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/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 deleted file mode 100644 index 9253a65..0000000 --- a/src/agent/codex.rs +++ /dev/null @@ -1,2183 +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 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/pinned_tests.rs b/src/agent/codex/pinned_tests.rs new file mode 100644 index 0000000..f10d8e3 --- /dev/null +++ b/src/agent/codex/pinned_tests.rs @@ -0,0 +1,963 @@ +//! 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, 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() { + let line = |name: &str| { + CORPUS + .iter() + .find(|(n, _)| *n == name) + .map(|(_, l)| *l) + .expect("a corpus line") + }; + 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); + let want = TURN_READINGS.iter().find(|(n, _)| *n == name); + if want.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 +} + +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"); + 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); + cases +} + +/// 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", + reported("codex", ".", &plain(&[BYPASS, "-C", ".", "the task"]), &[]), + ), + ( + "bare_resumed", + reported( + "codex", + ".", + &strings( + &[ + &["exec", "resume"][..], + &LEAD[..], + &[BYPASS, "-c", AUTO, "t-9", "the task"], + ] + .concat(), + ), + &[], + ), + ), + ( + "own", + reported( + "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", + reported( + "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, 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"][..]), + ] { + 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, reported("codex-x", "ws", &args, &[]))); + } + want +} + +/// `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 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())) + .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, reported("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/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 1185b69..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,600 +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 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, @@ -817,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.