From bfa39ba5608dbb78e525ca1aed30a522c66d09c9 Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Fri, 23 Oct 2026 17:03:11 -0600 Subject: [PATCH 1/3] codex, agent: pin the codex reading, argv and budget_for_spawn before the split 60 real and broken `codex exec --json` lines read on both routes, 7 whole turns, the argv and environment of 11 spawn configurations, the bridged registration, mcp_config and a turn that cannot start; budget_for_spawn at every size around its limits, its priority order, both cut floors and the spill notice. Every expectation was produced by the code as it stands. --- src/agent/budget_pinned_tests.rs | 214 +++++++ src/agent/codex.rs | 3 + src/agent/codex/pinned_tests.rs | 935 +++++++++++++++++++++++++++++++ src/agent/mod.rs | 3 + 4 files changed, 1155 insertions(+) create mode 100644 src/agent/budget_pinned_tests.rs create mode 100644 src/agent/codex/pinned_tests.rs diff --git a/src/agent/budget_pinned_tests.rs b/src/agent/budget_pinned_tests.rs new file mode 100644 index 0000000..378976c --- /dev/null +++ b/src/agent/budget_pinned_tests.rs @@ -0,0 +1,214 @@ +//! Pins on [`crate::agent::budget_for_spawn`], taken from the code before it +//! was broken into named steps: what it returns at every size around the +//! limits, which blocks it keeps first, where it cuts, and the file it +//! writes for a prompt too long to send. Each expectation is written out by +//! construction from the limits, so it holds on Windows and Unix alike. + +use crate::agent::{budget_for_spawn, MAX_CMDLINE_PAYLOAD_LEN as MAX, MAX_PROMPT_BUDGET}; + +/// What a cut block ends with. +const CUT: &str = "\n\n[...truncated for OS command line limit...]"; + +fn budget(prompt: &str, context: &[String]) -> (String, String, Vec) { + let dir = tempfile::tempdir().expect("dir"); + let (p, c) = budget_for_spawn(prompt, context, dir.path()).expect("budgeted"); + let spilled = std::fs::read_dir(dir.path().join(crate::hooks::memory::CONTEXT)) + .map(|entries| { + entries + .flatten() + .map(|e| e.file_name().to_string_lossy().into_owned()) + .collect() + }) + .unwrap_or_default(); + (p, c, spilled) +} + +fn blocks(list: &[&str]) -> Vec { + list.iter().map(|b| (*b).to_string()).collect() +} + +#[test] +fn nothing_at_all_is_nothing() { + assert_eq!(budget("", &[]), (String::new(), String::new(), Vec::new())); +} + +/// Under the limit every block is joined as given — blank and padded ones +/// too: only an over-limit payload is trimmed. +#[test] +fn under_the_limit_everything_is_joined_untouched() { + let (p, c, files) = budget("p", &blocks(&["a", " ", " b \n"])); + assert_eq!(p, "p"); + assert_eq!(c, "a\n\n \n\n b \n"); + assert!(files.is_empty()); + + let prompt = "p".repeat(MAX - 10); + let context = blocks(&["c".repeat(10).as_str()]); + let (p, c, files) = budget(&prompt, &context); + assert_eq!((p.len(), c.as_str()), (MAX - 10, "cccccccccc")); + assert!(files.is_empty(), "exactly at the limit is under it"); +} + +/// One byte over: a single high-priority block is cut to the budget less +/// 80, and marked. +#[test] +fn one_byte_over_cuts_the_block_and_marks_it() { + let block = format!("{}", "g".repeat(MAX - 8)); + let (p, c, files) = budget("p", std::slice::from_ref(&block)); + assert_eq!(p, "p"); + assert_eq!(c, format!("{}{CUT}", &block[..MAX - 81])); + assert!(files.is_empty()); +} + +/// High-priority blocks go first whatever their place; blocks are trimmed and +/// blank ones dropped; the low block that does not fit is cut to what is +/// left less 80. +#[test] +fn high_priority_blocks_go_first_and_low_ones_are_cut() { + let big = "z".repeat(MAX); + let context = blocks(&[" low one \n", " ", "r", big.as_str()]); + let (p, c, _) = budget("p", &context); + assert_eq!(p, "p"); + let kept = "r\n\nlow one\n\n"; + let left = (MAX - 1) - (16 + 2) - (7 + 2); + assert_eq!(c, format!("{kept}{}{CUT}", "z".repeat(left - 80))); +} + +/// Every marker of a high-priority block, in any case. +#[test] +fn every_high_priority_marker_is_recognised() { + let highs = [ + "g", + "The owner's standing rules: 1", + "i", + "a", + "r", + "p", + "o", + "disallowedTools: Bash", + "STANDING RULES IN CAPS", + ]; + let low = "l".repeat(MAX); + let mut context = vec![low]; + context.extend(highs.iter().map(|h| (*h).to_string())); + let (_, c, _) = budget("p", &context); + let used: usize = highs.iter().map(|h| h.len() + 2).sum(); + let left = (MAX - 1) - used; + assert_eq!( + c, + format!("{}\n\n{}{CUT}", highs.join("\n\n"), "l".repeat(left - 80)) + ); +} + +/// A high block that had to be cut still leaves room counted after it, and +/// a small low block that fits there is kept. +#[test] +fn a_low_block_still_fits_after_a_cut_high_one() { + let high = format!("{}", "g".repeat(MAX)); + let context = vec!["tiny low".to_string(), high.clone()]; + let (_, c, _) = budget("p", &context); + assert_eq!(c, format!("{}{CUT}\n\ntiny low", &high[..MAX - 81])); +} + +/// A low block is cut only when MORE than 120 bytes are left. +#[test] +fn a_low_block_is_cut_only_past_120_left() { + let low = "l".repeat(500); + for (left, want_low) in [(120, None), (121, Some(41))] { + let high = format!("{}", "g".repeat(MAX - 3 - left - 8)); + let (_, c, _) = budget("p", &[high.clone(), low.clone()]); + let want = match want_low { + None => high.clone(), + Some(n) => format!("{high}\n\n{}{CUT}", "l".repeat(n)), + }; + assert_eq!(c, want, "left={left}"); + } +} + +/// A high block is cut only when MORE than 100 bytes are left; one that is +/// not cut is dropped, and the low blocks still get their turn. +#[test] +fn a_high_block_is_cut_only_past_100_left() { + let second = format!("{}", "a".repeat(500)); + for (left, want_second) in [(100, None), (101, Some(21))] { + let first = format!("{}", "g".repeat(MAX - 3 - left - 8)); + let context = vec![first.clone(), second.clone(), "x".to_string()]; + let (_, c, _) = budget("p", &context); + let want = match want_second { + None => format!("{first}\n\nx"), + Some(n) => format!("{first}\n\n{}{CUT}\n\nx", &second[..n]), + }; + assert_eq!(c, want, "left={left}"); + } +} + +/// The cut never splits a character. +#[test] +fn the_cut_lands_on_a_character_boundary() { + let block = format!("{}", "é".repeat(MAX)); + let (_, c, _) = budget("p", std::slice::from_ref(&block)); + let at = (0..=MAX - 81) + .rev() + .find(|&i| block.is_char_boundary(i)) + .expect("a boundary"); + assert_eq!(c, format!("{}{CUT}", &block[..at])); +} + +/// A prompt of exactly the prompt budget is sent whole, even over the limit, +/// and the context takes the rest. +#[test] +fn a_prompt_at_the_prompt_budget_is_not_spilled() { + let prompt = "q".repeat(MAX_PROMPT_BUDGET); + let context = vec!["c".repeat(MAX - MAX_PROMPT_BUDGET + 1)]; + let (p, c, files) = budget(&prompt, &context); + assert_eq!(p, prompt); + assert_eq!( + c, + format!("{}{CUT}", "c".repeat(MAX - MAX_PROMPT_BUDGET - 80)) + ); + assert!(files.is_empty()); +} + +/// One byte over the prompt budget, over the limit: the prompt goes to a +/// file named by its hash, the agent is told where in these exact words, and +/// a context that fits beside the notice is untouched. The same prompt is the +/// same file. +#[test] +fn an_over_budget_prompt_is_spilled_with_the_same_notice() { + let prompt = "q".repeat(MAX_PROMPT_BUDGET + 1); + let context = vec!["c".repeat(MAX - MAX_PROMPT_BUDGET)]; + let dir = tempfile::tempdir().expect("dir"); + let (p, c) = budget_for_spawn(&prompt, &context, dir.path()).expect("budgeted"); + assert_eq!(c, context[0]); + let folder = dir.path().join(crate::hooks::memory::CONTEXT); + let names: Vec = std::fs::read_dir(&folder) + .expect("the context folder") + .flatten() + .map(|e| e.file_name().to_string_lossy().into_owned()) + .collect(); + assert_eq!(names.len(), 1, "{names:?}"); + let name = &names[0]; + assert!( + name.len() == "task-".len() + 16 + ".md".len() + && name.starts_with("task-") + && name.ends_with(".md"), + "{name}" + ); + assert_eq!( + std::fs::read_to_string(folder.join(name)).expect("the file"), + prompt + ); + assert_eq!( + p, + format!( + "This task is {} bytes, more than a command line can carry, so the whole of it \ + is in the file `{}/{name}` in your working folder ({}). Read that file in \ + full, from its first line to its last, before doing anything else: it is the \ + task, and what it asks is what you do.", + prompt.len(), + crate::hooks::memory::CONTEXT, + folder.join(name).display() + ) + ); + let (again, _) = budget_for_spawn(&prompt, &context, dir.path()).expect("budgeted"); + assert_eq!(again, p, "the same prompt is the same file"); +} diff --git a/src/agent/codex.rs b/src/agent/codex.rs index 9253a65..ef239b7 100644 --- a/src/agent/codex.rs +++ b/src/agent/codex.rs @@ -1279,6 +1279,9 @@ fn to_usage(wire: &WireUsage) -> crate::runtime::usage::TokenUsage { // Tests // --------------------------------------------------------------------------- +#[cfg(test)] +mod pinned_tests; + #[cfg(test)] mod tests { use super::*; diff --git a/src/agent/codex/pinned_tests.rs b/src/agent/codex/pinned_tests.rs new file mode 100644 index 0000000..ec50677 --- /dev/null +++ b/src/agent/codex/pinned_tests.rs @@ -0,0 +1,935 @@ +//! Pins on what the codex backend does, taken from the code before it was +//! split into a module directory: what each `codex exec --json` line is read +//! as, the exact argv and environment each route builds, and the errors a +//! turn that cannot start reports. Every expectation below was produced by +//! the original `src/agent/codex.rs` and written down literally, so a split +//! that changes any of it fails here. + +use std::path::{Path, PathBuf}; + +use super::{CodexBackend, CodexTools, Reading, MODEL_ONLY_OVERRIDES}; +use crate::agent::{AgentBackend, AgentEvent, TurnOutcome}; + +// --------------------------------------------------------------------------- +// Reading: one line at a time +// --------------------------------------------------------------------------- + +/// One event, every field shown. +fn event(e: &AgentEvent) -> String { + match e { + AgentEvent::SessionStarted { session_id, model } => { + format!("session({session_id:?},{model:?})") + } + AgentEvent::Text(t) => format!("text({t:?})"), + AgentEvent::TextDelta(t) => format!("delta({t:?})"), + AgentEvent::ToolUse { id, name, input } => format!("use({id:?},{name:?},{input:?})"), + AgentEvent::ToolResult { + id, + output, + is_error, + } => format!("result({id:?},{is_error},{output:?})"), + other => format!("{other:?}"), + } +} + +fn outcome(o: Option<&TurnOutcome>) -> String { + o.map_or_else( + || "-".to_string(), + |o| { + format!( + "outcome({:?},{:?},{},{:?},{:?})", + o.session_id, o.stop_reason, o.is_error, o.detail, o.served_by + ) + }, + ) +} + +/// Everything a run of `lines` leaves behind: the events, the thread the +/// backend now holds, the turn's result and its cost. +fn read_all(lines: &[&str], model: Option<&str>, bridged: bool) -> String { + let mut thread = None; + let mut reading = Reading::new(&mut thread, model.map(str::to_string), bridged); + let events: Vec = lines + .iter() + .flat_map(|l| reading.line(l)) + .map(|e| event(&e)) + .collect(); + let (result, usage) = reading.finish(); + format!( + "[{}] thread={thread:?} {} usage({},{},{},{})", + events.join(" "), + outcome(result.as_ref()), + usage.input_tokens, + usage.output_tokens, + usage.cache_creation_input_tokens, + usage.cache_read_input_tokens + ) +} + +/// Real `codex exec --json` line shapes (0.145.0 to 0.163.0) and the broken +/// ones a stream can carry, by name. +const CORPUS: &[(&str, &str)] = &[ + ("thread", r#"{"type":"thread.started","thread_id":"th-1"}"#), + ("turn_started", r#"{"type":"turn.started"}"#), + ( + "start_cmd", + r#"{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","aggregated_output":"","exit_code":null,"status":"in_progress"}}"#, + ), + ( + "start_cmd_no_command", + r#"{"type":"item.started","item":{"id":"item_1","type":"command_execution"}}"#, + ), + ( + "start_mcp_elsewhere", + r#"{"type":"item.started","item":{"id":"item_2","type":"mcp_tool_call","server":"memory","tool":"recall","arguments":{"q":"x"},"result":null,"error":null,"status":"in_progress"}}"#, + ), + ( + "start_mcp_incode", + r#"{"type":"item.started","item":{"id":"item_3","type":"mcp_tool_call","server":"incode","tool":"Write","arguments":{"path":"a.txt"},"result":null,"error":null,"status":"in_progress"}}"#, + ), + ( + "start_mcp_no_arguments", + r#"{"type":"item.started","item":{"id":"item_4","type":"mcp_tool_call","server":"memory","tool":"recall"}}"#, + ), + ( + "start_mcp_no_tool", + r#"{"type":"item.started","item":{"id":"item_5","type":"mcp_tool_call","server":"memory"}}"#, + ), + ( + "start_message", + r#"{"type":"item.started","item":{"id":"item_6","type":"agent_message","text":"hi"}}"#, + ), + ( + "start_reasoning", + r#"{"type":"item.started","item":{"id":"item_7","type":"reasoning","text":"thinking"}}"#, + ), + ( + "done_message", + r#"{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"The package name is incord-code."}}"#, + ), + ( + "done_message_blank", + r#"{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":" \n "}}"#, + ), + ( + "done_message_no_text", + r#"{"type":"item.completed","item":{"id":"item_0","type":"agent_message"}}"#, + ), + ( + "done_cmd_ok", + r#"{"type":"item.completed","item":{"id":"item_5","type":"command_execution","command":"powershell.exe -Command Get-Location","aggregated_output":"C:\\Projects\\incord-code\n","exit_code":0,"status":"completed"}}"#, + ), + ( + "done_cmd_failed", + r#"{"type":"item.completed","item":{"id":"item_6","type":"command_execution","command":"false","aggregated_output":"oops","exit_code":1,"status":"failed"}}"#, + ), + ( + "done_cmd_bare", + r#"{"type":"item.completed","item":{"id":"item_7","type":"command_execution","command":"true"}}"#, + ), + ( + "done_cmd_no_command", + r#"{"type":"item.completed","item":{"id":"item_8","type":"command_execution","aggregated_output":"x","exit_code":2}}"#, + ), + ( + "done_mcp_texts", + r#"{"type":"item.completed","item":{"id":"item_1","type":"mcp_tool_call","server":"memory","tool":"watchman_lookup","arguments":{"task":"C:\\Projects\\incord-code"},"result":{"content":[{"type":"text","text":"one"},{"type":"image","data":"x"},{"type":"text","text":"two"}]},"error":null,"status":"completed"}}"#, + ), + ( + "done_mcp_structured", + r#"{"type":"item.completed","item":{"id":"item_2","type":"mcp_tool_call","server":"memory","tool":"t","arguments":{},"result":{"structured_content":{"n":1}},"error":null,"status":"completed"}}"#, + ), + ( + "done_mcp_empty_content", + r#"{"type":"item.completed","item":{"id":"item_3","type":"mcp_tool_call","server":"memory","tool":"t","arguments":null,"result":{"content":[]},"status":"completed"}}"#, + ), + ( + "done_mcp_error_string", + r#"{"type":"item.completed","item":{"id":"item_4","type":"mcp_tool_call","server":"memory","tool":"t","result":null,"error":"boom","status":"failed"}}"#, + ), + ( + "done_mcp_error_object", + r#"{"type":"item.completed","item":{"id":"item_5","type":"mcp_tool_call","server":"memory","tool":"t","result":null,"error":{"message":"tool call timed out"},"status":"failed"}}"#, + ), + ( + "done_mcp_error_nested", + r#"{"type":"item.completed","item":{"id":"item_6","type":"mcp_tool_call","server":"memory","tool":"t","error":{"error":{"message":"inner"},"message":"outer"}}}"#, + ), + ( + "done_mcp_error_unshaped", + r#"{"type":"item.completed","item":{"id":"item_7","type":"mcp_tool_call","server":"memory","tool":"t","error":{"code":5}}}"#, + ), + ( + "done_mcp_error_beside_result", + r#"{"type":"item.completed","item":{"id":"item_8","type":"mcp_tool_call","server":"memory","tool":"t","result":{"content":[{"type":"text","text":"partial"}]},"error":{"message":"late"},"status":"completed"}}"#, + ), + ( + "done_mcp_status_failed", + r#"{"type":"item.completed","item":{"id":"item_9","type":"mcp_tool_call","server":"memory","tool":"t","result":{"content":[{"type":"text","text":"denied"}]},"error":null,"status":"failed"}}"#, + ), + ( + "done_mcp_no_tool", + r#"{"type":"item.completed","item":{"id":"item_10","type":"mcp_tool_call","server":"memory","result":{"content":[{"type":"text","text":"x"}]}}}"#, + ), + ( + "done_mcp_incode", + r#"{"type":"item.completed","item":{"id":"item_1","type":"mcp_tool_call","server":"incode","tool":"Write","arguments":{"path":"a.txt","content":"x"},"result":{"content":[{"type":"text","text":"wrote a.txt"}],"structured_content":null},"error":null,"status":"completed"}}"#, + ), + ( + "done_mcp_incode_failed", + r#"{"type":"item.completed","item":{"id":"item_2","type":"mcp_tool_call","server":"incode","tool":"Write","result":null,"error":{"message":"refused"},"status":"failed"}}"#, + ), + ( + "done_cmd_server_incode", + r#"{"type":"item.completed","item":{"id":"item_3","type":"command_execution","server":"incode","command":"ls","exit_code":0}}"#, + ), + ( + "done_error_item", + r#"{"type":"item.completed","item":{"id":"item_11","type":"error","text":"stream hiccup"}}"#, + ), + ( + "done_error_item_no_text", + r#"{"type":"item.completed","item":{"id":"item_12","type":"error"}}"#, + ), + ( + "done_reasoning", + r#"{"type":"item.completed","item":{"id":"item_13","type":"reasoning","text":"**Thinking**"}}"#, + ), + ( + "done_file_change", + r#"{"type":"item.completed","item":{"id":"item_14","type":"file_change","changes":[{"path":"a.rs","kind":"update"}],"status":"completed"}}"#, + ), + ( + "done_todo_list", + r#"{"type":"item.completed","item":{"id":"item_15","type":"todo_list","items":[{"text":"a","completed":false}]}}"#, + ), + ( + "done_untyped_item", + r#"{"type":"item.completed","item":{"id":"item_16"}}"#, + ), + ("done_empty_item", r#"{"type":"item.completed","item":{}}"#), + ( + "turn_done_usage", + r#"{"type":"turn.completed","usage":{"input_tokens":122070,"cached_input_tokens":112128,"cache_write_input_tokens":100,"output_tokens":438,"reasoning_output_tokens":83}}"#, + ), + ( + "turn_done_partial_usage", + r#"{"type":"turn.completed","usage":{"input_tokens":3,"output_tokens":2}}"#, + ), + ("turn_done_no_usage", r#"{"type":"turn.completed"}"#), + ( + "turn_done_null_usage", + r#"{"type":"turn.completed","usage":null}"#, + ), + ( + "turn_failed_nested", + r#"{"type":"turn.failed","error":{"message":"{\"type\":\"error\",\"status\":400,\"error\":{\"type\":\"invalid_request_error\",\"message\":\"The 'bad-model' model is not supported.\"}}"}}"#, + ), + ( + "turn_failed_top_message", + r#"{"type":"turn.failed","error":{"message":"{\"message\":\"You've hit your usage limit.\"}"}}"#, + ), + ( + "turn_failed_plain", + r#"{"type":"turn.failed","error":{"message":"stream disconnected before completion"}}"#, + ), + ( + "turn_failed_empty_error", + r#"{"type":"turn.failed","error":{}}"#, + ), + ("turn_failed_no_error", r#"{"type":"turn.failed"}"#), + ( + "error_plain", + r#"{"type":"error","message":"Reconnecting... 1/5"}"#, + ), + ( + "error_nested", + r#"{"type":"error","message":"{\"error\":{\"message\":\"Unauthorized\"}}"}"#, + ), + ( + "error_json_not_shaped", + r#"{"type":"error","message":"[1,2]"}"#, + ), + ("error_no_message", r#"{"type":"error"}"#), + ( + "unknown_type", + r#"{"type":"session.configured","model":"gpt-5.5"}"#, + ), + ("not_json", "Reading additional input from stdin..."), + ("empty", ""), + ("untyped_json", r#"{"thread_id":"th-x"}"#), + ("thread_without_id", r#"{"type":"thread.started"}"#), + ("completed_without_item", r#"{"type":"item.completed"}"#), + ( + "wrong_field_type", + r#"{"type":"item.completed","item":{"id":"i","type":"command_execution","command":"ls","exit_code":"0"}}"#, + ), + ("json_array", r#"[{"type":"turn.started"}]"#), + ("numeric_type", r#"{"type":7}"#), + ("truncated", r#"{"type":"thread.started","thread_id":"th"#), +]; + +/// What each line of [`CORPUS`] is read as on codex's own tools, by a fresh +/// reading whose model is `gpt-5.5`. +const OWN: &[(&str, &str)] = &[ + ( + "thread", + "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") - usage(0,0,0,0)", + ), + ("turn_started", NOTHING), + ( + "start_cmd", + "[use(\"item_1\",\"Bash\",\"bash -lc ls\")] thread=None - usage(0,0,0,0)", + ), + ("start_cmd_no_command", NOTHING), + ( + "start_mcp_elsewhere", + "[use(\"item_2\",\"recall\",\"{\\\"q\\\":\\\"x\\\"}\")] thread=None - usage(0,0,0,0)", + ), + ( + "start_mcp_incode", + "[use(\"item_3\",\"Write\",\"{\\\"path\\\":\\\"a.txt\\\"}\")] thread=None - usage(0,0,0,0)", + ), + ( + "start_mcp_no_arguments", + "[use(\"item_4\",\"recall\",\"\")] thread=None - usage(0,0,0,0)", + ), + ("start_mcp_no_tool", NOTHING), + ("start_message", NOTHING), + ("start_reasoning", NOTHING), + ( + "done_message", + "[delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=None - usage(0,0,0,0)", + ), + ("done_message_blank", NOTHING), + ("done_message_no_text", NOTHING), + ( + "done_cmd_ok", + "[use(\"item_5\",\"Bash\",\"powershell.exe -Command Get-Location\") result(\"item_5\",false,\"C:\\\\Projects\\\\incord-code\\n\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_cmd_failed", + "[use(\"item_6\",\"Bash\",\"false\") result(\"item_6\",true,\"oops\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_cmd_bare", + "[use(\"item_7\",\"Bash\",\"true\") result(\"item_7\",false,\"\")] thread=None - usage(0,0,0,0)", + ), + ("done_cmd_no_command", NOTHING), + ( + "done_mcp_texts", + "[use(\"item_1\",\"watchman_lookup\",\"{\\\"task\\\":\\\"C:\\\\\\\\Projects\\\\\\\\incord-code\\\"}\") result(\"item_1\",false,\"one\\ntwo\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_structured", + "[use(\"item_2\",\"t\",\"{}\") result(\"item_2\",false,\"{\\\"structured_content\\\":{\\\"n\\\":1}}\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_empty_content", + "[use(\"item_3\",\"t\",\"\") result(\"item_3\",false,\"{\\\"content\\\":[]}\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_error_string", + "[use(\"item_4\",\"t\",\"\") result(\"item_4\",true,\"boom\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_error_object", + "[use(\"item_5\",\"t\",\"\") result(\"item_5\",true,\"tool call timed out\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_error_nested", + "[use(\"item_6\",\"t\",\"\") result(\"item_6\",true,\"inner\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_error_unshaped", + "[use(\"item_7\",\"t\",\"\") result(\"item_7\",true,\"{\\\"code\\\":5}\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_error_beside_result", + "[use(\"item_8\",\"t\",\"\") result(\"item_8\",true,\"partial\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_status_failed", + "[use(\"item_9\",\"t\",\"\") result(\"item_9\",true,\"denied\")] thread=None - usage(0,0,0,0)", + ), + ("done_mcp_no_tool", NOTHING), + ( + "done_mcp_incode", + "[use(\"item_1\",\"Write\",\"{\\\"path\\\":\\\"a.txt\\\",\\\"content\\\":\\\"x\\\"}\") result(\"item_1\",false,\"wrote a.txt\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_mcp_incode_failed", + "[use(\"item_2\",\"Write\",\"\") result(\"item_2\",true,\"refused\")] thread=None - usage(0,0,0,0)", + ), + ( + "done_cmd_server_incode", + "[use(\"item_3\",\"Bash\",\"ls\") result(\"item_3\",false,\"\")] thread=None - usage(0,0,0,0)", + ), + ("done_error_item", NOTHING), + ("done_error_item_no_text", NOTHING), + ("done_reasoning", NOTHING), + ("done_file_change", NOTHING), + ("done_todo_list", NOTHING), + ("done_untyped_item", NOTHING), + ("done_empty_item", NOTHING), + ( + "turn_done_usage", + "[] thread=None outcome(\"\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(122070,438,100,112128)", + ), + ( + "turn_done_partial_usage", + "[] thread=None outcome(\"\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(3,2,0,0)", + ), + ("turn_done_no_usage", SUCCEEDED), + ("turn_done_null_usage", SUCCEEDED), + ( + "turn_failed_nested", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"The 'bad-model' model is not supported.\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "turn_failed_top_message", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"You've hit your usage limit.\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "turn_failed_plain", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"stream disconnected before completion\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "turn_failed_empty_error", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "turn_failed_no_error", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"turn failed\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "error_plain", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"Reconnecting... 1/5\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "error_nested", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"Unauthorized\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "error_json_not_shaped", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"[1,2]\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "error_no_message", + "[] thread=None outcome(\"\",\"ERROR\",true,Some(\"codex error\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ("unknown_type", NOTHING), + ("not_json", NOTHING), + ("empty", NOTHING), + ("untyped_json", NOTHING), + ("thread_without_id", NOTHING), + ("completed_without_item", NOTHING), + ("wrong_field_type", NOTHING), + ("json_array", NOTHING), + ("numeric_type", NOTHING), + ("truncated", NOTHING), +]; + +/// A line that stands for nothing and changes nothing. +const NOTHING: &str = "[] thread=None - usage(0,0,0,0)"; + +/// A turn that completed and reported no usage. +const SUCCEEDED: &str = + "[] thread=None outcome(\"\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(0,0,0,0)"; + +/// The lines read differently when bridged: codex's record of a call to +/// incode's own server is not shown. Every other line reads as [`OWN`]. +const BRIDGED: &[(&str, &str)] = &[ + ("start_mcp_incode", NOTHING), + ("done_mcp_incode", NOTHING), + ("done_mcp_incode_failed", NOTHING), + ("done_cmd_server_incode", NOTHING), +]; + +#[test] +fn every_corpus_line_reads_as_it_did_on_both_routes() { + let mut wrong = Vec::new(); + for (name, line) in CORPUS { + let own = read_all(&[line], Some("gpt-5.5"), false); + let bridged = read_all(&[line], Some("gpt-5.5"), true); + let want_own = OWN.iter().find(|(n, _)| n == name).map(|(_, w)| *w); + let want_bridged = BRIDGED + .iter() + .find(|(n, _)| n == name) + .map(|(_, w)| *w) + .or(want_own); + if want_own != Some(own.as_str()) { + wrong.push(format!(" ({name:?}, {own:?}),")); + } + if want_bridged != Some(bridged.as_str()) { + wrong.push(format!("BRIDGED ({name:?}, {bridged:?}),")); + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); + assert_eq!(OWN.len(), CORPUS.len(), "one reading per line"); +} + +/// Whole turns: the state a line leaves is what the next one reads. +#[test] +fn whole_turns_read_as_they_did() { + let line = |name: &str| { + CORPUS + .iter() + .find(|(n, _)| *n == name) + .map(|(_, l)| *l) + .expect("a corpus line") + }; + let turns: [(&str, &[&str], Option<&str>, bool); 7] = [ + ( + "own_turn", + &[ + "thread", + "turn_started", + "not_json", + "start_cmd", + "done_cmd_ok", + "start_mcp_elsewhere", + "done_mcp_texts", + "done_message", + "turn_done_usage", + ], + Some("gpt-5.5"), + false, + ), + ( + "bridged_turn", + &[ + "thread", + "turn_started", + "start_mcp_incode", + "done_mcp_incode", + "done_mcp_incode_failed", + "done_message", + "turn_done_partial_usage", + ], + Some("gpt-5.5"), + true, + ), + ( + "failed_after_thread", + &["thread", "turn_failed_nested"], + Some("gpt-5.5"), + false, + ), + ( + "error_overwrites_success", + &["thread", "turn_done_usage", "error_plain"], + Some("gpt-5.5"), + false, + ), + ( + "success_overwrites_error", + &["error_no_message", "thread", "turn_done_no_usage"], + Some("gpt-5.5"), + false, + ), + ( + "no_model", + &["thread", "done_message", "turn_done_partial_usage"], + None, + false, + ), + ( + "usage_kept_when_a_later_turn_has_none", + &["turn_done_usage", "turn_done_no_usage"], + None, + false, + ), + ]; + let want: &[(&str, &str)] = &[ + ( + "own_turn", + "[session(\"th-1\",\"gpt-5.5\") use(\"item_1\",\"Bash\",\"bash -lc ls\") use(\"item_5\",\"Bash\",\"powershell.exe -Command Get-Location\") result(\"item_5\",false,\"C:\\\\Projects\\\\incord-code\\n\") use(\"item_2\",\"recall\",\"{\\\"q\\\":\\\"x\\\"}\") use(\"item_1\",\"watchman_lookup\",\"{\\\"task\\\":\\\"C:\\\\\\\\Projects\\\\\\\\incord-code\\\"}\") result(\"item_1\",false,\"one\\ntwo\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(122070,438,100,112128)", + ), + ( + "bridged_turn", + "[session(\"th-1\",\"gpt-5.5\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(3,2,0,0)", + ), + ( + "failed_after_thread", + "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"ERROR\",true,Some(\"The 'bad-model' model is not supported.\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "error_overwrites_success", + "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"ERROR\",true,Some(\"Reconnecting... 1/5\"),[\"gpt-5.5\"]) usage(122070,438,100,112128)", + ), + ( + "success_overwrites_error", + "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "no_model", + "[session(\"th-1\",\"\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[]) usage(3,2,0,0)", + ), + ( + "usage_kept_when_a_later_turn_has_none", + "[] thread=None outcome(\"\",\"SUCCESS\",false,None,[]) usage(122070,438,100,112128)", + ), + ]; + let mut wrong = Vec::new(); + for (name, names, model, bridged) in turns { + let lines: Vec<&str> = names.iter().map(|n| line(n)).collect(); + let got = read_all(&lines, model, bridged); + if want.iter().find(|(n, _)| *n == name).map(|(_, w)| *w) != Some(got.as_str()) { + wrong.push(format!("({name:?}, {got:?}),")); + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} + +// --------------------------------------------------------------------------- +// argv and environment +// --------------------------------------------------------------------------- + +/// Everything a built command says about how it starts. +fn spawn(cmd: &std::process::Command) -> String { + let args: Vec = cmd + .get_args() + .map(|a| a.to_string_lossy().into_owned()) + .collect(); + let set: Vec<(String, String)> = cmd + .get_envs() + .filter_map(|(k, v)| { + Some(( + k.to_string_lossy().into_owned(), + v?.to_string_lossy().into_owned(), + )) + }) + .collect(); + format!( + "program={:?} dir={:?} args={args:?} env={set:?}", + cmd.get_program().to_string_lossy(), + cmd.get_current_dir() + .map(|d| d.to_string_lossy().into_owned()) + ) +} + +/// The parent session's variables are removed on every spawn, both routes. +fn removes_the_parent_session(cmd: &std::process::Command) -> bool { + [ + "CLAUDECODE", + "CLAUDE_CODE_ENTRYPOINT", + "CLAUDE_CODE_CHILD_SESSION", + "CLAUDE_CODE_MESSAGING_SOCKET", + "CLAUDE_CODE_MESSAGING_TOKEN", + "CLAUDE_SESSION_INGRESS_TOKEN_FILE", + ] + .iter() + .all(|name| cmd.get_envs().any(|(k, v)| k == *name && v.is_none())) +} + +/// A backend with every setting the own route reads. +fn configured(tools: CodexTools) -> CodexBackend { + let mut backend = CodexBackend::new(PathBuf::from("ws")) + .with_binary("codex-x") + .with_tools(tools) + .with_mcp_overrides(vec![ + "mcp_servers.team.command=\"incode\"".to_string(), + "mcp_servers.desktop.args=[\"--desktop\"]".to_string(), + ]); + backend.set_models(&["claude-x".to_string(), "gpt-5.5".to_string()]); + backend.set_permission_mode("acceptEdits"); + backend.set_extra_dirs(vec![PathBuf::from("/a"), PathBuf::from("/b")]); + backend.set_team_identity("review"); + backend.image_files = vec![PathBuf::from("one.png"), PathBuf::from("two.jpg")]; + backend.tool_server = Some(PathBuf::from("/opt/incode/bin/incode")); + backend +} + +#[test] +fn every_spawn_is_built_as_it_was() { + let mut cases: Vec<(String, String)> = Vec::new(); + let mut add = |name: &str, backend: &CodexBackend| { + let cmd = backend.command("the task"); + assert!(removes_the_parent_session(&cmd), "{name}"); + cases.push((name.to_string(), spawn(&cmd))); + }; + let mut bare = CodexBackend::new(PathBuf::from(".")); + add("bare", &bare); + bare.thread_id = Some("t-9".to_string()); + add("bare_resumed", &bare); + + let mut own = configured(CodexTools::Own); + add("own", &own); + own.thread_id = Some("t-1".to_string()); + add("own_resumed", &own); + for mode in [ + "plan", + "read-only", + "accept-edits", + "workspace-write", + "bypassPermissions", + ] { + let mut backend = CodexBackend::new(PathBuf::from(".")); + backend.set_permission_mode(mode); + add(mode, &backend); + } + + let mut bridged = configured(CodexTools::Incode); + add("bridged", &bridged); + bridged.thread_id = Some("t-2".to_string()); + add("bridged_resumed", &bridged); + + const AUTO: &str = "mcp_servers.memory.default_tools_approval_mode=\"auto\""; + const TEAM: &str = "mcp_servers.team.command=\"incode\""; + const DESKTOP: &str = "mcp_servers.desktop.args=[\"--desktop\"]"; + const LEAD: [&str; 4] = ["--skip-git-repo-check", "--json", "--disable", "hooks"]; + const IMAGES: [&str; 4] = ["--image", "one.png", "--image", "two.jpg"]; + const BYPASS: &str = "--dangerously-bypass-approvals-and-sandbox"; + let opt = bridged_overrides("/opt/incode/bin/incode"); + let plain = |tail: &[&str]| -> Vec { + let mut args = vec!["exec"]; + args.extend(LEAD); + args.extend(["-c", AUTO]); + args.extend(tail); + args.iter().map(|a| (*a).to_string()).collect() + }; + let mut want: Vec<(&str, String)> = vec![ + ( + "bare", + expect("codex", ".", &plain(&[BYPASS, "-C", ".", "the task"]), &[]), + ), + ( + "bare_resumed", + expect( + "codex", + ".", + &strings( + &[ + &["exec", "resume"][..], + &LEAD[..], + &[BYPASS, "-c", AUTO, "t-9", "the task"], + ] + .concat(), + ), + &[], + ), + ), + ( + "own", + expect( + "codex-x", + "ws", + &strings( + &[ + &["exec"][..], + &IMAGES[..], + &LEAD[..], + &["-c", AUTO, "-c", TEAM, "-c", DESKTOP], + &["-s", "workspace-write", "-m", "gpt-5.5"], + &["--add-dir", "/a", "--add-dir", "/b", "-C", "ws", "the task"], + ] + .concat(), + ), + &[("INCODE_TEAM_AS", "review")], + ), + ), + ( + "own_resumed", + expect( + "codex-x", + "ws", + &strings( + &[ + &["exec", "resume"][..], + &IMAGES[..], + &LEAD[..], + &[BYPASS, "-c", AUTO, "-c", TEAM, "-c", DESKTOP], + &["-m", "gpt-5.5", "t-1", "the task"], + ] + .concat(), + ), + &[("INCODE_TEAM_AS", "review")], + ), + ), + ]; + for (mode, flags) in [ + ("plan", &["-s", "read-only"][..]), + ("read-only", &["-s", "read-only"][..]), + ("accept-edits", &["-s", "workspace-write"][..]), + ("workspace-write", &["-s", "workspace-write"][..]), + ("bypassPermissions", &[BYPASS][..]), + ] { + let tail: Vec<&str> = flags + .iter() + .copied() + .chain(["-C", ".", "the task"]) + .collect(); + want.push((mode, expect("codex", ".", &plain(&tail), &[]))); + } + for (name, lead, tail) in [ + ("bridged", &["exec"][..], &["-C", "ws"][..]), + ("bridged_resumed", &["exec", "resume"][..], &["t-2"][..]), + ] { + let mut args = strings(&[lead, &IMAGES[..], &LEAD[..], &["--ignore-user-config"]].concat()); + args.extend(opt.iter().cloned()); + args.extend(strings( + &[&["-m", "gpt-5.5"][..], tail, &["the task"]].concat(), + )); + want.push((name, expect("codex-x", "ws", &args, &[]))); + } + assert_eq!(cases.len(), want.len()); + for ((name, got), (want_name, want)) in cases.iter().zip(&want) { + assert_eq!(name, want_name); + assert_eq!(got, want, "{name}"); + } +} + +/// `strs` as owned strings. +fn strings(strs: &[&str]) -> Vec { + strs.iter().map(|s| (*s).to_string()).collect() +} + +/// What [`spawn`] reports for a command built this way. +fn expect(program: &str, dir: &str, args: &[String], env: &[(&str, &str)]) -> String { + let env: Vec<(String, String)> = env + .iter() + .map(|(k, v)| ((*k).to_string(), (*v).to_string())) + .collect(); + format!( + "program={:?} dir={:?} args={args:?} env={env:?}", + program, + Some(dir) + ) +} + +/// The bridged route's `-c` pairs, written out, for a tool server at `exe` +/// as it appears in the TOML (backslashes already doubled). +fn bridged_overrides(exe: &str) -> Vec { + let values = [ + "features.shell_tool=false".to_string(), + "features.view_image=false".to_string(), + "web_search=\"disabled\"".to_string(), + "features.goals=false".to_string(), + "tools.experimental_request_user_input.enabled=false".to_string(), + "agents.enabled=false".to_string(), + "features.multi_agent=false".to_string(), + "features.apps=false".to_string(), + "features.plugins=false".to_string(), + "features.browser_use=false".to_string(), + "features.computer_use=false".to_string(), + "features.image_generation=false".to_string(), + "sandbox_mode=\"read-only\"".to_string(), + "approval_policy=\"never\"".to_string(), + format!("mcp_servers.incode.command=\"{exe}\""), + "mcp_servers.incode.args=[\"--tool-server\"]".to_string(), + "mcp_servers.incode.env_vars=[\"INCODE_TOOL_BRIDGE\",\"INCODE_TOOL_TOKEN\"]".to_string(), + "mcp_servers.incode.default_tools_approval_mode=\"approve\"".to_string(), + "mcp_servers.incode.required=true".to_string(), + "mcp_servers.incode.tool_timeout_sec=3600".to_string(), + "mcp_servers.incode.omit_tools_from=[\"deferred\"]".to_string(), + ]; + values + .into_iter() + .flat_map(|v| ["-c".to_string(), v]) + .collect() +} + +/// A Windows path with spaces, as the tool server, on the bridged command. +#[test] +fn the_bridged_command_escapes_a_windows_server_path() { + let mut backend = CodexBackend::new(PathBuf::from(".")) + .with_tools(CodexTools::Incode) + .with_binary("codex"); + let exe = Path::new(r"C:\Program Files\incode\incode.exe"); + let fresh = spawn(&backend.bridged_command("p", exe)); + backend.thread_id = Some("t".to_string()); + let resumed = spawn(&backend.bridged_command("p", exe)); + let overrides = bridged_overrides(r"C:\\Program Files\\incode\\incode.exe"); + for (got, lead, tail) in [ + (fresh, &["exec"][..], &["-C", ".", "p"][..]), + (resumed, &["exec", "resume"][..], &["t", "p"][..]), + ] { + let mut args = strings( + &[ + lead, + &["--skip-git-repo-check", "--json", "--disable", "hooks"], + &["--ignore-user-config"], + ] + .concat(), + ); + args.extend(overrides.iter().cloned()); + args.extend(strings(tail)); + assert_eq!(got, expect("codex", ".", &args, &[])); + } +} + +#[test] +fn the_model_only_overrides_are_the_fourteen() { + assert_eq!( + MODEL_ONLY_OVERRIDES, + [ + "features.shell_tool=false", + "features.view_image=false", + "web_search=\"disabled\"", + "features.goals=false", + "tools.experimental_request_user_input.enabled=false", + "agents.enabled=false", + "features.multi_agent=false", + "features.apps=false", + "features.plugins=false", + "features.browser_use=false", + "features.computer_use=false", + "features.image_generation=false", + "sandbox_mode=\"read-only\"", + "approval_policy=\"never\"", + ] + ); +} + +/// What each route says it was handed. +#[test] +fn the_mcp_config_each_route_reports_is_unchanged() { + assert_eq!(CodexBackend::new(PathBuf::from(".")).mcp_config(), None); + let own = configured(CodexTools::Own); + assert_eq!( + own.mcp_config().as_deref(), + Some("mcp_servers.team.command=\"incode\"\nmcp_servers.desktop.args=[\"--desktop\"]") + ); + let bridged = configured(CodexTools::Incode); + assert_eq!( + bridged.mcp_config().as_deref(), + Some( + "mcp_servers.incode.command=\"/opt/incode/bin/incode\"\n\ + mcp_servers.incode.args=[\"--tool-server\"]\n\ + mcp_servers.incode.env_vars=[\"INCODE_TOOL_BRIDGE\",\"INCODE_TOOL_TOKEN\"]\n\ + mcp_servers.incode.default_tools_approval_mode=\"approve\"\n\ + mcp_servers.incode.required=true\n\ + mcp_servers.incode.tool_timeout_sec=3600\n\ + mcp_servers.incode.omit_tools_from=[\"deferred\"]" + ) + ); +} + +// --------------------------------------------------------------------------- +// A turn that cannot start +// --------------------------------------------------------------------------- + +/// A binary that is not there fails the turn with the same words on both +/// routes, and the images it was handed are let go. +#[test] +fn a_missing_binary_fails_the_turn_with_the_same_words() { + for tools in [CodexTools::Own, CodexTools::Incode] { + let dir = tempfile::tempdir().expect("dir"); + let mut backend = CodexBackend::new(dir.path().to_path_buf()) + .with_binary("incode-no-such-codex-binary") + .with_tools(tools); + let mut seen = Vec::new(); + let err = backend + .run_turn("hi", &mut |e| seen.push(e.clone())) + .expect_err("nothing to start"); + assert!( + err.to_string() + .starts_with("could not start `incode-no-such-codex-binary`: "), + "{tools:?}: {err}" + ); + assert!(seen.is_empty(), "{tools:?}: {seen:?}"); + assert!(backend.image_files.is_empty(), "{tools:?}"); + assert_eq!(backend.session_id(), None, "{tools:?}"); + } +} diff --git a/src/agent/mod.rs b/src/agent/mod.rs index 1185b69..6883771 100644 --- a/src/agent/mod.rs +++ b/src/agent/mod.rs @@ -503,6 +503,9 @@ fn spill(prompt: &str, workspace: &std::path::Path) -> Result Date: Fri, 23 Oct 2026 17:35:16 -0600 Subject: [PATCH 2/3] codex pins: lift the turn and spawn tables out of the two long tests Same expectations, same assertions: the whole-turn cases and readings become consts, and the spawn pin builds its configurations and its two routes' expected argv in helpers, so no pin function passes 100 lines. The argv helper is renamed `reported`, which no other module defines. --- src/agent/codex/pinned_tests.rs | 270 ++++++++++++++++++-------------- 1 file changed, 149 insertions(+), 121 deletions(-) diff --git a/src/agent/codex/pinned_tests.rs b/src/agent/codex/pinned_tests.rs index ec50677..f10d8e3 100644 --- a/src/agent/codex/pinned_tests.rs +++ b/src/agent/codex/pinned_tests.rs @@ -469,6 +469,103 @@ fn every_corpus_line_reads_as_it_did_on_both_routes() { assert_eq!(OWN.len(), CORPUS.len(), "one reading per line"); } +/// Whole turns, by name: the [`CORPUS`] lines read in order, the model the +/// reading was started with, and whether it is bridged. +const TURNS: [(&str, &[&str], Option<&str>, bool); 7] = [ + ( + "own_turn", + &[ + "thread", + "turn_started", + "not_json", + "start_cmd", + "done_cmd_ok", + "start_mcp_elsewhere", + "done_mcp_texts", + "done_message", + "turn_done_usage", + ], + Some("gpt-5.5"), + false, + ), + ( + "bridged_turn", + &[ + "thread", + "turn_started", + "start_mcp_incode", + "done_mcp_incode", + "done_mcp_incode_failed", + "done_message", + "turn_done_partial_usage", + ], + Some("gpt-5.5"), + true, + ), + ( + "failed_after_thread", + &["thread", "turn_failed_nested"], + Some("gpt-5.5"), + false, + ), + ( + "error_overwrites_success", + &["thread", "turn_done_usage", "error_plain"], + Some("gpt-5.5"), + false, + ), + ( + "success_overwrites_error", + &["error_no_message", "thread", "turn_done_no_usage"], + Some("gpt-5.5"), + false, + ), + ( + "no_model", + &["thread", "done_message", "turn_done_partial_usage"], + None, + false, + ), + ( + "usage_kept_when_a_later_turn_has_none", + &["turn_done_usage", "turn_done_no_usage"], + None, + false, + ), +]; + +/// What each of [`TURNS`] leaves behind. +const TURN_READINGS: &[(&str, &str)] = &[ + ( + "own_turn", + "[session(\"th-1\",\"gpt-5.5\") use(\"item_1\",\"Bash\",\"bash -lc ls\") use(\"item_5\",\"Bash\",\"powershell.exe -Command Get-Location\") result(\"item_5\",false,\"C:\\\\Projects\\\\incord-code\\n\") use(\"item_2\",\"recall\",\"{\\\"q\\\":\\\"x\\\"}\") use(\"item_1\",\"watchman_lookup\",\"{\\\"task\\\":\\\"C:\\\\\\\\Projects\\\\\\\\incord-code\\\"}\") result(\"item_1\",false,\"one\\ntwo\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(122070,438,100,112128)", + ), + ( + "bridged_turn", + "[session(\"th-1\",\"gpt-5.5\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(3,2,0,0)", + ), + ( + "failed_after_thread", + "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"ERROR\",true,Some(\"The 'bad-model' model is not supported.\"),[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "error_overwrites_success", + "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"ERROR\",true,Some(\"Reconnecting... 1/5\"),[\"gpt-5.5\"]) usage(122070,438,100,112128)", + ), + ( + "success_overwrites_error", + "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(0,0,0,0)", + ), + ( + "no_model", + "[session(\"th-1\",\"\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[]) usage(3,2,0,0)", + ), + ( + "usage_kept_when_a_later_turn_has_none", + "[] thread=None outcome(\"\",\"SUCCESS\",false,None,[]) usage(122070,438,100,112128)", + ), +]; + /// Whole turns: the state a line leaves is what the next one reads. #[test] fn whole_turns_read_as_they_did() { @@ -479,103 +576,12 @@ fn whole_turns_read_as_they_did() { .map(|(_, l)| *l) .expect("a corpus line") }; - let turns: [(&str, &[&str], Option<&str>, bool); 7] = [ - ( - "own_turn", - &[ - "thread", - "turn_started", - "not_json", - "start_cmd", - "done_cmd_ok", - "start_mcp_elsewhere", - "done_mcp_texts", - "done_message", - "turn_done_usage", - ], - Some("gpt-5.5"), - false, - ), - ( - "bridged_turn", - &[ - "thread", - "turn_started", - "start_mcp_incode", - "done_mcp_incode", - "done_mcp_incode_failed", - "done_message", - "turn_done_partial_usage", - ], - Some("gpt-5.5"), - true, - ), - ( - "failed_after_thread", - &["thread", "turn_failed_nested"], - Some("gpt-5.5"), - false, - ), - ( - "error_overwrites_success", - &["thread", "turn_done_usage", "error_plain"], - Some("gpt-5.5"), - false, - ), - ( - "success_overwrites_error", - &["error_no_message", "thread", "turn_done_no_usage"], - Some("gpt-5.5"), - false, - ), - ( - "no_model", - &["thread", "done_message", "turn_done_partial_usage"], - None, - false, - ), - ( - "usage_kept_when_a_later_turn_has_none", - &["turn_done_usage", "turn_done_no_usage"], - None, - false, - ), - ]; - let want: &[(&str, &str)] = &[ - ( - "own_turn", - "[session(\"th-1\",\"gpt-5.5\") use(\"item_1\",\"Bash\",\"bash -lc ls\") use(\"item_5\",\"Bash\",\"powershell.exe -Command Get-Location\") result(\"item_5\",false,\"C:\\\\Projects\\\\incord-code\\n\") use(\"item_2\",\"recall\",\"{\\\"q\\\":\\\"x\\\"}\") use(\"item_1\",\"watchman_lookup\",\"{\\\"task\\\":\\\"C:\\\\\\\\Projects\\\\\\\\incord-code\\\"}\") result(\"item_1\",false,\"one\\ntwo\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(122070,438,100,112128)", - ), - ( - "bridged_turn", - "[session(\"th-1\",\"gpt-5.5\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(3,2,0,0)", - ), - ( - "failed_after_thread", - "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"ERROR\",true,Some(\"The 'bad-model' model is not supported.\"),[\"gpt-5.5\"]) usage(0,0,0,0)", - ), - ( - "error_overwrites_success", - "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"ERROR\",true,Some(\"Reconnecting... 1/5\"),[\"gpt-5.5\"]) usage(122070,438,100,112128)", - ), - ( - "success_overwrites_error", - "[session(\"th-1\",\"gpt-5.5\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[\"gpt-5.5\"]) usage(0,0,0,0)", - ), - ( - "no_model", - "[session(\"th-1\",\"\") delta(\"The package name is incord-code.\") text(\"The package name is incord-code.\")] thread=Some(\"th-1\") outcome(\"th-1\",\"SUCCESS\",false,None,[]) usage(3,2,0,0)", - ), - ( - "usage_kept_when_a_later_turn_has_none", - "[] thread=None outcome(\"\",\"SUCCESS\",false,None,[]) usage(122070,438,100,112128)", - ), - ]; let mut wrong = Vec::new(); - for (name, names, model, bridged) in turns { + for (name, names, model, bridged) in TURNS { let lines: Vec<&str> = names.iter().map(|n| line(n)).collect(); let got = read_all(&lines, model, bridged); - if want.iter().find(|(n, _)| *n == name).map(|(_, w)| *w) != Some(got.as_str()) { + let want = TURN_READINGS.iter().find(|(n, _)| *n == name); + if want.map(|(_, w)| *w) != Some(got.as_str()) { wrong.push(format!("({name:?}, {got:?}),")); } } @@ -641,8 +647,27 @@ fn configured(tools: CodexTools) -> CodexBackend { backend } +const AUTO: &str = "mcp_servers.memory.default_tools_approval_mode=\"auto\""; +const TEAM: &str = "mcp_servers.team.command=\"incode\""; +const DESKTOP: &str = "mcp_servers.desktop.args=[\"--desktop\"]"; +const LEAD: [&str; 4] = ["--skip-git-repo-check", "--json", "--disable", "hooks"]; +const IMAGES: [&str; 4] = ["--image", "one.png", "--image", "two.jpg"]; +const BYPASS: &str = "--dangerously-bypass-approvals-and-sandbox"; + #[test] fn every_spawn_is_built_as_it_was() { + let cases = built_spawns(); + let mut want = own_route_spawns(); + want.extend(bridged_route_spawns()); + assert_eq!(cases.len(), want.len()); + for ((name, got), (want_name, want)) in cases.iter().zip(&want) { + assert_eq!(name, want_name); + assert_eq!(got, want, "{name}"); + } +} + +/// What [`spawn`] reports for each configuration, by name, in order. +fn built_spawns() -> Vec<(String, String)> { let mut cases: Vec<(String, String)> = Vec::new(); let mut add = |name: &str, backend: &CodexBackend| { let cmd = backend.command("the task"); @@ -674,29 +699,29 @@ fn every_spawn_is_built_as_it_was() { add("bridged", &bridged); bridged.thread_id = Some("t-2".to_string()); add("bridged_resumed", &bridged); + cases +} - const AUTO: &str = "mcp_servers.memory.default_tools_approval_mode=\"auto\""; - const TEAM: &str = "mcp_servers.team.command=\"incode\""; - const DESKTOP: &str = "mcp_servers.desktop.args=[\"--desktop\"]"; - const LEAD: [&str; 4] = ["--skip-git-repo-check", "--json", "--disable", "hooks"]; - const IMAGES: [&str; 4] = ["--image", "one.png", "--image", "two.jpg"]; - const BYPASS: &str = "--dangerously-bypass-approvals-and-sandbox"; - let opt = bridged_overrides("/opt/incode/bin/incode"); - let plain = |tail: &[&str]| -> Vec { - let mut args = vec!["exec"]; - args.extend(LEAD); - args.extend(["-c", AUTO]); - args.extend(tail); - args.iter().map(|a| (*a).to_string()).collect() - }; +/// A fresh own-route argv with no settings, ending in `tail`. +fn plain(tail: &[&str]) -> Vec { + let mut args = vec!["exec"]; + args.extend(LEAD); + args.extend(["-c", AUTO]); + args.extend(tail); + args.iter().map(|a| (*a).to_string()).collect() +} + +/// What the original built on codex's own tools, for the configurations of +/// [`built_spawns`] before the bridged two. +fn own_route_spawns() -> Vec<(&'static str, String)> { let mut want: Vec<(&str, String)> = vec![ ( "bare", - expect("codex", ".", &plain(&[BYPASS, "-C", ".", "the task"]), &[]), + reported("codex", ".", &plain(&[BYPASS, "-C", ".", "the task"]), &[]), ), ( "bare_resumed", - expect( + reported( "codex", ".", &strings( @@ -712,7 +737,7 @@ fn every_spawn_is_built_as_it_was() { ), ( "own", - expect( + reported( "codex-x", "ws", &strings( @@ -731,7 +756,7 @@ fn every_spawn_is_built_as_it_was() { ), ( "own_resumed", - expect( + reported( "codex-x", "ws", &strings( @@ -760,8 +785,15 @@ fn every_spawn_is_built_as_it_was() { .copied() .chain(["-C", ".", "the task"]) .collect(); - want.push((mode, expect("codex", ".", &plain(&tail), &[]))); + want.push((mode, reported("codex", ".", &plain(&tail), &[]))); } + want +} + +/// What the original built on the bridged route, fresh and resumed. +fn bridged_route_spawns() -> Vec<(&'static str, String)> { + let opt = bridged_overrides("/opt/incode/bin/incode"); + let mut want = Vec::new(); for (name, lead, tail) in [ ("bridged", &["exec"][..], &["-C", "ws"][..]), ("bridged_resumed", &["exec", "resume"][..], &["t-2"][..]), @@ -771,13 +803,9 @@ fn every_spawn_is_built_as_it_was() { args.extend(strings( &[&["-m", "gpt-5.5"][..], tail, &["the task"]].concat(), )); - want.push((name, expect("codex-x", "ws", &args, &[]))); - } - assert_eq!(cases.len(), want.len()); - for ((name, got), (want_name, want)) in cases.iter().zip(&want) { - assert_eq!(name, want_name); - assert_eq!(got, want, "{name}"); + want.push((name, reported("codex-x", "ws", &args, &[]))); } + want } /// `strs` as owned strings. @@ -786,7 +814,7 @@ fn strings(strs: &[&str]) -> Vec { } /// What [`spawn`] reports for a command built this way. -fn expect(program: &str, dir: &str, args: &[String], env: &[(&str, &str)]) -> String { +fn reported(program: &str, dir: &str, args: &[String], env: &[(&str, &str)]) -> String { let env: Vec<(String, String)> = env .iter() .map(|(k, v)| ((*k).to_string(), (*v).to_string())) @@ -855,7 +883,7 @@ fn the_bridged_command_escapes_a_windows_server_path() { ); args.extend(overrides.iter().cloned()); args.extend(strings(tail)); - assert_eq!(got, expect("codex", ".", &args, &[])); + assert_eq!(got, reported("codex", ".", &args, &[])); } } From d4cf8caf592fc39380e7cc7a96423bfe3ebd9439 Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Fri, 23 Oct 2026 17:54:26 -0600 Subject: [PATCH 3/3] refactor(codex, agent): split the module, no behaviour change codex.rs becomes src/agent/codex/: mod.rs (the backend and its settings), argv.rs (both routes' commands, MODEL_ONLY_OVERRIDES, the bridge registration), bridged.rs (run_bridged), wire.rs (the --json wire types and Reading). Reading::line is one match that hands each variant to a helper; the long bridged-turn test is backed by setup and event helpers with the same assertions. Tests split into codex/tests.rs and codex/wire_tests.rs, declared #[cfg(test)]. agent/mod.rs keeps AgentEvent, TurnOutcome, the quota status and AgentError; the trait and its Box forwarding move to backend.rs, the handover classifiers to handover.rs, budget_for_spawn to spawn_budget.rs as named steps (by_priority, is_high_priority, Kept::take). Everything is re-exported at its old path. Docs that named codex.rs or agent/mod.rs now name the new files. The pins of the two commits before pass unchanged; MAX_UNWIRED stays 41. --- docs/COMPUTER_USE.md | 12 +- docs/incord-memory-integration.md | 8 +- src/agent/backend.rs | 552 ++++++++ src/agent/codex.rs | 2186 ----------------------------- src/agent/codex/argv.rs | 265 ++++ src/agent/codex/bridged.rs | 111 ++ src/agent/codex/mod.rs | 647 +++++++++ src/agent/codex/tests.rs | 730 ++++++++++ src/agent/codex/wire.rs | 396 ++++++ src/agent/codex/wire_tests.rs | 191 +++ src/agent/handover.rs | 230 +++ src/agent/mod.rs | 1053 +------------- src/agent/spawn_budget.rs | 299 ++++ src/desktop/mcp.rs | 2 +- src/hooks/memory.rs | 2 +- 15 files changed, 3451 insertions(+), 3233 deletions(-) create mode 100644 src/agent/backend.rs delete mode 100644 src/agent/codex.rs create mode 100644 src/agent/codex/argv.rs create mode 100644 src/agent/codex/bridged.rs create mode 100644 src/agent/codex/mod.rs create mode 100644 src/agent/codex/tests.rs create mode 100644 src/agent/codex/wire.rs create mode 100644 src/agent/codex/wire_tests.rs create mode 100644 src/agent/handover.rs create mode 100644 src/agent/spawn_budget.rs diff --git a/docs/COMPUTER_USE.md b/docs/COMPUTER_USE.md index 43857ab..6867b18 100644 --- a/docs/COMPUTER_USE.md +++ b/docs/COMPUTER_USE.md @@ -93,7 +93,7 @@ screenshot-reason-click loop. ## 2. Where it plugs in -The seam already exists and is already used. `src/agent/codex.rs:207` injects MCP server +The seam already exists and is already used. `src/agent/codex/argv.rs` (`command`) injects MCP server configuration into the delegated agent's process: ```rust @@ -124,7 +124,7 @@ spawn-flag call site: | Backend | MCP registration in the harness | Spawn flags it does pass | |---|---|---| -| `src/agent/codex.rs` | **Yes** — `:207` and `:218` inject `mcp_servers.memory.…` | | +| `src/agent/codex/argv.rs` | **Yes** — both spawn paths of `command` inject `mcp_servers.memory.…` | | | `src/agent/claude_code.rs` | **NONE** | `:894-935` — `--output-format`, `--verbose`, `--model`, `--include-partial-messages`, `--add-dir`, `--permission-mode`, `--append-system-prompt`, `--disallowedTools`, `--fallback-model`, `--resume`. No `--mcp-config`, no `--strict-mcp-config`. | | `src/agent/agy.rs` | **NONE** | `:232-254` — `--print`, `--output-format`, `--print-timeout`, `--model`, `--mode`, `--add-dir`, `--conversation`. | @@ -151,7 +151,7 @@ until the adapters are measured. Section 12 orders it that way. ### Approval mode is NOT copied from memory -`codex.rs:207` sets `default_tools_approval_mode="auto"` for the memory server. That is +`codex/argv.rs` (`command`) sets `default_tools_approval_mode="auto"` for the memory server. That is correct for memory — reads and writes to a local store are recoverable. It is **wrong** for desktop control and must not be copy-pasted. See section 7. @@ -514,7 +514,7 @@ that does. Computer use therefore has exactly two real gates: dead-man's switch (7b) live here, in `src/desktop/`, because here they cannot be configured away. 2. **The agent's MCP approval mode**, set when the harness registers the server - (section 2). This is where `codex.rs:207`'s `default_tools_approval_mode` sits, and it + (section 2). This is where `codex/argv.rs`'s `default_tools_approval_mode` sits, and it is why that line must NOT be copied verbatim: ```rust @@ -658,7 +658,7 @@ before it is pinned. **Platform crates go behind `[target.'cfg(windows)'.dependencies]` and friends**, so a Linux build never compiles the Windows accessibility stack. This is consistent with the crate as it already stands: 9 files already use `cfg(windows)` / `cfg(not(windows))` -(`src/tools/bash.rs`, `src/verify.rs`, `src/agent/mod.rs`, `src/agent/registry.rs`, +(`src/tools/bash.rs`, `src/verify.rs`, `src/agent/spawn_budget.rs`, `src/agent/registry.rs`, `src/hooks/mod.rs`, `src/runtime/lifecycle.rs`, `src/tools/bash_jobs.rs`, `src/tools/tool_status.rs`, `src/cli/render.rs`), so decision 3 is continuing existing practice rather than introducing it. @@ -787,7 +787,7 @@ from one working implementation is honest, one generalised from zero is a guess. turns "computer use exists" into "every agent has computer use". **Done, 2026-09-16, for the two backends that have a per-spawn flag.** The seam is - `AgentBackend::mcp_config()` (`src/agent/mod.rs`), defaulting to `None`: + `AgentBackend::mcp_config()` (`src/agent/backend.rs`), defaulting to `None`: | backend | spelling | measured from | | --- | --- | --- | diff --git a/docs/incord-memory-integration.md b/docs/incord-memory-integration.md index 87b745d..1efad41 100644 --- a/docs/incord-memory-integration.md +++ b/docs/incord-memory-integration.md @@ -31,7 +31,7 @@ they disagree with this table, this table is right. | — | Session id | incode's own (the ACP `sessionId`, or a v4 UUID), given to every backend, the toolbox and the model. | `AgentBackend::set_memory_session` | | — | Transcript | `.incode/transcripts/.jsonl` in the engine's shape, when an engine is present or the session is an ACP one; newest 200 kept. | `src/hooks/memory.rs` | | — | `/run` workers | Each worker (sequential, and each lane) is a memory session of its own. | `cli::run_memory` | -| — | Recording a session twice | claude: its settings and hooks are off. codex: `--disable hooks` (`b39a99e`). **agy** has no switch to skip its settings, so if its hooks file is installed the engine may still hear an agy session twice. | `src/agent/codex.rs` | +| — | Recording a session twice | claude: its settings and hooks are off. codex: `--disable hooks` (`b39a99e`). **agy** has no switch to skip its settings, so if its hooks file is installed the engine may still hear an agy session twice. | `src/agent/codex/argv.rs` | | — | Operator hooks | The operator's `hooks` (alias `desktop_hooks`) run around every Toolbox tool, before the engine. | `hooks::HookRunner` | ### Phase 8 (2026-09-26) — CLI parity and the OS sandbox @@ -44,7 +44,7 @@ they disagree with this table, this table is right. | OS sandbox for shell commands | **DONE (Windows + Linux live; macOS validated on a Mac)** — `src/sandbox`. `admin.json` `sandbox: off\|workspace-write\|read-only` (env `INCODE_SANDBOX`), tied to the permission mode by default. Linux: Landlock (`--sandbox-exec` helper). macOS: `sandbox-exec` Seatbelt profile. Windows: a write-restricted token for **read-only** (measured: writes denied inside and outside the workspace, reads and `NUL` work); **workspace-write left OFF** on Windows with the reason stated — see `docs/ARCHITECTURE.md`. Network not restricted on any OS; reported, not pretended. | | Operator hooks on every tool | **DONE** — `hooks::HookRunner` now runs the operator's `admin.json` `desktop_hooks` (alias `hooks`) pre- and post-tool for EVERY Toolbox tool, in `Toolbox::run_call` (exit 2 denies; stdin piped with the event JSON, bounded 10 s). The desktop's own executor still runs them for the desktop tools, so they are not doubled. | | `/run` workers as memory sessions | **DONE** — `cli::run_memory::Remembered` makes each ledger worker (sequential and each lane) a memory session of its own: `session-start`, a `capture` per task, `session-end`, under its own id, with its agents' calls filed under it. A carry-on answer is recorded, not followed (the task's check decides). | -| codex hooks off | **DONE** — `codex exec`/`exec resume` now carry `--disable hooks` (`src/agent/codex.rs`), so codex does not fire its own `~/.codex/hooks.json` and record a session incode already records. Proven live on codex 0.145.0 and 0.153.4 (probe hooks file, trust bypassed): hooks on recorded `session-start`/`user-prompt`, `--disable hooks` recorded nothing. | +| codex hooks off | **DONE** — `codex exec`/`exec resume` now carry `--disable hooks` (`src/agent/codex/argv.rs`), so codex does not fire its own `~/.codex/hooks.json` and record a session incode already records. Proven live on codex 0.145.0 and 0.153.4 (probe hooks file, trust bypassed): hooks on recorded `session-start`/`user-prompt`, `--disable hooks` recorded nothing. | | `--thinking-display` fallback | **DONE** — the claude backend drops `--thinking-display summarized` and retries the turn once if the CLI rejects it with "unknown option" naming the flag, and remembers that for the session (`agent::claude_code`). Tested with a fake CLI that rejects the flag. | | `run_on_compact` | Allowlisted honestly in `wiring.rs` `DELIBERATELY_UNWIRED` with the reason: incode never compacts (the model CLI compacts inside its own process); the claude stream's `compact_boundary` frame is where it would wire once measured. | @@ -123,8 +123,8 @@ inherits whichever route that session uses. the CLI route, whether each feature works depends on the child CLI. Three facts about how incord-code starts the child limit that: -- **Nobody can type into the child.** Claude is started with `-p` (`src/agent/claude_code.rs:931`) and `stdin(Stdio::null())` (`:1060`). Codex also gets `stdin(Stdio::null())` (`src/agent/codex.rs:270`). -- **Codex never asks for approval** when resuming, because it is started with `--dangerously-bypass-approvals-and-sandbox` (`src/agent/codex.rs:234`). +- **Nobody can type into the child.** Claude is started with `-p` (`src/agent/claude_code.rs:931`) and `stdin(Stdio::null())` (`:1060`). Codex also gets `stdin(Stdio::null())` (`src/agent/codex/argv.rs`, `command`). +- **Codex never asks for approval** when resuming, because it is started with `--dangerously-bypass-approvals-and-sandbox` (`src/agent/codex/argv.rs`, `command`). - **Nothing in incord-code cuts a 600 s hook short on this route.** - The Claude/Codex stream readers have no turn timeout. The only `recv_timeout` in `claude_code.rs` is test code (`:1872`). - Antigravity gets `--print-timeout 30m` (`src/agent/agy.rs:36`, `:241`). diff --git a/src/agent/backend.rs b/src/agent/backend.rs new file mode 100644 index 0000000..479e563 --- /dev/null +++ b/src/agent/backend.rs @@ -0,0 +1,552 @@ +//! The interface every agent route implements, and its forwarding through a +//! box. +//! +//! Wired to: every backend in [`crate::agent`] (`api`, `claude_code`, `agy`, +//! `codex`) and every caller that drives one — `agent::worker`, the CLI, the +//! run ledger and the ACP agent. + +use super::{moves_the_work, AgentError, AgentEvent, TurnOutcome}; + +/// An external agent this harness can route a turn to. +pub trait AgentBackend { + /// Stable identifier, e.g. `"claude-code"`. + fn id(&self) -> &str; + + /// Run one turn, calling `on_event` as events arrive. + /// + /// Implementations must continue an existing session where the underlying + /// agent supports it: re-establishing a session per turn re-pays the whole + /// prompt prefix. Measured against Claude Code 2.1.229, a fresh session + /// costs ~36k cache-creation tokens versus ~1.8k when resuming. + fn run_turn( + &mut self, + prompt: &str, + on_event: &mut dyn FnMut(&AgentEvent), + ) -> Result; + + /// The agent's current session id, once one exists. + fn session_id(&self) -> Option<&str>; + + /// Ask for a particular model on the next turn, with ordered fallbacks. + /// + /// Defaulted to doing nothing, because not every agent can be told which + /// model to use and one that cannot should not have to say so. An agent + /// that CAN is where routing pays: cheap work on a cheap model, without an + /// API credential anywhere. + /// + /// Called with the candidates in preference order. An empty slice means the + /// caller has no opinion and the agent's own default should stand. + fn set_models(&mut self, _candidates: &[String]) {} + + /// A model the operator named outright (`/model`, `-m`), rather than a + /// role table's candidates. Defaulted to the same rule as + /// [`Self::set_models`]; an API route takes any id its service offers. + fn choose_model(&mut self, model: &str) { + self.set_models(&[model.to_string()]); + } + + // The methods below exist because an interactive session needs them and not + // every backend can honour them. Each defaults to doing nothing rather than + // being required, so a backend implements only what it actually supports — + // and a caller reading the default gets "this route cannot do that", which + // is the truth, instead of a panic or a pretence. + + /// Also work in these directories, beyond the workspace root. + fn set_extra_dirs(&mut self, _dirs: Vec) {} + + /// The deny rules in force, for showing the operator. + /// + /// Empty when the backend protects paths some other way — the toolbox + /// checks the guards itself rather than handing rules to anyone. + fn deny_rules(&self) -> &[String] { + &[] + } + + /// The harness context this backend will carry into its next turn. + /// + /// On the trait so the invariant can be checked for ANY agent, not just the + /// one that happens to expose it. The context going missing is a measured + /// regression — twice — and it is invisible from the outside, so the test + /// that pins it must not be limited to a single backend. + fn system_context(&self) -> &[String] { + &[] + } + + /// The MCP server configuration this agent will be handed, if any. + /// + /// Exists for the same reason [`Self::system_context`] does: the flag is + /// assembled inside a spawn and is invisible from outside, so a test that + /// checks "did the harness actually hand this over" needs a way to look. + /// Defaults to `None`, which is the truth for every backend that has no + /// registration path yet — see `docs/COMPUTER_USE.md` section 2. + /// + /// Returns an owned string because a backend may register SEVERAL servers + /// and hold them as separate pieces. Borrowing forced codex to answer with + /// the first of its overrides, which read as the whole registration and + /// hid the second server completely. + fn mcp_config(&self) -> Option { + None + } + + /// Who this agent is on the team channel for the task about to run. + /// + /// # Why the environment and not the registration + /// + /// An agent CLI's MCP servers are configured ONCE, when the backend is + /// built, and the role changes every task. So the team server cannot be + /// told who it serves at registration time — it reads + /// [`crate::team_mcp::IDENTITY_ENV`] instead, and the server is a child of + /// the agent process, so setting the variable on the spawn is what reaches + /// it. + /// + /// Identity has to come from here rather than from the model, because the + /// harness RECORDS what is said on the channel: a name the agent could + /// choose would be a claim written down as a fact. + /// + /// Defaulted to nothing, for a backend that spawns no process. + fn set_team_identity(&mut self, _role: &str) {} + + /// This agent's OWN model ladder for a role, in preference order. + /// + /// # Why a backend supplies one at all + /// + /// The operator's ladder in `admin.json` holds concrete model ids, and ids + /// do not cross vendors: measured, forwarding one agent's `sonnet` to + /// another returned `model sonnet is not recognized` and failed every task + /// on arrival. Dropping the foreign name keeps the run alive but loses + /// routing entirely — every role then runs on the agent's default, which is + /// the expensive one. + /// + /// So a backend may answer for itself, in its own namespace. The operator's + /// ladder still wins wherever it names something this agent can serve; this + /// is the floor, not an override. + /// + /// Empty by default: an agent whose model names have not been measured must + /// not have a ladder invented for it. + fn ladder_for(&self, _role: &str) -> Vec { + Vec::new() + } + + /// What this backend can PREVENT for itself. + /// + /// Defaulted to [`crate::guards::Enforcement::NOTHING`] deliberately: a + /// backend whose enforcement has not been MEASURED must not be credited + /// with any, because the cost of guessing high is a guard the operator + /// believes in and the agent never applies. + fn enforces(&self) -> crate::guards::Enforcement { + crate::guards::Enforcement::NOTHING + } + + /// Whether a FAILED turn was the agent's own failure rather than the work's. + /// + /// # Why this is the backend's judgement and not a phrase list + /// + /// [`moves_the_work`] reads the failure MESSAGE, which is all a failure + /// that never produced a turn gives us. That list can only ever hold the + /// wordings someone has already seen, and a provider invents new ones: + /// MEASURED live, a busy model answered `Our servers are experiencing high + /// traffic right now, please try again in a minute.` — an unmistakable + /// agent-side failure that matched no needle, so both attempts ran on the + /// agent that had just said it could not serve them and the task was + /// abandoned with a standby idle. + /// + /// A backend whose protocol has a SEPARATE channel for its own machinery + /// knows the answer structurally and should say so, rather than waiting for + /// the message to be recognised. One that has no such channel keeps the + /// default and loses nothing. + fn agent_failed(&self, outcome: &TurnOutcome) -> bool { + moves_the_work(&outcome.failure()) + } + + /// Stop the turn when this token is tripped. + fn set_cancel(&mut self, _token: crate::runtime::cancel::CancelToken) {} + + /// Who to ask when a tool call needs a person's confirmation, or a + /// question needs the owner's answer. + /// + /// Defaulted to nothing: only a backend whose tools this harness runs + /// itself ([`crate::toolbox::Toolbox`]) has a moment at which to ask. + fn set_prompter(&mut self, _prompter: std::sync::Arc) {} + + /// Who to ask about a protected write when nobody is at the session — a + /// run's owner channel. Defaulted to nothing, as [`Self::set_prompter`] is. + fn set_owner(&mut self, _owner: std::sync::Arc) {} + + /// Record the protected writes a person allows into `record` — a + /// sub-agent's, into its parent's. Defaulted to nothing, as the rest are. + fn share_allowed_writes(&mut self, _record: std::sync::Arc) {} + + /// The API route this backend drives, when it drives one — what + /// `/models` asks for its service's model list. `None` for a CLI. + fn api_route(&self) -> Option<&crate::agent::api::Settings> { + None + } + + /// The session's own tool state — its background jobs and task list — + /// for a backend whose tools this harness runs, so every backend of one + /// session shares them. + /// + /// Defaulted to nothing: a backend whose tools are not incode's has no + /// jobs or list of incode's to share. + fn share_session_tools(&mut self, _state: std::sync::Arc) {} + + /// Whether every tool call this backend's model makes runs through + /// incode's [`crate::toolbox::Toolbox`] — so a restriction set on the + /// shared [`crate::toolbox::SessionTools`] binds it. + /// + /// Defaulted to no: an agent CLI that brings its own tools runs them + /// where incode cannot refuse one. + fn runs_tools_here(&self) -> bool { + false + } + + /// The model this backend was asked for, when it was asked for one. + fn model(&self) -> Option<&str> { + None + } + + /// Begin a new conversation, forgetting the current one. + fn clear_session(&mut self) {} + + /// Summarise the older part of the conversation into one message, now, + /// with the operator's `instructions` steering the summary (`/compact`). + /// + /// `None` when this backend does not hold its conversation — an agent CLI + /// compacts its own, inside its own process. `Some(Ok(_))` says what was + /// done; `Some(Err(_))` why it could not be. + fn compact(&mut self, _instructions: &str) -> Option> { + None + } + + /// How much the backend may do without asking. + fn set_permission_mode(&mut self, _mode: &str) {} + + /// Continue the conversation with this id. + fn set_session_id(&mut self, _session_id: &str) {} + + /// incode's id for the session, which the memory engine files everything + /// under — its pre-tool cards as well as the session's capture. + /// + /// Defaulted to nothing: only a backend whose tool calls this harness runs + /// itself sends the engine anything per call. + fn set_memory_session(&mut self, _session: &str) {} + + /// The session is over: tell the engine's edit check, so what this agent + /// claimed, read and announced is let go now rather than at its TTL. + /// + /// Defaulted to nothing: only a backend whose file tools this harness + /// runs itself announced anything. + fn end_code_edits(&mut self) {} + + /// Replace the harness context this backend carries into its turns. + /// + /// Defaulted to nothing for a backend that carries none. + fn set_system_context(&mut self, _blocks: Vec) {} + + /// The conversations subagents opened, as `(session id, what it was asked)`. + /// + /// Empty for a backend that does not delegate, and for one whose subagents + /// are its own business — an agent CLI spawns them inside a process this + /// harness cannot see into, so it has nothing to report and says so rather + /// than guessing. + fn children(&self) -> Vec<(String, String)> { + Vec::new() + } + + /// The tools incode itself runs for this agent's model, by name: the + /// toolbox's, for a backend whose model has no tools of its own. Empty + /// for an agent whose CLI still brings its own. A session traces them + /// when it starts, so which tools a model was handed is on the record — + /// including whether the desktop was among them. + fn offered_tools(&self) -> Vec { + Vec::new() + } + + /// Who is told what this backend's tools and workers do while they run + /// — see [`crate::watch`]. + /// + /// Defaulted to nothing: only a backend whose tools this harness runs + /// itself has calls, output and workers of incode's to report. + fn set_watch(&mut self, _watch: std::sync::Arc) {} + + /// Carry these pictures with the next turn's prompt, and only that turn. + /// + /// # Errors + /// + /// The agent cannot take a picture headless — the default, because no + /// route may be credited with a capability that was not measured on it. + /// The error names the agent, for the person who attached them. + fn attach_images(&mut self, images: Vec) -> Result<(), String> { + Err(format!( + "{} cannot take pictures headless, so {} picture(s) could not be sent; \ + describe them in words, or pick an agent that takes them", + self.id(), + images.len() + )) + } +} + +/// A boxed backend is a backend. +/// +/// The choice between routes is made at runtime — an installed CLI when there +/// is one, a model over an API when the operator configured one — so the call +/// sites hold one value either way. Without this they would each need to know +/// both types and branch around them. +impl AgentBackend for Box { + fn id(&self) -> &str { + (**self).id() + } + + /// Forwarded, so a boxed standby reports what the backend INSIDE it can + /// enforce. Falling through to the trait default here would credit every + /// boxed agent with enforcing nothing, and the gap report would be right by + /// accident rather than by measurement. + fn enforces(&self) -> crate::guards::Enforcement { + (**self).enforces() + } + + /// Forwarded for the same reason as [`Self::enforces`]: the run holds its + /// agents BOXED, so a default here would mean no backend's structural + /// judgement ever reached the failover loop — the one place it is read. + fn agent_failed(&self, outcome: &TurnOutcome) -> bool { + (**self).agent_failed(outcome) + } + + fn system_context(&self) -> &[String] { + (**self).system_context() + } + + fn ladder_for(&self, role: &str) -> Vec { + (**self).ladder_for(role) + } + + fn run_turn( + &mut self, + prompt: &str, + on_event: &mut dyn FnMut(&AgentEvent), + ) -> Result { + (**self).run_turn(prompt, on_event) + } + + fn session_id(&self) -> Option<&str> { + (**self).session_id() + } + + fn choose_model(&mut self, model: &str) { + (**self).choose_model(model); + } + + fn set_models(&mut self, candidates: &[String]) { + (**self).set_models(candidates); + } + + fn set_extra_dirs(&mut self, dirs: Vec) { + (**self).set_extra_dirs(dirs); + } + + fn set_team_identity(&mut self, role: &str) { + (**self).set_team_identity(role); + } + + fn deny_rules(&self) -> &[String] { + (**self).deny_rules() + } + + fn set_cancel(&mut self, token: crate::runtime::cancel::CancelToken) { + (**self).set_cancel(token); + } + + fn set_prompter(&mut self, prompter: std::sync::Arc) { + (**self).set_prompter(prompter); + } + + fn set_owner(&mut self, owner: std::sync::Arc) { + (**self).set_owner(owner); + } + + fn share_allowed_writes(&mut self, record: std::sync::Arc) { + (**self).share_allowed_writes(record); + } + + fn api_route(&self) -> Option<&crate::agent::api::Settings> { + (**self).api_route() + } + + fn share_session_tools(&mut self, state: std::sync::Arc) { + (**self).share_session_tools(state); + } + + fn runs_tools_here(&self) -> bool { + (**self).runs_tools_here() + } + + fn model(&self) -> Option<&str> { + (**self).model() + } + + fn clear_session(&mut self) { + (**self).clear_session(); + } + + fn compact(&mut self, instructions: &str) -> Option> { + (**self).compact(instructions) + } + + fn set_permission_mode(&mut self, mode: &str) { + (**self).set_permission_mode(mode); + } + + fn set_session_id(&mut self, session_id: &str) { + (**self).set_session_id(session_id); + } + + fn set_memory_session(&mut self, session: &str) { + (**self).set_memory_session(session); + } + + fn end_code_edits(&mut self) { + (**self).end_code_edits(); + } + + fn set_system_context(&mut self, blocks: Vec) { + (**self).set_system_context(blocks); + } + + fn children(&self) -> Vec<(String, String)> { + (**self).children() + } + + fn offered_tools(&self) -> Vec { + (**self).offered_tools() + } + + fn set_watch(&mut self, watch: std::sync::Arc) { + (**self).set_watch(watch); + } + + fn attach_images(&mut self, images: Vec) -> Result<(), String> { + (**self).attach_images(images) + } +} + +#[cfg(test)] +mod route_parity_tests { + use super::*; + use crate::guards::Enforcement; + + /// **Every route declares what it really enforces — none inherits by + /// accident.** + /// + /// The trait default is `NOTHING`, which is right for an unmeasured + /// backend and WRONG for two of the three that exist. The API route was + /// left on the default when the capability layer was added, so every task + /// on it would have reported two guards unenforced while enforcing both by + /// prevention. A default that is safe in general is not safe for a route + /// nobody re-checked, which is the whole point of pinning all three here. + #[test] + fn each_route_states_its_own_enforcement() { + let api = crate::agent::api::ApiBackend::new( + crate::agent::api::Settings { + endpoint: "http://localhost/x".to_string(), + key: String::new(), + model: "m".to_string(), + ..Default::default() + }, + std::path::Path::new("."), + "", + true, + ); + assert_eq!( + api.enforces(), + Enforcement::EVERYTHING, + "the API route enforces guards at the toolbox, before any write" + ); + + let cli = crate::agent::claude_code::ClaudeCodeBackend::new(std::path::PathBuf::new()); + assert_eq!( + cli.enforces(), + Enforcement::EVERYTHING, + "this CLI accepts a deny list and was measured honouring it" + ); + + let agy = crate::agent::agy::AgyBackend::new(std::path::PathBuf::new()); + assert_eq!( + agy.enforces(), + Enforcement::NOTHING, + "this CLI has no deny surface and ships sub-agent tools" + ); + + let codex = crate::agent::codex::CodexBackend::new(std::path::PathBuf::new()); + assert_eq!( + codex.enforces(), + Enforcement::NOTHING, + "this CLI has no deny surface; Sentinel detects writes" + ); + } + + /// **Every route reports the harness context it carries.** + /// + /// The API route held the context in a field and answered the empty + /// default, so anything checking "did the session's context reach the + /// agent?" would have concluded the API route drops it. The block COUNT + /// differs by route — this one is handed a joined string — but "it + /// arrived" must be answerable everywhere. + #[test] + fn each_route_reports_the_context_it_was_given() { + let block = "the paths the agent may not write"; + + let api = crate::agent::api::ApiBackend::new( + crate::agent::api::Settings { + endpoint: "http://localhost/x".to_string(), + key: String::new(), + model: "m".to_string(), + ..Default::default() + }, + std::path::Path::new("."), + block, + true, + ); + assert!( + api.system_context() + .iter() + .any(|b| b.contains("may not write")), + "the API route carries the context but reported none: {:?}", + api.system_context() + ); + + let cli = crate::agent::claude_code::ClaudeCodeBackend::new(std::path::PathBuf::new()) + .with_system_context(vec![block.to_string()]); + assert!(cli + .system_context() + .iter() + .any(|b| b.contains("may not write"))); + + let agy = crate::agent::agy::AgyBackend::new(std::path::PathBuf::new()) + .with_system_context(vec![block.to_string()]); + assert!(agy + .system_context() + .iter() + .any(|b| b.contains("may not write"))); + + let codex = crate::agent::codex::CodexBackend::new(std::path::PathBuf::new()) + .with_system_context(vec![block.to_string()]); + assert!(codex + .system_context() + .iter() + .any(|b| b.contains("may not write"))); + + // And a session with nothing to say sends nothing, on every route. + let quiet = crate::agent::api::ApiBackend::new( + crate::agent::api::Settings { + endpoint: "http://localhost/x".to_string(), + key: String::new(), + model: "m".to_string(), + ..Default::default() + }, + std::path::Path::new("."), + " ", + true, + ); + assert!(quiet.system_context().is_empty()); + } +} diff --git a/src/agent/codex.rs b/src/agent/codex.rs deleted file mode 100644 index ef239b7..0000000 --- a/src/agent/codex.rs +++ /dev/null @@ -1,2186 +0,0 @@ -//! OpenAI Codex (`codex`) agent backend, driven as a subprocess. -//! -//! # Where this came from -//! -//! [`crate::agent::registry`] listed `codex` as `Protocol::Unverified`. -//! This module implements that driver: every CLI flag and wire event below was -//! measured directly from real `codex exec --json` runs on Codex CLI (v0.145.0 / -//! v0.153.4). -//! -//! # How it is driven -//! -//! - Non-interactive turns are started with `codex exec [OPTIONS] [PROMPT]`. -//! - Resumed turns are continued with `codex exec resume [OPTIONS] [PROMPT]`. -//! - Output is read from stdout as newline-delimited JSON (`--json`). -//! - Standard input is closed (`Stdio::null()`) so Codex does not wait on interactive input. -//! - By default, headless turns bypass confirmation prompts with -//! `--dangerously-bypass-approvals-and-sandbox` so unattended runs do not hang waiting -//! for approvals on a terminal that has nobody typing into it. -//! -//! # Enforcement -//! -//! Like Antigravity, Codex CLI does not provide external flags to disallow specific tools -//! or protected file paths. Protection is derived from [`crate::guards::Sentinel`] which -//! detects changes after the turn. See [`CodexBackend::enforces`]. -//! -//! # Bridged: incode's tools instead of codex's ([`CodexTools::Incode`]) -//! -//! Opt-in (`codex_tools: "incode"` in admin.json, or `INCODE_CODEX_TOOLS=incode`), -//! because no turn with a REAL model has been run this way yet. When on, codex is -//! driven the way the Claude route is ([`crate::tool_bridge`]): its own tools are -//! switched off by config, it is handed ONE MCP server — `incode --tool-server` — -//! and every call the model makes comes back to this process and runs through the -//! toolbox. What each override does was read from codex's source at -//! `rust-v0.163.0`, checked against `rust-v0.153.4` and `rust-v0.145.0`, and -//! measured on the 0.163.0 binary against a stand-in Responses endpoint -//! (`model_providers..base_url`) that recorded what codex sent: -//! -//! - `gpt-5.5`, own tools (control): `exec_command, write_stdin, -//! request_user_input, apply_patch, view_image, get_goal, create_goal, -//! update_goal, tool_search, web_search`; -//! - `gpt-5.5`, with [`MODEL_ONLY_OVERRIDES`] and the bridge's registration: -//! `list_mcp_resources, list_mcp_resource_templates, read_mcp_resource, -//! apply_patch, mcp__incode{…}`; -//! - `gpt-5.6-terra`, a code-mode model: one `exec` tool (JavaScript in an -//! isolate with no file system or network, calling nested tools) whose nested -//! tools were `apply_patch`, the three resource readers and every -//! `mcp__incode__*`, plus `wait` — and, before `agents.enabled=false`, a -//! `collaboration` namespace (`spawn_agent`, …). -//! -//! Driven end to end through `incode -t` with that endpoint scripted to call -//! `mcp__incode` `Write`: codex started `incode --tool-server`, the call ran in -//! incode's toolbox (trace `tool Write (change)`), the file was written, the event -//! was incode's (`incode-1`), and the model was handed the toolbox's answer. -//! -//! `apply_patch` cannot be switched off: it is offered when the MODEL CATALOGUE -//! says so (`model_info.apply_patch_tool_type`, `core/src/tools/spec_plan.rs`), not -//! by any config key or feature. It is neutralised instead: with -//! `sandbox_mode="read-only"` and `approval_policy="never"`, codex's -//! `assess_patch_safety` (`core/src/safety.rs`) finds no writable root and REJECTS -//! the patch before it runs, on every platform, sandbox or not. The three -//! `*_mcp_resource*` tools only read resources the MCP servers offer, and the only -//! server is incode's. - -use std::io::{BufRead, BufReader}; -use std::path::{Path, PathBuf}; -use std::process::{Command, Stdio}; - -use serde::Deserialize; - -use super::{AgentBackend, AgentError, AgentEvent, TurnOutcome}; - -/// Whose tools a codex model runs, from admin.json's `codex_tools` or -/// [`CODEX_TOOLS_ENV`] — see [`crate::admin::AdminConfig::resolve_codex_tools`]. -#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] -pub enum CodexTools { - /// Codex's own (`exec_command`, `apply_patch`, …), watched afterwards by - /// the Sentinel. The default until a live turn has proved the other. - #[default] - Own, - /// incode's, through the tool bridge: codex is a model and nothing else. - Incode, -} - -impl CodexTools { - /// `own` or `incode`, ignoring case; anything else is no answer. - #[must_use] - pub fn parse(raw: &str) -> Option { - match raw.trim().to_ascii_lowercase().as_str() { - "own" => Some(Self::Own), - "incode" => Some(Self::Incode), - _ => None, - } - } - - #[must_use] - pub fn as_str(self) -> &'static str { - match self { - Self::Own => "own", - Self::Incode => "incode", - } - } -} - -/// The variable that wins over admin.json's `codex_tools`. -pub const CODEX_TOOLS_ENV: &str = "INCODE_CODEX_TOOLS"; - -/// Codex's own hooks file off, on both spawn paths: incode fires the memory -/// engine's lifecycle itself, and codex firing it too would record each -/// session twice. Proved on 0.145.0 and 0.153.4, `exec` and `exec resume`: -/// with a probe hooks file (trust bypassed), hooks on recorded `session-start` -/// and `user-prompt`; `--disable hooks` recorded nothing, and codex no longer -/// read `~/.codex/hooks.json`. -const HOOKS_OFF: [&str; 2] = ["--disable", "hooks"]; - -/// The `-c` overrides that make codex a model and nothing else, on the -/// bridged route. Each key is from codex's own config types (`ConfigToml`, -/// `ToolsToml`, `features/src/lib.rs`), present in 0.145.0, 0.153.4 and -/// 0.163.0 unless said; a key a version does not know is ignored by it, not -/// refused (measured on 0.163.0 with an invented feature name), so a typo -/// here would do nothing — which is why each was watched leave the tool list. -/// -/// - `features.shell_tool=false`: no `exec_command` / `write_stdin` / `shell`. -/// - `features.view_image=false`: no `view_image` (the key is 0.153+; 0.145 -/// has no switch). -/// - `web_search="disabled"`: no hosted `web_search`. -/// - `features.goals=false`: no `get_goal` / `create_goal` / `update_goal`. -/// - `tools.experimental_request_user_input.enabled=false`: no -/// `request_user_input` — incode asks the person itself. -/// - `agents.enabled=false`: no sub-agents of codex's own. Needed beside -/// `features.multi_agent=false`, which only covers models the catalogue -/// leaves to the features: measured on 0.163.0, `gpt-5.6-terra` (whose -/// catalogue entry names multi-agent v2) was still offered -/// `collaboration.spawn_agent` & co. with the feature off. `agents.enabled` -/// wins over the catalogue (`Config::multi_agent_version_override`). -/// - `features.multi_agent=false`, `features.apps=false`, -/// `features.plugins=false`, `features.browser_use=false`, -/// `features.computer_use=false`, `features.image_generation=false`: no -/// sub-agents, connectors, plugin tools, browser, desktop or image tools of -/// codex's own; incode's toolbox has its own sub-agent, browser and desktop. -/// - `sandbox_mode="read-only"`, `approval_policy="never"`: what is left of -/// codex's own reach writes nothing — `apply_patch` is rejected before it -/// runs (see the module notes) — and nothing waits on a person. -pub const MODEL_ONLY_OVERRIDES: [&str; 14] = [ - "features.shell_tool=false", - "features.view_image=false", - "web_search=\"disabled\"", - "features.goals=false", - "tools.experimental_request_user_input.enabled=false", - "agents.enabled=false", - "features.multi_agent=false", - "features.apps=false", - "features.plugins=false", - "features.browser_use=false", - "features.computer_use=false", - "features.image_generation=false", - "sandbox_mode=\"read-only\"", - "approval_policy=\"never\"", -]; - -/// Codex's user config (`$CODEX_HOME/config.toml`) is not read on the -/// bridged route — the counterpart of the Claude route's -/// `--setting-sources ""`: an MCP server the operator registered there would -/// be a tool incode cannot refuse. Auth still comes from `CODEX_HOME` -/// (`codex exec --help`). A global flag, taken by `exec resume` too. -const IGNORE_USER_CONFIG: &str = "--ignore-user-config"; - -/// The bridge's registration, as `-c` overrides: incode's tool server and -/// nothing else. -/// -/// - `env_vars`: codex starts a stdio MCP server with ONLY a short list of -/// variables (`HOME`, `PATH`, …; `rmcp-client/src/utils.rs` -/// `create_env_for_mcp_server`) plus the ones named here. Measured on -/// 0.163.0: a stand-in server received the two named and NOT a third set -/// beside them. The values never reach the argv. -/// - `default_tools_approval_mode="approve"`: the one mode in which codex never -/// asks before an MCP call (`requires_mcp_tool_approval_for_mode`); `auto` -/// asks for any tool not marked read-only, and with `approval_policy="never"` -/// that ask is a refusal. Whether a call may run is incode's decision. -/// - `required=true`: a server that fails to start fails the turn, rather than -/// the model running on with no tools. -/// - `tool_timeout_sec`: codex gives up on an MCP call after 300 s by default; -/// incode may still be asking the person, or running a long command. -/// - `omit_tools_from=["deferred"]`: the tools are listed to the model -/// directly. Without it codex hid them behind its `tool_search` (measured); -/// 0.145.0 has no such key, and its model finds them through `tool_search`. -fn bridge_registration(exe: &Path) -> Vec { - let key = crate::tool_bridge::CLIENT_KEY; - // TOML basic strings take backslash escapes: a Windows path must have its - // separators doubled — see `desktop::mcp::codex_config_overrides`. - let exe = exe.to_string_lossy().replace('\\', "\\\\"); - vec![ - format!("mcp_servers.{key}.command=\"{exe}\""), - format!( - "mcp_servers.{key}.args=[\"{}\"]", - crate::tool_bridge::SERVER_FLAG - ), - format!( - "mcp_servers.{key}.env_vars=[\"{}\",\"{}\"]", - crate::tool_bridge::ADDR_ENV, - crate::tool_bridge::TOKEN_ENV - ), - format!("mcp_servers.{key}.default_tools_approval_mode=\"approve\""), - format!("mcp_servers.{key}.required=true"), - format!( - "mcp_servers.{key}.tool_timeout_sec={}", - crate::tool_bridge::REPLY_BOUND_SECS - ), - format!("mcp_servers.{key}.omit_tools_from=[\"deferred\"]"), - ] -} - -// --------------------------------------------------------------------------- -// Wire types — measured from real Codex CLI runs -// --------------------------------------------------------------------------- - -/// One line of `codex exec --json`. -/// -/// Tagged on `type`. -#[derive(Debug, Deserialize)] -#[serde(tag = "type")] -enum Wire { - #[serde(rename = "thread.started")] - ThreadStarted { thread_id: String }, - #[serde(rename = "turn.started")] - TurnStarted, - #[serde(rename = "item.started")] - ItemStarted { item: WireItem }, - #[serde(rename = "item.completed")] - ItemCompleted { item: WireItem }, - #[serde(rename = "turn.completed")] - TurnCompleted { - #[serde(default)] - usage: Option, - }, - #[serde(rename = "turn.failed")] - TurnFailed { - #[serde(default)] - error: Option, - }, - #[serde(rename = "error")] - Error { - #[serde(default)] - message: Option, - }, - #[serde(other)] - Other, -} - -#[derive(Debug, Default, Deserialize)] -struct WireItem { - #[serde(default)] - id: String, - #[serde(rename = "type", default)] - item_type: String, - #[serde(default)] - text: Option, - #[serde(default)] - command: Option, - #[serde(default)] - aggregated_output: Option, - #[serde(default)] - exit_code: Option, - #[serde(default)] - server: Option, - #[serde(default)] - tool: Option, - #[serde(default)] - arguments: Option, - #[serde(default)] - result: Option, - #[serde(default)] - error: Option, - #[serde(default)] - status: Option, -} - -#[derive(Debug, Default, Deserialize)] -struct WireUsage { - #[serde(default)] - input_tokens: u32, - #[serde(default)] - cached_input_tokens: u32, - #[serde(default)] - cache_write_input_tokens: u32, - #[serde(default)] - output_tokens: u32, - #[allow(dead_code)] - #[serde(default)] - reasoning_output_tokens: u32, -} - -#[derive(Debug, Default, Deserialize)] -struct WireError { - #[serde(default)] - message: String, -} - -// --------------------------------------------------------------------------- -// Backend -// --------------------------------------------------------------------------- - -/// Drives OpenAI Codex CLI over its non-interactive interface. -pub struct CodexBackend { - binary: String, - workspace: PathBuf, - /// Thread ID for this conversation. Resumed with `codex exec resume `. - thread_id: Option, - model: Option, - extra_dirs: Vec, - /// Sandbox mode, e.g. "read-only" or "workspace-write". - sandbox: Option, - /// `-c key=value` overrides registering an MCP server, if the caller wants - /// this agent to have one. - /// - /// Built by [`crate::desktop::mcp::codex_config_overrides`]. Off unless - /// asked — handing every run a desktop it did not request would widen an - /// agent's reach as a side effect of a constructor. - mcp_overrides: Vec, - /// Who this agent speaks as on the team channel, for the task in hand. - team_identity: Option, - /// System context blocks prepended to the prompt. - system_context: Vec, - cancel: Option, - /// Pictures for the next turn's prompt only. - images: Vec, - /// Where this turn's pictures were written, while its command is built. - image_files: Vec, - /// Every tool the model has, run HERE — on the bridged route only - /// ([`CodexTools::Incode`]). `None` is codex running its own tools, and - /// then nothing below this line is used. - tools: Option, - /// How many calls the toolbox has run for this backend, so each gets an - /// id no earlier turn used. - calls: u64, - /// The binary codex is told to start as the tool server, when not this - /// one — a test's stand-in. `None` is this process's own binary. - tool_server: Option, -} - -/// A turn's pictures as files for `--image`, removed when the turn is over. -struct ImageFiles { - paths: Vec, -} - -impl ImageFiles { - /// Write each picture to a file of its own in the system's temporary - /// directory, named so no two turns share one. - fn write(images: &[crate::toolbox::Image]) -> Result { - let mut written = Self { paths: Vec::new() }; - for image in images { - let path = std::env::temp_dir().join(format!( - "incode-prompt-{}.{}", - uuid::Uuid::new_v4(), - image.format().word() - )); - std::fs::write(&path, image.bytes()) - .map_err(|e| format!("a picture could not be written for the agent: {e}"))?; - written.paths.push(path); - } - Ok(written) - } -} - -impl Drop for ImageFiles { - fn drop(&mut self) { - for path in &self.paths { - let _ = std::fs::remove_file(path); - } - } -} - -impl CodexBackend { - #[must_use] - pub fn new(workspace: PathBuf) -> Self { - Self { - binary: "codex".to_string(), - workspace, - thread_id: None, - model: None, - extra_dirs: Vec::new(), - sandbox: None, - mcp_overrides: Vec::new(), - team_identity: None, - system_context: Vec::new(), - cancel: None, - images: Vec::new(), - image_files: Vec::new(), - tools: None, - calls: 0, - tool_server: None, - } - } - - /// Run this model's tool calls in incode's toolbox, through the bridge, - /// with codex's own tools switched off — or not, for [`CodexTools::Own`]. - /// - /// Set before the toolbox builders below, which do nothing without it: - /// codex's own tools are not incode's to configure. - #[must_use] - pub fn with_tools(mut self, tools: CodexTools) -> Self { - self.tools = match tools { - // The filtered environment for the shell tool, as on the Claude - // route: a command the model chose must not inherit this - // process's credentials. No sub-agent CLI is named: the toolbox - // drives one as the Claude CLI, which codex is not. - CodexTools::Incode => Some(crate::toolbox::Toolbox::new(&self.workspace, true)), - CodexTools::Own => None, - }; - self - } - - /// The toolbox, when this model's tools are incode's. - fn toolbox(&mut self) -> Option<&mut crate::toolbox::Toolbox> { - self.tools.as_mut() - } - - /// Ask the memory engine before every tool call this model makes — on the - /// bridged route, where incode runs them. - #[must_use] - pub fn with_engine(mut self, engine: Option) -> Self { - self.tools = self.tools.map(|t| t.with_engine(engine)); - self - } - - /// Announce each file write to the engine's edit check — bridged only. - #[must_use] - pub fn with_code_edits(mut self, edits: Option) -> Self { - self.tools = self.tools.map(|t| t.with_code_edits(edits)); - self - } - - /// Run the operator's own pre- and post-tool commands around every call — - /// bridged only. See [`crate::hooks`]. - #[must_use] - pub fn with_operator_hooks(mut self, hooks: Option) -> Self { - self.tools = self.tools.map(|t| t.with_operator_hooks(hooks)); - self - } - - /// Confine this model's shell commands to `policy` — bridged only: codex's - /// own shell is off there, and incode's runs under incode's sandbox. - #[must_use] - pub fn with_sandbox(mut self, policy: crate::sandbox::SandboxPolicy) -> Self { - self.tools = self.tools.map(|t| t.with_sandbox(policy)); - self - } - - /// Offer the model the desktop tools, run through incode's toolbox — - /// bridged only; codex's own route registers the desktop server instead - /// ([`Self::with_mcp_overrides`]). - #[must_use] - pub fn with_desktop(mut self, setup: crate::toolbox::DesktopSetup) -> Self { - if let Some(tools) = self.toolbox() { - tools.enable_desktop(setup); - } - self - } - - /// Offer the model only `tools`, when given — a user-defined sub-agent's - /// allow-list, refused by the toolbox. Bridged only. - #[must_use] - pub fn with_tool_allowlist(mut self, allowed: Option>) -> Self { - if let (Some(tools), Some(allowed)) = (self.toolbox(), allowed) { - tools.restrict_tools(allowed); - } - self - } - - /// Have codex start `exe` as the tool server instead of this binary. - /// Unix only, as its one caller is (the bridged-turn test's fakes are - /// shell scripts). - #[cfg(all(test, unix))] - fn with_tool_server(mut self, exe: PathBuf) -> Self { - self.tool_server = Some(exe); - self - } - - /// Hand this agent an MCP server, as `-c key=value` overrides. - /// - /// Build them with [`crate::desktop::mcp::codex_config_overrides`] so the - /// TOML shape stays in one place. - #[must_use] - pub fn with_mcp_overrides(mut self, overrides: Vec) -> Self { - self.mcp_overrides = overrides; - self - } - - /// Carry the harness's context on every turn. - /// - /// Blank blocks are dropped so a project with no brief or findings sends - /// nothing rather than blank text. - #[must_use] - pub fn with_system_context(mut self, context: Vec) -> Self { - self.system_context = context - .into_iter() - .filter(|block| !block.trim().is_empty()) - .collect(); - self - } - - /// Override the binary command or path. - #[must_use] - pub fn with_binary(mut self, binary: impl Into) -> Self { - self.binary = binary.into(); - self - } - - /// Whether this agent recognises a model id as one of its own. - fn serves(&self, model: &str) -> bool { - const KNOWN_FAMILIES: [&str; 6] = ["gpt-", "o1", "o3", "o4", "chatgpt-", "codex-"]; - let id = model.trim().to_ascii_lowercase(); - KNOWN_FAMILIES.iter().any(|f| id.starts_with(f)) - } - - /// The prompt actually sent: the harness's context, then the task, budgeted for OS limits. - fn full_prompt(&self, prompt: &str) -> Result { - let (budgeted_prompt, budgeted_context) = - crate::agent::budget_for_spawn(prompt, &self.system_context, &self.workspace)?; - Ok(if budgeted_context.is_empty() { - budgeted_prompt - } else { - format!("{budgeted_context}\n\n{budgeted_prompt}") - }) - } - - /// The binary codex is told to start as the tool server. - fn server_exe(&self) -> PathBuf { - self.tool_server - .clone() - .or_else(|| std::env::current_exe().ok()) - .unwrap_or_else(|| PathBuf::from("incode")) - } - - /// The command for one turn, on whichever route this backend is on. - fn command(&self, prompt: &str) -> Command { - if self.tools.is_some() { - return self.bridged_command(prompt, &self.server_exe()); - } - let mut cmd = Command::new(&self.binary); - crate::agent::parent_session::detach_from_parent_session(&mut cmd); - cmd.current_dir(&self.workspace); - - // WHO THIS AGENT IS ON THE TEAM CHANNEL, for the task about to run. - // The team MCP server is a child of this process and reads it from - // here — the registration cannot carry it, because MCP servers are - // configured once and the role changes every task. - if let Some(role) = &self.team_identity { - cmd.env(crate::team_mcp::IDENTITY_ENV, role); - } - - // The pictures for this turn, as files — `codex exec -i, --image - // ...` (and the same on `exec resume`). Each goes FIRST, before - // any other flag, so the next flag ends the list: `--image` takes - // several values, and one placed before the prompt would take the - // prompt for a file name. - let images = |cmd: &mut Command| { - for file in &self.image_files { - cmd.arg("--image").arg(file); - } - }; - if let Some(tid) = &self.thread_id { - cmd.arg("exec"); - cmd.arg("resume"); - images(&mut cmd); - cmd.arg("--skip-git-repo-check"); - cmd.arg("--json"); - cmd.args(HOOKS_OFF); - cmd.arg("--dangerously-bypass-approvals-and-sandbox"); - cmd.arg("-c") - .arg("mcp_servers.memory.default_tools_approval_mode=\"auto\""); - for override_ in &self.mcp_overrides { - cmd.arg("-c").arg(override_); - } - if let Some(model) = &self.model { - cmd.arg("-m").arg(model); - } - cmd.arg(tid); - cmd.arg(prompt); - } else { - cmd.arg("exec"); - images(&mut cmd); - cmd.arg("--skip-git-repo-check"); - cmd.arg("--json"); - cmd.args(HOOKS_OFF); - cmd.arg("-c") - .arg("mcp_servers.memory.default_tools_approval_mode=\"auto\""); - for override_ in &self.mcp_overrides { - cmd.arg("-c").arg(override_); - } - if let Some(sandbox) = &self.sandbox { - cmd.arg("-s").arg(sandbox); - } else { - cmd.arg("--dangerously-bypass-approvals-and-sandbox"); - } - if let Some(model) = &self.model { - cmd.arg("-m").arg(model); - } - for dir in &self.extra_dirs { - cmd.arg("--add-dir").arg(dir); - } - cmd.arg("-C").arg(&self.workspace); - cmd.arg(prompt); - } - - // Close stdin so Codex does not wait on interactive input. - cmd.stdin(Stdio::null()); - cmd - } - - /// The command for one bridged turn: codex as a model only, with `exe` - /// started as its one MCP server. The bridge's address and token are - /// added by the caller, which holds the bridge. - /// - /// Not handed over, because incode decides them in its toolbox: the - /// permission mode (`-s`), the added roots (`--add-dir`), the bypass - /// flag, the team and desktop servers ([`Self::with_mcp_overrides`] — both - /// are toolbox tools here) and the memory server's approval override (the - /// server lives in the user config this route does not read). - fn bridged_command(&self, prompt: &str, exe: &Path) -> Command { - let mut cmd = Command::new(&self.binary); - crate::agent::parent_session::detach_from_parent_session(&mut cmd); - cmd.current_dir(&self.workspace); - cmd.arg("exec"); - if self.thread_id.is_some() { - cmd.arg("resume"); - } - // The pictures FIRST, as on the other route: `--image` takes several - // values, and the next flag is what ends the list. - for file in &self.image_files { - cmd.arg("--image").arg(file); - } - cmd.arg("--skip-git-repo-check"); - cmd.arg("--json"); - cmd.args(HOOKS_OFF); - cmd.arg(IGNORE_USER_CONFIG); - for override_ in MODEL_ONLY_OVERRIDES - .iter() - .map(|o| (*o).to_string()) - .chain(bridge_registration(exe)) - { - cmd.arg("-c").arg(override_); - } - if let Some(model) = &self.model { - cmd.arg("-m").arg(model); - } - match &self.thread_id { - // `exec resume` takes no `-C`: the thread carries its directory. - Some(tid) => { - cmd.arg(tid); - } - None => { - cmd.arg("-C").arg(&self.workspace); - } - } - cmd.arg(prompt); - // No team identity in the environment: the team channel's tools are - // the toolbox's on this route, and it is told who speaks. - cmd.stdin(Stdio::null()); - cmd - } -} - -impl AgentBackend for CodexBackend { - fn id(&self) -> &str { - "codex" - } - - /// On its own tools, neither half. Measured from the CLI surface: no - /// per-tool deny flag exists, so Sentinel detection covers file writes - /// after the fact. - /// - /// Bridged, both — by incode's toolbox, as on the Claude route: every - /// write the model can make is a toolbox call refused before it runs, and - /// its only sub-agent tool is incode's, which stops at its depth limit. - /// What codex keeps of its own cannot do either: `apply_patch` is rejected - /// unrun under read-only + never, and its sub-agent tools are off - /// (`features.multi_agent=false`) — both measured; see the module notes. - fn enforces(&self) -> crate::guards::Enforcement { - if self.tools.is_some() { - return crate::guards::Enforcement::EVERYTHING; - } - crate::guards::Enforcement::NOTHING - } - - fn agent_failed(&self, outcome: &TurnOutcome) -> bool { - outcome.is_error - || outcome.stop_reason.eq_ignore_ascii_case("ERROR") - || crate::agent::moves_the_work(&outcome.failure()) - } - - /// Bridged, the team channel's tools are the toolbox's, so the toolbox is - /// who speaks; otherwise the team server reads it from the spawn. - fn set_team_identity(&mut self, role: &str) { - match self.toolbox() { - Some(tools) => tools.set_team_identity(role), - None => self.team_identity = Some(role.to_string()), - } - } - - fn mcp_config(&self) -> Option { - // Bridged, the one server codex is handed is the bridge — the binary - // is the one each turn names, so this is what the next turn sends. - if self.tools.is_some() { - return Some(bridge_registration(&self.server_exe()).join("\n")); - } - // EVERY override, not the first. Returning one of them read as the - // whole registration, which was true while there was a single server - // and became a lie the moment there were two — the second was simply - // invisible to anything asking what this agent had been handed. - if self.mcp_overrides.is_empty() { - return None; - } - Some(self.mcp_overrides.join("\n")) - } - - // What follows reaches the toolbox, and so means something only on the - // bridged route. On codex's own tools each is the trait's default: there - // is no call of incode's to ask about, record or watch. - - /// Bridged: codex's own tools are switched off and every call comes back - /// through the bridge to this backend's toolbox. - fn runs_tools_here(&self) -> bool { - self.tools.is_some() - } - - fn set_prompter(&mut self, prompter: std::sync::Arc) { - if let Some(tools) = self.toolbox() { - tools.set_prompter(prompter); - } - } - - fn set_owner(&mut self, owner: std::sync::Arc) { - if let Some(tools) = self.toolbox() { - tools.set_owner(owner); - } - } - - fn share_allowed_writes(&mut self, record: std::sync::Arc) { - if let Some(tools) = self.toolbox() { - tools.share_allowed_writes(record); - } - } - - fn share_session_tools(&mut self, state: std::sync::Arc) { - if let Some(tools) = self.toolbox() { - tools.share_session(state); - } - } - - fn set_watch(&mut self, watch: std::sync::Arc) { - if let Some(tools) = self.toolbox() { - tools.set_watch(watch); - } - } - - /// The engine hears incode's session id with every call, not codex's - /// thread id: incode's is the one its session events carry too. - fn set_memory_session(&mut self, session: &str) { - if let Some(tools) = self.toolbox() { - tools.pin_session(session); - } - } - - fn end_code_edits(&mut self) { - if let Some(tools) = self.toolbox() { - tools.end_code_edits(); - } - } - - fn children(&self) -> Vec<(String, String)> { - self.tools.as_ref().map_or_else(Vec::new, |tools| { - tools - .children() - .into_iter() - .map(|c| (c.session, c.title)) - .collect() - }) - } - - fn offered_tools(&self) -> Vec { - self.tools - .as_ref() - .map_or_else(Vec::new, crate::toolbox::Toolbox::names) - } - - fn system_context(&self) -> &[String] { - &self.system_context - } - - fn set_system_context(&mut self, blocks: Vec) { - self.system_context = blocks - .into_iter() - .filter(|b| !b.trim().is_empty()) - .collect(); - } - - /// Model ladder in Codex / OpenAI namespace. - fn ladder_for(&self, role: &str) -> Vec { - let ids: &[&str] = match role { - "explore" | "grunt" => &["gpt-5.6-luna", "gpt-5.4-mini", "o4-mini", "o3-mini"], - "diagnose" | "review" | "plan" => &["gpt-5.6-terra", "gpt-5.5", "o3"], - "implement" | "frontend" => &["gpt-5.6-terra", "gpt-5.5", "o3"], - _ => &[], - }; - ids.iter().map(|id| (*id).to_string()).collect() - } - - fn session_id(&self) -> Option<&str> { - self.thread_id.as_deref() - } - - fn set_session_id(&mut self, session_id: &str) { - self.thread_id = Some(session_id.to_string()); - } - - fn clear_session(&mut self) { - self.thread_id = None; - } - - fn model(&self) -> Option<&str> { - self.model.as_deref() - } - - fn set_models(&mut self, candidates: &[String]) { - self.model = candidates.iter().find(|c| self.serves(c)).cloned(); - } - - /// Bridged, incode's toolbox does the writing, so it is the toolbox that - /// must reach the added roots — under the same guards. Codex is not told: - /// its own sandbox is read-only there. - fn set_extra_dirs(&mut self, dirs: Vec) { - if let Some(tools) = self.toolbox() { - tools.set_extra_dirs(dirs.clone()); - } - self.extra_dirs = dirs; - } - - /// Bridged, decided by incode's toolbox and never handed to codex: its - /// own sandbox stays read-only whatever the mode, because it runs nothing - /// that writes. A spelling nobody recognises lands on read-only. - fn set_permission_mode(&mut self, mode: &str) { - if let Some(tools) = self.toolbox() { - tools.set_permission_mode(crate::permissions::PermissionMode::from_agent_mode(mode)); - return; - } - self.sandbox = match mode { - "plan" | "read-only" => Some("read-only".to_string()), - "acceptEdits" | "accept-edits" | "workspace-write" => { - Some("workspace-write".to_string()) - } - _ => None, - }; - } - - fn set_cancel(&mut self, token: crate::runtime::cancel::CancelToken) { - if let Some(tools) = self.toolbox() { - tools.set_cancel(token.clone()); - } - self.cancel = Some(token); - } - - /// As files, with `--image` — in `codex exec --help` (0.153.4) for both - /// `exec` and `exec resume`. Not run live here: every live turn on this - /// machine answers with the account's usage limit. - fn attach_images(&mut self, images: Vec) -> Result<(), String> { - self.images = images; - Ok(()) - } - - fn run_turn( - &mut self, - prompt: &str, - on_event: &mut dyn FnMut(&AgentEvent), - ) -> Result { - let sent = self.full_prompt(prompt)?; - // Held to the end of the turn, then removed. - let pictures = - ImageFiles::write(&std::mem::take(&mut self.images)).map_err(AgentError::new)?; - self.image_files.clone_from(&pictures.paths); - if self.tools.is_some() { - // The turn's channel first: the command names the binary it was - // opened for, and a channel that cannot open starts nothing. - let turn = match crate::tool_bridge::Turn::open(self.cancel.clone()) { - Ok(turn) => turn, - Err(e) => { - self.image_files.clear(); - return Err(e); - } - }; - let exe = self.tool_server.clone().unwrap_or_else(|| turn.exe.clone()); - let command = self.bridged_command(&sent, &exe); - self.image_files.clear(); - return self.run_bridged(command, turn, on_event); - } - let mut command = self.command(&sent); - self.image_files.clear(); - crate::agent::process_tree::prepare(&mut command); - let mut child = command - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - .spawn() - .map_err(|e| AgentError::new(format!("could not start `{}`: {e}", self.binary)))?; - let tree = crate::agent::process_tree::Tree::adopt(&child); - - let stdout = child - .stdout - .take() - .ok_or_else(|| AgentError::new("the agent produced no output stream"))?; - - let stderr = crate::agent::stderr_tail::StderrTail::capture(child.stderr.take()); - - let mut reading = Reading::new(&mut self.thread_id, self.model.clone(), false); - - for line in BufReader::new(stdout).lines() { - if let Some(token) = &self.cancel { - if token.is_cancelled() { - tree.kill(&mut child); - return Err(AgentError::new("the turn was cancelled")); - } - } - let Ok(line) = line else { break }; - for event in reading.line(&line) { - on_event(&event); - } - } - let (outcome, usage) = reading.finish(); - - on_event(&AgentEvent::Usage { - input_tokens: usage.input_tokens, - output_tokens: usage.output_tokens, - cache_creation_tokens: usage.cache_creation_input_tokens, - cache_read_tokens: usage.cache_read_input_tokens, - }); - - let status = child - .wait() - .map_err(|e| AgentError::new(format!("the agent did not exit cleanly: {e}")))?; - - if let Some(outcome) = outcome { - Ok(outcome) - } else { - let stderr_output = stderr.finish(); - let detail = if stderr_output.is_empty() { - String::new() - } else { - format!(": {stderr_output}") - }; - Err(AgentError::new(format!( - "the agent produced no result line (exit {}){detail}", - status.code().unwrap_or(-1) - ))) - } - } -} - -impl CodexBackend { - /// One bridged turn: `command` spawned with the bridge's address and token - /// in its environment, its tool calls answered by the toolbox, its stream - /// read to the end — the Claude route's loop ([`crate::tool_bridge::drive`]) - /// over codex's lines. - fn run_bridged( - &mut self, - mut command: Command, - turn: crate::tool_bridge::Turn, - on_event: &mut dyn FnMut(&AgentEvent), - ) -> Result { - let crate::tool_bridge::Turn { - bridge, to, from, .. - } = turn; - // How the tool server finds this process: codex's environment, which - // it passes on to the server by the names `env_vars` lists — never - // its argv. - for (key, value) in bridge.env() { - command.env(key, value); - } - crate::agent::process_tree::prepare(&mut command); - let mut child = command - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - .spawn() - .map_err(|e| AgentError::new(format!("could not start `{}`: {e}", self.binary)))?; - let tree = crate::agent::process_tree::Tree::adopt(&child); - let stdout = child - .stdout - .take() - .ok_or_else(|| AgentError::new("the agent produced no output stream"))?; - let stderr = crate::agent::stderr_tail::StderrTail::capture(child.stderr.take()); - crate::tool_bridge::pump(BufReader::new(stdout), to); - - let Self { - tools, - calls, - thread_id, - model, - cancel, - .. - } = self; - let tools = tools - .as_mut() - .ok_or_else(|| AgentError::new("a bridged turn needs incode's toolbox"))?; - let mut reading = Reading::new(thread_id, model.clone(), true); - let driven = crate::tool_bridge::drive( - &from, - cancel.as_ref(), - tools, - calls, - on_event, - &mut |line, tools| { - let events = reading.line(&line); - for event in &events { - if let AgentEvent::SessionStarted { session_id, .. } = event { - // The engine files its cards under the conversation. - tools.set_session(session_id); - } - } - events - }, - ); - let (outcome, usage) = reading.finish(); - // Closed as soon as the loop is done: a call that arrives from here on - // is refused rather than left waiting on a loop that is gone. - drop(bridge); - if let Err(e) = driven { - // Whatever happened, codex must not outlive the turn — nor - // whatever it started. - tree.kill(&mut child); - return Err(e); - } - - on_event(&AgentEvent::Usage { - input_tokens: usage.input_tokens, - output_tokens: usage.output_tokens, - cache_creation_tokens: usage.cache_creation_input_tokens, - cache_read_tokens: usage.cache_read_input_tokens, - }); - let status = child - .wait() - .map_err(|e| AgentError::new(format!("the agent did not exit cleanly: {e}")))?; - outcome.ok_or_else(|| { - let stderr_output = stderr.finish(); - let detail = if stderr_output.is_empty() { - String::new() - } else { - format!(": {stderr_output}") - }; - AgentError::new(format!( - "the agent produced no result line (exit {}){detail}", - status.code().unwrap_or(-1) - )) - }) - } -} - -/// What one turn of `codex exec --json` has said so far, and what each line -/// means — the same reading on both routes. -struct Reading<'a> { - /// The backend's own: a thread that started is resumable even if the - /// turn is then stopped. - thread_id: &'a mut Option, - model: Option, - outcome: Option, - usage: crate::runtime::usage::TokenUsage, - /// Bridged: a call to incode's own server is shown by the bridge, as - /// incode ran it, under incode's id; codex's record of the same call is - /// not shown a second time. - bridged: bool, -} - -impl<'a> Reading<'a> { - fn new(thread_id: &'a mut Option, model: Option, bridged: bool) -> Self { - Self { - thread_id, - model, - outcome: None, - usage: crate::runtime::usage::TokenUsage::default(), - bridged, - } - } - - /// The turn's result, if it reported one, and what it cost. - fn finish(self) -> (Option, crate::runtime::usage::TokenUsage) { - (self.outcome, self.usage) - } - - /// Whether an item is codex's own echo of a call the bridge already showed. - fn shown_by_the_bridge(&self, item: &WireItem) -> bool { - self.bridged && item.server.as_deref() == Some(crate::tool_bridge::CLIENT_KEY) - } - - /// The events one line stands for. A line that is not one of codex's is - /// nothing. - fn line(&mut self, line: &str) -> Vec { - let Ok(wire) = serde_json::from_str::(line) else { - return Vec::new(); - }; - let mut events = Vec::new(); - match wire { - Wire::ThreadStarted { thread_id } => { - *self.thread_id = Some(thread_id.clone()); - events.push(AgentEvent::SessionStarted { - session_id: thread_id, - model: self.model.clone().unwrap_or_default(), - }); - } - Wire::TurnStarted => {} - Wire::ItemStarted { item } if self.shown_by_the_bridge(&item) => {} - Wire::ItemStarted { item } => match item.item_type.as_str() { - "command_execution" => { - if let Some(cmd) = item.command { - events.push(AgentEvent::ToolUse { - id: item.id, - name: "Bash".to_string(), - input: cmd, - }); - } - } - "mcp_tool_call" => { - if let Some(tool) = item.tool { - let input = item - .arguments - .as_ref() - .map(|a| a.to_string()) - .unwrap_or_default(); - events.push(AgentEvent::ToolUse { - id: item.id, - name: tool, - input, - }); - } - } - _ => {} - }, - Wire::ItemCompleted { item } if self.shown_by_the_bridge(&item) => {} - Wire::ItemCompleted { item } => match item.item_type.as_str() { - "agent_message" => { - if let Some(text) = item.text { - if !text.trim().is_empty() { - events.push(AgentEvent::TextDelta(text.clone())); - events.push(AgentEvent::Text(text)); - } - } - } - "command_execution" => { - if let Some(cmd) = item.command { - events.push(AgentEvent::ToolUse { - id: item.id.clone(), - name: "Bash".to_string(), - input: cmd, - }); - events.push(AgentEvent::ToolResult { - id: item.id, - output: item.aggregated_output.unwrap_or_default(), - is_error: item.exit_code.unwrap_or(0) != 0, - }); - } - } - "mcp_tool_call" => { - if let Some(tool) = item.tool { - let input = item - .arguments - .as_ref() - .map(|a| a.to_string()) - .unwrap_or_default(); - events.push(AgentEvent::ToolUse { - id: item.id.clone(), - name: tool, - input, - }); - let mut output = extract_mcp_output(&item.result); - if output.is_empty() { - if let Some(err) = &item.error { - output = err - .as_str() - .map(|s| s.to_string()) - .unwrap_or_else(|| parse_error_detail(&err.to_string())); - } - } - let is_error = - item.error.is_some() || item.status.as_deref() == Some("failed"); - events.push(AgentEvent::ToolResult { - id: item.id, - output, - is_error, - }); - } - } - "error" => { - if let Some(msg) = item.text { - crate::trace!("agent", "codex item error: {msg}"); - } - } - _ => {} - }, - Wire::TurnCompleted { usage: u } => { - if let Some(u) = &u { - self.usage = to_usage(u); - } - let sid = self.thread_id.clone().unwrap_or_default(); - self.outcome = Some(TurnOutcome { - session_id: sid, - stop_reason: "SUCCESS".to_string(), - is_error: false, - detail: None, - served_by: self.model.clone().into_iter().collect(), - }); - } - Wire::TurnFailed { error } => { - let err_msg = error - .map(|e| parse_error_detail(&e.message)) - .unwrap_or_else(|| "turn failed".to_string()); - let sid = self.thread_id.clone().unwrap_or_default(); - self.outcome = Some(TurnOutcome { - session_id: sid, - stop_reason: "ERROR".to_string(), - is_error: true, - detail: Some(err_msg), - served_by: self.model.clone().into_iter().collect(), - }); - } - Wire::Error { message } => { - let err_msg = message - .map(|m| parse_error_detail(&m)) - .unwrap_or_else(|| "codex error".to_string()); - let sid = self.thread_id.clone().unwrap_or_default(); - self.outcome = Some(TurnOutcome { - session_id: sid, - stop_reason: "ERROR".to_string(), - is_error: true, - detail: Some(err_msg), - served_by: self.model.clone().into_iter().collect(), - }); - } - Wire::Other => {} - } - events - } -} - -/// Extract readable text from MCP tool result JSON. -fn extract_mcp_output(res: &Option) -> String { - let Some(val) = res else { - return String::new(); - }; - if let Some(content) = val.get("content").and_then(|c| c.as_array()) { - let texts: Vec<&str> = content - .iter() - .filter_map(|item| item.get("text").and_then(|t| t.as_str())) - .collect(); - if !texts.is_empty() { - return texts.join("\n"); - } - } - val.to_string() -} - -/// Parse error message, unpacking nested JSON error objects if present. -fn parse_error_detail(raw: &str) -> String { - if let Ok(v) = serde_json::from_str::(raw) { - if let Some(inner) = v.pointer("/error/message").and_then(|m| m.as_str()) { - return inner.to_string(); - } - if let Some(msg) = v.get("message").and_then(|m| m.as_str()) { - return msg.to_string(); - } - } - raw.to_string() -} - -fn to_usage(wire: &WireUsage) -> crate::runtime::usage::TokenUsage { - crate::runtime::usage::TokenUsage { - input_tokens: wire.input_tokens, - output_tokens: wire.output_tokens, - cache_creation_input_tokens: wire.cache_write_input_tokens, - cache_read_input_tokens: wire.cached_input_tokens, - } -} - -// --------------------------------------------------------------------------- -// Tests -// --------------------------------------------------------------------------- - -#[cfg(test)] -mod pinned_tests; - -#[cfg(test)] -mod tests { - use super::*; - - /// Issue #3: launched from inside another agent session, a child that - /// inherits its variables reports that session as its own — on both the - /// fresh and the resumed spawn. - #[test] - fn the_cli_never_joins_the_session_that_launched_incode() { - let mut backend = CodexBackend::new(PathBuf::from(".")); - for resumed in [false, true] { - if resumed { - backend.thread_id = Some("t-1".to_string()); - } - let cmd = backend.command("p"); - assert!( - cmd.get_envs() - .any(|(k, v)| k == "CLAUDECODE" && v.is_none()), - "CLAUDECODE is inherited (resumed={resumed}), so the child joins the parent's session" - ); - } - } - - fn parse(line: &str) -> Wire { - serde_json::from_str(line).expect("a wire line") - } - - #[test] - fn the_thread_started_line_sets_session_id() { - let wire = parse( - r#"{"type":"thread.started","thread_id":"01a081c2-bdb1-7c71-a922-9a10bbb2ccae"}"#, - ); - match wire { - Wire::ThreadStarted { thread_id } => { - assert_eq!(thread_id, "01a081c2-bdb1-7c71-a922-9a10bbb2ccae"); - } - other => panic!("expected ThreadStarted: {other:?}"), - } - } - - #[test] - fn agent_message_item_is_parsed() { - let wire = parse( - r#"{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"The package name is incord-code."}}"#, - ); - match wire { - Wire::ItemCompleted { item } => { - assert_eq!(item.item_type, "agent_message"); - assert_eq!( - item.text.as_deref(), - Some("The package name is incord-code.") - ); - } - other => panic!("expected ItemCompleted: {other:?}"), - } - } - - #[test] - fn command_execution_item_is_parsed() { - let wire = parse( - r#"{"type":"item.completed","item":{"id":"item_5","type":"command_execution","command":"powershell.exe -Command Get-Location","aggregated_output":"C:\\Projects\\incord-code\n","exit_code":0,"status":"completed"}}"#, - ); - match wire { - Wire::ItemCompleted { item } => { - assert_eq!(item.item_type, "command_execution"); - assert_eq!( - item.command.as_deref(), - Some("powershell.exe -Command Get-Location") - ); - assert_eq!(item.exit_code, Some(0)); - } - other => panic!("expected ItemCompleted: {other:?}"), - } - } - - #[test] - fn mcp_tool_call_item_is_parsed() { - let wire = parse( - r#"{"type":"item.completed","item":{"id":"item_1","type":"mcp_tool_call","server":"memory","tool":"watchman_lookup","arguments":{"task":"C:\\Projects\\incord-code"},"result":{"content":[{"type":"text","text":"{\"hit\":false}"}]},"error":null,"status":"completed"}}"#, - ); - match wire { - Wire::ItemCompleted { item } => { - assert_eq!(item.item_type, "mcp_tool_call"); - assert_eq!(item.tool.as_deref(), Some("watchman_lookup")); - assert_eq!(extract_mcp_output(&item.result), "{\"hit\":false}"); - } - other => panic!("expected ItemCompleted: {other:?}"), - } - } - - #[test] - fn turn_completed_usage_is_parsed() { - let wire = parse( - r#"{"type":"turn.completed","usage":{"input_tokens":122070,"cached_input_tokens":112128,"cache_write_input_tokens":100,"output_tokens":438,"reasoning_output_tokens":83}}"#, - ); - match wire { - Wire::TurnCompleted { usage } => { - let u = to_usage(&usage.expect("usage")); - assert_eq!(u.input_tokens, 122070); - assert_eq!(u.cache_read_input_tokens, 112128); - assert_eq!(u.cache_creation_input_tokens, 100); - assert_eq!(u.output_tokens, 438); - } - other => panic!("expected TurnCompleted: {other:?}"), - } - } - - #[test] - fn turn_failed_unpacks_json_error() { - let wire = parse( - r#"{"type":"turn.failed","error":{"message":"{\"type\":\"error\",\"status\":400,\"error\":{\"type\":\"invalid_request_error\",\"message\":\"The 'bad-model' model is not supported.\"}}"}}"#, - ); - match wire { - Wire::TurnFailed { error } => { - let detail = parse_error_detail(&error.expect("error").message); - assert_eq!(detail, "The 'bad-model' model is not supported."); - } - other => panic!("expected TurnFailed: {other:?}"), - } - } - - #[test] - fn foreign_model_id_is_dropped() { - let mut backend = CodexBackend::new(PathBuf::from(".")); - backend.set_models(&[ - "claude-sonnet-4-6".to_string(), - "gemini-3.8-flash-high".to_string(), - ]); - assert_eq!(backend.model(), None); - - backend.set_models(&["claude-sonnet-4-6".to_string(), "gpt-5.6-terra".to_string()]); - assert_eq!(backend.model(), Some("gpt-5.6-terra")); - } - - #[test] - fn role_ladder_contains_supported_models() { - let backend = CodexBackend::new(PathBuf::from(".")); - for role in crate::roles::KNOWN_ROLES { - for id in backend.ladder_for(role) { - assert!( - backend.serves(&id), - "role {role} drew model {id} which codex cannot serve" - ); - } - } - assert_ne!( - backend.ladder_for("explore"), - backend.ladder_for("implement") - ); - } - - #[test] - fn harness_context_is_carried_in_prompt() { - let bare = CodexBackend::new(PathBuf::from(".")); - assert_eq!( - bare.full_prompt("fix the bug").expect("sent"), - "fix the bug" - ); - - let briefed = CodexBackend::new(PathBuf::from(".")) - .with_system_context(vec!["Guards: no writes outside src/".to_string()]); - let sent = briefed.full_prompt("fix the bug").expect("sent"); - assert!(sent.contains("Guards: no writes outside src/")); - assert!(sent.ends_with("fix the bug")); - } - - #[test] - fn enforces_claims_nothing() { - let backend = CodexBackend::new(PathBuf::from(".")); - assert_eq!(backend.enforces(), crate::guards::Enforcement::NOTHING); - } - - /// **A TURN'S PICTURES GO AS `--image` FILES, BEFORE ANY OTHER FLAG**, on - /// a new thread and on a resumed one, so the prompt is never read as one - /// more file; the files are removed when the turn's hold on them ends. - #[test] - fn pictures_go_first_as_image_files_and_are_removed_after() { - let picture = crate::toolbox::Image::from_base64( - "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC", - ) - .expect("a 1x1 png"); - let files = ImageFiles::write(std::slice::from_ref(&picture)).expect("written"); - let path = files.paths[0].clone(); - assert_eq!(std::fs::read(&path).expect("on disk"), picture.bytes()); - let mut backend = CodexBackend::new(PathBuf::from(".")); - backend.image_files.clone_from(&files.paths); - for resumed in [false, true] { - if resumed { - backend.thread_id = Some("t-1".to_string()); - } - let args: Vec = backend - .command("the prompt") - .get_args() - .map(|a| a.to_string_lossy().into_owned()) - .collect(); - let at = if resumed { 2 } else { 1 }; - assert_eq!(args[at], "--image", "{args:?}"); - assert_eq!(args[at + 1], path.to_string_lossy(), "{args:?}"); - assert!( - args[at + 2].starts_with("--"), - "the list is ended: {args:?}" - ); - assert_eq!(args.last().map(String::as_str), Some("the prompt")); - } - drop(files); - assert!(!path.exists(), "the picture outlived its turn"); - } - - #[test] - fn command_includes_mcp_auto_approval_config() { - let backend = CodexBackend::new(PathBuf::from(".")); - let cmd = backend.command("test prompt"); - let args: Vec = cmd.get_args().map(|a| a.to_os_string()).collect(); - let args_str: Vec = args - .iter() - .map(|a| a.to_string_lossy().to_string()) - .collect(); - assert!( - args_str - .windows(2) - .any(|w| w[0] == "-c" && w[1].contains("default_tools_approval_mode=\"auto\"")), - "codex command must include auto approval for memory MCP tools so calls are not cancelled" - ); - } - - /// **THE TEAM IDENTITY MUST REACH THE SPAWNED PROCESS'S ENVIRONMENT.** - /// - /// The team MCP server is a child of the agent and reads who it speaks - /// for from this variable. It cannot come from the MCP registration — - /// that is written once and the role changes every task — so if it does - /// not land on the spawn, every mid-turn message is filed as `unrouted` - /// and the channel stops being addressable. - #[test] - fn the_team_identity_is_set_on_the_spawn() { - let mut backend = CodexBackend::new(PathBuf::from(".")); - backend.set_team_identity("implement"); - - let cmd = backend.command("test prompt"); - let found = cmd - .get_envs() - .find(|(k, _)| *k == std::ffi::OsStr::new(crate::team_mcp::IDENTITY_ENV)); - - let (_, value) = found.expect("the identity never reached the environment"); - assert_eq!( - value.expect("a value").to_string_lossy(), - "implement", - "the agent would speak under the wrong name" - ); - - // And a backend nobody told stays silent rather than inventing one. - let plain = CodexBackend::new(PathBuf::from(".")); - assert!( - !plain - .command("p") - .get_envs() - .any(|(k, _)| k == std::ffi::OsStr::new(crate::team_mcp::IDENTITY_ENV)), - "an identity was invented for a task that had no role" - ); - } - - /// **THE DESKTOP MUST REACH ARGV, ON BOTH SPAWN PATHS.** - /// - /// `mcp_config()` is an accessor — it reads the field back and would keep - /// answering after the `-c` loops were deleted. What the spawned process - /// actually receives is argv, so that is what this asserts. Both paths, - /// because `command` builds a *different* argument list when resuming a - /// thread (line 218) than when starting fresh (line 234): wiring one and - /// forgetting the other is a desktop that works until the first resume. - #[test] - fn the_desktop_overrides_reach_argv_on_both_spawn_paths() { - let overrides = crate::desktop::mcp::codex_config_overrides( - std::path::Path::new(r"C:\Users\someone\incode.exe"), - Some(std::path::Path::new(r"C:\work\.incode\desktop.jsonl")), - crate::permissions::PermissionMode::WorkspaceWrite, - ); - - let argv = |backend: &CodexBackend| -> Vec { - backend - .command("test prompt") - .get_args() - .map(|a| a.to_string_lossy().to_string()) - .collect() - }; - let carries = |args: &[String]| { - args.windows(2) - .filter(|w| w[0] == "-c" && w[1].starts_with("mcp_servers.desktop.")) - .count() - }; - - let fresh = CodexBackend::new(PathBuf::from(".")).with_mcp_overrides(overrides.clone()); - assert_eq!( - carries(&argv(&fresh)), - overrides.len(), - "fresh spawn dropped the desktop: {:?}", - argv(&fresh) - ); - - let mut resumed = - CodexBackend::new(PathBuf::from(".")).with_mcp_overrides(overrides.clone()); - resumed.thread_id = Some("thread-abc".to_string()); - assert_eq!( - carries(&argv(&resumed)), - overrides.len(), - "resume spawn dropped the desktop: {:?}", - argv(&resumed) - ); - - // And without it, nothing: the flag is not unconditional. - let plain = CodexBackend::new(PathBuf::from(".")); - assert_eq!(carries(&argv(&plain)), 0); - } - - /// **CODEX'S OWN HOOKS ARE OFF ON BOTH SPAWN PATHS.** incode fires the - /// memory engine's lifecycle itself; codex loading its hooks file too - /// would record every session twice, under two ids. - #[test] - fn codex_is_started_with_its_own_hooks_off_on_both_paths() { - let off = |backend: &CodexBackend| { - let args: Vec = backend - .command("hi") - .get_args() - .map(|a| a.to_string_lossy().to_string()) - .collect(); - args.windows(2) - .any(|w| w[0] == "--disable" && w[1] == "hooks") - }; - let fresh = CodexBackend::new(PathBuf::from(".")); - assert!(off(&fresh)); - let mut resumed = CodexBackend::new(PathBuf::from(".")); - resumed.thread_id = Some("thread-abc".to_string()); - assert!(off(&resumed)); - for mut backend in [fresh, resumed] { - backend = backend.with_tools(CodexTools::Incode); - assert!(off(&backend), "bridged too"); - } - } - - // ----------------------------------------------------------------------- - // Bridged: codex as a model, incode's toolbox as its tools. - // ----------------------------------------------------------------------- - - fn args_of(cmd: &Command) -> Vec { - cmd.get_args() - .map(|a| a.to_string_lossy().into_owned()) - .collect() - } - - /// Every `-c` value on an argv. - fn overrides_in(args: &[String]) -> Vec { - args.windows(2) - .filter(|w| w[0] == "-c") - .map(|w| w[1].clone()) - .collect() - } - - /// **CODEX ON ITS OWN TOOLS IS STARTED EXACTLY AS BEFORE.** The whole argv, - /// both spawn paths, pinned: the bridged route must not leak a flag onto - /// the route that has run live. - #[test] - fn the_own_tools_argv_is_unchanged() { - let mut backend = CodexBackend::new(PathBuf::from(".")) - .with_mcp_overrides(vec!["mcp_servers.team.command=\"incode\"".to_string()]); - backend.set_models(&["gpt-5.5".to_string()]); - backend.set_permission_mode("plan"); - backend.set_extra_dirs(vec![PathBuf::from("/more")]); - let auto = "mcp_servers.memory.default_tools_approval_mode=\"auto\""; - let team = "mcp_servers.team.command=\"incode\""; - assert_eq!( - args_of(&backend.command("the task")), - [ - "exec", - "--skip-git-repo-check", - "--json", - "--disable", - "hooks", - "-c", - auto, - "-c", - team, - "-s", - "read-only", - "-m", - "gpt-5.5", - "--add-dir", - "/more", - "-C", - ".", - "the task", - ] - ); - backend.thread_id = Some("t-1".to_string()); - assert_eq!( - args_of(&backend.command("again")), - [ - "exec", - "resume", - "--skip-git-repo-check", - "--json", - "--disable", - "hooks", - "--dangerously-bypass-approvals-and-sandbox", - "-c", - auto, - "-c", - team, - "-m", - "gpt-5.5", - "t-1", - "again", - ] - ); - assert!(!backend.runs_tools_here()); - assert!(backend.offered_tools().is_empty()); - } - - /// **BRIDGED, CODEX IS STARTED AS A MODEL AND NOTHING ELSE**, on both - /// spawn paths: its user config unread, every tool switch off, read-only - /// and never asking, and incode's tool server its one MCP server — and - /// none of the flags the other route hands it, because incode's toolbox - /// decides what they decided. - #[test] - fn bridged_codex_is_started_as_a_model_with_incodes_server_only() { - let exe = Path::new(r"C:\Program Files\incode\incode.exe"); - let mut backend = CodexBackend::new(PathBuf::from(".")) - .with_mcp_overrides(vec!["mcp_servers.team.command=\"incode\"".to_string()]) - .with_tools(CodexTools::Incode); - backend.set_models(&["gpt-5.5".to_string()]); - backend.set_permission_mode("acceptEdits"); - backend.set_extra_dirs(vec![PathBuf::from("/more")]); - backend.set_team_identity("implement"); - for resumed in [false, true] { - if resumed { - backend.thread_id = Some("t-1".to_string()); - } - let cmd = backend.bridged_command("the task", exe); - let args = args_of(&cmd); - let lead: &[&str] = if resumed { - &["exec", "resume"] - } else { - &["exec"] - }; - assert_eq!(&args[..lead.len()], lead, "{args:?}"); - for flag in ["--skip-git-repo-check", "--json", "--ignore-user-config"] { - assert!(args.iter().any(|a| a == flag), "{flag}: {args:?}"); - } - assert!(args.windows(2).any(|w| w == ["--disable", "hooks"])); - let overrides = overrides_in(&args); - let mut expected: Vec = MODEL_ONLY_OVERRIDES - .iter() - .map(|o| (*o).to_string()) - .collect(); - expected.extend([ - r#"mcp_servers.incode.command="C:\\Program Files\\incode\\incode.exe""#.to_string(), - r#"mcp_servers.incode.args=["--tool-server"]"#.to_string(), - r#"mcp_servers.incode.env_vars=["INCODE_TOOL_BRIDGE","INCODE_TOOL_TOKEN"]"# - .to_string(), - r#"mcp_servers.incode.default_tools_approval_mode="approve""#.to_string(), - "mcp_servers.incode.required=true".to_string(), - "mcp_servers.incode.tool_timeout_sec=3600".to_string(), - r#"mcp_servers.incode.omit_tools_from=["deferred"]"#.to_string(), - ]); - assert_eq!(overrides, expected, "resumed={resumed}"); - for gone in [ - "--dangerously-bypass-approvals-and-sandbox", - "-s", - "--add-dir", - ] { - assert!(!args.iter().any(|a| a == gone), "{gone}: {args:?}"); - } - assert!( - !overrides - .iter() - .any(|o| o.starts_with("mcp_servers.team.") - || o.starts_with("mcp_servers.memory.")), - "a server beside the bridge: {overrides:?}" - ); - assert_eq!( - args.iter().any(|a| a == "-C"), - !resumed, - "`exec resume` takes no -C: {args:?}" - ); - assert_eq!(args.last().map(String::as_str), Some("the task")); - if resumed { - assert_eq!(args[args.len() - 2], "t-1", "{args:?}"); - } - assert!( - !cmd.get_envs() - .any(|(k, _)| k == std::ffi::OsStr::new(crate::team_mcp::IDENTITY_ENV)), - "the team identity is the toolbox's on this route" - ); - assert!( - cmd.get_envs() - .any(|(k, v)| k == "CLAUDECODE" && v.is_none()), - "issue #3 on this route too" - ); - } - // The mode and the roots went to the toolbox, not to codex. - assert_eq!(backend.sandbox, None); - } - - /// Bridged, the backend says so to every caller that asks: its calls run - /// here, it enforces both halves, and it offers the toolbox's tools. - #[test] - fn bridged_codex_runs_its_tools_here() { - let backend = CodexBackend::new(PathBuf::from(".")).with_tools(CodexTools::Incode); - assert!(backend.runs_tools_here()); - assert_eq!(backend.enforces(), crate::guards::Enforcement::EVERYTHING); - let tools = backend.offered_tools(); - for tool in ["Read", "Write", "Edit", "Bash", "team_ask"] { - assert!(tools.iter().any(|t| t == tool), "{tool}: {tools:?}"); - } - assert!( - backend - .mcp_config() - .is_some_and(|c| c.contains("--tool-server")), - "{:?}", - backend.mcp_config() - ); - // And setting it back to codex's own is the route as it was. - let own = CodexBackend::new(PathBuf::from(".")) - .with_tools(CodexTools::Incode) - .with_tools(CodexTools::Own); - assert!(!own.runs_tools_here()); - assert_eq!(own.mcp_config(), None); - } - - #[test] - fn the_setting_spells_own_and_incode() { - assert_eq!(CodexTools::parse("own"), Some(CodexTools::Own)); - assert_eq!(CodexTools::parse(" INCODE "), Some(CodexTools::Incode)); - assert_eq!(CodexTools::parse("bridge"), None); - assert_eq!(CodexTools::parse(""), None); - assert_eq!(CodexTools::default(), CodexTools::Own); - for tools in [CodexTools::Own, CodexTools::Incode] { - assert_eq!(CodexTools::parse(tools.as_str()), Some(tools)); - } - } - - /// The events a sequence of `codex exec --json` lines stands for. - fn read(lines: &[&str], bridged: bool) -> (Vec, Option) { - let mut thread = None; - let mut reading = Reading::new(&mut thread, Some("gpt-5.5".to_string()), bridged); - let events = lines.iter().flat_map(|l| reading.line(l)).collect(); - drop(reading); - (events, thread) - } - - /// An MCP call to incode's own server, in the shape `codex exec --json` - /// prints it (`exec/src/exec_events.rs` `McpToolCallItem`, 0.163.0): a - /// started item, then a completed one with the result's content blocks. - const INCODE_CALL: [&str; 2] = [ - r#"{"type":"item.started","item":{"id":"item_1","type":"mcp_tool_call","server":"incode","tool":"Write","arguments":{"path":"a.txt","content":"x"},"result":null,"error":null,"status":"in_progress"}}"#, - r#"{"type":"item.completed","item":{"id":"item_1","type":"mcp_tool_call","server":"incode","tool":"Write","arguments":{"path":"a.txt","content":"x"},"result":{"content":[{"type":"text","text":"wrote a.txt"}],"structured_content":null},"error":null,"status":"completed"}}"#, - ]; - - /// **BRIDGED, A CALL TO incode's SERVER IS SHOWN ONCE — AS INCODE RAN - /// IT.** The bridge shows the call under incode's id when it runs it; - /// codex's own record of the same call is not shown again. A call to any - /// other server is still shown from codex's record. - #[test] - fn bridged_codex_does_not_show_incodes_calls_twice() { - let (events, _) = read(&INCODE_CALL, true); - assert!(events.is_empty(), "{events:?}"); - - let other = r#"{"type":"item.completed","item":{"id":"item_2","type":"mcp_tool_call","server":"elsewhere","tool":"lookup","arguments":{},"result":{"content":[{"type":"text","text":"found"}]},"error":null,"status":"completed"}}"#; - let (events, _) = read(&[other], true); - assert!( - matches!(&events[..], [AgentEvent::ToolUse { name, .. }, AgentEvent::ToolResult { output, is_error: false, .. }] if name == "lookup" && output == "found"), - "{events:?}" - ); - } - - /// On codex's own tools the same lines are its tool calls, mapped as - /// they always were: a use when the call starts, and the use and its - /// result when it completes. - #[test] - fn own_tools_codex_shows_an_mcp_call_from_its_record() { - let (events, _) = read(&INCODE_CALL, false); - assert!( - matches!( - &events[..], - [ - AgentEvent::ToolUse { id: a, name: n1, .. }, - AgentEvent::ToolUse { id: b, name: n2, input }, - AgentEvent::ToolResult { output, is_error: false, .. }, - ] if a == "item_1" && b == "item_1" && n1 == "Write" && n2 == "Write" - && input.contains("a.txt") && output == "wrote a.txt" - ), - "{events:?}" - ); - } - - /// A failed MCP call carries its error as an object — `{"message": …}`, - /// not a string — and is shown as a failed result with that message. - #[test] - fn a_failed_mcp_call_shows_its_message() { - let failed = r#"{"type":"item.completed","item":{"id":"item_3","type":"mcp_tool_call","server":"elsewhere","tool":"Write","arguments":{},"result":null,"error":{"message":"tool call timed out"},"status":"failed"}}"#; - let (events, _) = read(&[failed], false); - assert!( - matches!(&events[..], [_, AgentEvent::ToolResult { output, is_error: true, .. }] if output == "tool call timed out"), - "{events:?}" - ); - } - - /// The rest of a turn reads the same on both routes: the thread, the - /// reply, and the result. - #[test] - fn a_turn_reads_the_same_on_both_routes() { - let lines = [ - r#"{"type":"thread.started","thread_id":"th-1"}"#, - r#"{"type":"turn.started"}"#, - r#"Reading additional input from stdin..."#, - r#"{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"done"}}"#, - r#"{"type":"turn.completed","usage":{"input_tokens":3,"cached_input_tokens":1,"output_tokens":2}}"#, - ]; - let (own, own_thread) = read(&lines, false); - let (bridged, bridged_thread) = read(&lines, true); - assert_eq!(own, bridged); - assert_eq!(own_thread.as_deref(), Some("th-1")); - assert_eq!(bridged_thread.as_deref(), Some("th-1")); - assert!( - matches!(&own[0], AgentEvent::SessionStarted { session_id, .. } if session_id == "th-1") - ); - assert!(own - .iter() - .any(|e| matches!(e, AgentEvent::Text(t) if t == "done"))); - } - - // ----------------------------------------------------------------------- - // The flow, end to end, with a stand-in codex. - // ----------------------------------------------------------------------- - - /// Set only in the stand-in codex the flow test starts: the directory it - /// reads its argv from. - const FAKE_CODEX: &str = "INCODE_FAKE_CODEX"; - /// Set only in the stand-in tool server the stand-in codex starts. - const FAKE_TOOL_SERVER: &str = "INCODE_FAKE_TOOL_SERVER"; - - /// The value of the `-c` override for `key`, as codex's TOML reads it. - fn override_value<'a>(overrides: &'a [String], key: &str) -> &'a str { - overrides - .iter() - .find_map(|o| o.strip_prefix(&format!("{key}="))) - .unwrap_or_else(|| panic!("no {key} among {overrides:?}")) - } - - /// The tool server half, as `incode --tool-server` runs it. - #[test] - fn tool_server_child() { - if std::env::var_os(FAKE_TOOL_SERVER).is_none() { - return; - } - let _ = crate::tool_bridge::run_stdio(); - std::process::exit(0); - } - - /// A stand-in codex: reads the argv it was started with, starts the MCP - /// server it was told to — with ONLY the variables `env_vars` names, as - /// codex does — and, over MCP stdio, lists the tools and calls `Write` - /// twice. It prints what it did as `codex exec --json` lines. - #[test] - fn fake_codex_child() { - use std::io::Write as _; - let Some(dir) = std::env::var_os(FAKE_CODEX) else { - return; - }; - let dir = PathBuf::from(dir); - let argv = std::fs::read(dir.join("argv")).expect("argv"); - let args: Vec = argv - .split(|b| *b == 0) - .filter(|a| !a.is_empty()) - .map(|a| String::from_utf8_lossy(a).into_owned()) - .collect(); - let overrides = overrides_in(&args); - let command = override_value(&overrides, "mcp_servers.incode.command") - .trim_matches('"') - .replace("\\\\", "\\"); - let server_args: Vec = - serde_json::from_str(override_value(&overrides, "mcp_servers.incode.args")) - .expect("args"); - let passed: Vec = - serde_json::from_str(override_value(&overrides, "mcp_servers.incode.env_vars")) - .expect("env_vars"); - let mut server = std::process::Command::new(&command) - .args(&server_args) - .env_clear() - .env("PATH", std::env::var_os("PATH").unwrap_or_default()) - .envs( - passed - .iter() - .filter_map(|name| Some((name, std::env::var_os(name)?))), - ) - .stdin(Stdio::piped()) - .stdout(Stdio::piped()) - .spawn() - .expect("start the tool server"); - let mut to = server.stdin.take().expect("stdin"); - let mut from = BufReader::new(server.stdout.take().expect("stdout")); - let mut ask = |id: u64, method: &str, params: serde_json::Value| -> serde_json::Value { - let request = - serde_json::json!({"jsonrpc":"2.0","id":id,"method":method,"params":params}); - writeln!(to, "{request}").expect("send"); - to.flush().expect("flush"); - loop { - let mut line = String::new(); - if from.read_line(&mut line).expect("read") == 0 { - panic!("the tool server went away"); - } - // The test harness's own banner is not a reply. - if let Ok(reply) = serde_json::from_str::(&line) { - if reply["id"] == id { - return reply; - } - } - } - }; - let say = |line: serde_json::Value| println!("{line}"); - say(serde_json::json!({"type":"thread.started","thread_id":"fake-thread"})); - say(serde_json::json!({"type":"turn.started"})); - ask( - 0, - "initialize", - serde_json::json!({"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"fake-codex","version":"0"}}), - ); - let listed = ask(1, "tools/list", serde_json::json!({})); - let names: Vec<&str> = listed["result"]["tools"] - .as_array() - .map(|t| t.iter().filter_map(|t| t["name"].as_str()).collect()) - .unwrap_or_default(); - say( - serde_json::json!({"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":format!("tools: {}", names.join(","))}}), - ); - for (n, path) in [(2, "notes.txt"), (3, "secret.txt")] { - let arguments = serde_json::json!({"path": path, "content": "written"}); - let item = format!("item_{n}"); - say( - serde_json::json!({"type":"item.started","item":{"id":item,"type":"mcp_tool_call","server":"incode","tool":"Write","arguments":arguments,"result":null,"error":null,"status":"in_progress"}}), - ); - let reply = ask( - n, - "tools/call", - serde_json::json!({"name":"Write","arguments":arguments}), - ); - let failed = reply["result"]["isError"] == true; - say( - serde_json::json!({"type":"item.completed","item":{"id":item,"type":"mcp_tool_call","server":"incode","tool":"Write","arguments":arguments, - "result": if failed { serde_json::Value::Null } else { serde_json::json!({"content": reply["result"]["content"]}) }, - "error": if failed { serde_json::json!({"message": reply["result"]["content"][0]["text"]}) } else { serde_json::Value::Null }, - "status": if failed { "failed" } else { "completed" }}}), - ); - } - drop(to); - let _ = server.wait(); - say( - serde_json::json!({"type":"item.completed","item":{"id":"item_9","type":"agent_message","text":"done"}}), - ); - say( - serde_json::json!({"type":"turn.completed","usage":{"input_tokens":1,"output_tokens":1}}), - ); - std::process::exit(0); - } - - /// A shell script at `path` that runs this test binary's `test` with - /// `marker` set to `value`, after `before`. - #[cfg(unix)] - fn child_script(path: &Path, before: &str, marker: &str, value: &Path, test: &str) { - use std::os::unix::fs::PermissionsExt; - let exe = std::env::current_exe().expect("test binary"); - let body = format!( - "#!/bin/sh\n{before}\n{marker}='{}' exec '{}' --exact '{test}' --nocapture -q --test-threads=1\n", - value.display(), - exe.display() - ); - std::fs::write(path, body).expect("write the script"); - std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).expect("runnable"); - } - - /// **A BRIDGED CODEX TURN RUNS ITS TOOL CALLS IN incode's TOOLBOX**, end - /// to end: the backend opens the bridge and starts "codex" with the - /// bridged argv; the stand-in reads the registration off that argv, - /// starts the tool server with only the variables it names, and calls - /// `Write` twice over MCP. The first lands — written by incode. The - /// second is refused by a deny rule in incode's toolbox and nothing is - /// written. Each call is shown once, under incode's id; codex's record of - /// it is not shown again. - #[cfg(unix)] - #[test] - fn a_bridged_turn_runs_its_calls_in_incodes_toolbox_and_a_deny_rule_refuses_one() { - let ws = tempfile::tempdir().expect("ws"); - let bin = tempfile::tempdir().expect("bin"); - let codex = bin.path().join("codex.sh"); - let server = bin.path().join("server.sh"); - child_script( - &codex, - &format!( - "printf '%s\\0' \"$@\" > '{}'", - bin.path().join("argv").display() - ), - FAKE_CODEX, - bin.path(), - "agent::codex::tests::fake_codex_child", - ); - child_script( - &server, - "", - FAKE_TOOL_SERVER, - Path::new("1"), - "agent::codex::tests::tool_server_child", - ); - - let mut backend = CodexBackend::new(ws.path().to_path_buf()) - .with_binary(codex.to_string_lossy()) - .with_tools(CodexTools::Incode) - .with_tool_server(server.clone()); - let mut rules = crate::permissions::rules::PermissionRules::none(); - rules.add( - &crate::permissions::rules::RuleLists { - deny: vec!["Write(secret.txt)".to_string()], - ..Default::default() - }, - crate::permissions::rules::Layer::User, - None, - ); - backend - .tools - .as_mut() - .expect("bridged") - .set_permission_rules(rules); - - let mut seen = Vec::new(); - let outcome = backend - .run_turn("write two files", &mut |e| seen.push(e.clone())) - .expect("the turn completes"); - assert!(!outcome.is_error, "{outcome:?}"); - assert_eq!(outcome.session_id, "fake-thread"); - assert_eq!(backend.session_id(), Some("fake-thread")); - - // The argv codex was really started with: the bridged one. - let argv = String::from_utf8(std::fs::read(bin.path().join("argv")).expect("argv")) - .expect("utf-8"); - assert!(argv.contains("--ignore-user-config"), "{argv:?}"); - assert!(argv.contains("features.shell_tool=false"), "{argv:?}"); - assert!( - argv.contains(&format!( - "mcp_servers.incode.command=\"{}\"", - server.display() - )), - "{argv:?}" - ); - - // The model saw incode's tools. - assert!( - seen.iter().any(|e| matches!(e, AgentEvent::Text(t) if t.starts_with("tools: ") && t.contains("Write") && t.contains("Read"))), - "{seen:?}" - ); - // The first call ran in incode's toolbox; the second was refused there. - assert_eq!( - std::fs::read_to_string(ws.path().join("notes.txt")).expect("written by incode"), - "written" - ); - assert!( - !ws.path().join("secret.txt").exists(), - "the deny rule did not hold" - ); - let uses: Vec<(&str, &str)> = seen - .iter() - .filter_map(|e| match e { - AgentEvent::ToolUse { id, name, .. } => Some((id.as_str(), name.as_str())), - _ => None, - }) - .collect(); - assert_eq!( - uses, - [("incode-1", "Write"), ("incode-2", "Write")], - "each call once, under incode's id: {seen:?}" - ); - let results: Vec<(&str, bool, &str)> = seen - .iter() - .filter_map(|e| match e { - AgentEvent::ToolResult { - id, - is_error, - output, - } => Some((id.as_str(), *is_error, output.as_str())), - _ => None, - }) - .collect(); - assert_eq!(results.len(), 2, "{seen:?}"); - assert_eq!((results[0].0, results[0].1), ("incode-1", false)); - assert_eq!((results[1].0, results[1].1), ("incode-2", true)); - assert!( - results[1].2.contains("Write(secret.txt)"), - "refused by the rule, by name: {}", - results[1].2 - ); - assert!( - seen.iter() - .any(|e| matches!(e, AgentEvent::Text(t) if t == "done")), - "{seen:?}" - ); - } -} diff --git a/src/agent/codex/argv.rs b/src/agent/codex/argv.rs new file mode 100644 index 0000000..9bbea9a --- /dev/null +++ b/src/agent/codex/argv.rs @@ -0,0 +1,265 @@ +//! The command each turn starts codex with, on either route: the flags, the +//! `-c` overrides that make codex a model and nothing else on the bridged +//! route, and the registration of incode's tool server. +//! +//! Wired to: [`super::CodexBackend`]'s `run_turn` (both routes) and its +//! `mcp_config`, which reports [`bridge_registration`]. + +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; + +use super::CodexBackend; + +/// Codex's own hooks file off, on both spawn paths: incode fires the memory +/// engine's lifecycle itself, and codex firing it too would record each +/// session twice. Proved on 0.145.0 and 0.153.4, `exec` and `exec resume`: +/// with a probe hooks file (trust bypassed), hooks on recorded `session-start` +/// and `user-prompt`; `--disable hooks` recorded nothing, and codex no longer +/// read `~/.codex/hooks.json`. +const HOOKS_OFF: [&str; 2] = ["--disable", "hooks"]; + +/// The `-c` overrides that make codex a model and nothing else, on the +/// bridged route. Each key is from codex's own config types (`ConfigToml`, +/// `ToolsToml`, `features/src/lib.rs`), present in 0.145.0, 0.153.4 and +/// 0.163.0 unless said; a key a version does not know is ignored by it, not +/// refused (measured on 0.163.0 with an invented feature name), so a typo +/// here would do nothing — which is why each was watched leave the tool list. +/// +/// - `features.shell_tool=false`: no `exec_command` / `write_stdin` / `shell`. +/// - `features.view_image=false`: no `view_image` (the key is 0.153+; 0.145 +/// has no switch). +/// - `web_search="disabled"`: no hosted `web_search`. +/// - `features.goals=false`: no `get_goal` / `create_goal` / `update_goal`. +/// - `tools.experimental_request_user_input.enabled=false`: no +/// `request_user_input` — incode asks the person itself. +/// - `agents.enabled=false`: no sub-agents of codex's own. Needed beside +/// `features.multi_agent=false`, which only covers models the catalogue +/// leaves to the features: measured on 0.163.0, `gpt-5.6-terra` (whose +/// catalogue entry names multi-agent v2) was still offered +/// `collaboration.spawn_agent` & co. with the feature off. `agents.enabled` +/// wins over the catalogue (`Config::multi_agent_version_override`). +/// - `features.multi_agent=false`, `features.apps=false`, +/// `features.plugins=false`, `features.browser_use=false`, +/// `features.computer_use=false`, `features.image_generation=false`: no +/// sub-agents, connectors, plugin tools, browser, desktop or image tools of +/// codex's own; incode's toolbox has its own sub-agent, browser and desktop. +/// - `sandbox_mode="read-only"`, `approval_policy="never"`: what is left of +/// codex's own reach writes nothing — `apply_patch` is rejected before it +/// runs (see the notes on [`crate::agent::codex`]) — and nothing waits on +/// a person. +pub const MODEL_ONLY_OVERRIDES: [&str; 14] = [ + "features.shell_tool=false", + "features.view_image=false", + "web_search=\"disabled\"", + "features.goals=false", + "tools.experimental_request_user_input.enabled=false", + "agents.enabled=false", + "features.multi_agent=false", + "features.apps=false", + "features.plugins=false", + "features.browser_use=false", + "features.computer_use=false", + "features.image_generation=false", + "sandbox_mode=\"read-only\"", + "approval_policy=\"never\"", +]; + +/// Codex's user config (`$CODEX_HOME/config.toml`) is not read on the +/// bridged route — the counterpart of the Claude route's +/// `--setting-sources ""`: an MCP server the operator registered there would +/// be a tool incode cannot refuse. Auth still comes from `CODEX_HOME` +/// (`codex exec --help`). A global flag, taken by `exec resume` too. +const IGNORE_USER_CONFIG: &str = "--ignore-user-config"; + +/// The bridge's registration, as `-c` overrides: incode's tool server and +/// nothing else. +/// +/// - `env_vars`: codex starts a stdio MCP server with ONLY a short list of +/// variables (`HOME`, `PATH`, …; `rmcp-client/src/utils.rs` +/// `create_env_for_mcp_server`) plus the ones named here. Measured on +/// 0.163.0: a stand-in server received the two named and NOT a third set +/// beside them. The values never reach the argv. +/// - `default_tools_approval_mode="approve"`: the one mode in which codex never +/// asks before an MCP call (`requires_mcp_tool_approval_for_mode`); `auto` +/// asks for any tool not marked read-only, and with `approval_policy="never"` +/// that ask is a refusal. Whether a call may run is incode's decision. +/// - `required=true`: a server that fails to start fails the turn, rather than +/// the model running on with no tools. +/// - `tool_timeout_sec`: codex gives up on an MCP call after 300 s by default; +/// incode may still be asking the person, or running a long command. +/// - `omit_tools_from=["deferred"]`: the tools are listed to the model +/// directly. Without it codex hid them behind its `tool_search` (measured); +/// 0.145.0 has no such key, and its model finds them through `tool_search`. +/// +/// Called by [`CodexBackend::bridged_command`] and by the backend's +/// `mcp_config`. +pub(super) fn bridge_registration(exe: &Path) -> Vec { + let key = crate::tool_bridge::CLIENT_KEY; + // TOML basic strings take backslash escapes: a Windows path must have its + // separators doubled — see `desktop::mcp::codex_config_overrides`. + let exe = exe.to_string_lossy().replace('\\', "\\\\"); + vec![ + format!("mcp_servers.{key}.command=\"{exe}\""), + format!( + "mcp_servers.{key}.args=[\"{}\"]", + crate::tool_bridge::SERVER_FLAG + ), + format!( + "mcp_servers.{key}.env_vars=[\"{}\",\"{}\"]", + crate::tool_bridge::ADDR_ENV, + crate::tool_bridge::TOKEN_ENV + ), + format!("mcp_servers.{key}.default_tools_approval_mode=\"approve\""), + format!("mcp_servers.{key}.required=true"), + format!( + "mcp_servers.{key}.tool_timeout_sec={}", + crate::tool_bridge::REPLY_BOUND_SECS + ), + format!("mcp_servers.{key}.omit_tools_from=[\"deferred\"]"), + ] +} + +impl CodexBackend { + /// The binary codex is told to start as the tool server. + /// + /// Called by [`Self::command`] and by the backend's `mcp_config`. + pub(super) fn server_exe(&self) -> PathBuf { + self.tool_server + .clone() + .or_else(|| std::env::current_exe().ok()) + .unwrap_or_else(|| PathBuf::from("incode")) + } + + /// The command for one turn, on whichever route this backend is on. + /// + /// Called by the backend's `run_turn` on codex's own tools. + pub(super) fn command(&self, prompt: &str) -> Command { + if self.tools.is_some() { + return self.bridged_command(prompt, &self.server_exe()); + } + let mut cmd = Command::new(&self.binary); + crate::agent::parent_session::detach_from_parent_session(&mut cmd); + cmd.current_dir(&self.workspace); + + // WHO THIS AGENT IS ON THE TEAM CHANNEL, for the task about to run. + // The team MCP server is a child of this process and reads it from + // here — the registration cannot carry it, because MCP servers are + // configured once and the role changes every task. + if let Some(role) = &self.team_identity { + cmd.env(crate::team_mcp::IDENTITY_ENV, role); + } + + // The pictures for this turn, as files — `codex exec -i, --image + // ...` (and the same on `exec resume`). Each goes FIRST, before + // any other flag, so the next flag ends the list: `--image` takes + // several values, and one placed before the prompt would take the + // prompt for a file name. + let images = |cmd: &mut Command| { + for file in &self.image_files { + cmd.arg("--image").arg(file); + } + }; + if let Some(tid) = &self.thread_id { + cmd.arg("exec"); + cmd.arg("resume"); + images(&mut cmd); + cmd.arg("--skip-git-repo-check"); + cmd.arg("--json"); + cmd.args(HOOKS_OFF); + cmd.arg("--dangerously-bypass-approvals-and-sandbox"); + cmd.arg("-c") + .arg("mcp_servers.memory.default_tools_approval_mode=\"auto\""); + for override_ in &self.mcp_overrides { + cmd.arg("-c").arg(override_); + } + if let Some(model) = &self.model { + cmd.arg("-m").arg(model); + } + cmd.arg(tid); + cmd.arg(prompt); + } else { + cmd.arg("exec"); + images(&mut cmd); + cmd.arg("--skip-git-repo-check"); + cmd.arg("--json"); + cmd.args(HOOKS_OFF); + cmd.arg("-c") + .arg("mcp_servers.memory.default_tools_approval_mode=\"auto\""); + for override_ in &self.mcp_overrides { + cmd.arg("-c").arg(override_); + } + if let Some(sandbox) = &self.sandbox { + cmd.arg("-s").arg(sandbox); + } else { + cmd.arg("--dangerously-bypass-approvals-and-sandbox"); + } + if let Some(model) = &self.model { + cmd.arg("-m").arg(model); + } + for dir in &self.extra_dirs { + cmd.arg("--add-dir").arg(dir); + } + cmd.arg("-C").arg(&self.workspace); + cmd.arg(prompt); + } + + // Close stdin so Codex does not wait on interactive input. + cmd.stdin(Stdio::null()); + cmd + } + + /// The command for one bridged turn: codex as a model only, with `exe` + /// started as its one MCP server. The bridge's address and token are + /// added by the caller, which holds the bridge. + /// + /// Not handed over, because incode decides them in its toolbox: the + /// permission mode (`-s`), the added roots (`--add-dir`), the bypass + /// flag, the team and desktop servers ([`Self::with_mcp_overrides`] — both + /// are toolbox tools here) and the memory server's approval override (the + /// server lives in the user config this route does not read). + /// + /// Called by [`Self::command`] and, on the bridged route, by the + /// backend's `run_turn`, which names the binary the turn's channel opened. + pub(super) fn bridged_command(&self, prompt: &str, exe: &Path) -> Command { + let mut cmd = Command::new(&self.binary); + crate::agent::parent_session::detach_from_parent_session(&mut cmd); + cmd.current_dir(&self.workspace); + cmd.arg("exec"); + if self.thread_id.is_some() { + cmd.arg("resume"); + } + // The pictures FIRST, as on the other route: `--image` takes several + // values, and the next flag is what ends the list. + for file in &self.image_files { + cmd.arg("--image").arg(file); + } + cmd.arg("--skip-git-repo-check"); + cmd.arg("--json"); + cmd.args(HOOKS_OFF); + cmd.arg(IGNORE_USER_CONFIG); + for override_ in MODEL_ONLY_OVERRIDES + .iter() + .map(|o| (*o).to_string()) + .chain(bridge_registration(exe)) + { + cmd.arg("-c").arg(override_); + } + if let Some(model) = &self.model { + cmd.arg("-m").arg(model); + } + match &self.thread_id { + // `exec resume` takes no `-C`: the thread carries its directory. + Some(tid) => { + cmd.arg(tid); + } + None => { + cmd.arg("-C").arg(&self.workspace); + } + } + cmd.arg(prompt); + // No team identity in the environment: the team channel's tools are + // the toolbox's on this route, and it is told who speaks. + cmd.stdin(Stdio::null()); + cmd + } +} diff --git a/src/agent/codex/bridged.rs b/src/agent/codex/bridged.rs new file mode 100644 index 0000000..5f402ba --- /dev/null +++ b/src/agent/codex/bridged.rs @@ -0,0 +1,111 @@ +//! One bridged turn: codex spawned as a model only, its tool calls answered +//! by incode's toolbox over the tool bridge. +//! +//! Wired to: [`super::CodexBackend`]'s `run_turn`, on [`super::CodexTools::Incode`]. + +use std::io::BufReader; +use std::process::{Command, Stdio}; + +use super::wire::Reading; +use super::CodexBackend; +use crate::agent::{AgentError, AgentEvent, TurnOutcome}; + +impl CodexBackend { + /// One bridged turn: `command` spawned with the bridge's address and token + /// in its environment, its tool calls answered by the toolbox, its stream + /// read to the end — the Claude route's loop ([`crate::tool_bridge::drive`]) + /// over codex's lines. + /// + /// Called by the backend's `run_turn` once the turn's channel is open. + pub(super) fn run_bridged( + &mut self, + mut command: Command, + turn: crate::tool_bridge::Turn, + on_event: &mut dyn FnMut(&AgentEvent), + ) -> Result { + let crate::tool_bridge::Turn { + bridge, to, from, .. + } = turn; + // How the tool server finds this process: codex's environment, which + // it passes on to the server by the names `env_vars` lists — never + // its argv. + for (key, value) in bridge.env() { + command.env(key, value); + } + crate::agent::process_tree::prepare(&mut command); + let mut child = command + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .map_err(|e| AgentError::new(format!("could not start `{}`: {e}", self.binary)))?; + let tree = crate::agent::process_tree::Tree::adopt(&child); + let stdout = child + .stdout + .take() + .ok_or_else(|| AgentError::new("the agent produced no output stream"))?; + let stderr = crate::agent::stderr_tail::StderrTail::capture(child.stderr.take()); + crate::tool_bridge::pump(BufReader::new(stdout), to); + + let Self { + tools, + calls, + thread_id, + model, + cancel, + .. + } = self; + let tools = tools + .as_mut() + .ok_or_else(|| AgentError::new("a bridged turn needs incode's toolbox"))?; + let mut reading = Reading::new(thread_id, model.clone(), true); + let driven = crate::tool_bridge::drive( + &from, + cancel.as_ref(), + tools, + calls, + on_event, + &mut |line, tools| { + let events = reading.line(&line); + for event in &events { + if let AgentEvent::SessionStarted { session_id, .. } = event { + // The engine files its cards under the conversation. + tools.set_session(session_id); + } + } + events + }, + ); + let (outcome, usage) = reading.finish(); + // Closed as soon as the loop is done: a call that arrives from here on + // is refused rather than left waiting on a loop that is gone. + drop(bridge); + if let Err(e) = driven { + // Whatever happened, codex must not outlive the turn — nor + // whatever it started. + tree.kill(&mut child); + return Err(e); + } + + on_event(&AgentEvent::Usage { + input_tokens: usage.input_tokens, + output_tokens: usage.output_tokens, + cache_creation_tokens: usage.cache_creation_input_tokens, + cache_read_tokens: usage.cache_read_input_tokens, + }); + let status = child + .wait() + .map_err(|e| AgentError::new(format!("the agent did not exit cleanly: {e}")))?; + outcome.ok_or_else(|| { + let stderr_output = stderr.finish(); + let detail = if stderr_output.is_empty() { + String::new() + } else { + format!(": {stderr_output}") + }; + AgentError::new(format!( + "the agent produced no result line (exit {}){detail}", + status.code().unwrap_or(-1) + )) + }) + } +} diff --git a/src/agent/codex/mod.rs b/src/agent/codex/mod.rs new file mode 100644 index 0000000..78a0248 --- /dev/null +++ b/src/agent/codex/mod.rs @@ -0,0 +1,647 @@ +//! OpenAI Codex (`codex`) agent backend, driven as a subprocess. +//! +//! # Where this came from +//! +//! [`crate::agent::registry`] listed `codex` as `Protocol::Unverified`. +//! This module implements that driver: every CLI flag and wire event below was +//! measured directly from real `codex exec --json` runs on Codex CLI (v0.145.0 / +//! v0.153.4). +//! +//! # How it is driven +//! +//! - Non-interactive turns are started with `codex exec [OPTIONS] [PROMPT]`. +//! - Resumed turns are continued with `codex exec resume [OPTIONS] [PROMPT]`. +//! - Output is read from stdout as newline-delimited JSON (`--json`). +//! - Standard input is closed (`Stdio::null()`) so Codex does not wait on interactive input. +//! - By default, headless turns bypass confirmation prompts with +//! `--dangerously-bypass-approvals-and-sandbox` so unattended runs do not hang waiting +//! for approvals on a terminal that has nobody typing into it. +//! +//! # Enforcement +//! +//! Like Antigravity, Codex CLI does not provide external flags to disallow specific tools +//! or protected file paths. Protection is derived from [`crate::guards::Sentinel`] which +//! detects changes after the turn. See [`CodexBackend::enforces`]. +//! +//! # Bridged: incode's tools instead of codex's ([`CodexTools::Incode`]) +//! +//! Opt-in (`codex_tools: "incode"` in admin.json, or `INCODE_CODEX_TOOLS=incode`), +//! because no turn with a REAL model has been run this way yet. When on, codex is +//! driven the way the Claude route is ([`crate::tool_bridge`]): its own tools are +//! switched off by config, it is handed ONE MCP server — `incode --tool-server` — +//! and every call the model makes comes back to this process and runs through the +//! toolbox. What each override does was read from codex's source at +//! `rust-v0.163.0`, checked against `rust-v0.153.4` and `rust-v0.145.0`, and +//! measured on the 0.163.0 binary against a stand-in Responses endpoint +//! (`model_providers..base_url`) that recorded what codex sent: +//! +//! - `gpt-5.5`, own tools (control): `exec_command, write_stdin, +//! request_user_input, apply_patch, view_image, get_goal, create_goal, +//! update_goal, tool_search, web_search`; +//! - `gpt-5.5`, with [`MODEL_ONLY_OVERRIDES`] and the bridge's registration: +//! `list_mcp_resources, list_mcp_resource_templates, read_mcp_resource, +//! apply_patch, mcp__incode{…}`; +//! - `gpt-5.6-terra`, a code-mode model: one `exec` tool (JavaScript in an +//! isolate with no file system or network, calling nested tools) whose nested +//! tools were `apply_patch`, the three resource readers and every +//! `mcp__incode__*`, plus `wait` — and, before `agents.enabled=false`, a +//! `collaboration` namespace (`spawn_agent`, …). +//! +//! Driven end to end through `incode -t` with that endpoint scripted to call +//! `mcp__incode` `Write`: codex started `incode --tool-server`, the call ran in +//! incode's toolbox (trace `tool Write (change)`), the file was written, the event +//! was incode's (`incode-1`), and the model was handed the toolbox's answer. +//! +//! `apply_patch` cannot be switched off: it is offered when the MODEL CATALOGUE +//! says so (`model_info.apply_patch_tool_type`, `core/src/tools/spec_plan.rs`), not +//! by any config key or feature. It is neutralised instead: with +//! `sandbox_mode="read-only"` and `approval_policy="never"`, codex's +//! `assess_patch_safety` (`core/src/safety.rs`) finds no writable root and REJECTS +//! the patch before it runs, on every platform, sandbox or not. The three +//! `*_mcp_resource*` tools only read resources the MCP servers offer, and the only +//! server is incode's. +//! +//! # Layout +//! +//! This file holds the backend and its settings. The command each turn starts +//! is built in `argv.rs`, a bridged turn is run in `bridged.rs`, and what codex +//! prints is read in `wire.rs`. + +mod argv; +mod bridged; +mod wire; + +use std::io::{BufRead, BufReader}; +use std::path::PathBuf; +use std::process::Stdio; + +use super::{AgentBackend, AgentError, AgentEvent, TurnOutcome}; +pub use argv::MODEL_ONLY_OVERRIDES; +use wire::Reading; + +/// Whose tools a codex model runs, from admin.json's `codex_tools` or +/// [`CODEX_TOOLS_ENV`] — see [`crate::admin::AdminConfig::resolve_codex_tools`]. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum CodexTools { + /// Codex's own (`exec_command`, `apply_patch`, …), watched afterwards by + /// the Sentinel. The default until a live turn has proved the other. + #[default] + Own, + /// incode's, through the tool bridge: codex is a model and nothing else. + Incode, +} + +impl CodexTools { + /// `own` or `incode`, ignoring case; anything else is no answer. + #[must_use] + pub fn parse(raw: &str) -> Option { + match raw.trim().to_ascii_lowercase().as_str() { + "own" => Some(Self::Own), + "incode" => Some(Self::Incode), + _ => None, + } + } + + #[must_use] + pub fn as_str(self) -> &'static str { + match self { + Self::Own => "own", + Self::Incode => "incode", + } + } +} + +/// The variable that wins over admin.json's `codex_tools`. +pub const CODEX_TOOLS_ENV: &str = "INCODE_CODEX_TOOLS"; + +// --------------------------------------------------------------------------- +// Backend +// --------------------------------------------------------------------------- + +/// Drives OpenAI Codex CLI over its non-interactive interface. +pub struct CodexBackend { + binary: String, + workspace: PathBuf, + /// Thread ID for this conversation. Resumed with `codex exec resume `. + thread_id: Option, + model: Option, + extra_dirs: Vec, + /// Sandbox mode, e.g. "read-only" or "workspace-write". + sandbox: Option, + /// `-c key=value` overrides registering an MCP server, if the caller wants + /// this agent to have one. + /// + /// Built by [`crate::desktop::mcp::codex_config_overrides`]. Off unless + /// asked — handing every run a desktop it did not request would widen an + /// agent's reach as a side effect of a constructor. + mcp_overrides: Vec, + /// Who this agent speaks as on the team channel, for the task in hand. + team_identity: Option, + /// System context blocks prepended to the prompt. + system_context: Vec, + cancel: Option, + /// Pictures for the next turn's prompt only. + images: Vec, + /// Where this turn's pictures were written, while its command is built. + image_files: Vec, + /// Every tool the model has, run HERE — on the bridged route only + /// ([`CodexTools::Incode`]). `None` is codex running its own tools, and + /// then nothing below this line is used. + tools: Option, + /// How many calls the toolbox has run for this backend, so each gets an + /// id no earlier turn used. + calls: u64, + /// The binary codex is told to start as the tool server, when not this + /// one — a test's stand-in. `None` is this process's own binary. + tool_server: Option, +} + +/// A turn's pictures as files for `--image`, removed when the turn is over. +struct ImageFiles { + paths: Vec, +} + +impl ImageFiles { + /// Write each picture to a file of its own in the system's temporary + /// directory, named so no two turns share one. + fn write(images: &[crate::toolbox::Image]) -> Result { + let mut written = Self { paths: Vec::new() }; + for image in images { + let path = std::env::temp_dir().join(format!( + "incode-prompt-{}.{}", + uuid::Uuid::new_v4(), + image.format().word() + )); + std::fs::write(&path, image.bytes()) + .map_err(|e| format!("a picture could not be written for the agent: {e}"))?; + written.paths.push(path); + } + Ok(written) + } +} + +impl Drop for ImageFiles { + fn drop(&mut self) { + for path in &self.paths { + let _ = std::fs::remove_file(path); + } + } +} + +impl CodexBackend { + #[must_use] + pub fn new(workspace: PathBuf) -> Self { + Self { + binary: "codex".to_string(), + workspace, + thread_id: None, + model: None, + extra_dirs: Vec::new(), + sandbox: None, + mcp_overrides: Vec::new(), + team_identity: None, + system_context: Vec::new(), + cancel: None, + images: Vec::new(), + image_files: Vec::new(), + tools: None, + calls: 0, + tool_server: None, + } + } + + /// Run this model's tool calls in incode's toolbox, through the bridge, + /// with codex's own tools switched off — or not, for [`CodexTools::Own`]. + /// + /// Set before the toolbox builders below, which do nothing without it: + /// codex's own tools are not incode's to configure. + #[must_use] + pub fn with_tools(mut self, tools: CodexTools) -> Self { + self.tools = match tools { + // The filtered environment for the shell tool, as on the Claude + // route: a command the model chose must not inherit this + // process's credentials. No sub-agent CLI is named: the toolbox + // drives one as the Claude CLI, which codex is not. + CodexTools::Incode => Some(crate::toolbox::Toolbox::new(&self.workspace, true)), + CodexTools::Own => None, + }; + self + } + + /// The toolbox, when this model's tools are incode's. + fn toolbox(&mut self) -> Option<&mut crate::toolbox::Toolbox> { + self.tools.as_mut() + } + + /// Ask the memory engine before every tool call this model makes — on the + /// bridged route, where incode runs them. + #[must_use] + pub fn with_engine(mut self, engine: Option) -> Self { + self.tools = self.tools.map(|t| t.with_engine(engine)); + self + } + + /// Announce each file write to the engine's edit check — bridged only. + #[must_use] + pub fn with_code_edits(mut self, edits: Option) -> Self { + self.tools = self.tools.map(|t| t.with_code_edits(edits)); + self + } + + /// Run the operator's own pre- and post-tool commands around every call — + /// bridged only. See [`crate::hooks`]. + #[must_use] + pub fn with_operator_hooks(mut self, hooks: Option) -> Self { + self.tools = self.tools.map(|t| t.with_operator_hooks(hooks)); + self + } + + /// Confine this model's shell commands to `policy` — bridged only: codex's + /// own shell is off there, and incode's runs under incode's sandbox. + #[must_use] + pub fn with_sandbox(mut self, policy: crate::sandbox::SandboxPolicy) -> Self { + self.tools = self.tools.map(|t| t.with_sandbox(policy)); + self + } + + /// Offer the model the desktop tools, run through incode's toolbox — + /// bridged only; codex's own route registers the desktop server instead + /// ([`Self::with_mcp_overrides`]). + #[must_use] + pub fn with_desktop(mut self, setup: crate::toolbox::DesktopSetup) -> Self { + if let Some(tools) = self.toolbox() { + tools.enable_desktop(setup); + } + self + } + + /// Offer the model only `tools`, when given — a user-defined sub-agent's + /// allow-list, refused by the toolbox. Bridged only. + #[must_use] + pub fn with_tool_allowlist(mut self, allowed: Option>) -> Self { + if let (Some(tools), Some(allowed)) = (self.toolbox(), allowed) { + tools.restrict_tools(allowed); + } + self + } + + /// Have codex start `exe` as the tool server instead of this binary. + /// Unix only, as its one caller is (the bridged-turn test's fakes are + /// shell scripts). + #[cfg(all(test, unix))] + fn with_tool_server(mut self, exe: PathBuf) -> Self { + self.tool_server = Some(exe); + self + } + + /// Hand this agent an MCP server, as `-c key=value` overrides. + /// + /// Build them with [`crate::desktop::mcp::codex_config_overrides`] so the + /// TOML shape stays in one place. + #[must_use] + pub fn with_mcp_overrides(mut self, overrides: Vec) -> Self { + self.mcp_overrides = overrides; + self + } + + /// Carry the harness's context on every turn. + /// + /// Blank blocks are dropped so a project with no brief or findings sends + /// nothing rather than blank text. + #[must_use] + pub fn with_system_context(mut self, context: Vec) -> Self { + self.system_context = context + .into_iter() + .filter(|block| !block.trim().is_empty()) + .collect(); + self + } + + /// Override the binary command or path. + #[must_use] + pub fn with_binary(mut self, binary: impl Into) -> Self { + self.binary = binary.into(); + self + } + + /// Whether this agent recognises a model id as one of its own. + fn serves(&self, model: &str) -> bool { + const KNOWN_FAMILIES: [&str; 6] = ["gpt-", "o1", "o3", "o4", "chatgpt-", "codex-"]; + let id = model.trim().to_ascii_lowercase(); + KNOWN_FAMILIES.iter().any(|f| id.starts_with(f)) + } + + /// The prompt actually sent: the harness's context, then the task, budgeted for OS limits. + fn full_prompt(&self, prompt: &str) -> Result { + let (budgeted_prompt, budgeted_context) = + crate::agent::budget_for_spawn(prompt, &self.system_context, &self.workspace)?; + Ok(if budgeted_context.is_empty() { + budgeted_prompt + } else { + format!("{budgeted_context}\n\n{budgeted_prompt}") + }) + } +} + +impl AgentBackend for CodexBackend { + fn id(&self) -> &str { + "codex" + } + + /// On its own tools, neither half. Measured from the CLI surface: no + /// per-tool deny flag exists, so Sentinel detection covers file writes + /// after the fact. + /// + /// Bridged, both — by incode's toolbox, as on the Claude route: every + /// write the model can make is a toolbox call refused before it runs, and + /// its only sub-agent tool is incode's, which stops at its depth limit. + /// What codex keeps of its own cannot do either: `apply_patch` is rejected + /// unrun under read-only + never, and its sub-agent tools are off + /// (`features.multi_agent=false`) — both measured; see the module notes. + fn enforces(&self) -> crate::guards::Enforcement { + if self.tools.is_some() { + return crate::guards::Enforcement::EVERYTHING; + } + crate::guards::Enforcement::NOTHING + } + + fn agent_failed(&self, outcome: &TurnOutcome) -> bool { + outcome.is_error + || outcome.stop_reason.eq_ignore_ascii_case("ERROR") + || crate::agent::moves_the_work(&outcome.failure()) + } + + /// Bridged, the team channel's tools are the toolbox's, so the toolbox is + /// who speaks; otherwise the team server reads it from the spawn. + fn set_team_identity(&mut self, role: &str) { + match self.toolbox() { + Some(tools) => tools.set_team_identity(role), + None => self.team_identity = Some(role.to_string()), + } + } + + fn mcp_config(&self) -> Option { + // Bridged, the one server codex is handed is the bridge — the binary + // is the one each turn names, so this is what the next turn sends. + if self.tools.is_some() { + return Some(argv::bridge_registration(&self.server_exe()).join("\n")); + } + // EVERY override, not the first. Returning one of them read as the + // whole registration, which was true while there was a single server + // and became a lie the moment there were two — the second was simply + // invisible to anything asking what this agent had been handed. + if self.mcp_overrides.is_empty() { + return None; + } + Some(self.mcp_overrides.join("\n")) + } + + // What follows reaches the toolbox, and so means something only on the + // bridged route. On codex's own tools each is the trait's default: there + // is no call of incode's to ask about, record or watch. + + /// Bridged: codex's own tools are switched off and every call comes back + /// through the bridge to this backend's toolbox. + fn runs_tools_here(&self) -> bool { + self.tools.is_some() + } + + fn set_prompter(&mut self, prompter: std::sync::Arc) { + if let Some(tools) = self.toolbox() { + tools.set_prompter(prompter); + } + } + + fn set_owner(&mut self, owner: std::sync::Arc) { + if let Some(tools) = self.toolbox() { + tools.set_owner(owner); + } + } + + fn share_allowed_writes(&mut self, record: std::sync::Arc) { + if let Some(tools) = self.toolbox() { + tools.share_allowed_writes(record); + } + } + + fn share_session_tools(&mut self, state: std::sync::Arc) { + if let Some(tools) = self.toolbox() { + tools.share_session(state); + } + } + + fn set_watch(&mut self, watch: std::sync::Arc) { + if let Some(tools) = self.toolbox() { + tools.set_watch(watch); + } + } + + /// The engine hears incode's session id with every call, not codex's + /// thread id: incode's is the one its session events carry too. + fn set_memory_session(&mut self, session: &str) { + if let Some(tools) = self.toolbox() { + tools.pin_session(session); + } + } + + fn end_code_edits(&mut self) { + if let Some(tools) = self.toolbox() { + tools.end_code_edits(); + } + } + + fn children(&self) -> Vec<(String, String)> { + self.tools.as_ref().map_or_else(Vec::new, |tools| { + tools + .children() + .into_iter() + .map(|c| (c.session, c.title)) + .collect() + }) + } + + fn offered_tools(&self) -> Vec { + self.tools + .as_ref() + .map_or_else(Vec::new, crate::toolbox::Toolbox::names) + } + + fn system_context(&self) -> &[String] { + &self.system_context + } + + fn set_system_context(&mut self, blocks: Vec) { + self.system_context = blocks + .into_iter() + .filter(|b| !b.trim().is_empty()) + .collect(); + } + + /// Model ladder in Codex / OpenAI namespace. + fn ladder_for(&self, role: &str) -> Vec { + let ids: &[&str] = match role { + "explore" | "grunt" => &["gpt-5.6-luna", "gpt-5.4-mini", "o4-mini", "o3-mini"], + "diagnose" | "review" | "plan" => &["gpt-5.6-terra", "gpt-5.5", "o3"], + "implement" | "frontend" => &["gpt-5.6-terra", "gpt-5.5", "o3"], + _ => &[], + }; + ids.iter().map(|id| (*id).to_string()).collect() + } + + fn session_id(&self) -> Option<&str> { + self.thread_id.as_deref() + } + + fn set_session_id(&mut self, session_id: &str) { + self.thread_id = Some(session_id.to_string()); + } + + fn clear_session(&mut self) { + self.thread_id = None; + } + + fn model(&self) -> Option<&str> { + self.model.as_deref() + } + + fn set_models(&mut self, candidates: &[String]) { + self.model = candidates.iter().find(|c| self.serves(c)).cloned(); + } + + /// Bridged, incode's toolbox does the writing, so it is the toolbox that + /// must reach the added roots — under the same guards. Codex is not told: + /// its own sandbox is read-only there. + fn set_extra_dirs(&mut self, dirs: Vec) { + if let Some(tools) = self.toolbox() { + tools.set_extra_dirs(dirs.clone()); + } + self.extra_dirs = dirs; + } + + /// Bridged, decided by incode's toolbox and never handed to codex: its + /// own sandbox stays read-only whatever the mode, because it runs nothing + /// that writes. A spelling nobody recognises lands on read-only. + fn set_permission_mode(&mut self, mode: &str) { + if let Some(tools) = self.toolbox() { + tools.set_permission_mode(crate::permissions::PermissionMode::from_agent_mode(mode)); + return; + } + self.sandbox = match mode { + "plan" | "read-only" => Some("read-only".to_string()), + "acceptEdits" | "accept-edits" | "workspace-write" => { + Some("workspace-write".to_string()) + } + _ => None, + }; + } + + fn set_cancel(&mut self, token: crate::runtime::cancel::CancelToken) { + if let Some(tools) = self.toolbox() { + tools.set_cancel(token.clone()); + } + self.cancel = Some(token); + } + + /// As files, with `--image` — in `codex exec --help` (0.153.4) for both + /// `exec` and `exec resume`. Not run live here: every live turn on this + /// machine answers with the account's usage limit. + fn attach_images(&mut self, images: Vec) -> Result<(), String> { + self.images = images; + Ok(()) + } + + fn run_turn( + &mut self, + prompt: &str, + on_event: &mut dyn FnMut(&AgentEvent), + ) -> Result { + let sent = self.full_prompt(prompt)?; + // Held to the end of the turn, then removed. + let pictures = + ImageFiles::write(&std::mem::take(&mut self.images)).map_err(AgentError::new)?; + self.image_files.clone_from(&pictures.paths); + if self.tools.is_some() { + // The turn's channel first: the command names the binary it was + // opened for, and a channel that cannot open starts nothing. + let turn = match crate::tool_bridge::Turn::open(self.cancel.clone()) { + Ok(turn) => turn, + Err(e) => { + self.image_files.clear(); + return Err(e); + } + }; + let exe = self.tool_server.clone().unwrap_or_else(|| turn.exe.clone()); + let command = self.bridged_command(&sent, &exe); + self.image_files.clear(); + return self.run_bridged(command, turn, on_event); + } + let mut command = self.command(&sent); + self.image_files.clear(); + crate::agent::process_tree::prepare(&mut command); + let mut child = command + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .map_err(|e| AgentError::new(format!("could not start `{}`: {e}", self.binary)))?; + let tree = crate::agent::process_tree::Tree::adopt(&child); + + let stdout = child + .stdout + .take() + .ok_or_else(|| AgentError::new("the agent produced no output stream"))?; + + let stderr = crate::agent::stderr_tail::StderrTail::capture(child.stderr.take()); + + let mut reading = Reading::new(&mut self.thread_id, self.model.clone(), false); + + for line in BufReader::new(stdout).lines() { + if let Some(token) = &self.cancel { + if token.is_cancelled() { + tree.kill(&mut child); + return Err(AgentError::new("the turn was cancelled")); + } + } + let Ok(line) = line else { break }; + for event in reading.line(&line) { + on_event(&event); + } + } + let (outcome, usage) = reading.finish(); + + on_event(&AgentEvent::Usage { + input_tokens: usage.input_tokens, + output_tokens: usage.output_tokens, + cache_creation_tokens: usage.cache_creation_input_tokens, + cache_read_tokens: usage.cache_read_input_tokens, + }); + + let status = child + .wait() + .map_err(|e| AgentError::new(format!("the agent did not exit cleanly: {e}")))?; + + if let Some(outcome) = outcome { + Ok(outcome) + } else { + let stderr_output = stderr.finish(); + let detail = if stderr_output.is_empty() { + String::new() + } else { + format!(": {stderr_output}") + }; + Err(AgentError::new(format!( + "the agent produced no result line (exit {}){detail}", + status.code().unwrap_or(-1) + ))) + } + } +} + +// --------------------------------------------------------------------------- +// Tests +// --------------------------------------------------------------------------- + +#[cfg(test)] +mod pinned_tests; + +#[cfg(test)] +mod tests; diff --git a/src/agent/codex/tests.rs b/src/agent/codex/tests.rs new file mode 100644 index 0000000..0b0430a --- /dev/null +++ b/src/agent/codex/tests.rs @@ -0,0 +1,730 @@ +use std::io::{BufRead, BufReader}; +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; + +use super::*; + +/// Issue #3: launched from inside another agent session, a child that +/// inherits its variables reports that session as its own — on both the +/// fresh and the resumed spawn. +#[test] +fn the_cli_never_joins_the_session_that_launched_incode() { + let mut backend = CodexBackend::new(PathBuf::from(".")); + for resumed in [false, true] { + if resumed { + backend.thread_id = Some("t-1".to_string()); + } + let cmd = backend.command("p"); + assert!( + cmd.get_envs() + .any(|(k, v)| k == "CLAUDECODE" && v.is_none()), + "CLAUDECODE is inherited (resumed={resumed}), so the child joins the parent's session" + ); + } +} + +#[test] +fn foreign_model_id_is_dropped() { + let mut backend = CodexBackend::new(PathBuf::from(".")); + backend.set_models(&[ + "claude-sonnet-4-6".to_string(), + "gemini-3.8-flash-high".to_string(), + ]); + assert_eq!(backend.model(), None); + + backend.set_models(&["claude-sonnet-4-6".to_string(), "gpt-5.6-terra".to_string()]); + assert_eq!(backend.model(), Some("gpt-5.6-terra")); +} + +#[test] +fn role_ladder_contains_supported_models() { + let backend = CodexBackend::new(PathBuf::from(".")); + for role in crate::roles::KNOWN_ROLES { + for id in backend.ladder_for(role) { + assert!( + backend.serves(&id), + "role {role} drew model {id} which codex cannot serve" + ); + } + } + assert_ne!( + backend.ladder_for("explore"), + backend.ladder_for("implement") + ); +} + +#[test] +fn harness_context_is_carried_in_prompt() { + let bare = CodexBackend::new(PathBuf::from(".")); + assert_eq!( + bare.full_prompt("fix the bug").expect("sent"), + "fix the bug" + ); + + let briefed = CodexBackend::new(PathBuf::from(".")) + .with_system_context(vec!["Guards: no writes outside src/".to_string()]); + let sent = briefed.full_prompt("fix the bug").expect("sent"); + assert!(sent.contains("Guards: no writes outside src/")); + assert!(sent.ends_with("fix the bug")); +} + +#[test] +fn enforces_claims_nothing() { + let backend = CodexBackend::new(PathBuf::from(".")); + assert_eq!(backend.enforces(), crate::guards::Enforcement::NOTHING); +} + +/// **A TURN'S PICTURES GO AS `--image` FILES, BEFORE ANY OTHER FLAG**, on +/// a new thread and on a resumed one, so the prompt is never read as one +/// more file; the files are removed when the turn's hold on them ends. +#[test] +fn pictures_go_first_as_image_files_and_are_removed_after() { + let picture = crate::toolbox::Image::from_base64( + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC", + ) + .expect("a 1x1 png"); + let files = ImageFiles::write(std::slice::from_ref(&picture)).expect("written"); + let path = files.paths[0].clone(); + assert_eq!(std::fs::read(&path).expect("on disk"), picture.bytes()); + let mut backend = CodexBackend::new(PathBuf::from(".")); + backend.image_files.clone_from(&files.paths); + for resumed in [false, true] { + if resumed { + backend.thread_id = Some("t-1".to_string()); + } + let args: Vec = backend + .command("the prompt") + .get_args() + .map(|a| a.to_string_lossy().into_owned()) + .collect(); + let at = if resumed { 2 } else { 1 }; + assert_eq!(args[at], "--image", "{args:?}"); + assert_eq!(args[at + 1], path.to_string_lossy(), "{args:?}"); + assert!( + args[at + 2].starts_with("--"), + "the list is ended: {args:?}" + ); + assert_eq!(args.last().map(String::as_str), Some("the prompt")); + } + drop(files); + assert!(!path.exists(), "the picture outlived its turn"); +} + +#[test] +fn command_includes_mcp_auto_approval_config() { + let backend = CodexBackend::new(PathBuf::from(".")); + let cmd = backend.command("test prompt"); + let args: Vec = cmd.get_args().map(|a| a.to_os_string()).collect(); + let args_str: Vec = args + .iter() + .map(|a| a.to_string_lossy().to_string()) + .collect(); + assert!( + args_str + .windows(2) + .any(|w| w[0] == "-c" && w[1].contains("default_tools_approval_mode=\"auto\"")), + "codex command must include auto approval for memory MCP tools so calls are not cancelled" + ); +} + +/// **THE TEAM IDENTITY MUST REACH THE SPAWNED PROCESS'S ENVIRONMENT.** +/// +/// The team MCP server is a child of the agent and reads who it speaks +/// for from this variable. It cannot come from the MCP registration — +/// that is written once and the role changes every task — so if it does +/// not land on the spawn, every mid-turn message is filed as `unrouted` +/// and the channel stops being addressable. +#[test] +fn the_team_identity_is_set_on_the_spawn() { + let mut backend = CodexBackend::new(PathBuf::from(".")); + backend.set_team_identity("implement"); + + let cmd = backend.command("test prompt"); + let found = cmd + .get_envs() + .find(|(k, _)| *k == std::ffi::OsStr::new(crate::team_mcp::IDENTITY_ENV)); + + let (_, value) = found.expect("the identity never reached the environment"); + assert_eq!( + value.expect("a value").to_string_lossy(), + "implement", + "the agent would speak under the wrong name" + ); + + // And a backend nobody told stays silent rather than inventing one. + let plain = CodexBackend::new(PathBuf::from(".")); + assert!( + !plain + .command("p") + .get_envs() + .any(|(k, _)| k == std::ffi::OsStr::new(crate::team_mcp::IDENTITY_ENV)), + "an identity was invented for a task that had no role" + ); +} + +/// **THE DESKTOP MUST REACH ARGV, ON BOTH SPAWN PATHS.** +/// +/// `mcp_config()` is an accessor — it reads the field back and would keep +/// answering after the `-c` loops were deleted. What the spawned process +/// actually receives is argv, so that is what this asserts. Both paths, +/// because `command` (`argv.rs`) builds a *different* argument list when +/// resuming a thread than when starting fresh: wiring one and forgetting +/// the other is a desktop that works until the first resume. +#[test] +fn the_desktop_overrides_reach_argv_on_both_spawn_paths() { + let overrides = crate::desktop::mcp::codex_config_overrides( + std::path::Path::new(r"C:\Users\someone\incode.exe"), + Some(std::path::Path::new(r"C:\work\.incode\desktop.jsonl")), + crate::permissions::PermissionMode::WorkspaceWrite, + ); + + let argv = |backend: &CodexBackend| -> Vec { + backend + .command("test prompt") + .get_args() + .map(|a| a.to_string_lossy().to_string()) + .collect() + }; + let carries = |args: &[String]| { + args.windows(2) + .filter(|w| w[0] == "-c" && w[1].starts_with("mcp_servers.desktop.")) + .count() + }; + + let fresh = CodexBackend::new(PathBuf::from(".")).with_mcp_overrides(overrides.clone()); + assert_eq!( + carries(&argv(&fresh)), + overrides.len(), + "fresh spawn dropped the desktop: {:?}", + argv(&fresh) + ); + + let mut resumed = CodexBackend::new(PathBuf::from(".")).with_mcp_overrides(overrides.clone()); + resumed.thread_id = Some("thread-abc".to_string()); + assert_eq!( + carries(&argv(&resumed)), + overrides.len(), + "resume spawn dropped the desktop: {:?}", + argv(&resumed) + ); + + // And without it, nothing: the flag is not unconditional. + let plain = CodexBackend::new(PathBuf::from(".")); + assert_eq!(carries(&argv(&plain)), 0); +} + +/// **CODEX'S OWN HOOKS ARE OFF ON BOTH SPAWN PATHS.** incode fires the +/// memory engine's lifecycle itself; codex loading its hooks file too +/// would record every session twice, under two ids. +#[test] +fn codex_is_started_with_its_own_hooks_off_on_both_paths() { + let off = |backend: &CodexBackend| { + let args: Vec = backend + .command("hi") + .get_args() + .map(|a| a.to_string_lossy().to_string()) + .collect(); + args.windows(2) + .any(|w| w[0] == "--disable" && w[1] == "hooks") + }; + let fresh = CodexBackend::new(PathBuf::from(".")); + assert!(off(&fresh)); + let mut resumed = CodexBackend::new(PathBuf::from(".")); + resumed.thread_id = Some("thread-abc".to_string()); + assert!(off(&resumed)); + for mut backend in [fresh, resumed] { + backend = backend.with_tools(CodexTools::Incode); + assert!(off(&backend), "bridged too"); + } +} + +// ----------------------------------------------------------------------- +// Bridged: codex as a model, incode's toolbox as its tools. +// ----------------------------------------------------------------------- + +fn args_of(cmd: &Command) -> Vec { + cmd.get_args() + .map(|a| a.to_string_lossy().into_owned()) + .collect() +} + +/// Every `-c` value on an argv. +fn overrides_in(args: &[String]) -> Vec { + args.windows(2) + .filter(|w| w[0] == "-c") + .map(|w| w[1].clone()) + .collect() +} + +/// **CODEX ON ITS OWN TOOLS IS STARTED EXACTLY AS BEFORE.** The whole argv, +/// both spawn paths, pinned: the bridged route must not leak a flag onto +/// the route that has run live. +#[test] +fn the_own_tools_argv_is_unchanged() { + let mut backend = CodexBackend::new(PathBuf::from(".")) + .with_mcp_overrides(vec!["mcp_servers.team.command=\"incode\"".to_string()]); + backend.set_models(&["gpt-5.5".to_string()]); + backend.set_permission_mode("plan"); + backend.set_extra_dirs(vec![PathBuf::from("/more")]); + let auto = "mcp_servers.memory.default_tools_approval_mode=\"auto\""; + let team = "mcp_servers.team.command=\"incode\""; + assert_eq!( + args_of(&backend.command("the task")), + [ + "exec", + "--skip-git-repo-check", + "--json", + "--disable", + "hooks", + "-c", + auto, + "-c", + team, + "-s", + "read-only", + "-m", + "gpt-5.5", + "--add-dir", + "/more", + "-C", + ".", + "the task", + ] + ); + backend.thread_id = Some("t-1".to_string()); + assert_eq!( + args_of(&backend.command("again")), + [ + "exec", + "resume", + "--skip-git-repo-check", + "--json", + "--disable", + "hooks", + "--dangerously-bypass-approvals-and-sandbox", + "-c", + auto, + "-c", + team, + "-m", + "gpt-5.5", + "t-1", + "again", + ] + ); + assert!(!backend.runs_tools_here()); + assert!(backend.offered_tools().is_empty()); +} + +/// **BRIDGED, CODEX IS STARTED AS A MODEL AND NOTHING ELSE**, on both +/// spawn paths: its user config unread, every tool switch off, read-only +/// and never asking, and incode's tool server its one MCP server — and +/// none of the flags the other route hands it, because incode's toolbox +/// decides what they decided. +#[test] +fn bridged_codex_is_started_as_a_model_with_incodes_server_only() { + let exe = Path::new(r"C:\Program Files\incode\incode.exe"); + let mut backend = CodexBackend::new(PathBuf::from(".")) + .with_mcp_overrides(vec!["mcp_servers.team.command=\"incode\"".to_string()]) + .with_tools(CodexTools::Incode); + backend.set_models(&["gpt-5.5".to_string()]); + backend.set_permission_mode("acceptEdits"); + backend.set_extra_dirs(vec![PathBuf::from("/more")]); + backend.set_team_identity("implement"); + for resumed in [false, true] { + if resumed { + backend.thread_id = Some("t-1".to_string()); + } + let cmd = backend.bridged_command("the task", exe); + let args = args_of(&cmd); + let lead: &[&str] = if resumed { + &["exec", "resume"] + } else { + &["exec"] + }; + assert_eq!(&args[..lead.len()], lead, "{args:?}"); + for flag in ["--skip-git-repo-check", "--json", "--ignore-user-config"] { + assert!(args.iter().any(|a| a == flag), "{flag}: {args:?}"); + } + assert!(args.windows(2).any(|w| w == ["--disable", "hooks"])); + let overrides = overrides_in(&args); + let mut expected: Vec = MODEL_ONLY_OVERRIDES + .iter() + .map(|o| (*o).to_string()) + .collect(); + expected.extend([ + r#"mcp_servers.incode.command="C:\\Program Files\\incode\\incode.exe""#.to_string(), + r#"mcp_servers.incode.args=["--tool-server"]"#.to_string(), + r#"mcp_servers.incode.env_vars=["INCODE_TOOL_BRIDGE","INCODE_TOOL_TOKEN"]"#.to_string(), + r#"mcp_servers.incode.default_tools_approval_mode="approve""#.to_string(), + "mcp_servers.incode.required=true".to_string(), + "mcp_servers.incode.tool_timeout_sec=3600".to_string(), + r#"mcp_servers.incode.omit_tools_from=["deferred"]"#.to_string(), + ]); + assert_eq!(overrides, expected, "resumed={resumed}"); + for gone in [ + "--dangerously-bypass-approvals-and-sandbox", + "-s", + "--add-dir", + ] { + assert!(!args.iter().any(|a| a == gone), "{gone}: {args:?}"); + } + assert!( + !overrides + .iter() + .any(|o| o.starts_with("mcp_servers.team.") || o.starts_with("mcp_servers.memory.")), + "a server beside the bridge: {overrides:?}" + ); + assert_eq!( + args.iter().any(|a| a == "-C"), + !resumed, + "`exec resume` takes no -C: {args:?}" + ); + assert_eq!(args.last().map(String::as_str), Some("the task")); + if resumed { + assert_eq!(args[args.len() - 2], "t-1", "{args:?}"); + } + assert!( + !cmd.get_envs() + .any(|(k, _)| k == std::ffi::OsStr::new(crate::team_mcp::IDENTITY_ENV)), + "the team identity is the toolbox's on this route" + ); + assert!( + cmd.get_envs() + .any(|(k, v)| k == "CLAUDECODE" && v.is_none()), + "issue #3 on this route too" + ); + } + // The mode and the roots went to the toolbox, not to codex. + assert_eq!(backend.sandbox, None); +} + +/// Bridged, the backend says so to every caller that asks: its calls run +/// here, it enforces both halves, and it offers the toolbox's tools. +#[test] +fn bridged_codex_runs_its_tools_here() { + let backend = CodexBackend::new(PathBuf::from(".")).with_tools(CodexTools::Incode); + assert!(backend.runs_tools_here()); + assert_eq!(backend.enforces(), crate::guards::Enforcement::EVERYTHING); + let tools = backend.offered_tools(); + for tool in ["Read", "Write", "Edit", "Bash", "team_ask"] { + assert!(tools.iter().any(|t| t == tool), "{tool}: {tools:?}"); + } + assert!( + backend + .mcp_config() + .is_some_and(|c| c.contains("--tool-server")), + "{:?}", + backend.mcp_config() + ); + // And setting it back to codex's own is the route as it was. + let own = CodexBackend::new(PathBuf::from(".")) + .with_tools(CodexTools::Incode) + .with_tools(CodexTools::Own); + assert!(!own.runs_tools_here()); + assert_eq!(own.mcp_config(), None); +} + +#[test] +fn the_setting_spells_own_and_incode() { + assert_eq!(CodexTools::parse("own"), Some(CodexTools::Own)); + assert_eq!(CodexTools::parse(" INCODE "), Some(CodexTools::Incode)); + assert_eq!(CodexTools::parse("bridge"), None); + assert_eq!(CodexTools::parse(""), None); + assert_eq!(CodexTools::default(), CodexTools::Own); + for tools in [CodexTools::Own, CodexTools::Incode] { + assert_eq!(CodexTools::parse(tools.as_str()), Some(tools)); + } +} + +// ----------------------------------------------------------------------- +// The flow, end to end, with a stand-in codex. +// ----------------------------------------------------------------------- + +/// Set only in the stand-in codex the flow test starts: the directory it +/// reads its argv from. +const FAKE_CODEX: &str = "INCODE_FAKE_CODEX"; +/// Set only in the stand-in tool server the stand-in codex starts. +const FAKE_TOOL_SERVER: &str = "INCODE_FAKE_TOOL_SERVER"; + +/// The value of the `-c` override for `key`, as codex's TOML reads it. +fn override_value<'a>(overrides: &'a [String], key: &str) -> &'a str { + overrides + .iter() + .find_map(|o| o.strip_prefix(&format!("{key}="))) + .unwrap_or_else(|| panic!("no {key} among {overrides:?}")) +} + +/// The tool server half, as `incode --tool-server` runs it. +#[test] +fn tool_server_child() { + if std::env::var_os(FAKE_TOOL_SERVER).is_none() { + return; + } + let _ = crate::tool_bridge::run_stdio(); + std::process::exit(0); +} + +/// A stand-in codex: reads the argv it was started with, starts the MCP +/// server it was told to — with ONLY the variables `env_vars` names, as +/// codex does — and, over MCP stdio, lists the tools and calls `Write` +/// twice. It prints what it did as `codex exec --json` lines. +#[test] +fn fake_codex_child() { + use std::io::Write as _; + let Some(dir) = std::env::var_os(FAKE_CODEX) else { + return; + }; + let dir = PathBuf::from(dir); + let argv = std::fs::read(dir.join("argv")).expect("argv"); + let args: Vec = argv + .split(|b| *b == 0) + .filter(|a| !a.is_empty()) + .map(|a| String::from_utf8_lossy(a).into_owned()) + .collect(); + let overrides = overrides_in(&args); + let command = override_value(&overrides, "mcp_servers.incode.command") + .trim_matches('"') + .replace("\\\\", "\\"); + let server_args: Vec = + serde_json::from_str(override_value(&overrides, "mcp_servers.incode.args")).expect("args"); + let passed: Vec = + serde_json::from_str(override_value(&overrides, "mcp_servers.incode.env_vars")) + .expect("env_vars"); + let mut server = std::process::Command::new(&command) + .args(&server_args) + .env_clear() + .env("PATH", std::env::var_os("PATH").unwrap_or_default()) + .envs( + passed + .iter() + .filter_map(|name| Some((name, std::env::var_os(name)?))), + ) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .spawn() + .expect("start the tool server"); + let mut to = server.stdin.take().expect("stdin"); + let mut from = BufReader::new(server.stdout.take().expect("stdout")); + let mut ask = |id: u64, method: &str, params: serde_json::Value| -> serde_json::Value { + let request = serde_json::json!({"jsonrpc":"2.0","id":id,"method":method,"params":params}); + writeln!(to, "{request}").expect("send"); + to.flush().expect("flush"); + loop { + let mut line = String::new(); + if from.read_line(&mut line).expect("read") == 0 { + panic!("the tool server went away"); + } + // The test harness's own banner is not a reply. + if let Ok(reply) = serde_json::from_str::(&line) { + if reply["id"] == id { + return reply; + } + } + } + }; + let say = |line: serde_json::Value| println!("{line}"); + say(serde_json::json!({"type":"thread.started","thread_id":"fake-thread"})); + say(serde_json::json!({"type":"turn.started"})); + ask( + 0, + "initialize", + serde_json::json!({"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"fake-codex","version":"0"}}), + ); + let listed = ask(1, "tools/list", serde_json::json!({})); + let names: Vec<&str> = listed["result"]["tools"] + .as_array() + .map(|t| t.iter().filter_map(|t| t["name"].as_str()).collect()) + .unwrap_or_default(); + say( + serde_json::json!({"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":format!("tools: {}", names.join(","))}}), + ); + for (n, path) in [(2, "notes.txt"), (3, "secret.txt")] { + let arguments = serde_json::json!({"path": path, "content": "written"}); + let item = format!("item_{n}"); + say( + serde_json::json!({"type":"item.started","item":{"id":item,"type":"mcp_tool_call","server":"incode","tool":"Write","arguments":arguments,"result":null,"error":null,"status":"in_progress"}}), + ); + let reply = ask( + n, + "tools/call", + serde_json::json!({"name":"Write","arguments":arguments}), + ); + let failed = reply["result"]["isError"] == true; + say( + serde_json::json!({"type":"item.completed","item":{"id":item,"type":"mcp_tool_call","server":"incode","tool":"Write","arguments":arguments, + "result": if failed { serde_json::Value::Null } else { serde_json::json!({"content": reply["result"]["content"]}) }, + "error": if failed { serde_json::json!({"message": reply["result"]["content"][0]["text"]}) } else { serde_json::Value::Null }, + "status": if failed { "failed" } else { "completed" }}}), + ); + } + drop(to); + let _ = server.wait(); + say( + serde_json::json!({"type":"item.completed","item":{"id":"item_9","type":"agent_message","text":"done"}}), + ); + say(serde_json::json!({"type":"turn.completed","usage":{"input_tokens":1,"output_tokens":1}})); + std::process::exit(0); +} + +/// A shell script at `path` that runs this test binary's `test` with +/// `marker` set to `value`, after `before`. +#[cfg(unix)] +fn child_script(path: &Path, before: &str, marker: &str, value: &Path, test: &str) { + use std::os::unix::fs::PermissionsExt; + let exe = std::env::current_exe().expect("test binary"); + let body = format!( + "#!/bin/sh\n{before}\n{marker}='{}' exec '{}' --exact '{test}' --nocapture -q --test-threads=1\n", + value.display(), + exe.display() + ); + std::fs::write(path, body).expect("write the script"); + std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).expect("runnable"); +} + +/// A bridged backend in `ws` whose "codex" is the stand-in in `bin` — which +/// records its argv to `bin/argv` — and whose tool server is the stand-in +/// server, returned beside it; with a deny rule on `Write(secret.txt)` in +/// incode's toolbox. +/// +/// Called by [`a_bridged_turn_runs_its_calls_in_incodes_toolbox_and_a_deny_rule_refuses_one`]. +#[cfg(unix)] +fn stand_in_bridged_backend(ws: &Path, bin: &Path) -> (CodexBackend, PathBuf) { + let codex = bin.join("codex.sh"); + let server = bin.join("server.sh"); + child_script( + &codex, + &format!("printf '%s\\0' \"$@\" > '{}'", bin.join("argv").display()), + FAKE_CODEX, + bin, + "agent::codex::tests::fake_codex_child", + ); + child_script( + &server, + "", + FAKE_TOOL_SERVER, + Path::new("1"), + "agent::codex::tests::tool_server_child", + ); + + let mut backend = CodexBackend::new(ws.to_path_buf()) + .with_binary(codex.to_string_lossy()) + .with_tools(CodexTools::Incode) + .with_tool_server(server.clone()); + let mut rules = crate::permissions::rules::PermissionRules::none(); + rules.add( + &crate::permissions::rules::RuleLists { + deny: vec!["Write(secret.txt)".to_string()], + ..Default::default() + }, + crate::permissions::rules::Layer::User, + None, + ); + backend + .tools + .as_mut() + .expect("bridged") + .set_permission_rules(rules); + (backend, server) +} + +/// Every tool use a turn showed, as `(id, name)`. +/// +/// Called by [`a_bridged_turn_runs_its_calls_in_incodes_toolbox_and_a_deny_rule_refuses_one`]. +#[cfg(unix)] +fn uses_in(seen: &[AgentEvent]) -> Vec<(&str, &str)> { + seen.iter() + .filter_map(|e| match e { + AgentEvent::ToolUse { id, name, .. } => Some((id.as_str(), name.as_str())), + _ => None, + }) + .collect() +} + +/// Every tool result a turn showed, as `(id, is_error, output)`. +/// +/// Called by [`a_bridged_turn_runs_its_calls_in_incodes_toolbox_and_a_deny_rule_refuses_one`]. +#[cfg(unix)] +fn results_in(seen: &[AgentEvent]) -> Vec<(&str, bool, &str)> { + seen.iter() + .filter_map(|e| match e { + AgentEvent::ToolResult { + id, + is_error, + output, + } => Some((id.as_str(), *is_error, output.as_str())), + _ => None, + }) + .collect() +} + +/// **A BRIDGED CODEX TURN RUNS ITS TOOL CALLS IN incode's TOOLBOX**, end +/// to end: the backend opens the bridge and starts "codex" with the +/// bridged argv; the stand-in reads the registration off that argv, +/// starts the tool server with only the variables it names, and calls +/// `Write` twice over MCP. The first lands — written by incode. The +/// second is refused by a deny rule in incode's toolbox and nothing is +/// written. Each call is shown once, under incode's id; codex's record of +/// it is not shown again. +#[cfg(unix)] +#[test] +fn a_bridged_turn_runs_its_calls_in_incodes_toolbox_and_a_deny_rule_refuses_one() { + let ws = tempfile::tempdir().expect("ws"); + let bin = tempfile::tempdir().expect("bin"); + let (mut backend, server) = stand_in_bridged_backend(ws.path(), bin.path()); + + let mut seen = Vec::new(); + let outcome = backend + .run_turn("write two files", &mut |e| seen.push(e.clone())) + .expect("the turn completes"); + assert!(!outcome.is_error, "{outcome:?}"); + assert_eq!(outcome.session_id, "fake-thread"); + assert_eq!(backend.session_id(), Some("fake-thread")); + + // The argv codex was really started with: the bridged one. + let argv = + String::from_utf8(std::fs::read(bin.path().join("argv")).expect("argv")).expect("utf-8"); + assert!(argv.contains("--ignore-user-config"), "{argv:?}"); + assert!(argv.contains("features.shell_tool=false"), "{argv:?}"); + assert!( + argv.contains(&format!( + "mcp_servers.incode.command=\"{}\"", + server.display() + )), + "{argv:?}" + ); + + // The model saw incode's tools. + assert!( + seen.iter().any(|e| matches!(e, AgentEvent::Text(t) if t.starts_with("tools: ") && t.contains("Write") && t.contains("Read"))), + "{seen:?}" + ); + // The first call ran in incode's toolbox; the second was refused there. + assert_eq!( + std::fs::read_to_string(ws.path().join("notes.txt")).expect("written by incode"), + "written" + ); + assert!( + !ws.path().join("secret.txt").exists(), + "the deny rule did not hold" + ); + assert_eq!( + uses_in(&seen), + [("incode-1", "Write"), ("incode-2", "Write")], + "each call once, under incode's id: {seen:?}" + ); + let results = results_in(&seen); + assert_eq!(results.len(), 2, "{seen:?}"); + assert_eq!((results[0].0, results[0].1), ("incode-1", false)); + assert_eq!((results[1].0, results[1].1), ("incode-2", true)); + assert!( + results[1].2.contains("Write(secret.txt)"), + "refused by the rule, by name: {}", + results[1].2 + ); + assert!( + seen.iter() + .any(|e| matches!(e, AgentEvent::Text(t) if t == "done")), + "{seen:?}" + ); +} diff --git a/src/agent/codex/wire.rs b/src/agent/codex/wire.rs new file mode 100644 index 0000000..534276b --- /dev/null +++ b/src/agent/codex/wire.rs @@ -0,0 +1,396 @@ +//! What `codex exec --json` prints, and what each line of it means — the same +//! reading on both routes. +//! +//! Wired to: [`super::CodexBackend`]'s `run_turn` on codex's own tools, and +//! its bridged turn (`bridged.rs`), each reading the child's stdout a line +//! at a time through [`Reading::line`]. + +use serde::Deserialize; + +use crate::agent::{AgentEvent, TurnOutcome}; + +// --------------------------------------------------------------------------- +// Wire types — measured from real Codex CLI runs +// --------------------------------------------------------------------------- + +/// One line of `codex exec --json`. +/// +/// Tagged on `type`. +#[derive(Debug, Deserialize)] +#[serde(tag = "type")] +enum Wire { + #[serde(rename = "thread.started")] + ThreadStarted { thread_id: String }, + #[serde(rename = "turn.started")] + TurnStarted, + #[serde(rename = "item.started")] + ItemStarted { item: WireItem }, + #[serde(rename = "item.completed")] + ItemCompleted { item: WireItem }, + #[serde(rename = "turn.completed")] + TurnCompleted { + #[serde(default)] + usage: Option, + }, + #[serde(rename = "turn.failed")] + TurnFailed { + #[serde(default)] + error: Option, + }, + #[serde(rename = "error")] + Error { + #[serde(default)] + message: Option, + }, + #[serde(other)] + Other, +} + +#[derive(Debug, Default, Deserialize)] +struct WireItem { + #[serde(default)] + id: String, + #[serde(rename = "type", default)] + item_type: String, + #[serde(default)] + text: Option, + #[serde(default)] + command: Option, + #[serde(default)] + aggregated_output: Option, + #[serde(default)] + exit_code: Option, + #[serde(default)] + server: Option, + #[serde(default)] + tool: Option, + #[serde(default)] + arguments: Option, + #[serde(default)] + result: Option, + #[serde(default)] + error: Option, + #[serde(default)] + status: Option, +} + +#[derive(Debug, Default, Deserialize)] +struct WireUsage { + #[serde(default)] + input_tokens: u32, + #[serde(default)] + cached_input_tokens: u32, + #[serde(default)] + cache_write_input_tokens: u32, + #[serde(default)] + output_tokens: u32, + #[allow(dead_code)] + #[serde(default)] + reasoning_output_tokens: u32, +} + +#[derive(Debug, Default, Deserialize)] +struct WireError { + #[serde(default)] + message: String, +} + +impl WireItem { + /// The call's input as the model wrote it: its arguments as JSON, or + /// nothing. + /// + /// Called by [`Reading::item_started`] and [`Reading::mcp_call_completed`]. + fn input(&self) -> String { + self.arguments + .as_ref() + .map(|a| a.to_string()) + .unwrap_or_default() + } + + /// What a finished MCP call answered: the text of its result, or — when + /// that is empty — its error, unpacked. + /// + /// Called by [`Reading::mcp_call_completed`]. + fn mcp_output(&self) -> String { + let mut output = extract_mcp_output(&self.result); + if output.is_empty() { + if let Some(err) = &self.error { + output = err + .as_str() + .map(|s| s.to_string()) + .unwrap_or_else(|| parse_error_detail(&err.to_string())); + } + } + output + } + + /// Whether a finished MCP call failed: it carries an error, or says so. + /// + /// Called by [`Reading::mcp_call_completed`]. + fn mcp_failed(&self) -> bool { + self.error.is_some() || self.status.as_deref() == Some("failed") + } +} + +/// A shell command codex ran, as the use it stands for. +/// +/// Called by [`Reading::item_started`] and [`Reading::item_completed`]. +fn bash_use(id: String, command: String) -> AgentEvent { + AgentEvent::ToolUse { + id, + name: "Bash".to_string(), + input: command, + } +} + +// --------------------------------------------------------------------------- +// Reading +// --------------------------------------------------------------------------- + +/// What one turn of `codex exec --json` has said so far, and what each line +/// means — the same reading on both routes. +pub(super) struct Reading<'a> { + /// The backend's own: a thread that started is resumable even if the + /// turn is then stopped. + thread_id: &'a mut Option, + model: Option, + outcome: Option, + usage: crate::runtime::usage::TokenUsage, + /// Bridged: a call to incode's own server is shown by the bridge, as + /// incode ran it, under incode's id; codex's record of the same call is + /// not shown a second time. + bridged: bool, +} + +impl<'a> Reading<'a> { + /// Called by the backend's `run_turn` and its bridged turn, once per turn. + pub(super) fn new( + thread_id: &'a mut Option, + model: Option, + bridged: bool, + ) -> Self { + Self { + thread_id, + model, + outcome: None, + usage: crate::runtime::usage::TokenUsage::default(), + bridged, + } + } + + /// The turn's result, if it reported one, and what it cost. + pub(super) fn finish(self) -> (Option, crate::runtime::usage::TokenUsage) { + (self.outcome, self.usage) + } + + /// Whether an item is codex's own echo of a call the bridge already showed. + fn shown_by_the_bridge(&self, item: &WireItem) -> bool { + self.bridged && item.server.as_deref() == Some(crate::tool_bridge::CLIENT_KEY) + } + + /// The events one line stands for. A line that is not one of codex's is + /// nothing. + pub(super) fn line(&mut self, line: &str) -> Vec { + let Ok(wire) = serde_json::from_str::(line) else { + return Vec::new(); + }; + match wire { + Wire::ThreadStarted { thread_id } => vec![self.thread_started(thread_id)], + Wire::ItemStarted { item } => self.item_started(item), + Wire::ItemCompleted { item } => self.item_completed(item), + Wire::TurnCompleted { usage } => { + self.turn_completed(usage.as_ref()); + Vec::new() + } + Wire::TurnFailed { error } => { + let detail = error + .map(|e| parse_error_detail(&e.message)) + .unwrap_or_else(|| "turn failed".to_string()); + self.failed(detail); + Vec::new() + } + Wire::Error { message } => { + let detail = message + .map(|m| parse_error_detail(&m)) + .unwrap_or_else(|| "codex error".to_string()); + self.failed(detail); + Vec::new() + } + Wire::TurnStarted | Wire::Other => Vec::new(), + } + } + + /// The thread is codex's session: held as the backend's, and announced. + /// + /// Called by [`Self::line`]. + fn thread_started(&mut self, thread_id: String) -> AgentEvent { + *self.thread_id = Some(thread_id.clone()); + AgentEvent::SessionStarted { + session_id: thread_id, + model: self.model.clone().unwrap_or_default(), + } + } + + /// A call starting: its use, for a shell command or an MCP call that + /// names its tool. + /// + /// Called by [`Self::line`]. + fn item_started(&self, item: WireItem) -> Vec { + if self.shown_by_the_bridge(&item) { + return Vec::new(); + } + match item.item_type.as_str() { + "command_execution" => item + .command + .map(|cmd| bash_use(item.id, cmd)) + .into_iter() + .collect(), + "mcp_tool_call" => { + let input = item.input(); + item.tool + .map(|tool| AgentEvent::ToolUse { + id: item.id, + name: tool, + input, + }) + .into_iter() + .collect() + } + _ => Vec::new(), + } + } + + /// An item finished: the reply's text, or a call's use and its result. + /// + /// Called by [`Self::line`]. + fn item_completed(&self, item: WireItem) -> Vec { + if self.shown_by_the_bridge(&item) { + return Vec::new(); + } + match item.item_type.as_str() { + "agent_message" => match item.text { + Some(text) if !text.trim().is_empty() => { + vec![AgentEvent::TextDelta(text.clone()), AgentEvent::Text(text)] + } + _ => Vec::new(), + }, + "command_execution" => match item.command { + Some(cmd) => vec![ + bash_use(item.id.clone(), cmd), + AgentEvent::ToolResult { + id: item.id, + output: item.aggregated_output.unwrap_or_default(), + is_error: item.exit_code.unwrap_or(0) != 0, + }, + ], + None => Vec::new(), + }, + "mcp_tool_call" => Self::mcp_call_completed(item), + "error" => { + if let Some(msg) = item.text { + crate::trace!("agent", "codex item error: {msg}"); + } + Vec::new() + } + _ => Vec::new(), + } + } + + /// A finished MCP call that names its tool: its use, then its result. + /// + /// Called by [`Self::item_completed`]. + fn mcp_call_completed(item: WireItem) -> Vec { + let input = item.input(); + let output = item.mcp_output(); + let is_error = item.mcp_failed(); + let Some(tool) = item.tool else { + return Vec::new(); + }; + vec![ + AgentEvent::ToolUse { + id: item.id.clone(), + name: tool, + input, + }, + AgentEvent::ToolResult { + id: item.id, + output, + is_error, + }, + ] + } + + /// The turn succeeded, at the cost it reported (if it reported one). + /// + /// Called by [`Self::line`]. + fn turn_completed(&mut self, usage: Option<&WireUsage>) { + if let Some(u) = usage { + self.usage = to_usage(u); + } + self.outcome = Some(self.outcome_of("SUCCESS", false, None)); + } + + /// The turn failed, for the reason given. + /// + /// Called by [`Self::line`], for `turn.failed` and `error`. + fn failed(&mut self, detail: String) { + self.outcome = Some(self.outcome_of("ERROR", true, Some(detail))); + } + + /// The turn's result on the thread it ran in, served by the model asked + /// for. + /// + /// Called by [`Self::turn_completed`] and [`Self::failed`]. + fn outcome_of(&self, stop_reason: &str, is_error: bool, detail: Option) -> TurnOutcome { + TurnOutcome { + session_id: self.thread_id.clone().unwrap_or_default(), + stop_reason: stop_reason.to_string(), + is_error, + detail, + served_by: self.model.clone().into_iter().collect(), + } + } +} + +/// Extract readable text from MCP tool result JSON. +fn extract_mcp_output(res: &Option) -> String { + let Some(val) = res else { + return String::new(); + }; + if let Some(content) = val.get("content").and_then(|c| c.as_array()) { + let texts: Vec<&str> = content + .iter() + .filter_map(|item| item.get("text").and_then(|t| t.as_str())) + .collect(); + if !texts.is_empty() { + return texts.join("\n"); + } + } + val.to_string() +} + +/// Parse error message, unpacking nested JSON error objects if present. +fn parse_error_detail(raw: &str) -> String { + if let Ok(v) = serde_json::from_str::(raw) { + if let Some(inner) = v.pointer("/error/message").and_then(|m| m.as_str()) { + return inner.to_string(); + } + if let Some(msg) = v.get("message").and_then(|m| m.as_str()) { + return msg.to_string(); + } + } + raw.to_string() +} + +fn to_usage(wire: &WireUsage) -> crate::runtime::usage::TokenUsage { + crate::runtime::usage::TokenUsage { + input_tokens: wire.input_tokens, + output_tokens: wire.output_tokens, + cache_creation_input_tokens: wire.cache_write_input_tokens, + cache_read_input_tokens: wire.cached_input_tokens, + } +} + +#[cfg(test)] +#[path = "wire_tests.rs"] +mod tests; diff --git a/src/agent/codex/wire_tests.rs b/src/agent/codex/wire_tests.rs new file mode 100644 index 0000000..5989e1e --- /dev/null +++ b/src/agent/codex/wire_tests.rs @@ -0,0 +1,191 @@ +//! The wire types and the reading of `codex exec --json`, moved here from +//! the tests of `src/agent/codex.rs` when it became a module directory. + +use super::*; + +fn parse(line: &str) -> Wire { + serde_json::from_str(line).expect("a wire line") +} + +#[test] +fn the_thread_started_line_sets_session_id() { + let wire = + parse(r#"{"type":"thread.started","thread_id":"01a081c2-bdb1-7c71-a922-9a10bbb2ccae"}"#); + match wire { + Wire::ThreadStarted { thread_id } => { + assert_eq!(thread_id, "01a081c2-bdb1-7c71-a922-9a10bbb2ccae"); + } + other => panic!("expected ThreadStarted: {other:?}"), + } +} + +#[test] +fn agent_message_item_is_parsed() { + let wire = parse( + r#"{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"The package name is incord-code."}}"#, + ); + match wire { + Wire::ItemCompleted { item } => { + assert_eq!(item.item_type, "agent_message"); + assert_eq!( + item.text.as_deref(), + Some("The package name is incord-code.") + ); + } + other => panic!("expected ItemCompleted: {other:?}"), + } +} + +#[test] +fn command_execution_item_is_parsed() { + let wire = parse( + r#"{"type":"item.completed","item":{"id":"item_5","type":"command_execution","command":"powershell.exe -Command Get-Location","aggregated_output":"C:\\Projects\\incord-code\n","exit_code":0,"status":"completed"}}"#, + ); + match wire { + Wire::ItemCompleted { item } => { + assert_eq!(item.item_type, "command_execution"); + assert_eq!( + item.command.as_deref(), + Some("powershell.exe -Command Get-Location") + ); + assert_eq!(item.exit_code, Some(0)); + } + other => panic!("expected ItemCompleted: {other:?}"), + } +} + +#[test] +fn mcp_tool_call_item_is_parsed() { + let wire = parse( + r#"{"type":"item.completed","item":{"id":"item_1","type":"mcp_tool_call","server":"memory","tool":"watchman_lookup","arguments":{"task":"C:\\Projects\\incord-code"},"result":{"content":[{"type":"text","text":"{\"hit\":false}"}]},"error":null,"status":"completed"}}"#, + ); + match wire { + Wire::ItemCompleted { item } => { + assert_eq!(item.item_type, "mcp_tool_call"); + assert_eq!(item.tool.as_deref(), Some("watchman_lookup")); + assert_eq!(extract_mcp_output(&item.result), "{\"hit\":false}"); + } + other => panic!("expected ItemCompleted: {other:?}"), + } +} + +#[test] +fn turn_completed_usage_is_parsed() { + let wire = parse( + r#"{"type":"turn.completed","usage":{"input_tokens":122070,"cached_input_tokens":112128,"cache_write_input_tokens":100,"output_tokens":438,"reasoning_output_tokens":83}}"#, + ); + match wire { + Wire::TurnCompleted { usage } => { + let u = to_usage(&usage.expect("usage")); + assert_eq!(u.input_tokens, 122070); + assert_eq!(u.cache_read_input_tokens, 112128); + assert_eq!(u.cache_creation_input_tokens, 100); + assert_eq!(u.output_tokens, 438); + } + other => panic!("expected TurnCompleted: {other:?}"), + } +} + +#[test] +fn turn_failed_unpacks_json_error() { + let wire = parse( + r#"{"type":"turn.failed","error":{"message":"{\"type\":\"error\",\"status\":400,\"error\":{\"type\":\"invalid_request_error\",\"message\":\"The 'bad-model' model is not supported.\"}}"}}"#, + ); + match wire { + Wire::TurnFailed { error } => { + let detail = parse_error_detail(&error.expect("error").message); + assert_eq!(detail, "The 'bad-model' model is not supported."); + } + other => panic!("expected TurnFailed: {other:?}"), + } +} + +/// The events a sequence of `codex exec --json` lines stands for. +fn read(lines: &[&str], bridged: bool) -> (Vec, Option) { + let mut thread = None; + let mut reading = Reading::new(&mut thread, Some("gpt-5.5".to_string()), bridged); + let events = lines.iter().flat_map(|l| reading.line(l)).collect(); + drop(reading); + (events, thread) +} + +/// An MCP call to incode's own server, in the shape `codex exec --json` +/// prints it (`exec/src/exec_events.rs` `McpToolCallItem`, 0.163.0): a +/// started item, then a completed one with the result's content blocks. +const INCODE_CALL: [&str; 2] = [ + r#"{"type":"item.started","item":{"id":"item_1","type":"mcp_tool_call","server":"incode","tool":"Write","arguments":{"path":"a.txt","content":"x"},"result":null,"error":null,"status":"in_progress"}}"#, + r#"{"type":"item.completed","item":{"id":"item_1","type":"mcp_tool_call","server":"incode","tool":"Write","arguments":{"path":"a.txt","content":"x"},"result":{"content":[{"type":"text","text":"wrote a.txt"}],"structured_content":null},"error":null,"status":"completed"}}"#, +]; + +/// **BRIDGED, A CALL TO incode's SERVER IS SHOWN ONCE — AS INCODE RAN +/// IT.** The bridge shows the call under incode's id when it runs it; +/// codex's own record of the same call is not shown again. A call to any +/// other server is still shown from codex's record. +#[test] +fn bridged_codex_does_not_show_incodes_calls_twice() { + let (events, _) = read(&INCODE_CALL, true); + assert!(events.is_empty(), "{events:?}"); + + let other = r#"{"type":"item.completed","item":{"id":"item_2","type":"mcp_tool_call","server":"elsewhere","tool":"lookup","arguments":{},"result":{"content":[{"type":"text","text":"found"}]},"error":null,"status":"completed"}}"#; + let (events, _) = read(&[other], true); + assert!( + matches!(&events[..], [AgentEvent::ToolUse { name, .. }, AgentEvent::ToolResult { output, is_error: false, .. }] if name == "lookup" && output == "found"), + "{events:?}" + ); +} + +/// On codex's own tools the same lines are its tool calls, mapped as +/// they always were: a use when the call starts, and the use and its +/// result when it completes. +#[test] +fn own_tools_codex_shows_an_mcp_call_from_its_record() { + let (events, _) = read(&INCODE_CALL, false); + assert!( + matches!( + &events[..], + [ + AgentEvent::ToolUse { id: a, name: n1, .. }, + AgentEvent::ToolUse { id: b, name: n2, input }, + AgentEvent::ToolResult { output, is_error: false, .. }, + ] if a == "item_1" && b == "item_1" && n1 == "Write" && n2 == "Write" + && input.contains("a.txt") && output == "wrote a.txt" + ), + "{events:?}" + ); +} + +/// A failed MCP call carries its error as an object — `{"message": …}`, +/// not a string — and is shown as a failed result with that message. +#[test] +fn a_failed_mcp_call_shows_its_message() { + let failed = r#"{"type":"item.completed","item":{"id":"item_3","type":"mcp_tool_call","server":"elsewhere","tool":"Write","arguments":{},"result":null,"error":{"message":"tool call timed out"},"status":"failed"}}"#; + let (events, _) = read(&[failed], false); + assert!( + matches!(&events[..], [_, AgentEvent::ToolResult { output, is_error: true, .. }] if output == "tool call timed out"), + "{events:?}" + ); +} + +/// The rest of a turn reads the same on both routes: the thread, the +/// reply, and the result. +#[test] +fn a_turn_reads_the_same_on_both_routes() { + let lines = [ + r#"{"type":"thread.started","thread_id":"th-1"}"#, + r#"{"type":"turn.started"}"#, + r#"Reading additional input from stdin..."#, + r#"{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"done"}}"#, + r#"{"type":"turn.completed","usage":{"input_tokens":3,"cached_input_tokens":1,"output_tokens":2}}"#, + ]; + let (own, own_thread) = read(&lines, false); + let (bridged, bridged_thread) = read(&lines, true); + assert_eq!(own, bridged); + assert_eq!(own_thread.as_deref(), Some("th-1")); + assert_eq!(bridged_thread.as_deref(), Some("th-1")); + assert!( + matches!(&own[0], AgentEvent::SessionStarted { session_id, .. } if session_id == "th-1") + ); + assert!(own + .iter() + .any(|e| matches!(e, AgentEvent::Text(t) if t == "done"))); +} diff --git a/src/agent/handover.rs b/src/agent/handover.rs new file mode 100644 index 0000000..8a55de9 --- /dev/null +++ b/src/agent/handover.rs @@ -0,0 +1,230 @@ +//! Whether a failed turn is the agent's own failure — out of room, signed +//! out, gone quiet — rather than the work's, which decides whether the work +//! moves to a standby agent. +//! +//! Wired to: [`super::AgentBackend::agent_failed`] (the default and each +//! backend's), and [`super::TurnOutcome::failure`] for the sign-in remedy. + +/// Whether a failure is the agent being unable to authenticate. +/// +/// Matched on the agent's own words rather than a status code, because the stop +/// reason does not distinguish it: the failure that started this arrived as +/// `stop_sequence` with the subtype `success`, and only the message said what +/// had actually happened. +#[must_use] +pub fn looks_like_auth_failure(detail: &str) -> bool { + let said = detail.to_ascii_lowercase(); + said.contains("authenticate") + || said.contains("unauthorized") + || said.contains("oauth") + || (said.contains("session") && said.contains("expired")) + || said.contains("log in") + || said.contains("login") +} + +/// Whether a failed turn failed because the agent ran out of room, rather than +/// because the work was wrong. +/// +/// The difference decides whether trying a DIFFERENT agent is sensible: a +/// subscription that is out of room will serve the same task fine tomorrow, or +/// on another subscription now. A task that is genuinely broken will fail +/// everywhere, and retrying it elsewhere just spends someone else's quota. +#[must_use] +pub fn is_limit_failure(reason: &str) -> bool { + let reason = reason.to_ascii_lowercase(); + let needles = [ + "rate limit", + "rate_limit", + "quota", + "usage limit", + "too many requests", + "429", + "overloaded", + "capacity", + "weekly limit", + "monthly limit", + "daily limit", + "hourly limit", + "limit reached", + "limit exceeded", + "reached your limit", + "hit your limit", + "exceeded your limit", + "out of credits", + "insufficient credits", + "credit balance", + "billing limit", + "plan limit", + "free tier limit", + "spending limit", + "token limit", + "request limit", + ]; + if needles.iter().any(|needle| reason.contains(needle)) { + return true; + } + if reason.contains("limit") + && (reason.contains("week") + || reason.contains("month") + || reason.contains("day") + || reason.contains("hour") + || reason.contains("credit") + || reason.contains("reset") + || reason.contains("exhaust") + || reason.contains("reach") + || reason.contains("exceed")) + { + return true; + } + false +} + +/// Whether this failure is the AGENT's rather than the WORK's. +/// +/// # Why a limit is not the only reason to move +/// +/// This used to be [`is_limit_failure`] alone, on the reasoning that a task +/// which failed because it is wrong will fail the same way everywhere — true, +/// and still the reason the list below is narrow rather than "anything". +/// +/// But it lumped a whole class in with the task's own faults. Measured: one +/// agent abandoned a task with `timeout waiting for response` at its own +/// deadline, having done real work; another rejected the turn outright with +/// `model sonnet is not recognized`. Neither says anything about the task, and +/// both would have succeeded on a different agent. The work stopped anyway, +/// with a standby sitting idle. +/// +/// So: a failure that names the AGENT's own state moves the work. A failure +/// that names the WORK — a check that did not pass, a guard that refused, a +/// contract that was broken — does not, because carrying it to a second +/// subscription only spends that one too. +#[must_use] +pub fn moves_the_work(reason: &str) -> bool { + if is_limit_failure(reason) { + return true; + } + // An account that cannot sign in cannot do ANY work, and a second agent + // authenticates separately — so this is the clearest case of all for + // handing over. Reusing [`looks_like_auth_failure`] rather than copying its + // needles: two lists of the same thing drift, and the one that drifts is + // never the one being read. + if looks_like_auth_failure(reason) { + return true; + } + let reason = reason.to_ascii_lowercase(); + [ + // The agent ran out of time on its own clock, not the harness's. + "timeout", + "timed out", + // The agent could not be started, spawned, or executed by the OS + // (missing binary, permission denied, Windows command line length limit os error 206, etc.). + "could not start", + "not installed", + "no output stream", + "did not exit cleanly", + "produced no result", + "failed to spawn", + "cannot spawn", + "unable to spawn", + "failed to execute", + "spawn", + "os error 206", + "os error", + "too long", + "filename or extension", + "command line too long", + "createprocess", + "executable file not found", + // The agent refused the request shape itself. + "not recognized", + "invalid model", + "unknown model", + // The agent's own transport gave out. + "connection", + "broken pipe", + // MEASURED, not guessed: a busy upstream model answered + // `status: ERROR, error: The stream was interrupted. Please continue + // the task you were working on.` — the agent's link to its provider + // broke mid-turn. It says nothing about the task, and it is the most + // common way a popular model fails, so a list without it leaves the + // standby idle exactly when it is most needed. + "stream was interrupted", + "stream interrupted", + ] + .iter() + .any(|needle| reason.contains(needle)) +} + +#[cfg(test)] +mod handover_tests { + use super::*; + + /// **An agent's own failure moves the work; the task's own does not.** + /// + /// Both halves matter. Measured failures that SHOULD move: a CLI that + /// abandoned a task at its own deadline, and one that rejected the turn + /// with `model sonnet is not recognized` — neither says anything about the + /// task. Failures that must NOT move: a check that did not pass or a guard + /// that refused will do the same on every agent, and carrying them spends a + /// second subscription to learn one thing. + #[test] + fn only_the_agents_own_failures_move_the_work() { + for agent_side in [ + "rate limit reached", + "the agent stopped without finishing (ERROR): timeout waiting for response", + "could not start `agy`: program not found", + "invalid model selection: model sonnet is not recognized", + "the agent produced no result line (exit 1)", + // Copied from a real busy-model reply, not composed here. + "The stream was interrupted. Please continue the task you were working on.", + ] { + assert!( + moves_the_work(agent_side), + "an agent-side failure must reach the standby: {agent_side}" + ); + } + + for task_side in [ + "`node --check game.js` exited 1", + "a protected file changed and the owner did not approve it", + "the contract for this task was broken", + "the agent finished but the check did not pass", + ] { + assert!( + !moves_the_work(task_side), + "a task-side failure must NOT walk through every subscription: {task_side}" + ); + } + } + + #[test] + fn weekly_and_credit_limits_move_the_work() { + assert!(moves_the_work( + "You've reached your weekly limit for Claude Code" + )); + assert!(moves_the_work("weekly limit reached")); + assert!(moves_the_work("exceeded your limit for the current period")); + assert!(moves_the_work("out of credits on this account")); + assert!(moves_the_work( + "monthly limit exceeded: try again next billing cycle" + )); + assert!(moves_the_work("daily request limit reached")); + } + + #[test] + fn spawn_and_os_errors_move_the_work() { + assert!(moves_the_work( + "failed to spawn `claude`: The filename or extension is too long. (os error 206)" + )); + assert!(moves_the_work( + "failed to spawn `claude`: No such file or directory (os error 2)" + )); + assert!(moves_the_work( + "failed to spawn `agy`: Access is denied. (os error 5)" + )); + assert!(moves_the_work("cannot spawn child process: os error 206")); + assert!(moves_the_work("command line too long")); + assert!(moves_the_work("failed to execute process")); + assert!(moves_the_work("CreateProcess failed")); + } +} diff --git a/src/agent/mod.rs b/src/agent/mod.rs index 6883771..3de771b 100644 --- a/src/agent/mod.rs +++ b/src/agent/mod.rs @@ -13,24 +13,40 @@ //! //! The harness never reads, copies or transmits an agent's credentials. It //! detects that a binary exists and lets the agent authenticate itself. +//! +//! # Layout +//! +//! This file holds what a turn produces ([`AgentEvent`], [`TurnOutcome`], +//! [`AgentError`]). The trait every route implements is in `backend.rs`, +//! whether a failure moves the work to another agent in `handover.rs`, and +//! the command-line budget for a prompt in `spawn_budget.rs` — each +//! re-exported here, so callers name them as `crate::agent::…`. pub mod agy; pub mod api; +mod backend; pub mod catalogue; pub mod claude_code; pub mod codex; pub mod compact; +mod handover; pub mod models; pub mod openai; pub mod parent_session; pub mod process_tree; pub mod registry; +mod spawn_budget; pub mod stderr_tail; pub mod worker; use std::fmt::{Display, Formatter}; +pub use backend::AgentBackend; +pub use handover::{is_limit_failure, looks_like_auth_failure, moves_the_work}; pub use registry::{discover, DetectedAgent, Protocol}; +pub use spawn_budget::{ + budget_for_spawn, MAX_CMDLINE_PAYLOAD_LEN, MAX_PROMPT_BUDGET, MIN_CONTEXT_BUDGET, +}; /// An event produced by an agent backend while running one turn. #[derive(Debug, Clone, PartialEq, Eq)] @@ -170,23 +186,6 @@ impl TurnOutcome { } } -/// Whether a failure is the agent being unable to authenticate. -/// -/// Matched on the agent's own words rather than a status code, because the stop -/// reason does not distinguish it: the failure that started this arrived as -/// `stop_sequence` with the subtype `success`, and only the message said what -/// had actually happened. -#[must_use] -pub fn looks_like_auth_failure(detail: &str) -> bool { - let said = detail.to_ascii_lowercase(); - said.contains("authenticate") - || said.contains("unauthorized") - || said.contains("oauth") - || (said.contains("session") && said.contains("expired")) - || said.contains("log in") - || said.contains("login") -} - /// The one quota status that means work can proceed. /// /// Captured from a real turn. The spelling of an EXHAUSTED status has not been @@ -201,603 +200,6 @@ pub fn is_limit_status(status: &str) -> bool { !status.trim().is_empty() && !status.eq_ignore_ascii_case(QUOTA_ALLOWED) } -/// Whether a failed turn failed because the agent ran out of room, rather than -/// because the work was wrong. -/// -/// The difference decides whether trying a DIFFERENT agent is sensible: a -/// subscription that is out of room will serve the same task fine tomorrow, or -/// on another subscription now. A task that is genuinely broken will fail -/// everywhere, and retrying it elsewhere just spends someone else's quota. -#[must_use] -pub fn is_limit_failure(reason: &str) -> bool { - let reason = reason.to_ascii_lowercase(); - let needles = [ - "rate limit", - "rate_limit", - "quota", - "usage limit", - "too many requests", - "429", - "overloaded", - "capacity", - "weekly limit", - "monthly limit", - "daily limit", - "hourly limit", - "limit reached", - "limit exceeded", - "reached your limit", - "hit your limit", - "exceeded your limit", - "out of credits", - "insufficient credits", - "credit balance", - "billing limit", - "plan limit", - "free tier limit", - "spending limit", - "token limit", - "request limit", - ]; - if needles.iter().any(|needle| reason.contains(needle)) { - return true; - } - if reason.contains("limit") - && (reason.contains("week") - || reason.contains("month") - || reason.contains("day") - || reason.contains("hour") - || reason.contains("credit") - || reason.contains("reset") - || reason.contains("exhaust") - || reason.contains("reach") - || reason.contains("exceed")) - { - return true; - } - false -} - -/// Whether this failure is the AGENT's rather than the WORK's. -/// -/// # Why a limit is not the only reason to move -/// -/// This used to be [`is_limit_failure`] alone, on the reasoning that a task -/// which failed because it is wrong will fail the same way everywhere — true, -/// and still the reason the list below is narrow rather than "anything". -/// -/// But it lumped a whole class in with the task's own faults. Measured: one -/// agent abandoned a task with `timeout waiting for response` at its own -/// deadline, having done real work; another rejected the turn outright with -/// `model sonnet is not recognized`. Neither says anything about the task, and -/// both would have succeeded on a different agent. The work stopped anyway, -/// with a standby sitting idle. -/// -/// So: a failure that names the AGENT's own state moves the work. A failure -/// that names the WORK — a check that did not pass, a guard that refused, a -/// contract that was broken — does not, because carrying it to a second -/// subscription only spends that one too. -#[must_use] -pub fn moves_the_work(reason: &str) -> bool { - if is_limit_failure(reason) { - return true; - } - // An account that cannot sign in cannot do ANY work, and a second agent - // authenticates separately — so this is the clearest case of all for - // handing over. Reusing [`looks_like_auth_failure`] rather than copying its - // needles: two lists of the same thing drift, and the one that drifts is - // never the one being read. - if looks_like_auth_failure(reason) { - return true; - } - let reason = reason.to_ascii_lowercase(); - [ - // The agent ran out of time on its own clock, not the harness's. - "timeout", - "timed out", - // The agent could not be started, spawned, or executed by the OS - // (missing binary, permission denied, Windows command line length limit os error 206, etc.). - "could not start", - "not installed", - "no output stream", - "did not exit cleanly", - "produced no result", - "failed to spawn", - "cannot spawn", - "unable to spawn", - "failed to execute", - "spawn", - "os error 206", - "os error", - "too long", - "filename or extension", - "command line too long", - "createprocess", - "executable file not found", - // The agent refused the request shape itself. - "not recognized", - "invalid model", - "unknown model", - // The agent's own transport gave out. - "connection", - "broken pipe", - // MEASURED, not guessed: a busy upstream model answered - // `status: ERROR, error: The stream was interrupted. Please continue - // the task you were working on.` — the agent's link to its provider - // broke mid-turn. It says nothing about the task, and it is the most - // common way a popular model fails, so a list without it leaves the - // standby idle exactly when it is most needed. - "stream was interrupted", - "stream interrupted", - ] - .iter() - .any(|needle| reason.contains(needle)) -} - -/// Maximum length of payload (prompt + system context) passed to external CLI -/// processes via command-line flags. -/// -/// On Windows, Win32 `CreateProcessW` imposes a hard 32,767 character limit on -/// the entire command line (`lpCommandLine`). Exceeding this triggers OS error 206 -/// (`ERROR_FILENAME_EXCED_RANGE: The filename or extension is too long`). -/// Keeping the combined payload at or below 28,000 characters leaves ample room -/// (~4,700 chars) for binary paths, flags, arguments, quotes, and whitespace. -#[cfg(windows)] -pub const MAX_CMDLINE_PAYLOAD_LEN: usize = 28_000; -#[cfg(not(windows))] -pub const MAX_CMDLINE_PAYLOAD_LEN: usize = 120_000; - -/// Prompt budget ceiling when total payload exceeds [`MAX_CMDLINE_PAYLOAD_LEN`]. -pub const MAX_PROMPT_BUDGET: usize = 12_000; - -/// Minimum context budget preserved when budgeting payload. -pub const MIN_CONTEXT_BUDGET: usize = 4_000; - -/// Compacts / budgets prompt and system context so external agent CLI processes -/// spawned via `Command::new` stay safely within OS command-line limits. -/// -/// When the total payload exceeds [`MAX_CMDLINE_PAYLOAD_LEN`], a prompt over -/// [`MAX_PROMPT_BUDGET`] is written whole to a file in `workspace` and the -/// agent is told to read it ([`spill`]); nothing of it is dropped. Then -/// high-priority context blocks (guards, standing rules, intake, asking, -/// roles) are preserved, while large informational blocks (discovered skills -/// catalog, auditor findings, recorder handoff) are truncated to fit the -/// remaining budget. An error only when the spill file cannot be written: -/// the turn is not started on a prompt the agent would never see whole. -/// -/// Called by the CLI backends that pass the prompt on a command line: -/// `agy.rs` and `codex.rs` (`full_prompt`) and `claude_code/turn.rs` -/// (`run_once`). -pub fn budget_for_spawn( - prompt: &str, - system_context: &[String], - workspace: &std::path::Path, -) -> Result<(String, String), AgentError> { - let unbudgeted_context = system_context.join("\n\n"); - let total_len = prompt.len() + unbudgeted_context.len(); - if total_len <= MAX_CMDLINE_PAYLOAD_LEN { - return Ok((prompt.to_string(), unbudgeted_context)); - } - - // NO PART OF THE PROMPT IS DROPPED. It used to keep the first 2,000 and - // the last ~9,900 bytes and cut the middle, on the theory that the - // instruction is always short and last. Measured on Insi's lesson writer: - // its instruction comes FIRST and its prompt runs to 20 KB, so the model - // got the preamble's head and the tail of a diff, and answered by asking - // what it was meant to do — four lessons of fifteen lost. - let budgeted_prompt = if prompt.len() > MAX_PROMPT_BUDGET { - spill(prompt, workspace)? - } else { - prompt.to_string() - }; - - let context_budget = MAX_CMDLINE_PAYLOAD_LEN - .saturating_sub(budgeted_prompt.len()) - .max(MIN_CONTEXT_BUDGET); - - if unbudgeted_context.len() <= context_budget { - return Ok((budgeted_prompt, unbudgeted_context)); - } - - // Partition blocks by priority: - // High-priority: guards, standing rules, intake task, question prompt, roles - // Low-priority: discovered skills index, auditor findings, recorder handoff - let mut high_priority = Vec::new(); - let mut low_priority = Vec::new(); - - for block in system_context { - let trimmed = block.trim(); - if trimmed.is_empty() { - continue; - } - let lower = trimmed.to_ascii_lowercase(); - if lower.contains("") - || lower.contains("standing rules") - || lower.contains("") - || lower.contains("") - || lower.contains("") - || lower.contains(" 100 { - let cutoff = crate::text::head_bytes(block, remaining.saturating_sub(80)); - let truncated = - format!("{}\n\n[...truncated for OS command line limit...]", cutoff); - current_len += truncated.len() + 2; - result_blocks.push(truncated); - } - break; - } - } - - // Second pass: add low-priority blocks if budget remains - for block in low_priority { - let block_len = block.len() + 2; - if current_len + block_len <= context_budget { - result_blocks.push(block.to_string()); - current_len += block_len; - } else { - let remaining = context_budget.saturating_sub(current_len); - if remaining > 120 { - let cutoff = crate::text::head_bytes(block, remaining.saturating_sub(80)); - let truncated = - format!("{}\n\n[...truncated for OS command line limit...]", cutoff); - result_blocks.push(truncated); - } - break; - } - } - - Ok((budgeted_prompt, result_blocks.join("\n\n"))) -} - -/// Write the whole of a prompt too long for a command line to the context -/// folder in `workspace` — the folder incode's memory hooks spill their -/// blocks to and prune (`crate::hooks::memory::CONTEXT`) — and return what the -/// agent is told instead: where the file is, and to read all of it first. -/// The name is the prompt's hash, so the same prompt is one file. -fn spill(prompt: &str, workspace: &std::path::Path) -> Result { - use std::hash::{Hash, Hasher}; - let mut hasher = std::collections::hash_map::DefaultHasher::new(); - prompt.hash(&mut hasher); - let name = format!("task-{:016x}.md", hasher.finish()); - let dir = workspace.join(crate::hooks::memory::CONTEXT); - let path = dir.join(&name); - std::fs::create_dir_all(&dir) - .and_then(|()| std::fs::write(&path, prompt)) - .map_err(|e| { - AgentError::new(format!( - "the task is {} bytes, more than a command line can carry, and could not \ - be written to {} for the agent to read: {e}; the turn was not started", - prompt.len(), - path.display() - )) - })?; - Ok(format!( - "This task is {} bytes, more than a command line can carry, so the whole of it \ - is in the file `{}/{name}` in your working folder ({}). Read that file in \ - full, from its first line to its last, before doing anything else: it is the \ - task, and what it asks is what you do.", - prompt.len(), - crate::hooks::memory::CONTEXT, - path.display() - )) -} - -#[cfg(test)] -mod budget_pinned_tests; - -#[cfg(test)] -mod route_parity_tests { - use super::*; - use crate::guards::Enforcement; - - /// **Every route declares what it really enforces — none inherits by - /// accident.** - /// - /// The trait default is `NOTHING`, which is right for an unmeasured - /// backend and WRONG for two of the three that exist. The API route was - /// left on the default when the capability layer was added, so every task - /// on it would have reported two guards unenforced while enforcing both by - /// prevention. A default that is safe in general is not safe for a route - /// nobody re-checked, which is the whole point of pinning all three here. - #[test] - fn each_route_states_its_own_enforcement() { - let api = crate::agent::api::ApiBackend::new( - crate::agent::api::Settings { - endpoint: "http://localhost/x".to_string(), - key: String::new(), - model: "m".to_string(), - ..Default::default() - }, - std::path::Path::new("."), - "", - true, - ); - assert_eq!( - api.enforces(), - Enforcement::EVERYTHING, - "the API route enforces guards at the toolbox, before any write" - ); - - let cli = crate::agent::claude_code::ClaudeCodeBackend::new(std::path::PathBuf::new()); - assert_eq!( - cli.enforces(), - Enforcement::EVERYTHING, - "this CLI accepts a deny list and was measured honouring it" - ); - - let agy = crate::agent::agy::AgyBackend::new(std::path::PathBuf::new()); - assert_eq!( - agy.enforces(), - Enforcement::NOTHING, - "this CLI has no deny surface and ships sub-agent tools" - ); - - let codex = crate::agent::codex::CodexBackend::new(std::path::PathBuf::new()); - assert_eq!( - codex.enforces(), - Enforcement::NOTHING, - "this CLI has no deny surface; Sentinel detects writes" - ); - } - - /// **Every route reports the harness context it carries.** - /// - /// The API route held the context in a field and answered the empty - /// default, so anything checking "did the session's context reach the - /// agent?" would have concluded the API route drops it. The block COUNT - /// differs by route — this one is handed a joined string — but "it - /// arrived" must be answerable everywhere. - #[test] - fn each_route_reports_the_context_it_was_given() { - let block = "the paths the agent may not write"; - - let api = crate::agent::api::ApiBackend::new( - crate::agent::api::Settings { - endpoint: "http://localhost/x".to_string(), - key: String::new(), - model: "m".to_string(), - ..Default::default() - }, - std::path::Path::new("."), - block, - true, - ); - assert!( - api.system_context() - .iter() - .any(|b| b.contains("may not write")), - "the API route carries the context but reported none: {:?}", - api.system_context() - ); - - let cli = crate::agent::claude_code::ClaudeCodeBackend::new(std::path::PathBuf::new()) - .with_system_context(vec![block.to_string()]); - assert!(cli - .system_context() - .iter() - .any(|b| b.contains("may not write"))); - - let agy = crate::agent::agy::AgyBackend::new(std::path::PathBuf::new()) - .with_system_context(vec![block.to_string()]); - assert!(agy - .system_context() - .iter() - .any(|b| b.contains("may not write"))); - - let codex = crate::agent::codex::CodexBackend::new(std::path::PathBuf::new()) - .with_system_context(vec![block.to_string()]); - assert!(codex - .system_context() - .iter() - .any(|b| b.contains("may not write"))); - - // And a session with nothing to say sends nothing, on every route. - let quiet = crate::agent::api::ApiBackend::new( - crate::agent::api::Settings { - endpoint: "http://localhost/x".to_string(), - key: String::new(), - model: "m".to_string(), - ..Default::default() - }, - std::path::Path::new("."), - " ", - true, - ); - assert!(quiet.system_context().is_empty()); - } -} - -#[cfg(test)] -mod handover_tests { - use super::*; - - /// **An agent's own failure moves the work; the task's own does not.** - /// - /// Both halves matter. Measured failures that SHOULD move: a CLI that - /// abandoned a task at its own deadline, and one that rejected the turn - /// with `model sonnet is not recognized` — neither says anything about the - /// task. Failures that must NOT move: a check that did not pass or a guard - /// that refused will do the same on every agent, and carrying them spends a - /// second subscription to learn one thing. - #[test] - fn only_the_agents_own_failures_move_the_work() { - for agent_side in [ - "rate limit reached", - "the agent stopped without finishing (ERROR): timeout waiting for response", - "could not start `agy`: program not found", - "invalid model selection: model sonnet is not recognized", - "the agent produced no result line (exit 1)", - // Copied from a real busy-model reply, not composed here. - "The stream was interrupted. Please continue the task you were working on.", - ] { - assert!( - moves_the_work(agent_side), - "an agent-side failure must reach the standby: {agent_side}" - ); - } - - for task_side in [ - "`node --check game.js` exited 1", - "a protected file changed and the owner did not approve it", - "the contract for this task was broken", - "the agent finished but the check did not pass", - ] { - assert!( - !moves_the_work(task_side), - "a task-side failure must NOT walk through every subscription: {task_side}" - ); - } - } - - #[test] - fn weekly_and_credit_limits_move_the_work() { - assert!(moves_the_work( - "You've reached your weekly limit for Claude Code" - )); - assert!(moves_the_work("weekly limit reached")); - assert!(moves_the_work("exceeded your limit for the current period")); - assert!(moves_the_work("out of credits on this account")); - assert!(moves_the_work( - "monthly limit exceeded: try again next billing cycle" - )); - assert!(moves_the_work("daily request limit reached")); - } - - #[test] - fn spawn_and_os_errors_move_the_work() { - assert!(moves_the_work( - "failed to spawn `claude`: The filename or extension is too long. (os error 206)" - )); - assert!(moves_the_work( - "failed to spawn `claude`: No such file or directory (os error 2)" - )); - assert!(moves_the_work( - "failed to spawn `agy`: Access is denied. (os error 5)" - )); - assert!(moves_the_work("cannot spawn child process: os error 206")); - assert!(moves_the_work("command line too long")); - assert!(moves_the_work("failed to execute process")); - assert!(moves_the_work("CreateProcess failed")); - } - - #[test] - fn budget_for_spawn_preserves_under_limit() { - let prompt = "Implement feature X"; - let context = vec![ - "no-write tests".to_string(), - "standing rules: follow style guide".to_string(), - ]; - let dir = tempfile::tempdir().expect("dir"); - let (p, c) = budget_for_spawn(prompt, &context, dir.path()).expect("budgeted"); - assert_eq!(p, prompt); - assert_eq!(c, context.join("\n\n")); - assert!( - !dir.path().join(crate::hooks::memory::CONTEXT).exists(), - "a prompt that fits writes no file" - ); - } - - #[test] - fn budget_for_spawn_bounds_large_context_preserving_guards() { - let prompt = "Fix bug"; - let large_skills = "Skills on this machine:\n".to_string() + &"x".repeat(35_000); - let context = vec![ - "protected".to_string(), - "The owner's standing rules:\n1. do not delete".to_string(), - large_skills, - ]; - let dir = tempfile::tempdir().expect("dir"); - let (p, c) = budget_for_spawn(prompt, &context, dir.path()).expect("budgeted"); - assert_eq!(p, prompt); - assert!(p.len() + c.len() <= MAX_CMDLINE_PAYLOAD_LEN); - assert!(c.contains("protected")); - assert!(c.contains("standing rules")); - } - - /// The file an over-budget prompt was written to, read from what the - /// agent was told. - fn spilled(told: &str, workspace: &std::path::Path) -> String { - let at = told.find("task-").expect("names a task file"); - let name = &told[at..at + "task-".len() + 16 + ".md".len()]; - std::fs::read_to_string(workspace.join(crate::hooks::memory::CONTEXT).join(name)) - .expect("the task file exists") - } - - /// **AN OVER-BUDGET PROMPT REACHES THE AGENT WHOLE.** Both shapes a - /// harness sends: the instruction LAST (a task after its context) and - /// the instruction FIRST, then a long body (Insi's lesson writer, whose - /// instruction the old middle cut dropped). Each is written to a file in - /// full, the agent is told where it is and to read all of it, and the - /// command line stays within the OS limit. - #[test] - fn budget_for_spawn_spills_an_oversized_prompt_whole() { - let body = "context é ".repeat(MAX_CMDLINE_PAYLOAD_LEN / 10); - let last = format!("g\n\n{body}\n\nNow do this:\n\ncreate a.txt with hi"); - let first = - format!("Write one lesson as JSON with an issue field.\n\n{body}\nVERIFIED_FIX>>>"); - let context = vec!["safe".to_string(), "x".repeat(20_000)]; - for prompt in [last, first] { - let dir = tempfile::tempdir().expect("dir"); - let (p, c) = budget_for_spawn(&prompt, &context, dir.path()).expect("budgeted"); - assert!( - p.len() + c.len() <= MAX_CMDLINE_PAYLOAD_LEN, - "{}", - p.len() + c.len() - ); - assert!( - p.len() < 1_000, - "the agent is told where, not sent a cut: {p}" - ); - assert!(p.contains("Read that file in full"), "{p}"); - assert_eq!( - spilled(&p, dir.path()), - prompt, - "nothing of the prompt is dropped" - ); - assert!(c.contains("safe")); - } - } - - /// **A PROMPT THAT CANNOT BE WRITTEN DOWN IS NOT SENT AT ALL.** The - /// workspace is a file, so the context folder cannot be made: the turn - /// stops with the reason instead of starting on a prompt the agent would - /// never see whole. - #[test] - fn budget_for_spawn_refuses_when_the_task_file_cannot_be_written() { - let dir = tempfile::tempdir().expect("dir"); - let not_a_folder = dir.path().join("plain-file"); - std::fs::write(¬_a_folder, "x").expect("file"); - let prompt = "y".repeat(MAX_CMDLINE_PAYLOAD_LEN + 1); - let why = budget_for_spawn(&prompt, &[], ¬_a_folder).expect_err("refused"); - let why = why.to_string(); - assert!( - why.contains("could not be written") && why.contains("not started"), - "{why}" - ); - } -} - #[derive(Debug, Clone, PartialEq, Eq)] pub struct AgentError { message: String, @@ -820,427 +222,8 @@ impl Display for AgentError { impl std::error::Error for AgentError {} -/// An external agent this harness can route a turn to. -pub trait AgentBackend { - /// Stable identifier, e.g. `"claude-code"`. - fn id(&self) -> &str; - - /// Run one turn, calling `on_event` as events arrive. - /// - /// Implementations must continue an existing session where the underlying - /// agent supports it: re-establishing a session per turn re-pays the whole - /// prompt prefix. Measured against Claude Code 2.1.229, a fresh session - /// costs ~36k cache-creation tokens versus ~1.8k when resuming. - fn run_turn( - &mut self, - prompt: &str, - on_event: &mut dyn FnMut(&AgentEvent), - ) -> Result; - - /// The agent's current session id, once one exists. - fn session_id(&self) -> Option<&str>; - - /// Ask for a particular model on the next turn, with ordered fallbacks. - /// - /// Defaulted to doing nothing, because not every agent can be told which - /// model to use and one that cannot should not have to say so. An agent - /// that CAN is where routing pays: cheap work on a cheap model, without an - /// API credential anywhere. - /// - /// Called with the candidates in preference order. An empty slice means the - /// caller has no opinion and the agent's own default should stand. - fn set_models(&mut self, _candidates: &[String]) {} - - /// A model the operator named outright (`/model`, `-m`), rather than a - /// role table's candidates. Defaulted to the same rule as - /// [`Self::set_models`]; an API route takes any id its service offers. - fn choose_model(&mut self, model: &str) { - self.set_models(&[model.to_string()]); - } - - // The methods below exist because an interactive session needs them and not - // every backend can honour them. Each defaults to doing nothing rather than - // being required, so a backend implements only what it actually supports — - // and a caller reading the default gets "this route cannot do that", which - // is the truth, instead of a panic or a pretence. - - /// Also work in these directories, beyond the workspace root. - fn set_extra_dirs(&mut self, _dirs: Vec) {} - - /// The deny rules in force, for showing the operator. - /// - /// Empty when the backend protects paths some other way — the toolbox - /// checks the guards itself rather than handing rules to anyone. - fn deny_rules(&self) -> &[String] { - &[] - } - - /// The harness context this backend will carry into its next turn. - /// - /// On the trait so the invariant can be checked for ANY agent, not just the - /// one that happens to expose it. The context going missing is a measured - /// regression — twice — and it is invisible from the outside, so the test - /// that pins it must not be limited to a single backend. - fn system_context(&self) -> &[String] { - &[] - } - - /// The MCP server configuration this agent will be handed, if any. - /// - /// Exists for the same reason [`Self::system_context`] does: the flag is - /// assembled inside a spawn and is invisible from outside, so a test that - /// checks "did the harness actually hand this over" needs a way to look. - /// Defaults to `None`, which is the truth for every backend that has no - /// registration path yet — see `docs/COMPUTER_USE.md` section 2. - /// - /// Returns an owned string because a backend may register SEVERAL servers - /// and hold them as separate pieces. Borrowing forced codex to answer with - /// the first of its overrides, which read as the whole registration and - /// hid the second server completely. - fn mcp_config(&self) -> Option { - None - } - - /// Who this agent is on the team channel for the task about to run. - /// - /// # Why the environment and not the registration - /// - /// An agent CLI's MCP servers are configured ONCE, when the backend is - /// built, and the role changes every task. So the team server cannot be - /// told who it serves at registration time — it reads - /// [`crate::team_mcp::IDENTITY_ENV`] instead, and the server is a child of - /// the agent process, so setting the variable on the spawn is what reaches - /// it. - /// - /// Identity has to come from here rather than from the model, because the - /// harness RECORDS what is said on the channel: a name the agent could - /// choose would be a claim written down as a fact. - /// - /// Defaulted to nothing, for a backend that spawns no process. - fn set_team_identity(&mut self, _role: &str) {} - - /// This agent's OWN model ladder for a role, in preference order. - /// - /// # Why a backend supplies one at all - /// - /// The operator's ladder in `admin.json` holds concrete model ids, and ids - /// do not cross vendors: measured, forwarding one agent's `sonnet` to - /// another returned `model sonnet is not recognized` and failed every task - /// on arrival. Dropping the foreign name keeps the run alive but loses - /// routing entirely — every role then runs on the agent's default, which is - /// the expensive one. - /// - /// So a backend may answer for itself, in its own namespace. The operator's - /// ladder still wins wherever it names something this agent can serve; this - /// is the floor, not an override. - /// - /// Empty by default: an agent whose model names have not been measured must - /// not have a ladder invented for it. - fn ladder_for(&self, _role: &str) -> Vec { - Vec::new() - } - - /// What this backend can PREVENT for itself. - /// - /// Defaulted to [`crate::guards::Enforcement::NOTHING`] deliberately: a - /// backend whose enforcement has not been MEASURED must not be credited - /// with any, because the cost of guessing high is a guard the operator - /// believes in and the agent never applies. - fn enforces(&self) -> crate::guards::Enforcement { - crate::guards::Enforcement::NOTHING - } - - /// Whether a FAILED turn was the agent's own failure rather than the work's. - /// - /// # Why this is the backend's judgement and not a phrase list - /// - /// [`moves_the_work`] reads the failure MESSAGE, which is all a failure - /// that never produced a turn gives us. That list can only ever hold the - /// wordings someone has already seen, and a provider invents new ones: - /// MEASURED live, a busy model answered `Our servers are experiencing high - /// traffic right now, please try again in a minute.` — an unmistakable - /// agent-side failure that matched no needle, so both attempts ran on the - /// agent that had just said it could not serve them and the task was - /// abandoned with a standby idle. - /// - /// A backend whose protocol has a SEPARATE channel for its own machinery - /// knows the answer structurally and should say so, rather than waiting for - /// the message to be recognised. One that has no such channel keeps the - /// default and loses nothing. - fn agent_failed(&self, outcome: &TurnOutcome) -> bool { - moves_the_work(&outcome.failure()) - } - - /// Stop the turn when this token is tripped. - fn set_cancel(&mut self, _token: crate::runtime::cancel::CancelToken) {} - - /// Who to ask when a tool call needs a person's confirmation, or a - /// question needs the owner's answer. - /// - /// Defaulted to nothing: only a backend whose tools this harness runs - /// itself ([`crate::toolbox::Toolbox`]) has a moment at which to ask. - fn set_prompter(&mut self, _prompter: std::sync::Arc) {} - - /// Who to ask about a protected write when nobody is at the session — a - /// run's owner channel. Defaulted to nothing, as [`Self::set_prompter`] is. - fn set_owner(&mut self, _owner: std::sync::Arc) {} - - /// Record the protected writes a person allows into `record` — a - /// sub-agent's, into its parent's. Defaulted to nothing, as the rest are. - fn share_allowed_writes(&mut self, _record: std::sync::Arc) {} - - /// The API route this backend drives, when it drives one — what - /// `/models` asks for its service's model list. `None` for a CLI. - fn api_route(&self) -> Option<&crate::agent::api::Settings> { - None - } - - /// The session's own tool state — its background jobs and task list — - /// for a backend whose tools this harness runs, so every backend of one - /// session shares them. - /// - /// Defaulted to nothing: a backend whose tools are not incode's has no - /// jobs or list of incode's to share. - fn share_session_tools(&mut self, _state: std::sync::Arc) {} - - /// Whether every tool call this backend's model makes runs through - /// incode's [`crate::toolbox::Toolbox`] — so a restriction set on the - /// shared [`crate::toolbox::SessionTools`] binds it. - /// - /// Defaulted to no: an agent CLI that brings its own tools runs them - /// where incode cannot refuse one. - fn runs_tools_here(&self) -> bool { - false - } - - /// The model this backend was asked for, when it was asked for one. - fn model(&self) -> Option<&str> { - None - } - - /// Begin a new conversation, forgetting the current one. - fn clear_session(&mut self) {} - - /// Summarise the older part of the conversation into one message, now, - /// with the operator's `instructions` steering the summary (`/compact`). - /// - /// `None` when this backend does not hold its conversation — an agent CLI - /// compacts its own, inside its own process. `Some(Ok(_))` says what was - /// done; `Some(Err(_))` why it could not be. - fn compact(&mut self, _instructions: &str) -> Option> { - None - } - - /// How much the backend may do without asking. - fn set_permission_mode(&mut self, _mode: &str) {} - - /// Continue the conversation with this id. - fn set_session_id(&mut self, _session_id: &str) {} - - /// incode's id for the session, which the memory engine files everything - /// under — its pre-tool cards as well as the session's capture. - /// - /// Defaulted to nothing: only a backend whose tool calls this harness runs - /// itself sends the engine anything per call. - fn set_memory_session(&mut self, _session: &str) {} - - /// The session is over: tell the engine's edit check, so what this agent - /// claimed, read and announced is let go now rather than at its TTL. - /// - /// Defaulted to nothing: only a backend whose file tools this harness - /// runs itself announced anything. - fn end_code_edits(&mut self) {} - - /// Replace the harness context this backend carries into its turns. - /// - /// Defaulted to nothing for a backend that carries none. - fn set_system_context(&mut self, _blocks: Vec) {} - - /// The conversations subagents opened, as `(session id, what it was asked)`. - /// - /// Empty for a backend that does not delegate, and for one whose subagents - /// are its own business — an agent CLI spawns them inside a process this - /// harness cannot see into, so it has nothing to report and says so rather - /// than guessing. - fn children(&self) -> Vec<(String, String)> { - Vec::new() - } - - /// The tools incode itself runs for this agent's model, by name: the - /// toolbox's, for a backend whose model has no tools of its own. Empty - /// for an agent whose CLI still brings its own. A session traces them - /// when it starts, so which tools a model was handed is on the record — - /// including whether the desktop was among them. - fn offered_tools(&self) -> Vec { - Vec::new() - } - - /// Who is told what this backend's tools and workers do while they run - /// — see [`crate::watch`]. - /// - /// Defaulted to nothing: only a backend whose tools this harness runs - /// itself has calls, output and workers of incode's to report. - fn set_watch(&mut self, _watch: std::sync::Arc) {} - - /// Carry these pictures with the next turn's prompt, and only that turn. - /// - /// # Errors - /// - /// The agent cannot take a picture headless — the default, because no - /// route may be credited with a capability that was not measured on it. - /// The error names the agent, for the person who attached them. - fn attach_images(&mut self, images: Vec) -> Result<(), String> { - Err(format!( - "{} cannot take pictures headless, so {} picture(s) could not be sent; \ - describe them in words, or pick an agent that takes them", - self.id(), - images.len() - )) - } -} - -/// A boxed backend is a backend. -/// -/// The choice between routes is made at runtime — an installed CLI when there -/// is one, a model over an API when the operator configured one — so the call -/// sites hold one value either way. Without this they would each need to know -/// both types and branch around them. -impl AgentBackend for Box { - fn id(&self) -> &str { - (**self).id() - } - - /// Forwarded, so a boxed standby reports what the backend INSIDE it can - /// enforce. Falling through to the trait default here would credit every - /// boxed agent with enforcing nothing, and the gap report would be right by - /// accident rather than by measurement. - fn enforces(&self) -> crate::guards::Enforcement { - (**self).enforces() - } - - /// Forwarded for the same reason as [`Self::enforces`]: the run holds its - /// agents BOXED, so a default here would mean no backend's structural - /// judgement ever reached the failover loop — the one place it is read. - fn agent_failed(&self, outcome: &TurnOutcome) -> bool { - (**self).agent_failed(outcome) - } - - fn system_context(&self) -> &[String] { - (**self).system_context() - } - - fn ladder_for(&self, role: &str) -> Vec { - (**self).ladder_for(role) - } - - fn run_turn( - &mut self, - prompt: &str, - on_event: &mut dyn FnMut(&AgentEvent), - ) -> Result { - (**self).run_turn(prompt, on_event) - } - - fn session_id(&self) -> Option<&str> { - (**self).session_id() - } - - fn choose_model(&mut self, model: &str) { - (**self).choose_model(model); - } - - fn set_models(&mut self, candidates: &[String]) { - (**self).set_models(candidates); - } - - fn set_extra_dirs(&mut self, dirs: Vec) { - (**self).set_extra_dirs(dirs); - } - - fn set_team_identity(&mut self, role: &str) { - (**self).set_team_identity(role); - } - - fn deny_rules(&self) -> &[String] { - (**self).deny_rules() - } - - fn set_cancel(&mut self, token: crate::runtime::cancel::CancelToken) { - (**self).set_cancel(token); - } - - fn set_prompter(&mut self, prompter: std::sync::Arc) { - (**self).set_prompter(prompter); - } - - fn set_owner(&mut self, owner: std::sync::Arc) { - (**self).set_owner(owner); - } - - fn share_allowed_writes(&mut self, record: std::sync::Arc) { - (**self).share_allowed_writes(record); - } - - fn api_route(&self) -> Option<&crate::agent::api::Settings> { - (**self).api_route() - } - - fn share_session_tools(&mut self, state: std::sync::Arc) { - (**self).share_session_tools(state); - } - - fn runs_tools_here(&self) -> bool { - (**self).runs_tools_here() - } - - fn model(&self) -> Option<&str> { - (**self).model() - } - - fn clear_session(&mut self) { - (**self).clear_session(); - } - - fn compact(&mut self, instructions: &str) -> Option> { - (**self).compact(instructions) - } - - fn set_permission_mode(&mut self, mode: &str) { - (**self).set_permission_mode(mode); - } - - fn set_session_id(&mut self, session_id: &str) { - (**self).set_session_id(session_id); - } - - fn set_memory_session(&mut self, session: &str) { - (**self).set_memory_session(session); - } - - fn end_code_edits(&mut self) { - (**self).end_code_edits(); - } - - fn set_system_context(&mut self, blocks: Vec) { - (**self).set_system_context(blocks); - } - - fn children(&self) -> Vec<(String, String)> { - (**self).children() - } - - fn offered_tools(&self) -> Vec { - (**self).offered_tools() - } - - fn set_watch(&mut self, watch: std::sync::Arc) { - (**self).set_watch(watch); - } - - fn attach_images(&mut self, images: Vec) -> Result<(), String> { - (**self).attach_images(images) - } -} +#[cfg(test)] +mod budget_pinned_tests; #[cfg(test)] mod outcome_tests { diff --git a/src/agent/spawn_budget.rs b/src/agent/spawn_budget.rs new file mode 100644 index 0000000..541baf9 --- /dev/null +++ b/src/agent/spawn_budget.rs @@ -0,0 +1,299 @@ +//! Keeping a prompt and its context within what an OS command line can +//! carry, for the agent CLIs that are handed both as arguments. +//! +//! Wired to: the CLI backends that pass the prompt on a command line — +//! `agy.rs` and `codex/mod.rs` (`full_prompt`) and `claude_code/turn.rs` +//! (`run_once`) — through [`budget_for_spawn`]. + +use super::AgentError; + +/// Maximum length of payload (prompt + system context) passed to external CLI +/// processes via command-line flags. +/// +/// On Windows, Win32 `CreateProcessW` imposes a hard 32,767 character limit on +/// the entire command line (`lpCommandLine`). Exceeding this triggers OS error 206 +/// (`ERROR_FILENAME_EXCED_RANGE: The filename or extension is too long`). +/// Keeping the combined payload at or below 28,000 characters leaves ample room +/// (~4,700 chars) for binary paths, flags, arguments, quotes, and whitespace. +#[cfg(windows)] +pub const MAX_CMDLINE_PAYLOAD_LEN: usize = 28_000; +#[cfg(not(windows))] +pub const MAX_CMDLINE_PAYLOAD_LEN: usize = 120_000; + +/// Prompt budget ceiling when total payload exceeds [`MAX_CMDLINE_PAYLOAD_LEN`]. +pub const MAX_PROMPT_BUDGET: usize = 12_000; + +/// Minimum context budget preserved when budgeting payload. +pub const MIN_CONTEXT_BUDGET: usize = 4_000; + +/// What a block cut to fit ends with. +const CUT_MARK: &str = "\n\n[...truncated for OS command line limit...]"; + +/// A high-priority block is cut to fit only when more than this is left; +/// otherwise it is dropped. +const HIGH_PRIORITY_CUT_FLOOR: usize = 100; + +/// The same floor for a low-priority block. +const LOW_PRIORITY_CUT_FLOOR: usize = 120; + +/// Compacts / budgets prompt and system context so external agent CLI processes +/// spawned via `Command::new` stay safely within OS command-line limits. +/// +/// When the total payload exceeds [`MAX_CMDLINE_PAYLOAD_LEN`], a prompt over +/// [`MAX_PROMPT_BUDGET`] is written whole to a file in `workspace` and the +/// agent is told to read it ([`spill`]); nothing of it is dropped. Then +/// high-priority context blocks (guards, standing rules, intake, asking, +/// roles) are preserved, while large informational blocks (discovered skills +/// catalog, auditor findings, recorder handoff) are truncated to fit the +/// remaining budget. An error only when the spill file cannot be written: +/// the turn is not started on a prompt the agent would never see whole. +/// +/// Called by the CLI backends that pass the prompt on a command line: +/// `agy.rs` and `codex/mod.rs` (`full_prompt`) and `claude_code/turn.rs` +/// (`run_once`). +pub fn budget_for_spawn( + prompt: &str, + system_context: &[String], + workspace: &std::path::Path, +) -> Result<(String, String), AgentError> { + let unbudgeted_context = system_context.join("\n\n"); + let total_len = prompt.len() + unbudgeted_context.len(); + if total_len <= MAX_CMDLINE_PAYLOAD_LEN { + return Ok((prompt.to_string(), unbudgeted_context)); + } + + // NO PART OF THE PROMPT IS DROPPED. It used to keep the first 2,000 and + // the last ~9,900 bytes and cut the middle, on the theory that the + // instruction is always short and last. Measured on Insi's lesson writer: + // its instruction comes FIRST and its prompt runs to 20 KB, so the model + // got the preamble's head and the tail of a diff, and answered by asking + // what it was meant to do — four lessons of fifteen lost. + let budgeted_prompt = if prompt.len() > MAX_PROMPT_BUDGET { + spill(prompt, workspace)? + } else { + prompt.to_string() + }; + + let context_budget = MAX_CMDLINE_PAYLOAD_LEN + .saturating_sub(budgeted_prompt.len()) + .max(MIN_CONTEXT_BUDGET); + + if unbudgeted_context.len() <= context_budget { + return Ok((budgeted_prompt, unbudgeted_context)); + } + + let (high_priority, low_priority) = by_priority(system_context); + let mut kept = Kept::default(); + kept.take(&high_priority, context_budget, HIGH_PRIORITY_CUT_FLOOR); + kept.take(&low_priority, context_budget, LOW_PRIORITY_CUT_FLOOR); + Ok((budgeted_prompt, kept.blocks.join("\n\n"))) +} + +/// The context's non-blank blocks, trimmed, split by priority in their +/// order: +/// high-priority: guards, standing rules, intake task, question prompt, roles; +/// low-priority: discovered skills index, auditor findings, recorder handoff. +/// +/// Called by [`budget_for_spawn`]. +fn by_priority(system_context: &[String]) -> (Vec<&str>, Vec<&str>) { + let mut high_priority = Vec::new(); + let mut low_priority = Vec::new(); + for block in system_context { + let trimmed = block.trim(); + if trimmed.is_empty() { + continue; + } + if is_high_priority(trimmed) { + high_priority.push(trimmed); + } else { + low_priority.push(trimmed); + } + } + (high_priority, low_priority) +} + +/// Whether a block is one the agent must keep: its guards, the owner's +/// rules and instructions, the task's intake, how to ask, the roles, the +/// output style and the tools it may not use. +/// +/// Called by [`by_priority`]. +fn is_high_priority(block: &str) -> bool { + let lower = block.to_ascii_lowercase(); + lower.contains("") + || lower.contains("standing rules") + || lower.contains("") + || lower.contains("") + || lower.contains("") + || lower.contains(", + /// Each block's length plus its separator. + used: usize, +} + +impl Kept { + /// Keep `blocks` in order while each fits in `budget`; the first that + /// does not is cut to what is left — when more than `floor` is — and + /// nothing after it in `blocks` is kept. + /// + /// Called by [`budget_for_spawn`], for the high-priority blocks and then + /// the low. + fn take(&mut self, blocks: &[&str], budget: usize, floor: usize) { + for block in blocks { + let block_len = block.len() + 2; + if self.used + block_len <= budget { + self.blocks.push((*block).to_string()); + self.used += block_len; + continue; + } + let remaining = budget.saturating_sub(self.used); + if remaining > floor { + let cutoff = crate::text::head_bytes(block, remaining.saturating_sub(80)); + let truncated = format!("{cutoff}{CUT_MARK}"); + self.used += truncated.len() + 2; + self.blocks.push(truncated); + } + break; + } + } +} + +/// Write the whole of a prompt too long for a command line to the context +/// folder in `workspace` — the folder incode's memory hooks spill their +/// blocks to and prune (`crate::hooks::memory::CONTEXT`) — and return what the +/// agent is told instead: where the file is, and to read all of it first. +/// The name is the prompt's hash, so the same prompt is one file. +fn spill(prompt: &str, workspace: &std::path::Path) -> Result { + use std::hash::{Hash, Hasher}; + let mut hasher = std::collections::hash_map::DefaultHasher::new(); + prompt.hash(&mut hasher); + let name = format!("task-{:016x}.md", hasher.finish()); + let dir = workspace.join(crate::hooks::memory::CONTEXT); + let path = dir.join(&name); + std::fs::create_dir_all(&dir) + .and_then(|()| std::fs::write(&path, prompt)) + .map_err(|e| { + AgentError::new(format!( + "the task is {} bytes, more than a command line can carry, and could not \ + be written to {} for the agent to read: {e}; the turn was not started", + prompt.len(), + path.display() + )) + })?; + Ok(format!( + "This task is {} bytes, more than a command line can carry, so the whole of it \ + is in the file `{}/{name}` in your working folder ({}). Read that file in \ + full, from its first line to its last, before doing anything else: it is the \ + task, and what it asks is what you do.", + prompt.len(), + crate::hooks::memory::CONTEXT, + path.display() + )) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn budget_for_spawn_preserves_under_limit() { + let prompt = "Implement feature X"; + let context = vec![ + "no-write tests".to_string(), + "standing rules: follow style guide".to_string(), + ]; + let dir = tempfile::tempdir().expect("dir"); + let (p, c) = budget_for_spawn(prompt, &context, dir.path()).expect("budgeted"); + assert_eq!(p, prompt); + assert_eq!(c, context.join("\n\n")); + assert!( + !dir.path().join(crate::hooks::memory::CONTEXT).exists(), + "a prompt that fits writes no file" + ); + } + + #[test] + fn budget_for_spawn_bounds_large_context_preserving_guards() { + let prompt = "Fix bug"; + let large_skills = "Skills on this machine:\n".to_string() + &"x".repeat(35_000); + let context = vec![ + "protected".to_string(), + "The owner's standing rules:\n1. do not delete".to_string(), + large_skills, + ]; + let dir = tempfile::tempdir().expect("dir"); + let (p, c) = budget_for_spawn(prompt, &context, dir.path()).expect("budgeted"); + assert_eq!(p, prompt); + assert!(p.len() + c.len() <= MAX_CMDLINE_PAYLOAD_LEN); + assert!(c.contains("protected")); + assert!(c.contains("standing rules")); + } + + /// The file an over-budget prompt was written to, read from what the + /// agent was told. + fn spilled(told: &str, workspace: &std::path::Path) -> String { + let at = told.find("task-").expect("names a task file"); + let name = &told[at..at + "task-".len() + 16 + ".md".len()]; + std::fs::read_to_string(workspace.join(crate::hooks::memory::CONTEXT).join(name)) + .expect("the task file exists") + } + + /// **AN OVER-BUDGET PROMPT REACHES THE AGENT WHOLE.** Both shapes a + /// harness sends: the instruction LAST (a task after its context) and + /// the instruction FIRST, then a long body (Insi's lesson writer, whose + /// instruction the old middle cut dropped). Each is written to a file in + /// full, the agent is told where it is and to read all of it, and the + /// command line stays within the OS limit. + #[test] + fn budget_for_spawn_spills_an_oversized_prompt_whole() { + let body = "context é ".repeat(MAX_CMDLINE_PAYLOAD_LEN / 10); + let last = format!("g\n\n{body}\n\nNow do this:\n\ncreate a.txt with hi"); + let first = + format!("Write one lesson as JSON with an issue field.\n\n{body}\nVERIFIED_FIX>>>"); + let context = vec!["safe".to_string(), "x".repeat(20_000)]; + for prompt in [last, first] { + let dir = tempfile::tempdir().expect("dir"); + let (p, c) = budget_for_spawn(&prompt, &context, dir.path()).expect("budgeted"); + assert!( + p.len() + c.len() <= MAX_CMDLINE_PAYLOAD_LEN, + "{}", + p.len() + c.len() + ); + assert!( + p.len() < 1_000, + "the agent is told where, not sent a cut: {p}" + ); + assert!(p.contains("Read that file in full"), "{p}"); + assert_eq!( + spilled(&p, dir.path()), + prompt, + "nothing of the prompt is dropped" + ); + assert!(c.contains("safe")); + } + } + + /// **A PROMPT THAT CANNOT BE WRITTEN DOWN IS NOT SENT AT ALL.** The + /// workspace is a file, so the context folder cannot be made: the turn + /// stops with the reason instead of starting on a prompt the agent would + /// never see whole. + #[test] + fn budget_for_spawn_refuses_when_the_task_file_cannot_be_written() { + let dir = tempfile::tempdir().expect("dir"); + let not_a_folder = dir.path().join("plain-file"); + std::fs::write(¬_a_folder, "x").expect("file"); + let prompt = "y".repeat(MAX_CMDLINE_PAYLOAD_LEN + 1); + let why = budget_for_spawn(&prompt, &[], ¬_a_folder).expect_err("refused"); + let why = why.to_string(); + assert!( + why.contains("could not be written") && why.contains("not started"), + "{why}" + ); + } +} diff --git a/src/desktop/mcp.rs b/src/desktop/mcp.rs index ba0a19d..088a6df 100644 --- a/src/desktop/mcp.rs +++ b/src/desktop/mcp.rs @@ -1340,7 +1340,7 @@ pub const CLIENT_KEY: &str = "desktop"; /// Verified against the installed Claude CLI 2.1.273: `--mcp-config ` /// takes JSON, and `--strict-mcp-config` confines the agent to only what is /// passed there. Codex takes the same information as -/// `-c mcp_servers..…` instead (`src/agent/codex.rs:207`), which is why +/// `-c mcp_servers..…` instead (`src/agent/codex/argv.rs`), which is why /// this returns the SHAPE rather than a command line — each backend spells it /// differently, and the thing they agree on is what to launch. /// diff --git a/src/hooks/memory.rs b/src/hooks/memory.rs index a5ff0f2..529257c 100644 --- a/src/hooks/memory.rs +++ b/src/hooks/memory.rs @@ -64,7 +64,7 @@ pub(crate) const TRANSCRIPTS: &str = ".incode/transcripts"; /// Where an oversized block is written whole, under the workspace. Also where /// `crate::agent::budget_for_spawn` writes a task too long for a command -/// line (src/agent/mod.rs `spill`), so `prune` keeps both bounded. +/// line (src/agent/spawn_budget.rs `spill`), so `prune` keeps both bounded. pub(crate) const CONTEXT: &str = ".incode/context"; /// How many files each of those two directories keeps. The newest survive.