From 7548a73612a91a11594c60ba199bf64600167246 Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Fri, 23 Oct 2026 13:11:14 -0600 Subject: [PATCH 1/3] test(claude_code, agy): pin the wire mapping, the argv and env, and whole turns Before splitting the two backends, pin what they do through the paths a refactor could move: a 47-line corpus over map_line (every event type, subagent and empty cases, each way a failed result describes itself, lines that do not parse) and that only a result line writes the outcome; the exact argv and environment of claude's command for a plain turn, a fully configured one and one after the thinking flag was refused, and the stdin message; agy's exact command, default and configured. Whole turns run through run_turn on stand-in CLIs: the events in order, the outcome, the session kept, and the exact error texts for a CLI that cannot start, a turn with no result line and a cancelled agy turn. All pass on the original single-file code. Co-Authored-By: Claude --- src/agent/agy.rs | 298 +++++++++++++++++++++ src/agent/claude_code.rs | 558 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 856 insertions(+) diff --git a/src/agent/agy.rs b/src/agent/agy.rs index d4db316..82e1bea 100644 --- a/src/agent/agy.rs +++ b/src/agent/agy.rs @@ -924,4 +924,302 @@ mod tests { backend.set_permission_mode("plan"); assert_eq!(backend.mode.as_deref(), Some("plan")); } + + // ----------------------------------------------------------------------- + // Pinned behaviour: the exact command a turn is started with, and what a + // whole turn through `run_turn` reports. + // ----------------------------------------------------------------------- + + fn args_of(cmd: &Command) -> Vec { + cmd.get_args() + .map(|a| a.to_string_lossy().into_owned()) + .collect() + } + + fn strings(items: &[&str]) -> Vec { + items.iter().map(|s| (*s).to_string()).collect() + } + + /// What the command SETS in the environment. Removals are the parent + /// session's variables, guarded by the test above. + fn set_envs(cmd: &Command) -> Vec<(String, String)> { + cmd.get_envs() + .filter_map(|(k, v)| { + Some(( + k.to_string_lossy().into_owned(), + v?.to_string_lossy().into_owned(), + )) + }) + .collect() + } + + /// **THE EXACT COMMAND FOR A DEFAULT TURN**: accept-edits, the long print + /// timeout, the workspace as the working directory. + #[test] + fn a_default_turn_is_started_with_exactly_this_command() { + let cmd = AgyBackend::new(PathBuf::from("ws")).command("p"); + assert_eq!(cmd.get_program(), "agy"); + assert_eq!( + args_of(&cmd), + strings(&[ + "--print", + "p", + "--output-format", + "stream-json", + "--print-timeout", + "30m", + "--mode", + "accept-edits", + ]) + ); + assert_eq!(cmd.get_current_dir(), Some(std::path::Path::new("ws"))); + assert!(set_envs(&cmd).is_empty(), "{:?}", set_envs(&cmd)); + } + + /// **THE EXACT COMMAND WITH EVERYTHING SET**: a model, plan mode, two + /// extra roots and a conversation to resume. + #[test] + fn a_configured_turn_is_started_with_exactly_this_command() { + let mut backend = AgyBackend::new(PathBuf::from(".")).with_binary("/opt/agy"); + backend.set_models(&strings(&["sonnet", "gemini-3.1-pro-high"])); + backend.set_permission_mode("read-only"); + backend.set_extra_dirs(vec![PathBuf::from("a"), PathBuf::from("b")]); + backend.set_session_id("c-1"); + let cmd = backend.command("p"); + assert_eq!(cmd.get_program(), "/opt/agy"); + assert_eq!( + args_of(&cmd), + strings(&[ + "--print", + "p", + "--output-format", + "stream-json", + "--print-timeout", + "30m", + "--model", + "gemini-3.1-pro-high", + "--mode", + "plan", + "--add-dir", + "a", + "--add-dir", + "b", + "--conversation", + "c-1", + ]) + ); + + backend.set_permission_mode("danger-full-access"); + backend.clear_session(); + assert!( + !args_of(&backend.command("p")) + .iter() + .any(|a| a == "--mode" || a == "--conversation"), + "an unknown mode and a cleared session leave no flag" + ); + } + + /// A stand-in agy: prints `lines` on stdout, `stderr` on stderr, and + /// exits with `code`. + fn stand_in_agy(dir: &std::path::Path, lines: &[&str], stderr: &str, code: i32) -> PathBuf { + #[cfg(windows)] + { + let mut body = String::from("@echo off\r\n"); + for line in lines { + body.push_str(&format!("echo {line}\r\n")); + } + if !stderr.is_empty() { + body.push_str(&format!("echo {stderr} 1>&2\r\n")); + } + body.push_str(&format!("exit /b {code}\r\n")); + let path = dir.join("agy.cmd"); + std::fs::write(&path, body).expect("write the stand-in agy"); + path + } + #[cfg(not(windows))] + { + use std::os::unix::fs::PermissionsExt; + let mut body = String::from("#!/bin/sh\n"); + for line in lines { + body.push_str(&format!("echo '{line}'\n")); + } + if !stderr.is_empty() { + body.push_str(&format!("echo '{stderr}' >&2\n")); + } + body.push_str(&format!("exit {code}\n")); + let path = dir.join("agy.sh"); + std::fs::write(&path, body).expect("write the stand-in agy"); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) + .expect("make it runnable"); + path + } + } + + /// One turn through `run_turn` on a stand-in, with its events. + fn turn_on( + lines: &[&str], + stderr: &str, + code: i32, + set_up: impl FnOnce(&mut AgyBackend), + ) -> (Result, Vec, AgyBackend) { + let dir = tempfile::tempdir().expect("scratch"); + let fake = stand_in_agy(dir.path(), lines, stderr, code); + let mut backend = + AgyBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); + set_up(&mut backend); + let mut seen = Vec::new(); + let result = backend + .run_turn("hi", &mut |e| seen.push(e.clone())) + .map_err(|e| e.to_string()); + (result, seen, backend) + } + + const INIT: &str = r#"{"event":"init","conversation_id":"conv-1","init":{"tools":["view_file","invoke_subagent"]}}"#; + + /// **A WHOLE TURN**: the session, each fragment live, the step's text + /// once, the last usage reported, a garbage line skipped, and the + /// conversation the result names kept for the next turn. + #[test] + fn a_whole_turn_reports_these_events_and_this_outcome() { + let (result, seen, backend) = turn_on( + &[ + INIT, + r#"{"event":"step_update","step_update":{"step_index":1,"step_type":"agent_response","text_delta":"PO"}}"#, + "not json", + r#"{"event":"step_update","step_update":{"step_index":1,"step_type":"agent_response","text_delta":"NG","usage":{"input_tokens":7,"output_tokens":3,"cache_read_tokens":2}}}"#, + r#"{"event":"step_update","step_update":{"step_index":2,"step_type":"tool_call","text_delta":"ignored"}}"#, + r#"{"event":"something_new"}"#, + r#"{"event":"result","result":{"conversation_id":"conv-2","status":"SUCCESS","usage":{"input_tokens":9,"output_tokens":4,"cache_read_tokens":5}}}"#, + ], + "", + 0, + |b| b.set_models(&strings(&["gemini-3.8-flash-high"])), + ); + assert_eq!( + seen, + vec![ + AgentEvent::SessionStarted { + session_id: "conv-1".to_string(), + model: "gemini-3.8-flash-high".to_string(), + }, + AgentEvent::TextDelta("PO".to_string()), + AgentEvent::TextDelta("NG".to_string()), + AgentEvent::Text("PONG".to_string()), + AgentEvent::Usage { + input_tokens: 9, + output_tokens: 4, + cache_creation_tokens: 0, + cache_read_tokens: 5, + }, + ] + ); + assert_eq!( + result.expect("a result line"), + TurnOutcome { + session_id: "conv-2".to_string(), + stop_reason: "SUCCESS".to_string(), + is_error: false, + detail: None, + served_by: strings(&["gemini-3.8-flash-high"]), + } + ); + assert_eq!(backend.session_id(), Some("conv-2")); + } + + /// A step's usage stands when the result carries none; an `ERROR` status + /// is a failed outcome carrying the agent's reason. + #[test] + fn an_error_result_is_an_outcome_with_the_agents_reason() { + let (result, seen, _) = turn_on( + &[ + INIT, + r#"{"event":"step_update","step_update":{"step_index":0,"step_type":"agent_response","text_delta":"","usage":{"input_tokens":2,"output_tokens":1,"cache_read_tokens":0}}}"#, + r#"{"event":"result","result":{"conversation_id":"conv-1","status":"ERROR","error":"model x is not recognized"}}"#, + ], + "", + 1, + |_| {}, + ); + assert_eq!( + seen, + vec![ + AgentEvent::SessionStarted { + session_id: "conv-1".to_string(), + model: String::new(), + }, + AgentEvent::Usage { + input_tokens: 2, + output_tokens: 1, + cache_creation_tokens: 0, + cache_read_tokens: 0, + }, + ] + ); + assert_eq!( + result.expect("a result line"), + TurnOutcome { + session_id: "conv-1".to_string(), + stop_reason: "ERROR".to_string(), + is_error: true, + detail: Some("model x is not recognized".to_string()), + served_by: Vec::new(), + } + ); + } + + /// No result line: the exact error, with and without stderr, after the + /// usage is still reported. + #[test] + fn a_turn_without_a_result_fails_with_this_error() { + let (result, seen, backend) = turn_on(&[INIT], "boom", 3, |_| {}); + assert_eq!( + result.expect_err("no result line"), + "the agent produced no result line (exit 3): boom" + ); + assert_eq!( + seen.last(), + Some(&AgentEvent::Usage { + input_tokens: 0, + output_tokens: 0, + cache_creation_tokens: 0, + cache_read_tokens: 0, + }) + ); + assert_eq!(backend.session_id(), Some("conv-1")); + + let (quiet, _, _) = turn_on(&[INIT], "", 0, |_| {}); + assert_eq!( + quiet.expect_err("no result line"), + "the agent produced no result line (exit 0)" + ); + } + + /// A stopped turn says so, before handling any output. + #[test] + fn a_cancelled_turn_stops_with_this_error() { + let (result, seen, _) = turn_on(&[INIT], "", 0, |b| { + let token = crate::runtime::cancel::CancelToken::new(); + token.cancel(); + b.set_cancel(token); + }); + assert_eq!(result.expect_err("cancelled"), "the turn was cancelled"); + assert!(seen.is_empty(), "{seen:?}"); + } + + /// A CLI that cannot be started names itself in the error. + #[test] + fn a_cli_that_cannot_start_is_named_in_the_error() { + let dir = tempfile::tempdir().expect("scratch"); + let missing = dir.path().join("no-such-agy-binary"); + let mut backend = + AgyBackend::new(dir.path().to_path_buf()).with_binary(missing.to_string_lossy()); + let err = backend + .run_turn("hi", &mut |_| {}) + .expect_err("nothing to start"); + assert!( + err.to_string() + .starts_with(&format!("could not start `{}`: ", missing.display())), + "{err}" + ); + } } diff --git a/src/agent/claude_code.rs b/src/agent/claude_code.rs index 18c84d0..eb19f28 100644 --- a/src/agent/claude_code.rs +++ b/src/agent/claude_code.rs @@ -2996,4 +2996,562 @@ pub(crate) mod tests { path } } + + // ----------------------------------------------------------------------- + // Pinned behaviour: every wire shape `map_line` reads, the exact argv and + // environment a turn is started with, and what a whole turn reports. + // ----------------------------------------------------------------------- + + /// A turn outcome, spelled out. + fn outcome_of( + session: &str, + stop: &str, + is_error: bool, + detail: Option<&str>, + served_by: &[&str], + ) -> TurnOutcome { + TurnOutcome { + session_id: session.to_string(), + stop_reason: stop.to_string(), + is_error, + detail: detail.map(str::to_string), + served_by: served_by.iter().map(|m| (*m).to_string()).collect(), + } + } + + fn usage_of(input: u32, output: u32, creation: u32, read: u32) -> AgentEvent { + AgentEvent::Usage { + input_tokens: input, + output_tokens: output, + cache_creation_tokens: creation, + cache_read_tokens: read, + } + } + + /// **EVERY WIRE SHAPE, AND WHAT IT BECOMES.** One line per branch of the + /// mapping — each event type, the subagent and empty cases, every way a + /// failed result can describe itself, and lines that do not parse. + #[test] + fn the_map_line_corpus_is_pinned() { + let text = |t: &str| AgentEvent::Text(t.to_string()); + let started = |s: &str, m: &str| AgentEvent::SessionStarted { + session_id: s.to_string(), + model: m.to_string(), + }; + let none: Vec = Vec::new(); + let cases: Vec<(&str, Vec, Option)> = vec![ + // system + ( + r#"{"type":"system","subtype":"init","session_id":"s1","model":"m1"}"#, + vec![started("s1", "m1")], + None, + ), + ( + r#"{"type":"system","subtype":"init"}"#, + vec![started("", "unknown")], + None, + ), + ( + r#" {"type":"system","subtype":"init","session_id":"s2"} "#, + vec![started("s2", "unknown")], + None, + ), + ( + r#"{"type":"system","subtype":"hook_started","hook_id":"h"}"#, + none.clone(), + None, + ), + (r#"{"type":"system"}"#, none.clone(), None), + // stream_event + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hi"}},"parent_tool_use_id":null}"#, + vec![AgentEvent::TextDelta("hi".to_string())], + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":""}}}"#, + none.clone(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta"}}}"#, + none.clone(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"why"}}}"#, + vec![AgentEvent::Thinking("why".to_string())], + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":""}}}"#, + none.clone(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"x"}},"parent_tool_use_id":"toolu_9"}"#, + none.clone(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"x"}},"parent_tool_use_id":"toolu_9"}"#, + none.clone(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0},"parent_tool_use_id":null}"#, + none.clone(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"input_json_delta","partial_json":"{}"}}}"#, + none.clone(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_start","delta":{"type":"text_delta","text":"x"}}}"#, + none.clone(), + None, + ), + (r#"{"type":"stream_event"}"#, none.clone(), None), + // assistant + ( + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"a"},{"type":"tool_use","id":"t1","name":"Write","input":{}},{"type":"thinking","thinking":"hm"},{"type":"text","text":"b"}]},"parent_tool_use_id":null}"#, + vec![text("a"), text("b")], + None, + ), + ( + r#"{"type":"assistant","message":{"content":[{"type":"text","text":""}]}}"#, + vec![text("")], + None, + ), + (r#"{"type":"assistant","message":{}}"#, none.clone(), None), + ( + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"sub"}]},"parent_tool_use_id":"toolu_2"}"#, + none.clone(), + None, + ), + (r#"{"type":"assistant"}"#, none.clone(), None), + // user lines carry tool results incode already showed + ( + r#"{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"t1","content":"ok"}]}}"#, + none.clone(), + None, + ), + // rate_limit_event + ( + r#"{"type":"rate_limit_event","rate_limit_info":{"status":"rejected"}}"#, + vec![AgentEvent::Quota { + status: "rejected".to_string(), + kind: String::new(), + resets_at: 0, + using_overage: false, + }], + None, + ), + ( + r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning","resetsAt":17,"rateLimitType":"seven_day","isUsingOverage":true}}"#, + vec![AgentEvent::Quota { + status: "allowed_warning".to_string(), + kind: "seven_day".to_string(), + resets_at: 17, + using_overage: true, + }], + None, + ), + (r#"{"type":"rate_limit_event"}"#, none.clone(), None), + // result + ( + r#"{"type":"result","is_error":false,"session_id":"r1"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r1", "unknown", false, None, &[])), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r1","stop_reason":"max_tokens","result":"the reply","subtype":"success","usage":{"input_tokens":3,"output_tokens":4,"cache_creation_input_tokens":5,"cache_read_input_tokens":6}}"#, + vec![usage_of(3, 4, 5, 6)], + Some(outcome_of("r1", "max_tokens", false, None, &[])), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","stop_reason":"stop_sequence","subtype":"error_x","result":"said"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of( + "r2", + "stop_sequence", + true, + Some("error_x: said"), + &[], + )), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","subtype":"error_max_turns"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of( + "r2", + "unknown", + true, + Some("error_max_turns"), + &[], + )), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","result":"boom"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r2", "unknown", true, Some("boom"), &[])), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r2", "unknown", true, None, &[])), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","subtype":" ","result":" "}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r2", "unknown", true, None, &[])), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","subtype":" k ","result":" t "}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r2", "unknown", true, Some("k: t"), &[])), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r3","usage":{"input_tokens":1,"iterations":[{"input_tokens":9},{"input_tokens":10,"output_tokens":5,"cache_read_input_tokens":100,"cache_creation_input_tokens":20}]},"modelUsage":{"b-model":{"inputTokens":50,"contextWindow":200000},"a-model":{"inputTokens":1,"contextWindow":1000}}}"#, + vec![ + usage_of(1, 0, 0, 0), + AgentEvent::Context { + used: 135, + size: 200_000, + }, + ], + Some(outcome_of( + "r3", + "unknown", + false, + None, + &["a-model", "b-model"], + )), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r4","usage":{"iterations":[]},"modelUsage":{"m":{"contextWindow":200000}}}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r4", "unknown", false, None, &["m"])), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r5","usage":{"iterations":[{"input_tokens":1}]},"modelUsage":{"m":{"contextWindow":0}}}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r5", "unknown", false, None, &["m"])), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r6","usage":{"iterations":[{"input_tokens":1}]},"modelUsage":{"m":{"inputTokens":1}}}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r6", "unknown", false, None, &["m"])), + ), + (r#"{"type":"result","is_error":false}"#, none.clone(), None), + (r#"{"type":"result","session_id":"r7"}"#, none.clone(), None), + // unknown and malformed + ( + r#"{"type":"some_future_event","payload":{}}"#, + none.clone(), + None, + ), + ("not json", none.clone(), None), + ("", none.clone(), None), + ("[]", none.clone(), None), + ("null", none.clone(), None), + ("{}", none.clone(), None), + (r#"{"type":42}"#, none.clone(), None), + ( + r#"{"type":"assistant","message":{"content":[{"type":"text"}]}}"#, + none, + None, + ), + ]; + for (line, events, outcome) in cases { + let mut got = None; + assert_eq!(map_line(line, &mut got), events, "events of {line}"); + assert_eq!(got, outcome, "outcome of {line}"); + } + } + + /// Only a result line touches the outcome; every other line leaves an + /// earlier one in place. + #[test] + fn only_a_result_line_writes_the_outcome() { + let earlier = outcome_of("before", "end_turn", false, None, &[]); + for line in [ + r#"{"type":"system","subtype":"init","session_id":"s"}"#, + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"a"}]}}"#, + r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed"}}"#, + "not json", + ] { + let mut outcome = Some(earlier.clone()); + map_line(line, &mut outcome); + assert_eq!(outcome.as_ref(), Some(&earlier), "{line}"); + } + } + + /// The environment a command sets or removes, minus the entries that + /// depend on the machine: the profile choice, and the session variables + /// removed only when this process inherited them. + fn pinned_envs(cmd: &Command) -> Vec<(String, Option)> { + let mut envs: Vec<(String, Option)> = cmd + .get_envs() + .map(|(k, v)| { + ( + k.to_string_lossy().into_owned(), + v.map(|v| v.to_string_lossy().into_owned()), + ) + }) + .filter(|(k, _)| { + let upper = k.to_ascii_uppercase(); + upper != PROFILE_ENV + && upper != "SESSION_INGRESS_URL" + && !upper.starts_with("CLAUDE_CODE_SESSION") + && !upper.starts_with("CLAUDE_CODE_REMOTE") + }) + .collect(); + envs.sort(); + envs + } + + /// The environment every turn's command carries, sorted. + fn turn_envs() -> Vec<(String, Option)> { + let mut envs: Vec<(String, Option)> = [ + "CLAUDECODE", + "CLAUDE_CODE_ENTRYPOINT", + "CLAUDE_CODE_CHILD_SESSION", + "CLAUDE_CODE_MESSAGING_SOCKET", + "CLAUDE_CODE_MESSAGING_TOKEN", + "CLAUDE_SESSION_INGRESS_TOKEN_FILE", + ] + .into_iter() + .map(|k| (k.to_string(), None)) + .chain([ + ( + "CLAUDE_CODE_DISABLE_CLAUDE_MDS".to_string(), + Some("1".to_string()), + ), + ( + "CLAUDE_CODE_DISABLE_AUTO_MEMORY".to_string(), + Some("1".to_string()), + ), + ]) + .collect(); + envs.sort(); + envs + } + + fn strings(items: &[&str]) -> Vec { + items.iter().map(|s| (*s).to_string()).collect() + } + + /// **THE EXACT ARGV AND ENVIRONMENT, FOR A PLAIN TURN.** Guards, a + /// permission mode and extra roots change nothing on the command line: + /// the toolbox enforces them. + #[test] + fn a_plain_turn_is_started_with_exactly_this_command() { + let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")) + .with_guards(&crate::guards::Guards::default()) + .with_extra_dirs(vec![PathBuf::from("other-root")]); + backend.set_permission_mode("acceptEdits"); + let allowed = strings(&["mcp__incode"]); + let cmd = backend.command(Some("hi"), "", "SERVERS", &allowed); + assert_eq!(cmd.get_program(), "claude"); + assert_eq!( + args_of(&cmd), + strings(&[ + "-p", + "hi", + "--output-format", + "stream-json", + "--tools", + "", + "--strict-mcp-config", + "--setting-sources", + "", + "--disable-slash-commands", + "--verbose", + "--mcp-config", + "SERVERS", + "--allowedTools", + "mcp__incode", + ]) + ); + assert_eq!(pinned_envs(&cmd), turn_envs()); + assert_eq!(cmd.get_current_dir(), None); + } + + /// **THE EXACT ARGV FOR A TURN WITH EVERYTHING SET**: pictures (prompt on + /// stdin), a model chain, streaming, context and a session to resume. + #[test] + fn a_fully_configured_turn_is_started_with_exactly_this_command() { + let backend = ClaudeCodeBackend::new(PathBuf::from(".")) + .with_binary("/opt/agent/claude") + .with_models(&strings(&["opus", "sonnet", "haiku"])) + .with_session("s-9") + .streaming(true); + let allowed = strings(&["a", "b"]); + let cmd = backend.command(None, "CTX", "SERVERS", &allowed); + assert_eq!(cmd.get_program(), "/opt/agent/claude"); + assert_eq!( + args_of(&cmd), + strings(&[ + "-p", + "--input-format", + "stream-json", + "--output-format", + "stream-json", + "--tools", + "", + "--strict-mcp-config", + "--setting-sources", + "", + "--disable-slash-commands", + "--verbose", + "--mcp-config", + "SERVERS", + "--allowedTools", + "a", + "b", + "--model", + "opus", + "--include-partial-messages", + "--thinking-display", + "summarized", + "--append-system-prompt", + "CTX", + "--fallback-model", + "sonnet,haiku", + "--resume", + "s-9", + ]) + ); + assert_eq!(pinned_envs(&cmd), turn_envs()); + } + + /// Once the CLI has refused the thinking flag, a streaming turn is + /// started without it — and nothing else changes. + #[test] + fn a_turn_after_the_thinking_flag_was_refused_omits_only_that_flag() { + let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")).streaming(true); + backend.thinking_display = false; + let cmd = backend.command(Some("q"), "", "S", &[]); + assert_eq!( + args_of(&cmd), + strings(&[ + "-p", + "q", + "--output-format", + "stream-json", + "--tools", + "", + "--strict-mcp-config", + "--setting-sources", + "", + "--disable-slash-commands", + "--verbose", + "--mcp-config", + "S", + "--allowedTools", + "--include-partial-messages", + ]) + ); + } + + /// The stdin message for a turn with no pictures, byte for byte. + #[test] + fn the_stdin_message_is_pinned() { + assert_eq!( + user_message("hi", &[]), + "{\"type\":\"user\",\"message\":{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"hi\"}]}}\n" + ); + } + + /// **A WHOLE TURN THROUGH `run_turn`**: the events in order, the outcome, + /// and the session kept for the next turn. + #[test] + fn a_whole_turn_reports_these_events_and_this_outcome() { + let dir = tempfile::tempdir().expect("scratch"); + let fake = stand_in_cli(dir.path(), false); + let mut backend = + ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); + let mut seen = Vec::new(); + let outcome = backend + .run_turn("hi", &mut |e| seen.push(e.clone())) + .expect("the stand-in finishes its turn"); + assert_eq!( + seen, + vec![ + AgentEvent::SessionStarted { + session_id: "sub-conv-1".to_string(), + model: "fake-sub-model".to_string(), + }, + AgentEvent::Thinking("looking around".to_string()), + AgentEvent::TextDelta("three files".to_string()), + AgentEvent::Text("three files".to_string()), + usage_of(1, 1, 0, 0), + ] + ); + assert_eq!( + outcome, + outcome_of("sub-conv-1", "end_turn", false, None, &[]) + ); + assert_eq!(backend.session_id(), Some("sub-conv-1")); + } + + /// A CLI that cannot be started names itself in the error. + #[test] + fn a_cli_that_cannot_start_is_named_in_the_error() { + let dir = tempfile::tempdir().expect("scratch"); + let missing = dir.path().join("no-such-agent-binary"); + let mut backend = + ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(missing.to_string_lossy()); + let err = backend + .run_turn("hi", &mut |_| {}) + .expect_err("nothing to start"); + assert!( + err.to_string() + .starts_with(&format!("failed to spawn `{}`: ", missing.display())), + "{err}" + ); + } + + /// A stand-in that starts a session and exits cleanly, saying nothing + /// else and writing nothing to stderr. + fn a_cli_that_ends_without_a_result(dir: &std::path::Path) -> PathBuf { + const INIT: &str = r#"{"type":"system","subtype":"init","session_id":"cut-1","model":"m"}"#; + #[cfg(windows)] + { + let path = dir.join("cut-agent.cmd"); + std::fs::write(&path, format!("@echo off\r\necho {INIT}\r\nexit /b 0\r\n")) + .expect("write the stand-in agent"); + path + } + #[cfg(not(windows))] + { + use std::os::unix::fs::PermissionsExt; + let path = dir.join("cut-agent.sh"); + std::fs::write(&path, format!("#!/bin/sh\necho '{INIT}'\nexit 0\n")) + .expect("write the stand-in agent"); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) + .expect("make it runnable"); + path + } + } + + /// No result line: the exact error, and the session still kept. + #[test] + fn a_turn_without_a_result_fails_with_this_error_and_keeps_its_session() { + let dir = tempfile::tempdir().expect("scratch"); + let fake = a_cli_that_ends_without_a_result(dir.path()); + let mut backend = + ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); + let err = backend + .run_turn("hi", &mut |_| {}) + .expect_err("no result line"); + assert_eq!( + err.to_string(), + "agent exited with 0 before producing a result: " + ); + assert_eq!(backend.session_id(), Some("cut-1")); + } } From 7a9aa77c041b6c73eb57d1d23669b5c22598d525 Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Fri, 23 Oct 2026 14:09:29 -0600 Subject: [PATCH 2/3] refactor(claude_code, agy): split the backends, no behaviour change claude_code.rs (3557 lines with the pins) becomes src/agent/claude_code/: the backend and its AgentBackend face (mod.rs), the stream-json lines and what each becomes (wire.rs), the argv and environment a turn starts with (command.rs), one run of the CLI with the bridge and the stream loop (turn.rs), profile and login choice (profiles.rs), and deny rendering (deny.rs); tests split into tests.rs (stand_in_cli stays at its crate path), wire_tests.rs, command_tests.rs and profile_tests.rs. Everything other code names is re-exported, so every crate::agent::claude_code:: path is unchanged. map_line is a dispatch over named steps (session_started, stream_delta, assistant_text, quota, result_events, failure_detail); run_once is spawn plumbing plus trace_spawn, dump_argv, spawn and finish, with the process tree kept alive until stderr is read, as before. agy's run_turn becomes spawn, read, started, finished and no_result_line, and its tests move to agy_tests.rs. A stray doc comment that sat on PROFILE_ENV goes back to consume, which it describes. MAX_UNWIRED 41 -> 38, as the wiring ratchet asks. The old file had a column-zero #[cfg(test)] at line 8, so the scanner never read it: Toolbox::run_subagents_on and tool_bridge::client_entry were listed unwired while called from it, and are now seen. The third drop is NOT real wiring: guards::restrictions is still called only by tests, which the scanner now reads because test files reached by #[path]/mod have no column-zero marker (the same blind spot api_wire_tests.rs and the runner's test files already have). The pins from the previous commit pass unchanged. Co-Authored-By: Claude --- docs/ARCHITECTURE.md | 4 +- src/agent/agy.rs | 878 +----- src/agent/agy_tests.rs | 637 +++++ src/agent/claude_code.rs | 3557 ------------------------ src/agent/claude_code/command.rs | 181 ++ src/agent/claude_code/command_tests.rs | 411 +++ src/agent/claude_code/deny.rs | 42 + src/agent/claude_code/mod.rs | 566 ++++ src/agent/claude_code/profile_tests.rs | 213 ++ src/agent/claude_code/profiles.rs | 278 ++ src/agent/claude_code/tests.rs | 512 ++++ src/agent/claude_code/turn.rs | 308 ++ src/agent/claude_code/wire.rs | 380 +++ src/agent/claude_code/wire_tests.rs | 899 ++++++ src/wiring.rs | 2 +- 15 files changed, 4581 insertions(+), 4287 deletions(-) create mode 100644 src/agent/agy_tests.rs delete mode 100644 src/agent/claude_code.rs create mode 100644 src/agent/claude_code/command.rs create mode 100644 src/agent/claude_code/command_tests.rs create mode 100644 src/agent/claude_code/deny.rs create mode 100644 src/agent/claude_code/mod.rs create mode 100644 src/agent/claude_code/profile_tests.rs create mode 100644 src/agent/claude_code/profiles.rs create mode 100644 src/agent/claude_code/tests.rs create mode 100644 src/agent/claude_code/turn.rs create mode 100644 src/agent/claude_code/wire.rs create mode 100644 src/agent/claude_code/wire_tests.rs diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d6e56ba..0536fd8 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -691,7 +691,7 @@ That is why the fallback is traced rather than silent. ### The mechanical half -`agent/` discovers an installed agent and drives it as a model — `claude_code.rs` +`agent/` discovers an installed agent and drives it as a model — `claude_code/` speaks its stream protocol and opens the tool bridge per turn, `api.rs` is the API route's own tool loop, `catalogue.rs` is the one list of agents, `worker.rs` hands one ledger task at a time. `cli/` is the terminal, and `cli/agent_turn.rs` is one @@ -936,7 +936,7 @@ incode (parent) ──spawns──▶ agent CLI (the model; its own tools off) - `incode --tool-server` (`src/tool_bridge.rs`) speaks MCP on stdio to the CLI, through the framing shared with the team server (`src/mcp_stdio.rs`). It runs nothing: each `tools/list` and `tools/call` is forwarded to the parent over a loopback socket. -- The parent (`Bridge`, opened per turn by `src/agent/claude_code.rs` `run_turn`) binds +- The parent (`Bridge`, opened per turn by `src/agent/claude_code/turn.rs` `run_once`) binds `127.0.0.1:0`, makes a 256-bit token, and passes both to the CLI through its ENVIRONMENT (`INCODE_TOOL_BRIDGE`, `INCODE_TOOL_TOKEN`), never its argv. The CLI's stdio servers inherit that environment (measured live). diff --git a/src/agent/agy.rs b/src/agent/agy.rs index 82e1bea..83902ed 100644 --- a/src/agent/agy.rs +++ b/src/agent/agy.rs @@ -419,7 +419,68 @@ impl AgentBackend for AgyBackend { on_event: &mut dyn FnMut(&AgentEvent), ) -> Result { let sent = self.full_prompt(prompt)?; - let mut command = self.command(&sent); + let Running { + mut child, + tree, + stdout, + stderr, + } = self.spawn(&sent)?; + let mut turn = TurnSoFar::default(); + + for line in BufReader::new(stdout).lines() { + if self.cancel.as_ref().is_some_and(|t| t.is_cancelled()) { + tree.kill(&mut child); + return Err(AgentError::new("the turn was cancelled")); + } + let Ok(line) = line else { break }; + // A line this module does not understand is SKIPPED, never fatal: + // the CLI is free to add events, and a turn that died because of an + // unrecognised one would be a self-inflicted outage on upgrade. + let Ok(wire) = serde_json::from_str::(&line) else { + continue; + }; + self.read(wire, &mut turn, on_event); + } + turn.reply.finish(on_event); + + on_event(&AgentEvent::Usage { + input_tokens: turn.usage.input_tokens, + output_tokens: turn.usage.output_tokens, + cache_creation_tokens: turn.usage.cache_creation_input_tokens, + cache_read_tokens: turn.usage.cache_read_input_tokens, + }); + + let status = child + .wait() + .map_err(|e| AgentError::new(format!("the agent did not exit cleanly: {e}")))?; + + turn.outcome.ok_or_else(|| no_result_line(status, stderr)) + } +} + +/// A started agy, with what `run_turn` reads from it. +struct Running { + child: std::process::Child, + tree: crate::agent::process_tree::Tree, + stdout: std::process::ChildStdout, + stderr: crate::agent::stderr_tail::StderrTail, +} + +/// What a turn has gathered from the stream so far. +#[derive(Default)] +struct TurnSoFar { + outcome: Option, + usage: crate::runtime::usage::TokenUsage, + reply: StepText, +} + +impl AgyBackend { + /// The CLI started on `prompt` with its output piped, everything it starts + /// taken in, and its stderr drained from the start. + /// + /// Called by `run_turn`, once per turn. + fn spawn(&self, prompt: &str) -> Result { + let mut command = self.command(prompt); crate::agent::process_tree::prepare(&mut command); let mut child = command .stdout(Stdio::piped()) @@ -434,104 +495,105 @@ impl AgentBackend for AgyBackend { .ok_or_else(|| AgentError::new("the agent produced no output stream"))?; let stderr = crate::agent::stderr_tail::StderrTail::capture(child.stderr.take()); + Ok(Running { + child, + tree, + stdout, + stderr, + }) + } - let mut outcome: Option = None; - let mut usage = crate::runtime::usage::TokenUsage::default(); - let mut reply = StepText::default(); - - 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")); + /// One understood line of the stream, folded into `turn`. + /// + /// Called by `run_turn` for every line that parses. + fn read(&mut self, wire: Wire, turn: &mut TurnSoFar, on_event: &mut dyn FnMut(&AgentEvent)) { + match wire { + Wire::Init(init) => self.started(init, on_event), + Wire::StepUpdate { step_update } => { + turn.reply.feed(&step_update, on_event); + if let Some(u) = step_update.usage { + turn.usage = to_usage(&u); } } - let Ok(line) = line else { break }; - // A line this module does not understand is SKIPPED, never fatal: - // the CLI is free to add events, and a turn that died because of an - // unrecognised one would be a self-inflicted outage on upgrade. - let Ok(wire) = serde_json::from_str::(&line) else { - continue; - }; - match wire { - Wire::Init(init) => { - self.conversation_id = Some(init.conversation_id.clone()); - on_event(&AgentEvent::SessionStarted { - session_id: init.conversation_id, - model: self.model.clone().unwrap_or_default(), - }); - // Reported rather than acted on: the harness cannot remove - // a tool from this agent, so the honest thing is to record - // that the sub-agent tools were on offer. - if init.init.tools.iter().any(|t| t.contains("subagent")) { - crate::trace!( - "guards", - "agy offers sub-agent tools and cannot be told not to: {}", - init.init - .tools - .iter() - .filter(|t| t.contains("subagent")) - .cloned() - .collect::>() - .join(", ") - ); - } - } - Wire::StepUpdate { step_update } => { - reply.feed(&step_update, on_event); - if let Some(u) = step_update.usage { - usage = to_usage(&u); - } - } - Wire::Result { result } => { - if let Some(u) = &result.usage { - usage = to_usage(u); - } - let is_error = !result.status.eq_ignore_ascii_case("SUCCESS"); - self.conversation_id = Some(result.conversation_id.clone()); - outcome = Some(TurnOutcome { - session_id: result.conversation_id.clone(), - stop_reason: result.status.clone(), - is_error, - // This CLI reports no per-model billing record, so the - // model that was ASKED for is the only answer available - // — and it is labelled as such by being the requested - // one, never presented as a billing fact. - detail: result.error.clone().filter(|e| !e.trim().is_empty()), - served_by: self.model.clone().into_iter().collect(), - }); + Wire::Result { result } => { + if let Some(u) = &result.usage { + turn.usage = to_usage(u); } - Wire::Other => {} + turn.outcome = Some(self.finished(&result)); } + Wire::Other => {} } - reply.finish(on_event); + } - 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, + /// The conversation this turn runs in, kept for the next one and + /// announced. + /// + /// Called by [`Self::read`] on the `init` line. + fn started(&mut self, init: InitEvent, on_event: &mut dyn FnMut(&AgentEvent)) { + self.conversation_id = Some(init.conversation_id.clone()); + on_event(&AgentEvent::SessionStarted { + session_id: init.conversation_id, + model: self.model.clone().unwrap_or_default(), }); + // Reported rather than acted on: the harness cannot remove + // a tool from this agent, so the honest thing is to record + // that the sub-agent tools were on offer. + if init.init.tools.iter().any(|t| t.contains("subagent")) { + crate::trace!( + "guards", + "agy offers sub-agent tools and cannot be told not to: {}", + init.init + .tools + .iter() + .filter(|t| t.contains("subagent")) + .cloned() + .collect::>() + .join(", ") + ); + } + } - 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) - )) - }) + /// The turn's outcome, from the `result` line; the conversation it names + /// is kept for the next turn. + /// + /// Called by [`Self::read`] on the `result` line. + fn finished(&mut self, result: &ResultEvent) -> TurnOutcome { + let is_error = !result.status.eq_ignore_ascii_case("SUCCESS"); + self.conversation_id = Some(result.conversation_id.clone()); + TurnOutcome { + session_id: result.conversation_id.clone(), + stop_reason: result.status.clone(), + is_error, + // This CLI reports no per-model billing record, so the + // model that was ASKED for is the only answer available + // — and it is labelled as such by being the requested + // one, never presented as a billing fact. + detail: result.error.clone().filter(|e| !e.trim().is_empty()), + served_by: self.model.clone().into_iter().collect(), + } } } +/// The error for a turn that ended without a result line: its exit code, +/// and what it wrote on stderr when it wrote anything. +/// +/// Called by `run_turn` once the agent has exited. +fn no_result_line( + status: std::process::ExitStatus, + stderr: crate::agent::stderr_tail::StderrTail, +) -> AgentError { + 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) + )) +} + /// The assistant's words for a turn, rebuilt from step updates: each /// fragment is shown as it arrives (`TextDelta`), and each step's whole text /// is said once (`Text`) when the next step begins or the stream ends. @@ -583,643 +645,5 @@ fn to_usage(wire: &WireUsage) -> crate::runtime::usage::TokenUsage { } #[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. - #[test] - fn the_cli_never_joins_the_session_that_launched_incode() { - let cmd = AgyBackend::new(PathBuf::from(".")).command("p"); - assert!( - cmd.get_envs() - .any(|(k, v)| k == "CLAUDECODE" && v.is_none()), - "CLAUDECODE is inherited, so the child joins the parent's session" - ); - } - - /// **AN AGENT THAT CANNOT TAKE A PICTURE HEADLESS SAYS SO, BY NAME.** - /// `agy --help` (1.2.11) has no image flag, and its stream-json input - /// shape is not measured, so pictures are refused rather than dropped. - #[test] - fn pictures_are_refused_by_name() { - let picture = crate::toolbox::Image::from_base64( - "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC", - ) - .expect("a 1x1 png"); - let mut backend = AgyBackend::new(PathBuf::from(".")); - let why = backend - .attach_images(vec![picture]) - .expect_err("agy takes no pictures"); - assert!(why.starts_with("agy cannot take pictures"), "{why}"); - } - - fn parse(line: &str) -> Wire { - serde_json::from_str(line).expect("a wire line") - } - - /// **A REPLY STREAMED IN FRAGMENTS IS SAID ONCE, WHOLE.** Lines shaped as - /// a real long reply (measured on agy, Insi's lesson writer): fragments of - /// one step, `ACTIVE` then `DONE`, each a few words and split inside words - /// and inside a JSON key. The step is one `Text`, the fragments joined byte - /// for byte, so its JSON parses; every fragment is still shown live as a - /// `TextDelta`; a later step is a `Text` of its own. - #[test] - fn a_reply_streamed_in_fragments_is_said_once_whole() { - let line = |index: u64, state: &str, kind: &str, text: &str| { - format!( - r#"{{"event":"step_update","step_update":{{"step_index":{index},"state":"{state}","step_type":"{kind}","text_delta":{}}}}}"#, - serde_json::to_string(text).expect("json") - ) - }; - let stream = [ - line(0, "DONE", "user_input", ""), - line(2, "ACTIVE", "agent_response", "{\n \"issue"), - line(2, "ACTIVE", "agent_response", "\": \"The agent added anim"), - line( - 2, - "ACTIVE", - "agent_response", - "ation math\",\n \"use\": \"Wire it", - ), - line(2, "DONE", "agent_response", " end to end.\"\n}"), - line(4, "DONE", "agent_response", "Done."), - ]; - let mut said = Vec::new(); - let mut deltas = 0; - { - let mut on_event = |event: &AgentEvent| match event { - AgentEvent::Text(text) => said.push(text.clone()), - AgentEvent::TextDelta(_) => deltas += 1, - _ => {} - }; - let mut reply = StepText::default(); - for wire in stream.iter().map(|l| parse(l)) { - if let Wire::StepUpdate { step_update } = wire { - reply.feed(&step_update, &mut on_event); - } - } - reply.finish(&mut on_event); - } - assert_eq!(said.len(), 2, "{said:?}"); - let answer: serde_json::Value = - serde_json::from_str(&said[0]).expect("the whole reply parses"); - assert_eq!(answer["issue"], "The agent added animation math"); - assert_eq!(answer["use"], "Wire it end to end."); - assert_eq!(said[1], "Done."); - assert_eq!(deltas, 5, "every fragment shown as it came"); - } - - /// The envelope is keyed on `event`, not `type`. - /// - /// Copied from a real v1.1.23 run. If this ever parses as `Other` the CLI - /// changed its envelope, and every other test here would still pass while - /// the backend silently read nothing. - #[test] - fn the_init_line_from_a_real_run_is_understood() { - let wire = parse( - r#"{"event":"init","conversation_id":"1b343cea","init":{"cwd":"C:\\tmp","tools":["view_file","invoke_subagent"],"permission_mode":"request-review"}}"#, - ); - match wire { - Wire::Init(init) => { - assert_eq!(init.conversation_id, "1b343cea"); - assert!(init.init.tools.iter().any(|t| t == "invoke_subagent")); - } - other => panic!("the init envelope was not recognised: {other:?}"), - } - } - - /// Assistant text arrives on a step update, not a content block. - #[test] - fn the_agents_reply_is_read_from_a_step_update() { - let wire = parse( - r#"{"event":"step_update","step_update":{"step_index":1,"state":"DONE","step_type":"agent_response","text_delta":"PONG\n","usage":{"input_tokens":16317,"output_tokens":183,"cache_read_tokens":0}}}"#, - ); - match wire { - Wire::StepUpdate { step_update } => { - assert_eq!(step_update.step_type, "agent_response"); - assert_eq!(step_update.text_delta, "PONG\n"); - let u = to_usage(&step_update.usage.expect("usage")); - assert_eq!(u.input_tokens, 16317); - assert_eq!(u.output_tokens, 183); - } - other => panic!("a step update was not recognised: {other:?}"), - } - } - - /// **Every `status: ERROR` moves the work, whatever the wording.** - /// - /// The three the owner named — a lapsed subscription, a model the account - /// cannot reach, a model that is busy — arrive with three unrelated - /// messages and one identical status. Only the middle one is in the phrase - /// list; the first and third are asserted below to MISS it, which is what - /// makes reading the status the fix rather than a longer list. - #[test] - fn any_error_status_moves_the_work_however_it_is_worded() { - let backend = AgyBackend::new(std::path::PathBuf::from(".")); - let failed = |detail: &str| crate::agent::TurnOutcome { - session_id: "c1".to_string(), - stop_reason: "ERROR".to_string(), - is_error: true, - detail: Some(detail.to_string()), - served_by: Vec::new(), - }; - - // VERBATIM from the live run. - let busy = - "Our servers are experiencing high traffic right now, please try again in a minute."; - let lapsed = "Your plan does not include this model."; - let missing = "model sonnet is not recognized"; - - assert!( - !crate::agent::moves_the_work(busy) && !crate::agent::moves_the_work(lapsed), - "the control holds only while the phrase list really does miss these" - ); - for detail in [busy, lapsed, missing] { - assert!( - backend.agent_failed(&failed(detail)), - "an ERROR status is the agent's own failure: {detail}" - ); - } - - // A turn the agent COMPLETED is never moved, however it reads — that is - // the harness's own check to judge, and walking a wrong task through - // every subscription spends them all to learn one thing. - let finished = crate::agent::TurnOutcome { - session_id: "c1".to_string(), - stop_reason: "SUCCESS".to_string(), - is_error: false, - detail: None, - served_by: Vec::new(), - }; - assert!(!backend.agent_failed(&finished)); - } - - /// A non-SUCCESS status is a failed turn, and says which status it was. - #[test] - fn a_failed_turn_is_reported_with_the_status_that_caused_it() { - let ok = - parse(r#"{"event":"result","result":{"conversation_id":"c1","status":"SUCCESS"}}"#); - let bad = - parse(r#"{"event":"result","result":{"conversation_id":"c1","status":"CANCELLED"}}"#); - let status_of = |w: Wire| match w { - Wire::Result { result } => ( - result.status.clone(), - !result.status.eq_ignore_ascii_case("SUCCESS"), - ), - other => panic!("a result line was not recognised: {other:?}"), - }; - assert_eq!(status_of(ok), ("SUCCESS".to_string(), false)); - assert_eq!(status_of(bad), ("CANCELLED".to_string(), true)); - } - - /// An unknown event is ignored, never fatal — the CLI may add events. - #[test] - fn an_unrecognised_event_does_not_break_the_turn() { - assert!(matches!( - parse(r#"{"event":"something_new_in_a_later_release"}"#), - Wire::Other - )); - } - - /// **This backend enforces nothing, and says so.** - /// - /// The measured reason: no per-tool deny flag exists on this CLI, and its - /// own init line advertises four sub-agent tools. Claiming enforcement it - /// does not have would be the exact failure the guard docs warn about. - #[test] - fn this_backend_claims_no_enforcement_it_does_not_have() { - let backend = AgyBackend::new(PathBuf::from(".")); - assert_eq!( - backend.enforces(), - crate::guards::Enforcement::NOTHING, - "claiming enforcement this CLI has no flag for would report a guard \ - that is not there" - ); - } - - /// The harness's policy becomes a REPORTED GAP here, not a silent drop. - #[test] - fn the_whole_policy_is_reported_as_unenforced_on_this_agent() { - let policy = crate::guards::restrictions(&crate::guards::Guards::default()); - let gaps = policy.unenforced_by(&AgyBackend::new(PathBuf::from(".")).enforces()); - assert_eq!(gaps.len(), 2, "both halves must be reported: {gaps:?}"); - assert!(gaps.iter().any(|g| g.contains("protected path"))); - assert!(gaps.iter().any(|g| g.contains("sub-agents"))); - } - - /// Only the first SERVEABLE candidate survives: no fallback chain here. - #[test] - fn a_fallback_chain_collapses_to_the_first_choice() { - let mut backend = AgyBackend::new(PathBuf::from(".")); - backend.set_models(&[ - "gemini-3.8-flash-high".to_string(), - "gemini-3.1-pro-high".to_string(), - ]); - assert_eq!(backend.model(), Some("gemini-3.8-flash-high")); - } - - /// **Another vendor's model id is NOT forwarded.** - /// - /// The live failure: the role ladder holds `sonnet`/`opus`, this agent - /// answered `status: ERROR, error: model sonnet is not recognized`, and - /// every task in the run died before any work began. Leaving the agent's - /// own default standing loses routing; forwarding the name loses the run. - #[test] - fn a_foreign_model_id_is_dropped_rather_than_sent() { - let mut backend = AgyBackend::new(PathBuf::from(".")); - backend.set_models(&["sonnet".to_string(), "opus".to_string()]); - assert_eq!( - backend.model(), - None, - "a model this agent cannot serve must not reach its command line" - ); - - // Control: a ladder it CAN serve is still honoured, so the assertion - // above is not passing because nothing is ever accepted. - backend.set_models(&["sonnet".to_string(), "gemini-3.1-pro-high".to_string()]); - assert_eq!(backend.model(), Some("gemini-3.1-pro-high")); - } - - /// **This agent routes on its OWN ladder, not the operator's foreign one.** - /// - /// Before this, a ladder of `sonnet, opus` left the agent un-routed and - /// every role ran on its default — the expensive one. The ids below come - /// from `agy models`, and a cheap role must not draw the strong model. - #[test] - fn each_role_draws_a_model_this_agent_actually_has() { - let backend = AgyBackend::new(PathBuf::from(".")); - for role in crate::roles::KNOWN_ROLES { - for id in backend.ladder_for(role) { - assert!( - backend.serves(&id), - "role {role} was given `{id}`, which this agent cannot serve" - ); - } - } - assert_ne!( - backend.ladder_for("explore"), - backend.ladder_for("implement"), - "reading and writing must not draw the same tier, or routing saves nothing" - ); - assert!( - backend.ladder_for("no-such-role").is_empty(), - "an unknown role gets the agent's default, never a guess" - ); - } - - /// A failed turn carries the agent's OWN reason, not a shrug. - #[test] - fn a_failure_reports_the_reason_the_agent_gave() { - let line = r#"{"event":"result","result":{"conversation_id":"c1","status":"ERROR","error":"model sonnet is not recognized"}}"#; - match parse(line) { - Wire::Result { result } => { - let detail = result.error.clone().filter(|e| !e.trim().is_empty()); - assert_eq!( - detail.as_deref(), - Some("model sonnet is not recognized"), - "the reason the agent gave was discarded" - ); - } - other => panic!("not a result: {other:?}"), - } - } - - /// **The harness's context reaches this agent even with no flag for it.** - /// - /// The pinned failure on the other backend was a run where every task was - /// worked by an agent told none of the guards, findings or roles. This CLI - /// has no `--append-system-prompt`, so the same loss would happen silently - /// unless the context is carried in the prompt instead. - #[test] - fn the_harness_context_is_carried_in_the_prompt_when_no_flag_exists() { - let bare = AgyBackend::new(PathBuf::from(".")); - assert_eq!( - bare.full_prompt("do the work").expect("sent"), - "do the work" - ); - - let briefed = AgyBackend::new(PathBuf::from(".")) - .with_system_context(vec!["the guards in force: tests/ is protected".to_string()]); - let sent = briefed.full_prompt("do the work").expect("sent"); - assert!( - sent.contains("tests/ is protected"), - "the harness context never reached the agent: {sent}" - ); - assert!( - sent.ends_with("do the work"), - "the task must come last, after its context: {sent}" - ); - } - - /// An unknown permission mode leaves the agent's default standing. - #[test] - fn an_unknown_permission_mode_is_not_passed_through() { - let mut backend = AgyBackend::new(PathBuf::from(".")); - backend.set_permission_mode("danger-full-access"); - assert!( - backend.mode.is_none(), - "passing a word this CLI rejects would fail the turn over a setting" - ); - backend.set_permission_mode("plan"); - assert_eq!(backend.mode.as_deref(), Some("plan")); - } - - // ----------------------------------------------------------------------- - // Pinned behaviour: the exact command a turn is started with, and what a - // whole turn through `run_turn` reports. - // ----------------------------------------------------------------------- - - fn args_of(cmd: &Command) -> Vec { - cmd.get_args() - .map(|a| a.to_string_lossy().into_owned()) - .collect() - } - - fn strings(items: &[&str]) -> Vec { - items.iter().map(|s| (*s).to_string()).collect() - } - - /// What the command SETS in the environment. Removals are the parent - /// session's variables, guarded by the test above. - fn set_envs(cmd: &Command) -> Vec<(String, String)> { - cmd.get_envs() - .filter_map(|(k, v)| { - Some(( - k.to_string_lossy().into_owned(), - v?.to_string_lossy().into_owned(), - )) - }) - .collect() - } - - /// **THE EXACT COMMAND FOR A DEFAULT TURN**: accept-edits, the long print - /// timeout, the workspace as the working directory. - #[test] - fn a_default_turn_is_started_with_exactly_this_command() { - let cmd = AgyBackend::new(PathBuf::from("ws")).command("p"); - assert_eq!(cmd.get_program(), "agy"); - assert_eq!( - args_of(&cmd), - strings(&[ - "--print", - "p", - "--output-format", - "stream-json", - "--print-timeout", - "30m", - "--mode", - "accept-edits", - ]) - ); - assert_eq!(cmd.get_current_dir(), Some(std::path::Path::new("ws"))); - assert!(set_envs(&cmd).is_empty(), "{:?}", set_envs(&cmd)); - } - - /// **THE EXACT COMMAND WITH EVERYTHING SET**: a model, plan mode, two - /// extra roots and a conversation to resume. - #[test] - fn a_configured_turn_is_started_with_exactly_this_command() { - let mut backend = AgyBackend::new(PathBuf::from(".")).with_binary("/opt/agy"); - backend.set_models(&strings(&["sonnet", "gemini-3.1-pro-high"])); - backend.set_permission_mode("read-only"); - backend.set_extra_dirs(vec![PathBuf::from("a"), PathBuf::from("b")]); - backend.set_session_id("c-1"); - let cmd = backend.command("p"); - assert_eq!(cmd.get_program(), "/opt/agy"); - assert_eq!( - args_of(&cmd), - strings(&[ - "--print", - "p", - "--output-format", - "stream-json", - "--print-timeout", - "30m", - "--model", - "gemini-3.1-pro-high", - "--mode", - "plan", - "--add-dir", - "a", - "--add-dir", - "b", - "--conversation", - "c-1", - ]) - ); - - backend.set_permission_mode("danger-full-access"); - backend.clear_session(); - assert!( - !args_of(&backend.command("p")) - .iter() - .any(|a| a == "--mode" || a == "--conversation"), - "an unknown mode and a cleared session leave no flag" - ); - } - - /// A stand-in agy: prints `lines` on stdout, `stderr` on stderr, and - /// exits with `code`. - fn stand_in_agy(dir: &std::path::Path, lines: &[&str], stderr: &str, code: i32) -> PathBuf { - #[cfg(windows)] - { - let mut body = String::from("@echo off\r\n"); - for line in lines { - body.push_str(&format!("echo {line}\r\n")); - } - if !stderr.is_empty() { - body.push_str(&format!("echo {stderr} 1>&2\r\n")); - } - body.push_str(&format!("exit /b {code}\r\n")); - let path = dir.join("agy.cmd"); - std::fs::write(&path, body).expect("write the stand-in agy"); - path - } - #[cfg(not(windows))] - { - use std::os::unix::fs::PermissionsExt; - let mut body = String::from("#!/bin/sh\n"); - for line in lines { - body.push_str(&format!("echo '{line}'\n")); - } - if !stderr.is_empty() { - body.push_str(&format!("echo '{stderr}' >&2\n")); - } - body.push_str(&format!("exit {code}\n")); - let path = dir.join("agy.sh"); - std::fs::write(&path, body).expect("write the stand-in agy"); - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) - .expect("make it runnable"); - path - } - } - - /// One turn through `run_turn` on a stand-in, with its events. - fn turn_on( - lines: &[&str], - stderr: &str, - code: i32, - set_up: impl FnOnce(&mut AgyBackend), - ) -> (Result, Vec, AgyBackend) { - let dir = tempfile::tempdir().expect("scratch"); - let fake = stand_in_agy(dir.path(), lines, stderr, code); - let mut backend = - AgyBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); - set_up(&mut backend); - let mut seen = Vec::new(); - let result = backend - .run_turn("hi", &mut |e| seen.push(e.clone())) - .map_err(|e| e.to_string()); - (result, seen, backend) - } - - const INIT: &str = r#"{"event":"init","conversation_id":"conv-1","init":{"tools":["view_file","invoke_subagent"]}}"#; - - /// **A WHOLE TURN**: the session, each fragment live, the step's text - /// once, the last usage reported, a garbage line skipped, and the - /// conversation the result names kept for the next turn. - #[test] - fn a_whole_turn_reports_these_events_and_this_outcome() { - let (result, seen, backend) = turn_on( - &[ - INIT, - r#"{"event":"step_update","step_update":{"step_index":1,"step_type":"agent_response","text_delta":"PO"}}"#, - "not json", - r#"{"event":"step_update","step_update":{"step_index":1,"step_type":"agent_response","text_delta":"NG","usage":{"input_tokens":7,"output_tokens":3,"cache_read_tokens":2}}}"#, - r#"{"event":"step_update","step_update":{"step_index":2,"step_type":"tool_call","text_delta":"ignored"}}"#, - r#"{"event":"something_new"}"#, - r#"{"event":"result","result":{"conversation_id":"conv-2","status":"SUCCESS","usage":{"input_tokens":9,"output_tokens":4,"cache_read_tokens":5}}}"#, - ], - "", - 0, - |b| b.set_models(&strings(&["gemini-3.8-flash-high"])), - ); - assert_eq!( - seen, - vec![ - AgentEvent::SessionStarted { - session_id: "conv-1".to_string(), - model: "gemini-3.8-flash-high".to_string(), - }, - AgentEvent::TextDelta("PO".to_string()), - AgentEvent::TextDelta("NG".to_string()), - AgentEvent::Text("PONG".to_string()), - AgentEvent::Usage { - input_tokens: 9, - output_tokens: 4, - cache_creation_tokens: 0, - cache_read_tokens: 5, - }, - ] - ); - assert_eq!( - result.expect("a result line"), - TurnOutcome { - session_id: "conv-2".to_string(), - stop_reason: "SUCCESS".to_string(), - is_error: false, - detail: None, - served_by: strings(&["gemini-3.8-flash-high"]), - } - ); - assert_eq!(backend.session_id(), Some("conv-2")); - } - - /// A step's usage stands when the result carries none; an `ERROR` status - /// is a failed outcome carrying the agent's reason. - #[test] - fn an_error_result_is_an_outcome_with_the_agents_reason() { - let (result, seen, _) = turn_on( - &[ - INIT, - r#"{"event":"step_update","step_update":{"step_index":0,"step_type":"agent_response","text_delta":"","usage":{"input_tokens":2,"output_tokens":1,"cache_read_tokens":0}}}"#, - r#"{"event":"result","result":{"conversation_id":"conv-1","status":"ERROR","error":"model x is not recognized"}}"#, - ], - "", - 1, - |_| {}, - ); - assert_eq!( - seen, - vec![ - AgentEvent::SessionStarted { - session_id: "conv-1".to_string(), - model: String::new(), - }, - AgentEvent::Usage { - input_tokens: 2, - output_tokens: 1, - cache_creation_tokens: 0, - cache_read_tokens: 0, - }, - ] - ); - assert_eq!( - result.expect("a result line"), - TurnOutcome { - session_id: "conv-1".to_string(), - stop_reason: "ERROR".to_string(), - is_error: true, - detail: Some("model x is not recognized".to_string()), - served_by: Vec::new(), - } - ); - } - - /// No result line: the exact error, with and without stderr, after the - /// usage is still reported. - #[test] - fn a_turn_without_a_result_fails_with_this_error() { - let (result, seen, backend) = turn_on(&[INIT], "boom", 3, |_| {}); - assert_eq!( - result.expect_err("no result line"), - "the agent produced no result line (exit 3): boom" - ); - assert_eq!( - seen.last(), - Some(&AgentEvent::Usage { - input_tokens: 0, - output_tokens: 0, - cache_creation_tokens: 0, - cache_read_tokens: 0, - }) - ); - assert_eq!(backend.session_id(), Some("conv-1")); - - let (quiet, _, _) = turn_on(&[INIT], "", 0, |_| {}); - assert_eq!( - quiet.expect_err("no result line"), - "the agent produced no result line (exit 0)" - ); - } - - /// A stopped turn says so, before handling any output. - #[test] - fn a_cancelled_turn_stops_with_this_error() { - let (result, seen, _) = turn_on(&[INIT], "", 0, |b| { - let token = crate::runtime::cancel::CancelToken::new(); - token.cancel(); - b.set_cancel(token); - }); - assert_eq!(result.expect_err("cancelled"), "the turn was cancelled"); - assert!(seen.is_empty(), "{seen:?}"); - } - - /// A CLI that cannot be started names itself in the error. - #[test] - fn a_cli_that_cannot_start_is_named_in_the_error() { - let dir = tempfile::tempdir().expect("scratch"); - let missing = dir.path().join("no-such-agy-binary"); - let mut backend = - AgyBackend::new(dir.path().to_path_buf()).with_binary(missing.to_string_lossy()); - let err = backend - .run_turn("hi", &mut |_| {}) - .expect_err("nothing to start"); - assert!( - err.to_string() - .starts_with(&format!("could not start `{}`: ", missing.display())), - "{err}" - ); - } -} +#[path = "agy_tests.rs"] +mod tests; diff --git a/src/agent/agy_tests.rs b/src/agent/agy_tests.rs new file mode 100644 index 0000000..b91058b --- /dev/null +++ b/src/agent/agy_tests.rs @@ -0,0 +1,637 @@ +//! The agy backend: its wire envelope, its own model ladder, the enforcement +//! it does not have, the exact command a turn is started with, and whole +//! turns through `run_turn` on a stand-in CLI. + +use super::*; + +/// Issue #3: launched from inside another agent session, a child that +/// inherits its variables reports that session as its own. +#[test] +fn the_cli_never_joins_the_session_that_launched_incode() { + let cmd = AgyBackend::new(PathBuf::from(".")).command("p"); + assert!( + cmd.get_envs() + .any(|(k, v)| k == "CLAUDECODE" && v.is_none()), + "CLAUDECODE is inherited, so the child joins the parent's session" + ); +} + +/// **AN AGENT THAT CANNOT TAKE A PICTURE HEADLESS SAYS SO, BY NAME.** +/// `agy --help` (1.2.11) has no image flag, and its stream-json input +/// shape is not measured, so pictures are refused rather than dropped. +#[test] +fn pictures_are_refused_by_name() { + let picture = crate::toolbox::Image::from_base64( + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC", + ) + .expect("a 1x1 png"); + let mut backend = AgyBackend::new(PathBuf::from(".")); + let why = backend + .attach_images(vec![picture]) + .expect_err("agy takes no pictures"); + assert!(why.starts_with("agy cannot take pictures"), "{why}"); +} + +fn parse(line: &str) -> Wire { + serde_json::from_str(line).expect("a wire line") +} + +/// **A REPLY STREAMED IN FRAGMENTS IS SAID ONCE, WHOLE.** Lines shaped as +/// a real long reply (measured on agy, Insi's lesson writer): fragments of +/// one step, `ACTIVE` then `DONE`, each a few words and split inside words +/// and inside a JSON key. The step is one `Text`, the fragments joined byte +/// for byte, so its JSON parses; every fragment is still shown live as a +/// `TextDelta`; a later step is a `Text` of its own. +#[test] +fn a_reply_streamed_in_fragments_is_said_once_whole() { + let line = |index: u64, state: &str, kind: &str, text: &str| { + format!( + r#"{{"event":"step_update","step_update":{{"step_index":{index},"state":"{state}","step_type":"{kind}","text_delta":{}}}}}"#, + serde_json::to_string(text).expect("json") + ) + }; + let stream = [ + line(0, "DONE", "user_input", ""), + line(2, "ACTIVE", "agent_response", "{\n \"issue"), + line(2, "ACTIVE", "agent_response", "\": \"The agent added anim"), + line( + 2, + "ACTIVE", + "agent_response", + "ation math\",\n \"use\": \"Wire it", + ), + line(2, "DONE", "agent_response", " end to end.\"\n}"), + line(4, "DONE", "agent_response", "Done."), + ]; + let mut said = Vec::new(); + let mut deltas = 0; + { + let mut on_event = |event: &AgentEvent| match event { + AgentEvent::Text(text) => said.push(text.clone()), + AgentEvent::TextDelta(_) => deltas += 1, + _ => {} + }; + let mut reply = StepText::default(); + for wire in stream.iter().map(|l| parse(l)) { + if let Wire::StepUpdate { step_update } = wire { + reply.feed(&step_update, &mut on_event); + } + } + reply.finish(&mut on_event); + } + assert_eq!(said.len(), 2, "{said:?}"); + let answer: serde_json::Value = serde_json::from_str(&said[0]).expect("the whole reply parses"); + assert_eq!(answer["issue"], "The agent added animation math"); + assert_eq!(answer["use"], "Wire it end to end."); + assert_eq!(said[1], "Done."); + assert_eq!(deltas, 5, "every fragment shown as it came"); +} + +/// The envelope is keyed on `event`, not `type`. +/// +/// Copied from a real v1.1.23 run. If this ever parses as `Other` the CLI +/// changed its envelope, and every other test here would still pass while +/// the backend silently read nothing. +#[test] +fn the_init_line_from_a_real_run_is_understood() { + let wire = parse( + r#"{"event":"init","conversation_id":"1b343cea","init":{"cwd":"C:\\tmp","tools":["view_file","invoke_subagent"],"permission_mode":"request-review"}}"#, + ); + match wire { + Wire::Init(init) => { + assert_eq!(init.conversation_id, "1b343cea"); + assert!(init.init.tools.iter().any(|t| t == "invoke_subagent")); + } + other => panic!("the init envelope was not recognised: {other:?}"), + } +} + +/// Assistant text arrives on a step update, not a content block. +#[test] +fn the_agents_reply_is_read_from_a_step_update() { + let wire = parse( + r#"{"event":"step_update","step_update":{"step_index":1,"state":"DONE","step_type":"agent_response","text_delta":"PONG\n","usage":{"input_tokens":16317,"output_tokens":183,"cache_read_tokens":0}}}"#, + ); + match wire { + Wire::StepUpdate { step_update } => { + assert_eq!(step_update.step_type, "agent_response"); + assert_eq!(step_update.text_delta, "PONG\n"); + let u = to_usage(&step_update.usage.expect("usage")); + assert_eq!(u.input_tokens, 16317); + assert_eq!(u.output_tokens, 183); + } + other => panic!("a step update was not recognised: {other:?}"), + } +} + +/// **Every `status: ERROR` moves the work, whatever the wording.** +/// +/// The three the owner named — a lapsed subscription, a model the account +/// cannot reach, a model that is busy — arrive with three unrelated +/// messages and one identical status. Only the middle one is in the phrase +/// list; the first and third are asserted below to MISS it, which is what +/// makes reading the status the fix rather than a longer list. +#[test] +fn any_error_status_moves_the_work_however_it_is_worded() { + let backend = AgyBackend::new(std::path::PathBuf::from(".")); + let failed = |detail: &str| crate::agent::TurnOutcome { + session_id: "c1".to_string(), + stop_reason: "ERROR".to_string(), + is_error: true, + detail: Some(detail.to_string()), + served_by: Vec::new(), + }; + + // VERBATIM from the live run. + let busy = "Our servers are experiencing high traffic right now, please try again in a minute."; + let lapsed = "Your plan does not include this model."; + let missing = "model sonnet is not recognized"; + + assert!( + !crate::agent::moves_the_work(busy) && !crate::agent::moves_the_work(lapsed), + "the control holds only while the phrase list really does miss these" + ); + for detail in [busy, lapsed, missing] { + assert!( + backend.agent_failed(&failed(detail)), + "an ERROR status is the agent's own failure: {detail}" + ); + } + + // A turn the agent COMPLETED is never moved, however it reads — that is + // the harness's own check to judge, and walking a wrong task through + // every subscription spends them all to learn one thing. + let finished = crate::agent::TurnOutcome { + session_id: "c1".to_string(), + stop_reason: "SUCCESS".to_string(), + is_error: false, + detail: None, + served_by: Vec::new(), + }; + assert!(!backend.agent_failed(&finished)); +} + +/// A non-SUCCESS status is a failed turn, and says which status it was. +#[test] +fn a_failed_turn_is_reported_with_the_status_that_caused_it() { + let ok = parse(r#"{"event":"result","result":{"conversation_id":"c1","status":"SUCCESS"}}"#); + let bad = parse(r#"{"event":"result","result":{"conversation_id":"c1","status":"CANCELLED"}}"#); + let status_of = |w: Wire| match w { + Wire::Result { result } => ( + result.status.clone(), + !result.status.eq_ignore_ascii_case("SUCCESS"), + ), + other => panic!("a result line was not recognised: {other:?}"), + }; + assert_eq!(status_of(ok), ("SUCCESS".to_string(), false)); + assert_eq!(status_of(bad), ("CANCELLED".to_string(), true)); +} + +/// An unknown event is ignored, never fatal — the CLI may add events. +#[test] +fn an_unrecognised_event_does_not_break_the_turn() { + assert!(matches!( + parse(r#"{"event":"something_new_in_a_later_release"}"#), + Wire::Other + )); +} + +/// **This backend enforces nothing, and says so.** +/// +/// The measured reason: no per-tool deny flag exists on this CLI, and its +/// own init line advertises four sub-agent tools. Claiming enforcement it +/// does not have would be the exact failure the guard docs warn about. +#[test] +fn this_backend_claims_no_enforcement_it_does_not_have() { + let backend = AgyBackend::new(PathBuf::from(".")); + assert_eq!( + backend.enforces(), + crate::guards::Enforcement::NOTHING, + "claiming enforcement this CLI has no flag for would report a guard \ + that is not there" + ); +} + +/// The harness's policy becomes a REPORTED GAP here, not a silent drop. +#[test] +fn the_whole_policy_is_reported_as_unenforced_on_this_agent() { + let policy = crate::guards::restrictions(&crate::guards::Guards::default()); + let gaps = policy.unenforced_by(&AgyBackend::new(PathBuf::from(".")).enforces()); + assert_eq!(gaps.len(), 2, "both halves must be reported: {gaps:?}"); + assert!(gaps.iter().any(|g| g.contains("protected path"))); + assert!(gaps.iter().any(|g| g.contains("sub-agents"))); +} + +/// Only the first SERVEABLE candidate survives: no fallback chain here. +#[test] +fn a_fallback_chain_collapses_to_the_first_choice() { + let mut backend = AgyBackend::new(PathBuf::from(".")); + backend.set_models(&[ + "gemini-3.8-flash-high".to_string(), + "gemini-3.1-pro-high".to_string(), + ]); + assert_eq!(backend.model(), Some("gemini-3.8-flash-high")); +} + +/// **Another vendor's model id is NOT forwarded.** +/// +/// The live failure: the role ladder holds `sonnet`/`opus`, this agent +/// answered `status: ERROR, error: model sonnet is not recognized`, and +/// every task in the run died before any work began. Leaving the agent's +/// own default standing loses routing; forwarding the name loses the run. +#[test] +fn a_foreign_model_id_is_dropped_rather_than_sent() { + let mut backend = AgyBackend::new(PathBuf::from(".")); + backend.set_models(&["sonnet".to_string(), "opus".to_string()]); + assert_eq!( + backend.model(), + None, + "a model this agent cannot serve must not reach its command line" + ); + + // Control: a ladder it CAN serve is still honoured, so the assertion + // above is not passing because nothing is ever accepted. + backend.set_models(&["sonnet".to_string(), "gemini-3.1-pro-high".to_string()]); + assert_eq!(backend.model(), Some("gemini-3.1-pro-high")); +} + +/// **This agent routes on its OWN ladder, not the operator's foreign one.** +/// +/// Before this, a ladder of `sonnet, opus` left the agent un-routed and +/// every role ran on its default — the expensive one. The ids below come +/// from `agy models`, and a cheap role must not draw the strong model. +#[test] +fn each_role_draws_a_model_this_agent_actually_has() { + let backend = AgyBackend::new(PathBuf::from(".")); + for role in crate::roles::KNOWN_ROLES { + for id in backend.ladder_for(role) { + assert!( + backend.serves(&id), + "role {role} was given `{id}`, which this agent cannot serve" + ); + } + } + assert_ne!( + backend.ladder_for("explore"), + backend.ladder_for("implement"), + "reading and writing must not draw the same tier, or routing saves nothing" + ); + assert!( + backend.ladder_for("no-such-role").is_empty(), + "an unknown role gets the agent's default, never a guess" + ); +} + +/// A failed turn carries the agent's OWN reason, not a shrug. +#[test] +fn a_failure_reports_the_reason_the_agent_gave() { + let line = r#"{"event":"result","result":{"conversation_id":"c1","status":"ERROR","error":"model sonnet is not recognized"}}"#; + match parse(line) { + Wire::Result { result } => { + let detail = result.error.clone().filter(|e| !e.trim().is_empty()); + assert_eq!( + detail.as_deref(), + Some("model sonnet is not recognized"), + "the reason the agent gave was discarded" + ); + } + other => panic!("not a result: {other:?}"), + } +} + +/// **The harness's context reaches this agent even with no flag for it.** +/// +/// The pinned failure on the other backend was a run where every task was +/// worked by an agent told none of the guards, findings or roles. This CLI +/// has no `--append-system-prompt`, so the same loss would happen silently +/// unless the context is carried in the prompt instead. +#[test] +fn the_harness_context_is_carried_in_the_prompt_when_no_flag_exists() { + let bare = AgyBackend::new(PathBuf::from(".")); + assert_eq!( + bare.full_prompt("do the work").expect("sent"), + "do the work" + ); + + let briefed = AgyBackend::new(PathBuf::from(".")) + .with_system_context(vec!["the guards in force: tests/ is protected".to_string()]); + let sent = briefed.full_prompt("do the work").expect("sent"); + assert!( + sent.contains("tests/ is protected"), + "the harness context never reached the agent: {sent}" + ); + assert!( + sent.ends_with("do the work"), + "the task must come last, after its context: {sent}" + ); +} + +/// An unknown permission mode leaves the agent's default standing. +#[test] +fn an_unknown_permission_mode_is_not_passed_through() { + let mut backend = AgyBackend::new(PathBuf::from(".")); + backend.set_permission_mode("danger-full-access"); + assert!( + backend.mode.is_none(), + "passing a word this CLI rejects would fail the turn over a setting" + ); + backend.set_permission_mode("plan"); + assert_eq!(backend.mode.as_deref(), Some("plan")); +} + +// --------------------------------------------------------------------------- +// Pinned behaviour: the exact command a turn is started with, and what a +// whole turn through `run_turn` reports. +// --------------------------------------------------------------------------- + +fn args_of(cmd: &Command) -> Vec { + cmd.get_args() + .map(|a| a.to_string_lossy().into_owned()) + .collect() +} + +fn strings(items: &[&str]) -> Vec { + items.iter().map(|s| (*s).to_string()).collect() +} + +/// What the command SETS in the environment. Removals are the parent +/// session's variables, guarded by the test above. +fn set_envs(cmd: &Command) -> Vec<(String, String)> { + cmd.get_envs() + .filter_map(|(k, v)| { + Some(( + k.to_string_lossy().into_owned(), + v?.to_string_lossy().into_owned(), + )) + }) + .collect() +} + +/// **THE EXACT COMMAND FOR A DEFAULT TURN**: accept-edits, the long print +/// timeout, the workspace as the working directory. +#[test] +fn a_default_turn_is_started_with_exactly_this_command() { + let cmd = AgyBackend::new(PathBuf::from("ws")).command("p"); + assert_eq!(cmd.get_program(), "agy"); + assert_eq!( + args_of(&cmd), + strings(&[ + "--print", + "p", + "--output-format", + "stream-json", + "--print-timeout", + "30m", + "--mode", + "accept-edits", + ]) + ); + assert_eq!(cmd.get_current_dir(), Some(std::path::Path::new("ws"))); + assert!(set_envs(&cmd).is_empty(), "{:?}", set_envs(&cmd)); +} + +/// **THE EXACT COMMAND WITH EVERYTHING SET**: a model, plan mode, two +/// extra roots and a conversation to resume. +#[test] +fn a_configured_turn_is_started_with_exactly_this_command() { + let mut backend = AgyBackend::new(PathBuf::from(".")).with_binary("/opt/agy"); + backend.set_models(&strings(&["sonnet", "gemini-3.1-pro-high"])); + backend.set_permission_mode("read-only"); + backend.set_extra_dirs(vec![PathBuf::from("a"), PathBuf::from("b")]); + backend.set_session_id("c-1"); + let cmd = backend.command("p"); + assert_eq!(cmd.get_program(), "/opt/agy"); + assert_eq!( + args_of(&cmd), + strings(&[ + "--print", + "p", + "--output-format", + "stream-json", + "--print-timeout", + "30m", + "--model", + "gemini-3.1-pro-high", + "--mode", + "plan", + "--add-dir", + "a", + "--add-dir", + "b", + "--conversation", + "c-1", + ]) + ); + + backend.set_permission_mode("danger-full-access"); + backend.clear_session(); + assert!( + !args_of(&backend.command("p")) + .iter() + .any(|a| a == "--mode" || a == "--conversation"), + "an unknown mode and a cleared session leave no flag" + ); +} + +/// A stand-in agy: prints `lines` on stdout, `stderr` on stderr, and +/// exits with `code`. +fn stand_in_agy(dir: &std::path::Path, lines: &[&str], stderr: &str, code: i32) -> PathBuf { + #[cfg(windows)] + { + let mut body = String::from("@echo off\r\n"); + for line in lines { + body.push_str(&format!("echo {line}\r\n")); + } + if !stderr.is_empty() { + body.push_str(&format!("echo {stderr} 1>&2\r\n")); + } + body.push_str(&format!("exit /b {code}\r\n")); + let path = dir.join("agy.cmd"); + std::fs::write(&path, body).expect("write the stand-in agy"); + path + } + #[cfg(not(windows))] + { + use std::os::unix::fs::PermissionsExt; + let mut body = String::from("#!/bin/sh\n"); + for line in lines { + body.push_str(&format!("echo '{line}'\n")); + } + if !stderr.is_empty() { + body.push_str(&format!("echo '{stderr}' >&2\n")); + } + body.push_str(&format!("exit {code}\n")); + let path = dir.join("agy.sh"); + std::fs::write(&path, body).expect("write the stand-in agy"); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) + .expect("make it runnable"); + path + } +} + +/// One turn through `run_turn` on a stand-in, with its events. +fn turn_on( + lines: &[&str], + stderr: &str, + code: i32, + set_up: impl FnOnce(&mut AgyBackend), +) -> (Result, Vec, AgyBackend) { + let dir = tempfile::tempdir().expect("scratch"); + let fake = stand_in_agy(dir.path(), lines, stderr, code); + let mut backend = AgyBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); + set_up(&mut backend); + let mut seen = Vec::new(); + let result = backend + .run_turn("hi", &mut |e| seen.push(e.clone())) + .map_err(|e| e.to_string()); + (result, seen, backend) +} + +const INIT: &str = r#"{"event":"init","conversation_id":"conv-1","init":{"tools":["view_file","invoke_subagent"]}}"#; + +/// **A WHOLE TURN**: the session, each fragment live, the step's text +/// once, the last usage reported, a garbage line skipped, and the +/// conversation the result names kept for the next turn. +#[test] +fn a_whole_turn_reports_these_events_and_this_outcome() { + let (result, seen, backend) = turn_on( + &[ + INIT, + r#"{"event":"step_update","step_update":{"step_index":1,"step_type":"agent_response","text_delta":"PO"}}"#, + "not json", + r#"{"event":"step_update","step_update":{"step_index":1,"step_type":"agent_response","text_delta":"NG","usage":{"input_tokens":7,"output_tokens":3,"cache_read_tokens":2}}}"#, + r#"{"event":"step_update","step_update":{"step_index":2,"step_type":"tool_call","text_delta":"ignored"}}"#, + r#"{"event":"something_new"}"#, + r#"{"event":"result","result":{"conversation_id":"conv-2","status":"SUCCESS","usage":{"input_tokens":9,"output_tokens":4,"cache_read_tokens":5}}}"#, + ], + "", + 0, + |b| b.set_models(&strings(&["gemini-3.8-flash-high"])), + ); + assert_eq!( + seen, + vec![ + AgentEvent::SessionStarted { + session_id: "conv-1".to_string(), + model: "gemini-3.8-flash-high".to_string(), + }, + AgentEvent::TextDelta("PO".to_string()), + AgentEvent::TextDelta("NG".to_string()), + AgentEvent::Text("PONG".to_string()), + AgentEvent::Usage { + input_tokens: 9, + output_tokens: 4, + cache_creation_tokens: 0, + cache_read_tokens: 5, + }, + ] + ); + assert_eq!( + result.expect("a result line"), + TurnOutcome { + session_id: "conv-2".to_string(), + stop_reason: "SUCCESS".to_string(), + is_error: false, + detail: None, + served_by: strings(&["gemini-3.8-flash-high"]), + } + ); + assert_eq!(backend.session_id(), Some("conv-2")); +} + +/// A step's usage stands when the result carries none; an `ERROR` status +/// is a failed outcome carrying the agent's reason. +#[test] +fn an_error_result_is_an_outcome_with_the_agents_reason() { + let (result, seen, _) = turn_on( + &[ + INIT, + r#"{"event":"step_update","step_update":{"step_index":0,"step_type":"agent_response","text_delta":"","usage":{"input_tokens":2,"output_tokens":1,"cache_read_tokens":0}}}"#, + r#"{"event":"result","result":{"conversation_id":"conv-1","status":"ERROR","error":"model x is not recognized"}}"#, + ], + "", + 1, + |_| {}, + ); + assert_eq!( + seen, + vec![ + AgentEvent::SessionStarted { + session_id: "conv-1".to_string(), + model: String::new(), + }, + AgentEvent::Usage { + input_tokens: 2, + output_tokens: 1, + cache_creation_tokens: 0, + cache_read_tokens: 0, + }, + ] + ); + assert_eq!( + result.expect("a result line"), + TurnOutcome { + session_id: "conv-1".to_string(), + stop_reason: "ERROR".to_string(), + is_error: true, + detail: Some("model x is not recognized".to_string()), + served_by: Vec::new(), + } + ); +} + +/// No result line: the exact error, with and without stderr, after the +/// usage is still reported. +#[test] +fn a_turn_without_a_result_fails_with_this_error() { + let (result, seen, backend) = turn_on(&[INIT], "boom", 3, |_| {}); + assert_eq!( + result.expect_err("no result line"), + "the agent produced no result line (exit 3): boom" + ); + assert_eq!( + seen.last(), + Some(&AgentEvent::Usage { + input_tokens: 0, + output_tokens: 0, + cache_creation_tokens: 0, + cache_read_tokens: 0, + }) + ); + assert_eq!(backend.session_id(), Some("conv-1")); + + let (quiet, _, _) = turn_on(&[INIT], "", 0, |_| {}); + assert_eq!( + quiet.expect_err("no result line"), + "the agent produced no result line (exit 0)" + ); +} + +/// A stopped turn says so, before handling any output. +#[test] +fn a_cancelled_turn_stops_with_this_error() { + let (result, seen, _) = turn_on(&[INIT], "", 0, |b| { + let token = crate::runtime::cancel::CancelToken::new(); + token.cancel(); + b.set_cancel(token); + }); + assert_eq!(result.expect_err("cancelled"), "the turn was cancelled"); + assert!(seen.is_empty(), "{seen:?}"); +} + +/// A CLI that cannot be started names itself in the error. +#[test] +fn a_cli_that_cannot_start_is_named_in_the_error() { + let dir = tempfile::tempdir().expect("scratch"); + let missing = dir.path().join("no-such-agy-binary"); + let mut backend = + AgyBackend::new(dir.path().to_path_buf()).with_binary(missing.to_string_lossy()); + let err = backend + .run_turn("hi", &mut |_| {}) + .expect_err("nothing to start"); + assert!( + err.to_string() + .starts_with(&format!("could not start `{}`: ", missing.display())), + "{err}" + ); +} diff --git a/src/agent/claude_code.rs b/src/agent/claude_code.rs deleted file mode 100644 index eb19f28..0000000 --- a/src/agent/claude_code.rs +++ /dev/null @@ -1,3557 +0,0 @@ -//! Claude Code agent backend, driven as a subprocess. -//! -//! There is no Rust binding for the Claude Agent SDK (Python and TypeScript -//! only); the documented path for any other language is to run the CLI with -//! `-p` and a structured `--output-format`. The wire shapes below were taken -//! from real runs of CLI 2.1.229, not from documentation. - -#[cfg(test)] -use std::io::BufRead; -use std::io::BufReader; -use std::path::PathBuf; -use std::process::{Command, Stdio}; - -use serde::Deserialize; - -use super::{AgentBackend, AgentError, AgentEvent, TurnOutcome}; - -// --------------------------------------------------------------------------- -// Wire types -// --------------------------------------------------------------------------- - -/// One line of `--output-format stream-json`. -/// -/// Tagged on `type`, which every line carries — but field ORDER varies (the -/// final `result` line puts `type` near the end), so this must be a tagged -/// enum rather than anything positional. -#[derive(Debug, Deserialize)] -#[serde(tag = "type")] -enum CliEvent { - #[serde(rename = "system")] - System(SystemEvent), - #[serde(rename = "assistant")] - Assistant(AssistantMsg), - // No `user` variant: those lines carry the results of tool calls, which - // are incode's own and were shown by incode when it ran them. - #[serde(rename = "stream_event")] - StreamEvent(StreamEvent), - #[serde(rename = "rate_limit_event")] - RateLimit(RateLimitEvent), - #[serde(rename = "result")] - Result(Box), - #[serde(other)] - Other, -} - -/// A partial-message frame, present only with `--include-partial-messages`. -/// -/// Shape captured from a real run rather than assumed: -/// `{"type":"stream_event","event":{"type":"content_block_delta","index":0, -/// "delta":{"type":"text_delta","text":"h"}},"parent_tool_use_id":null}` -#[derive(Debug, Deserialize)] -struct StreamEvent { - event: StreamInner, - #[serde(default)] - parent_tool_use_id: Option, -} - -#[derive(Debug, Deserialize)] -struct StreamInner { - #[serde(rename = "type")] - event_type: String, - #[serde(default)] - delta: Option, -} - -#[derive(Debug, Deserialize)] -struct StreamDelta { - #[serde(rename = "type", default)] - delta_type: String, - #[serde(default)] - text: String, - /// A `thinking_delta`'s text. Measured on 2.1.283: EMPTY unless the run - /// asked for `--thinking-display summarized` (the default display, - /// `updates`, sends only `estimated_tokens`). - #[serde(default)] - thinking: String, -} - -#[derive(Debug, Deserialize)] -struct SystemEvent { - subtype: String, - #[serde(default)] - session_id: Option, - #[serde(default)] - model: Option, -} - -#[derive(Debug, Deserialize)] -struct AssistantMsg { - message: InnerMessage, - /// `None` for the main conversation; `Some(id)` for a subagent's output. - #[serde(default)] - parent_tool_use_id: Option, -} - -#[derive(Debug, Deserialize)] -struct InnerMessage { - #[serde(default)] - content: Vec, -} - -/// One block of a message on the wire. -/// -/// Only text is read. The CLI also reports the tool calls it forwarded and -/// their results, but every tool it has is incode's own, run by incode — which -/// shows each call and its result itself, from its own toolbox (see -/// [`crate::tool_bridge`]). Reading the CLI's copy as well would show every call -/// twice, and would take the CLI's word for what incode did. -#[derive(Debug, Deserialize)] -#[serde(tag = "type")] -enum WireContentBlock { - #[serde(rename = "text")] - Text { text: String }, - #[serde(other)] - Other, -} - -/// Subscription quota signal. Not on the published headless docs page, but -/// emitted on every run — this is the figure a subscription-backed host should -/// surface, since no per-token money is being spent. -#[derive(Debug, Deserialize)] -struct RateLimitEvent { - rate_limit_info: RateLimitInfo, -} - -#[derive(Debug, Deserialize)] -struct RateLimitInfo { - status: String, - #[serde(rename = "resetsAt", default)] - resets_at: i64, - #[serde(rename = "rateLimitType", default)] - rate_limit_type: String, - #[serde(rename = "isUsingOverage", default)] - is_using_overage: bool, -} - -#[derive(Debug, Deserialize)] -struct ResultEvent { - is_error: bool, - session_id: String, - #[serde(default)] - stop_reason: Option, - #[serde(default)] - usage: WireUsage, - /// Which models were actually BILLED for this turn, keyed by model id. - /// - /// The only trustworthy answer to "what ran?". The session's start event - /// reports the model that was *requested* — measured: asking for a model - /// that does not exist echoes that name back while the fallback quietly - /// answers. Attribution built on the request would credit work to a model - /// that never saw it. - #[serde(default, rename = "modelUsage")] - model_usage: std::collections::BTreeMap, - /// What the agent says about how the turn ended. - /// - /// On success this repeats the streamed reply and is dropped. On FAILURE it - /// is the only place the reason is written down — and it was not read at - /// all, so every failed turn reported the bare word `stop_sequence` and - /// nothing else. A whole day went into guessing a value the program was - /// receiving and discarding. - #[serde(default)] - result: Option, - /// The agent's own category for the ending, e.g. `success`, `error_*`. - #[serde(default)] - subtype: Option, -} - -#[derive(Debug, Default, Deserialize)] -struct WireUsage { - #[serde(default)] - input_tokens: u32, - #[serde(default)] - output_tokens: u32, - #[serde(default)] - cache_creation_input_tokens: u32, - #[serde(default)] - cache_read_input_tokens: u32, - /// Per request. Measured on a two-request turn: this held ONE entry, the - /// last request's, while the fields above were the sum of both. - #[serde(default)] - iterations: Vec, -} - -/// One request's tokens, as `usage.iterations` reports it. -#[derive(Debug, Default, Deserialize)] -struct WireIteration { - #[serde(default)] - input_tokens: u64, - #[serde(default)] - output_tokens: u64, - #[serde(default)] - cache_creation_input_tokens: u64, - #[serde(default)] - cache_read_input_tokens: u64, -} - -/// How full the context window was when the turn ended, when the result -/// reports both halves. -/// -/// `used` is the LAST request's tokens — input, both cache kinds and its -/// output, which is what the next request starts from. The turn's top-level -/// usage cannot stand in for it: it sums every request, counting the same -/// cached prefix once per request. -/// -/// `size` is the `contextWindow` the CLI put on the result. With more than one -/// model listed, it is the window of the model given the most input — the one -/// that held the conversation; a side model sees a fragment of it. -fn context_of( - usage: &WireUsage, - model_usage: &std::collections::BTreeMap, -) -> Option { - let last = usage.iterations.last()?; - let input_of = |entry: &serde_json::Value| -> u64 { - [ - "inputTokens", - "cacheReadInputTokens", - "cacheCreationInputTokens", - ] - .iter() - .filter_map(|key| entry.get(*key).and_then(serde_json::Value::as_u64)) - .sum() - }; - let size = model_usage - .values() - .filter_map(|entry| { - let window = entry.get("contextWindow")?.as_u64()?; - (window > 0).then_some((input_of(entry), window)) - }) - .max_by_key(|(input, _)| *input) - .map(|(_, window)| window)?; - Some(AgentEvent::Context { - used: last.input_tokens - + last.cache_read_input_tokens - + last.cache_creation_input_tokens - + last.output_tokens, - size, - }) -} - -// --------------------------------------------------------------------------- -// Backend -// --------------------------------------------------------------------------- - -/// Drives Claude Code over its non-interactive interface. -pub struct ClaudeCodeBackend { - binary: String, - workspace: PathBuf, - /// Set after the first turn; every later turn resumes it. - session_id: Option, - /// Which model serves the next turn, if the caller has an opinion. - /// - /// **This is what makes role routing work on a subscription.** Verified - /// against the installed CLI: `--model haiku` really is served by the haiku - /// model, confirmed by both the session's own `init.model` and the usage - /// recorded on the result. So cheap work can run cheap without an API key. - model: Option, - /// Models to try when the first is overloaded, in order. - /// - /// The CLI takes these as one comma-separated list, which is exactly the - /// ordered candidate chain the role table already produces. - fallbacks: Vec, - /// What the harness knows and the agent does not, carried on every turn. - /// - /// APPENDED to the agent's own system prompt rather than replacing it: the - /// agent's instructions are what make it good at the work, and this is the - /// project's context riding alongside them — the guard rules in force, what - /// the auditor already found, what the recorder already solved, which roles - /// exist. Replacing would trade a working coder for a briefed one. - system_context: Vec, - /// Directories beyond the workspace this agent may reach. - extra_dirs: Vec, - /// The policy the deny rules were built from. - /// - /// Held so that CHANGING THE ROOTS REBUILDS THE RULES automatically. A - /// separate "now re-derive them" call is a call someone forgets — and this - /// one was: reach was widened to a second root while the rules stayed - /// anchored to the first, and the agent wrote into a protected directory - /// there unstopped. - guards: crate::guards::Guards, - /// Every tool the model has, run HERE. - /// - /// The CLI is started with its own tools switched off and handed only - /// these, through [`crate::tool_bridge`]: each call the model makes comes - /// back to this process and runs through the toolbox's guards, the memory - /// engine's hook, the permission mode and the person to ask — the same - /// path a model over an API takes. - tools: crate::toolbox::Toolbox, - /// How many calls this backend has run, so each gets an id no earlier - /// turn used. - calls: u64, - /// Set when the user asks to stop. - /// - /// The agent runs as a CHILD PROCESS, so stopping it means killing that - /// process — there is no cooperative checkpoint to fall back on. Without - /// this, Ctrl-C during a turn would leave the agent running, still writing - /// files, with nothing reading its output. - cancel: Option, - /// Whether to ask for text as it is generated, not only in whole blocks. - /// - /// Off by default: a caller collecting a REPORT wants whole blocks, and - /// turning this on would make it choose between two copies of the same - /// text. An interactive caller turns it on and reads the deltas. - partial_messages: bool, - /// The protected paths, in the CLI's own deny syntax — REPORTED, no longer - /// handed to the CLI. - /// - /// The CLI has no file tools of its own any more, so a rule in its syntax - /// would bind nothing. The paths are refused by the toolbox instead, before - /// the write (see [`crate::toolbox::Toolbox`]); these stay as the readable - /// statement of what the session protects. - deny: Vec, - /// Pictures for the next turn's prompt only, already inside the image - /// bounds. A turn that carries any is given its prompt on stdin, as a - /// stream-json user message (see [`user_message`]). - images: Vec, - /// Whether a turn with partial messages still asks for - /// `--thinking-display summarized`. The flag is not in the CLI's - /// `--help`, so a release may drop it; the first turn that fails with - /// "unknown option" naming it turns this off for the rest of the - /// session, and that turn is run again without it. - thinking_display: bool, -} - -/// The flag that asks the CLI for a readable summary of the model's -/// thinking. Undocumented; see [`rejects_thinking_display`]. -const THINKING_DISPLAY_FLAG: &str = "--thinking-display"; - -/// Whether a failed start is the CLI refusing [`THINKING_DISPLAY_FLAG`]: -/// its option parser names the flag with "unknown option" (or a close -/// spelling) and exits before any output. -fn rejects_thinking_display(failure: &str) -> bool { - let said = failure.to_ascii_lowercase(); - said.contains("thinking-display") - && ["unknown option", "unknown argument", "unrecognized option"] - .iter() - .any(|phrase| said.contains(phrase)) -} - -/// What THIS agent calls its sub-agent tool. -/// -/// One backend's name for one capability. [`crate::guards::Restrictions`] says -/// only that sub-agents are refused; the word for it lives here, because the -/// next backend will have a different one — or none. -/// -/// Measured: a turn given this on `--disallowedTools` reports the tool ABSENT -/// rather than merely refused, so the child is never offered a capability it -/// cannot use. -const SUBAGENT_TOOL: &str = "Task"; - -/// The harness's restrictions, in this agent's own deny syntax. -/// -/// # `Edit`, never `Write` — measured, not assumed -/// -/// The tool name is `Edit`. A rule written as `Write(tests/**)` is **silently -/// ineffective**: it parses, it is accepted, and the write goes through. That -/// was measured — a probe denying only `Write(tests/**)` created the file -/// anyway, and this CLI reports that only `Edit(path)` rules are matched by -/// file permission checks, `Edit` covering every file-editing tool. -/// -/// A guard that looks right and does nothing is worse than no guard, so the -/// choice is pinned by a test rather than left to whoever edits next. -/// -/// Measured to cover shell redirection too: with `Edit(tests/**)` in force a -/// `printf > tests/x` was denied, and the identical command without it wrote -/// the file. -fn render_denials(restrictions: &crate::guards::Restrictions) -> Vec { - let mut rules = Vec::new(); - if restrictions.no_subagents { - rules.push(SUBAGENT_TOOL.to_string()); - } - rules.extend( - restrictions - .no_write - .iter() - .map(|glob| format!("Edit({glob})")), - ); - rules -} - -impl ClaudeCodeBackend { - #[must_use] - pub fn new(workspace: PathBuf) -> Self { - // The filtered environment for the shell tool: a command the model - // chose must not inherit this process's credentials. - let mut tools = crate::toolbox::Toolbox::new(&workspace, true); - // The `Agent` tool's sub-agent runs on this same CLI when no model - // endpoint is configured. - tools.run_subagents_on("claude"); - Self { - binary: "claude".to_string(), - tools, - calls: 0, - workspace, - session_id: None, - model: None, - fallbacks: Vec::new(), - partial_messages: false, - system_context: Vec::new(), - extra_dirs: Vec::new(), - guards: crate::guards::Guards::default(), - cancel: None, - deny: Vec::new(), - images: Vec::new(), - thinking_display: true, - } - } - - /// The same backend, one level further down the tree of agents: its - /// toolbox refuses a delegation past the depth limit. - #[must_use] - pub fn at_depth(mut self, depth: u8) -> Self { - self.tools = self.tools.at_depth(depth); - self - } - - /// Let the agent work in directories beyond the workspace. - /// - /// The caller must extend the SENTINEL to the same roots. This method only - /// widens what the agent can touch; widening reach without widening the - /// check is how a protected file stops being protected. - #[must_use] - pub fn with_extra_dirs(mut self, dirs: Vec) -> Self { - self.set_extra_dirs(dirs); - self - } - - /// The same, for a caller that already owns the backend in place. - pub fn set_extra_dirs(&mut self, dirs: Vec) { - // incode's toolbox does the writing on this route, so it is the toolbox - // that must be able to reach the added roots — under the same guards. - self.tools.set_extra_dirs(dirs.clone()); - self.extra_dirs = dirs; - // Reach and guard move together, by construction rather than by anyone - // remembering to call something afterwards. - self.rebuild_deny(); - } - - /// Give the backend the flag that says the user asked to stop. - /// - /// Checked between output lines, so it lands while the agent is talking. - /// A turn that has gone quiet — a long tool call with no output — is not - /// interrupted until it next says something; that limit is real and stated - /// rather than implied. - #[must_use] - pub fn with_cancel(mut self, token: crate::runtime::cancel::CancelToken) -> Self { - self.cancel = Some(token); - self - } - - /// Give the agent the project context this harness assembled. - /// - /// Rides EVERY turn, not just the first: the agent may compact its own - /// conversation, and context that only arrived once would quietly stop - /// applying part-way through a session. - #[must_use] - pub fn with_system_context(mut self, blocks: Vec) -> Self { - self.system_context = blocks - .into_iter() - .filter(|b| !b.trim().is_empty()) - .collect(); - self - } - - /// What the agent is told about this project, beyond the instruction. - #[must_use] - pub fn system_context(&self) -> &[String] { - &self.system_context - } - - /// Ask for text as it is generated, for an interactive caller. - /// - /// The caller then reads [`AgentEvent::TextDelta`] and must IGNORE - /// [`AgentEvent::Text`], which still arrives with the same words in it. - #[must_use] - pub fn streaming(mut self, on: bool) -> Self { - self.partial_messages = on; - self - } - - /// Refuse the agent write access to the operator's protected paths. - /// - /// **Prevention, not detection.** The agent enforces these itself, so the - /// write never happens — where [`crate::guards::Sentinel`] can only notice - /// afterwards. Both are used: they cover different routes and neither is - /// asked to be complete on its own. - #[must_use] - pub fn with_guards(mut self, guards: &crate::guards::Guards) -> Self { - self.guards = guards.clone(); - self.rebuild_deny(); - self - } - - /// Re-derive the deny rules from the policy and the current roots. - /// - /// Called by everything that changes either. A bare glob is matched - /// relative to the working directory, so a root added later needs its own - /// absolute rules. - fn rebuild_deny(&mut self) { - let restrictions = crate::guards::restrictions_for(&self.guards, &self.extra_dirs); - self.deny = render_denials(&restrictions); - } - - /// The deny rules this backend will pass to the agent. - #[must_use] - pub fn deny_rules(&self) -> &[String] { - &self.deny - } - - /// Offer the model the desktop tools, run through incode's toolbox and - /// executed by the desktop child it starts — see `toolbox::desktop`. - /// Off unless a caller asks: handing every run a desktop it did not - /// request would widen what an agent can reach as a side effect of a - /// constructor. - #[must_use] - pub fn with_desktop(mut self, setup: crate::toolbox::DesktopSetup) -> Self { - self.tools.enable_desktop(setup); - self - } - - /// Run the operator's own pre- and post-tool commands around every call - /// this model makes — see [`crate::hooks`]. - #[must_use] - pub fn with_operator_hooks(mut self, hooks: Option) -> Self { - self.tools = self.tools.with_operator_hooks(hooks); - self - } - - /// Confine this model's shell commands to `mode` — see [`crate::sandbox`]. - #[must_use] - pub fn with_sandbox(mut self, policy: crate::sandbox::SandboxPolicy) -> Self { - self.tools = self.tools.with_sandbox(policy); - self - } - - /// Offer the model only `tools`, when given — a user-defined sub-agent's - /// allow-list. A call to any other tool is refused by the toolbox. - #[must_use] - pub fn with_tool_allowlist(mut self, tools: Option>) -> Self { - if let Some(tools) = tools { - self.tools.restrict_tools(tools); - } - self - } - - /// Override the binary (e.g. an absolute path from agent discovery). - #[must_use] - pub fn with_binary(mut self, binary: impl Into) -> Self { - self.binary = binary.into(); - self.tools.run_subagents_on(&self.binary); - self - } - - /// Continue a specific pre-existing session. - #[must_use] - pub fn with_session(mut self, session_id: impl Into) -> Self { - self.session_id = Some(session_id.into()); - self - } - - /// Serve the next turn with a named model, falling back through the rest. - /// - /// **Changing the model abandons the session.** A resumed session carries - /// the earlier turns, and asking a different model to continue them is a - /// request the harness cannot reason about — it would be paying to resume a - /// conversation the new model did not have. Starting fresh costs the prompt - /// prefix once and is the only behaviour that means what it says. - #[must_use] - pub fn with_models(mut self, candidates: &[String]) -> Self { - // One implementation of the rule, not two. A second copy of "changing - // model abandons the session" is a copy that can drift, and a drifted - // safety rule is worse than an absent one. - AgentBackend::set_models(&mut self, candidates); - self - } - - /// Forget the session, so the next turn starts a new one. - pub fn clear_session(&mut self) { - self.session_id = None; - } - - /// How much the model's tool calls may do without asking, as the session - /// spells it (`plan`, `default`, `acceptEdits`). - /// - /// Decided by incode's toolbox, never handed to the CLI: the CLI runs no - /// tools, so a mode given to it would govern nothing. A spelling nobody - /// recognises lands on read-only, like - /// [`crate::permissions::PermissionMode::from_str_lossy`]. - pub fn set_permission_mode(&mut self, mode: &str) { - self.tools - .set_permission_mode(crate::permissions::PermissionMode::from_agent_mode(mode)); - } - - /// Ask the memory engine before every tool call this model makes. - #[must_use] - pub fn with_engine(mut self, engine: Option) -> Self { - self.tools = self.tools.with_engine(engine); - self - } - - /// Announce each file write this model makes to the engine's edit check, - /// and record each read — see `toolbox::code_edits`. - #[must_use] - pub fn with_code_edits(mut self, edits: Option) -> Self { - self.tools = self.tools.with_code_edits(edits); - self - } - - /// Continue an existing agent session on the next turn. - pub fn set_session_id(&mut self, session_id: &str) { - self.session_id = Some(session_id.to_string()); - } - - /// The model the next turn will ask for, if one was chosen. - #[must_use] - pub fn model(&self) -> Option<&str> { - self.model.as_deref() - } - - /// The CLI's command for one turn, as a model and nothing else, with - /// `servers` as its only MCP servers and `allowed` the tool names it may - /// send without asking. The bridge's address and token are added by the - /// caller, which holds the bridge. - /// - /// `prompt` is `None` for a turn carrying pictures, whose prompt goes on - /// stdin instead, as one stream-json user message ([`user_message`]): `-p` - /// with no prompt and `--input-format stream-json`. Measured on 2.1.283: a - /// message with a base64 PNG block was described correctly, and the CLI - /// ended when stdin closed. - fn command( - &self, - prompt: Option<&str>, - context: &str, - servers: &str, - allowed: &[String], - ) -> Command { - let mut cmd = Command::new(&self.binary); - crate::agent::parent_session::detach_from_parent_session(&mut cmd); - cmd.arg("-p"); - match prompt { - Some(prompt) => { - cmd.arg(prompt); - } - None => { - cmd.arg("--input-format").arg("stream-json"); - } - } - cmd.arg("--output-format") - .arg("stream-json") - .args(MODEL_ONLY_FLAGS) - .arg("--mcp-config") - .arg(servers) - .arg("--allowedTools") - .args(allowed); - for (key, value) in MODEL_ONLY_ENV { - cmd.env(key, value); - } - - // Which model serves this turn. Absent, the CLI uses its own default, - // which is the right behaviour for a caller with no opinion. - if let Some(model) = &self.model { - cmd.arg("--model").arg(model); - } - if self.partial_messages { - cmd.arg("--include-partial-messages"); - // The model's reasoning as text a person can read, streamed as - // `thinking_delta`s. Not in `--help` on 2.1.283 (it is in the - // CLI's option table, choices summarized / omitted / highlights); - // measured: without it every thinking delta arrived EMPTY, with it - // the summary arrived word by word, beside an unchanged reply. - // Left off once this CLI has refused it (`thinking_display`). - if self.thinking_display { - cmd.arg(THINKING_DISPLAY_FLAG).arg("summarized"); - } - } - if !context.is_empty() { - cmd.arg("--append-system-prompt").arg(context); - } - if !self.fallbacks.is_empty() { - // One comma-separated list, tried in order — the CLI's own shape for - // the ordered chain the role table produces. - cmd.arg("--fallback-model").arg(self.fallbacks.join(",")); - } - - // Continue the existing session rather than starting a new one. A fresh - // session re-pays the entire prompt prefix; resuming does not. - if let Some(sid) = &self.session_id { - cmd.arg("--resume").arg(sid); - } - - // Point the agent at a profile whose session is actually live. - // - // Skipped entirely when the operator has already said which profile to - // use: an explicit choice is a decision, and silently overriding it - // would be worse than the fallback this replaces. - if std::env::var_os(PROFILE_ENV).is_none() { - if let Some(profile) = usable_profile() { - cmd.env(PROFILE_ENV, &profile.dir); - } - } - - // No team server identity here: on this route the team channel's - // tools are incode's own (`toolbox::team`), and who they speak as is - // set on the toolbox by `set_team_identity`. - cmd - } - - /// Whether this agent recognises a model id as one it can serve. - /// - /// Recognises Claude families and generic names, and rejects known foreign - /// vendor namespaces (`gemini-`, `gpt-`, `o1/3/4`, `codex-`) so a cross-vendor - /// candidate chain from a shared tier never sends a foreign model to the CLI. - pub fn serves(&self, model: &str) -> bool { - const FOREIGN_PREFIXES: [&str; 7] = - ["gemini-", "gpt-", "o1", "o3", "o4", "chatgpt-", "codex-"]; - let id = model.trim().to_ascii_lowercase(); - if id.is_empty() { - return false; - } - !FOREIGN_PREFIXES.iter().any(|f| id.starts_with(f)) - } -} - -/// One stream-json user message: the prompt as a text block, then each -/// picture as a base64 image block — the shape the CLI reads on stdin with -/// `--input-format stream-json`, one message per line. -fn user_message(prompt: &str, images: &[crate::toolbox::Image]) -> String { - let mut content = vec![serde_json::json!({"type": "text", "text": prompt})]; - content.extend(images.iter().map(crate::agent::api::image_block)); - let message = serde_json::json!({ - "type": "user", - "message": {"role": "user", "content": content}, - }); - format!("{message}\n") -} - -/// Map one wire line to zero or more harness events. -/// -/// Split out from the process plumbing so it can be tested against captured -/// output without spawning anything. -fn map_line(line: &str, outcome: &mut Option) -> Vec { - let mut events = Vec::new(); - - // A line we cannot model is data we don't understand yet, never a reason to - // abort the turn — the CLI adds event types over time. - let Ok(evt) = serde_json::from_str::(line) else { - return events; - }; - - match evt { - CliEvent::System(s) if s.subtype == "init" => { - events.push(AgentEvent::SessionStarted { - session_id: s.session_id.unwrap_or_default(), - model: s.model.unwrap_or_else(|| "unknown".to_string()), - }); - } - CliEvent::System(_) => {} - CliEvent::StreamEvent(e) => { - // Subagent output is not the main conversation's text — the same - // rule the whole-block branch below applies. - if e.parent_tool_use_id.is_some() { - return events; - } - if e.event.event_type == "content_block_delta" { - if let Some(delta) = e.event.delta { - if delta.delta_type == "text_delta" && !delta.text.is_empty() { - events.push(AgentEvent::TextDelta(delta.text)); - } else if delta.delta_type == "thinking_delta" && !delta.thinking.is_empty() { - events.push(AgentEvent::Thinking(delta.thinking)); - } - } - } - } - CliEvent::Assistant(a) => { - // Subagent output is not the main conversation's text. - if a.parent_tool_use_id.is_some() { - return events; - } - for block in a.message.content { - if let WireContentBlock::Text { text } = block { - events.push(AgentEvent::Text(text)); - } - } - } - CliEvent::RateLimit(r) => events.push(AgentEvent::Quota { - status: r.rate_limit_info.status, - kind: r.rate_limit_info.rate_limit_type, - resets_at: r.rate_limit_info.resets_at, - using_overage: r.rate_limit_info.is_using_overage, - }), - CliEvent::Result(r) => { - events.push(AgentEvent::Usage { - input_tokens: r.usage.input_tokens, - output_tokens: r.usage.output_tokens, - cache_creation_tokens: r.usage.cache_creation_input_tokens, - cache_read_tokens: r.usage.cache_read_input_tokens, - }); - if let Some(context) = context_of(&r.usage, &r.model_usage) { - events.push(context); - } - // NOTE: the result line also carries a `result` field holding the - // final assembled text. It repeats what the assistant content - // blocks already delivered, so emitting both duplicates every - // reply. The incremental stream is the single source of truth. - // Only when the turn FAILED. On success `result` is a copy of the - // reply that already streamed, and carrying it would duplicate - // every answer. - let detail = if r.is_error { - let said = r.result.unwrap_or_default(); - let kind = r.subtype.unwrap_or_default(); - let joined = match (kind.trim(), said.trim()) { - ("", "") => String::new(), - (k, "") => k.to_string(), - ("", t) => t.to_string(), - (k, t) => format!("{k}: {t}"), - }; - (!joined.is_empty()).then_some(joined) - } else { - None - }; - *outcome = Some(TurnOutcome { - session_id: r.session_id, - stop_reason: r.stop_reason.unwrap_or_else(|| "unknown".to_string()), - is_error: r.is_error, - detail, - // The keys are model ids; the values are per-model token counts - // this harness has no use for. Sorted by the map, so the record - // is the same on every run for the same turn. - served_by: r.model_usage.into_keys().collect(), - }); - } - CliEvent::Other => {} - } - - events -} - -/// Consume an agent's event stream to completion. -/// -/// Split from the spawn plumbing so the loop that actually matters — event -/// mapping, session capture for `--resume`, and outcome extraction — is -/// testable over canned bytes without launching a process. -/// -/// `session` is updated in place as soon as the session id appears, so a turn -/// that fails partway still leaves the backend able to resume. -/// The environment variable naming which agent profile to use. -const PROFILE_ENV: &str = "CLAUDE_CONFIG_DIR"; -/// Profile directories are the home entries beginning with this. -const PROFILE_PREFIX: &str = ".claude"; -/// Where a profile records its session. -const CREDENTIALS_FILE: &str = ".credentials.json"; -/// A session with less than this left is treated as already gone, so a turn is -/// not started on a login that will expire while it runs. -const SESSION_MARGIN_SECS: i64 = 120; - -/// One agent profile and how much longer its session is good for. -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct Profile { - /// The directory to point the agent at. - pub dir: std::path::PathBuf, - /// Seconds of session left; negative means it expired that long ago. - pub seconds_left: i64, -} - -/// Every agent profile in the home directory, whether or not its session is live. -/// -/// # Why this exists -/// -/// The agent falls back to its default profile when nothing says otherwise, and -/// that profile is not necessarily the one the operator logged in with. On this -/// machine the default held a session that had expired while a second profile -/// was live, so every turn failed with an authentication error that named -/// neither profile. Choosing the profile that can actually work removes a whole -/// class of failure that looks exactly like a broken harness. -/// -/// # Credentials are never read -/// -/// Only the expiry timestamp is taken from the file. The tokens beside it are -/// not read, not copied and not logged — the harness has no use for them and -/// every reason not to touch them. -#[must_use] -pub fn profiles() -> Vec { - home_dir() - .map(|home| profiles_in(&home)) - .unwrap_or_default() -} - -/// The profiles under a given home directory. -/// -/// Split from [`profiles`] so the selection can be tested against a directory -/// built for the purpose, rather than against whatever the machine happens to -/// hold. -#[must_use] -pub fn profiles_in(home: &std::path::Path) -> Vec { - let Ok(entries) = std::fs::read_dir(home) else { - return Vec::new(); - }; - let mut found: Vec = entries - .filter_map(Result::ok) - .map(|e| e.path()) - // A directory only: the home also holds `.claude.json` and a long tail - // of its backups, none of which are profiles. - .filter(|p| p.is_dir()) - .filter(|p| { - p.file_name() - .and_then(|n| n.to_str()) - .is_some_and(|n| n.starts_with(PROFILE_PREFIX)) - }) - .filter_map(|dir| { - session_seconds_left(&dir).map(|seconds_left| Profile { dir, seconds_left }) - }) - .collect(); - // Longest-lived first, then by path so the order is the same on every run. - found.sort_by(|a, b| { - b.seconds_left - .cmp(&a.seconds_left) - .then_with(|| a.dir.cmp(&b.dir)) - }); - found -} - -/// The profile whose session is live and lasts longest, if any is — and none -/// when the agent already has a login that no profile file records. -/// -/// # Why a login elsewhere wins over a live file -/// -/// Pointing the CLI at a profile directory is the only lever this has, and it -/// moves the login along with everything else. On macOS the default profile's -/// login lives in the Keychain under a service name that changes once -/// [`PROFILE_ENV`] names another directory, so redirecting to a leftover -/// `.credentials.json` swapped a working login for a stale one. With a -/// credential in the environment the redirect buys nothing — the CLI -/// authenticates from the variable whichever directory it reads — and costs -/// the operator's own settings for that directory. -#[must_use] -pub fn usable_profile() -> Option { - choose_profile(profiles(), &|| { - login_outside_profiles(&process_env, &keychain_holds_login) - }) -} - -/// [`pick_usable`], unless `outside` names a login the CLI would use anyway. -/// -/// `outside` is asked only once a file profile would otherwise be chosen: the -/// Keychain answer costs a process, and with no live file there is nothing it -/// could change. -fn choose_profile( - found: Vec, - outside: &dyn Fn() -> Option, -) -> Option { - let live = pick_usable(found)?; - if let Some(login) = outside() { - crate::trace!( - "agent", - "{} not chosen: the agent already logs in via {login:?}", - live.dir.display() - ); - return None; - } - Some(live) -} - -/// A login the agent CLI uses that is not a profile's credentials file. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum OutsideLogin { - /// This variable is set. Only its NAME is carried: the value is a secret - /// and nothing here has a use for it. - Environment(&'static str), - /// The macOS Keychain holds the default profile's login. - Keychain, -} - -/// Variables that carry a credential: set to anything, the CLI authenticates -/// with them. Names measured in the 2.1.303 binary. -/// -/// `ANTHROPIC_BASE_URL` is deliberately absent. It moves where requests go, -/// not what authenticates them — the CLI still sends a key, a token or its -/// login — so a base URL with no credential is exactly the state in which -/// every turn fails, and counting it would hide that. A host that manages the -/// provider says so with a provider switch below. -const CREDENTIAL_ENV: [&str; 4] = [ - "ANTHROPIC_API_KEY", - "CLAUDE_CODE_OAUTH_TOKEN", - "CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR", - "ANTHROPIC_AUTH_TOKEN", -]; - -/// Switches to a provider whose own credentials then authenticate the CLI. -/// -/// Read as switches, the way the CLI reads them (measured in 2.1.303: `1`, -/// `true`, `yes` or `on`, any case) — so `CLAUDE_CODE_USE_BEDROCK=0` is a -/// switch that is off, not a login. -const PROVIDER_ENV: [&str; 7] = [ - "CLAUDE_CODE_USE_BEDROCK", - "CLAUDE_CODE_USE_VERTEX", - "CLAUDE_CODE_USE_FOUNDRY", - "CLAUDE_CODE_USE_ANTHROPIC_AWS", - "CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD", - "CLAUDE_CODE_USE_MANTLE", - "CLAUDE_CODE_USE_GATEWAY", -]; - -/// The Keychain service the CLI keeps the DEFAULT profile's login under. -/// -/// Measured in 2.1.303: `"Claude Code" + "-credentials"`, with a hash of the -/// directory appended when [`PROFILE_ENV`] names another one — which is why -/// the Keychain is only consulted while that variable is unset. -const KEYCHAIN_SERVICE: &str = "Claude Code-credentials"; - -/// How long the Keychain lookup may take. A local lookup answers in -/// milliseconds; a locked or hung keychain must not hold up a turn or a -/// diagnosis. -const KEYCHAIN_WAIT: std::time::Duration = std::time::Duration::from_secs(3); - -/// The login the CLI will use that no profile file records, if there is one. -/// -/// `env` and `keychain` are parameters so the decision can be tested without -/// touching the process environment, which every test thread shares. The -/// environment is read first because it is free; the Keychain costs a process. -#[must_use] -pub fn login_outside_profiles( - env: &dyn Fn(&str) -> Option, - keychain: &dyn Fn() -> bool, -) -> Option { - let set = |name: &str| env(name).is_some_and(|v| !v.is_empty()); - let switched_on = |name: &str| { - env(name).is_some_and(|v| { - matches!( - v.trim().to_ascii_lowercase().as_str(), - "1" | "true" | "yes" | "on" - ) - }) - }; - if let Some(name) = CREDENTIAL_ENV.into_iter().find(|name| set(name)) { - return Some(OutsideLogin::Environment(name)); - } - if let Some(name) = PROVIDER_ENV.into_iter().find(|name| switched_on(name)) { - return Some(OutsideLogin::Environment(name)); - } - (env(PROFILE_ENV).is_none() && keychain()).then_some(OutsideLogin::Keychain) -} - -/// One variable from this process's environment, as [`login_outside_profiles`] -/// reads it. -#[must_use] -pub fn process_env(name: &str) -> Option { - std::env::var_os(name).map(|v| v.to_string_lossy().into_owned()) -} - -/// Whether the macOS Keychain holds the default profile's login. -/// -/// Asks for the item's EXISTENCE only: no `-w`, so the secret is never -/// printed, and an attribute lookup does not raise the access prompt a read -/// of the secret would. Output is discarded; the exit code is the answer. -/// Elsewhere there is no Keychain, and the answer is no without a process. -#[must_use] -pub fn keychain_holds_login() -> bool { - if !cfg!(target_os = "macos") { - return false; - } - let mut cmd = Command::new("security"); - cmd.args(["find-generic-password", "-s", KEYCHAIN_SERVICE]) - .stdin(Stdio::null()) - .stdout(Stdio::null()) - .stderr(Stdio::null()); - crate::agent::process_tree::prepare(&mut cmd); - let Ok(child) = cmd.spawn() else { - return false; - }; - crate::tools::bash::wait_with_timeout(child, KEYCHAIN_WAIT) - .is_ok_and(|out| out.status.success()) -} - -/// The first profile with enough session left to be worth starting a turn on. -#[must_use] -pub fn pick_usable(found: Vec) -> Option { - found - .into_iter() - .find(|p| p.seconds_left > SESSION_MARGIN_SECS) -} - -/// How long this profile's session has left, or `None` if it records none. -fn session_seconds_left(dir: &std::path::Path) -> Option { - let text = std::fs::read_to_string(dir.join(CREDENTIALS_FILE)).ok()?; - let parsed: serde_json::Value = serde_json::from_str(&text).ok()?; - let expires_at_ms = find_expiry(&parsed)?; - let now_ms = i64::try_from( - std::time::SystemTime::now() - .duration_since(std::time::UNIX_EPOCH) - .ok()? - .as_millis(), - ) - .ok()?; - Some((expires_at_ms - now_ms) / 1_000) -} - -/// The session expiry anywhere in the document, in milliseconds. -/// -/// Searched rather than addressed by path: the key sits one level down today, -/// and a layout change should cost the selection, never break the harness. -fn find_expiry(value: &serde_json::Value) -> Option { - match value { - serde_json::Value::Object(map) => { - if let Some(found) = map.get("expiresAt").and_then(serde_json::Value::as_i64) { - return Some(found); - } - map.values().find_map(find_expiry) - } - _ => None, - } -} - -/// The operator's home directory. -fn home_dir() -> Option { - std::env::var_os("HOME") - .or_else(|| std::env::var_os("USERPROFILE")) - .map(std::path::PathBuf::from) -} - -/// Where to write the agent's raw output, if the operator asked for it. -/// -/// `INCODE_DEBUG_STREAM=` appends every line the agent sends. It is the -/// only way to answer "why did this turn fail" without guessing. -#[must_use] -pub fn debug_stream_path() -> Option { - std::env::var("INCODE_DEBUG_STREAM") - .ok() - .filter(|p| !p.is_empty()) -} - -use crate::tool_bridge::Incoming; -/// What a cancelled turn reports, so the caller can tell it apart from a crash. -/// One wording for every bridged CLI — see [`crate::tool_bridge::CANCELLED`]. -pub use crate::tool_bridge::CANCELLED; - -/// The turn itself: the CLI's output mapped to events, and every tool call -/// the model makes run by `tools`, until the CLI finishes or the turn is -/// stopped. The loop is the bridge's ([`crate::tool_bridge::drive`]); what a -/// line of THIS CLI means is decided here. -fn consume( - from: &std::sync::mpsc::Receiver, - session: &mut Option, - on_event: &mut dyn FnMut(&AgentEvent), - cancel: Option<&crate::runtime::cancel::CancelToken>, - tools: &mut crate::toolbox::Toolbox, - calls: &mut u64, -) -> Result, AgentError> { - let mut outcome = None; - crate::tool_bridge::drive(from, cancel, tools, calls, on_event, &mut |line, tools| { - // Every raw line, when asked for. A turn that fails for a reason the - // harness cannot explain — "stopped without finishing: stop_sequence" — - // is unanswerable without the bytes the agent actually sent, and - // guessing at them from a screenshot is how an afternoon disappears. - if let Some(path) = debug_stream_path() { - if let Ok(mut file) = std::fs::OpenOptions::new() - .create(true) - .append(true) - .open(path) - { - use std::io::Write as _; - let _ = writeln!(file, "{line}"); - } - } - if line.trim().is_empty() { - return Vec::new(); - } - let events = map_line(&line, &mut outcome); - for event in &events { - if let AgentEvent::SessionStarted { session_id, .. } = event { - if !session_id.is_empty() { - *session = Some(session_id.clone()); - // The engine files its cards and backups under the - // conversation, so it is told this one. - tools.set_session(session_id); - } - } - } - events - })?; - Ok(outcome) -} - -/// [`consume`] over a finished stream of bytes, for the tests that replay -/// captured output. -#[cfg(test)] -fn consume_stream( - reader: R, - session: &mut Option, - on_event: &mut dyn FnMut(&AgentEvent), - cancel: Option<&crate::runtime::cancel::CancelToken>, -) -> Result, AgentError> { - let (to, from) = std::sync::mpsc::channel(); - for line in reader.lines() { - let message = match line { - Ok(line) => Incoming::Line(line), - Err(e) => Incoming::ReadFailed(e.to_string()), - }; - let _ = to.send(message); - } - let _ = to.send(Incoming::Ended); - let mut tools = crate::toolbox::Toolbox::new(std::path::Path::new("."), true); - consume(&from, session, on_event, cancel, &mut tools, &mut 0) -} - -/// The flags that make the CLI a model and nothing else. Each was proved on -/// the installed CLI before it was relied on — see `docs/ARCHITECTURE.md`, -/// "Models only: incode runs every tool". -/// -/// - `--tools ""`: none of its built-in tools. Its session then lists only the -/// MCP tools incode hands it. -/// - `--strict-mcp-config`: only the servers in `--mcp-config`, so nothing the -/// operator configured for the CLI is reachable. -/// - `--setting-sources ""`: no user, project or local settings — and with -/// them none of their hooks, permission rules or default mode. Measured: -/// thirteen hook events on a control run, none with this flag. -/// - `--disable-slash-commands`: no skills of its own. -/// -/// `--bare` would do most of this in one flag, and cannot be used: it reads -/// only an API key, and a subscription login answers "Not logged in". -const MODEL_ONLY_FLAGS: [&str; 7] = [ - "--tools", - "", - "--strict-mcp-config", - "--setting-sources", - "", - "--disable-slash-commands", - "--verbose", -]; - -/// Environment that keeps the CLI's own memory out: no `CLAUDE.md` files and -/// no auto-memory. Measured: a project canary in `CLAUDE.md` was repeated by a -/// control run and unknown to a run with these set. -const MODEL_ONLY_ENV: [(&str, &str); 2] = [ - ("CLAUDE_CODE_DISABLE_CLAUDE_MDS", "1"), - ("CLAUDE_CODE_DISABLE_AUTO_MEMORY", "1"), -]; - -/// The one MCP server the CLI gets: the tool bridge — as an `--mcp-config` -/// document, and the tool names its calls may use without the CLI asking -/// anyone. The team channel and the desktop are toolbox tools reached -/// through it, so no server of their own is handed over. -/// -/// `--strict-mcp-config` goes with it: the CLI loads ONLY what incode hands -/// it. Memory is reached through incode's own tools, not through a server -/// the operator happened to configure for the CLI. -fn servers_for(exe: &std::path::Path) -> (String, Vec) { - let mut servers = serde_json::Map::new(); - servers.insert( - crate::tool_bridge::CLIENT_KEY.to_string(), - crate::tool_bridge::client_entry(exe), - ); - // Allowed by server, not by tool: the CLI would otherwise refuse each call - // for want of a person to ask. Whether a call may run is decided by incode - // when it arrives, not by the CLI before it is sent. - let allowed = servers.keys().map(|key| format!("mcp__{key}")).collect(); - let config = serde_json::json!({ "mcpServers": servers }).to_string(); - (config, allowed) -} - -impl AgentBackend for ClaudeCodeBackend { - /// Both halves, by incode's own toolbox: a protected path is refused - /// before the write, and the model has no sub-agent tool but incode's, - /// which stops at its depth limit. - fn enforces(&self) -> crate::guards::Enforcement { - crate::guards::Enforcement::EVERYTHING - } - - fn system_context(&self) -> &[String] { - &self.system_context - } - - fn id(&self) -> &str { - "claude-code" - } - - // The session-shaped methods, forwarded to this backend's own. Fully - // qualified rather than `self.x()`, which would resolve to the inherent - // method and read as though the trait were calling itself. - - fn set_extra_dirs(&mut self, dirs: Vec) { - ClaudeCodeBackend::set_extra_dirs(self, dirs); - } - - /// The team channel's tools are incode's toolbox's on this route, so the - /// toolbox is who speaks. - fn set_team_identity(&mut self, role: &str) { - self.tools.set_team_identity(role); - } - - fn share_session_tools(&mut self, state: std::sync::Arc) { - self.tools.share_session(state); - } - - /// The CLI's own tools are switched off; every call comes back through - /// the bridge to this backend's toolbox. - fn runs_tools_here(&self) -> bool { - true - } - - fn deny_rules(&self) -> &[String] { - ClaudeCodeBackend::deny_rules(self) - } - - fn set_cancel(&mut self, token: crate::runtime::cancel::CancelToken) { - self.tools.set_cancel(token.clone()); - self.cancel = Some(token); - } - - fn set_prompter(&mut self, prompter: std::sync::Arc) { - self.tools.set_prompter(prompter); - } - - fn set_owner(&mut self, owner: std::sync::Arc) { - self.tools.set_owner(owner); - } - - fn share_allowed_writes(&mut self, record: std::sync::Arc) { - self.tools.share_allowed_writes(record); - } - - fn children(&self) -> Vec<(String, String)> { - self.tools - .children() - .into_iter() - .map(|c| (c.session, c.title)) - .collect() - } - - fn offered_tools(&self) -> Vec { - self.tools.names() - } - - /// The tools are incode's toolbox's on this route, so the toolbox is - /// what is watched. - fn set_watch(&mut self, watch: std::sync::Arc) { - self.tools.set_watch(watch); - } - - /// Taken headless: the next turn's prompt goes on stdin as a stream-json - /// message carrying them — see [`ClaudeCodeBackend::command`]. - fn attach_images(&mut self, images: Vec) -> Result<(), String> { - self.images = images; - Ok(()) - } - - fn model(&self) -> Option<&str> { - ClaudeCodeBackend::model(self) - } - - fn clear_session(&mut self) { - ClaudeCodeBackend::clear_session(self); - } - - fn set_permission_mode(&mut self, mode: &str) { - ClaudeCodeBackend::set_permission_mode(self, mode); - } - - fn set_session_id(&mut self, session_id: &str) { - ClaudeCodeBackend::set_session_id(self, session_id); - } - - /// The engine hears incode's session id with every call, not the CLI's - /// conversation id: incode's is the one its session events carry too. - fn set_memory_session(&mut self, session: &str) { - self.tools.pin_session(session); - } - - fn end_code_edits(&mut self) { - self.tools.end_code_edits(); - } - - fn set_system_context(&mut self, blocks: Vec) { - self.system_context = blocks - .into_iter() - .filter(|b| !b.trim().is_empty()) - .collect(); - } - - fn session_id(&self) -> Option<&str> { - self.session_id.as_deref() - } - - fn set_models(&mut self, candidates: &[String]) { - let applicable: Vec = candidates - .iter() - .filter(|c| self.serves(c)) - .cloned() - .collect(); - let Some((first, rest)) = applicable.split_first() else { - return; - }; - // Changing model abandons the session — see `with_models` for why a - // resumed conversation cannot be handed to a different model. - if self.model.as_deref() != Some(first.as_str()) { - self.session_id = None; - } - self.model = Some(first.clone()); - self.fallbacks = rest.to_vec(); - } - - fn ladder_for(&self, role: &str) -> Vec { - let ids: &[&str] = match role { - "explore" | "grunt" => &["haiku"], - "diagnose" | "review" | "plan" => &["opus", "sonnet"], - "implement" | "frontend" => &["sonnet", "opus"], - _ => &[], - }; - ids.iter().map(|id| (*id).to_string()).collect() - } - - fn run_turn( - &mut self, - prompt: &str, - on_event: &mut dyn FnMut(&AgentEvent), - ) -> Result { - // This turn's pictures, and only this turn's: taken now, so a turn - // that fails to start does not carry them into the next one. - let images = std::mem::take(&mut self.images); - let asked_for_thinking = self.partial_messages && self.thinking_display; - match self.run_once(prompt, images.clone(), on_event) { - // The CLI refused the undocumented thinking flag before it did - // anything: remembered for the session, and the turn run again, - // once, without it. - Err(e) if asked_for_thinking && rejects_thinking_display(&e.to_string()) => { - crate::trace!( - "agent", - "{} refused {THINKING_DISPLAY_FLAG}; running without it from now on", - self.binary - ); - self.thinking_display = false; - self.run_once(prompt, images, on_event) - } - other => other, - } - } -} - -impl ClaudeCodeBackend { - /// One run of the CLI for a turn: spawned, its tool calls answered, its - /// stream read to the end. - fn run_once( - &mut self, - prompt: &str, - images: Vec, - on_event: &mut dyn FnMut(&AgentEvent), - ) -> Result { - let (budgeted_prompt, budgeted_context) = - crate::agent::budget_for_spawn(prompt, &self.system_context, &self.workspace)?; - - // THE TOOLS ARE incode's. The CLI's own are switched off below and the - // model is handed incode's toolbox through the bridge, which this - // process answers for the whole turn. Without the bridge there would - // be no tools but the CLI's, so a bridge that cannot open stops the - // turn rather than falling back to them. - let crate::tool_bridge::Turn { - exe, - bridge, - to: to_loop, - from: from_cli, - } = crate::tool_bridge::Turn::open(self.cancel.clone())?; - let (servers, allowed) = servers_for(&exe); - - let mut cmd = self.command( - images.is_empty().then_some(budgeted_prompt.as_str()), - &budgeted_context, - &servers, - &allowed, - ); - // How the tool server finds this process: through the CLI's - // environment, which the servers it starts inherit — never its argv. - for (key, value) in bridge.env() { - cmd.env(key, value); - } - - // WHAT WAS ACTUALLY SPAWNED, on the ordinary trace. The flags decide the - // whole turn — which model, which profile, which deny rules — and a - // failure is unreadable without them. The full argv, including the - // appended system prompt, still goes to the stream dump below; this is - // the one-line version that belongs beside everything else that happened. - if crate::trace::on() { - let flags: Vec = cmd - .get_args() - .map(|a| a.to_string_lossy().into_owned()) - .filter(|a| a.starts_with("--")) - .collect(); - crate::trace!( - "agent", - "spawning {} model={:?} resume={:?} flags={}", - self.binary, - self.model, - self.session_id, - flags.join(" ") - ); - } - - // The exact command, when the operator asks for it. - // - // A turn that fails cannot be investigated from outside the harness - // without the argv that produced it: the flags, the deny rules and the - // whole appended system prompt are assembled here and were, until now, - // invisible. Written alongside the raw stream so a failure can be - // replayed by hand and the flags bisected. - if let Some(path) = debug_stream_path() { - if let Ok(mut file) = std::fs::OpenOptions::new() - .create(true) - .append(true) - .open(path) - { - use std::io::Write as _; - let argv: Vec = std::iter::once(self.binary.clone()) - .chain(cmd.get_args().map(|a| a.to_string_lossy().into_owned())) - .collect(); - // As JSON, so an argument containing spaces or newlines — the - // system prompt does — survives being read back. - let _ = writeln!( - file, - "{}", - serde_json::json!({ "type": "incode_argv", "argv": argv }) - ); - } - } - - // stdin must be closed explicitly, or the CLI waits ~3s for piped input - // on every invocation. A turn with pictures writes its one message - // there instead, and closes it. - crate::agent::process_tree::prepare(&mut cmd); - let mut child = cmd - .current_dir(&self.workspace) - .stdin(if images.is_empty() { - Stdio::null() - } else { - Stdio::piped() - }) - .stdout(Stdio::piped()) - .stderr(Stdio::piped()) - .spawn() - .map_err(|e| AgentError::new(format!("failed to spawn `{}`: {e}", self.binary)))?; - let tree = crate::agent::process_tree::Tree::adopt(&child); - if let Some(mut stdin) = child.stdin.take() { - // On a thread of its own: the message can be megabytes, and a - // pipe the CLI is not reading yet must not stall this loop. - let message = user_message(&budgeted_prompt, &images); - std::thread::spawn(move || { - use std::io::Write as _; - let _ = stdin.write_all(message.as_bytes()); - // Dropped here: the CLI ends its input, and its turn, on EOF. - }); - } - - let stdout = child - .stdout - .take() - .ok_or_else(|| AgentError::new("child stdout was not piped"))?; - // Drained from now, not after `wait()`: an agent that fills the pipe - // blocks on the write and never exits. See `stderr_tail`. - let stderr = crate::agent::stderr_tail::StderrTail::capture(child.stderr.take()); - - crate::tool_bridge::pump(BufReader::new(stdout), to_loop); - let outcome = consume( - &from_cli, - &mut self.session_id, - on_event, - self.cancel.as_ref(), - &mut self.tools, - &mut self.calls, - ); - // Closed as soon as the turn's loop is done: a call that arrives from - // here on is refused rather than left waiting on a loop that is gone. - drop(bridge); - - // Whatever happened, the child must not outlive this call. A cancelled - // turn that left the agent running would keep writing files with - // nobody reading its output — and that includes whatever it started. - let cancelled = matches!(outcome, Err(ref e) if e.to_string() == CANCELLED); - if cancelled { - tree.kill(&mut child); - } - let outcome = outcome?; - - let status = child - .wait() - .map_err(|e| AgentError::new(format!("waiting for agent: {e}")))?; - - match outcome { - Some(o) => { - if !o.session_id.is_empty() { - self.session_id = Some(o.session_id.clone()); - } - Ok(o) - } - None => Err(AgentError::new(format!( - "agent exited with {} before producing a result: {}", - status.code().unwrap_or(-1), - stderr.finish() - ))), - } - } -} - -// --------------------------------------------------------------------------- -// Tests — fixtures are real lines captured from Claude Code 2.1.229 -// --------------------------------------------------------------------------- - -#[cfg(test)] -pub(crate) mod tests { - - /// Build a home directory holding the named profiles. - /// - /// `hours` is how long each session has left; negative means it expired. - fn home_with(profiles: &[(&str, Option)]) -> tempfile::TempDir { - let home = tempfile::tempdir().expect("tmp"); - let now_ms = i64::try_from( - std::time::SystemTime::now() - .duration_since(std::time::UNIX_EPOCH) - .expect("clock") - .as_millis(), - ) - .expect("fits"); - for (name, hours) in profiles { - let dir = home.path().join(name); - std::fs::create_dir_all(&dir).expect("dir"); - if let Some(h) = hours { - #[allow(clippy::cast_possible_truncation)] - let expires = now_ms + (h * 3_600_000.0) as i64; - // Same nesting the real file uses, and the same field names. - // The token fields are deliberately absent: the code must never - // need them, and a test that supplied them would hide it if it did. - std::fs::write( - dir.join(".credentials.json"), - format!(r#"{{"claudeAiOauth":{{"expiresAt":{expires},"scopes":[]}}}}"#), - ) - .expect("write"); - } - } - home - } - - #[test] - fn the_profile_with_a_live_session_is_chosen_over_the_default() { - // The exact situation that broke every turn for a day: the default - // profile's session had expired while another profile was still good, - // and the agent fell back to the default because nothing said otherwise. - let home = home_with(&[(".claude", Some(-4.0)), (".claude-work", Some(2.0))]); - let chosen = pick_usable(profiles_in(home.path())).expect("one is live"); - assert!( - chosen.dir.ends_with(".claude-work"), - "chose {:?}, but only .claude-work can work", - chosen.dir - ); - } - - #[test] - fn the_longest_lived_session_wins() { - let home = home_with(&[ - (".claude", Some(1.0)), - (".claude-work", Some(9.0)), - (".claude-other", Some(4.0)), - ]); - let chosen = pick_usable(profiles_in(home.path())).expect("live"); - assert!(chosen.dir.ends_with(".claude-work"), "{:?}", chosen.dir); - } - - #[test] - fn every_session_expired_means_no_choice_rather_than_a_bad_one() { - // Picking an expired profile would produce the same unexplained failure - // this replaces. Choosing nothing lets the turn fail with the message - // that actually names the problem. - let home = home_with(&[(".claude", Some(-1.0)), (".claude-work", Some(-9.0))]); - assert_eq!(pick_usable(profiles_in(home.path())), None); - } - - #[test] - fn a_session_about_to_expire_is_not_treated_as_live() { - // Starting a turn on a session with seconds left fails halfway through, - // which is worse than not starting it. - let home = home_with(&[(".claude", Some(0.01))]); // 36 seconds - assert_eq!(pick_usable(profiles_in(home.path())), None); - } - - #[test] - fn only_directories_count_as_profiles() { - // The home also holds `.claude.json` and a long tail of its backups. - let home = home_with(&[(".claude-work", Some(3.0))]); - std::fs::write(home.path().join(".claude.json"), "{}").expect("write"); - std::fs::write(home.path().join(".claude.json.backup"), "{}").expect("write"); - let found = profiles_in(home.path()); - assert_eq!(found.len(), 1, "found {found:?}"); - assert!(found[0].dir.ends_with(".claude-work")); - } - - #[test] - fn a_directory_with_no_session_recorded_is_skipped() { - let home = home_with(&[(".claude", None), (".claude-work", Some(3.0))]); - let found = profiles_in(home.path()); - assert_eq!(found.len(), 1, "found {found:?}"); - } - - #[test] - fn the_expiry_is_found_wherever_it_is_nested() { - let doc: serde_json::Value = - serde_json::from_str(r#"{"a":{"b":{"expiresAt":1234567890123}}}"#).expect("parse"); - assert_eq!(find_expiry(&doc), Some(1_234_567_890_123)); - let none: serde_json::Value = serde_json::from_str(r#"{"a":{"b":1}}"#).expect("parse"); - assert_eq!(find_expiry(&none), None); - } - - /// An environment holding exactly these variables. - fn env_of(vars: &'static [(&'static str, &'static str)]) -> impl Fn(&str) -> Option { - move |name| { - vars.iter() - .find(|(k, _)| *k == name) - .map(|(_, v)| (*v).to_string()) - } - } - - /// **A LOGIN THE CLI USES ANYWAY IS NEVER SWAPPED FOR A FILE PROFILE.** - /// Redirecting to a live `.credentials.json` moved a Keychain login out - /// of reach on macOS, and with a credential in the environment it changed - /// nothing but which settings the CLI read. - #[test] - fn a_login_outside_the_profiles_keeps_the_agent_where_it_is() { - let home = home_with(&[(".claude-work", Some(5.0))]); - let outside = || Some(OutsideLogin::Environment("CLAUDE_CODE_OAUTH_TOKEN")); - assert_eq!( - choose_profile(profiles_in(home.path()), &outside), - None, - "a live file profile replaced a login the CLI already had" - ); - - let nothing_else = || None; - let chosen = choose_profile(profiles_in(home.path()), ¬hing_else).expect("live"); - assert!( - chosen.dir.ends_with(".claude-work"), - "with no other login, the live profile is still the choice" - ); - } - - /// The Keychain costs a process, so it is not asked when no live file - /// profile could be chosen anyway. - #[test] - fn the_keychain_is_not_asked_when_no_profile_is_live() { - let home = home_with(&[(".claude", Some(-2.0))]); - let asked = std::cell::Cell::new(false); - let outside = || { - asked.set(true); - Some(OutsideLogin::Keychain) - }; - assert_eq!(choose_profile(profiles_in(home.path()), &outside), None); - assert!( - !asked.get(), - "a process was spent on a question nobody needed" - ); - } - - /// A credential variable is a login, and only its NAME is reported. - #[test] - fn a_credential_in_the_environment_is_a_login_named_by_its_variable() { - let env = env_of(&[("CLAUDE_CODE_OAUTH_TOKEN", "x")]); - assert_eq!( - login_outside_profiles(&env, &|| false), - Some(OutsideLogin::Environment("CLAUDE_CODE_OAUTH_TOKEN")) - ); - let empty = env_of(&[("ANTHROPIC_API_KEY", "")]); - assert_eq!( - login_outside_profiles(&empty, &|| false), - None, - "an empty variable carries no credential" - ); - } - - /// Provider switches are read the way the CLI reads them: `0` is off. - #[test] - fn a_provider_switch_counts_only_when_it_is_on() { - for on in ["1", "true", "YES", " on "] { - let env = move |name: &str| (name == "CLAUDE_CODE_USE_BEDROCK").then(|| on.to_string()); - assert_eq!( - login_outside_profiles(&env, &|| false), - Some(OutsideLogin::Environment("CLAUDE_CODE_USE_BEDROCK")), - "`{on}` switches the provider on" - ); - } - for off in ["0", "false", "no", ""] { - let env = move |name: &str| (name == "CLAUDE_CODE_USE_VERTEX").then(|| off.to_string()); - assert_eq!( - login_outside_profiles(&env, &|| false), - None, - "`{off}` leaves the provider off" - ); - } - } - - /// A base URL says where requests go, not what authenticates them; on its - /// own it is the state in which every turn fails, and must not read as a - /// login. - #[test] - fn a_base_url_alone_is_not_a_login() { - let env = env_of(&[("ANTHROPIC_BASE_URL", "https://gateway.example")]); - assert_eq!(login_outside_profiles(&env, &|| false), None); - } - - /// The default Keychain entry belongs to the default profile; once the - /// operator names another directory the CLI looks under another service, - /// so the default entry says nothing about this session. - #[test] - fn the_keychain_counts_only_for_the_default_profile() { - let nothing = env_of(&[]); - assert_eq!( - login_outside_profiles(¬hing, &|| true), - Some(OutsideLogin::Keychain) - ); - let elsewhere = env_of(&[("CLAUDE_CONFIG_DIR", "/home/op/.claude-work")]); - assert_eq!(login_outside_profiles(&elsewhere, &|| true), None); - } - - /// **The harness's project context must actually REACH the agent.** It was - /// assembled and then dropped when the loop was removed: the build stayed - /// green, the tests passed and the live runs worked, while the guard rules, - /// the auditor's findings and the recorder's handoff silently stopped being - /// sent. Nothing catches that except asserting the argument is built. - #[test] - fn the_session_context_is_carried_to_the_agent() { - let backend = ClaudeCodeBackend::new(std::path::PathBuf::from(".")) - .with_system_context(vec!["do not edit tests".to_string()]); - assert_eq!( - backend.system_context(), - &["do not edit tests".to_string()] - ); - } - - /// Empty blocks are dropped rather than sent as blank lines — a context - /// section with nothing in it is noise the agent pays for. - #[test] - fn empty_context_blocks_are_not_sent() { - let backend = ClaudeCodeBackend::new(std::path::PathBuf::from(".")) - .with_system_context(vec![String::new(), " ".to_string(), "real".to_string()]); - assert_eq!(backend.system_context(), &["real".to_string()]); - } - - /// A session with no context sends no flag at all. - #[test] - fn no_context_means_no_flag() { - let backend = ClaudeCodeBackend::new(std::path::PathBuf::from(".")); - assert!(backend.system_context().is_empty()); - } - - /// **A cancelled turn stops reading and says so.** Without a distinct - /// error the caller cannot tell "the user pressed Ctrl-C" from "the agent - /// crashed", and would report a crash. - #[test] - fn a_cancelled_turn_stops_and_names_itself() { - let token = crate::runtime::cancel::CancelToken::new(); - token.cancel(); - let lines = "{\"type\":\"system\",\"subtype\":\"init\",\"session_id\":\"s\"}\n"; - let mut session = None; - let mut seen = Vec::new(); - let err = consume_stream( - std::io::BufReader::new(lines.as_bytes()), - &mut session, - &mut |e: &AgentEvent| seen.push(e.clone()), - Some(&token), - ) - .expect_err("a cancelled turn must not report success"); - assert_eq!(err.to_string(), CANCELLED); - assert!(seen.is_empty(), "it must stop BEFORE handling more output"); - } - - /// Without cancellation the same stream is read normally — the control - /// that proves the test above is measuring the flag and not the fixture. - #[test] - fn the_same_stream_reads_normally_when_not_cancelled() { - let lines = "{\"type\":\"system\",\"subtype\":\"init\",\"session_id\":\"s\"}\n"; - let mut session = None; - let mut seen = Vec::new(); - consume_stream( - std::io::BufReader::new(lines.as_bytes()), - &mut session, - &mut |e: &AgentEvent| seen.push(e.clone()), - None, - ) - .expect("it reads"); - assert_eq!(session.as_deref(), Some("s")); - assert_eq!(seen.len(), 1); - } - - /// **Captured from a real run, not composed here.** The delta shape is the - /// CLI's, and a parser written against an imagined one would pass its own - /// test and fail the first real line. - #[test] - fn a_text_delta_from_the_real_wire_becomes_a_delta_event() { - let line = r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"h"}},"session_id":"a77936b0","parent_tool_use_id":null,"uuid":"bfc09fc8"}"#; - let mut outcome = None; - let events = map_line(line, &mut outcome); - assert_eq!(events, vec![AgentEvent::TextDelta("h".to_string())]); - } - - /// A subagent's deltas are not the main conversation's text — the same rule - /// the whole-block branch already applies. - #[test] - fn a_subagents_delta_is_not_the_conversation() { - let line = r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"h"}},"parent_tool_use_id":"toolu_1"}"#; - let mut outcome = None; - assert!(map_line(line, &mut outcome).is_empty()); - } - - /// The other stream frames carry no user-facing text and must stay silent — - /// message_start and content_block_stop arrive for every single turn. - #[test] - fn stream_frames_that_are_not_text_produce_nothing() { - let mut outcome = None; - for line in [ - r#"{"type":"stream_event","event":{"type":"message_start","message":{"model":"m"}},"parent_tool_use_id":null}"#, - r#"{"type":"stream_event","event":{"type":"content_block_stop","index":0},"parent_tool_use_id":null}"#, - r#"{"type":"stream_event","event":{"type":"message_stop"},"parent_tool_use_id":null}"#, - ] { - assert!( - map_line(line, &mut outcome).is_empty(), - "should be silent: {line}" - ); - } - } - - /// **Deltas are opt-in.** A caller collecting a report must not be handed - /// two copies of the same words, so the flag is off unless asked for. - #[test] - fn partial_messages_are_off_unless_asked_for() { - let plain = ClaudeCodeBackend::new(std::path::PathBuf::from(".")); - assert!(!plain.partial_messages); - let streaming = ClaudeCodeBackend::new(std::path::PathBuf::from(".")).streaming(true); - assert!(streaming.partial_messages); - } - use super::*; - - const REAL_ASSISTANT: &str = r#"{"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CdyZz5W5Z65fqwbCLUrvy","type":"message","role":"assistant","content":[{"type":"text","text":"OK"}],"stop_reason":null,"usage":{"input_tokens":1,"output_tokens":1}},"parent_tool_use_id":null,"session_id":"e2996c17-f358-46fa-89b9-e757a4742abe"}"#; - - const REAL_RATE_LIMIT: &str = r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed","resetsAt":1786575600,"rateLimitType":"five_hour","overageStatus":"rejected","isUsingOverage":false},"session_id":"e2996c17-f358-46fa-89b9-e757a4742abe"}"#; - - /// The real result line puts `type` near the END of the object — a - /// deserializer that assumes `type` comes first will not parse it. - /// A FAILED result, in the wire shape the agent actually emits. - /// - /// The `result` and `subtype` fields here were not deserialized at all, so - /// a turn that ended this way was reported to the operator as the single - /// word `stop_sequence` — for an entire day, while the sentence explaining - /// it sat unread in the same line. - const FAILED_RESULT: &str = r#"{"is_error":true,"duration_api_ms":900,"num_turns":3,"stop_reason":"stop_sequence","session_id":"e2996c17-f358-46fa-89b9-e757a4742abe","usage":{"input_tokens":1,"output_tokens":2},"subtype":"error_during_execution","result":"tool use was interrupted before it completed","type":"result","duration_ms":1200}"#; - - const REAL_RESULT: &str = r#"{"is_error":false,"duration_api_ms":1846,"num_turns":1,"stop_reason":"end_turn","session_id":"393279e4-f6e9-4d64-bd17-57926443ef94","total_cost_usd":0.399,"usage":{"input_tokens":1,"cache_creation_input_tokens":36371,"cache_read_input_tokens":23432,"output_tokens":4},"subtype":"success","result":"OK","type":"result","duration_ms":31639}"#; - - fn map(line: &str) -> (Vec, Option) { - let mut outcome = None; - let events = map_line(line, &mut outcome); - (events, outcome) - } - - #[test] - fn parses_assistant_text_from_real_output() { - let (events, _) = map(REAL_ASSISTANT); - assert_eq!(events, vec![AgentEvent::Text("OK".to_string())]); - } - - /// A subagent's messages must not be mistaken for the main conversation. - #[test] - fn subagent_output_is_not_emitted_as_main_text() { - let sub = REAL_ASSISTANT.replace( - r#""parent_tool_use_id":null"#, - r#""parent_tool_use_id":"toolu_1""#, - ); - assert_ne!(sub, REAL_ASSISTANT, "fixture must actually differ"); - let (events, _) = map(&sub); - assert!( - events.is_empty(), - "subagent text must not surface as main-conversation output; got {events:?}" - ); - } - - #[test] - fn parses_subscription_quota_signal() { - let (events, _) = map(REAL_RATE_LIMIT); - assert_eq!( - events, - vec![AgentEvent::Quota { - status: "allowed".to_string(), - kind: "five_hour".to_string(), - resets_at: 1_786_575_600, - using_overage: false, - }] - ); - } - - /// Guards the field-order hazard: `type` is not the first key on this line. - #[test] - fn a_failed_turn_reports_what_the_agent_said_about_it() { - let (_, outcome) = map(FAILED_RESULT); - let outcome = outcome.expect("the result line produces an outcome"); - assert!(outcome.is_error); - let said = outcome.failure(); - assert!( - said.contains("tool use was interrupted"), - "the agent's own explanation must reach the operator: {said}" - ); - assert!( - said.contains("error_during_execution"), - "and so must the category: {said}" - ); - assert!( - !said.contains("gave no reason"), - "it DID give a reason: {said}" - ); - } - - #[test] - fn a_successful_turn_carries_no_detail() { - // On success `result` repeats the streamed reply; carrying it would - // print every answer twice. - let (_, outcome) = map(REAL_RESULT); - assert_eq!(outcome.expect("outcome").detail, None); - } - - #[test] - fn parses_result_line_despite_type_being_last() { - let (events, outcome) = map(REAL_RESULT); - let outcome = outcome.expect("result line must yield a turn outcome"); - assert_eq!(outcome.stop_reason, "end_turn"); - assert!(!outcome.is_error); - assert_eq!(outcome.session_id, "393279e4-f6e9-4d64-bd17-57926443ef94"); - assert_eq!( - events, - vec![AgentEvent::Usage { - input_tokens: 1, - output_tokens: 4, - cache_creation_tokens: 36371, - cache_read_tokens: 23432, - }] - ); - } - - /// A result line from a real two-request turn (`claude -p … --output-format - /// stream-json --verbose`, 2026-09-25), trimmed to the fields read here. - /// The top-level usage is the SUM of both requests; `iterations` holds the - /// last request only; `modelUsage` carries the window. - const REAL_TWO_REQUEST_RESULT: &str = r#"{"type":"result","subtype":"success","is_error":false,"num_turns":2,"stop_reason":"end_turn","session_id":"sess-probe","total_cost_usd":0.19127059999999999,"usage":{"input_tokens":4,"cache_creation_input_tokens":22197,"cache_read_input_tokens":55293,"output_tokens":131,"iterations":[{"input_tokens":2,"output_tokens":4,"cache_read_input_tokens":38663,"cache_creation_input_tokens":164,"type":"message"}]},"modelUsage":{"claude-opus-5-5":{"inputTokens":4,"outputTokens":131,"cacheReadInputTokens":55293,"cacheCreationInputTokens":22197,"webSearchRequests":0,"costUSD":0.19127059999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":0,"canonicalModel":"claude-opus-5-5","provider":"firstParty","costBasis":"list"}},"result":"banana"}"#; - - /// **CONTEXT USED IS THE LAST REQUEST, NOT THE TURN'S SUM.** - /// - /// The sum counts the same cached prefix once per request — 77 494 input - /// tokens here for a context that held 38 829 — so it would show a window - /// twice as full as it is. The window is the one the CLI reported. - #[test] - fn a_result_reports_the_last_requests_context_and_the_reported_window() { - let (events, _) = map(REAL_TWO_REQUEST_RESULT); - let context: Vec<&AgentEvent> = events - .iter() - .filter(|e| matches!(e, AgentEvent::Context { .. })) - .collect(); - assert_eq!( - context, - vec![&AgentEvent::Context { - used: 2 + 38_663 + 164 + 4, - size: 1_000_000, - }] - ); - } - - /// With more than one model on the result, the window is the one of the - /// model that held the conversation: the one given the most input. A side - /// model sees a fragment of it. (The second entry is added to the real - /// line for this test.) - #[test] - fn the_window_is_the_conversations_model_not_a_side_one() { - let line = REAL_TWO_REQUEST_RESULT.replace( - r#""modelUsage":{"#, - r#""modelUsage":{"side-model":{"inputTokens":900,"cacheReadInputTokens":0,"cacheCreationInputTokens":0,"contextWindow":200000},"#, - ); - let (events, _) = map(&line); - assert!( - events.contains(&AgentEvent::Context { - used: 38_833, - size: 1_000_000 - }), - "{events:?}" - ); - } - - /// No window reported, no context event — the token counts still go out - /// as [`AgentEvent::Usage`]. - #[test] - fn no_window_means_no_context_event() { - let (events, _) = map(REAL_RESULT); - assert!( - !events - .iter() - .any(|e| matches!(e, AgentEvent::Context { .. })), - "{events:?}" - ); - } - - /// The final text must be emitted exactly once. The result line repeats it, - /// so counting both duplicates every reply the user sees. - #[test] - fn final_text_is_not_emitted_twice() { - let mut outcome = None; - let mut texts = Vec::new(); - for line in [REAL_ASSISTANT, REAL_RESULT] { - for e in map_line(line, &mut outcome) { - if let AgentEvent::Text(t) = e { - texts.push(t); - } - } - } - assert_eq!( - texts, - vec!["OK".to_string()], - "assistant blocks and the result line both carry the reply; only one may be emitted" - ); - } - - /// An unrecognised line must be skipped, not abort the turn. - #[test] - fn unknown_event_type_is_skipped() { - let (events, outcome) = map(r#"{"type":"some_future_event","payload":{}}"#); - assert!(events.is_empty()); - assert!(outcome.is_none()); - } - - #[test] - fn malformed_line_does_not_panic() { - let (events, outcome) = map("not json at all"); - assert!(events.is_empty()); - assert!(outcome.is_none()); - } - - /// Drive the stream loop the way a real turn does, over canned bytes. - fn drive(stream: &str) -> (Vec, Option, Option) { - let mut session = None; - let mut seen = Vec::new(); - let outcome = { - let mut sink = |e: &AgentEvent| seen.push(e.clone()); - consume_stream( - std::io::BufReader::new(std::io::Cursor::new(stream.as_bytes())), - &mut session, - &mut sink, - None, - ) - .expect("a well-formed stream must not error") - }; - (seen, session, outcome) - } - - /// A whole turn, in the order and shape the real CLI emits it — including - /// the hook events that precede `init` when the agent loads user config. - const REAL_SESSION: &str = concat!( - r#"{"type":"system","subtype":"hook_started","hook_id":"b5d0"}"#, - "\n", - r#"{"type":"system","subtype":"hook_response","hook_id":"b5d0"}"#, - "\n", - r#"{"type":"system","subtype":"init","session_id":"sess-real","model":"claude-opus-5[1m]"}"#, - "\n", - "\n", - r#"{"type":"assistant","message":{"content":[{"type":"text","text":"OK"}]},"parent_tool_use_id":null}"#, - "\n", - r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed","resetsAt":1786575600,"rateLimitType":"five_hour","isUsingOverage":false}}"#, - "\n", - r#"{"is_error":false,"stop_reason":"end_turn","session_id":"sess-real","usage":{"input_tokens":1,"output_tokens":4,"cache_creation_input_tokens":36371,"cache_read_input_tokens":23432},"type":"result"}"#, - "\n", - ); - - /// The stream loop must turn a real turn into the right events, in order, - /// and skip the blank line without treating it as data. - #[test] - fn consumes_a_real_turn_into_ordered_events() { - let (events, session, outcome) = drive(REAL_SESSION); - - assert_eq!( - events, - vec![ - AgentEvent::SessionStarted { - session_id: "sess-real".to_string(), - model: "claude-opus-5[1m]".to_string(), - }, - AgentEvent::Text("OK".to_string()), - AgentEvent::Quota { - status: "allowed".to_string(), - kind: "five_hour".to_string(), - resets_at: 1_786_575_600, - using_overage: false, - }, - AgentEvent::Usage { - input_tokens: 1, - output_tokens: 4, - cache_creation_tokens: 36371, - cache_read_tokens: 23432, - }, - ], - "hook events must be dropped and the rest emitted in stream order" - ); - - assert_eq!(session.as_deref(), Some("sess-real")); - let outcome = outcome.expect("a result line must produce an outcome"); - assert_eq!(outcome.stop_reason, "end_turn"); - assert!(!outcome.is_error); - } - - /// The session id must be captured even if the turn dies before the result - /// line — otherwise a crashed turn forces the next one to start fresh and - /// re-pay the whole prompt prefix. - #[test] - fn session_is_captured_even_when_the_turn_never_completes() { - let truncated = REAL_SESSION - .lines() - .take(3) // hook, hook, init — then the agent dies - .collect::>() - .join("\n"); - - let (_, session, outcome) = drive(&truncated); - - assert_eq!( - session.as_deref(), - Some("sess-real"), - "a turn that dies after init must still leave a resumable session" - ); - assert!( - outcome.is_none(), - "no result line means no outcome — the caller must see the failure" - ); - } - - /// Garbage in the middle of a stream must not abort the turn; the CLI adds - /// event types over time and an unknown line is not a failure. - #[test] - fn a_corrupt_line_does_not_abort_the_turn() { - let mut polluted = String::from(REAL_SESSION); - polluted = polluted.replace( - r#"{"type":"rate_limit_event""#, - r#"{{{NOT JSON}}} -{"type":"rate_limit_event""#, - ); - - let (events, _, outcome) = drive(&polluted); - assert!( - outcome.is_some(), - "the turn must still complete despite an unparseable line" - ); - assert!(events - .iter() - .any(|e| matches!(e, AgentEvent::Text(t) if t == "OK"))); - } - - /// Session reuse is the single largest cost lever in this backend: measured - /// against CLI 2.1.229, a fresh session costs ~36k cache-creation tokens per - /// turn versus ~1.8k when resuming — roughly 5.8x. That only holds if the - /// backend actually remembers the session and asks to continue it, so this - /// asserts the state transition that makes `--resume` possible. - #[test] - fn backend_remembers_the_session_so_later_turns_can_resume() { - let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")); - assert!( - backend.session_id().is_none(), - "control: a fresh backend has no session to resume" - ); - - // Drive the state transition the way a real turn does: the init line - // carries the session id. - let mut outcome = None; - for event in map_line( - r#"{"type":"system","subtype":"init","session_id":"sess-xyz","model":"m"}"#, - &mut outcome, - ) { - if let AgentEvent::SessionStarted { session_id, .. } = event { - backend.session_id = Some(session_id); - } - } - - assert_eq!( - backend.session_id(), - Some("sess-xyz"), - "the backend must retain the session id, or every turn starts fresh \ - and re-pays the whole prompt prefix" - ); - } - - /// An explicitly supplied session must be carried too, so a caller can - /// continue a task across process restarts. - #[test] - fn explicit_session_is_carried() { - let backend = ClaudeCodeBackend::new(PathBuf::from(".")).with_session("prior-session"); - assert_eq!(backend.session_id(), Some("prior-session")); - } - - #[test] - fn session_id_is_captured_for_resume() { - let (events, _) = map( - r#"{"type":"system","subtype":"init","session_id":"abc-123","model":"claude-opus-5[1m]"}"#, - ); - assert_eq!( - events, - vec![AgentEvent::SessionStarted { - session_id: "abc-123".to_string(), - model: "claude-opus-5[1m]".to_string(), - }] - ); - } - - /// **Changing the model abandons the session, and that is deliberate.** A - /// resumed session carries earlier turns; asking a different model to - /// continue them means paying to resume a conversation it never had. - #[test] - fn switching_model_starts_a_fresh_session() { - let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")) - .with_session("s-existing") - .with_models(&["cheap".to_string()]); - assert_eq!(backend.model(), Some("cheap")); - assert_eq!( - backend.session_id(), - None, - "a session belonging to another model must not be resumed" - ); - - // Re-asking for the SAME model must not throw away a session — that - // would re-pay the whole prompt prefix on every turn. - backend.session_id = Some("s-cheap".to_string()); - backend.set_models(&["cheap".to_string()]); - assert_eq!(backend.session_id(), Some("s-cheap")); - - // And switching again drops it. - backend.set_models(&["expensive".to_string()]); - assert_eq!(backend.session_id(), None); - } - - /// An empty candidate list is "no opinion", not "clear the model". - #[test] - fn no_candidates_leaves_the_choice_untouched() { - let mut backend = - ClaudeCodeBackend::new(PathBuf::from(".")).with_models(&["cheap".to_string()]); - backend.set_models(&[]); - assert_eq!(backend.model(), Some("cheap")); - } - - /// The rest of the chain becomes the CLI's own fallback list, which is the - /// shape it takes: one comma-separated argument, tried in order. - #[test] - fn the_candidate_chain_becomes_the_fallback_list() { - let backend = ClaudeCodeBackend::new(PathBuf::from(".")).with_models(&[ - "first".to_string(), - "second".to_string(), - "third".to_string(), - ]); - assert_eq!(backend.model(), Some("first")); - assert_eq!( - backend.fallbacks, - vec!["second".to_string(), "third".to_string()] - ); - } - - /// **What actually ran, from the billing record.** Captured from a real - /// turn: the request named a model that does not exist, the CLI warned, and - /// the FALLBACK answered — so `modelUsage` and the requested name disagree, - /// which is exactly the case attribution has to get right. - #[test] - fn the_served_model_comes_from_the_billing_record_not_the_request() { - let real = r#"{"type":"result","is_error":false,"session_id":"s-1", - "stop_reason":"end_turn","result":"OK", - "usage":{"input_tokens":1,"output_tokens":4}, - "modelUsage":{"claude-haiku-4-5-20251001":{"inputTokens":1,"outputTokens":4}}}"#; - let (_, outcome) = map(real); - let outcome = outcome.expect("a result line produces an outcome"); - assert_eq!( - outcome.served_by, - vec!["claude-haiku-4-5-20251001".to_string()] - ); - } - - /// **Not reported is empty, never guessed.** A backend that says nothing - /// about the model must not have the requested one filled in for it. - #[test] - fn a_result_without_a_billing_record_reports_no_model() { - let (_, outcome) = map(REAL_RESULT); - assert!( - outcome.expect("an outcome").served_by.is_empty(), - "an absent billing record must stay absent" - ); - } - - /// **`Edit`, never `Write`.** Measured: a rule denying only `Write(tests/**)` - /// let the file through, and this CLI reports that only `Edit(path)` rules - /// are matched by file permission checks. A guard that parses and does - /// nothing is worse than no guard, so the tool name is pinned. - /// - /// This test lives HERE, beside the renderer, because it is a fact about one - /// agent's permission layer rather than about the harness's policy. - #[test] - fn the_rendered_rules_use_the_tool_name_that_actually_binds() { - let rules = render_denials(&crate::guards::restrictions( - &crate::guards::Guards::default(), - )); - assert!(!rules.is_empty(), "the defaults must produce rules"); - for rule in rules.iter().filter(|r| *r != SUBAGENT_TOOL) { - assert!( - rule.starts_with("Edit("), - "`Write(...)` is silently ignored by the permission layer: {rule}" - ); - } - } - - /// The policy's "no sub-agents" becomes THIS agent's word for it. - #[test] - fn refusing_sub_agents_renders_as_this_agents_tool_name() { - let with = crate::guards::Restrictions { - no_write: Vec::new(), - no_subagents: true, - }; - let without = crate::guards::Restrictions { - no_write: Vec::new(), - no_subagents: false, - }; - assert_eq!(render_denials(&with), vec![SUBAGENT_TOOL.to_string()]); - assert!( - render_denials(&without).is_empty(), - "a policy that permits delegation must not deny it anyway" - ); - } - - /// A bare glob from the policy is wrapped, not passed through raw. - /// - /// The policy deliberately carries `**/tests/**` with no syntax around it; - /// handing that to the CLI unwrapped would be accepted and enforce nothing. - #[test] - fn a_bare_policy_glob_is_wrapped_in_this_agents_syntax() { - let rules = render_denials(&crate::guards::Restrictions { - no_write: vec!["**/tests/**".to_string()], - no_subagents: false, - }); - assert_eq!(rules, vec!["Edit(**/tests/**)".to_string()]); - } - - /// Foreign vendor model IDs are dropped so mixed-fleet candidate lists from - /// shared tiers do not cause Claude Code CLI to error on unsupported flags. - #[test] - fn foreign_model_id_is_dropped_from_claude_candidates() { - let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")); - backend.set_models(&[ - "gemini-3.8-flash-high".to_string(), - "gpt-5.6-terra".to_string(), - ]); - assert_eq!(backend.model(), None); - - backend.set_models(&[ - "gemini-3.8-flash-high".to_string(), - "sonnet".to_string(), - "gpt-5.6-terra".to_string(), - ]); - assert_eq!(backend.model(), Some("sonnet")); - assert_eq!(backend.fallbacks, Vec::::new()); - } - - /// Every role in the native Claude Code ladder can be served by Claude Code. - #[test] - fn claude_code_ladder_for_known_roles_serves_every_model() { - let backend = ClaudeCodeBackend::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 claude-code cannot serve" - ); - } - } - assert_ne!( - backend.ladder_for("explore"), - backend.ladder_for("diagnose"), - "reading and reasoning must not draw the same tier" - ); - } - - /// A stand-in agent that writes far more to stderr than a pipe holds, then - /// exits without ever printing a result — the shape of a CLI that fails - /// loudly at startup. - fn a_loud_failing_agent(dir: &std::path::Path) -> PathBuf { - #[cfg(windows)] - { - let path = dir.join("loud-agent.cmd"); - std::fs::write( - &path, - "@echo off\r\nfor /L %%i in (1,1,3000) do echo stderr line %%i \ - padding padding padding padding padding padding padding 1>&2\r\n\ - echo token=hunter2-not-a-real-secret 1>&2\r\nexit /b 3\r\n", - ) - .expect("write the fake agent"); - path - } - #[cfg(not(windows))] - { - use std::os::unix::fs::PermissionsExt; - let path = dir.join("loud-agent.sh"); - std::fs::write( - &path, - "#!/bin/sh\ni=0\nwhile [ $i -lt 3000 ]; do echo \"stderr line $i padding \ - padding padding padding padding padding padding\" >&2; i=$((i+1)); done\n\ - echo 'token=hunter2-not-a-real-secret' >&2\nexit 3\n", - ) - .expect("write the fake agent"); - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) - .expect("make it runnable"); - path - } - } - - /// **A LOUD FAILURE DOES NOT HANG THE TURN, AND WHAT IT SAID IS BOUNDED - /// AND CLEANED.** - /// - /// stderr was piped and only read after `wait()`. An agent that wrote more - /// than the pipe holds blocked on the write, never exited, and `wait()` - /// never returned: the turn hung with no message. The same text, once - /// read, went unbounded and unredacted into the error, the ledger and the - /// transcript. - #[test] - fn an_agent_that_floods_stderr_fails_promptly_with_a_bounded_clean_reason() { - let dir = tempfile::tempdir().expect("scratch"); - let fake = a_loud_failing_agent(dir.path()); - let workspace = dir.path().to_path_buf(); - - let (tx, rx) = std::sync::mpsc::channel(); - std::thread::spawn(move || { - let mut backend = ClaudeCodeBackend::new(workspace).with_binary(fake.to_string_lossy()); - let result = backend.run_turn("hi", &mut |_| {}); - let _ = tx.send(result.map(|_| ()).map_err(|e| e.to_string())); - }); - - let result = rx - .recv_timeout(std::time::Duration::from_secs(60)) - .expect("the turn hung: the agent's stderr was never drained"); - let reason = result.expect_err("the fake agent produced no result line"); - - assert!( - reason.contains("stderr line"), - "what the agent said was lost: {reason}" - ); - assert!( - reason.len() <= crate::agent::stderr_tail::MAX_BYTES + 1024, - "the reason was not bounded: {} bytes", - reason.len() - ); - assert!( - !reason.contains("hunter2-not-a-real-secret"), - "a secret-shaped value reached the error unredacted" - ); - } - - // ----------------------------------------------------------------------- - // Models only: the CLI's tools off, incode's toolbox on. - // ----------------------------------------------------------------------- - - fn args_of(cmd: &Command) -> Vec { - cmd.get_args() - .map(|a| a.to_string_lossy().into_owned()) - .collect() - } - - fn value_after(args: &[String], flag: &str) -> Option { - let at = args.iter().position(|a| a == flag)?; - args.get(at + 1).cloned() - } - - /// **THE CLI IS STARTED AS A MODEL AND NOTHING ELSE**: no tools of its - /// own, only incode's servers, none of its settings — and none of the - /// harness flags it used to be handed, because it has nothing left for - /// them to govern. - #[test] - fn the_cli_is_started_with_its_own_harness_switched_off() { - let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")) - .with_guards(&crate::guards::Guards::default()); - backend.set_permission_mode("plan"); - assert!( - !backend.deny_rules().is_empty(), - "control: there are deny rules that could leak onto the argv" - ); - let (servers, allowed) = servers_for(std::path::Path::new("incode")); - let cmd = backend.command(Some("hi"), "", &servers, &allowed); - let args = args_of(&cmd); - - assert_eq!( - value_after(&args, "--tools").as_deref(), - Some(""), - "{args:?}" - ); - assert_eq!( - value_after(&args, "--setting-sources").as_deref(), - Some(""), - "{args:?}" - ); - assert!(args.iter().any(|a| a == "--strict-mcp-config"), "{args:?}"); - assert!( - args.iter().any(|a| a == "--disable-slash-commands"), - "{args:?}" - ); - assert_eq!( - value_after(&args, "--allowedTools").as_deref(), - Some("mcp__incode") - ); - for gone in [ - "--permission-mode", - "--disallowedTools", - "--add-dir", - "--dangerously-skip-permissions", - "--bare", - ] { - assert!( - !args.iter().any(|a| a == gone), - "{gone} reached the CLI: {args:?}" - ); - } - let envs: Vec<(String, String)> = cmd - .get_envs() - .filter_map(|(k, v)| { - Some(( - k.to_string_lossy().into_owned(), - v?.to_string_lossy().into_owned(), - )) - }) - .collect(); - for (key, value) in MODEL_ONLY_ENV { - assert!( - envs.iter().any(|(k, v)| k == key && v == value), - "{key} is not set: {envs:?}" - ); - } - } - - /// **A TURN IS ITS OWN SESSION, NEVER THE ONE INCODE WAS LAUNCHED FROM.** - /// Issue #3: run from inside another session, every turn reported that - /// session's id as its own. - #[test] - fn the_cli_never_joins_the_session_that_launched_incode() { - let backend = ClaudeCodeBackend::new(PathBuf::from(".")); - let (servers, allowed) = servers_for(std::path::Path::new("incode")); - for prompt in [Some("hi"), None] { - let cmd = backend.command(prompt, "", &servers, &allowed); - assert!( - cmd.get_envs() - .any(|(k, v)| k == "CLAUDECODE" && v.is_none()), - "CLAUDECODE is inherited, so the turn joins the parent's session" - ); - } - } - - /// **THE DESKTOP IS THE TOOLBOX'S, NOT A SERVER BESIDE THE BRIDGE.** With - /// the desktop switched on, the model's tool list (the toolbox's) holds - /// the desktop tools, and the CLI is handed the bridge and nothing else. - #[test] - fn the_bridge_is_the_only_server_and_the_desktop_is_the_toolboxs() { - let off = ClaudeCodeBackend::new(PathBuf::from(".")); - assert!( - !off.tools.names().iter().any(|n| n == "screenshot"), - "a desktop nobody switched on" - ); - let on = - ClaudeCodeBackend::new(PathBuf::from(".")).with_desktop(crate::toolbox::DesktopSetup { - exe: PathBuf::from("incode"), - journal: PathBuf::from(".incode/desktop.jsonl"), - }); - let names = on.tools.names(); - for tool in ["screenshot", "screen_info", "ui_tree", "click", "type_text"] { - assert!(names.iter().any(|n| n == tool), "{tool} missing: {names:?}"); - } - let (servers, allowed) = servers_for(std::path::Path::new("incode")); - let parsed: serde_json::Value = serde_json::from_str(&servers).expect("json"); - let keys: Vec<&String> = parsed["mcpServers"] - .as_object() - .expect("servers") - .keys() - .collect(); - assert_eq!(keys, [crate::tool_bridge::CLIENT_KEY], "{servers}"); - assert_eq!( - parsed["mcpServers"][crate::tool_bridge::CLIENT_KEY]["args"][0], - crate::tool_bridge::SERVER_FLAG - ); - assert_eq!(allowed, ["mcp__incode".to_string()]); - } - - /// One request to the bridge, as the tool server sends it. - fn raw_call( - addr: &str, - token: &str, - name: &str, - input: serde_json::Value, - ) -> serde_json::Value { - use std::io::Write as _; - let mut stream = std::net::TcpStream::connect(addr).expect("connect"); - let body = serde_json::json!({"token": token, "op": "call", "name": name, "input": input}); - writeln!(stream, "{body}").expect("send"); - let mut line = String::new(); - BufReader::new(stream).read_line(&mut line).expect("reply"); - serde_json::from_str(&line).expect("json reply") - } - - /// **A TOOL CALL MID-TURN IS RUN BY incode's TOOLBOX, AND SHOWN ONCE.** - /// - /// The CLI's stream carries its own record of the call it forwarded — the - /// `tool_use` and `tool_result` blocks. Those are not shown: the call is - /// shown as incode ran it, under incode's name for the tool. - #[test] - fn a_tool_call_mid_turn_runs_in_incodes_toolbox_and_is_shown_once() { - let ws = tempfile::tempdir().expect("ws"); - let mut tools = crate::toolbox::Toolbox::new(ws.path(), true); - let (to, from) = std::sync::mpsc::channel(); - let bridge = - crate::tool_bridge::Bridge::open(to.clone(), Incoming::Tool, None).expect("bridge"); - let [(_, addr), (_, token)] = bridge.env(); - - let cli = std::thread::spawn(move || { - let say = |line: &str| { - let _ = to.send(Incoming::Line(line.to_string())); - }; - say(r#"{"type":"system","subtype":"init","session_id":"s-bridge","model":"m"}"#); - say( - r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_1","name":"mcp__incode__Write","input":{"path":"hello.txt","content":"hi"}}]},"parent_tool_use_id":null}"#, - ); - let reply = raw_call( - &addr, - &token, - "Write", - serde_json::json!({"path": "hello.txt", "content": "hi"}), - ); - say( - r#"{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"toolu_1","content":"wrote it","is_error":false}]},"parent_tool_use_id":null}"#, - ); - say( - r#"{"type":"assistant","message":{"content":[{"type":"text","text":"done"}]},"parent_tool_use_id":null}"#, - ); - say( - r#"{"type":"result","is_error":false,"stop_reason":"end_turn","session_id":"s-bridge","usage":{"input_tokens":1,"output_tokens":1}}"#, - ); - let _ = to.send(Incoming::Ended); - reply - }); - - let mut session = None; - let mut seen = Vec::new(); - let mut calls = 0; - let outcome = consume( - &from, - &mut session, - &mut |e: &AgentEvent| seen.push(e.clone()), - None, - &mut tools, - &mut calls, - ) - .expect("the turn completes"); - drop(bridge); - let reply = cli.join().expect("the fake CLI"); - - assert_eq!(reply["ok"], true, "{reply}"); - assert_eq!( - std::fs::read_to_string(ws.path().join("hello.txt")).expect("written by incode"), - "hi" - ); - assert!(outcome.is_some_and(|o| !o.is_error)); - let uses: Vec<&AgentEvent> = seen - .iter() - .filter(|e| matches!(e, AgentEvent::ToolUse { .. })) - .collect(); - assert_eq!(uses.len(), 1, "one call, shown once: {seen:?}"); - assert!( - matches!(uses[0], AgentEvent::ToolUse { name, id, .. } if name == "Write" && id == "incode-1"), - "shown under incode's own name and id: {seen:?}" - ); - let results: Vec<&AgentEvent> = seen - .iter() - .filter(|e| matches!(e, AgentEvent::ToolResult { .. })) - .collect(); - assert_eq!(results.len(), 1, "{seen:?}"); - assert!( - matches!(results[0], AgentEvent::ToolResult { output, is_error: false, .. } if !output.contains("wrote it")), - "the result is incode's, not the CLI's echo: {seen:?}" - ); - } - - /// **A QUIET TURN STILL STOPS.** Nothing arrives — the model thinking, a - /// long command — and the stop lands within the poll, not at the next - /// line the CLI happens to print. - #[test] - fn a_quiet_turn_stops_promptly_when_cancelled() { - let token = crate::runtime::cancel::CancelToken::new(); - let (to, from) = std::sync::mpsc::channel::(); - let stopper = token.clone(); - std::thread::spawn(move || { - std::thread::sleep(std::time::Duration::from_millis(300)); - stopper.cancel(); - }); - let mut tools = crate::toolbox::Toolbox::new(std::path::Path::new("."), true); - let started = std::time::Instant::now(); - let err = consume( - &from, - &mut None, - &mut |_| {}, - Some(&token), - &mut tools, - &mut 0, - ) - .expect_err("a stopped turn is not a finished one"); - assert_eq!(err.to_string(), CANCELLED); - assert!( - started.elapsed() < std::time::Duration::from_secs(5), - "{:?}", - started.elapsed() - ); - drop(to); - } - - /// **A TURN WITH PICTURES GIVES ITS PROMPT ON STDIN**, as the stream-json - /// message the CLI was measured reading: no prompt on the argv, the input - /// format named, and the message holding the text then each picture as a - /// base64 image block. Thinking is asked for as a readable summary when - /// partial messages are on. - #[test] - fn a_turn_with_pictures_sends_its_prompt_as_a_stream_json_message() { - let backend = ClaudeCodeBackend::new(PathBuf::from(".")).streaming(true); - let (servers, allowed) = servers_for(std::path::Path::new("incode")); - let args = args_of(&backend.command(None, "", &servers, &allowed)); - assert_eq!(value_after(&args, "-p").as_deref(), Some("--input-format")); - assert_eq!( - value_after(&args, "--input-format").as_deref(), - Some("stream-json") - ); - assert_eq!( - value_after(&args, "--thinking-display").as_deref(), - Some("summarized") - ); - let plain = args_of(&backend.command(Some("hi"), "", &servers, &allowed)); - assert_eq!(value_after(&plain, "-p").as_deref(), Some("hi")); - assert!(!plain.iter().any(|a| a == "--input-format"), "{plain:?}"); - - let picture = crate::toolbox::Image::from_base64( - "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC", - ) - .expect("a 1x1 png"); - let line = user_message("what is this", std::slice::from_ref(&picture)); - assert!(line.ends_with('\n')); - let message: serde_json::Value = serde_json::from_str(line.trim()).expect("json"); - assert_eq!(message["type"], "user"); - let content = &message["message"]["content"]; - assert_eq!( - content[0], - serde_json::json!({"type": "text", "text": "what is this"}) - ); - assert_eq!(content[1]["type"], "image"); - assert_eq!(content[1]["source"]["media_type"], "image/png"); - assert_eq!(content[1]["source"]["data"], picture.base64()); - } - - /// A summarized thinking delta is the model's reasoning; an empty one — - /// the default display — is nothing. - #[test] - fn a_thinking_delta_becomes_a_thought_and_an_empty_one_nothing() { - let line = r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"This is a","estimated_tokens":null}},"session_id":"c2","parent_tool_use_id":null,"thinking_display":"summarized"}"#; - let (events, _) = map(line); - assert!( - matches!(events.as_slice(), [AgentEvent::Thinking(t)] if t == "This is a"), - "{events:?}" - ); - let empty = r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"","estimated_tokens":50}},"session_id":"d4","parent_tool_use_id":null,"thinking_display":"updates"}"#; - assert!(map(empty).0.is_empty()); - } - - /// A stand-in CLI whose option parser does not know the thinking flag: - /// named on its argv, it says so on stderr and exits 1 before any - /// output; otherwise it prints a short turn. Every start is counted in - /// `starts.txt` beside it. - fn a_cli_without_the_thinking_flag(dir: &std::path::Path) -> PathBuf { - const LINES: [&str; 3] = [ - r#"{"type":"system","subtype":"init","session_id":"no-think-1","model":"m"}"#, - r#"{"type":"assistant","message":{"content":[{"type":"text","text":"still here"}]},"parent_tool_use_id":null}"#, - r#"{"type":"result","is_error":false,"stop_reason":"end_turn","session_id":"no-think-1","usage":{"input_tokens":1,"output_tokens":1}}"#, - ]; - #[cfg(windows)] - { - let mut body = String::from( - "@echo off\r\necho x>>\"%~dp0starts.txt\"\r\n\ - echo %* | findstr /C:\"--thinking-display\" >nul\r\n\ - if not errorlevel 1 (\r\n\ - echo error: unknown option '--thinking-display' 1>&2\r\n\ - exit /b 1\r\n)\r\n", - ); - for line in LINES { - body.push_str(&format!("echo {line}\r\n")); - } - let path = dir.join("old-agent.cmd"); - std::fs::write(&path, body).expect("write the stand-in agent"); - path - } - #[cfg(not(windows))] - { - use std::os::unix::fs::PermissionsExt; - let mut body = String::from( - "#!/bin/sh\necho x >> \"$(dirname \"$0\")/starts.txt\"\n\ - case \"$*\" in *--thinking-display*) \ - echo \"error: unknown option '--thinking-display'\" >&2; exit 1;; esac\n", - ); - for line in LINES { - body.push_str(&format!("echo '{line}'\n")); - } - let path = dir.join("old-agent.sh"); - std::fs::write(&path, body).expect("write the stand-in agent"); - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) - .expect("make it runnable"); - path - } - } - - /// **A CLI THAT DROPS THE UNDOCUMENTED THINKING FLAG DOES NOT BREAK EVERY - /// TURN.** The first refusal is recognised, the turn runs again without - /// the flag, and the backend remembers: the next turn starts once. - #[test] - fn a_refused_thinking_flag_is_dropped_once_and_remembered() { - let dir = tempfile::tempdir().expect("scratch"); - let fake = a_cli_without_the_thinking_flag(dir.path()); - let starts = dir.path().join("starts.txt"); - let count = || { - std::fs::read_to_string(&starts) - .map(|s| s.lines().count()) - .unwrap_or(0) - }; - let mut backend = ClaudeCodeBackend::new(dir.path().to_path_buf()) - .with_binary(fake.to_string_lossy()) - .streaming(true); - - let mut said = Vec::new(); - let first = backend - .run_turn("hi", &mut |e| { - if let AgentEvent::Text(t) = e { - said.push(t.clone()); - } - }) - .expect("the turn is run again without the flag"); - assert!(!first.is_error, "{first:?}"); - assert_eq!(said, ["still here"], "{said:?}"); - assert_eq!(count(), 2, "one refused start, one without the flag"); - - backend.run_turn("again", &mut |_| {}).expect("second turn"); - assert_eq!(count(), 3, "the refusal is remembered: one start this turn"); - } - - /// Only a refusal that names the flag counts; any other failure is left - /// as it was. - #[test] - fn only_a_refusal_naming_the_thinking_flag_is_recognised() { - assert!(rejects_thinking_display( - "agent exited with 1 before producing a result: error: unknown option \ - '--thinking-display'" - )); - assert!(!rejects_thinking_display( - "error: unknown option '--fallback-model'" - )); - assert!(!rejects_thinking_display( - "the --thinking-display summary was empty" - )); - } - - /// A stand-in for the agent CLI, for tests elsewhere in the crate: it prints - /// a short stream-json turn — a summarized thinking delta, the reply - /// `three files`, the result — and ignores its argv and stdin. With `waits` - /// it pauses half a minute after the session starts, so a test can stop it. - pub(crate) fn stand_in_cli(dir: &std::path::Path, waits: bool) -> PathBuf { - const LINES: [&str; 5] = [ - r#"{"type":"system","subtype":"init","session_id":"sub-conv-1","model":"fake-sub-model"}"#, - r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"looking around"}},"parent_tool_use_id":null}"#, - r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"three files"}},"parent_tool_use_id":null}"#, - r#"{"type":"assistant","message":{"content":[{"type":"text","text":"three files"}]},"parent_tool_use_id":null}"#, - r#"{"type":"result","is_error":false,"stop_reason":"end_turn","session_id":"sub-conv-1","usage":{"input_tokens":1,"output_tokens":1}}"#, - ]; - #[cfg(windows)] - { - let mut body = format!("@echo off\r\necho {}\r\n", LINES[0]); - if waits { - body.push_str("ping -n 30 127.0.0.1 >nul\r\n"); - } - for line in &LINES[1..] { - body.push_str(&format!("echo {line}\r\n")); - } - let path = dir.join(if waits { "slow-agent.cmd" } else { "agent.cmd" }); - std::fs::write(&path, body).expect("write the stand-in agent"); - path - } - #[cfg(not(windows))] - { - use std::os::unix::fs::PermissionsExt; - let mut body = format!("#!/bin/sh\necho '{}'\n", LINES[0]); - if waits { - body.push_str("sleep 30\n"); - } - for line in &LINES[1..] { - body.push_str(&format!("echo '{line}'\n")); - } - let path = dir.join(if waits { "slow-agent.sh" } else { "agent.sh" }); - std::fs::write(&path, body).expect("write the stand-in agent"); - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) - .expect("make it runnable"); - path - } - } - - // ----------------------------------------------------------------------- - // Pinned behaviour: every wire shape `map_line` reads, the exact argv and - // environment a turn is started with, and what a whole turn reports. - // ----------------------------------------------------------------------- - - /// A turn outcome, spelled out. - fn outcome_of( - session: &str, - stop: &str, - is_error: bool, - detail: Option<&str>, - served_by: &[&str], - ) -> TurnOutcome { - TurnOutcome { - session_id: session.to_string(), - stop_reason: stop.to_string(), - is_error, - detail: detail.map(str::to_string), - served_by: served_by.iter().map(|m| (*m).to_string()).collect(), - } - } - - fn usage_of(input: u32, output: u32, creation: u32, read: u32) -> AgentEvent { - AgentEvent::Usage { - input_tokens: input, - output_tokens: output, - cache_creation_tokens: creation, - cache_read_tokens: read, - } - } - - /// **EVERY WIRE SHAPE, AND WHAT IT BECOMES.** One line per branch of the - /// mapping — each event type, the subagent and empty cases, every way a - /// failed result can describe itself, and lines that do not parse. - #[test] - fn the_map_line_corpus_is_pinned() { - let text = |t: &str| AgentEvent::Text(t.to_string()); - let started = |s: &str, m: &str| AgentEvent::SessionStarted { - session_id: s.to_string(), - model: m.to_string(), - }; - let none: Vec = Vec::new(); - let cases: Vec<(&str, Vec, Option)> = vec![ - // system - ( - r#"{"type":"system","subtype":"init","session_id":"s1","model":"m1"}"#, - vec![started("s1", "m1")], - None, - ), - ( - r#"{"type":"system","subtype":"init"}"#, - vec![started("", "unknown")], - None, - ), - ( - r#" {"type":"system","subtype":"init","session_id":"s2"} "#, - vec![started("s2", "unknown")], - None, - ), - ( - r#"{"type":"system","subtype":"hook_started","hook_id":"h"}"#, - none.clone(), - None, - ), - (r#"{"type":"system"}"#, none.clone(), None), - // stream_event - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hi"}},"parent_tool_use_id":null}"#, - vec![AgentEvent::TextDelta("hi".to_string())], - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":""}}}"#, - none.clone(), - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta"}}}"#, - none.clone(), - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"why"}}}"#, - vec![AgentEvent::Thinking("why".to_string())], - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":""}}}"#, - none.clone(), - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"x"}},"parent_tool_use_id":"toolu_9"}"#, - none.clone(), - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"x"}},"parent_tool_use_id":"toolu_9"}"#, - none.clone(), - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0},"parent_tool_use_id":null}"#, - none.clone(), - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"input_json_delta","partial_json":"{}"}}}"#, - none.clone(), - None, - ), - ( - r#"{"type":"stream_event","event":{"type":"content_block_start","delta":{"type":"text_delta","text":"x"}}}"#, - none.clone(), - None, - ), - (r#"{"type":"stream_event"}"#, none.clone(), None), - // assistant - ( - r#"{"type":"assistant","message":{"content":[{"type":"text","text":"a"},{"type":"tool_use","id":"t1","name":"Write","input":{}},{"type":"thinking","thinking":"hm"},{"type":"text","text":"b"}]},"parent_tool_use_id":null}"#, - vec![text("a"), text("b")], - None, - ), - ( - r#"{"type":"assistant","message":{"content":[{"type":"text","text":""}]}}"#, - vec![text("")], - None, - ), - (r#"{"type":"assistant","message":{}}"#, none.clone(), None), - ( - r#"{"type":"assistant","message":{"content":[{"type":"text","text":"sub"}]},"parent_tool_use_id":"toolu_2"}"#, - none.clone(), - None, - ), - (r#"{"type":"assistant"}"#, none.clone(), None), - // user lines carry tool results incode already showed - ( - r#"{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"t1","content":"ok"}]}}"#, - none.clone(), - None, - ), - // rate_limit_event - ( - r#"{"type":"rate_limit_event","rate_limit_info":{"status":"rejected"}}"#, - vec![AgentEvent::Quota { - status: "rejected".to_string(), - kind: String::new(), - resets_at: 0, - using_overage: false, - }], - None, - ), - ( - r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning","resetsAt":17,"rateLimitType":"seven_day","isUsingOverage":true}}"#, - vec![AgentEvent::Quota { - status: "allowed_warning".to_string(), - kind: "seven_day".to_string(), - resets_at: 17, - using_overage: true, - }], - None, - ), - (r#"{"type":"rate_limit_event"}"#, none.clone(), None), - // result - ( - r#"{"type":"result","is_error":false,"session_id":"r1"}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of("r1", "unknown", false, None, &[])), - ), - ( - r#"{"type":"result","is_error":false,"session_id":"r1","stop_reason":"max_tokens","result":"the reply","subtype":"success","usage":{"input_tokens":3,"output_tokens":4,"cache_creation_input_tokens":5,"cache_read_input_tokens":6}}"#, - vec![usage_of(3, 4, 5, 6)], - Some(outcome_of("r1", "max_tokens", false, None, &[])), - ), - ( - r#"{"type":"result","is_error":true,"session_id":"r2","stop_reason":"stop_sequence","subtype":"error_x","result":"said"}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of( - "r2", - "stop_sequence", - true, - Some("error_x: said"), - &[], - )), - ), - ( - r#"{"type":"result","is_error":true,"session_id":"r2","subtype":"error_max_turns"}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of( - "r2", - "unknown", - true, - Some("error_max_turns"), - &[], - )), - ), - ( - r#"{"type":"result","is_error":true,"session_id":"r2","result":"boom"}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of("r2", "unknown", true, Some("boom"), &[])), - ), - ( - r#"{"type":"result","is_error":true,"session_id":"r2"}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of("r2", "unknown", true, None, &[])), - ), - ( - r#"{"type":"result","is_error":true,"session_id":"r2","subtype":" ","result":" "}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of("r2", "unknown", true, None, &[])), - ), - ( - r#"{"type":"result","is_error":true,"session_id":"r2","subtype":" k ","result":" t "}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of("r2", "unknown", true, Some("k: t"), &[])), - ), - ( - r#"{"type":"result","is_error":false,"session_id":"r3","usage":{"input_tokens":1,"iterations":[{"input_tokens":9},{"input_tokens":10,"output_tokens":5,"cache_read_input_tokens":100,"cache_creation_input_tokens":20}]},"modelUsage":{"b-model":{"inputTokens":50,"contextWindow":200000},"a-model":{"inputTokens":1,"contextWindow":1000}}}"#, - vec![ - usage_of(1, 0, 0, 0), - AgentEvent::Context { - used: 135, - size: 200_000, - }, - ], - Some(outcome_of( - "r3", - "unknown", - false, - None, - &["a-model", "b-model"], - )), - ), - ( - r#"{"type":"result","is_error":false,"session_id":"r4","usage":{"iterations":[]},"modelUsage":{"m":{"contextWindow":200000}}}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of("r4", "unknown", false, None, &["m"])), - ), - ( - r#"{"type":"result","is_error":false,"session_id":"r5","usage":{"iterations":[{"input_tokens":1}]},"modelUsage":{"m":{"contextWindow":0}}}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of("r5", "unknown", false, None, &["m"])), - ), - ( - r#"{"type":"result","is_error":false,"session_id":"r6","usage":{"iterations":[{"input_tokens":1}]},"modelUsage":{"m":{"inputTokens":1}}}"#, - vec![usage_of(0, 0, 0, 0)], - Some(outcome_of("r6", "unknown", false, None, &["m"])), - ), - (r#"{"type":"result","is_error":false}"#, none.clone(), None), - (r#"{"type":"result","session_id":"r7"}"#, none.clone(), None), - // unknown and malformed - ( - r#"{"type":"some_future_event","payload":{}}"#, - none.clone(), - None, - ), - ("not json", none.clone(), None), - ("", none.clone(), None), - ("[]", none.clone(), None), - ("null", none.clone(), None), - ("{}", none.clone(), None), - (r#"{"type":42}"#, none.clone(), None), - ( - r#"{"type":"assistant","message":{"content":[{"type":"text"}]}}"#, - none, - None, - ), - ]; - for (line, events, outcome) in cases { - let mut got = None; - assert_eq!(map_line(line, &mut got), events, "events of {line}"); - assert_eq!(got, outcome, "outcome of {line}"); - } - } - - /// Only a result line touches the outcome; every other line leaves an - /// earlier one in place. - #[test] - fn only_a_result_line_writes_the_outcome() { - let earlier = outcome_of("before", "end_turn", false, None, &[]); - for line in [ - r#"{"type":"system","subtype":"init","session_id":"s"}"#, - r#"{"type":"assistant","message":{"content":[{"type":"text","text":"a"}]}}"#, - r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed"}}"#, - "not json", - ] { - let mut outcome = Some(earlier.clone()); - map_line(line, &mut outcome); - assert_eq!(outcome.as_ref(), Some(&earlier), "{line}"); - } - } - - /// The environment a command sets or removes, minus the entries that - /// depend on the machine: the profile choice, and the session variables - /// removed only when this process inherited them. - fn pinned_envs(cmd: &Command) -> Vec<(String, Option)> { - let mut envs: Vec<(String, Option)> = cmd - .get_envs() - .map(|(k, v)| { - ( - k.to_string_lossy().into_owned(), - v.map(|v| v.to_string_lossy().into_owned()), - ) - }) - .filter(|(k, _)| { - let upper = k.to_ascii_uppercase(); - upper != PROFILE_ENV - && upper != "SESSION_INGRESS_URL" - && !upper.starts_with("CLAUDE_CODE_SESSION") - && !upper.starts_with("CLAUDE_CODE_REMOTE") - }) - .collect(); - envs.sort(); - envs - } - - /// The environment every turn's command carries, sorted. - fn turn_envs() -> Vec<(String, Option)> { - let mut envs: Vec<(String, Option)> = [ - "CLAUDECODE", - "CLAUDE_CODE_ENTRYPOINT", - "CLAUDE_CODE_CHILD_SESSION", - "CLAUDE_CODE_MESSAGING_SOCKET", - "CLAUDE_CODE_MESSAGING_TOKEN", - "CLAUDE_SESSION_INGRESS_TOKEN_FILE", - ] - .into_iter() - .map(|k| (k.to_string(), None)) - .chain([ - ( - "CLAUDE_CODE_DISABLE_CLAUDE_MDS".to_string(), - Some("1".to_string()), - ), - ( - "CLAUDE_CODE_DISABLE_AUTO_MEMORY".to_string(), - Some("1".to_string()), - ), - ]) - .collect(); - envs.sort(); - envs - } - - fn strings(items: &[&str]) -> Vec { - items.iter().map(|s| (*s).to_string()).collect() - } - - /// **THE EXACT ARGV AND ENVIRONMENT, FOR A PLAIN TURN.** Guards, a - /// permission mode and extra roots change nothing on the command line: - /// the toolbox enforces them. - #[test] - fn a_plain_turn_is_started_with_exactly_this_command() { - let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")) - .with_guards(&crate::guards::Guards::default()) - .with_extra_dirs(vec![PathBuf::from("other-root")]); - backend.set_permission_mode("acceptEdits"); - let allowed = strings(&["mcp__incode"]); - let cmd = backend.command(Some("hi"), "", "SERVERS", &allowed); - assert_eq!(cmd.get_program(), "claude"); - assert_eq!( - args_of(&cmd), - strings(&[ - "-p", - "hi", - "--output-format", - "stream-json", - "--tools", - "", - "--strict-mcp-config", - "--setting-sources", - "", - "--disable-slash-commands", - "--verbose", - "--mcp-config", - "SERVERS", - "--allowedTools", - "mcp__incode", - ]) - ); - assert_eq!(pinned_envs(&cmd), turn_envs()); - assert_eq!(cmd.get_current_dir(), None); - } - - /// **THE EXACT ARGV FOR A TURN WITH EVERYTHING SET**: pictures (prompt on - /// stdin), a model chain, streaming, context and a session to resume. - #[test] - fn a_fully_configured_turn_is_started_with_exactly_this_command() { - let backend = ClaudeCodeBackend::new(PathBuf::from(".")) - .with_binary("/opt/agent/claude") - .with_models(&strings(&["opus", "sonnet", "haiku"])) - .with_session("s-9") - .streaming(true); - let allowed = strings(&["a", "b"]); - let cmd = backend.command(None, "CTX", "SERVERS", &allowed); - assert_eq!(cmd.get_program(), "/opt/agent/claude"); - assert_eq!( - args_of(&cmd), - strings(&[ - "-p", - "--input-format", - "stream-json", - "--output-format", - "stream-json", - "--tools", - "", - "--strict-mcp-config", - "--setting-sources", - "", - "--disable-slash-commands", - "--verbose", - "--mcp-config", - "SERVERS", - "--allowedTools", - "a", - "b", - "--model", - "opus", - "--include-partial-messages", - "--thinking-display", - "summarized", - "--append-system-prompt", - "CTX", - "--fallback-model", - "sonnet,haiku", - "--resume", - "s-9", - ]) - ); - assert_eq!(pinned_envs(&cmd), turn_envs()); - } - - /// Once the CLI has refused the thinking flag, a streaming turn is - /// started without it — and nothing else changes. - #[test] - fn a_turn_after_the_thinking_flag_was_refused_omits_only_that_flag() { - let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")).streaming(true); - backend.thinking_display = false; - let cmd = backend.command(Some("q"), "", "S", &[]); - assert_eq!( - args_of(&cmd), - strings(&[ - "-p", - "q", - "--output-format", - "stream-json", - "--tools", - "", - "--strict-mcp-config", - "--setting-sources", - "", - "--disable-slash-commands", - "--verbose", - "--mcp-config", - "S", - "--allowedTools", - "--include-partial-messages", - ]) - ); - } - - /// The stdin message for a turn with no pictures, byte for byte. - #[test] - fn the_stdin_message_is_pinned() { - assert_eq!( - user_message("hi", &[]), - "{\"type\":\"user\",\"message\":{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"hi\"}]}}\n" - ); - } - - /// **A WHOLE TURN THROUGH `run_turn`**: the events in order, the outcome, - /// and the session kept for the next turn. - #[test] - fn a_whole_turn_reports_these_events_and_this_outcome() { - let dir = tempfile::tempdir().expect("scratch"); - let fake = stand_in_cli(dir.path(), false); - let mut backend = - ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); - let mut seen = Vec::new(); - let outcome = backend - .run_turn("hi", &mut |e| seen.push(e.clone())) - .expect("the stand-in finishes its turn"); - assert_eq!( - seen, - vec![ - AgentEvent::SessionStarted { - session_id: "sub-conv-1".to_string(), - model: "fake-sub-model".to_string(), - }, - AgentEvent::Thinking("looking around".to_string()), - AgentEvent::TextDelta("three files".to_string()), - AgentEvent::Text("three files".to_string()), - usage_of(1, 1, 0, 0), - ] - ); - assert_eq!( - outcome, - outcome_of("sub-conv-1", "end_turn", false, None, &[]) - ); - assert_eq!(backend.session_id(), Some("sub-conv-1")); - } - - /// A CLI that cannot be started names itself in the error. - #[test] - fn a_cli_that_cannot_start_is_named_in_the_error() { - let dir = tempfile::tempdir().expect("scratch"); - let missing = dir.path().join("no-such-agent-binary"); - let mut backend = - ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(missing.to_string_lossy()); - let err = backend - .run_turn("hi", &mut |_| {}) - .expect_err("nothing to start"); - assert!( - err.to_string() - .starts_with(&format!("failed to spawn `{}`: ", missing.display())), - "{err}" - ); - } - - /// A stand-in that starts a session and exits cleanly, saying nothing - /// else and writing nothing to stderr. - fn a_cli_that_ends_without_a_result(dir: &std::path::Path) -> PathBuf { - const INIT: &str = r#"{"type":"system","subtype":"init","session_id":"cut-1","model":"m"}"#; - #[cfg(windows)] - { - let path = dir.join("cut-agent.cmd"); - std::fs::write(&path, format!("@echo off\r\necho {INIT}\r\nexit /b 0\r\n")) - .expect("write the stand-in agent"); - path - } - #[cfg(not(windows))] - { - use std::os::unix::fs::PermissionsExt; - let path = dir.join("cut-agent.sh"); - std::fs::write(&path, format!("#!/bin/sh\necho '{INIT}'\nexit 0\n")) - .expect("write the stand-in agent"); - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) - .expect("make it runnable"); - path - } - } - - /// No result line: the exact error, and the session still kept. - #[test] - fn a_turn_without_a_result_fails_with_this_error_and_keeps_its_session() { - let dir = tempfile::tempdir().expect("scratch"); - let fake = a_cli_that_ends_without_a_result(dir.path()); - let mut backend = - ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); - let err = backend - .run_turn("hi", &mut |_| {}) - .expect_err("no result line"); - assert_eq!( - err.to_string(), - "agent exited with 0 before producing a result: " - ); - assert_eq!(backend.session_id(), Some("cut-1")); - } -} diff --git a/src/agent/claude_code/command.rs b/src/agent/claude_code/command.rs new file mode 100644 index 0000000..f7cac50 --- /dev/null +++ b/src/agent/claude_code/command.rs @@ -0,0 +1,181 @@ +//! The command one turn of the CLI is started with: the flags that make it a +//! model and nothing else, the one MCP server it is handed, and the stdin +//! message that carries a turn's pictures. + +use std::process::Command; + +use super::profiles::{usable_profile, PROFILE_ENV}; +use super::ClaudeCodeBackend; + +/// The flag that asks the CLI for a readable summary of the model's +/// thinking. Undocumented; see [`rejects_thinking_display`]. +pub(super) const THINKING_DISPLAY_FLAG: &str = "--thinking-display"; + +/// Whether a failed start is the CLI refusing [`THINKING_DISPLAY_FLAG`]: +/// its option parser names the flag with "unknown option" (or a close +/// spelling) and exits before any output. +pub(super) fn rejects_thinking_display(failure: &str) -> bool { + let said = failure.to_ascii_lowercase(); + said.contains("thinking-display") + && ["unknown option", "unknown argument", "unrecognized option"] + .iter() + .any(|phrase| said.contains(phrase)) +} + +impl ClaudeCodeBackend { + /// The CLI's command for one turn, as a model and nothing else, with + /// `servers` as its only MCP servers and `allowed` the tool names it may + /// send without asking. The bridge's address and token are added by the + /// caller, which holds the bridge. + /// + /// `prompt` is `None` for a turn carrying pictures, whose prompt goes on + /// stdin instead, as one stream-json user message ([`user_message`]): `-p` + /// with no prompt and `--input-format stream-json`. Measured on 2.1.283: a + /// message with a base64 PNG block was described correctly, and the CLI + /// ended when stdin closed. + pub(super) fn command( + &self, + prompt: Option<&str>, + context: &str, + servers: &str, + allowed: &[String], + ) -> Command { + let mut cmd = Command::new(&self.binary); + crate::agent::parent_session::detach_from_parent_session(&mut cmd); + cmd.arg("-p"); + match prompt { + Some(prompt) => { + cmd.arg(prompt); + } + None => { + cmd.arg("--input-format").arg("stream-json"); + } + } + cmd.arg("--output-format") + .arg("stream-json") + .args(MODEL_ONLY_FLAGS) + .arg("--mcp-config") + .arg(servers) + .arg("--allowedTools") + .args(allowed); + for (key, value) in MODEL_ONLY_ENV { + cmd.env(key, value); + } + + // Which model serves this turn. Absent, the CLI uses its own default, + // which is the right behaviour for a caller with no opinion. + if let Some(model) = &self.model { + cmd.arg("--model").arg(model); + } + if self.partial_messages { + cmd.arg("--include-partial-messages"); + // The model's reasoning as text a person can read, streamed as + // `thinking_delta`s. Not in `--help` on 2.1.283 (it is in the + // CLI's option table, choices summarized / omitted / highlights); + // measured: without it every thinking delta arrived EMPTY, with it + // the summary arrived word by word, beside an unchanged reply. + // Left off once this CLI has refused it (`thinking_display`). + if self.thinking_display { + cmd.arg(THINKING_DISPLAY_FLAG).arg("summarized"); + } + } + if !context.is_empty() { + cmd.arg("--append-system-prompt").arg(context); + } + if !self.fallbacks.is_empty() { + // One comma-separated list, tried in order — the CLI's own shape for + // the ordered chain the role table produces. + cmd.arg("--fallback-model").arg(self.fallbacks.join(",")); + } + + // Continue the existing session rather than starting a new one. A fresh + // session re-pays the entire prompt prefix; resuming does not. + if let Some(sid) = &self.session_id { + cmd.arg("--resume").arg(sid); + } + + // Point the agent at a profile whose session is actually live. + // + // Skipped entirely when the operator has already said which profile to + // use: an explicit choice is a decision, and silently overriding it + // would be worse than the fallback this replaces. + if std::env::var_os(PROFILE_ENV).is_none() { + if let Some(profile) = usable_profile() { + cmd.env(PROFILE_ENV, &profile.dir); + } + } + + // No team server identity here: on this route the team channel's + // tools are incode's own (`toolbox::team`), and who they speak as is + // set on the toolbox by `set_team_identity`. + cmd + } +} + +/// One stream-json user message: the prompt as a text block, then each +/// picture as a base64 image block — the shape the CLI reads on stdin with +/// `--input-format stream-json`, one message per line. +pub(super) fn user_message(prompt: &str, images: &[crate::toolbox::Image]) -> String { + let mut content = vec![serde_json::json!({"type": "text", "text": prompt})]; + content.extend(images.iter().map(crate::agent::api::image_block)); + let message = serde_json::json!({ + "type": "user", + "message": {"role": "user", "content": content}, + }); + format!("{message}\n") +} + +/// The flags that make the CLI a model and nothing else. Each was proved on +/// the installed CLI before it was relied on — see `docs/ARCHITECTURE.md`, +/// "Models only: incode runs every tool". +/// +/// - `--tools ""`: none of its built-in tools. Its session then lists only the +/// MCP tools incode hands it. +/// - `--strict-mcp-config`: only the servers in `--mcp-config`, so nothing the +/// operator configured for the CLI is reachable. +/// - `--setting-sources ""`: no user, project or local settings — and with +/// them none of their hooks, permission rules or default mode. Measured: +/// thirteen hook events on a control run, none with this flag. +/// - `--disable-slash-commands`: no skills of its own. +/// +/// `--bare` would do most of this in one flag, and cannot be used: it reads +/// only an API key, and a subscription login answers "Not logged in". +const MODEL_ONLY_FLAGS: [&str; 7] = [ + "--tools", + "", + "--strict-mcp-config", + "--setting-sources", + "", + "--disable-slash-commands", + "--verbose", +]; + +/// Environment that keeps the CLI's own memory out: no `CLAUDE.md` files and +/// no auto-memory. Measured: a project canary in `CLAUDE.md` was repeated by a +/// control run and unknown to a run with these set. +pub(super) const MODEL_ONLY_ENV: [(&str, &str); 2] = [ + ("CLAUDE_CODE_DISABLE_CLAUDE_MDS", "1"), + ("CLAUDE_CODE_DISABLE_AUTO_MEMORY", "1"), +]; + +/// The one MCP server the CLI gets: the tool bridge — as an `--mcp-config` +/// document, and the tool names its calls may use without the CLI asking +/// anyone. The team channel and the desktop are toolbox tools reached +/// through it, so no server of their own is handed over. +/// +/// `--strict-mcp-config` goes with it: the CLI loads ONLY what incode hands +/// it. Memory is reached through incode's own tools, not through a server +/// the operator happened to configure for the CLI. +pub(super) fn servers_for(exe: &std::path::Path) -> (String, Vec) { + let mut servers = serde_json::Map::new(); + servers.insert( + crate::tool_bridge::CLIENT_KEY.to_string(), + crate::tool_bridge::client_entry(exe), + ); + // Allowed by server, not by tool: the CLI would otherwise refuse each call + // for want of a person to ask. Whether a call may run is decided by incode + // when it arrives, not by the CLI before it is sent. + let allowed = servers.keys().map(|key| format!("mcp__{key}")).collect(); + let config = serde_json::json!({ "mcpServers": servers }).to_string(); + (config, allowed) +} diff --git a/src/agent/claude_code/command_tests.rs b/src/agent/claude_code/command_tests.rs new file mode 100644 index 0000000..6094422 --- /dev/null +++ b/src/agent/claude_code/command_tests.rs @@ -0,0 +1,411 @@ +//! Models only: the CLI's tools off, incode's toolbox on — the argv and +//! environment a turn is started with, the one server it is handed, and the +//! deny rules rendered in this agent's syntax. + +use std::process::Command; + +use super::command::{servers_for, user_message, MODEL_ONLY_ENV}; +use super::deny::{render_denials, SUBAGENT_TOOL}; +use super::profiles::PROFILE_ENV; +use super::*; + +fn args_of(cmd: &Command) -> Vec { + cmd.get_args() + .map(|a| a.to_string_lossy().into_owned()) + .collect() +} + +fn value_after(args: &[String], flag: &str) -> Option { + let at = args.iter().position(|a| a == flag)?; + args.get(at + 1).cloned() +} + +/// **THE CLI IS STARTED AS A MODEL AND NOTHING ELSE**: no tools of its +/// own, only incode's servers, none of its settings — and none of the +/// harness flags it used to be handed, because it has nothing left for +/// them to govern. +#[test] +fn the_cli_is_started_with_its_own_harness_switched_off() { + let mut backend = + ClaudeCodeBackend::new(PathBuf::from(".")).with_guards(&crate::guards::Guards::default()); + backend.set_permission_mode("plan"); + assert!( + !backend.deny_rules().is_empty(), + "control: there are deny rules that could leak onto the argv" + ); + let (servers, allowed) = servers_for(std::path::Path::new("incode")); + let cmd = backend.command(Some("hi"), "", &servers, &allowed); + let args = args_of(&cmd); + + assert_eq!( + value_after(&args, "--tools").as_deref(), + Some(""), + "{args:?}" + ); + assert_eq!( + value_after(&args, "--setting-sources").as_deref(), + Some(""), + "{args:?}" + ); + assert!(args.iter().any(|a| a == "--strict-mcp-config"), "{args:?}"); + assert!( + args.iter().any(|a| a == "--disable-slash-commands"), + "{args:?}" + ); + assert_eq!( + value_after(&args, "--allowedTools").as_deref(), + Some("mcp__incode") + ); + for gone in [ + "--permission-mode", + "--disallowedTools", + "--add-dir", + "--dangerously-skip-permissions", + "--bare", + ] { + assert!( + !args.iter().any(|a| a == gone), + "{gone} reached the CLI: {args:?}" + ); + } + let envs: Vec<(String, String)> = cmd + .get_envs() + .filter_map(|(k, v)| { + Some(( + k.to_string_lossy().into_owned(), + v?.to_string_lossy().into_owned(), + )) + }) + .collect(); + for (key, value) in MODEL_ONLY_ENV { + assert!( + envs.iter().any(|(k, v)| k == key && v == value), + "{key} is not set: {envs:?}" + ); + } +} + +/// **A TURN IS ITS OWN SESSION, NEVER THE ONE INCODE WAS LAUNCHED FROM.** +/// Issue #3: run from inside another session, every turn reported that +/// session's id as its own. +#[test] +fn the_cli_never_joins_the_session_that_launched_incode() { + let backend = ClaudeCodeBackend::new(PathBuf::from(".")); + let (servers, allowed) = servers_for(std::path::Path::new("incode")); + for prompt in [Some("hi"), None] { + let cmd = backend.command(prompt, "", &servers, &allowed); + assert!( + cmd.get_envs() + .any(|(k, v)| k == "CLAUDECODE" && v.is_none()), + "CLAUDECODE is inherited, so the turn joins the parent's session" + ); + } +} + +/// **THE DESKTOP IS THE TOOLBOX'S, NOT A SERVER BESIDE THE BRIDGE.** With +/// the desktop switched on, the model's tool list (the toolbox's) holds +/// the desktop tools, and the CLI is handed the bridge and nothing else. +#[test] +fn the_bridge_is_the_only_server_and_the_desktop_is_the_toolboxs() { + let off = ClaudeCodeBackend::new(PathBuf::from(".")); + assert!( + !off.tools.names().iter().any(|n| n == "screenshot"), + "a desktop nobody switched on" + ); + let on = + ClaudeCodeBackend::new(PathBuf::from(".")).with_desktop(crate::toolbox::DesktopSetup { + exe: PathBuf::from("incode"), + journal: PathBuf::from(".incode/desktop.jsonl"), + }); + let names = on.tools.names(); + for tool in ["screenshot", "screen_info", "ui_tree", "click", "type_text"] { + assert!(names.iter().any(|n| n == tool), "{tool} missing: {names:?}"); + } + let (servers, allowed) = servers_for(std::path::Path::new("incode")); + let parsed: serde_json::Value = serde_json::from_str(&servers).expect("json"); + let keys: Vec<&String> = parsed["mcpServers"] + .as_object() + .expect("servers") + .keys() + .collect(); + assert_eq!(keys, [crate::tool_bridge::CLIENT_KEY], "{servers}"); + assert_eq!( + parsed["mcpServers"][crate::tool_bridge::CLIENT_KEY]["args"][0], + crate::tool_bridge::SERVER_FLAG + ); + assert_eq!(allowed, ["mcp__incode".to_string()]); +} + +/// **A TURN WITH PICTURES GIVES ITS PROMPT ON STDIN**, as the stream-json +/// message the CLI was measured reading: no prompt on the argv, the input +/// format named, and the message holding the text then each picture as a +/// base64 image block. Thinking is asked for as a readable summary when +/// partial messages are on. +#[test] +fn a_turn_with_pictures_sends_its_prompt_as_a_stream_json_message() { + let backend = ClaudeCodeBackend::new(PathBuf::from(".")).streaming(true); + let (servers, allowed) = servers_for(std::path::Path::new("incode")); + let args = args_of(&backend.command(None, "", &servers, &allowed)); + assert_eq!(value_after(&args, "-p").as_deref(), Some("--input-format")); + assert_eq!( + value_after(&args, "--input-format").as_deref(), + Some("stream-json") + ); + assert_eq!( + value_after(&args, "--thinking-display").as_deref(), + Some("summarized") + ); + let plain = args_of(&backend.command(Some("hi"), "", &servers, &allowed)); + assert_eq!(value_after(&plain, "-p").as_deref(), Some("hi")); + assert!(!plain.iter().any(|a| a == "--input-format"), "{plain:?}"); + + let picture = crate::toolbox::Image::from_base64( + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC", + ) + .expect("a 1x1 png"); + let line = user_message("what is this", std::slice::from_ref(&picture)); + assert!(line.ends_with('\n')); + let message: serde_json::Value = serde_json::from_str(line.trim()).expect("json"); + assert_eq!(message["type"], "user"); + let content = &message["message"]["content"]; + assert_eq!( + content[0], + serde_json::json!({"type": "text", "text": "what is this"}) + ); + assert_eq!(content[1]["type"], "image"); + assert_eq!(content[1]["source"]["media_type"], "image/png"); + assert_eq!(content[1]["source"]["data"], picture.base64()); +} + +/// **`Edit`, never `Write`.** Measured: a rule denying only `Write(tests/**)` +/// let the file through, and this CLI reports that only `Edit(path)` rules +/// are matched by file permission checks. A guard that parses and does +/// nothing is worse than no guard, so the tool name is pinned. +/// +/// This test lives HERE, beside the renderer, because it is a fact about one +/// agent's permission layer rather than about the harness's policy. +#[test] +fn the_rendered_rules_use_the_tool_name_that_actually_binds() { + let rules = render_denials(&crate::guards::restrictions( + &crate::guards::Guards::default(), + )); + assert!(!rules.is_empty(), "the defaults must produce rules"); + for rule in rules.iter().filter(|r| *r != SUBAGENT_TOOL) { + assert!( + rule.starts_with("Edit("), + "`Write(...)` is silently ignored by the permission layer: {rule}" + ); + } +} + +/// The policy's "no sub-agents" becomes THIS agent's word for it. +#[test] +fn refusing_sub_agents_renders_as_this_agents_tool_name() { + let with = crate::guards::Restrictions { + no_write: Vec::new(), + no_subagents: true, + }; + let without = crate::guards::Restrictions { + no_write: Vec::new(), + no_subagents: false, + }; + assert_eq!(render_denials(&with), vec![SUBAGENT_TOOL.to_string()]); + assert!( + render_denials(&without).is_empty(), + "a policy that permits delegation must not deny it anyway" + ); +} + +/// A bare glob from the policy is wrapped, not passed through raw. +/// +/// The policy deliberately carries `**/tests/**` with no syntax around it; +/// handing that to the CLI unwrapped would be accepted and enforce nothing. +#[test] +fn a_bare_policy_glob_is_wrapped_in_this_agents_syntax() { + let rules = render_denials(&crate::guards::Restrictions { + no_write: vec!["**/tests/**".to_string()], + no_subagents: false, + }); + assert_eq!(rules, vec!["Edit(**/tests/**)".to_string()]); +} + +// --------------------------------------------------------------------------- +// Pinned behaviour: the exact argv and environment a turn is started with. +// --------------------------------------------------------------------------- + +/// The environment a command sets or removes, minus the entries that +/// depend on the machine: the profile choice, and the session variables +/// removed only when this process inherited them. +fn pinned_envs(cmd: &Command) -> Vec<(String, Option)> { + let mut envs: Vec<(String, Option)> = cmd + .get_envs() + .map(|(k, v)| { + ( + k.to_string_lossy().into_owned(), + v.map(|v| v.to_string_lossy().into_owned()), + ) + }) + .filter(|(k, _)| { + let upper = k.to_ascii_uppercase(); + upper != PROFILE_ENV + && upper != "SESSION_INGRESS_URL" + && !upper.starts_with("CLAUDE_CODE_SESSION") + && !upper.starts_with("CLAUDE_CODE_REMOTE") + }) + .collect(); + envs.sort(); + envs +} + +/// The environment every turn's command carries, sorted. +fn turn_envs() -> Vec<(String, Option)> { + let mut envs: Vec<(String, Option)> = [ + "CLAUDECODE", + "CLAUDE_CODE_ENTRYPOINT", + "CLAUDE_CODE_CHILD_SESSION", + "CLAUDE_CODE_MESSAGING_SOCKET", + "CLAUDE_CODE_MESSAGING_TOKEN", + "CLAUDE_SESSION_INGRESS_TOKEN_FILE", + ] + .into_iter() + .map(|k| (k.to_string(), None)) + .chain([ + ( + "CLAUDE_CODE_DISABLE_CLAUDE_MDS".to_string(), + Some("1".to_string()), + ), + ( + "CLAUDE_CODE_DISABLE_AUTO_MEMORY".to_string(), + Some("1".to_string()), + ), + ]) + .collect(); + envs.sort(); + envs +} + +fn strings(items: &[&str]) -> Vec { + items.iter().map(|s| (*s).to_string()).collect() +} + +/// **THE EXACT ARGV AND ENVIRONMENT, FOR A PLAIN TURN.** Guards, a +/// permission mode and extra roots change nothing on the command line: +/// the toolbox enforces them. +#[test] +fn a_plain_turn_is_started_with_exactly_this_command() { + let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")) + .with_guards(&crate::guards::Guards::default()) + .with_extra_dirs(vec![PathBuf::from("other-root")]); + backend.set_permission_mode("acceptEdits"); + let allowed = strings(&["mcp__incode"]); + let cmd = backend.command(Some("hi"), "", "SERVERS", &allowed); + assert_eq!(cmd.get_program(), "claude"); + assert_eq!( + args_of(&cmd), + strings(&[ + "-p", + "hi", + "--output-format", + "stream-json", + "--tools", + "", + "--strict-mcp-config", + "--setting-sources", + "", + "--disable-slash-commands", + "--verbose", + "--mcp-config", + "SERVERS", + "--allowedTools", + "mcp__incode", + ]) + ); + assert_eq!(pinned_envs(&cmd), turn_envs()); + assert_eq!(cmd.get_current_dir(), None); +} + +/// **THE EXACT ARGV FOR A TURN WITH EVERYTHING SET**: pictures (prompt on +/// stdin), a model chain, streaming, context and a session to resume. +#[test] +fn a_fully_configured_turn_is_started_with_exactly_this_command() { + let backend = ClaudeCodeBackend::new(PathBuf::from(".")) + .with_binary("/opt/agent/claude") + .with_models(&strings(&["opus", "sonnet", "haiku"])) + .with_session("s-9") + .streaming(true); + let allowed = strings(&["a", "b"]); + let cmd = backend.command(None, "CTX", "SERVERS", &allowed); + assert_eq!(cmd.get_program(), "/opt/agent/claude"); + assert_eq!( + args_of(&cmd), + strings(&[ + "-p", + "--input-format", + "stream-json", + "--output-format", + "stream-json", + "--tools", + "", + "--strict-mcp-config", + "--setting-sources", + "", + "--disable-slash-commands", + "--verbose", + "--mcp-config", + "SERVERS", + "--allowedTools", + "a", + "b", + "--model", + "opus", + "--include-partial-messages", + "--thinking-display", + "summarized", + "--append-system-prompt", + "CTX", + "--fallback-model", + "sonnet,haiku", + "--resume", + "s-9", + ]) + ); + assert_eq!(pinned_envs(&cmd), turn_envs()); +} + +/// Once the CLI has refused the thinking flag, a streaming turn is +/// started without it — and nothing else changes. +#[test] +fn a_turn_after_the_thinking_flag_was_refused_omits_only_that_flag() { + let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")).streaming(true); + backend.thinking_display = false; + let cmd = backend.command(Some("q"), "", "S", &[]); + assert_eq!( + args_of(&cmd), + strings(&[ + "-p", + "q", + "--output-format", + "stream-json", + "--tools", + "", + "--strict-mcp-config", + "--setting-sources", + "", + "--disable-slash-commands", + "--verbose", + "--mcp-config", + "S", + "--allowedTools", + "--include-partial-messages", + ]) + ); +} + +/// The stdin message for a turn with no pictures, byte for byte. +#[test] +fn the_stdin_message_is_pinned() { + assert_eq!( + user_message("hi", &[]), + "{\"type\":\"user\",\"message\":{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"hi\"}]}}\n" + ); +} diff --git a/src/agent/claude_code/deny.rs b/src/agent/claude_code/deny.rs new file mode 100644 index 0000000..ec76b90 --- /dev/null +++ b/src/agent/claude_code/deny.rs @@ -0,0 +1,42 @@ +//! The harness's restrictions, in this agent's own deny syntax. + +/// What THIS agent calls its sub-agent tool. +/// +/// One backend's name for one capability. [`crate::guards::Restrictions`] says +/// only that sub-agents are refused; the word for it lives here, because the +/// next backend will have a different one — or none. +/// +/// Measured: a turn given this on `--disallowedTools` reports the tool ABSENT +/// rather than merely refused, so the child is never offered a capability it +/// cannot use. +pub(super) const SUBAGENT_TOOL: &str = "Task"; + +/// The harness's restrictions, in this agent's own deny syntax. +/// +/// # `Edit`, never `Write` — measured, not assumed +/// +/// The tool name is `Edit`. A rule written as `Write(tests/**)` is **silently +/// ineffective**: it parses, it is accepted, and the write goes through. That +/// was measured — a probe denying only `Write(tests/**)` created the file +/// anyway, and this CLI reports that only `Edit(path)` rules are matched by +/// file permission checks, `Edit` covering every file-editing tool. +/// +/// A guard that looks right and does nothing is worse than no guard, so the +/// choice is pinned by a test rather than left to whoever edits next. +/// +/// Measured to cover shell redirection too: with `Edit(tests/**)` in force a +/// `printf > tests/x` was denied, and the identical command without it wrote +/// the file. +pub(super) fn render_denials(restrictions: &crate::guards::Restrictions) -> Vec { + let mut rules = Vec::new(); + if restrictions.no_subagents { + rules.push(SUBAGENT_TOOL.to_string()); + } + rules.extend( + restrictions + .no_write + .iter() + .map(|glob| format!("Edit({glob})")), + ); + rules +} diff --git a/src/agent/claude_code/mod.rs b/src/agent/claude_code/mod.rs new file mode 100644 index 0000000..7034bb5 --- /dev/null +++ b/src/agent/claude_code/mod.rs @@ -0,0 +1,566 @@ +//! Claude Code agent backend, driven as a subprocess. +//! +//! There is no Rust binding for the Claude Agent SDK (Python and TypeScript +//! only); the documented path for any other language is to run the CLI with +//! `-p` and a structured `--output-format`. The wire shapes were taken from +//! real runs of CLI 2.1.229, not from documentation. +//! +//! # Layout +//! +//! - this file: the backend, its builders and its [`AgentBackend`] face; +//! - `wire`: the stream-json lines and the events each becomes (`map_line`); +//! - `command`: the argv and environment a turn is started with; +//! - `turn`: one run of the CLI, the tool bridge and the stream loop; +//! - `profiles`: which agent profile a turn is pointed at; +//! - `deny`: the harness's restrictions in this agent's deny syntax. + +use std::path::PathBuf; + +use super::{AgentBackend, AgentError, AgentEvent, TurnOutcome}; + +mod command; +mod deny; +mod profiles; +mod turn; +mod wire; + +use command::{rejects_thinking_display, THINKING_DISPLAY_FLAG}; +pub use profiles::{ + keychain_holds_login, login_outside_profiles, pick_usable, process_env, profiles, profiles_in, + usable_profile, OutsideLogin, Profile, +}; +pub use turn::debug_stream_path; + +/// What a cancelled turn reports, so the caller can tell it apart from a crash. +/// One wording for every bridged CLI — see [`crate::tool_bridge::CANCELLED`]. +pub use crate::tool_bridge::CANCELLED; + +// --------------------------------------------------------------------------- +// Backend +// --------------------------------------------------------------------------- + +/// Drives Claude Code over its non-interactive interface. +pub struct ClaudeCodeBackend { + binary: String, + workspace: PathBuf, + /// Set after the first turn; every later turn resumes it. + session_id: Option, + /// Which model serves the next turn, if the caller has an opinion. + /// + /// **This is what makes role routing work on a subscription.** Verified + /// against the installed CLI: `--model haiku` really is served by the haiku + /// model, confirmed by both the session's own `init.model` and the usage + /// recorded on the result. So cheap work can run cheap without an API key. + model: Option, + /// Models to try when the first is overloaded, in order. + /// + /// The CLI takes these as one comma-separated list, which is exactly the + /// ordered candidate chain the role table already produces. + fallbacks: Vec, + /// What the harness knows and the agent does not, carried on every turn. + /// + /// APPENDED to the agent's own system prompt rather than replacing it: the + /// agent's instructions are what make it good at the work, and this is the + /// project's context riding alongside them — the guard rules in force, what + /// the auditor already found, what the recorder already solved, which roles + /// exist. Replacing would trade a working coder for a briefed one. + system_context: Vec, + /// Directories beyond the workspace this agent may reach. + extra_dirs: Vec, + /// The policy the deny rules were built from. + /// + /// Held so that CHANGING THE ROOTS REBUILDS THE RULES automatically. A + /// separate "now re-derive them" call is a call someone forgets — and this + /// one was: reach was widened to a second root while the rules stayed + /// anchored to the first, and the agent wrote into a protected directory + /// there unstopped. + guards: crate::guards::Guards, + /// Every tool the model has, run HERE. + /// + /// The CLI is started with its own tools switched off and handed only + /// these, through [`crate::tool_bridge`]: each call the model makes comes + /// back to this process and runs through the toolbox's guards, the memory + /// engine's hook, the permission mode and the person to ask — the same + /// path a model over an API takes. + tools: crate::toolbox::Toolbox, + /// How many calls this backend has run, so each gets an id no earlier + /// turn used. + calls: u64, + /// Set when the user asks to stop. + /// + /// The agent runs as a CHILD PROCESS, so stopping it means killing that + /// process — there is no cooperative checkpoint to fall back on. Without + /// this, Ctrl-C during a turn would leave the agent running, still writing + /// files, with nothing reading its output. + cancel: Option, + /// Whether to ask for text as it is generated, not only in whole blocks. + /// + /// Off by default: a caller collecting a REPORT wants whole blocks, and + /// turning this on would make it choose between two copies of the same + /// text. An interactive caller turns it on and reads the deltas. + partial_messages: bool, + /// The protected paths, in the CLI's own deny syntax — REPORTED, no longer + /// handed to the CLI. + /// + /// The CLI has no file tools of its own any more, so a rule in its syntax + /// would bind nothing. The paths are refused by the toolbox instead, before + /// the write (see [`crate::toolbox::Toolbox`]); these stay as the readable + /// statement of what the session protects. + deny: Vec, + /// Pictures for the next turn's prompt only, already inside the image + /// bounds. A turn that carries any is given its prompt on stdin, as a + /// stream-json user message (see [`command::user_message`]). + images: Vec, + /// Whether a turn with partial messages still asks for + /// `--thinking-display summarized`. The flag is not in the CLI's + /// `--help`, so a release may drop it; the first turn that fails with + /// "unknown option" naming it turns this off for the rest of the + /// session, and that turn is run again without it. + thinking_display: bool, +} + +impl ClaudeCodeBackend { + #[must_use] + pub fn new(workspace: PathBuf) -> Self { + // The filtered environment for the shell tool: a command the model + // chose must not inherit this process's credentials. + let mut tools = crate::toolbox::Toolbox::new(&workspace, true); + // The `Agent` tool's sub-agent runs on this same CLI when no model + // endpoint is configured. + tools.run_subagents_on("claude"); + Self { + binary: "claude".to_string(), + tools, + calls: 0, + workspace, + session_id: None, + model: None, + fallbacks: Vec::new(), + partial_messages: false, + system_context: Vec::new(), + extra_dirs: Vec::new(), + guards: crate::guards::Guards::default(), + cancel: None, + deny: Vec::new(), + images: Vec::new(), + thinking_display: true, + } + } + + /// The same backend, one level further down the tree of agents: its + /// toolbox refuses a delegation past the depth limit. + #[must_use] + pub fn at_depth(mut self, depth: u8) -> Self { + self.tools = self.tools.at_depth(depth); + self + } + + /// Let the agent work in directories beyond the workspace. + /// + /// The caller must extend the SENTINEL to the same roots. This method only + /// widens what the agent can touch; widening reach without widening the + /// check is how a protected file stops being protected. + #[must_use] + pub fn with_extra_dirs(mut self, dirs: Vec) -> Self { + self.set_extra_dirs(dirs); + self + } + + /// The same, for a caller that already owns the backend in place. + pub fn set_extra_dirs(&mut self, dirs: Vec) { + // incode's toolbox does the writing on this route, so it is the toolbox + // that must be able to reach the added roots — under the same guards. + self.tools.set_extra_dirs(dirs.clone()); + self.extra_dirs = dirs; + // Reach and guard move together, by construction rather than by anyone + // remembering to call something afterwards. + self.rebuild_deny(); + } + + /// Give the backend the flag that says the user asked to stop. + /// + /// Checked between output lines, so it lands while the agent is talking. + /// A turn that has gone quiet — a long tool call with no output — is not + /// interrupted until it next says something; that limit is real and stated + /// rather than implied. + #[must_use] + pub fn with_cancel(mut self, token: crate::runtime::cancel::CancelToken) -> Self { + self.cancel = Some(token); + self + } + + /// Give the agent the project context this harness assembled. + /// + /// Rides EVERY turn, not just the first: the agent may compact its own + /// conversation, and context that only arrived once would quietly stop + /// applying part-way through a session. + #[must_use] + pub fn with_system_context(mut self, blocks: Vec) -> Self { + self.system_context = blocks + .into_iter() + .filter(|b| !b.trim().is_empty()) + .collect(); + self + } + + /// What the agent is told about this project, beyond the instruction. + #[must_use] + pub fn system_context(&self) -> &[String] { + &self.system_context + } + + /// Ask for text as it is generated, for an interactive caller. + /// + /// The caller then reads [`AgentEvent::TextDelta`] and must IGNORE + /// [`AgentEvent::Text`], which still arrives with the same words in it. + #[must_use] + pub fn streaming(mut self, on: bool) -> Self { + self.partial_messages = on; + self + } + + /// Refuse the agent write access to the operator's protected paths. + /// + /// **Prevention, not detection.** The agent enforces these itself, so the + /// write never happens — where [`crate::guards::Sentinel`] can only notice + /// afterwards. Both are used: they cover different routes and neither is + /// asked to be complete on its own. + #[must_use] + pub fn with_guards(mut self, guards: &crate::guards::Guards) -> Self { + self.guards = guards.clone(); + self.rebuild_deny(); + self + } + + /// Re-derive the deny rules from the policy and the current roots. + /// + /// Called by everything that changes either. A bare glob is matched + /// relative to the working directory, so a root added later needs its own + /// absolute rules. + fn rebuild_deny(&mut self) { + let restrictions = crate::guards::restrictions_for(&self.guards, &self.extra_dirs); + self.deny = deny::render_denials(&restrictions); + } + + /// The deny rules this backend will pass to the agent. + #[must_use] + pub fn deny_rules(&self) -> &[String] { + &self.deny + } + + /// Offer the model the desktop tools, run through incode's toolbox and + /// executed by the desktop child it starts — see `toolbox::desktop`. + /// Off unless a caller asks: handing every run a desktop it did not + /// request would widen what an agent can reach as a side effect of a + /// constructor. + #[must_use] + pub fn with_desktop(mut self, setup: crate::toolbox::DesktopSetup) -> Self { + self.tools.enable_desktop(setup); + self + } + + /// Run the operator's own pre- and post-tool commands around every call + /// this model makes — see [`crate::hooks`]. + #[must_use] + pub fn with_operator_hooks(mut self, hooks: Option) -> Self { + self.tools = self.tools.with_operator_hooks(hooks); + self + } + + /// Confine this model's shell commands to `mode` — see [`crate::sandbox`]. + #[must_use] + pub fn with_sandbox(mut self, policy: crate::sandbox::SandboxPolicy) -> Self { + self.tools = self.tools.with_sandbox(policy); + self + } + + /// Offer the model only `tools`, when given — a user-defined sub-agent's + /// allow-list. A call to any other tool is refused by the toolbox. + #[must_use] + pub fn with_tool_allowlist(mut self, tools: Option>) -> Self { + if let Some(tools) = tools { + self.tools.restrict_tools(tools); + } + self + } + + /// Override the binary (e.g. an absolute path from agent discovery). + #[must_use] + pub fn with_binary(mut self, binary: impl Into) -> Self { + self.binary = binary.into(); + self.tools.run_subagents_on(&self.binary); + self + } + + /// Continue a specific pre-existing session. + #[must_use] + pub fn with_session(mut self, session_id: impl Into) -> Self { + self.session_id = Some(session_id.into()); + self + } + + /// Serve the next turn with a named model, falling back through the rest. + /// + /// **Changing the model abandons the session.** A resumed session carries + /// the earlier turns, and asking a different model to continue them is a + /// request the harness cannot reason about — it would be paying to resume a + /// conversation the new model did not have. Starting fresh costs the prompt + /// prefix once and is the only behaviour that means what it says. + #[must_use] + pub fn with_models(mut self, candidates: &[String]) -> Self { + // One implementation of the rule, not two. A second copy of "changing + // model abandons the session" is a copy that can drift, and a drifted + // safety rule is worse than an absent one. + AgentBackend::set_models(&mut self, candidates); + self + } + + /// Forget the session, so the next turn starts a new one. + pub fn clear_session(&mut self) { + self.session_id = None; + } + + /// How much the model's tool calls may do without asking, as the session + /// spells it (`plan`, `default`, `acceptEdits`). + /// + /// Decided by incode's toolbox, never handed to the CLI: the CLI runs no + /// tools, so a mode given to it would govern nothing. A spelling nobody + /// recognises lands on read-only, like + /// [`crate::permissions::PermissionMode::from_str_lossy`]. + pub fn set_permission_mode(&mut self, mode: &str) { + self.tools + .set_permission_mode(crate::permissions::PermissionMode::from_agent_mode(mode)); + } + + /// Ask the memory engine before every tool call this model makes. + #[must_use] + pub fn with_engine(mut self, engine: Option) -> Self { + self.tools = self.tools.with_engine(engine); + self + } + + /// Announce each file write this model makes to the engine's edit check, + /// and record each read — see `toolbox::code_edits`. + #[must_use] + pub fn with_code_edits(mut self, edits: Option) -> Self { + self.tools = self.tools.with_code_edits(edits); + self + } + + /// Continue an existing agent session on the next turn. + pub fn set_session_id(&mut self, session_id: &str) { + self.session_id = Some(session_id.to_string()); + } + + /// The model the next turn will ask for, if one was chosen. + #[must_use] + pub fn model(&self) -> Option<&str> { + self.model.as_deref() + } + + /// Whether this agent recognises a model id as one it can serve. + /// + /// Recognises Claude families and generic names, and rejects known foreign + /// vendor namespaces (`gemini-`, `gpt-`, `o1/3/4`, `codex-`) so a cross-vendor + /// candidate chain from a shared tier never sends a foreign model to the CLI. + pub fn serves(&self, model: &str) -> bool { + const FOREIGN_PREFIXES: [&str; 7] = + ["gemini-", "gpt-", "o1", "o3", "o4", "chatgpt-", "codex-"]; + let id = model.trim().to_ascii_lowercase(); + if id.is_empty() { + return false; + } + !FOREIGN_PREFIXES.iter().any(|f| id.starts_with(f)) + } +} + +impl AgentBackend for ClaudeCodeBackend { + /// Both halves, by incode's own toolbox: a protected path is refused + /// before the write, and the model has no sub-agent tool but incode's, + /// which stops at its depth limit. + fn enforces(&self) -> crate::guards::Enforcement { + crate::guards::Enforcement::EVERYTHING + } + + fn system_context(&self) -> &[String] { + &self.system_context + } + + fn id(&self) -> &str { + "claude-code" + } + + // The session-shaped methods, forwarded to this backend's own. Fully + // qualified rather than `self.x()`, which would resolve to the inherent + // method and read as though the trait were calling itself. + + fn set_extra_dirs(&mut self, dirs: Vec) { + ClaudeCodeBackend::set_extra_dirs(self, dirs); + } + + /// The team channel's tools are incode's toolbox's on this route, so the + /// toolbox is who speaks. + fn set_team_identity(&mut self, role: &str) { + self.tools.set_team_identity(role); + } + + fn share_session_tools(&mut self, state: std::sync::Arc) { + self.tools.share_session(state); + } + + /// The CLI's own tools are switched off; every call comes back through + /// the bridge to this backend's toolbox. + fn runs_tools_here(&self) -> bool { + true + } + + fn deny_rules(&self) -> &[String] { + ClaudeCodeBackend::deny_rules(self) + } + + fn set_cancel(&mut self, token: crate::runtime::cancel::CancelToken) { + self.tools.set_cancel(token.clone()); + self.cancel = Some(token); + } + + fn set_prompter(&mut self, prompter: std::sync::Arc) { + self.tools.set_prompter(prompter); + } + + fn set_owner(&mut self, owner: std::sync::Arc) { + self.tools.set_owner(owner); + } + + fn share_allowed_writes(&mut self, record: std::sync::Arc) { + self.tools.share_allowed_writes(record); + } + + fn children(&self) -> Vec<(String, String)> { + self.tools + .children() + .into_iter() + .map(|c| (c.session, c.title)) + .collect() + } + + fn offered_tools(&self) -> Vec { + self.tools.names() + } + + /// The tools are incode's toolbox's on this route, so the toolbox is + /// what is watched. + fn set_watch(&mut self, watch: std::sync::Arc) { + self.tools.set_watch(watch); + } + + /// Taken headless: the next turn's prompt goes on stdin as a stream-json + /// message carrying them — see [`ClaudeCodeBackend::command`]. + fn attach_images(&mut self, images: Vec) -> Result<(), String> { + self.images = images; + Ok(()) + } + + fn model(&self) -> Option<&str> { + ClaudeCodeBackend::model(self) + } + + fn clear_session(&mut self) { + ClaudeCodeBackend::clear_session(self); + } + + fn set_permission_mode(&mut self, mode: &str) { + ClaudeCodeBackend::set_permission_mode(self, mode); + } + + fn set_session_id(&mut self, session_id: &str) { + ClaudeCodeBackend::set_session_id(self, session_id); + } + + /// The engine hears incode's session id with every call, not the CLI's + /// conversation id: incode's is the one its session events carry too. + fn set_memory_session(&mut self, session: &str) { + self.tools.pin_session(session); + } + + fn end_code_edits(&mut self) { + self.tools.end_code_edits(); + } + + fn set_system_context(&mut self, blocks: Vec) { + self.system_context = blocks + .into_iter() + .filter(|b| !b.trim().is_empty()) + .collect(); + } + + fn session_id(&self) -> Option<&str> { + self.session_id.as_deref() + } + + fn set_models(&mut self, candidates: &[String]) { + let applicable: Vec = candidates + .iter() + .filter(|c| self.serves(c)) + .cloned() + .collect(); + let Some((first, rest)) = applicable.split_first() else { + return; + }; + // Changing model abandons the session — see `with_models` for why a + // resumed conversation cannot be handed to a different model. + if self.model.as_deref() != Some(first.as_str()) { + self.session_id = None; + } + self.model = Some(first.clone()); + self.fallbacks = rest.to_vec(); + } + + fn ladder_for(&self, role: &str) -> Vec { + let ids: &[&str] = match role { + "explore" | "grunt" => &["haiku"], + "diagnose" | "review" | "plan" => &["opus", "sonnet"], + "implement" | "frontend" => &["sonnet", "opus"], + _ => &[], + }; + ids.iter().map(|id| (*id).to_string()).collect() + } + + fn run_turn( + &mut self, + prompt: &str, + on_event: &mut dyn FnMut(&AgentEvent), + ) -> Result { + // This turn's pictures, and only this turn's: taken now, so a turn + // that fails to start does not carry them into the next one. + let images = std::mem::take(&mut self.images); + let asked_for_thinking = self.partial_messages && self.thinking_display; + match self.run_once(prompt, images.clone(), on_event) { + // The CLI refused the undocumented thinking flag before it did + // anything: remembered for the session, and the turn run again, + // once, without it. + Err(e) if asked_for_thinking && rejects_thinking_display(&e.to_string()) => { + crate::trace!( + "agent", + "{} refused {THINKING_DISPLAY_FLAG}; running without it from now on", + self.binary + ); + self.thinking_display = false; + self.run_once(prompt, images, on_event) + } + other => other, + } + } +} + +// --------------------------------------------------------------------------- +// Tests — fixtures are real lines captured from Claude Code 2.1.229 +// --------------------------------------------------------------------------- + +#[cfg(test)] +mod command_tests; +#[cfg(test)] +mod profile_tests; +#[cfg(test)] +pub(crate) mod tests; +#[cfg(test)] +mod wire_tests; diff --git a/src/agent/claude_code/profile_tests.rs b/src/agent/claude_code/profile_tests.rs new file mode 100644 index 0000000..5336b20 --- /dev/null +++ b/src/agent/claude_code/profile_tests.rs @@ -0,0 +1,213 @@ +//! Which profile a turn is pointed at, and the logins outside the profiles +//! that keep it where it is. + +use super::profiles::{choose_profile, find_expiry}; +use super::*; + +/// Build a home directory holding the named profiles. +/// +/// `hours` is how long each session has left; negative means it expired. +fn home_with(profiles: &[(&str, Option)]) -> tempfile::TempDir { + let home = tempfile::tempdir().expect("tmp"); + let now_ms = i64::try_from( + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .expect("clock") + .as_millis(), + ) + .expect("fits"); + for (name, hours) in profiles { + let dir = home.path().join(name); + std::fs::create_dir_all(&dir).expect("dir"); + if let Some(h) = hours { + #[allow(clippy::cast_possible_truncation)] + let expires = now_ms + (h * 3_600_000.0) as i64; + // Same nesting the real file uses, and the same field names. + // The token fields are deliberately absent: the code must never + // need them, and a test that supplied them would hide it if it did. + std::fs::write( + dir.join(".credentials.json"), + format!(r#"{{"claudeAiOauth":{{"expiresAt":{expires},"scopes":[]}}}}"#), + ) + .expect("write"); + } + } + home +} + +#[test] +fn the_profile_with_a_live_session_is_chosen_over_the_default() { + // The exact situation that broke every turn for a day: the default + // profile's session had expired while another profile was still good, + // and the agent fell back to the default because nothing said otherwise. + let home = home_with(&[(".claude", Some(-4.0)), (".claude-work", Some(2.0))]); + let chosen = pick_usable(profiles_in(home.path())).expect("one is live"); + assert!( + chosen.dir.ends_with(".claude-work"), + "chose {:?}, but only .claude-work can work", + chosen.dir + ); +} + +#[test] +fn the_longest_lived_session_wins() { + let home = home_with(&[ + (".claude", Some(1.0)), + (".claude-work", Some(9.0)), + (".claude-other", Some(4.0)), + ]); + let chosen = pick_usable(profiles_in(home.path())).expect("live"); + assert!(chosen.dir.ends_with(".claude-work"), "{:?}", chosen.dir); +} + +#[test] +fn every_session_expired_means_no_choice_rather_than_a_bad_one() { + // Picking an expired profile would produce the same unexplained failure + // this replaces. Choosing nothing lets the turn fail with the message + // that actually names the problem. + let home = home_with(&[(".claude", Some(-1.0)), (".claude-work", Some(-9.0))]); + assert_eq!(pick_usable(profiles_in(home.path())), None); +} + +#[test] +fn a_session_about_to_expire_is_not_treated_as_live() { + // Starting a turn on a session with seconds left fails halfway through, + // which is worse than not starting it. + let home = home_with(&[(".claude", Some(0.01))]); // 36 seconds + assert_eq!(pick_usable(profiles_in(home.path())), None); +} + +#[test] +fn only_directories_count_as_profiles() { + // The home also holds `.claude.json` and a long tail of its backups. + let home = home_with(&[(".claude-work", Some(3.0))]); + std::fs::write(home.path().join(".claude.json"), "{}").expect("write"); + std::fs::write(home.path().join(".claude.json.backup"), "{}").expect("write"); + let found = profiles_in(home.path()); + assert_eq!(found.len(), 1, "found {found:?}"); + assert!(found[0].dir.ends_with(".claude-work")); +} + +#[test] +fn a_directory_with_no_session_recorded_is_skipped() { + let home = home_with(&[(".claude", None), (".claude-work", Some(3.0))]); + let found = profiles_in(home.path()); + assert_eq!(found.len(), 1, "found {found:?}"); +} + +#[test] +fn the_expiry_is_found_wherever_it_is_nested() { + let doc: serde_json::Value = + serde_json::from_str(r#"{"a":{"b":{"expiresAt":1234567890123}}}"#).expect("parse"); + assert_eq!(find_expiry(&doc), Some(1_234_567_890_123)); + let none: serde_json::Value = serde_json::from_str(r#"{"a":{"b":1}}"#).expect("parse"); + assert_eq!(find_expiry(&none), None); +} + +/// An environment holding exactly these variables. +fn env_of(vars: &'static [(&'static str, &'static str)]) -> impl Fn(&str) -> Option { + move |name| { + vars.iter() + .find(|(k, _)| *k == name) + .map(|(_, v)| (*v).to_string()) + } +} + +/// **A LOGIN THE CLI USES ANYWAY IS NEVER SWAPPED FOR A FILE PROFILE.** +/// Redirecting to a live `.credentials.json` moved a Keychain login out +/// of reach on macOS, and with a credential in the environment it changed +/// nothing but which settings the CLI read. +#[test] +fn a_login_outside_the_profiles_keeps_the_agent_where_it_is() { + let home = home_with(&[(".claude-work", Some(5.0))]); + let outside = || Some(OutsideLogin::Environment("CLAUDE_CODE_OAUTH_TOKEN")); + assert_eq!( + choose_profile(profiles_in(home.path()), &outside), + None, + "a live file profile replaced a login the CLI already had" + ); + + let nothing_else = || None; + let chosen = choose_profile(profiles_in(home.path()), ¬hing_else).expect("live"); + assert!( + chosen.dir.ends_with(".claude-work"), + "with no other login, the live profile is still the choice" + ); +} + +/// The Keychain costs a process, so it is not asked when no live file +/// profile could be chosen anyway. +#[test] +fn the_keychain_is_not_asked_when_no_profile_is_live() { + let home = home_with(&[(".claude", Some(-2.0))]); + let asked = std::cell::Cell::new(false); + let outside = || { + asked.set(true); + Some(OutsideLogin::Keychain) + }; + assert_eq!(choose_profile(profiles_in(home.path()), &outside), None); + assert!( + !asked.get(), + "a process was spent on a question nobody needed" + ); +} + +/// A credential variable is a login, and only its NAME is reported. +#[test] +fn a_credential_in_the_environment_is_a_login_named_by_its_variable() { + let env = env_of(&[("CLAUDE_CODE_OAUTH_TOKEN", "x")]); + assert_eq!( + login_outside_profiles(&env, &|| false), + Some(OutsideLogin::Environment("CLAUDE_CODE_OAUTH_TOKEN")) + ); + let empty = env_of(&[("ANTHROPIC_API_KEY", "")]); + assert_eq!( + login_outside_profiles(&empty, &|| false), + None, + "an empty variable carries no credential" + ); +} + +/// Provider switches are read the way the CLI reads them: `0` is off. +#[test] +fn a_provider_switch_counts_only_when_it_is_on() { + for on in ["1", "true", "YES", " on "] { + let env = move |name: &str| (name == "CLAUDE_CODE_USE_BEDROCK").then(|| on.to_string()); + assert_eq!( + login_outside_profiles(&env, &|| false), + Some(OutsideLogin::Environment("CLAUDE_CODE_USE_BEDROCK")), + "`{on}` switches the provider on" + ); + } + for off in ["0", "false", "no", ""] { + let env = move |name: &str| (name == "CLAUDE_CODE_USE_VERTEX").then(|| off.to_string()); + assert_eq!( + login_outside_profiles(&env, &|| false), + None, + "`{off}` leaves the provider off" + ); + } +} + +/// A base URL says where requests go, not what authenticates them; on its +/// own it is the state in which every turn fails, and must not read as a +/// login. +#[test] +fn a_base_url_alone_is_not_a_login() { + let env = env_of(&[("ANTHROPIC_BASE_URL", "https://gateway.example")]); + assert_eq!(login_outside_profiles(&env, &|| false), None); +} + +/// The default Keychain entry belongs to the default profile; once the +/// operator names another directory the CLI looks under another service, +/// so the default entry says nothing about this session. +#[test] +fn the_keychain_counts_only_for_the_default_profile() { + let nothing = env_of(&[]); + assert_eq!( + login_outside_profiles(¬hing, &|| true), + Some(OutsideLogin::Keychain) + ); + let elsewhere = env_of(&[("CLAUDE_CONFIG_DIR", "/home/op/.claude-work")]); + assert_eq!(login_outside_profiles(&elsewhere, &|| true), None); +} diff --git a/src/agent/claude_code/profiles.rs b/src/agent/claude_code/profiles.rs new file mode 100644 index 0000000..9b8cf18 --- /dev/null +++ b/src/agent/claude_code/profiles.rs @@ -0,0 +1,278 @@ +//! Which agent profile a turn is pointed at, and the logins that make +//! pointing it anywhere unnecessary. + +use std::process::{Command, Stdio}; + +/// The environment variable naming which agent profile to use. +pub(super) const PROFILE_ENV: &str = "CLAUDE_CONFIG_DIR"; +/// Profile directories are the home entries beginning with this. +const PROFILE_PREFIX: &str = ".claude"; +/// Where a profile records its session. +const CREDENTIALS_FILE: &str = ".credentials.json"; +/// A session with less than this left is treated as already gone, so a turn is +/// not started on a login that will expire while it runs. +const SESSION_MARGIN_SECS: i64 = 120; + +/// One agent profile and how much longer its session is good for. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Profile { + /// The directory to point the agent at. + pub dir: std::path::PathBuf, + /// Seconds of session left; negative means it expired that long ago. + pub seconds_left: i64, +} + +/// Every agent profile in the home directory, whether or not its session is live. +/// +/// # Why this exists +/// +/// The agent falls back to its default profile when nothing says otherwise, and +/// that profile is not necessarily the one the operator logged in with. On this +/// machine the default held a session that had expired while a second profile +/// was live, so every turn failed with an authentication error that named +/// neither profile. Choosing the profile that can actually work removes a whole +/// class of failure that looks exactly like a broken harness. +/// +/// # Credentials are never read +/// +/// Only the expiry timestamp is taken from the file. The tokens beside it are +/// not read, not copied and not logged — the harness has no use for them and +/// every reason not to touch them. +#[must_use] +pub fn profiles() -> Vec { + home_dir() + .map(|home| profiles_in(&home)) + .unwrap_or_default() +} + +/// The profiles under a given home directory. +/// +/// Split from [`profiles`] so the selection can be tested against a directory +/// built for the purpose, rather than against whatever the machine happens to +/// hold. +#[must_use] +pub fn profiles_in(home: &std::path::Path) -> Vec { + let Ok(entries) = std::fs::read_dir(home) else { + return Vec::new(); + }; + let mut found: Vec = entries + .filter_map(Result::ok) + .map(|e| e.path()) + // A directory only: the home also holds `.claude.json` and a long tail + // of its backups, none of which are profiles. + .filter(|p| p.is_dir()) + .filter(|p| { + p.file_name() + .and_then(|n| n.to_str()) + .is_some_and(|n| n.starts_with(PROFILE_PREFIX)) + }) + .filter_map(|dir| { + session_seconds_left(&dir).map(|seconds_left| Profile { dir, seconds_left }) + }) + .collect(); + // Longest-lived first, then by path so the order is the same on every run. + found.sort_by(|a, b| { + b.seconds_left + .cmp(&a.seconds_left) + .then_with(|| a.dir.cmp(&b.dir)) + }); + found +} + +/// The profile whose session is live and lasts longest, if any is — and none +/// when the agent already has a login that no profile file records. +/// +/// # Why a login elsewhere wins over a live file +/// +/// Pointing the CLI at a profile directory is the only lever this has, and it +/// moves the login along with everything else. On macOS the default profile's +/// login lives in the Keychain under a service name that changes once +/// [`PROFILE_ENV`] names another directory, so redirecting to a leftover +/// `.credentials.json` swapped a working login for a stale one. With a +/// credential in the environment the redirect buys nothing — the CLI +/// authenticates from the variable whichever directory it reads — and costs +/// the operator's own settings for that directory. +#[must_use] +pub fn usable_profile() -> Option { + choose_profile(profiles(), &|| { + login_outside_profiles(&process_env, &keychain_holds_login) + }) +} + +/// [`pick_usable`], unless `outside` names a login the CLI would use anyway. +/// +/// `outside` is asked only once a file profile would otherwise be chosen: the +/// Keychain answer costs a process, and with no live file there is nothing it +/// could change. +pub(super) fn choose_profile( + found: Vec, + outside: &dyn Fn() -> Option, +) -> Option { + let live = pick_usable(found)?; + if let Some(login) = outside() { + crate::trace!( + "agent", + "{} not chosen: the agent already logs in via {login:?}", + live.dir.display() + ); + return None; + } + Some(live) +} + +/// A login the agent CLI uses that is not a profile's credentials file. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum OutsideLogin { + /// This variable is set. Only its NAME is carried: the value is a secret + /// and nothing here has a use for it. + Environment(&'static str), + /// The macOS Keychain holds the default profile's login. + Keychain, +} + +/// Variables that carry a credential: set to anything, the CLI authenticates +/// with them. Names measured in the 2.1.303 binary. +/// +/// `ANTHROPIC_BASE_URL` is deliberately absent. It moves where requests go, +/// not what authenticates them — the CLI still sends a key, a token or its +/// login — so a base URL with no credential is exactly the state in which +/// every turn fails, and counting it would hide that. A host that manages the +/// provider says so with a provider switch below. +const CREDENTIAL_ENV: [&str; 4] = [ + "ANTHROPIC_API_KEY", + "CLAUDE_CODE_OAUTH_TOKEN", + "CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR", + "ANTHROPIC_AUTH_TOKEN", +]; + +/// Switches to a provider whose own credentials then authenticate the CLI. +/// +/// Read as switches, the way the CLI reads them (measured in 2.1.303: `1`, +/// `true`, `yes` or `on`, any case) — so `CLAUDE_CODE_USE_BEDROCK=0` is a +/// switch that is off, not a login. +const PROVIDER_ENV: [&str; 7] = [ + "CLAUDE_CODE_USE_BEDROCK", + "CLAUDE_CODE_USE_VERTEX", + "CLAUDE_CODE_USE_FOUNDRY", + "CLAUDE_CODE_USE_ANTHROPIC_AWS", + "CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD", + "CLAUDE_CODE_USE_MANTLE", + "CLAUDE_CODE_USE_GATEWAY", +]; + +/// The Keychain service the CLI keeps the DEFAULT profile's login under. +/// +/// Measured in 2.1.303: `"Claude Code" + "-credentials"`, with a hash of the +/// directory appended when [`PROFILE_ENV`] names another one — which is why +/// the Keychain is only consulted while that variable is unset. +const KEYCHAIN_SERVICE: &str = "Claude Code-credentials"; + +/// How long the Keychain lookup may take. A local lookup answers in +/// milliseconds; a locked or hung keychain must not hold up a turn or a +/// diagnosis. +const KEYCHAIN_WAIT: std::time::Duration = std::time::Duration::from_secs(3); + +/// The login the CLI will use that no profile file records, if there is one. +/// +/// `env` and `keychain` are parameters so the decision can be tested without +/// touching the process environment, which every test thread shares. The +/// environment is read first because it is free; the Keychain costs a process. +#[must_use] +pub fn login_outside_profiles( + env: &dyn Fn(&str) -> Option, + keychain: &dyn Fn() -> bool, +) -> Option { + let set = |name: &str| env(name).is_some_and(|v| !v.is_empty()); + let switched_on = |name: &str| { + env(name).is_some_and(|v| { + matches!( + v.trim().to_ascii_lowercase().as_str(), + "1" | "true" | "yes" | "on" + ) + }) + }; + if let Some(name) = CREDENTIAL_ENV.into_iter().find(|name| set(name)) { + return Some(OutsideLogin::Environment(name)); + } + if let Some(name) = PROVIDER_ENV.into_iter().find(|name| switched_on(name)) { + return Some(OutsideLogin::Environment(name)); + } + (env(PROFILE_ENV).is_none() && keychain()).then_some(OutsideLogin::Keychain) +} + +/// One variable from this process's environment, as [`login_outside_profiles`] +/// reads it. +#[must_use] +pub fn process_env(name: &str) -> Option { + std::env::var_os(name).map(|v| v.to_string_lossy().into_owned()) +} + +/// Whether the macOS Keychain holds the default profile's login. +/// +/// Asks for the item's EXISTENCE only: no `-w`, so the secret is never +/// printed, and an attribute lookup does not raise the access prompt a read +/// of the secret would. Output is discarded; the exit code is the answer. +/// Elsewhere there is no Keychain, and the answer is no without a process. +#[must_use] +pub fn keychain_holds_login() -> bool { + if !cfg!(target_os = "macos") { + return false; + } + let mut cmd = Command::new("security"); + cmd.args(["find-generic-password", "-s", KEYCHAIN_SERVICE]) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()); + crate::agent::process_tree::prepare(&mut cmd); + let Ok(child) = cmd.spawn() else { + return false; + }; + crate::tools::bash::wait_with_timeout(child, KEYCHAIN_WAIT) + .is_ok_and(|out| out.status.success()) +} + +/// The first profile with enough session left to be worth starting a turn on. +#[must_use] +pub fn pick_usable(found: Vec) -> Option { + found + .into_iter() + .find(|p| p.seconds_left > SESSION_MARGIN_SECS) +} + +/// How long this profile's session has left, or `None` if it records none. +fn session_seconds_left(dir: &std::path::Path) -> Option { + let text = std::fs::read_to_string(dir.join(CREDENTIALS_FILE)).ok()?; + let parsed: serde_json::Value = serde_json::from_str(&text).ok()?; + let expires_at_ms = find_expiry(&parsed)?; + let now_ms = i64::try_from( + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .ok()? + .as_millis(), + ) + .ok()?; + Some((expires_at_ms - now_ms) / 1_000) +} + +/// The session expiry anywhere in the document, in milliseconds. +/// +/// Searched rather than addressed by path: the key sits one level down today, +/// and a layout change should cost the selection, never break the harness. +pub(super) fn find_expiry(value: &serde_json::Value) -> Option { + match value { + serde_json::Value::Object(map) => { + if let Some(found) = map.get("expiresAt").and_then(serde_json::Value::as_i64) { + return Some(found); + } + map.values().find_map(find_expiry) + } + _ => None, + } +} + +/// The operator's home directory. +fn home_dir() -> Option { + std::env::var_os("HOME") + .or_else(|| std::env::var_os("USERPROFILE")) + .map(std::path::PathBuf::from) +} diff --git a/src/agent/claude_code/tests.rs b/src/agent/claude_code/tests.rs new file mode 100644 index 0000000..779683a --- /dev/null +++ b/src/agent/claude_code/tests.rs @@ -0,0 +1,512 @@ +//! The backend's own state — context, sessions, models — and whole turns run +//! through `run_turn` on stand-in CLIs. [`stand_in_cli`] is shared with tests +//! elsewhere in the crate. + +use super::command::rejects_thinking_display; +use super::wire::map_line; +use super::*; + +/// A turn outcome, spelled out. +pub(super) fn outcome_of( + session: &str, + stop: &str, + is_error: bool, + detail: Option<&str>, + served_by: &[&str], +) -> TurnOutcome { + TurnOutcome { + session_id: session.to_string(), + stop_reason: stop.to_string(), + is_error, + detail: detail.map(str::to_string), + served_by: served_by.iter().map(|m| (*m).to_string()).collect(), + } +} + +pub(super) fn usage_of(input: u32, output: u32, creation: u32, read: u32) -> AgentEvent { + AgentEvent::Usage { + input_tokens: input, + output_tokens: output, + cache_creation_tokens: creation, + cache_read_tokens: read, + } +} + +/// **The harness's project context must actually REACH the agent.** It was +/// assembled and then dropped when the loop was removed: the build stayed +/// green, the tests passed and the live runs worked, while the guard rules, +/// the auditor's findings and the recorder's handoff silently stopped being +/// sent. Nothing catches that except asserting the argument is built. +#[test] +fn the_session_context_is_carried_to_the_agent() { + let backend = ClaudeCodeBackend::new(std::path::PathBuf::from(".")) + .with_system_context(vec!["do not edit tests".to_string()]); + assert_eq!( + backend.system_context(), + &["do not edit tests".to_string()] + ); +} + +/// Empty blocks are dropped rather than sent as blank lines — a context +/// section with nothing in it is noise the agent pays for. +#[test] +fn empty_context_blocks_are_not_sent() { + let backend = ClaudeCodeBackend::new(std::path::PathBuf::from(".")).with_system_context(vec![ + String::new(), + " ".to_string(), + "real".to_string(), + ]); + assert_eq!(backend.system_context(), &["real".to_string()]); +} + +/// A session with no context sends no flag at all. +#[test] +fn no_context_means_no_flag() { + let backend = ClaudeCodeBackend::new(std::path::PathBuf::from(".")); + assert!(backend.system_context().is_empty()); +} + +/// **Deltas are opt-in.** A caller collecting a report must not be handed +/// two copies of the same words, so the flag is off unless asked for. +#[test] +fn partial_messages_are_off_unless_asked_for() { + let plain = ClaudeCodeBackend::new(std::path::PathBuf::from(".")); + assert!(!plain.partial_messages); + let streaming = ClaudeCodeBackend::new(std::path::PathBuf::from(".")).streaming(true); + assert!(streaming.partial_messages); +} + +/// Session reuse is the single largest cost lever in this backend: measured +/// against CLI 2.1.229, a fresh session costs ~36k cache-creation tokens per +/// turn versus ~1.8k when resuming — roughly 5.8x. That only holds if the +/// backend actually remembers the session and asks to continue it, so this +/// asserts the state transition that makes `--resume` possible. +#[test] +fn backend_remembers_the_session_so_later_turns_can_resume() { + let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")); + assert!( + backend.session_id().is_none(), + "control: a fresh backend has no session to resume" + ); + + // Drive the state transition the way a real turn does: the init line + // carries the session id. + let mut outcome = None; + for event in map_line( + r#"{"type":"system","subtype":"init","session_id":"sess-xyz","model":"m"}"#, + &mut outcome, + ) { + if let AgentEvent::SessionStarted { session_id, .. } = event { + backend.session_id = Some(session_id); + } + } + + assert_eq!( + backend.session_id(), + Some("sess-xyz"), + "the backend must retain the session id, or every turn starts fresh \ + and re-pays the whole prompt prefix" + ); +} + +/// An explicitly supplied session must be carried too, so a caller can +/// continue a task across process restarts. +#[test] +fn explicit_session_is_carried() { + let backend = ClaudeCodeBackend::new(PathBuf::from(".")).with_session("prior-session"); + assert_eq!(backend.session_id(), Some("prior-session")); +} + +/// **Changing the model abandons the session, and that is deliberate.** A +/// resumed session carries earlier turns; asking a different model to +/// continue them means paying to resume a conversation it never had. +#[test] +fn switching_model_starts_a_fresh_session() { + let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")) + .with_session("s-existing") + .with_models(&["cheap".to_string()]); + assert_eq!(backend.model(), Some("cheap")); + assert_eq!( + backend.session_id(), + None, + "a session belonging to another model must not be resumed" + ); + + // Re-asking for the SAME model must not throw away a session — that + // would re-pay the whole prompt prefix on every turn. + backend.session_id = Some("s-cheap".to_string()); + backend.set_models(&["cheap".to_string()]); + assert_eq!(backend.session_id(), Some("s-cheap")); + + // And switching again drops it. + backend.set_models(&["expensive".to_string()]); + assert_eq!(backend.session_id(), None); +} + +/// An empty candidate list is "no opinion", not "clear the model". +#[test] +fn no_candidates_leaves_the_choice_untouched() { + let mut backend = + ClaudeCodeBackend::new(PathBuf::from(".")).with_models(&["cheap".to_string()]); + backend.set_models(&[]); + assert_eq!(backend.model(), Some("cheap")); +} + +/// The rest of the chain becomes the CLI's own fallback list, which is the +/// shape it takes: one comma-separated argument, tried in order. +#[test] +fn the_candidate_chain_becomes_the_fallback_list() { + let backend = ClaudeCodeBackend::new(PathBuf::from(".")).with_models(&[ + "first".to_string(), + "second".to_string(), + "third".to_string(), + ]); + assert_eq!(backend.model(), Some("first")); + assert_eq!( + backend.fallbacks, + vec!["second".to_string(), "third".to_string()] + ); +} + +/// Foreign vendor model IDs are dropped so mixed-fleet candidate lists from +/// shared tiers do not cause Claude Code CLI to error on unsupported flags. +#[test] +fn foreign_model_id_is_dropped_from_claude_candidates() { + let mut backend = ClaudeCodeBackend::new(PathBuf::from(".")); + backend.set_models(&[ + "gemini-3.8-flash-high".to_string(), + "gpt-5.6-terra".to_string(), + ]); + assert_eq!(backend.model(), None); + + backend.set_models(&[ + "gemini-3.8-flash-high".to_string(), + "sonnet".to_string(), + "gpt-5.6-terra".to_string(), + ]); + assert_eq!(backend.model(), Some("sonnet")); + assert_eq!(backend.fallbacks, Vec::::new()); +} + +/// Every role in the native Claude Code ladder can be served by Claude Code. +#[test] +fn claude_code_ladder_for_known_roles_serves_every_model() { + let backend = ClaudeCodeBackend::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 claude-code cannot serve" + ); + } + } + assert_ne!( + backend.ladder_for("explore"), + backend.ladder_for("diagnose"), + "reading and reasoning must not draw the same tier" + ); +} + +/// A stand-in agent that writes far more to stderr than a pipe holds, then +/// exits without ever printing a result — the shape of a CLI that fails +/// loudly at startup. +fn a_loud_failing_agent(dir: &std::path::Path) -> PathBuf { + #[cfg(windows)] + { + let path = dir.join("loud-agent.cmd"); + std::fs::write( + &path, + "@echo off\r\nfor /L %%i in (1,1,3000) do echo stderr line %%i \ + padding padding padding padding padding padding padding 1>&2\r\n\ + echo token=hunter2-not-a-real-secret 1>&2\r\nexit /b 3\r\n", + ) + .expect("write the fake agent"); + path + } + #[cfg(not(windows))] + { + use std::os::unix::fs::PermissionsExt; + let path = dir.join("loud-agent.sh"); + std::fs::write( + &path, + "#!/bin/sh\ni=0\nwhile [ $i -lt 3000 ]; do echo \"stderr line $i padding \ + padding padding padding padding padding padding\" >&2; i=$((i+1)); done\n\ + echo 'token=hunter2-not-a-real-secret' >&2\nexit 3\n", + ) + .expect("write the fake agent"); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) + .expect("make it runnable"); + path + } +} + +/// **A LOUD FAILURE DOES NOT HANG THE TURN, AND WHAT IT SAID IS BOUNDED +/// AND CLEANED.** +/// +/// stderr was piped and only read after `wait()`. An agent that wrote more +/// than the pipe holds blocked on the write, never exited, and `wait()` +/// never returned: the turn hung with no message. The same text, once +/// read, went unbounded and unredacted into the error, the ledger and the +/// transcript. +#[test] +fn an_agent_that_floods_stderr_fails_promptly_with_a_bounded_clean_reason() { + let dir = tempfile::tempdir().expect("scratch"); + let fake = a_loud_failing_agent(dir.path()); + let workspace = dir.path().to_path_buf(); + + let (tx, rx) = std::sync::mpsc::channel(); + std::thread::spawn(move || { + let mut backend = ClaudeCodeBackend::new(workspace).with_binary(fake.to_string_lossy()); + let result = backend.run_turn("hi", &mut |_| {}); + let _ = tx.send(result.map(|_| ()).map_err(|e| e.to_string())); + }); + + let result = rx + .recv_timeout(std::time::Duration::from_secs(60)) + .expect("the turn hung: the agent's stderr was never drained"); + let reason = result.expect_err("the fake agent produced no result line"); + + assert!( + reason.contains("stderr line"), + "what the agent said was lost: {reason}" + ); + assert!( + reason.len() <= crate::agent::stderr_tail::MAX_BYTES + 1024, + "the reason was not bounded: {} bytes", + reason.len() + ); + assert!( + !reason.contains("hunter2-not-a-real-secret"), + "a secret-shaped value reached the error unredacted" + ); +} + +/// A stand-in CLI whose option parser does not know the thinking flag: +/// named on its argv, it says so on stderr and exits 1 before any +/// output; otherwise it prints a short turn. Every start is counted in +/// `starts.txt` beside it. +fn a_cli_without_the_thinking_flag(dir: &std::path::Path) -> PathBuf { + const LINES: [&str; 3] = [ + r#"{"type":"system","subtype":"init","session_id":"no-think-1","model":"m"}"#, + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"still here"}]},"parent_tool_use_id":null}"#, + r#"{"type":"result","is_error":false,"stop_reason":"end_turn","session_id":"no-think-1","usage":{"input_tokens":1,"output_tokens":1}}"#, + ]; + #[cfg(windows)] + { + let mut body = String::from( + "@echo off\r\necho x>>\"%~dp0starts.txt\"\r\n\ + echo %* | findstr /C:\"--thinking-display\" >nul\r\n\ + if not errorlevel 1 (\r\n\ + echo error: unknown option '--thinking-display' 1>&2\r\n\ + exit /b 1\r\n)\r\n", + ); + for line in LINES { + body.push_str(&format!("echo {line}\r\n")); + } + let path = dir.join("old-agent.cmd"); + std::fs::write(&path, body).expect("write the stand-in agent"); + path + } + #[cfg(not(windows))] + { + use std::os::unix::fs::PermissionsExt; + let mut body = String::from( + "#!/bin/sh\necho x >> \"$(dirname \"$0\")/starts.txt\"\n\ + case \"$*\" in *--thinking-display*) \ + echo \"error: unknown option '--thinking-display'\" >&2; exit 1;; esac\n", + ); + for line in LINES { + body.push_str(&format!("echo '{line}'\n")); + } + let path = dir.join("old-agent.sh"); + std::fs::write(&path, body).expect("write the stand-in agent"); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) + .expect("make it runnable"); + path + } +} + +/// **A CLI THAT DROPS THE UNDOCUMENTED THINKING FLAG DOES NOT BREAK EVERY +/// TURN.** The first refusal is recognised, the turn runs again without +/// the flag, and the backend remembers: the next turn starts once. +#[test] +fn a_refused_thinking_flag_is_dropped_once_and_remembered() { + let dir = tempfile::tempdir().expect("scratch"); + let fake = a_cli_without_the_thinking_flag(dir.path()); + let starts = dir.path().join("starts.txt"); + let count = || { + std::fs::read_to_string(&starts) + .map(|s| s.lines().count()) + .unwrap_or(0) + }; + let mut backend = ClaudeCodeBackend::new(dir.path().to_path_buf()) + .with_binary(fake.to_string_lossy()) + .streaming(true); + + let mut said = Vec::new(); + let first = backend + .run_turn("hi", &mut |e| { + if let AgentEvent::Text(t) = e { + said.push(t.clone()); + } + }) + .expect("the turn is run again without the flag"); + assert!(!first.is_error, "{first:?}"); + assert_eq!(said, ["still here"], "{said:?}"); + assert_eq!(count(), 2, "one refused start, one without the flag"); + + backend.run_turn("again", &mut |_| {}).expect("second turn"); + assert_eq!(count(), 3, "the refusal is remembered: one start this turn"); +} + +/// Only a refusal that names the flag counts; any other failure is left +/// as it was. +#[test] +fn only_a_refusal_naming_the_thinking_flag_is_recognised() { + assert!(rejects_thinking_display( + "agent exited with 1 before producing a result: error: unknown option \ + '--thinking-display'" + )); + assert!(!rejects_thinking_display( + "error: unknown option '--fallback-model'" + )); + assert!(!rejects_thinking_display( + "the --thinking-display summary was empty" + )); +} + +/// A stand-in for the agent CLI, for tests elsewhere in the crate: it prints +/// a short stream-json turn — a summarized thinking delta, the reply +/// `three files`, the result — and ignores its argv and stdin. With `waits` +/// it pauses half a minute after the session starts, so a test can stop it. +pub(crate) fn stand_in_cli(dir: &std::path::Path, waits: bool) -> PathBuf { + const LINES: [&str; 5] = [ + r#"{"type":"system","subtype":"init","session_id":"sub-conv-1","model":"fake-sub-model"}"#, + r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"looking around"}},"parent_tool_use_id":null}"#, + r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"three files"}},"parent_tool_use_id":null}"#, + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"three files"}]},"parent_tool_use_id":null}"#, + r#"{"type":"result","is_error":false,"stop_reason":"end_turn","session_id":"sub-conv-1","usage":{"input_tokens":1,"output_tokens":1}}"#, + ]; + #[cfg(windows)] + { + let mut body = format!("@echo off\r\necho {}\r\n", LINES[0]); + if waits { + body.push_str("ping -n 30 127.0.0.1 >nul\r\n"); + } + for line in &LINES[1..] { + body.push_str(&format!("echo {line}\r\n")); + } + let path = dir.join(if waits { "slow-agent.cmd" } else { "agent.cmd" }); + std::fs::write(&path, body).expect("write the stand-in agent"); + path + } + #[cfg(not(windows))] + { + use std::os::unix::fs::PermissionsExt; + let mut body = format!("#!/bin/sh\necho '{}'\n", LINES[0]); + if waits { + body.push_str("sleep 30\n"); + } + for line in &LINES[1..] { + body.push_str(&format!("echo '{line}'\n")); + } + let path = dir.join(if waits { "slow-agent.sh" } else { "agent.sh" }); + std::fs::write(&path, body).expect("write the stand-in agent"); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) + .expect("make it runnable"); + path + } +} + +// --------------------------------------------------------------------------- +// Pinned behaviour: what a whole turn through `run_turn` reports. +// --------------------------------------------------------------------------- + +/// **A WHOLE TURN THROUGH `run_turn`**: the events in order, the outcome, +/// and the session kept for the next turn. +#[test] +fn a_whole_turn_reports_these_events_and_this_outcome() { + let dir = tempfile::tempdir().expect("scratch"); + let fake = stand_in_cli(dir.path(), false); + let mut backend = + ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); + let mut seen = Vec::new(); + let outcome = backend + .run_turn("hi", &mut |e| seen.push(e.clone())) + .expect("the stand-in finishes its turn"); + assert_eq!( + seen, + vec![ + AgentEvent::SessionStarted { + session_id: "sub-conv-1".to_string(), + model: "fake-sub-model".to_string(), + }, + AgentEvent::Thinking("looking around".to_string()), + AgentEvent::TextDelta("three files".to_string()), + AgentEvent::Text("three files".to_string()), + usage_of(1, 1, 0, 0), + ] + ); + assert_eq!( + outcome, + outcome_of("sub-conv-1", "end_turn", false, None, &[]) + ); + assert_eq!(backend.session_id(), Some("sub-conv-1")); +} + +/// A CLI that cannot be started names itself in the error. +#[test] +fn a_cli_that_cannot_start_is_named_in_the_error() { + let dir = tempfile::tempdir().expect("scratch"); + let missing = dir.path().join("no-such-agent-binary"); + let mut backend = + ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(missing.to_string_lossy()); + let err = backend + .run_turn("hi", &mut |_| {}) + .expect_err("nothing to start"); + assert!( + err.to_string() + .starts_with(&format!("failed to spawn `{}`: ", missing.display())), + "{err}" + ); +} + +/// A stand-in that starts a session and exits cleanly, saying nothing +/// else and writing nothing to stderr. +fn a_cli_that_ends_without_a_result(dir: &std::path::Path) -> PathBuf { + const INIT: &str = r#"{"type":"system","subtype":"init","session_id":"cut-1","model":"m"}"#; + #[cfg(windows)] + { + let path = dir.join("cut-agent.cmd"); + std::fs::write(&path, format!("@echo off\r\necho {INIT}\r\nexit /b 0\r\n")) + .expect("write the stand-in agent"); + path + } + #[cfg(not(windows))] + { + use std::os::unix::fs::PermissionsExt; + let path = dir.join("cut-agent.sh"); + std::fs::write(&path, format!("#!/bin/sh\necho '{INIT}'\nexit 0\n")) + .expect("write the stand-in agent"); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) + .expect("make it runnable"); + path + } +} + +/// No result line: the exact error, and the session still kept. +#[test] +fn a_turn_without_a_result_fails_with_this_error_and_keeps_its_session() { + let dir = tempfile::tempdir().expect("scratch"); + let fake = a_cli_that_ends_without_a_result(dir.path()); + let mut backend = + ClaudeCodeBackend::new(dir.path().to_path_buf()).with_binary(fake.to_string_lossy()); + let err = backend + .run_turn("hi", &mut |_| {}) + .expect_err("no result line"); + assert_eq!( + err.to_string(), + "agent exited with 0 before producing a result: " + ); + assert_eq!(backend.session_id(), Some("cut-1")); +} diff --git a/src/agent/claude_code/turn.rs b/src/agent/claude_code/turn.rs new file mode 100644 index 0000000..b025b2e --- /dev/null +++ b/src/agent/claude_code/turn.rs @@ -0,0 +1,308 @@ +//! One run of the CLI for a turn: spawned with the tool bridge open, its +//! tool calls answered by incode's toolbox, its stream read to the end. + +#[cfg(test)] +use std::io::BufRead; +use std::io::BufReader; +use std::process::{Child, Command, Stdio}; + +use super::command::{servers_for, user_message}; +use super::wire::map_line; +use super::{ClaudeCodeBackend, CANCELLED}; +use crate::agent::process_tree::Tree; +use crate::agent::stderr_tail::StderrTail; +use crate::agent::{AgentError, AgentEvent, TurnOutcome}; +use crate::tool_bridge::Incoming; + +/// Where to write the agent's raw output, if the operator asked for it. +/// +/// `INCODE_DEBUG_STREAM=` appends every line the agent sends. It is the +/// only way to answer "why did this turn fail" without guessing. +#[must_use] +pub fn debug_stream_path() -> Option { + std::env::var("INCODE_DEBUG_STREAM") + .ok() + .filter(|p| !p.is_empty()) +} + +/// The turn itself: the CLI's output mapped to events, and every tool call +/// the model makes run by `tools`, until the CLI finishes or the turn is +/// stopped. The loop is the bridge's ([`crate::tool_bridge::drive`]); what a +/// line of THIS CLI means is decided here. +/// +/// Split from the spawn plumbing so the loop that actually matters — event +/// mapping, session capture for `--resume`, and outcome extraction — is +/// testable over canned bytes without launching a process. +/// +/// `session` is updated in place as soon as the session id appears, so a turn +/// that fails partway still leaves the backend able to resume. +pub(super) fn consume( + from: &std::sync::mpsc::Receiver, + session: &mut Option, + on_event: &mut dyn FnMut(&AgentEvent), + cancel: Option<&crate::runtime::cancel::CancelToken>, + tools: &mut crate::toolbox::Toolbox, + calls: &mut u64, +) -> Result, AgentError> { + let mut outcome = None; + crate::tool_bridge::drive(from, cancel, tools, calls, on_event, &mut |line, tools| { + // Every raw line, when asked for. A turn that fails for a reason the + // harness cannot explain — "stopped without finishing: stop_sequence" — + // is unanswerable without the bytes the agent actually sent, and + // guessing at them from a screenshot is how an afternoon disappears. + if let Some(path) = debug_stream_path() { + if let Ok(mut file) = std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(path) + { + use std::io::Write as _; + let _ = writeln!(file, "{line}"); + } + } + if line.trim().is_empty() { + return Vec::new(); + } + let events = map_line(&line, &mut outcome); + for event in &events { + if let AgentEvent::SessionStarted { session_id, .. } = event { + if !session_id.is_empty() { + *session = Some(session_id.clone()); + // The engine files its cards and backups under the + // conversation, so it is told this one. + tools.set_session(session_id); + } + } + } + events + })?; + Ok(outcome) +} + +/// [`consume`] over a finished stream of bytes, for the tests that replay +/// captured output. +#[cfg(test)] +pub(super) fn consume_stream( + reader: R, + session: &mut Option, + on_event: &mut dyn FnMut(&AgentEvent), + cancel: Option<&crate::runtime::cancel::CancelToken>, +) -> Result, AgentError> { + let (to, from) = std::sync::mpsc::channel(); + for line in reader.lines() { + let message = match line { + Ok(line) => Incoming::Line(line), + Err(e) => Incoming::ReadFailed(e.to_string()), + }; + let _ = to.send(message); + } + let _ = to.send(Incoming::Ended); + let mut tools = crate::toolbox::Toolbox::new(std::path::Path::new("."), true); + consume(&from, session, on_event, cancel, &mut tools, &mut 0) +} + +impl ClaudeCodeBackend { + /// One run of the CLI for a turn: spawned, its tool calls answered, its + /// stream read to the end. + /// + /// Called by `run_turn` (`mod.rs`), and once more when the CLI refused the + /// thinking flag. + pub(super) fn run_once( + &mut self, + prompt: &str, + images: Vec, + on_event: &mut dyn FnMut(&AgentEvent), + ) -> Result { + let (budgeted_prompt, budgeted_context) = + crate::agent::budget_for_spawn(prompt, &self.system_context, &self.workspace)?; + + // THE TOOLS ARE incode's. The CLI's own are switched off below and the + // model is handed incode's toolbox through the bridge, which this + // process answers for the whole turn. Without the bridge there would + // be no tools but the CLI's, so a bridge that cannot open stops the + // turn rather than falling back to them. + let crate::tool_bridge::Turn { + exe, + bridge, + to: to_loop, + from: from_cli, + } = crate::tool_bridge::Turn::open(self.cancel.clone())?; + let (servers, allowed) = servers_for(&exe); + + let mut cmd = self.command( + images.is_empty().then_some(budgeted_prompt.as_str()), + &budgeted_context, + &servers, + &allowed, + ); + // How the tool server finds this process: through the CLI's + // environment, which the servers it starts inherit — never its argv. + for (key, value) in bridge.env() { + cmd.env(key, value); + } + self.trace_spawn(&cmd); + self.dump_argv(&cmd); + + let (mut child, tree) = self.spawn(&mut cmd, &budgeted_prompt, &images)?; + let stdout = child + .stdout + .take() + .ok_or_else(|| AgentError::new("child stdout was not piped"))?; + // Drained from now, not after `wait()`: an agent that fills the pipe + // blocks on the write and never exits. See `stderr_tail`. + let stderr = StderrTail::capture(child.stderr.take()); + + crate::tool_bridge::pump(BufReader::new(stdout), to_loop); + let outcome = consume( + &from_cli, + &mut self.session_id, + on_event, + self.cancel.as_ref(), + &mut self.tools, + &mut self.calls, + ); + // Closed as soon as the turn's loop is done: a call that arrives from + // here on is refused rather than left waiting on a loop that is gone. + drop(bridge); + self.finish(outcome, &mut child, &tree, stderr) + } + + /// WHAT WAS ACTUALLY SPAWNED, on the ordinary trace. The flags decide the + /// whole turn — which model, which profile, which deny rules — and a + /// failure is unreadable without them. The full argv, including the + /// appended system prompt, still goes to the stream dump + /// ([`Self::dump_argv`]); this is the one-line version that belongs beside + /// everything else that happened. + /// + /// Called by [`Self::run_once`], before the spawn. + fn trace_spawn(&self, cmd: &Command) { + if !crate::trace::on() { + return; + } + let flags: Vec = cmd + .get_args() + .map(|a| a.to_string_lossy().into_owned()) + .filter(|a| a.starts_with("--")) + .collect(); + crate::trace!( + "agent", + "spawning {} model={:?} resume={:?} flags={}", + self.binary, + self.model, + self.session_id, + flags.join(" ") + ); + } + + /// The exact command, when the operator asks for it. + /// + /// A turn that fails cannot be investigated from outside the harness + /// without the argv that produced it: the flags, the deny rules and the + /// whole appended system prompt are assembled here and were, until now, + /// invisible. Written alongside the raw stream so a failure can be + /// replayed by hand and the flags bisected. + /// + /// Called by [`Self::run_once`], before the spawn. + fn dump_argv(&self, cmd: &Command) { + let Some(path) = debug_stream_path() else { + return; + }; + if let Ok(mut file) = std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(path) + { + use std::io::Write as _; + let argv: Vec = std::iter::once(self.binary.clone()) + .chain(cmd.get_args().map(|a| a.to_string_lossy().into_owned())) + .collect(); + // As JSON, so an argument containing spaces or newlines — the + // system prompt does — survives being read back. + let _ = writeln!( + file, + "{}", + serde_json::json!({ "type": "incode_argv", "argv": argv }) + ); + } + } + + /// The CLI started in the workspace with its output piped and everything + /// it starts taken in; a turn with pictures has its one message written to + /// stdin. + /// + /// Called by [`Self::run_once`]. + fn spawn( + &self, + cmd: &mut Command, + prompt: &str, + images: &[crate::toolbox::Image], + ) -> Result<(Child, Tree), AgentError> { + // stdin must be closed explicitly, or the CLI waits ~3s for piped input + // on every invocation. A turn with pictures writes its one message + // there instead, and closes it. + crate::agent::process_tree::prepare(cmd); + let mut child = cmd + .current_dir(&self.workspace) + .stdin(if images.is_empty() { + Stdio::null() + } else { + Stdio::piped() + }) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .map_err(|e| AgentError::new(format!("failed to spawn `{}`: {e}", self.binary)))?; + let tree = Tree::adopt(&child); + if let Some(mut stdin) = child.stdin.take() { + // On a thread of its own: the message can be megabytes, and a + // pipe the CLI is not reading yet must not stall this loop. + let message = user_message(prompt, images); + std::thread::spawn(move || { + use std::io::Write as _; + let _ = stdin.write_all(message.as_bytes()); + // Dropped here: the CLI ends its input, and its turn, on EOF. + }); + } + Ok((child, tree)) + } + + /// The turn's end: the child stopped if the turn was, waited for, and the + /// outcome kept — or, with no result line, the error that says what the + /// CLI wrote on stderr. + /// + /// Called by [`Self::run_once`] once the stream is read. + fn finish( + &mut self, + outcome: Result, AgentError>, + child: &mut Child, + tree: &Tree, + stderr: StderrTail, + ) -> Result { + // Whatever happened, the child must not outlive this call. A cancelled + // turn that left the agent running would keep writing files with + // nobody reading its output — and that includes whatever it started. + let cancelled = matches!(outcome, Err(ref e) if e.to_string() == CANCELLED); + if cancelled { + tree.kill(child); + } + let outcome = outcome?; + + let status = child + .wait() + .map_err(|e| AgentError::new(format!("waiting for agent: {e}")))?; + + match outcome { + Some(o) => { + if !o.session_id.is_empty() { + self.session_id = Some(o.session_id.clone()); + } + Ok(o) + } + None => Err(AgentError::new(format!( + "agent exited with {} before producing a result: {}", + status.code().unwrap_or(-1), + stderr.finish() + ))), + } + } +} diff --git a/src/agent/claude_code/wire.rs b/src/agent/claude_code/wire.rs new file mode 100644 index 0000000..8991a8d --- /dev/null +++ b/src/agent/claude_code/wire.rs @@ -0,0 +1,380 @@ +//! The CLI's `--output-format stream-json` lines, and the harness events each +//! one becomes. +//! +//! The wire shapes below were taken from real runs of CLI 2.1.229, not from +//! documentation. + +use serde::Deserialize; + +use crate::agent::{AgentEvent, TurnOutcome}; + +// --------------------------------------------------------------------------- +// Wire types +// --------------------------------------------------------------------------- + +/// One line of `--output-format stream-json`. +/// +/// Tagged on `type`, which every line carries — but field ORDER varies (the +/// final `result` line puts `type` near the end), so this must be a tagged +/// enum rather than anything positional. +#[derive(Debug, Deserialize)] +#[serde(tag = "type")] +enum CliEvent { + #[serde(rename = "system")] + System(SystemEvent), + #[serde(rename = "assistant")] + Assistant(AssistantMsg), + // No `user` variant: those lines carry the results of tool calls, which + // are incode's own and were shown by incode when it ran them. + #[serde(rename = "stream_event")] + StreamEvent(StreamEvent), + #[serde(rename = "rate_limit_event")] + RateLimit(RateLimitEvent), + #[serde(rename = "result")] + Result(Box), + #[serde(other)] + Other, +} + +/// A partial-message frame, present only with `--include-partial-messages`. +/// +/// Shape captured from a real run rather than assumed: +/// `{"type":"stream_event","event":{"type":"content_block_delta","index":0, +/// "delta":{"type":"text_delta","text":"h"}},"parent_tool_use_id":null}` +#[derive(Debug, Deserialize)] +struct StreamEvent { + event: StreamInner, + #[serde(default)] + parent_tool_use_id: Option, +} + +#[derive(Debug, Deserialize)] +struct StreamInner { + #[serde(rename = "type")] + event_type: String, + #[serde(default)] + delta: Option, +} + +#[derive(Debug, Deserialize)] +struct StreamDelta { + #[serde(rename = "type", default)] + delta_type: String, + #[serde(default)] + text: String, + /// A `thinking_delta`'s text. Measured on 2.1.283: EMPTY unless the run + /// asked for `--thinking-display summarized` (the default display, + /// `updates`, sends only `estimated_tokens`). + #[serde(default)] + thinking: String, +} + +#[derive(Debug, Deserialize)] +struct SystemEvent { + subtype: String, + #[serde(default)] + session_id: Option, + #[serde(default)] + model: Option, +} + +#[derive(Debug, Deserialize)] +struct AssistantMsg { + message: InnerMessage, + /// `None` for the main conversation; `Some(id)` for a subagent's output. + #[serde(default)] + parent_tool_use_id: Option, +} + +#[derive(Debug, Deserialize)] +struct InnerMessage { + #[serde(default)] + content: Vec, +} + +/// One block of a message on the wire. +/// +/// Only text is read. The CLI also reports the tool calls it forwarded and +/// their results, but every tool it has is incode's own, run by incode — which +/// shows each call and its result itself, from its own toolbox (see +/// [`crate::tool_bridge`]). Reading the CLI's copy as well would show every call +/// twice, and would take the CLI's word for what incode did. +#[derive(Debug, Deserialize)] +#[serde(tag = "type")] +enum WireContentBlock { + #[serde(rename = "text")] + Text { text: String }, + #[serde(other)] + Other, +} + +/// Subscription quota signal. Not on the published headless docs page, but +/// emitted on every run — this is the figure a subscription-backed host should +/// surface, since no per-token money is being spent. +#[derive(Debug, Deserialize)] +struct RateLimitEvent { + rate_limit_info: RateLimitInfo, +} + +#[derive(Debug, Deserialize)] +struct RateLimitInfo { + status: String, + #[serde(rename = "resetsAt", default)] + resets_at: i64, + #[serde(rename = "rateLimitType", default)] + rate_limit_type: String, + #[serde(rename = "isUsingOverage", default)] + is_using_overage: bool, +} + +#[derive(Debug, Deserialize)] +struct ResultEvent { + is_error: bool, + session_id: String, + #[serde(default)] + stop_reason: Option, + #[serde(default)] + usage: WireUsage, + /// Which models were actually BILLED for this turn, keyed by model id. + /// + /// The only trustworthy answer to "what ran?". The session's start event + /// reports the model that was *requested* — measured: asking for a model + /// that does not exist echoes that name back while the fallback quietly + /// answers. Attribution built on the request would credit work to a model + /// that never saw it. + #[serde(default, rename = "modelUsage")] + model_usage: std::collections::BTreeMap, + /// What the agent says about how the turn ended. + /// + /// On success this repeats the streamed reply and is dropped. On FAILURE it + /// is the only place the reason is written down — and it was not read at + /// all, so every failed turn reported the bare word `stop_sequence` and + /// nothing else. A whole day went into guessing a value the program was + /// receiving and discarding. + #[serde(default)] + result: Option, + /// The agent's own category for the ending, e.g. `success`, `error_*`. + #[serde(default)] + subtype: Option, +} + +#[derive(Debug, Default, Deserialize)] +struct WireUsage { + #[serde(default)] + input_tokens: u32, + #[serde(default)] + output_tokens: u32, + #[serde(default)] + cache_creation_input_tokens: u32, + #[serde(default)] + cache_read_input_tokens: u32, + /// Per request. Measured on a two-request turn: this held ONE entry, the + /// last request's, while the fields above were the sum of both. + #[serde(default)] + iterations: Vec, +} + +/// One request's tokens, as `usage.iterations` reports it. +#[derive(Debug, Default, Deserialize)] +struct WireIteration { + #[serde(default)] + input_tokens: u64, + #[serde(default)] + output_tokens: u64, + #[serde(default)] + cache_creation_input_tokens: u64, + #[serde(default)] + cache_read_input_tokens: u64, +} + +/// How full the context window was when the turn ended, when the result +/// reports both halves. +/// +/// `used` is the LAST request's tokens — input, both cache kinds and its +/// output, which is what the next request starts from. The turn's top-level +/// usage cannot stand in for it: it sums every request, counting the same +/// cached prefix once per request. +/// +/// `size` is the `contextWindow` the CLI put on the result. With more than one +/// model listed, it is the window of the model given the most input — the one +/// that held the conversation; a side model sees a fragment of it. +fn context_of( + usage: &WireUsage, + model_usage: &std::collections::BTreeMap, +) -> Option { + let last = usage.iterations.last()?; + let input_of = |entry: &serde_json::Value| -> u64 { + [ + "inputTokens", + "cacheReadInputTokens", + "cacheCreationInputTokens", + ] + .iter() + .filter_map(|key| entry.get(*key).and_then(serde_json::Value::as_u64)) + .sum() + }; + let size = model_usage + .values() + .filter_map(|entry| { + let window = entry.get("contextWindow")?.as_u64()?; + (window > 0).then_some((input_of(entry), window)) + }) + .max_by_key(|(input, _)| *input) + .map(|(_, window)| window)?; + Some(AgentEvent::Context { + used: last.input_tokens + + last.cache_read_input_tokens + + last.cache_creation_input_tokens + + last.output_tokens, + size, + }) +} + +// --------------------------------------------------------------------------- +// Mapping +// --------------------------------------------------------------------------- + +/// Map one wire line to zero or more harness events. +/// +/// Split out from the process plumbing so it can be tested against captured +/// output without spawning anything. +/// +/// Called by `consume` (`turn.rs`) for every line of a turn that is not blank. +pub(super) fn map_line(line: &str, outcome: &mut Option) -> Vec { + // A line we cannot model is data we don't understand yet, never a reason to + // abort the turn — the CLI adds event types over time. + let Ok(evt) = serde_json::from_str::(line) else { + return Vec::new(); + }; + + match evt { + CliEvent::System(s) => session_started(s).into_iter().collect(), + CliEvent::StreamEvent(e) => stream_delta(e).into_iter().collect(), + CliEvent::Assistant(a) => assistant_text(a), + CliEvent::RateLimit(r) => vec![quota(r.rate_limit_info)], + CliEvent::Result(r) => result_events(*r, outcome), + CliEvent::Other => Vec::new(), + } +} + +/// The session's start, from the `init` line. Every other `system` subtype — +/// the hook events that precede `init`, among others — says nothing. +/// +/// Called by [`map_line`]. +fn session_started(s: SystemEvent) -> Option { + if s.subtype != "init" { + return None; + } + Some(AgentEvent::SessionStarted { + session_id: s.session_id.unwrap_or_default(), + model: s.model.unwrap_or_else(|| "unknown".to_string()), + }) +} + +/// Text or thinking as it is generated, from a partial-message frame: only a +/// non-empty `text_delta` or `thinking_delta` of a `content_block_delta`. +/// +/// Called by [`map_line`]. +fn stream_delta(e: StreamEvent) -> Option { + // Subagent output is not the main conversation's text — the same rule + // `assistant_text` applies to whole blocks. + if e.parent_tool_use_id.is_some() || e.event.event_type != "content_block_delta" { + return None; + } + let delta = e.event.delta?; + if delta.delta_type == "text_delta" && !delta.text.is_empty() { + Some(AgentEvent::TextDelta(delta.text)) + } else if delta.delta_type == "thinking_delta" && !delta.thinking.is_empty() { + Some(AgentEvent::Thinking(delta.thinking)) + } else { + None + } +} + +/// Each text block of a whole assistant message, in order. +/// +/// Called by [`map_line`]. +fn assistant_text(a: AssistantMsg) -> Vec { + // Subagent output is not the main conversation's text. + if a.parent_tool_use_id.is_some() { + return Vec::new(); + } + a.message + .content + .into_iter() + .filter_map(|block| match block { + WireContentBlock::Text { text } => Some(AgentEvent::Text(text)), + WireContentBlock::Other => None, + }) + .collect() +} + +/// The subscription quota a `rate_limit_event` reports. +/// +/// Called by [`map_line`]. +fn quota(info: RateLimitInfo) -> AgentEvent { + AgentEvent::Quota { + status: info.status, + kind: info.rate_limit_type, + resets_at: info.resets_at, + using_overage: info.is_using_overage, + } +} + +/// The token counts and the context of a `result` line, with the turn's +/// outcome written to `outcome`. +/// +/// Called by [`map_line`]. +fn result_events(r: ResultEvent, outcome: &mut Option) -> Vec { + let mut events = vec![AgentEvent::Usage { + input_tokens: r.usage.input_tokens, + output_tokens: r.usage.output_tokens, + cache_creation_tokens: r.usage.cache_creation_input_tokens, + cache_read_tokens: r.usage.cache_read_input_tokens, + }]; + if let Some(context) = context_of(&r.usage, &r.model_usage) { + events.push(context); + } + // NOTE: the result line also carries a `result` field holding the + // final assembled text. It repeats what the assistant content + // blocks already delivered, so emitting both duplicates every + // reply. The incremental stream is the single source of truth. + let detail = failure_detail(r.is_error, r.result, r.subtype); + *outcome = Some(TurnOutcome { + session_id: r.session_id, + stop_reason: r.stop_reason.unwrap_or_else(|| "unknown".to_string()), + is_error: r.is_error, + detail, + // The keys are model ids; the values are per-model token counts + // this harness has no use for. Sorted by the map, so the record + // is the same on every run for the same turn. + served_by: r.model_usage.into_keys().collect(), + }); + events +} + +/// What the agent said about a failed turn: its category and its sentence, +/// whichever it gave, trimmed. +/// +/// Only when the turn FAILED. On success `result` is a copy of the reply +/// that already streamed, and carrying it would duplicate every answer. +/// +/// Called by [`result_events`]. +fn failure_detail( + is_error: bool, + result: Option, + subtype: Option, +) -> Option { + if !is_error { + return None; + } + let said = result.unwrap_or_default(); + let kind = subtype.unwrap_or_default(); + let joined = match (kind.trim(), said.trim()) { + ("", "") => String::new(), + (k, "") => k.to_string(), + ("", t) => t.to_string(), + (k, t) => format!("{k}: {t}"), + }; + (!joined.is_empty()).then_some(joined) +} diff --git a/src/agent/claude_code/wire_tests.rs b/src/agent/claude_code/wire_tests.rs new file mode 100644 index 0000000..3e28ac8 --- /dev/null +++ b/src/agent/claude_code/wire_tests.rs @@ -0,0 +1,899 @@ +//! What the CLI's stream-json lines become, one line at a time +//! (`map_line`) and as a whole turn through the stream loop (`consume`). +//! Fixtures are real lines captured from Claude Code 2.1.229. + +use std::io::{BufRead, BufReader}; + +use super::tests::{outcome_of, usage_of}; +use super::turn::{consume, consume_stream}; +use super::wire::map_line; +use super::*; +use crate::tool_bridge::Incoming; + +/// **A cancelled turn stops reading and says so.** Without a distinct +/// error the caller cannot tell "the user pressed Ctrl-C" from "the agent +/// crashed", and would report a crash. +#[test] +fn a_cancelled_turn_stops_and_names_itself() { + let token = crate::runtime::cancel::CancelToken::new(); + token.cancel(); + let lines = "{\"type\":\"system\",\"subtype\":\"init\",\"session_id\":\"s\"}\n"; + let mut session = None; + let mut seen = Vec::new(); + let err = consume_stream( + std::io::BufReader::new(lines.as_bytes()), + &mut session, + &mut |e: &AgentEvent| seen.push(e.clone()), + Some(&token), + ) + .expect_err("a cancelled turn must not report success"); + assert_eq!(err.to_string(), CANCELLED); + assert!(seen.is_empty(), "it must stop BEFORE handling more output"); +} + +/// Without cancellation the same stream is read normally — the control +/// that proves the test above is measuring the flag and not the fixture. +#[test] +fn the_same_stream_reads_normally_when_not_cancelled() { + let lines = "{\"type\":\"system\",\"subtype\":\"init\",\"session_id\":\"s\"}\n"; + let mut session = None; + let mut seen = Vec::new(); + consume_stream( + std::io::BufReader::new(lines.as_bytes()), + &mut session, + &mut |e: &AgentEvent| seen.push(e.clone()), + None, + ) + .expect("it reads"); + assert_eq!(session.as_deref(), Some("s")); + assert_eq!(seen.len(), 1); +} + +/// **Captured from a real run, not composed here.** The delta shape is the +/// CLI's, and a parser written against an imagined one would pass its own +/// test and fail the first real line. +#[test] +fn a_text_delta_from_the_real_wire_becomes_a_delta_event() { + let line = r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"h"}},"session_id":"a77936b0","parent_tool_use_id":null,"uuid":"bfc09fc8"}"#; + let mut outcome = None; + let events = map_line(line, &mut outcome); + assert_eq!(events, vec![AgentEvent::TextDelta("h".to_string())]); +} + +/// A subagent's deltas are not the main conversation's text — the same rule +/// the whole-block branch already applies. +#[test] +fn a_subagents_delta_is_not_the_conversation() { + let line = r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"h"}},"parent_tool_use_id":"toolu_1"}"#; + let mut outcome = None; + assert!(map_line(line, &mut outcome).is_empty()); +} + +/// The other stream frames carry no user-facing text and must stay silent — +/// message_start and content_block_stop arrive for every single turn. +#[test] +fn stream_frames_that_are_not_text_produce_nothing() { + let mut outcome = None; + for line in [ + r#"{"type":"stream_event","event":{"type":"message_start","message":{"model":"m"}},"parent_tool_use_id":null}"#, + r#"{"type":"stream_event","event":{"type":"content_block_stop","index":0},"parent_tool_use_id":null}"#, + r#"{"type":"stream_event","event":{"type":"message_stop"},"parent_tool_use_id":null}"#, + ] { + assert!( + map_line(line, &mut outcome).is_empty(), + "should be silent: {line}" + ); + } +} + +const REAL_ASSISTANT: &str = r#"{"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CdyZz5W5Z65fqwbCLUrvy","type":"message","role":"assistant","content":[{"type":"text","text":"OK"}],"stop_reason":null,"usage":{"input_tokens":1,"output_tokens":1}},"parent_tool_use_id":null,"session_id":"e2996c17-f358-46fa-89b9-e757a4742abe"}"#; + +const REAL_RATE_LIMIT: &str = r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed","resetsAt":1786575600,"rateLimitType":"five_hour","overageStatus":"rejected","isUsingOverage":false},"session_id":"e2996c17-f358-46fa-89b9-e757a4742abe"}"#; + +/// The real result line puts `type` near the END of the object — a +/// deserializer that assumes `type` comes first will not parse it. +/// A FAILED result, in the wire shape the agent actually emits. +/// +/// The `result` and `subtype` fields here were not deserialized at all, so +/// a turn that ended this way was reported to the operator as the single +/// word `stop_sequence` — for an entire day, while the sentence explaining +/// it sat unread in the same line. +const FAILED_RESULT: &str = r#"{"is_error":true,"duration_api_ms":900,"num_turns":3,"stop_reason":"stop_sequence","session_id":"e2996c17-f358-46fa-89b9-e757a4742abe","usage":{"input_tokens":1,"output_tokens":2},"subtype":"error_during_execution","result":"tool use was interrupted before it completed","type":"result","duration_ms":1200}"#; + +const REAL_RESULT: &str = r#"{"is_error":false,"duration_api_ms":1846,"num_turns":1,"stop_reason":"end_turn","session_id":"393279e4-f6e9-4d64-bd17-57926443ef94","total_cost_usd":0.399,"usage":{"input_tokens":1,"cache_creation_input_tokens":36371,"cache_read_input_tokens":23432,"output_tokens":4},"subtype":"success","result":"OK","type":"result","duration_ms":31639}"#; + +fn map(line: &str) -> (Vec, Option) { + let mut outcome = None; + let events = map_line(line, &mut outcome); + (events, outcome) +} + +#[test] +fn parses_assistant_text_from_real_output() { + let (events, _) = map(REAL_ASSISTANT); + assert_eq!(events, vec![AgentEvent::Text("OK".to_string())]); +} + +/// A subagent's messages must not be mistaken for the main conversation. +#[test] +fn subagent_output_is_not_emitted_as_main_text() { + let sub = REAL_ASSISTANT.replace( + r#""parent_tool_use_id":null"#, + r#""parent_tool_use_id":"toolu_1""#, + ); + assert_ne!(sub, REAL_ASSISTANT, "fixture must actually differ"); + let (events, _) = map(&sub); + assert!( + events.is_empty(), + "subagent text must not surface as main-conversation output; got {events:?}" + ); +} + +#[test] +fn parses_subscription_quota_signal() { + let (events, _) = map(REAL_RATE_LIMIT); + assert_eq!( + events, + vec![AgentEvent::Quota { + status: "allowed".to_string(), + kind: "five_hour".to_string(), + resets_at: 1_786_575_600, + using_overage: false, + }] + ); +} + +/// Guards the field-order hazard: `type` is not the first key on this line. +#[test] +fn a_failed_turn_reports_what_the_agent_said_about_it() { + let (_, outcome) = map(FAILED_RESULT); + let outcome = outcome.expect("the result line produces an outcome"); + assert!(outcome.is_error); + let said = outcome.failure(); + assert!( + said.contains("tool use was interrupted"), + "the agent's own explanation must reach the operator: {said}" + ); + assert!( + said.contains("error_during_execution"), + "and so must the category: {said}" + ); + assert!( + !said.contains("gave no reason"), + "it DID give a reason: {said}" + ); +} + +#[test] +fn a_successful_turn_carries_no_detail() { + // On success `result` repeats the streamed reply; carrying it would + // print every answer twice. + let (_, outcome) = map(REAL_RESULT); + assert_eq!(outcome.expect("outcome").detail, None); +} + +#[test] +fn parses_result_line_despite_type_being_last() { + let (events, outcome) = map(REAL_RESULT); + let outcome = outcome.expect("result line must yield a turn outcome"); + assert_eq!(outcome.stop_reason, "end_turn"); + assert!(!outcome.is_error); + assert_eq!(outcome.session_id, "393279e4-f6e9-4d64-bd17-57926443ef94"); + assert_eq!( + events, + vec![AgentEvent::Usage { + input_tokens: 1, + output_tokens: 4, + cache_creation_tokens: 36371, + cache_read_tokens: 23432, + }] + ); +} + +/// A result line from a real two-request turn (`claude -p … --output-format +/// stream-json --verbose`, 2026-09-25), trimmed to the fields read here. +/// The top-level usage is the SUM of both requests; `iterations` holds the +/// last request only; `modelUsage` carries the window. +const REAL_TWO_REQUEST_RESULT: &str = r#"{"type":"result","subtype":"success","is_error":false,"num_turns":2,"stop_reason":"end_turn","session_id":"sess-probe","total_cost_usd":0.19127059999999999,"usage":{"input_tokens":4,"cache_creation_input_tokens":22197,"cache_read_input_tokens":55293,"output_tokens":131,"iterations":[{"input_tokens":2,"output_tokens":4,"cache_read_input_tokens":38663,"cache_creation_input_tokens":164,"type":"message"}]},"modelUsage":{"claude-opus-5-5":{"inputTokens":4,"outputTokens":131,"cacheReadInputTokens":55293,"cacheCreationInputTokens":22197,"webSearchRequests":0,"costUSD":0.19127059999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":0,"canonicalModel":"claude-opus-5-5","provider":"firstParty","costBasis":"list"}},"result":"banana"}"#; + +/// **CONTEXT USED IS THE LAST REQUEST, NOT THE TURN'S SUM.** +/// +/// The sum counts the same cached prefix once per request — 77 494 input +/// tokens here for a context that held 38 829 — so it would show a window +/// twice as full as it is. The window is the one the CLI reported. +#[test] +fn a_result_reports_the_last_requests_context_and_the_reported_window() { + let (events, _) = map(REAL_TWO_REQUEST_RESULT); + let context: Vec<&AgentEvent> = events + .iter() + .filter(|e| matches!(e, AgentEvent::Context { .. })) + .collect(); + assert_eq!( + context, + vec![&AgentEvent::Context { + used: 2 + 38_663 + 164 + 4, + size: 1_000_000, + }] + ); +} + +/// With more than one model on the result, the window is the one of the +/// model that held the conversation: the one given the most input. A side +/// model sees a fragment of it. (The second entry is added to the real +/// line for this test.) +#[test] +fn the_window_is_the_conversations_model_not_a_side_one() { + let line = REAL_TWO_REQUEST_RESULT.replace( + r#""modelUsage":{"#, + r#""modelUsage":{"side-model":{"inputTokens":900,"cacheReadInputTokens":0,"cacheCreationInputTokens":0,"contextWindow":200000},"#, + ); + let (events, _) = map(&line); + assert!( + events.contains(&AgentEvent::Context { + used: 38_833, + size: 1_000_000 + }), + "{events:?}" + ); +} + +/// No window reported, no context event — the token counts still go out +/// as [`AgentEvent::Usage`]. +#[test] +fn no_window_means_no_context_event() { + let (events, _) = map(REAL_RESULT); + assert!( + !events + .iter() + .any(|e| matches!(e, AgentEvent::Context { .. })), + "{events:?}" + ); +} + +/// The final text must be emitted exactly once. The result line repeats it, +/// so counting both duplicates every reply the user sees. +#[test] +fn final_text_is_not_emitted_twice() { + let mut outcome = None; + let mut texts = Vec::new(); + for line in [REAL_ASSISTANT, REAL_RESULT] { + for e in map_line(line, &mut outcome) { + if let AgentEvent::Text(t) = e { + texts.push(t); + } + } + } + assert_eq!( + texts, + vec!["OK".to_string()], + "assistant blocks and the result line both carry the reply; only one may be emitted" + ); +} + +/// An unrecognised line must be skipped, not abort the turn. +#[test] +fn unknown_event_type_is_skipped() { + let (events, outcome) = map(r#"{"type":"some_future_event","payload":{}}"#); + assert!(events.is_empty()); + assert!(outcome.is_none()); +} + +#[test] +fn malformed_line_does_not_panic() { + let (events, outcome) = map("not json at all"); + assert!(events.is_empty()); + assert!(outcome.is_none()); +} + +/// Drive the stream loop the way a real turn does, over canned bytes. +fn drive(stream: &str) -> (Vec, Option, Option) { + let mut session = None; + let mut seen = Vec::new(); + let outcome = { + let mut sink = |e: &AgentEvent| seen.push(e.clone()); + consume_stream( + std::io::BufReader::new(std::io::Cursor::new(stream.as_bytes())), + &mut session, + &mut sink, + None, + ) + .expect("a well-formed stream must not error") + }; + (seen, session, outcome) +} + +/// A whole turn, in the order and shape the real CLI emits it — including +/// the hook events that precede `init` when the agent loads user config. +const REAL_SESSION: &str = concat!( + r#"{"type":"system","subtype":"hook_started","hook_id":"b5d0"}"#, + "\n", + r#"{"type":"system","subtype":"hook_response","hook_id":"b5d0"}"#, + "\n", + r#"{"type":"system","subtype":"init","session_id":"sess-real","model":"claude-opus-5[1m]"}"#, + "\n", + "\n", + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"OK"}]},"parent_tool_use_id":null}"#, + "\n", + r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed","resetsAt":1786575600,"rateLimitType":"five_hour","isUsingOverage":false}}"#, + "\n", + r#"{"is_error":false,"stop_reason":"end_turn","session_id":"sess-real","usage":{"input_tokens":1,"output_tokens":4,"cache_creation_input_tokens":36371,"cache_read_input_tokens":23432},"type":"result"}"#, + "\n", +); + +/// The stream loop must turn a real turn into the right events, in order, +/// and skip the blank line without treating it as data. +#[test] +fn consumes_a_real_turn_into_ordered_events() { + let (events, session, outcome) = drive(REAL_SESSION); + + assert_eq!( + events, + vec![ + AgentEvent::SessionStarted { + session_id: "sess-real".to_string(), + model: "claude-opus-5[1m]".to_string(), + }, + AgentEvent::Text("OK".to_string()), + AgentEvent::Quota { + status: "allowed".to_string(), + kind: "five_hour".to_string(), + resets_at: 1_786_575_600, + using_overage: false, + }, + AgentEvent::Usage { + input_tokens: 1, + output_tokens: 4, + cache_creation_tokens: 36371, + cache_read_tokens: 23432, + }, + ], + "hook events must be dropped and the rest emitted in stream order" + ); + + assert_eq!(session.as_deref(), Some("sess-real")); + let outcome = outcome.expect("a result line must produce an outcome"); + assert_eq!(outcome.stop_reason, "end_turn"); + assert!(!outcome.is_error); +} + +/// The session id must be captured even if the turn dies before the result +/// line — otherwise a crashed turn forces the next one to start fresh and +/// re-pay the whole prompt prefix. +#[test] +fn session_is_captured_even_when_the_turn_never_completes() { + let truncated = REAL_SESSION + .lines() + .take(3) // hook, hook, init — then the agent dies + .collect::>() + .join("\n"); + + let (_, session, outcome) = drive(&truncated); + + assert_eq!( + session.as_deref(), + Some("sess-real"), + "a turn that dies after init must still leave a resumable session" + ); + assert!( + outcome.is_none(), + "no result line means no outcome — the caller must see the failure" + ); +} + +/// Garbage in the middle of a stream must not abort the turn; the CLI adds +/// event types over time and an unknown line is not a failure. +#[test] +fn a_corrupt_line_does_not_abort_the_turn() { + let mut polluted = String::from(REAL_SESSION); + polluted = polluted.replace( + r#"{"type":"rate_limit_event""#, + r#"{{{NOT JSON}}} +{"type":"rate_limit_event""#, + ); + + let (events, _, outcome) = drive(&polluted); + assert!( + outcome.is_some(), + "the turn must still complete despite an unparseable line" + ); + assert!(events + .iter() + .any(|e| matches!(e, AgentEvent::Text(t) if t == "OK"))); +} + +#[test] +fn session_id_is_captured_for_resume() { + let (events, _) = map( + r#"{"type":"system","subtype":"init","session_id":"abc-123","model":"claude-opus-5[1m]"}"#, + ); + assert_eq!( + events, + vec![AgentEvent::SessionStarted { + session_id: "abc-123".to_string(), + model: "claude-opus-5[1m]".to_string(), + }] + ); +} + +/// **What actually ran, from the billing record.** Captured from a real +/// turn: the request named a model that does not exist, the CLI warned, and +/// the FALLBACK answered — so `modelUsage` and the requested name disagree, +/// which is exactly the case attribution has to get right. +#[test] +fn the_served_model_comes_from_the_billing_record_not_the_request() { + let real = r#"{"type":"result","is_error":false,"session_id":"s-1", + "stop_reason":"end_turn","result":"OK", + "usage":{"input_tokens":1,"output_tokens":4}, + "modelUsage":{"claude-haiku-4-5-20251001":{"inputTokens":1,"outputTokens":4}}}"#; + let (_, outcome) = map(real); + let outcome = outcome.expect("a result line produces an outcome"); + assert_eq!( + outcome.served_by, + vec!["claude-haiku-4-5-20251001".to_string()] + ); +} + +/// **Not reported is empty, never guessed.** A backend that says nothing +/// about the model must not have the requested one filled in for it. +#[test] +fn a_result_without_a_billing_record_reports_no_model() { + let (_, outcome) = map(REAL_RESULT); + assert!( + outcome.expect("an outcome").served_by.is_empty(), + "an absent billing record must stay absent" + ); +} + +/// A summarized thinking delta is the model's reasoning; an empty one — +/// the default display — is nothing. +#[test] +fn a_thinking_delta_becomes_a_thought_and_an_empty_one_nothing() { + let line = r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"This is a","estimated_tokens":null}},"session_id":"c2","parent_tool_use_id":null,"thinking_display":"summarized"}"#; + let (events, _) = map(line); + assert!( + matches!(events.as_slice(), [AgentEvent::Thinking(t)] if t == "This is a"), + "{events:?}" + ); + let empty = r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"","estimated_tokens":50}},"session_id":"d4","parent_tool_use_id":null,"thinking_display":"updates"}"#; + assert!(map(empty).0.is_empty()); +} + +/// One request to the bridge, as the tool server sends it. +fn raw_call(addr: &str, token: &str, name: &str, input: serde_json::Value) -> serde_json::Value { + use std::io::Write as _; + let mut stream = std::net::TcpStream::connect(addr).expect("connect"); + let body = serde_json::json!({"token": token, "op": "call", "name": name, "input": input}); + writeln!(stream, "{body}").expect("send"); + let mut line = String::new(); + BufReader::new(stream).read_line(&mut line).expect("reply"); + serde_json::from_str(&line).expect("json reply") +} + +/// **A TOOL CALL MID-TURN IS RUN BY incode's TOOLBOX, AND SHOWN ONCE.** +/// +/// The CLI's stream carries its own record of the call it forwarded — the +/// `tool_use` and `tool_result` blocks. Those are not shown: the call is +/// shown as incode ran it, under incode's name for the tool. +#[test] +fn a_tool_call_mid_turn_runs_in_incodes_toolbox_and_is_shown_once() { + let ws = tempfile::tempdir().expect("ws"); + let mut tools = crate::toolbox::Toolbox::new(ws.path(), true); + let (to, from) = std::sync::mpsc::channel(); + let bridge = + crate::tool_bridge::Bridge::open(to.clone(), Incoming::Tool, None).expect("bridge"); + let [(_, addr), (_, token)] = bridge.env(); + + let cli = std::thread::spawn(move || { + let say = |line: &str| { + let _ = to.send(Incoming::Line(line.to_string())); + }; + say(r#"{"type":"system","subtype":"init","session_id":"s-bridge","model":"m"}"#); + say( + r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_1","name":"mcp__incode__Write","input":{"path":"hello.txt","content":"hi"}}]},"parent_tool_use_id":null}"#, + ); + let reply = raw_call( + &addr, + &token, + "Write", + serde_json::json!({"path": "hello.txt", "content": "hi"}), + ); + say( + r#"{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"toolu_1","content":"wrote it","is_error":false}]},"parent_tool_use_id":null}"#, + ); + say( + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"done"}]},"parent_tool_use_id":null}"#, + ); + say( + r#"{"type":"result","is_error":false,"stop_reason":"end_turn","session_id":"s-bridge","usage":{"input_tokens":1,"output_tokens":1}}"#, + ); + let _ = to.send(Incoming::Ended); + reply + }); + + let mut session = None; + let mut seen = Vec::new(); + let mut calls = 0; + let outcome = consume( + &from, + &mut session, + &mut |e: &AgentEvent| seen.push(e.clone()), + None, + &mut tools, + &mut calls, + ) + .expect("the turn completes"); + drop(bridge); + let reply = cli.join().expect("the fake CLI"); + + assert_eq!(reply["ok"], true, "{reply}"); + assert_eq!( + std::fs::read_to_string(ws.path().join("hello.txt")).expect("written by incode"), + "hi" + ); + assert!(outcome.is_some_and(|o| !o.is_error)); + let uses: Vec<&AgentEvent> = seen + .iter() + .filter(|e| matches!(e, AgentEvent::ToolUse { .. })) + .collect(); + assert_eq!(uses.len(), 1, "one call, shown once: {seen:?}"); + assert!( + matches!(uses[0], AgentEvent::ToolUse { name, id, .. } if name == "Write" && id == "incode-1"), + "shown under incode's own name and id: {seen:?}" + ); + let results: Vec<&AgentEvent> = seen + .iter() + .filter(|e| matches!(e, AgentEvent::ToolResult { .. })) + .collect(); + assert_eq!(results.len(), 1, "{seen:?}"); + assert!( + matches!(results[0], AgentEvent::ToolResult { output, is_error: false, .. } if !output.contains("wrote it")), + "the result is incode's, not the CLI's echo: {seen:?}" + ); +} + +/// **A QUIET TURN STILL STOPS.** Nothing arrives — the model thinking, a +/// long command — and the stop lands within the poll, not at the next +/// line the CLI happens to print. +#[test] +fn a_quiet_turn_stops_promptly_when_cancelled() { + let token = crate::runtime::cancel::CancelToken::new(); + let (to, from) = std::sync::mpsc::channel::(); + let stopper = token.clone(); + std::thread::spawn(move || { + std::thread::sleep(std::time::Duration::from_millis(300)); + stopper.cancel(); + }); + let mut tools = crate::toolbox::Toolbox::new(std::path::Path::new("."), true); + let started = std::time::Instant::now(); + let err = consume( + &from, + &mut None, + &mut |_| {}, + Some(&token), + &mut tools, + &mut 0, + ) + .expect_err("a stopped turn is not a finished one"); + assert_eq!(err.to_string(), CANCELLED); + assert!( + started.elapsed() < std::time::Duration::from_secs(5), + "{:?}", + started.elapsed() + ); + drop(to); +} + +// --------------------------------------------------------------------------- +// Pinned behaviour: every wire shape `map_line` reads, with the events and +// the outcome each produces. +// --------------------------------------------------------------------------- + +/// One pinned line: the events it becomes and the outcome it writes. +type Case = (&'static str, Vec, Option); + +fn text(t: &str) -> AgentEvent { + AgentEvent::Text(t.to_string()) +} + +fn started(s: &str, m: &str) -> AgentEvent { + AgentEvent::SessionStarted { + session_id: s.to_string(), + model: m.to_string(), + } +} + +/// **EVERY WIRE SHAPE, AND WHAT IT BECOMES.** One line per branch of the +/// mapping — each event type, the subagent and empty cases, every way a +/// failed result can describe itself, and lines that do not parse. +#[test] +fn the_map_line_corpus_is_pinned() { + let cases = [ + system_cases(), + stream_cases(), + message_and_quota_cases(), + result_cases(), + context_cases(), + unparsed_cases(), + ] + .concat(); + assert_eq!(cases.len(), 47, "the corpus lost or gained a line"); + for (line, events, outcome) in cases { + let mut got = None; + assert_eq!(map_line(line, &mut got), events, "events of {line}"); + assert_eq!(got, outcome, "outcome of {line}"); + } +} + +/// `system` lines: only `init` says anything. +fn system_cases() -> Vec { + vec![ + ( + r#"{"type":"system","subtype":"init","session_id":"s1","model":"m1"}"#, + vec![started("s1", "m1")], + None, + ), + ( + r#"{"type":"system","subtype":"init"}"#, + vec![started("", "unknown")], + None, + ), + ( + r#" {"type":"system","subtype":"init","session_id":"s2"} "#, + vec![started("s2", "unknown")], + None, + ), + ( + r#"{"type":"system","subtype":"hook_started","hook_id":"h"}"#, + Vec::new(), + None, + ), + (r#"{"type":"system"}"#, Vec::new(), None), + ] +} + +/// Partial-message frames: only non-empty main-conversation deltas. +fn stream_cases() -> Vec { + vec![ + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hi"}},"parent_tool_use_id":null}"#, + vec![AgentEvent::TextDelta("hi".to_string())], + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":""}}}"#, + Vec::new(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta"}}}"#, + Vec::new(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"why"}}}"#, + vec![AgentEvent::Thinking("why".to_string())], + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":""}}}"#, + Vec::new(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"x"}},"parent_tool_use_id":"toolu_9"}"#, + Vec::new(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"x"}},"parent_tool_use_id":"toolu_9"}"#, + Vec::new(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0},"parent_tool_use_id":null}"#, + Vec::new(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"input_json_delta","partial_json":"{}"}}}"#, + Vec::new(), + None, + ), + ( + r#"{"type":"stream_event","event":{"type":"content_block_start","delta":{"type":"text_delta","text":"x"}}}"#, + Vec::new(), + None, + ), + (r#"{"type":"stream_event"}"#, Vec::new(), None), + ] +} + +/// Whole messages, the tool-result lines incode already showed, and the +/// subscription quota. +fn message_and_quota_cases() -> Vec { + vec![ + ( + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"a"},{"type":"tool_use","id":"t1","name":"Write","input":{}},{"type":"thinking","thinking":"hm"},{"type":"text","text":"b"}]},"parent_tool_use_id":null}"#, + vec![text("a"), text("b")], + None, + ), + ( + r#"{"type":"assistant","message":{"content":[{"type":"text","text":""}]}}"#, + vec![text("")], + None, + ), + (r#"{"type":"assistant","message":{}}"#, Vec::new(), None), + ( + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"sub"}]},"parent_tool_use_id":"toolu_2"}"#, + Vec::new(), + None, + ), + (r#"{"type":"assistant"}"#, Vec::new(), None), + // user lines carry tool results incode already showed + ( + r#"{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"t1","content":"ok"}]}}"#, + Vec::new(), + None, + ), + // rate_limit_event + ( + r#"{"type":"rate_limit_event","rate_limit_info":{"status":"rejected"}}"#, + vec![AgentEvent::Quota { + status: "rejected".to_string(), + kind: String::new(), + resets_at: 0, + using_overage: false, + }], + None, + ), + ( + r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning","resetsAt":17,"rateLimitType":"seven_day","isUsingOverage":true}}"#, + vec![AgentEvent::Quota { + status: "allowed_warning".to_string(), + kind: "seven_day".to_string(), + resets_at: 17, + using_overage: true, + }], + None, + ), + (r#"{"type":"rate_limit_event"}"#, Vec::new(), None), + ] +} + +/// `result` lines: the outcome, and every way a failure describes itself. +fn result_cases() -> Vec { + vec![ + ( + r#"{"type":"result","is_error":false,"session_id":"r1"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r1", "unknown", false, None, &[])), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r1","stop_reason":"max_tokens","result":"the reply","subtype":"success","usage":{"input_tokens":3,"output_tokens":4,"cache_creation_input_tokens":5,"cache_read_input_tokens":6}}"#, + vec![usage_of(3, 4, 5, 6)], + Some(outcome_of("r1", "max_tokens", false, None, &[])), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","stop_reason":"stop_sequence","subtype":"error_x","result":"said"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of( + "r2", + "stop_sequence", + true, + Some("error_x: said"), + &[], + )), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","subtype":"error_max_turns"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of( + "r2", + "unknown", + true, + Some("error_max_turns"), + &[], + )), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","result":"boom"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r2", "unknown", true, Some("boom"), &[])), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2"}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r2", "unknown", true, None, &[])), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","subtype":" ","result":" "}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r2", "unknown", true, None, &[])), + ), + ( + r#"{"type":"result","is_error":true,"session_id":"r2","subtype":" k ","result":" t "}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r2", "unknown", true, Some("k: t"), &[])), + ), + ] +} + +/// `result` lines with a context window or without one, the billed models, +/// and results missing a required field. +fn context_cases() -> Vec { + vec![ + ( + r#"{"type":"result","is_error":false,"session_id":"r3","usage":{"input_tokens":1,"iterations":[{"input_tokens":9},{"input_tokens":10,"output_tokens":5,"cache_read_input_tokens":100,"cache_creation_input_tokens":20}]},"modelUsage":{"b-model":{"inputTokens":50,"contextWindow":200000},"a-model":{"inputTokens":1,"contextWindow":1000}}}"#, + vec![ + usage_of(1, 0, 0, 0), + AgentEvent::Context { + used: 135, + size: 200_000, + }, + ], + Some(outcome_of( + "r3", + "unknown", + false, + None, + &["a-model", "b-model"], + )), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r4","usage":{"iterations":[]},"modelUsage":{"m":{"contextWindow":200000}}}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r4", "unknown", false, None, &["m"])), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r5","usage":{"iterations":[{"input_tokens":1}]},"modelUsage":{"m":{"contextWindow":0}}}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r5", "unknown", false, None, &["m"])), + ), + ( + r#"{"type":"result","is_error":false,"session_id":"r6","usage":{"iterations":[{"input_tokens":1}]},"modelUsage":{"m":{"inputTokens":1}}}"#, + vec![usage_of(0, 0, 0, 0)], + Some(outcome_of("r6", "unknown", false, None, &["m"])), + ), + (r#"{"type":"result","is_error":false}"#, Vec::new(), None), + (r#"{"type":"result","session_id":"r7"}"#, Vec::new(), None), + ] +} + +/// Lines that are unknown or do not parse: nothing, and no outcome. +fn unparsed_cases() -> Vec { + vec![ + ( + r#"{"type":"some_future_event","payload":{}}"#, + Vec::new(), + None, + ), + ("not json", Vec::new(), None), + ("", Vec::new(), None), + ("[]", Vec::new(), None), + ("null", Vec::new(), None), + ("{}", Vec::new(), None), + (r#"{"type":42}"#, Vec::new(), None), + ( + r#"{"type":"assistant","message":{"content":[{"type":"text"}]}}"#, + Vec::new(), + None, + ), + ] +} + +/// Only a result line touches the outcome; every other line leaves an +/// earlier one in place. +#[test] +fn only_a_result_line_writes_the_outcome() { + let earlier = outcome_of("before", "end_turn", false, None, &[]); + for line in [ + r#"{"type":"system","subtype":"init","session_id":"s"}"#, + r#"{"type":"assistant","message":{"content":[{"type":"text","text":"a"}]}}"#, + r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed"}}"#, + "not json", + ] { + let mut outcome = Some(earlier.clone()); + map_line(line, &mut outcome); + assert_eq!(outcome.as_ref(), Some(&earlier), "{line}"); + } +} diff --git a/src/wiring.rs b/src/wiring.rs index 0a6dcb4..4be79d3 100644 --- a/src/wiring.rs +++ b/src/wiring.rs @@ -54,7 +54,7 @@ use std::path::{Path, PathBuf}; /// actually happened, six times. /// /// Lower it whenever the number falls. The test fails and tells you to. -pub const MAX_UNWIRED: usize = 41; +pub const MAX_UNWIRED: usize = 38; /// A `pub` item nothing outside its own file calls. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] From 5326ce8f7e23df431cb9cf11013c23102828885c Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Fri, 23 Oct 2026 14:59:56 -0600 Subject: [PATCH 3/3] claude_code: two pointers name where the split put things From the independent review of #63: budget_for_spawn's doc named claude_code.rs for run_once (now claude_code/turn.rs), and contracts.json's RateLimitInfo _owner named claude_code.rs (now claude_code/wire.rs). Documentation only; nothing reads _owner. --- .incode/contracts.json | 2 +- src/agent/mod.rs | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.incode/contracts.json b/.incode/contracts.json index 871d8e5..c6d5048 100644 --- a/.incode/contracts.json +++ b/.incode/contracts.json @@ -235,7 +235,7 @@ } }, "RateLimitInfo": { - "_owner": "src/agent/claude_code.rs — subscription quota, reported instead of a dollar figure. Wire names are camelCase; the Rust names are snake_case via serde rename.", + "_owner": "src/agent/claude_code/wire.rs — subscription quota, reported instead of a dollar figure. Wire names are camelCase; the Rust names are snake_case via serde rename.", "fields": { "status": "string — `allowed` is the only value that means work can proceed", "resets_at": "i64 (wire: resetsAt)", diff --git a/src/agent/mod.rs b/src/agent/mod.rs index da7c6fe..1185b69 100644 --- a/src/agent/mod.rs +++ b/src/agent/mod.rs @@ -366,7 +366,8 @@ pub const MIN_CONTEXT_BUDGET: usize = 4_000; /// 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.rs` (`run_once`). +/// `agy.rs` and `codex.rs` (`full_prompt`) and `claude_code/turn.rs` +/// (`run_once`). pub fn budget_for_spawn( prompt: &str, system_context: &[String],