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); + } +});