From 0ebe6d846d365e6a2a57caec7527fe2b44b83446 Mon Sep 17 00:00:00 2001 From: Nicky Leach Date: Fri, 13 Nov 2026 12:54:43 -0800 Subject: [PATCH] perf(runner): keep a quiet Claude provider between turns of a run (#21293) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip Runner runs Claude Code through the ACPX sidecar. The Runner stops and starts the sidecar and Claude at each turn boundary. > - The reason was that a late tool call from an earlier turn could run in a later turn. #21278 removes that reason for Claude: the sidecar refuses a call that the active turn did not announce. > - A second reason remains. Claude Code works by itself between prompts. When a background task finishes, Claude starts a cycle of its own. If the process stayed alive with a live background task, that cycle could start between turns or mix with the next turn. > - So the Runner can keep the process only when it knows that Claude has no background work. > - This pull request adds that knowledge and uses it. After a Claude turn that completed with no background work, the Runner keeps the process for the next turn of the same run. > - The benefit is that a later turn of the same run starts with no provider restart. This is also the base for the next step, which lets a run continue when background work finishes. ## Linked Issues or Issue Description No public issue exists. The issue is described here. This pull request is stacked on #21278. Its base branch is `fix/bind-claude-tool-calls-to-turn`. Refs #19912 (design), #12419 (restart at turn start), #20145 (restart at park) and #20190 (restart at turn end). **What existing behavior does this improve?** The provider restart between turns of the same run, for Claude through ACPX. **Subsystem affected** Paperclip Runner: the ACPX sidecar (TypeScript) and the ACPX provider session in `runner-core` (Rust). Claude only. **Current behavior** - When a completed turn settles, the Runner restarts the sidecar and Claude (`restart_session_after_turn`, #20190). - If that restart did not run, the next turn restarts them at its start (`start_turn`). - The Runner does not know if Claude has background tasks. **Proposed behavior** - The sidecar asks `claude-agent-acp` for its async task reports. This is an optional capability of the pinned `claude-agent-acp` 0.73.0. The patch does not change. - A tracker reads those reports and the id of each background Bash command. It reports `{ live: 0 }` only when it knows that this process never had a background task and that Claude did not act between prompts. In all other cases the state is unknown. - The sidecar adds `backgroundTasks` to the terminal event of a completed Claude turn, and to `session.snapshot`. - The Runner keeps the process between two turns only when all of these are true: - the agent is Claude; - the turn completed (not failed, cancelled or interrupted); - the terminal event reported `backgroundTasks: { "live": 0 }`; - each existing condition of the turn-end restart is true; - before the next turn, a new `session.snapshot` reports the same identity and run, no active turn, no pending work, and `{ "live": 0 }`; - the settled-turn ledger and the tool replay ledgers are not full. - In each other case the Runner restarts as before. - A kept process keeps its tool call-id tombstones and its settled turn identities. **Reason and benefit** - A turn that follows a quiet turn in the same run starts without a restart. - The decision is safe by default: unknown state means a restart. ## What Changed TypeScript (`packages/paperclip-runner/src`): - `drivers/acpx/claude-background-tasks.ts` (new): `ClaudeBackgroundTaskTracker`. It reads raw ACP messages. It reports unknown when the capability is not negotiated, when a task finished, when a live task is not a shell command, when an update is malformed, when a limit is reached, when Claude acts with no client request in flight, or when Claude calls `CronCreate` or `ScheduleWakeup`. - `drivers/acpx/provider-failure.ts` and `acpx-runtime-adapter.ts`: Claude sessions also advertise the `asyncTasks` capability. The raw ACP observer gives each message to the tracker. ACPX 0.22 drops the `async_task_*` updates before the turn event stream, so only the raw observer sees them. - `drivers/acpx/runtime-host.ts`: `backgroundTaskState()`. - `cli/acpx-runtime-sidecar.ts`: the terminal event of a completed Claude turn carries `backgroundTasks` in the same payload as `goalAtTerminal`, with the same size limit. `session.snapshot` carries it when no turn is active. - `drivers/acpx/claude-tool-use-admission.ts`: `hasRoomForAnotherTurn()`. When the admitted-id ledger cannot hold one more full turn, the sidecar reports unknown, so the Runner restarts before the ledger is full. Rust (`packages/paperclip-runner/runner/crates/runner-core`): - `acpx_provider_session.rs`: the session records a quiet turn from the terminal event. `start_turn` continues in the same process only under the conditions above, and then uses `prepare_turn`, which keeps the tombstones. - `acpx_provider_generation.rs`: `can_continue_after_turn`, `continue_after_quiet_turn`, and the snapshot check `background_work_is_quiet`. - `acpx_park_preparation.rs`: the turn-end restart does not run for a quiet Claude turn. - `acpx_provider_backend.rs`: `session.reconciled` reports a replaced process only when the turn start replaced it. - `bin/fake-acpx-sidecar.rs`: new option `--background-tasks` for tests. - `runner/DURABLE_TRANSPORT.md`: the rule for a kept sidecar. Contract (`packages/paperclip-runner/protocol`): - The `backgroundTasks` report is `$defs.backgroundTasks` in `provider-schemas/acpx-sidecar.schema.json`: an object with only `live`, a non-negative integer. The schema validates it on `runtime.turn_terminal`. - `scripts/generate-acpx-sidecar-contract.mjs` generates the TypeScript type and reader and the Rust reader from it. The tracker, the sidecar and the Rust session use the generated code. - `fixtures/provider-boundary/acpx-background-tasks.json` has shared test documents. The TypeScript reader, the Rust reader and the schema are tested with the same accepted and refused shapes. - This changes the contract digest of the provider pack (`prp.acpx-sidecar` and `rust`). Older image packs are not reused. No provider `commandDigest` and no profile version changes. Not changed: park and run attachment. A process that ran a turn is still restarted at park, and only a process that ran no turn is bound to the next run. Other ACPX agents and Codex do not change. The `claude-agent-acp` patch does not change. ## State saved by the previous release - This pull request adds no persisted state. The three new fields of the session are in memory only. - A terminal event or a snapshot without `backgroundTasks` means unknown. An older sidecar therefore gets the restart, as before. - An older Runner with a new pack ignores the field and restarts at each turn, as before. - After a Runner restart, the in-memory state is gone. The next turn restarts the provider, as before. A test covers this. ## Verification From `packages/paperclip-runner`: - `npx vitest run src/drivers/acpx/claude-background-tasks.test.ts src/drivers/acpx/acpx-runtime-adapter.claude-background-tasks.test.ts src/drivers/acpx/acpx-runtime-adapter.claude-tool-use.test.ts src/drivers/acpx/claude-tool-use-admission.test.ts src/cli/acpx-runtime-sidecar.test.ts src/drivers/acpx/acpx-runtime-adapter.test.ts src/drivers/acpx/runtime-host.test.ts`: `7 passed (7)` files, `363 passed` tests. - `npx tsc --noEmit -p tsconfig.json` and `npx tsc --noEmit -p tsconfig.test.json`: no errors. - `pnpm run typecheck:typescript` (it includes the contract checks): no errors. `node --test test/acpx-sidecar-contract.test.mjs`: 17 passed. - `cargo fmt --manifest-path runner/Cargo.toml --all -- --check`: no changes. - `cargo test -p paperclip-runner-core --test acpx_quiet_turn_continuation --test acpx_park_preparation --test acpx_park_readiness --test acpx_provider_turns --test acpx_provider_session --test acpx_warm_attachment --test native_provider_backend`: 4, 33, 8, 31, 12, 6 and 47 passed. No test failed. - `cargo test -p paperclip-runner-core --lib`: 637 passed, 4 ignored. - Mutation check: when the Rust code accepts each live count as quiet, two tests in `acpx_park_preparation` fail. New tests: - **Real ACP runtime** (`acpx-runtime-adapter.claude-background-tasks.test.ts`), with the pinned `claude-agent-acp`, the pinned Claude Code client and a local fake Anthropic API. A foreground Bash turn reports `{ live: 0 }`. A background Bash in the same process reports `{ live: 1 }` at the terminal event, and unknown after Claude ran its own cycle for the finished task. Each turn has its own usage receipt. One process serves all turns. - **Tracker unit tests** (13): spawn, completion, failure, stop, pause, a task that is not a shell, a subagent, no negotiation, malformed updates, activity between prompts, scheduling tools, session load replay, limits. - **Sidecar tests**: the terminal event carries the state for Claude and not for Codex. A full ledger reports unknown. - **Rust** `tests/acpx_quiet_turn_continuation.rs` (4) and `tests/support/acpx_quiet_turn_restart.rs` (7): - a quiet Claude turn continues in the same process, and a replay of a settled call id is refused; - live, unknown and malformed reports restart; - background work that appears after the terminal event restarts at turn start; - failed, cancelled and interrupted turns restart; - Codex with a quiet report restarts; - an active goal restarts; - 4,096 kept turns, then the next turn restarts; - park after a kept process still prepares a new process, and the next run attaches to it; - a Runner restart after a kept process resumes in a new process. - The existing restart tests did not change. The fake sidecar sends no report by default, so they are the tests for the unknown case. Live run with a real Claude account, not in CI: the real ACP runtime (ACPX 0.22, the patched `claude-agent-acp`, the pinned Claude Code client), a real tool bridge, and the real Anthropic API with model `claude-sonnet-5-5`, on the code at the top of this stack. A turn that started one background shell reported `{ live: 1 }`. A turn that started two reported `{ live: 2 }`, then `{ live: 1 }` and `{ live: 0 }` as each shell finished. A turn in which Claude waited for its background shell in the foreground reported the unknown state. Not run: server integration tests (the fake sidecar there sends no report, so their process counts do not change), Linux, and a live run through the real sidecar process and runnerd. ## Risks - **All Claude sessions now negotiate the `asyncTasks` capability.** `claude-agent-acp` then sends `async_task_*` updates and adds a marker to a background Bash update. ACPX drops the updates. No other behavior of `claude-agent-acp` changes, from a read of its code. - **Park after a kept process pays the restart again**, as it did before #20190. With real Claude that restart was about 1.5 s. - **A small window remains** between the snapshot and the prompt of the next turn. Claude can start a cycle of its own in that window only without a background task, because a process that had a background task is not kept. - **Activity between prompts is found only when no client request is in flight.** A request that never gets a response would hide such activity. - **Background watchers cannot be told apart from other tasks**, so each task that is not a shell command makes the state unknown. - **Each kept turn adds one `session.snapshot` request.** - A multi-turn run with real Claude now uses one provider process. This path has tests with the fake sidecar and with the real ACP runtime. It has no test with the real sidecar host. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Fable 5.2 (`claude-fable-5-2`) in Claude Code planned the change, reviewed the diff, and ran the TypeScript and Rust verification again. - Claude Opus 5.5 (`claude-opus-5-5`), as a Claude Code subagent with tool use (shell, file edits, local test runs), investigated the signals and wrote the change and the tests. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.2 --- .../acpx-background-tasks.json | 20 ++ .../paperclip-runner/protocol/manifest.json | 6 + .../provider-schemas/acpx-sidecar.schema.json | 13 + .../runner/DURABLE_TRANSPORT.md | 14 +- .../runner-core/src/acpx_park_preparation.rs | 15 +- .../runner-core/src/acpx_provider_backend.rs | 21 +- .../src/acpx_provider_generation.rs | 50 +++- .../runner-core/src/acpx_provider_session.rs | 30 ++- .../runner-core/src/bin/fake-acpx-sidecar.rs | 78 +++++- .../src/generated_acpx_sidecar_contract.rs | 12 + .../tests/acpx_park_preparation.rs | 12 +- .../tests/acpx_quiet_turn_continuation.rs | 250 ++++++++++++++++++ .../tests/support/acpx_quiet_turn_restart.rs | 229 ++++++++++++++++ .../generate-acpx-sidecar-contract.mjs | 18 +- .../src/cli/acpx-runtime-sidecar.test.ts | 93 +++++++ .../src/cli/acpx-runtime-sidecar.ts | 25 +- ...me-adapter.claude-background-tasks.test.ts | 149 +++++++++++ .../src/drivers/acpx/acpx-runtime-adapter.ts | 13 +- .../acpx/claude-background-tasks.test.ts | 176 ++++++++++++ .../drivers/acpx/claude-background-tasks.ts | 148 +++++++++++ .../acpx/claude-tool-use-admission.test.ts | 18 ++ .../drivers/acpx/claude-tool-use-admission.ts | 4 + .../acpx/generated-sidecar-contract.ts | 12 + .../src/drivers/acpx/provider-failure.ts | 3 +- .../src/drivers/acpx/runtime-host.ts | 6 + .../test/acpx-sidecar-contract.test.mjs | 12 + 26 files changed, 1400 insertions(+), 27 deletions(-) create mode 100644 packages/paperclip-runner/protocol/fixtures/provider-boundary/acpx-background-tasks.json create mode 100644 packages/paperclip-runner/runner/crates/runner-core/tests/acpx_quiet_turn_continuation.rs create mode 100644 packages/paperclip-runner/runner/crates/runner-core/tests/support/acpx_quiet_turn_restart.rs create mode 100644 packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.claude-background-tasks.test.ts create mode 100644 packages/paperclip-runner/src/drivers/acpx/claude-background-tasks.test.ts create mode 100644 packages/paperclip-runner/src/drivers/acpx/claude-background-tasks.ts diff --git a/packages/paperclip-runner/protocol/fixtures/provider-boundary/acpx-background-tasks.json b/packages/paperclip-runner/protocol/fixtures/provider-boundary/acpx-background-tasks.json new file mode 100644 index 00000000000..88e92761972 --- /dev/null +++ b/packages/paperclip-runner/protocol/fixtures/provider-boundary/acpx-background-tasks.json @@ -0,0 +1,20 @@ +{ + "schema": "paperclip.acpx-background-tasks-vectors.v1", + "accepted": [ + { "value": { "live": 0 }, "live": 0 }, + { "value": { "live": 3 }, "live": 3 }, + { "value": { "live": 9007199254740991 }, "live": 9007199254740991 } + ], + "rejected": [ + { "case": "extra key", "value": { "live": 0, "extra": true } }, + { "case": "negative", "value": { "live": -1 } }, + { "case": "non-integer", "value": { "live": 0.5 } }, + { "case": "string", "value": { "live": "0" } }, + { "case": "null live", "value": { "live": null } }, + { "case": "null", "value": null }, + { "case": "missing live", "value": {} }, + { "case": "array", "value": [0] }, + { "case": "number", "value": 0 }, + { "case": "above the safe range", "value": { "live": 9007199254740992 } } + ] +} diff --git a/packages/paperclip-runner/protocol/manifest.json b/packages/paperclip-runner/protocol/manifest.json index af6103f1cde..b32d9fb90b3 100644 --- a/packages/paperclip-runner/protocol/manifest.json +++ b/packages/paperclip-runner/protocol/manifest.json @@ -231,6 +231,12 @@ "expectation": "accept", "compatibilityCase": "canonical" }, + { + "path": "fixtures/provider-boundary/acpx-background-tasks.json", + "sha256": "25a8ee4368eaded9fd8a6784900c9918bbb5c8f59fffb2c37466971e1d5be438", + "expectation": "accept", + "compatibilityCase": "canonical" + }, { "path": "fixtures/provider-boundary/local-integrity.json", "sha256": "ca3d3eaddd80320b273f48e68f7562f63b1f03152901154ace5ef26232c24f4f", diff --git a/packages/paperclip-runner/protocol/provider-schemas/acpx-sidecar.schema.json b/packages/paperclip-runner/protocol/provider-schemas/acpx-sidecar.schema.json index 64a33d45c4a..bef5e71cb9d 100644 --- a/packages/paperclip-runner/protocol/provider-schemas/acpx-sidecar.schema.json +++ b/packages/paperclip-runner/protocol/provider-schemas/acpx-sidecar.schema.json @@ -248,6 +248,10 @@ } } }, "then": { "properties": { "payload": { "type": "object", "properties": { "cost": { "$ref": "#/$defs/usageCost" } } } } } }, + { + "if": { "properties": { "eventType": { "const": "runtime.turn_terminal" } } }, + "then": { "properties": { "payload": { "type": "object", "properties": { "backgroundTasks": { "$ref": "#/$defs/backgroundTasks" } } } } } + }, { "if": { "properties": { "eventType": { "const": "runtime.rich_event" } } }, "then": { @@ -260,6 +264,15 @@ } ] }, + "backgroundTasks": { + "description": "Claude's live background tasks, carried on a completed runtime.turn_terminal payload and on a session.snapshot result taken with no active turn. The sidecar sends it only when it knows the count. An absent value means unknown, and runnerd then restarts the provider as before. runnerd keeps the provider between turns only for exactly {\"live\": 0}.", + "type": "object", + "properties": { + "live": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } + }, + "required": ["live"], + "additionalProperties": false + }, "usageCost": { "description": "Provider cost is session-cumulative unless basis explicitly identifies a complete turn total. A turn total is never a session counter.", "type": ["object", "null"], diff --git a/packages/paperclip-runner/runner/DURABLE_TRANSPORT.md b/packages/paperclip-runner/runner/DURABLE_TRANSPORT.md index 1198af6dd92..1c1242934d0 100644 --- a/packages/paperclip-runner/runner/DURABLE_TRANSPORT.md +++ b/packages/paperclip-runner/runner/DURABLE_TRANSPORT.md @@ -202,7 +202,19 @@ that sidecar 100 ms to report its goal and session state. If the sidecar is slow or declines, Runner stays attached. Runner keeps at most one unanswered read and recognizes its late reply. Events received during that read still belong to A and are delivered before B attaches. The existing policy still replaces the -sidecar at the next turn or run attachment; the saved provider identity continues. +sidecar at park and run attachment; the saved provider identity continues. + +Between turns of the same run, Runner keeps a Claude sidecar only when the turn +completed normally, its terminal reported `backgroundTasks: {"live": 0}`, and +every condition of the turn-end restart holds. Before the next turn it reads +`session.snapshot` again and requires the same report. A missing, live or +malformed report, a failed, cancelled or interrupted turn, any other agent, a +full settled-turn ledger or a full tool replay ledger replaces the sidecar as +before. A kept sidecar keeps its tool call-ID tombstones and settled turn +identities. The report's shape is `$defs.backgroundTasks` in +`protocol/provider-schemas/acpx-sidecar.schema.json`; both readers are +generated from it and tested against +`protocol/fixtures/provider-boundary/acpx-background-tasks.json`. The check also inspects the live provider after that drain, so a late active-goal notification cannot be hidden by the diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_park_preparation.rs b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_park_preparation.rs index a68e5fce2fa..c32d37d89de 100644 --- a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_park_preparation.rs +++ b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_park_preparation.rs @@ -26,7 +26,12 @@ impl AcpxCommandExecutor { pub(super) fn restart_session_after_turn(&mut self) -> Result<(), DurableRunnerError> { self.ensure_persistence_healthy()?; - if !self.generation_restartable(AcpxProviderSession::can_restart_after_turn) { + if self + .session + .as_ref() + .is_some_and(AcpxProviderSession::continues_in_process) + || !self.generation_restartable(AcpxProviderSession::can_restart_after_turn) + { return Ok(()); } let session = self.session.as_mut().expect("checked ACPX session"); @@ -35,6 +40,14 @@ impl AcpxCommandExecutor { { return Ok(()); } + if self + .session + .as_mut() + .expect("checked ACPX session") + .continue_after_quiet_turn() + { + return Ok(()); + } let restarted = self .session .as_mut() diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_backend.rs b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_backend.rs index 5a27596232e..7aed75e7ff7 100644 --- a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_backend.rs +++ b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_backend.rs @@ -2205,12 +2205,13 @@ impl AcpxCommandExecutor { error }); } - let (provider_process_will_be_replaced, previous_process_id) = self + let previous_process_id = self .session .as_ref() - .map(|session| match session.restarted_after_turn_from() { - Some(process_id) => (true, process_id), - None => (session.generation_has_run_turn(), session.process_id()), + .map(|session| { + session + .restarted_after_turn_from() + .unwrap_or_else(|| session.process_id()) }) .expect("ACPX session exists after availability check"); { @@ -2338,12 +2339,12 @@ impl AcpxCommandExecutor { json!({"sessionGoals": state.goal_projection["sessionGoals"], "turnControls":state.turn_controls}) }); self.save_state()?; - let mut events = Vec::with_capacity(if provider_process_will_be_replaced { - 2 - } else { - 1 - }); - if provider_process_will_be_replaced { + let provider_process_was_replaced = self + .session + .as_ref() + .is_some_and(AcpxProviderSession::turn_start_replaced_provider); + let mut events = Vec::with_capacity(if provider_process_was_replaced { 2 } else { 1 }); + if provider_process_was_replaced { let session = self .session .as_ref() diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_generation.rs b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_generation.rs index 6d7cd78c6ba..9114f476f49 100644 --- a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_generation.rs +++ b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_generation.rs @@ -5,11 +5,12 @@ use sha2::{Digest, Sha256}; use super::{ reserved_terminal_tool_bridge, sidecar_run_tool_operations, AcpxProviderSession, - AcpxProviderSessionConfig, + AcpxProviderSessionConfig, AcpxProviderSessionIdentity, }; use crate::acpx_provider_state::AcpxProviderState; use crate::generated_acpx_sidecar_contract::{ - GeneratedAcpxSidecarCommand, GeneratedAcpxSidecarEventType, + read_generated_acpx_background_tasks, GeneratedAcpxSidecarCommand, + GeneratedAcpxSidecarEventType, }; use crate::local_runner::LocalRunnerError; use crate::provider_bridge::ProviderToolBridge; @@ -49,7 +50,52 @@ fn generation_digest(config: &AcpxProviderSessionConfig) -> String { format!("sha256:{:x}", Sha256::digest(shape.to_string().as_bytes())) } +pub(super) fn reports_no_live_background_tasks(payload: &Value) -> bool { + payload + .get("backgroundTasks") + .and_then(read_generated_acpx_background_tasks) + == Some(0) +} + impl AcpxProviderSession { + pub fn can_continue_after_turn(&self) -> bool { + self.config.agent == "claude" && self.quiet_turn_observed && self.can_restart_after_turn() + } + + pub fn continue_after_quiet_turn(&mut self) -> bool { + if !self.continues_in_process { + self.continues_in_process = self.can_continue_after_turn(); + } + self.continues_in_process + } + + pub fn continues_in_process(&self) -> bool { + self.continues_in_process + } + + pub fn turn_start_replaced_provider(&self) -> bool { + self.turn_start_replaced_provider + } + + pub(super) fn background_work_is_quiet(&mut self) -> bool { + let Ok(snapshot) = self + .transport + .request(GeneratedAcpxSidecarCommand::SessionSnapshot, json!({})) + else { + return false; + }; + serde_json::from_value::(snapshot["identity"].clone()) + .is_ok_and(|identity| identity == self.identity) + && snapshot["runId"].as_str() == Some(self.config.run_id.as_str()) + && snapshot["turnId"].is_null() + && snapshot["pendingToolCount"].as_u64() == Some(0) + && snapshot["pendingInputCount"].as_u64() == Some(0) + && snapshot["pendingRuntimeRequests"] + .as_array() + .is_some_and(Vec::is_empty) + && reports_no_live_background_tasks(&snapshot) + } + pub fn generation_has_run_turn(&self) -> bool { self.generation_has_run_turn } diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_session.rs b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_session.rs index 01d4a5b519b..3c79aaa114e 100644 --- a/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_session.rs +++ b/packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_session.rs @@ -361,6 +361,9 @@ pub struct AcpxProviderSession { runtime_retired: bool, cancelled_turn_id: Option, completed_turn_observed: bool, + quiet_turn_observed: bool, + continues_in_process: bool, + turn_start_replaced_provider: bool, generation_has_run_turn: bool, restarted_after_turn_from: Option, prepared_generation: Option, @@ -423,6 +426,9 @@ impl AcpxProviderSession { runtime_retired: false, cancelled_turn_id: None, completed_turn_observed: false, + quiet_turn_observed: false, + continues_in_process: false, + turn_start_replaced_provider: false, generation_has_run_turn: false, restarted_after_turn_from: None, prepared_generation: None, @@ -668,13 +674,24 @@ impl AcpxProviderSession { // provider turn originated a late HTTP callback. Reap the old sidecar // and provider before releasing its call-ID tombstones, then resume // the same verified persistent session in a fresh process generation. - let restart_now = self.generation_has_run_turn; + // A quiet Claude generation that the turn-end path kept continues in + // place instead: its tool calls are bound to their announcing turn and + // its tombstones are retained below. + let continue_in_process = self.continues_in_process + && !rotate_turn_identity_ledger + && !self.tool_bridge.replay_history_blocks_admission() + && !self.reserved_tool_bridge.replay_history_blocks_admission() + && self.background_work_is_quiet(); + self.continues_in_process = false; + self.quiet_turn_observed = false; + let restart_now = self.generation_has_run_turn && !continue_in_process; if restart_now { if let Err(error) = self.restart_idle_provider(None) { return Err(self.fail_closed(error)); } } let provider_restarted = restart_now || self.restarted_after_turn_from.is_some(); + self.turn_start_replaced_provider = provider_restarted; if rotate_turn_identity_ledger { if let Err(error) = self .state @@ -904,6 +921,8 @@ impl AcpxProviderSession { payload.insert("origin".to_owned(), origin); } } + let terminal_quiet = event.event_type == GeneratedAcpxSidecarEventType::RuntimeTurnTerminal + && generation::reports_no_live_background_tasks(&event.payload); let mut next_state = self.state.clone(); let events = match next_state.accept_event(&event) { Ok(events) => events, @@ -1057,6 +1076,10 @@ impl AcpxProviderSession { self.completed_turn_observed = *status == crate::acpx_event_payload::AcpxTurnStatus::Completed && self.state.active_turn_id() == Some(turn_id.as_str()); + self.quiet_turn_observed = self.completed_turn_observed + && terminal_quiet + && self.config.agent == "claude" + && self.cancelled_turn_id.as_deref() != Some(turn_id.as_str()); } } self.state = next_state; @@ -1381,6 +1404,8 @@ impl AcpxProviderSession { self.turn_controls = turn_controls; self.transport_terminated = false; self.generation_has_run_turn = false; + self.quiet_turn_observed = false; + self.continues_in_process = false; Ok(()) } @@ -2286,6 +2311,9 @@ mod mode_tests { runtime_retired: false, cancelled_turn_id: None, completed_turn_observed: false, + quiet_turn_observed: false, + continues_in_process: false, + turn_start_replaced_provider: false, generation_has_run_turn: false, restarted_after_turn_from: None, prepared_generation: None, diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/bin/fake-acpx-sidecar.rs b/packages/paperclip-runner/runner/crates/runner-core/src/bin/fake-acpx-sidecar.rs index ba2594f75bf..188b32c7e22 100644 --- a/packages/paperclip-runner/runner/crates/runner-core/src/bin/fake-acpx-sidecar.rs +++ b/packages/paperclip-runner/runner/crates/runner-core/src/bin/fake-acpx-sidecar.rs @@ -9,6 +9,54 @@ use serde_json::{json, Value}; const PROJECTED_INPUT_PROVIDER_ID: &str = "input / réquest"; +static BACKGROUND_TASKS: std::sync::OnceLock> = std::sync::OnceLock::new(); + +fn background_tasks_mode(snapshot: bool) -> Option { + let path = BACKGROUND_TASKS.get()?.as_ref()?; + let modes = std::fs::read_to_string(path).unwrap_or_default(); + let mut tokens = modes.split_whitespace(); + let terminal = tokens.next().unwrap_or("").to_owned(); + if !snapshot { + return Some(terminal); + } + Some( + tokens + .find_map(|token| token.strip_prefix("snapshot-")) + .map(str::to_owned) + .unwrap_or(terminal), + ) +} + +fn background_tasks_value(mode: &str) -> Option { + match mode { + "quiet" => Some(json!({"live":0})), + "live" => Some(json!({"live":1})), + "malformed" => Some(json!({"live":"0"})), + _ => None, + } +} + +fn apply_background_snapshot(response: &mut Value, id: u64, idle: bool) { + let Some(mode) = background_tasks_mode(true) else { + return; + }; + if mode == "reject" { + *response = json!({"protocolVersion":GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION,"id":id,"ok":false, + "error":{"code":"temporarily_unavailable","message":"Snapshot is unavailable.","retryable":true}}); + return; + } + let result = &mut response["result"]; + if idle { + result["turnId"] = Value::Null; + result["pendingToolCount"] = json!(0); + result["pendingInputCount"] = json!(0); + result["pendingRuntimeRequests"] = json!([]); + } + if let Some(tasks) = background_tasks_value(&mode) { + result["backgroundTasks"] = tasks; + } +} + fn main() { if let Err(error) = run() { eprintln!("fake-acpx-sidecar: {error}"); @@ -34,6 +82,11 @@ fn run() -> Result<(), Box> { .map(|pair| pair[1].parse::()) .transpose()?; let mut opened_identity: Option = None; + let _ = BACKGROUND_TASKS.set( + args.windows(2) + .find(|pair| pair[0] == "--background-tasks") + .map(|pair| pair[1].clone()), + ); let lifetime_fence_candidates = args .windows(2) .find(|pair| pair[0] == "--lifetime-fence-ports") @@ -189,6 +242,9 @@ fn run() -> Result<(), Box> { "pendingToolCount":if fault == "tool" || source_pending_completion.is_some() {1} else {0}, "pendingInputCount":0, "pendingRuntimeRequests":[]}); } + if command == "session.snapshot" { + apply_background_snapshot(&mut response, id, false); + } if command == "session.snapshot" && fault == "foreign-snapshot" { response["result"]["identity"]["agentSessionId"] = json!("foreign-session"); } @@ -379,13 +435,21 @@ fn run() -> Result<(), Box> { json!({"type":"text_delta", "text":"Completed fake ACPX work."}), )?; next_sequence += 1; + let status = background_tasks_mode(true) + .and_then(|_| std::fs::read_to_string(BACKGROUND_TASKS.get()?.as_ref()?).ok()) + .and_then(|modes| { + modes + .split_whitespace() + .find_map(|token| token.strip_prefix("status-").map(str::to_owned)) + }) + .unwrap_or_else(|| "completed".to_owned()); write_turn_event( &mut stdout, next_sequence, "runtime.turn_terminal", &source_run, turn, - json!({"status":"completed"}), + json!({"status":status}), )?; next_sequence += 1; } @@ -746,6 +810,9 @@ fn run() -> Result<(), Box> { continue; } } + if command == "session.snapshot" { + apply_background_snapshot(&mut response, id, true); + } if command == "session.suspend" { if let Some(delay_ms) = suspend_delay_ms { std::thread::sleep(Duration::from_millis(delay_ms)); @@ -1365,8 +1432,15 @@ fn write_turn_event( event_type: &str, run_id: &str, turn_id: &str, - payload: Value, + mut payload: Value, ) -> io::Result<()> { + if event_type == "runtime.turn_terminal" { + if let Some(tasks) = + background_tasks_mode(false).and_then(|mode| background_tasks_value(&mode)) + { + payload["backgroundTasks"] = tasks; + } + } write_json( output, &json!({ diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs b/packages/paperclip-runner/runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs index b0a137dac7d..c4d7314d539 100644 --- a/packages/paperclip-runner/runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs +++ b/packages/paperclip-runner/runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs @@ -3,6 +3,18 @@ pub const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION: u64 = 2; pub const GENERATED_ACPX_TURN_DISPATCH_JOURNAL_FILE: &str = "paperclip-turn-dispatch.jsonl"; pub const GENERATED_ACPX_TURN_DISPATCH_SCHEMA: &str = "paperclip.acpx-turn-dispatch.v1"; +pub const GENERATED_ACPX_BACKGROUND_TASKS_MAX_LIVE: u64 = 9007199254740991; + +pub fn read_generated_acpx_background_tasks(value: &serde_json::Value) -> Option { + let tasks = value.as_object()?; + if tasks.len() != 1 { + return None; + } + tasks + .get("live")? + .as_u64() + .filter(|live| *live <= GENERATED_ACPX_BACKGROUND_TASKS_MAX_LIVE) +} pub const GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE: &[(&str, &[&str])] = &[ ("edit", &["edit", "write", "patch"]), diff --git a/packages/paperclip-runner/runner/crates/runner-core/tests/acpx_park_preparation.rs b/packages/paperclip-runner/runner/crates/runner-core/tests/acpx_park_preparation.rs index 86614158302..ed0b6031535 100644 --- a/packages/paperclip-runner/runner/crates/runner-core/tests/acpx_park_preparation.rs +++ b/packages/paperclip-runner/runner/crates/runner-core/tests/acpx_park_preparation.rs @@ -20,6 +20,9 @@ mod turn_end_restart; #[path = "support/acpx_cut_turn_start.rs"] mod cut_turn_start; +#[path = "support/acpx_quiet_turn_restart.rs"] +mod quiet_turn_restart; + struct Fixture(PathBuf); impl Drop for Fixture { fn drop(&mut self) { @@ -32,6 +35,10 @@ impl Fixture { fs::write(self.0.join("fault"), fault).unwrap(); } + fn background(&self, mode: &str) { + fs::write(self.0.join("background-tasks"), mode).unwrap(); + } + fn journal(&self) -> Vec { fs::read_to_string(self.0.join("sidecar.jsonl")) .unwrap() @@ -82,10 +89,11 @@ impl Harness { fs::write( &sidecar, format!( - "#!/bin/sh\nexec '{}' --mode source-reconcile --emit-process --journal '{}' --source-fault '{}' \"$@\"\n", + "#!/bin/sh\nexec '{}' --mode source-reconcile --emit-process --journal '{}' --source-fault '{}' --background-tasks '{}' \"$@\"\n", native.display(), fixture.0.join("sidecar.jsonl").display(), - fixture.0.join("fault").display() + fixture.0.join("fault").display(), + fixture.0.join("background-tasks").display() ), ) .unwrap(); diff --git a/packages/paperclip-runner/runner/crates/runner-core/tests/acpx_quiet_turn_continuation.rs b/packages/paperclip-runner/runner/crates/runner-core/tests/acpx_quiet_turn_continuation.rs new file mode 100644 index 00000000000..0d69cc92bea --- /dev/null +++ b/packages/paperclip-runner/runner/crates/runner-core/tests/acpx_quiet_turn_continuation.rs @@ -0,0 +1,250 @@ +#![cfg(unix)] + +use std::path::{Path, PathBuf}; +use std::time::Duration; + +use paperclip_runner_core::acpx_provider_session::{ + AcpxPermissionMode, AcpxProviderSession, AcpxProviderSessionConfig, +}; +use paperclip_runner_core::acpx_provider_state::AcpxProviderStateEvent; +use paperclip_runner_core::acpx_sidecar_transport::AcpxSidecarTransportConfig; +use paperclip_runner_core::generated_acpx_sidecar_contract::read_generated_acpx_background_tasks; +use paperclip_runner_core::provider_bridge::{ + authorized_tool_catalog_digest, AuthorizedTool, AuthorizedToolSet, ToolResult, +}; +use serde_json::json; + +struct Scratch(PathBuf); + +impl Drop for Scratch { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +impl Scratch { + fn new() -> Self { + let path = std::env::temp_dir().join(format!("acpx-quiet-turn-{}", uuid::Uuid::new_v4())); + std::fs::create_dir_all(&path).unwrap(); + Self(path) + } + + fn background(&self, mode: &str) { + std::fs::write(self.0.join("background-tasks"), mode).unwrap(); + } +} + +fn config(scratch: &Path, mode: &str, agent: &str) -> AcpxProviderSessionConfig { + let operations = vec![AuthorizedTool { + operation_id: "issues.read".to_owned(), + version: 1, + description: "Read an issue.".to_owned(), + input_schema: json!({"type":"object"}), + response_schema: json!({"type":"object"}), + }]; + AcpxProviderSessionConfig { + candidate_admission: None, + transport: AcpxSidecarTransportConfig { + command: PathBuf::from(env!("CARGO_BIN_EXE_fake-acpx-sidecar")), + args: vec![ + "--mode".to_owned(), + mode.to_owned(), + "--background-tasks".to_owned(), + scratch.join("background-tasks").display().to_string(), + ], + verified_launch: None, + request_timeout: Duration::from_secs(1), + shutdown_grace: Duration::from_millis(100), + }, + agent: agent.to_owned(), + model: "explicit-test-model".to_owned(), + run_id: "run-1".to_owned(), + catalog_revision: 1, + runtime_directory: std::env::temp_dir(), + normalized_session_id: "session-1".to_owned(), + working_directory: std::env::temp_dir(), + permission_mode: AcpxPermissionMode::ApproveReads, + mode: None, + claude_effort: None, + grok_effort: None, + grok_disable_web_search: None, + pi_thinking_level: None, + permission_mode_pinned: true, + provider_policy: None, + system_instructions: "Complete the supplied task.".to_owned(), + runtime_context: serde_json::Value::Null, + tool_set: AuthorizedToolSet { + schema: "paperclip.runner.authorized-tools.v1".to_owned(), + schema_version: 1, + catalog_digest: authorized_tool_catalog_digest(&operations).unwrap(), + operations, + }, + expected_identity: None, + } +} + +fn reused_result() -> ToolResult { + ToolResult { + call_id: "call-reused".to_owned(), + operation_id: "issues.read".to_owned(), + result: json!({"id":"issue-1"}), + is_error: false, + } +} + +fn settle_reused_call(session: &mut AcpxProviderSession, turn_id: &str) { + session + .start_turn(turn_id, "Please continue", &std::env::temp_dir()) + .unwrap(); + let tool = session.poll_event(Duration::from_secs(1)).unwrap().unwrap(); + assert!(matches!( + &tool[0], + AcpxProviderStateEvent::ToolCall { call_id, .. } if call_id == "call-reused" + )); + let terminal = session.poll_event(Duration::from_secs(1)).unwrap().unwrap(); + assert!(matches!( + terminal.last().unwrap(), + AcpxProviderStateEvent::TurnTerminal { turn_id: settled, .. } if settled == turn_id + )); + session.deliver_tool_result(&reused_result()).unwrap(); +} + +#[test] +fn a_quiet_claude_turn_continues_in_process_and_refuses_a_replayed_settled_call() { + let scratch = Scratch::new(); + scratch.background("quiet"); + let mut session = AcpxProviderSession::start(&config( + &scratch.0, + "turns-reused-tool-id-terminal", + "claude", + )) + .unwrap(); + settle_reused_call(&mut session, "turn-1"); + let first_pid = session.process_id(); + assert!(session.can_continue_after_turn()); + assert!(session.continue_after_quiet_turn()); + assert!(session.continues_in_process()); + + session + .start_turn("turn-2", "Please continue", &std::env::temp_dir()) + .unwrap(); + assert_eq!(session.process_id(), first_pid); + assert!(!session.turn_start_replaced_provider()); + assert!(!session.continues_in_process()); + let replay = session.poll_event(Duration::from_secs(1)).unwrap_err(); + assert!( + replay + .to_string() + .contains("provider reused a completed tool call id"), + "{replay}" + ); + assert!(session.shutdown("already closed").is_ok()); +} + +#[test] +fn live_unknown_or_malformed_background_state_restarts_like_today() { + for (mode, agent) in [ + ("live", "claude"), + ("", "claude"), + ("malformed", "claude"), + ("quiet snapshot-live", "claude"), + ("quiet snapshot-unknown", "claude"), + ("quiet snapshot-reject", "claude"), + ("quiet", "codex"), + ] { + let scratch = Scratch::new(); + scratch.background(mode); + let mut session = + AcpxProviderSession::start(&config(&scratch.0, "turns-reused-tool-id-terminal", agent)) + .unwrap(); + settle_reused_call(&mut session, "turn-1"); + let first_pid = session.process_id(); + let snapshot_only = mode.contains("snapshot-"); + assert_eq!( + session.continue_after_quiet_turn(), + snapshot_only, + "{mode} {agent}" + ); + settle_reused_call(&mut session, "turn-2"); + assert_ne!(session.process_id(), first_pid, "{mode} {agent}"); + assert!(session.turn_start_replaced_provider(), "{mode} {agent}"); + session.shutdown("test complete").unwrap(); + } +} + +#[test] +fn an_interrupted_claude_turn_restarts_even_when_its_provider_reports_quiet() { + let scratch = Scratch::new(); + scratch.background("quiet"); + let mut session = AcpxProviderSession::start(&config(&scratch.0, "turns", "claude")).unwrap(); + session + .start_turn("turn-1", "Please help", &std::env::temp_dir()) + .unwrap(); + session.poll_event(Duration::from_secs(1)).unwrap().unwrap(); + session + .interrupt_turn("turn-1", "Paperclip interruption") + .unwrap(); + session.poll_event(Duration::from_secs(1)).unwrap().unwrap(); + let interrupted_pid = session.process_id(); + assert!(!session.can_continue_after_turn()); + assert!(!session.continue_after_quiet_turn()); + session + .start_turn("turn-2", "Start again", &std::env::temp_dir()) + .unwrap(); + assert_ne!(session.process_id(), interrupted_pid); + session.shutdown("test complete").unwrap(); +} + +#[test] +fn a_full_settled_turn_ledger_still_rotates_through_a_restart() { + let scratch = Scratch::new(); + scratch.background("quiet"); + let mut session = + AcpxProviderSession::start(&config(&scratch.0, "turns-tool-result-terminal", "claude")) + .unwrap(); + let first_pid = session.process_id(); + for index in 0..4_096 { + let turn_id = format!("turn-{index}"); + session + .start_turn(&turn_id, "Please continue", &std::env::temp_dir()) + .unwrap(); + loop { + let events = session.poll_event(Duration::from_secs(1)).unwrap().unwrap(); + if events.iter().any(|event| { + matches!(event, AcpxProviderStateEvent::TurnTerminal { turn_id: settled, .. } if settled == &turn_id) + }) { + break; + } + } + assert!(session.continue_after_quiet_turn(), "{turn_id}"); + } + assert_eq!(session.process_id(), first_pid); + session + .start_turn("turn-rotated", "Please continue", &std::env::temp_dir()) + .unwrap(); + assert_ne!(session.process_id(), first_pid); + assert!(session.turn_start_replaced_provider()); + session.shutdown("test complete").unwrap(); +} + +#[test] +fn the_generated_reader_matches_the_shared_background_task_vectors() { + let path = PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .join("../../../protocol/fixtures/provider-boundary/acpx-background-tasks.json"); + let vectors: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(path).unwrap()).unwrap(); + for vector in vectors["accepted"].as_array().unwrap() { + assert_eq!( + read_generated_acpx_background_tasks(&vector["value"]), + vector["live"].as_u64(), + "{vector}" + ); + } + for vector in vectors["rejected"].as_array().unwrap() { + assert_eq!( + read_generated_acpx_background_tasks(&vector["value"]), + None, + "{vector}" + ); + } +} diff --git a/packages/paperclip-runner/runner/crates/runner-core/tests/support/acpx_quiet_turn_restart.rs b/packages/paperclip-runner/runner/crates/runner-core/tests/support/acpx_quiet_turn_restart.rs new file mode 100644 index 00000000000..2f61aa3aa83 --- /dev/null +++ b/packages/paperclip-runner/runner/crates/runner-core/tests/support/acpx_quiet_turn_restart.rs @@ -0,0 +1,229 @@ +use super::*; + +fn live_providers(harness: &Harness) -> Vec { + harness + .fixture + .process_starts() + .into_iter() + .map(|line| line["processStart"].clone()) + .filter(alive) + .collect() +} + +fn run_turn(harness: &mut Harness, turn: &str) -> (Vec, Vec) { + let before = harness.fixture.journal().len(); + let execution = harness.execute( + "turn.start", + json!({"turnId": turn, "text": "Complete the work."}), + ); + let mut events = execution + .events + .iter() + .map(|(kind, _, payload)| json!({"type":kind,"payload":payload})) + .collect::>(); + let deadline = Instant::now() + Duration::from_secs(5); + while !events.iter().any(|event: &Value| { + event["type"] + .as_str() + .is_some_and(|kind| kind.starts_with("turn.") && kind != "turn.started") + }) { + assert!(Instant::now() < deadline, "no terminal provider turn"); + events.extend(harness.drain()); + } + events.extend(harness.drain()); + (events, commands_after(&harness.fixture.journal(), before)) +} + +fn replaced(events: &[Value]) -> bool { + events + .iter() + .any(|event| event["type"] == "session.reconciled") +} + +#[test] +fn a_quiet_completed_claude_turn_keeps_its_provider_for_the_next_turns() { + let mut harness = Harness::new(); + harness.fixture.background("quiet"); + let pid = harness.opened["processId"].clone(); + harness.complete_turn("first"); + let before = harness.fixture.journal().len(); + harness.executor.prepare_next_turn().unwrap(); + harness.executor.prepare_next_turn().unwrap(); + assert_eq!( + commands_after(&harness.fixture.journal(), before), + Vec::::new(), + "the turn-end path neither suspends nor respawns the provider" + ); + assert_eq!(harness.fixture.process_starts().len(), 1); + assert_eq!(live_providers(&harness), [pid.clone()]); + + for turn in ["second", "third"] { + let (events, commands) = run_turn(&mut harness, turn); + assert_eq!( + commands, + ["session.snapshot", "turn.start", "session.goal.get"], + "{turn}" + ); + assert!(!replaced(&events), "{turn}"); + assert!(events.iter().any(|event| event["type"] == "turn.completed")); + harness.executor.prepare_next_turn().unwrap(); + assert_eq!(harness.fixture.process_starts().len(), 1, "{turn}"); + assert_eq!(live_providers(&harness), [pid.clone()], "{turn}"); + } + harness.executor.shutdown().unwrap(); + assert_eq!(live_providers(&harness), Vec::::new()); +} + +#[test] +fn live_or_unknown_background_work_restarts_at_the_turn_end_like_today() { + for mode in ["live", "", "malformed"] { + let mut harness = Harness::new(); + harness.fixture.background(mode); + let pid = harness.opened["processId"].clone(); + harness.complete_turn("first"); + harness.executor.prepare_next_turn().unwrap(); + assert_eq!(harness.fixture.process_starts().len(), 2, "{mode}"); + assert!(!alive(&pid), "{mode}"); + let (events, commands) = run_turn(&mut harness, "second"); + assert_eq!(commands, ["turn.start", "session.goal.get"], "{mode}"); + assert_eq!( + events + .iter() + .find(|event| event["type"] == "session.reconciled") + .expect("the turn reports the replaced provider")["payload"]["previousProcessId"], + pid, + "{mode}" + ); + harness.executor.shutdown().unwrap(); + } +} + +#[test] +fn background_work_that_starts_after_a_quiet_terminal_restarts_at_the_next_turn() { + for snapshot in ["snapshot-live", "snapshot-unknown", "snapshot-reject"] { + let mut harness = Harness::new(); + harness.fixture.background("quiet"); + let pid = harness.opened["processId"].clone(); + harness.complete_turn("first"); + harness.executor.prepare_next_turn().unwrap(); + assert_eq!(harness.fixture.process_starts().len(), 1, "{snapshot}"); + harness.fixture.background(&format!("quiet {snapshot}")); + let (events, commands) = run_turn(&mut harness, "second"); + assert_eq!( + commands[..3], + ["session.snapshot", "session.suspend", "initialize"], + "{snapshot}" + ); + assert!(replaced(&events), "{snapshot}"); + assert!(!alive(&pid), "{snapshot}"); + assert_eq!(harness.fixture.process_starts().len(), 2, "{snapshot}"); + harness.executor.shutdown().unwrap(); + } +} + +#[test] +fn failed_cancelled_and_interrupted_turns_restart_like_today_even_when_quiet() { + for status in ["failed", "cancelled", "interrupted"] { + let outcome = |background: &str| { + let mut harness = Harness::new(); + harness.fixture.background(background); + let (events, _) = run_turn(&mut harness, "first"); + harness.executor.prepare_next_turn().unwrap(); + let after_turn_end = harness.fixture.process_starts().len(); + harness.fixture.background("quiet"); + let (next, commands) = run_turn(&mut harness, "second"); + let starts = harness.fixture.process_starts().len(); + harness.executor.shutdown().unwrap(); + ( + events + .iter() + .map(|event| event["type"].clone()) + .collect::>(), + after_turn_end, + commands, + replaced(&next), + starts, + ) + }; + let quiet = outcome(&format!("quiet status-{status}")); + let unknown = outcome(&format!("unknown status-{status}")); + assert_eq!(quiet, unknown, "{status}"); + assert_eq!(quiet.1, 1, "{status}"); + assert!(quiet.3, "{status}"); + assert_eq!(quiet.4, 2, "{status}"); + } +} + +#[test] +fn an_active_goal_or_an_early_turn_keeps_today_s_restart_when_quiet() { + let mut harness = Harness::new(); + harness.fixture.background("quiet"); + harness.fixture.fault("goal"); + harness.complete_turn("first"); + harness.executor.prepare_next_turn().unwrap(); + harness.fixture.fault(""); + let (events, _) = run_turn(&mut harness, "second"); + assert!(replaced(&events)); + harness.executor.shutdown().unwrap(); + + let mut harness = Harness::new(); + harness.fixture.background("quiet"); + harness.complete_turn("first"); + let (events, commands) = run_turn(&mut harness, "second"); + assert_eq!(commands[..2], ["session.suspend", "initialize"]); + assert!(replaced(&events)); + harness.executor.shutdown().unwrap(); +} + +#[test] +fn park_after_a_kept_quiet_provider_still_prepares_a_fresh_generation() { + let mut harness = Harness::new(); + harness.fixture.background("quiet"); + let pid = harness.opened["processId"].clone(); + harness.complete_turn("first"); + harness.executor.prepare_next_turn().unwrap(); + assert_eq!(harness.fixture.process_starts().len(), 1); + assert!(harness.executor.host_park_ready().unwrap()); + let started = Instant::now(); + assert!(harness.executor.prepare_for_park(park_deadline()).unwrap()); + eprintln!( + "park preparation after a kept quiet provider={:?}", + started.elapsed() + ); + assert!(!alive(&pid)); + assert_eq!(harness.fixture.process_starts().len(), 2); + let fresh = live_providers(&harness); + assert_eq!(fresh.len(), 1); + assert!(harness.executor.host_park_ready().unwrap()); + let (attached, _) = harness.attach("run-2", |_| {}); + assert_eq!(attached.result["processId"], fresh[0]); + harness.executor.shutdown().unwrap(); +} + +#[test] +fn a_runner_restart_after_a_kept_quiet_provider_resumes_in_a_fresh_process() { + let mut harness = Harness::new(); + harness.fixture.background("quiet"); + let pid = harness.opened["processId"].clone(); + harness.complete_turn("first"); + harness.executor.prepare_next_turn().unwrap(); + assert_eq!(harness.fixture.process_starts().len(), 1); + harness.executor.shutdown().unwrap(); + assert!(!alive(&pid)); + harness.executor = + NativeProviderCommandExecutor::with_runner_config(&harness.fixture.0, &harness.config); + harness.sequence = 90; + let (events, _) = run_turn(&mut harness, "second"); + assert!(events.iter().any(|event| event["type"] == "turn.completed")); + let journal = harness.fixture.journal(); + let spawned = last_process_start(&journal); + assert_eq!(journal[spawned]["livePredecessors"], json!([])); + assert_eq!(harness.fixture.process_starts().len(), 2); + harness.executor.prepare_next_turn().unwrap(); + assert_eq!( + harness.fixture.process_starts().len(), + 2, + "the resumed quiet generation is kept for the next turn" + ); + harness.executor.shutdown().unwrap(); +} diff --git a/packages/paperclip-runner/scripts/generate-acpx-sidecar-contract.mjs b/packages/paperclip-runner/scripts/generate-acpx-sidecar-contract.mjs index dfd1441e996..f530144a068 100644 --- a/packages/paperclip-runner/scripts/generate-acpx-sidecar-contract.mjs +++ b/packages/paperclip-runner/scripts/generate-acpx-sidecar-contract.mjs @@ -48,6 +48,20 @@ if ( ) { throw new Error("ACPX turn dispatch journal contract must declare its file, schema and closed phases"); } +const backgroundTasksSchema = schema.$defs.backgroundTasks; +const backgroundLive = backgroundTasksSchema?.properties?.live; +if ( + backgroundTasksSchema?.type !== "object" || + backgroundTasksSchema.additionalProperties !== false || + JSON.stringify(Object.keys(backgroundTasksSchema.properties ?? {})) !== JSON.stringify(["live"]) || + JSON.stringify(backgroundTasksSchema.required) !== JSON.stringify(["live"]) || + backgroundLive?.type !== "integer" || + backgroundLive.minimum !== 0 || + !Number.isSafeInteger(backgroundLive.maximum) +) { + throw new Error("ACPX background tasks must be a closed object with one non-negative integer live count"); +} +const backgroundLiveMaximum = backgroundLive.maximum; const quote = (value) => JSON.stringify(value); const rustVariant = (value) => value @@ -55,8 +69,8 @@ const rustVariant = (value) => .map((part) => part[0].toUpperCase() + part.slice(1)) .join(""); -const typescript = `// Generated by scripts/generate-acpx-sidecar-contract.mjs. Do not edit.\n\nexport const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION = ${protocolVersion} as const;\nexport const GENERATED_ACPX_TURN_DISPATCH_JOURNAL_FILE = ${quote(turnDispatchJournalFile)};\nexport const GENERATED_ACPX_TURN_DISPATCH_SCHEMA = ${quote(turnDispatchSchema)};\nexport const GENERATED_ACPX_SIDECAR_COMMANDS = [\n${commands.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\nexport type GeneratedAcpxSidecarCommand =\n (typeof GENERATED_ACPX_SIDECAR_COMMANDS)[number];\n\nexport const GENERATED_ACPX_SIDECAR_EVENT_TYPES = [\n${events.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\nexport type GeneratedAcpxSidecarEventType =\n (typeof GENERATED_ACPX_SIDECAR_EVENT_TYPES)[number];\n\nexport const GENERATED_ACPX_SIDECAR_OPEN_PARAMS = [\n${openParams.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\n\nexport const GENERATED_ACPX_SIDECAR_PROVIDER_POLICY_FIELDS = [\n${providerPolicyFields.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\n\nexport type GeneratedAcpxToolOperation =\n | "read"\n | "search"\n | "list"\n | "edit"\n | "execute"\n | "unknown";\n\nexport const GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE = [\n${toolOperationPrecedence.map(([operation, tokens]) => ` { operation: ${quote(operation)}, tokens: [${tokens.map(quote).join(", ")}] },`).join("\n")}\n] as const;\n\nexport function classifyGeneratedAcpxToolOperation(\n toolKind: unknown,\n toolTitle: unknown,\n): GeneratedAcpxToolOperation {\n const candidate =\n typeof toolKind === "string" && toolKind\n ? toolKind\n : typeof toolTitle === "string"\n ? toolTitle\n : "";\n const normalized = candidate.slice(0, 240).toLowerCase();\n for (const { operation, tokens } of GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE) {\n if (tokens.some((token) => normalized.includes(token))) return operation;\n }\n return normalized ? "execute" : "unknown";\n}\n`; -const rust = `// Generated by scripts/generate-acpx-sidecar-contract.mjs. Do not edit.\n\npub const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION: u64 = ${protocolVersion};\npub const GENERATED_ACPX_TURN_DISPATCH_JOURNAL_FILE: &str = ${quote(turnDispatchJournalFile)};\npub const GENERATED_ACPX_TURN_DISPATCH_SCHEMA: &str = ${quote(turnDispatchSchema)};\n\npub const GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE: &[(&str, &[&str])] = &[\n${toolOperationPrecedence.map(([operation, tokens]) => ` (${quote(operation)}, &[${tokens.map(quote).join(", ")}]),`).join("\n")}\n];\n\npub fn classify_generated_acpx_tool_operation(kind: &str, title: &str) -> &'static str {\n let kind = kind.to_ascii_lowercase();\n let title = title.to_ascii_lowercase();\n let candidate = if kind.is_empty() { &title } else { &kind };\n for (operation, tokens) in GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE {\n if tokens.iter().any(|token| candidate.contains(token)) {\n return operation;\n }\n }\n if candidate.is_empty() {\n "unknown"\n } else {\n "execute"\n }\n}\n\n#[derive(Clone, Copy, Debug, PartialEq, Eq)]\npub enum GeneratedAcpxSidecarCommand {\n${commands.map((value) => ` ${rustVariant(value)},`).join("\n")}\n}\n\nimpl GeneratedAcpxSidecarCommand {\n pub const fn as_str(self) -> &'static str {\n match self {\n${commands.map((value) => ` Self::${rustVariant(value)} => ${quote(value)},`).join("\n")}\n }\n }\n}\n\n#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Deserialize)]\npub enum GeneratedAcpxSidecarEventType {\n${events.map((value) => ` #[serde(rename = ${quote(value)})]\n ${rustVariant(value)},`).join("\n")}\n}\n`; +const typescript = `// Generated by scripts/generate-acpx-sidecar-contract.mjs. Do not edit.\n\nexport const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION = ${protocolVersion} as const;\nexport const GENERATED_ACPX_TURN_DISPATCH_JOURNAL_FILE = ${quote(turnDispatchJournalFile)};\nexport const GENERATED_ACPX_TURN_DISPATCH_SCHEMA = ${quote(turnDispatchSchema)};\nexport const GENERATED_ACPX_SIDECAR_COMMANDS = [\n${commands.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\nexport type GeneratedAcpxSidecarCommand =\n (typeof GENERATED_ACPX_SIDECAR_COMMANDS)[number];\n\nexport const GENERATED_ACPX_SIDECAR_EVENT_TYPES = [\n${events.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\nexport type GeneratedAcpxSidecarEventType =\n (typeof GENERATED_ACPX_SIDECAR_EVENT_TYPES)[number];\n\nexport const GENERATED_ACPX_SIDECAR_OPEN_PARAMS = [\n${openParams.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\n\nexport const GENERATED_ACPX_SIDECAR_PROVIDER_POLICY_FIELDS = [\n${providerPolicyFields.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\n\nexport const GENERATED_ACPX_BACKGROUND_TASKS_MAX_LIVE = ${backgroundLiveMaximum};\n\nexport type GeneratedAcpxBackgroundTasks = { live: number };\n\nexport function readGeneratedAcpxBackgroundTasks(value: unknown): GeneratedAcpxBackgroundTasks | null {\n if (value === null || typeof value !== "object" || Array.isArray(value)) return null;\n const keys = Object.keys(value);\n const live = (value as Record).live;\n if (keys.length !== 1 || keys[0] !== "live" || typeof live !== "number" || !Number.isInteger(live)) return null;\n return live >= 0 && live <= GENERATED_ACPX_BACKGROUND_TASKS_MAX_LIVE ? { live } : null;\n}\n\nexport type GeneratedAcpxToolOperation =\n | "read"\n | "search"\n | "list"\n | "edit"\n | "execute"\n | "unknown";\n\nexport const GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE = [\n${toolOperationPrecedence.map(([operation, tokens]) => ` { operation: ${quote(operation)}, tokens: [${tokens.map(quote).join(", ")}] },`).join("\n")}\n] as const;\n\nexport function classifyGeneratedAcpxToolOperation(\n toolKind: unknown,\n toolTitle: unknown,\n): GeneratedAcpxToolOperation {\n const candidate =\n typeof toolKind === "string" && toolKind\n ? toolKind\n : typeof toolTitle === "string"\n ? toolTitle\n : "";\n const normalized = candidate.slice(0, 240).toLowerCase();\n for (const { operation, tokens } of GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE) {\n if (tokens.some((token) => normalized.includes(token))) return operation;\n }\n return normalized ? "execute" : "unknown";\n}\n`; +const rust = `// Generated by scripts/generate-acpx-sidecar-contract.mjs. Do not edit.\n\npub const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION: u64 = ${protocolVersion};\npub const GENERATED_ACPX_TURN_DISPATCH_JOURNAL_FILE: &str = ${quote(turnDispatchJournalFile)};\npub const GENERATED_ACPX_TURN_DISPATCH_SCHEMA: &str = ${quote(turnDispatchSchema)};\npub const GENERATED_ACPX_BACKGROUND_TASKS_MAX_LIVE: u64 = ${backgroundLiveMaximum};\n\npub fn read_generated_acpx_background_tasks(value: &serde_json::Value) -> Option {\n let tasks = value.as_object()?;\n if tasks.len() != 1 {\n return None;\n }\n tasks\n .get("live")?\n .as_u64()\n .filter(|live| *live <= GENERATED_ACPX_BACKGROUND_TASKS_MAX_LIVE)\n}\n\npub const GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE: &[(&str, &[&str])] = &[\n${toolOperationPrecedence.map(([operation, tokens]) => ` (${quote(operation)}, &[${tokens.map(quote).join(", ")}]),`).join("\n")}\n];\n\npub fn classify_generated_acpx_tool_operation(kind: &str, title: &str) -> &'static str {\n let kind = kind.to_ascii_lowercase();\n let title = title.to_ascii_lowercase();\n let candidate = if kind.is_empty() { &title } else { &kind };\n for (operation, tokens) in GENERATED_ACPX_TOOL_OPERATION_PRECEDENCE {\n if tokens.iter().any(|token| candidate.contains(token)) {\n return operation;\n }\n }\n if candidate.is_empty() {\n "unknown"\n } else {\n "execute"\n }\n}\n\n#[derive(Clone, Copy, Debug, PartialEq, Eq)]\npub enum GeneratedAcpxSidecarCommand {\n${commands.map((value) => ` ${rustVariant(value)},`).join("\n")}\n}\n\nimpl GeneratedAcpxSidecarCommand {\n pub const fn as_str(self) -> &'static str {\n match self {\n${commands.map((value) => ` Self::${rustVariant(value)} => ${quote(value)},`).join("\n")}\n }\n }\n}\n\n#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Deserialize)]\npub enum GeneratedAcpxSidecarEventType {\n${events.map((value) => ` #[serde(rename = ${quote(value)})]\n ${rustVariant(value)},`).join("\n")}\n}\n`; // Classification must inspect the same complete provider value in both // languages. Display-field truncation happens only after operation selection. diff --git a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts index 753892126c1..88ad0d3e2cd 100644 --- a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts +++ b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts @@ -87,6 +87,7 @@ describe("live sidecar pending request snapshots", () => { import { deliverAcpxResponse } from "../drivers/acpx/response-delivery.js"; import { normalizeAcpxPermission } from "../drivers/acpx/acp-permission-adapter.js"; import { ACPX_CAPABILITY_PROFILES } from "../drivers/acpx/capability-profiles.js"; +import { readGeneratedAcpxBackgroundTasks } from "../drivers/acpx/generated-sidecar-contract.js"; import { resolveQualifiedAcpxProfile } from "../drivers/acpx/qualified-profiles.js"; import { ACPX_SIDECAR_PROTOCOL_VERSION, ACPX_SIDECAR_MAX_FRAME_BYTES, stringifyAcpxSidecarFrame, parseAcpxSidecarRequest, record, text } from "../drivers/acpx/sidecar-protocol.js"; import { canonicalProviderEventsFromAcpxRuntimeEvent } from "../provider-events.js"; @@ -1154,6 +1155,98 @@ describe("qualified ACPX runtime sidecar", () => { } finally { await sidecar.close(); rmSync(root,{recursive:true,force:true}); } }, 15000); + it.each(["claude", "codex"] as const)("reports %s live background tasks only on a completed Claude terminal and snapshot", async agent => { + const root = mkdtempSync(join(tmpdir(), "acpx-background-tasks-")); + const loader = join(root, "loader.mjs"), fixture = join(root, "host.mjs"); + const base = new URL("../test-support/acpx-blocked-output-host.mjs", import.meta.url).href; + const turns = [ + { state: { live: 0 }, status: "completed" }, + { state: { live: 2 }, status: "completed" }, + { state: null, status: "completed" }, + { state: { live: 0 }, status: "failed" }, + { state: { live: 0 }, status: "cancelled", plan: true }, + { state: { live: -1 }, status: "completed" }, + { throws: true, status: "completed" }, + ]; + writeFileSync(join(root, "turns.json"), JSON.stringify(turns)); + writeFileSync(fixture, `import { AcpxRuntimeHost as Base } from ${JSON.stringify(base)}; + import { readFileSync } from "node:fs"; + import { join } from "node:path"; + const turns = JSON.parse(readFileSync(join(process.env.PAPERCLIP_TEST_OUTPUT_ROOT, "turns.json"), "utf8")); + let turn = -1; + export class AcpxRuntimeHost extends Base { + static async open(options) { const host = await Base.open(options); Object.setPrototypeOf(host, this.prototype); return host; } + backgroundTaskState() { + const current = turns[Math.max(turn, 0)]; + if (current.throws) throw new Error("background task state unavailable"); + return current.state; + } + startTurn({ requestId, onPlanProposal }) { + const current = turns[++turn]; + if (current.plan) onPlanProposal({ toolCallId: "toolu_plan", markdown: "# Plan" }); + return { requestId, promptStarted: Promise.resolve(), + result: Promise.resolve(current.status === "failed" ? { status: "failed", error: { message: "provider failed" } } : { status: current.status }), + events: (async function* () {})() }; + } + }`); + writeFileSync(loader, `import { registerHooks } from "node:module"; import { pathToFileURL } from "node:url"; + registerHooks({resolve(specifier,context,next){ + if(context.parentURL?.includes("/acpx-runtime-sidecar.") && specifier.endsWith("/runtime-host.js")) + return {url:pathToFileURL(${JSON.stringify(fixture)}).href,shortCircuit:true}; + return next(specifier,context); + }});`); + const sidecar = new SidecarProcess({ loader, environment: { PAPERCLIP_TEST_OUTPUT_ROOT: root } }); + children.add(sidecar); + const model = agent === "claude" ? "claude-sonnet-5" : "gpt-5.6-sol"; + let id = 0; + const send = async (command: string, params: Record) => { + sidecar.write({ protocolVersion: ACPX_SIDECAR_PROTOCOL_VERSION, id: ++id, command, params }); + const sent = id; + const reply = await sidecar.next(frame => frame.id === sent); + expect(reply).toMatchObject({ ok: true }); + return reply.result as Record; + }; + try { + sidecar.write(initializeRequest(++id, agent, model)); + expect(await sidecar.next(frame => frame.id === 1)).toMatchObject({ ok: true }); + await send("session.open", { agent, model, runtimeDirectory: root, workingDirectory: root, + normalizedSessionId: "background-session", permissionMode: "deny-all", systemInstructions: "Test background tasks.", tools: [] }); + await send("run.attach", { runId: "background-run", catalogRevision: 1, tools: [] }); + const observed: Array<{ terminal: unknown; snapshot: unknown }> = []; + for (const [index] of turns.entries()) { + const turnId = `turn-${index + 1}`; + await send("turn.start", { turnId, message: "Work." }); + const terminal = await sidecar.next(frame => frame.eventType === "runtime.turn_terminal" && frame.turnId === turnId); + const snapshot = await send("session.snapshot", {}); + observed.push({ terminal: (terminal.payload as Record).backgroundTasks, snapshot: snapshot.backgroundTasks }); + } + expect(observed).toEqual(agent === "claude" ? [ + { terminal: { live: 0 }, snapshot: { live: 0 } }, + { terminal: { live: 2 }, snapshot: { live: 2 } }, + { terminal: undefined, snapshot: undefined }, + { terminal: undefined, snapshot: { live: 0 } }, + { terminal: undefined, snapshot: { live: 0 } }, + { terminal: undefined, snapshot: undefined }, + { terminal: undefined, snapshot: undefined }, + ] : turns.map(() => ({ terminal: undefined, snapshot: undefined }))); + } finally { await sidecar.close(); children.delete(sidecar); rmSync(root, { recursive: true, force: true }); } + }, 20_000); + + it("withholds the quiet Claude state once the tool-use ledger cannot fit another full turn", () => { + const source = readFileSync(new URL("./acpx-runtime-sidecar.ts", import.meta.url), "utf8"); + const start = source.indexOf("function claudeBackgroundTasks("); + const end = source.indexOf("async function waitForTool(", start); + expect(start).toBeGreaterThan(0); + const load = (agent: string, room: boolean | null) => new Function("initializedAgent", "toolUseAdmission", "readGeneratedAcpxBackgroundTasks", + `${stripTypeScriptTypes(source.slice(start, end))}; return claudeBackgroundTasks;`)( + agent, room === null ? null : { hasRoomForAnotherTurn: () => room }, readGeneratedAcpxBackgroundTasks); + const host = { backgroundTaskState: () => ({ live: 0 }) }; + expect(load("claude", true)(host)).toEqual({ live: 0 }); + expect(load("claude", false)(host)).toBeNull(); + expect(load("claude", null)(host)).toBeNull(); + expect(load("codex", true)(host)).toBeNull(); + }); + it.each(["claude", "codex"] as const)("binds %s tool calls to the turn that announced their tool use", async agent => { const root = mkdtempSync(join(tmpdir(), "acpx-tool-use-")); const loader = join(root, "loader.mjs"), fixture = join(root, "host.mjs"); diff --git a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts index c488227f01c..f83d4c290bd 100644 --- a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts +++ b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts @@ -81,7 +81,7 @@ import { type AcpxSidecarRequest, type AcpxSidecarResponse, } from "../drivers/acpx/sidecar-protocol.js"; -import { GENERATED_ACPX_SIDECAR_OPEN_PARAMS, GENERATED_ACPX_SIDECAR_PROVIDER_POLICY_FIELDS } from "../drivers/acpx/generated-sidecar-contract.js"; +import { GENERATED_ACPX_SIDECAR_OPEN_PARAMS, GENERATED_ACPX_SIDECAR_PROVIDER_POLICY_FIELDS, readGeneratedAcpxBackgroundTasks, type GeneratedAcpxBackgroundTasks } from "../drivers/acpx/generated-sidecar-contract.js"; import { safeAcpxLocations } from "./acpx-sidecar-locations.js"; import { createCopilotToolEvidence, type CopilotToolEvidence } from "../drivers/acpx/copilot-tool-evidence.js"; import { createCursorToolEvidence, type CursorToolEvidence } from "../drivers/acpx/cursor-tool-evidence.js"; @@ -629,6 +629,7 @@ async function dispatch( sequence, pendingToolCount: tools.size, pendingInputCount: inputs.size, + ...(turnId === null ? optionalBackgroundTasks(activeHost) : {}), pendingRuntimeRequests: [ ...Array.from(inputs, ([requestId, pending]) => ({ requestId, type: "input", turnId: pending.turnId })), ...Array.from(permissions, ([requestId, pending]) => ({ requestId, type: "permission", turnId: pending.turnId })), @@ -829,7 +830,8 @@ async function pumpTurn( } // Declining Claude's native plan approval interrupts its turn. The captured // proposal is this turn's deliverable, so the turn completes normally. - if (planProposalTurns.delete(currentTurnId) && terminal.status === "cancelled") { + const declinedPlan = planProposalTurns.delete(currentTurnId) && terminal.status === "cancelled"; + if (declinedPlan) { terminal = { status: "completed", stopReason: "end_turn" }; } // A terminal frame is also runnerd's permission to recycle this provider. @@ -842,8 +844,9 @@ async function pumpTurn( } catch { // The terminal stays authoritative even if the optional observation fails. } - if (goalAtTerminal) { - const payload = { ...terminal, goalAtTerminal }; + const backgroundTasks = terminal.status === "completed" && !declinedPlan ? claudeBackgroundTasks(activeHost) : null; + if (goalAtTerminal || backgroundTasks) { + const payload = { ...terminal, ...(goalAtTerminal ? { goalAtTerminal } : {}), ...(backgroundTasks ? { backgroundTasks } : {}) }; // Rust admits the payload separately from the larger sidecar frame. if (Buffer.byteLength(JSON.stringify(payload)) <= MAX_EVENT_PAYLOAD_BYTES && emit("runtime.turn_terminal", payload, currentTurnId)) return; @@ -851,6 +854,20 @@ async function pumpTurn( emit("runtime.turn_terminal", terminal, currentTurnId); } +function optionalBackgroundTasks(activeHost: AcpxRuntimeHost): { backgroundTasks?: GeneratedAcpxBackgroundTasks } { + const backgroundTasks = claudeBackgroundTasks(activeHost); + return backgroundTasks ? { backgroundTasks } : {}; +} + +function claudeBackgroundTasks(activeHost: AcpxRuntimeHost): GeneratedAcpxBackgroundTasks | null { + if (initializedAgent !== "claude" || !toolUseAdmission?.hasRoomForAnotherTurn()) return null; + try { + return readGeneratedAcpxBackgroundTasks(activeHost.backgroundTaskState()); + } catch { + return null; + } +} + async function waitForTool(call: RunnerToolCall, internal = false): Promise { const activeTurnId = turnId; const activeRunId = runId; diff --git a/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.claude-background-tasks.test.ts b/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.claude-background-tasks.test.ts new file mode 100644 index 00000000000..2c040d0cf67 --- /dev/null +++ b/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.claude-background-tasks.test.ts @@ -0,0 +1,149 @@ +import { spawn } from "node:child_process"; +import { mkdir, mkdtemp, rm } from "node:fs/promises"; +import { createServer } from "node:http"; +import { createRequire } from "node:module"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { expect, it, vi } from "vitest"; + +import { openCodexAcpxRuntime } from "./acpx-runtime-adapter.js"; +import type { VerifiedAcpxCommandLease } from "./installation-integrity.js"; +import { resolveQualifiedAcpxProfile } from "./qualified-profiles.js"; +import type { AcpxRuntimePortOpenOptions } from "./runtime-host.js"; +import { persistedAcpxTurnUsage } from "./usage-accounting.js"; + +type Block = { type: string; text?: string; tool_use_id?: string; content?: unknown }; +type Message = { role: string; content: string | Block[] }; + +const textOf = (content: string | Block[] | undefined): string => typeof content === "string" ? content + : (content ?? []).map(block => block.text ?? "").join("\n"); + +it("knows from the real Claude ACP stream when a turn leaves background work running", async () => { + const root = await mkdtemp(join(tmpdir(), "claude-background-tasks-acp-")); + const home = join(root, "home"), cwd = join(root, "workspace"), config = join(home, ".claude"); + await Promise.all([mkdir(config, { recursive: true }), mkdir(cwd)]); + const toolResults: string[] = []; + let notified = 0; + let sequence = 0; + const api = createServer(async (request, response) => { + let raw = ""; + for await (const chunk of request) raw += chunk; + if (request.method === "GET") { + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ data: [], has_more: false })); + return; + } + if (request.url?.includes("count_tokens")) { + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ input_tokens: 1 })); + return; + } + const body = JSON.parse(raw || "{}") as { model?: string; stream?: boolean; messages?: Message[]; tools?: Array<{ name: string }> }; + const model = body.model ?? "claude-sonnet-5"; + if (body.stream !== true) { + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ id: "msg_fixture", type: "message", role: "assistant", model, + content: [{ type: "text", text: "OK" }], stop_reason: "end_turn", usage: { input_tokens: 1, output_tokens: 1 } })); + return; + } + const conversation = (body.messages ?? []).filter(message => message.role === "user" || message.role === "assistant"); + const last = conversation.at(-1)?.content; + const results = Array.isArray(last) ? last.filter(block => block.type === "tool_result") : []; + const offersBash = (body.tools ?? []).some(tool => tool.name === "Bash"); + const frames: Array> = [{ type: "message_start", message: { id: `msg_${++sequence}`, type: "message", + role: "assistant", model, content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 3, output_tokens: 0 } } }]; + const text = (value: string) => frames.push({ type: "content_block_start", index: 0, content_block: { type: "text", text: "" } }, + { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: value } }, + { type: "content_block_stop", index: 0 }, + { type: "message_delta", delta: { stop_reason: "end_turn", stop_sequence: null }, usage: { output_tokens: 2 } }); + const bash = (input: Record) => frames.push( + { type: "content_block_start", index: 0, content_block: { type: "tool_use", id: `toolu_01Background${sequence}`, name: "Bash", input: {} } }, + { type: "content_block_delta", index: 0, delta: { type: "input_json_delta", partial_json: JSON.stringify(input) } }, + { type: "content_block_stop", index: 0 }, + { type: "message_delta", delta: { stop_reason: "tool_use", stop_sequence: null }, usage: { output_tokens: 2 } }); + if (results.length > 0) { + toolResults.push(...results.map(block => JSON.stringify(block.content))); + text("Done."); + } else if (//.test(textOf(last))) { + notified += 1; + text("The background command finished."); + } else if (offersBash && /FOREGROUND-TURN/.test(textOf(last))) { + bash({ command: "echo foreground-done", description: "foreground echo" }); + } else if (offersBash && /BACKGROUND-TURN/.test(textOf(last))) { + bash({ command: "sleep 2; echo background-done", description: "background sleep", run_in_background: true }); + } else { + text("Nothing to run."); + } + frames.push({ type: "message_stop" }); + response.writeHead(200, { "content-type": "text/event-stream" }); + for (const frame of frames) response.write(`event: ${frame.type}\ndata: ${JSON.stringify(frame)}\n\n`); + response.end(); + }); + await new Promise(resolve => api.listen(0, "127.0.0.1", resolve)); + const address = api.address() as { port: number }; + const entry = createRequire(import.meta.url).resolve("@agentclientprotocol/claude-agent-acp/dist/index.js"); + let spawned = 0; + const command: VerifiedAcpxCommandLease = { + spawn: (args, input) => { + spawned += 1; + return spawn(process.execPath, [entry, ...(args ?? [])], { ...input, detached: true, stdio: ["pipe", "pipe", "pipe"] }); + }, + close: async () => undefined, + }; + const options: AcpxRuntimePortOpenOptions = { + command, + profile: resolveQualifiedAcpxProfile("claude", "claude-sonnet-5"), + cwd, + stateDirectory: join(root, "state"), + providerSessionKey: "claude-background-tasks", + permissionMode: "approve-all", + permissionPolicy: { autoApprove: ["read", "write", "execute", "other"], defaultAction: "approve" }, + launchEnvironment: { HOME: home, CLAUDE_CONFIG_DIR: config, PATH: "/usr/bin:/bin", TMPDIR: root, + ANTHROPIC_API_KEY: "local-fixture-only", ANTHROPIC_BASE_URL: `http://127.0.0.1:${address.port}`, + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1", DISABLE_TELEMETRY: "1", DISABLE_ERROR_REPORTING: "1", ENABLE_TOOL_SEARCH: "false" }, + credentialFenceFds: [42, 43] as const, + activateCredentialFenceOwner: async () => undefined, + systemInstructions: "Run the requested command.", + mcpServers: [], + retainFailedAdmissionCleanup: vi.fn(), + } as AcpxRuntimePortOpenOptions; + let port: Awaited> | undefined; + const runTurn = async (turnId: string, text: string) => { + const before = await port!.getStatus(); + const turn = port!.startTurn({ text, requestId: turnId, onPermissionRequest: async () => ({ outcome: "allow_once" }) }); + for await (const _event of turn.events) void _event; + const result = await turn.result; + const state = port!.backgroundTaskState?.() ?? null; + const usage = persistedAcpxTurnUsage(before, await port!.getStatus(), turnId, "claude"); + return { result, state, usage }; + }; + try { + port = await openCodexAcpxRuntime(options, { + awaitProviderOwnership: async () => undefined, + awaitProviderExit: child => new Promise(resolve => child.once("exit", () => resolve())), + }); + const foreground = await runTurn("turn-foreground", "FOREGROUND-TURN: run the foreground command."); + expect(foreground.result).toMatchObject({ status: "completed" }); + expect(toolResults.join("\n")).toContain("foreground-done"); + expect(foreground.state).toEqual({ live: 0 }); + expect(foreground.usage).toMatchObject({ tag: "usage_update", breakdown: { inputTokens: expect.any(Number) } }); + + const background = await runTurn("turn-background", "BACKGROUND-TURN: start the command in the background."); + expect(background.result).toMatchObject({ status: "completed" }); + expect(toolResults.join("\n")).toContain("Command running in background with ID:"); + expect(background.state).toEqual({ live: 1 }); + expect(background.usage).toMatchObject({ tag: "usage_update", breakdown: { inputTokens: expect.any(Number) } }); + expect(spawned).toBe(1); + + await vi.waitFor(() => expect(notified).toBe(1), { timeout: 20_000, interval: 50 }); + expect(port.backgroundTaskState?.()).toBeNull(); + } finally { + try { await port?.close({ reason: "background task tracking verified" }); } + finally { + api.closeAllConnections(); + await new Promise(resolve => api.close(() => resolve())); + await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }); + } + } +}, 60_000); diff --git a/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.ts b/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.ts index 8823d182312..8d795e63b21 100644 --- a/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.ts +++ b/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.ts @@ -6,6 +6,7 @@ import { resolveGrokDisableWebSearch } from "./grok-web-search.js"; import { resolveGrokEffort, createGrokEffortAdmission } from "./grok-effort.js"; import { createGrokSessionOpenGuard } from "./grok-session-rules.js"; import { resolveClaudeEffort, createClaudeEffortAdmission } from "./claude-effort.js"; +import { CLAUDE_ASYNC_TASKS_CAPABILITY, ClaudeBackgroundTaskTracker } from "./claude-background-tasks.js"; import { acpxProviderFailure, acpxTypedSessionFailureClientCapabilities, acpxTypedTerminalSessionFailure, type AcpxTerminalSessionFailure } from "./provider-failure.js"; import type { ProviderFailure } from "../../contracts/provider-failure.generated.js"; import { createPiThinkingAdmission, resolvePiThinkingLevel } from "./pi-thinking.js"; @@ -368,6 +369,7 @@ export async function openQualifiedAcpxRuntime( const extensionNotifications = new Set(extensionProfile.extensionNotifications); const promptUsage = options.profile.agent === "grok" ? createGrokPromptUsageCollector() : undefined; const promptReceipts = createAcpxPromptReceiptCollector(options.profile.agent); + const backgroundTasks = options.profile.agent === "claude" ? new ClaudeBackgroundTaskTracker() : null; const permissionReplies = createAcpxPermissionReplyConfirmations(); const modelGate = createAcpxEffectiveModelGate(options.profile.reportedModelId); // Copilot's admitted permission policy is enforced from the observed wire: @@ -470,7 +472,10 @@ export async function openQualifiedAcpxRuntime( ? "approve-reads" : options.permissionMode, elicitationModes: ["form"], - clientCapabilities: acpxTypedSessionFailureClientCapabilities(options.clientCapabilities), + clientCapabilities: acpxTypedSessionFailureClientCapabilities( + options.clientCapabilities, + backgroundTasks ? [CLAUDE_ASYNC_TASKS_CAPABILITY] : [], + ), extensionMethods: [...new Set([...extensionRequests, ...extensionNotifications])], onExtensionRequest: async (method, params, context) => { const active = extensionBoundary.active; @@ -584,6 +589,7 @@ export async function openQualifiedAcpxRuntime( return { outcome: disposition }; }, onAcpMessage: (direction, message) => { + backgroundTasks?.observe(direction, message); observeAgentInitialize(direction, message); copilotPolicy?.observe(direction, message); modelGate.observe(direction, message); @@ -831,6 +837,7 @@ export async function openQualifiedAcpxRuntime( copilotPolicy, modelGate, promptReceipts, + backgroundTasks, ); } catch (error) { const cleanupReason = "ACPX runtime identity validation failed"; @@ -1285,6 +1292,7 @@ function runtimePort( copilotPolicy?: CopilotPolicyEnforcement | null, modelGate?: AcpxEffectiveModelGate, promptReceipts?: ReturnType, + backgroundTasks?: ClaudeBackgroundTaskTracker | null, ): AcpxRuntimePort { extensionBoundary.sessionIds = new Set([identity.backendSessionId]); let extensionControls: Promise = Promise.resolve(); @@ -1574,6 +1582,9 @@ function runtimePort( ? null : structuredClone(goalState.capability); }, + backgroundTaskState() { + return backgroundTasks?.state() ?? null; + }, goalSnapshot() { return goalState.snapshot === null ? null diff --git a/packages/paperclip-runner/src/drivers/acpx/claude-background-tasks.test.ts b/packages/paperclip-runner/src/drivers/acpx/claude-background-tasks.test.ts new file mode 100644 index 00000000000..984fda48076 --- /dev/null +++ b/packages/paperclip-runner/src/drivers/acpx/claude-background-tasks.test.ts @@ -0,0 +1,176 @@ +import { readFileSync } from "node:fs"; + +import { describe, expect, it } from "vitest"; + +import { ClaudeBackgroundTaskTracker } from "./claude-background-tasks.js"; +import { readGeneratedAcpxBackgroundTasks } from "./generated-sidecar-contract.js"; + +const vectors = JSON.parse(readFileSync( + new URL("../../../protocol/fixtures/provider-boundary/acpx-background-tasks.json", import.meta.url), "utf8", +)) as { accepted: Array<{ value: unknown; live: number }>; rejected: Array<{ case: string; value: unknown }> }; + +describe("generated ACPX background task reader", () => { + it("accepts and rejects exactly the shared vectors", () => { + for (const { value, live } of vectors.accepted) expect(readGeneratedAcpxBackgroundTasks(value)).toEqual({ live }); + for (const { value, case: name } of vectors.rejected) expect(readGeneratedAcpxBackgroundTasks(value), name).toBeNull(); + expect(readGeneratedAcpxBackgroundTasks(undefined)).toBeNull(); + }); +}); + +const air = (capabilities: string[]) => ({ jetbrains: { air: { version: 1, capabilities } } }); + +function negotiated(client = ["sessionFailure", "asyncTasks"], agent = ["sessionFailure", "asyncTasks"]) { + const tracker = new ClaudeBackgroundTaskTracker(); + tracker.observe("outbound", { jsonrpc: "2.0", id: 0, method: "initialize", params: { clientCapabilities: { _meta: air(client) } } }); + tracker.observe("inbound", { jsonrpc: "2.0", id: 0, result: { protocolVersion: 1, _meta: air(agent) } }); + return tracker; +} + +const update = (value: Record) => ({ + jsonrpc: "2.0", method: "session/update", params: { sessionId: "session-1", update: value }, +}); + +function prompt(tracker: ClaudeBackgroundTaskTracker, id: number, updates: Array>) { + tracker.observe("outbound", { jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId: "session-1" } }); + for (const value of updates) tracker.observe("inbound", update(value)); + tracker.observe("inbound", { jsonrpc: "2.0", id, result: { stopReason: "end_turn" } }); +} + +const spawned = (taskType = "shell") => ({ + sessionUpdate: "async_task_spawned", asyncTaskId: "task-1", name: "background", taskType, + description: "background", showInTranscript: false, canStop: true, +}); +const backgrounded = { + sessionUpdate: "tool_call_update", toolCallId: "toolu_1", + _meta: { claudeCode: { toolName: "Bash", toolResponse: { backgroundTaskId: "task-1" } } }, +}; +const settled = (state: string) => ({ sessionUpdate: "async_task_state_update", asyncTaskId: "task-1", state }); + +describe("ClaudeBackgroundTaskTracker", () => { + it("knows a negotiated provider that started no background work is quiet", () => { + const tracker = negotiated(); + prompt(tracker, 1, [ + { sessionUpdate: "tool_call", toolCallId: "toolu_1", _meta: { claudeCode: { toolName: "Bash" } } }, + { sessionUpdate: "tool_call_update", toolCallId: "toolu_1", status: "completed" }, + { sessionUpdate: "usage_update", used: 1, size: 2, _meta: { "_claude/origin": { kind: "human" } } }, + ]); + tracker.observe("inbound", update({ sessionUpdate: "session_info_update", title: "Done" })); + expect(tracker.state()).toEqual({ live: 0 }); + }); + + it("reports a spawned background shell as live", () => { + const tracker = negotiated(); + prompt(tracker, 1, [spawned(), { sessionUpdate: "async_task_progress", asyncTaskId: "task-1", toolCallId: "toolu_1" }, backgrounded]); + expect(tracker.state()).toEqual({ live: 1 }); + tracker.observe("inbound", update(settled("paused"))); + expect(tracker.state()).toEqual({ live: 1 }); + }); + + it.each(["completed", "failed", "stopped"])("never reports quiet again after a background shell %s", (state) => { + const tracker = negotiated(); + prompt(tracker, 1, [spawned(), backgrounded]); + tracker.observe("inbound", update(settled(state))); + expect(tracker.state()).toBeNull(); + prompt(tracker, 2, []); + expect(tracker.state()).toBeNull(); + }); + + it("counts a backgrounded Bash result even before its async task is announced", () => { + const tracker = negotiated(); + prompt(tracker, 1, [backgrounded]); + expect(tracker.state()).toEqual({ live: 1 }); + }); + + it("cannot classify a live monitor or other non-shell task, which covers ambient watchers", () => { + for (const taskType of ["monitor", "workflow", "task"]) { + const tracker = negotiated(); + prompt(tracker, 1, [spawned(taskType)]); + expect(tracker.state(), taskType).toBeNull(); + } + }); + + it("ignores subagents, which the adapter holds inside their spawning turn", () => { + const tracker = negotiated(); + prompt(tracker, 1, [ + { sessionUpdate: "tool_call", toolCallId: "toolu_1", _meta: { claudeCode: { toolName: "Agent", subagent: true } } }, + { sessionUpdate: "tool_call_update", toolCallId: "toolu_1", _meta: { claudeCode: { toolResponse: { isAsync: true, status: "async_launched" } } } }, + { sessionUpdate: "tool_call", toolCallId: "toolu_2", _meta: { claudeCode: { toolName: "Read", parentToolUseId: "toolu_1" } } }, + { sessionUpdate: "tool_call_update", toolCallId: "toolu_1", _meta: { claudeCode: { subagentState: { status: "completed" } } } }, + { sessionUpdate: "usage_update", used: 1, size: 2, _meta: { "_claude/origin": { kind: "task-notification" } } }, + ]); + expect(tracker.state()).toEqual({ live: 0 }); + }); + + it("is unknown without negotiating the asyncTasks capability on both sides", () => { + expect(new ClaudeBackgroundTaskTracker().state()).toBeNull(); + expect(negotiated(["sessionFailure"]).state()).toBeNull(); + expect(negotiated(undefined, ["sessionFailure"]).state()).toBeNull(); + const tracker = negotiated(); + tracker.observe("outbound", { jsonrpc: "2.0", id: 9, method: "initialize", params: { clientCapabilities: { _meta: air(["asyncTasks"]) } } }); + tracker.observe("inbound", { jsonrpc: "2.0", id: 9, result: { _meta: air([]) } }); + expect(tracker.state()).toBeNull(); + }); + + it("is unknown after malformed, unannounced or unrecognized task updates", () => { + const cases: Array> = [ + { sessionUpdate: "async_task_spawned", taskType: "shell" }, + { sessionUpdate: "async_task_progress", asyncTaskId: "unannounced" }, + { sessionUpdate: "async_task_state_update", asyncTaskId: "task-1", state: "exploded" }, + { sessionUpdate: "async_task_renamed", asyncTaskId: "task-1" }, + { ...backgrounded, _meta: { claudeCode: { toolResponse: { backgroundTaskId: 7 } } } }, + ]; + for (const value of cases) { + const tracker = negotiated(); + prompt(tracker, 1, [spawned(), value]); + expect(tracker.state(), JSON.stringify(value)).toBeNull(); + } + }); + + it("is unknown once Claude acts with no request in flight or schedules its own wakeup", () => { + const idle = negotiated(); + prompt(idle, 1, []); + idle.observe("inbound", update({ sessionUpdate: "tool_call", toolCallId: "toolu_9", _meta: { claudeCode: { toolName: "Read" } } })); + expect(idle.state()).toBeNull(); + + const idleUsage = negotiated(); + prompt(idleUsage, 1, []); + idleUsage.observe("inbound", update({ sessionUpdate: "usage_update", _meta: { "_claude/origin": { kind: "task-notification" } } })); + expect(idleUsage.state()).toBeNull(); + + const idleRequest = negotiated(); + idleRequest.observe("inbound", { jsonrpc: "2.0", id: 4, method: "session/request_permission", params: {} }); + expect(idleRequest.state()).toBeNull(); + + for (const toolName of ["CronCreate", "ScheduleWakeup"]) { + const scheduled = negotiated(); + prompt(scheduled, 1, [{ sessionUpdate: "tool_call", toolCallId: "toolu_1", _meta: { claudeCode: { toolName } } }]); + expect(scheduled.state(), toolName).toBeNull(); + } + }); + + it("does not treat replayed history during a session load as idle activity", () => { + const tracker = negotiated(); + tracker.observe("outbound", { jsonrpc: "2.0", id: 1, method: "session/load", params: {} }); + tracker.observe("inbound", update({ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "earlier" } })); + tracker.observe("inbound", { jsonrpc: "2.0", id: 1, result: {} }); + expect(tracker.state()).toEqual({ live: 0 }); + }); + + it("is unknown when its bounded ledgers overflow or a request id is reused", () => { + const reused = negotiated(); + reused.observe("outbound", { jsonrpc: "2.0", id: 1, method: "session/prompt" }); + reused.observe("outbound", { jsonrpc: "2.0", id: 1, method: "session/prompt" }); + expect(reused.state()).toBeNull(); + + const pending = negotiated(); + for (let id = 1; id <= 257; id += 1) pending.observe("outbound", { jsonrpc: "2.0", id, method: "session/prompt" }); + expect(pending.state()).toBeNull(); + + const tasks = negotiated(); + tasks.observe("outbound", { jsonrpc: "2.0", id: 1, method: "session/prompt" }); + for (let index = 0; index < 257; index += 1) { + tasks.observe("inbound", update({ ...spawned(), asyncTaskId: `task-${index}` })); + } + expect(tasks.state()).toBeNull(); + }); +}); diff --git a/packages/paperclip-runner/src/drivers/acpx/claude-background-tasks.ts b/packages/paperclip-runner/src/drivers/acpx/claude-background-tasks.ts new file mode 100644 index 00000000000..fd6752c1d76 --- /dev/null +++ b/packages/paperclip-runner/src/drivers/acpx/claude-background-tasks.ts @@ -0,0 +1,148 @@ +import type { GeneratedAcpxBackgroundTasks } from "./generated-sidecar-contract.js"; + +export const CLAUDE_ASYNC_TASKS_CAPABILITY = "asyncTasks"; + +export type ClaudeBackgroundTaskState = GeneratedAcpxBackgroundTasks; + +const MAX_TRACKED_TASKS = 256; +const MAX_PENDING_REQUESTS = 256; +const MAX_TASK_ID_CHARS = 256; +const IDLE_ACTIVITY = new Set(["tool_call", "tool_call_update", "agent_message_chunk", "agent_thought_chunk", "plan"]); +const SCHEDULING_TOOLS = new Set(["CronCreate", "ScheduleWakeup"]); +const LIVE_STATES = new Set(["running", "paused"]); +const TERMINAL_STATES = new Set(["completed", "failed", "stopped"]); + +type Task = { shell: boolean; live: boolean }; +type RequestId = string | number; + +const record = (value: unknown): Record => + value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record : {}; + +function advertisesAsyncTasks(meta: unknown): boolean { + const air = record(record(record(meta).jetbrains).air); + return typeof air.version === "number" && Number.isInteger(air.version) && air.version >= 1 + && Array.isArray(air.capabilities) && air.capabilities.includes(CLAUDE_ASYNC_TASKS_CAPABILITY); +} + +export class ClaudeBackgroundTaskTracker { + #negotiated = false; + #unknown = false; + #observedTask = false; + readonly #tasks = new Map(); + readonly #pending = new Map(); + + observe(direction: "inbound" | "outbound", message: unknown): void { + if (this.#unknown) return; + try { + if (direction === "outbound") this.#outbound(record(message)); + else this.#inbound(record(message)); + } catch { + this.#unknown = true; + } + } + + state(): ClaudeBackgroundTaskState | null { + if (this.#unknown || !this.#negotiated) return null; + if (!this.#observedTask) return { live: 0 }; + let live = 0; + for (const task of this.#tasks.values()) { + if (!task.live) continue; + if (!task.shell) return null; + live += 1; + } + return live > 0 ? { live } : null; + } + + #outbound(message: Record): void { + const id = message.id; + if ((typeof id !== "string" && typeof id !== "number") || typeof message.method !== "string") return; + if (this.#pending.has(id) || this.#pending.size >= MAX_PENDING_REQUESTS) { + this.#unknown = true; + return; + } + const advertised = message.method === "initialize" + && advertisesAsyncTasks(record(record(message.params).clientCapabilities)._meta); + this.#pending.set(id, { method: message.method, advertised }); + } + + #inbound(message: Record): void { + const id = message.id; + const hasId = typeof id === "string" || typeof id === "number"; + if (hasId && message.method === undefined) { + const request = this.#pending.get(id); + if (!request) return; + this.#pending.delete(id); + if (request.method !== "initialize") return; + if (request.advertised && message.error === undefined && advertisesAsyncTasks(record(message.result)._meta)) { + this.#negotiated = true; + } else { + this.#unknown = true; + } + return; + } + if (hasId) { + if (this.#pending.size === 0) this.#unknown = true; + return; + } + if (message.method !== "session/update") return; + const update = record(record(message.params).update); + const kind = update.sessionUpdate; + if (typeof kind !== "string") return; + if (kind.startsWith("async_task_")) { + this.#observedTask = true; + this.#asyncTask(kind, update); + return; + } + const claudeCode = record(record(update._meta).claudeCode); + const backgroundTaskId = record(claudeCode.toolResponse).backgroundTaskId; + if (backgroundTaskId !== undefined) { + this.#observedTask = true; + const taskId = this.#taskId(backgroundTaskId); + if (taskId !== null && !this.#tasks.has(taskId)) this.#track(taskId, { shell: true, live: true }); + } + if (kind === "tool_call" && typeof claudeCode.toolName === "string" && SCHEDULING_TOOLS.has(claudeCode.toolName)) { + this.#unknown = true; + } + const origin = record(update._meta)["_claude/origin"]; + if (this.#pending.size === 0 && (IDLE_ACTIVITY.has(kind) || (kind === "usage_update" && origin !== undefined))) { + this.#unknown = true; + } + } + + #asyncTask(kind: string, update: Record): void { + const taskId = this.#taskId(update.asyncTaskId); + if (taskId === null) return; + const task = this.#tasks.get(taskId); + if (kind === "async_task_spawned") { + const shell = update.taskType === "shell"; + if (task) task.shell = task.shell && shell; + else this.#track(taskId, { shell, live: true }); + return; + } + if (kind === "async_task_state_update") { + const state = update.state; + if (typeof state === "string" && TERMINAL_STATES.has(state)) { + if (task) task.live = false; + else this.#track(taskId, { shell: false, live: false }); + } else if (!(typeof state === "string" && LIVE_STATES.has(state) && task)) { + this.#unknown = true; + } + return; + } + if (kind !== "async_task_progress" || !task) this.#unknown = true; + } + + #taskId(value: unknown): string | null { + if (typeof value === "string" && value.length > 0 && value.length <= MAX_TASK_ID_CHARS) return value; + this.#unknown = true; + return null; + } + + #track(taskId: string, task: Task): void { + if (this.#tasks.size >= MAX_TRACKED_TASKS) { + this.#unknown = true; + return; + } + this.#tasks.set(taskId, task); + } +} diff --git a/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.test.ts b/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.test.ts index 3c222a56c25..f8c5190f2ee 100644 --- a/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.test.ts +++ b/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.test.ts @@ -175,4 +175,22 @@ describe("Claude tool-use admission", () => { admission.announce("turn-2", "toolu_idle"); await expect(admission.admit("turn-1", "toolu_idle", live())).rejects.toThrow("not bound to the active turn"); }); + + it("has room for another turn only while a full turn of admissions still fits its ledger", async () => { + const admission = new ClaudeToolUseAdmission(); + expect(admission.hasRoomForAnotherTurn()).toBe(true); + admission.beginTurn("turn-1"); + for (let index = 0; index < 4_096; index += 1) { + const id = `toolu_first${index}`; + admission.announce("turn-1", id); + await admission.admit("turn-1", id, live()); + } + admission.endTurn("turn-1"); + expect(admission.hasRoomForAnotherTurn()).toBe(true); + admission.beginTurn("turn-2"); + admission.announce("turn-2", "toolu_second"); + await admission.admit("turn-2", "toolu_second", live()); + admission.endTurn("turn-2"); + expect(admission.hasRoomForAnotherTurn()).toBe(false); + }); }); diff --git a/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts b/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts index 85e597e0794..ba4a38f5cb0 100644 --- a/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts +++ b/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts @@ -23,6 +23,10 @@ export class ClaudeToolUseAdmission { this.#wake(); } + hasRoomForAnotherTurn(): boolean { + return this.#admitted.size + MAX_TURN_ANNOUNCEMENTS <= MAX_ADMITTED_TOOL_USES; + } + endTurn(turnId: string): void { if (this.#turnId !== turnId) return; this.#turnId = null; diff --git a/packages/paperclip-runner/src/drivers/acpx/generated-sidecar-contract.ts b/packages/paperclip-runner/src/drivers/acpx/generated-sidecar-contract.ts index 01f0eefece9..c113f7cd7ff 100644 --- a/packages/paperclip-runner/src/drivers/acpx/generated-sidecar-contract.ts +++ b/packages/paperclip-runner/src/drivers/acpx/generated-sidecar-contract.ts @@ -64,6 +64,18 @@ export const GENERATED_ACPX_SIDECAR_PROVIDER_POLICY_FIELDS = [ "readOnly", ] as const; +export const GENERATED_ACPX_BACKGROUND_TASKS_MAX_LIVE = 9007199254740991; + +export type GeneratedAcpxBackgroundTasks = { live: number }; + +export function readGeneratedAcpxBackgroundTasks(value: unknown): GeneratedAcpxBackgroundTasks | null { + if (value === null || typeof value !== "object" || Array.isArray(value)) return null; + const keys = Object.keys(value); + const live = (value as Record).live; + if (keys.length !== 1 || keys[0] !== "live" || typeof live !== "number" || !Number.isInteger(live)) return null; + return live >= 0 && live <= GENERATED_ACPX_BACKGROUND_TASKS_MAX_LIVE ? { live } : null; +} + export type GeneratedAcpxToolOperation = | "read" | "search" diff --git a/packages/paperclip-runner/src/drivers/acpx/provider-failure.ts b/packages/paperclip-runner/src/drivers/acpx/provider-failure.ts index 9439f9cf41b..ec6c3328815 100644 --- a/packages/paperclip-runner/src/drivers/acpx/provider-failure.ts +++ b/packages/paperclip-runner/src/drivers/acpx/provider-failure.ts @@ -38,13 +38,14 @@ const TYPED_SESSION_FAILURE_CATEGORIES = new Set(["connection", "access", "limit /** Advertised on initialize so ACP agents report terminal failures as typed JetBrains AIR metadata. */ export function acpxTypedSessionFailureClientCapabilities( extra?: Record, + airCapabilities: readonly string[] = [], ): Record { const meta = extra?._meta !== null && typeof extra?._meta === "object" && !Array.isArray(extra._meta) ? extra._meta as Record : {}; return { ...structuredClone(extra ?? {}), - _meta: { jetbrains: { air: { version: 1, capabilities: ["sessionFailure"] } }, ...structuredClone(meta) }, + _meta: { jetbrains: { air: { version: 1, capabilities: ["sessionFailure", ...airCapabilities] } }, ...structuredClone(meta) }, }; } diff --git a/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts b/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts index ed5b229e85a..ee642d2cb99 100644 --- a/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts +++ b/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts @@ -9,6 +9,7 @@ import { resolveGrokEffort } from "./grok-effort.js"; import { piProviderConfiguration } from "./pi-provider-config.js"; import { withAcpxTurnCancellation } from "./turn-cancellation.js"; import type { AcpxTerminalSessionFailure } from "./provider-failure.js"; +import type { ClaudeBackgroundTaskState } from "./claude-background-tasks.js"; import { resolveAcpxProviderMode } from "./provider-mode.js"; import { resolvePiThinkingLevel, type PiThinkingLevel } from "./pi-thinking.js"; import { preparedHarnessHome, preconfiguredHomeEnvironment, usesPreconfiguredHome } from "../preconfigured-home.js"; @@ -167,6 +168,7 @@ export interface AcpxRuntimePort { queueFollowUp?(text: string, requestId: string): Promise; goalCapability?(): AcpxRuntimeGoalCapability | null; goalSnapshot?(): AcpxRuntimeGoalSnapshot | null; + backgroundTaskState?(): ClaudeBackgroundTaskState | null; controlGoal?( action: "set" | "pause" | "resume" | "clear", objective?: string, @@ -900,6 +902,10 @@ export class AcpxRuntimeHost { return this.#runtime.goalSnapshot?.() ?? null; } + backgroundTaskState(): ClaudeBackgroundTaskState | null { + return this.#runtime.backgroundTaskState?.() ?? null; + } + async controlGoal( action: "set" | "pause" | "resume" | "clear", objective?: string, diff --git a/packages/paperclip-runner/test/acpx-sidecar-contract.test.mjs b/packages/paperclip-runner/test/acpx-sidecar-contract.test.mjs index cb3097483c0..30ea257676a 100644 --- a/packages/paperclip-runner/test/acpx-sidecar-contract.test.mjs +++ b/packages/paperclip-runner/test/acpx-sidecar-contract.test.mjs @@ -277,3 +277,15 @@ test("Pi native empty message boundaries and replay history fit the strict sidec assert.equal(validate({ ...messages[2], payload, piMessageBoundary: { phase: "start" } }), false); } }); + +test("a terminal's background task report matches the shared accepted and rejected vectors", async () => { + const vectors = JSON.parse(await readFile(new URL("../protocol/fixtures/provider-boundary/acpx-background-tasks.json", import.meta.url), "utf8")); + const terminal = (payload) => ({ ...messages[2], eventType: "runtime.turn_terminal", payload }); + assert.equal(validate(terminal({ status: "completed" })), true, JSON.stringify(validate.errors)); + for (const { value } of vectors.accepted) { + assert.equal(validate(terminal({ status: "completed", backgroundTasks: value })), true, JSON.stringify(value)); + } + for (const { value, case: name } of vectors.rejected) { + assert.equal(validate(terminal({ status: "completed", backgroundTasks: value })), false, name); + } +});