//!

//! What this file owns is the part that is coder-lite's:

//!

//! - [`SYSTEM_INSTRUCTIONS`], carried verbatim. It is the reason the session

//! - The system prompt, composed from the staged `system-prompt` surface

//!   (`surfaces/coder/system-prompt.v1.json`) and carried verbatim. It is

//!   the reason the session

//!   answers as a terminal rather than as an assistant, and a merge that

//!   reworded it would have changed the product.

//! - [`Control`], the one-way channel the TUI loop reads. Text, tool calls,

use std::sync::mpsc::Sender;

use std::sync::{Arc, Mutex};

use openagents_cli::surfaces::system_prompt as prompt;

use openagents_cli::runtime::{

    ChatMessage, CoderRuntimeSession, Lane, ToolEvent, TurnUsage,

};

use openagents_cli::tools::{DelegationGate, HarnessToolRegistry, ToolDefinition};

/// coder-lite's voice. Carried verbatim from the first version of this file;

/// see the module header for why it does not move.

const SYSTEM_INSTRUCTIONS: &str = "You are OpenAgents Coder. Do not say you are from Google, Anthropic, OpenAI, or any other company. Do not mention your model, training, or architecture. Respond as a neutral, terse terminal: no greetings, no \"As an AI\", no explanations of your role, and no unnecessary padding. Use short sentences and dense, factual output. Answer questions directly. Output only code and minimal context when asked for code.";

type Failure = Box<dyn std::error::Error + Send + Sync>;

/// The system message this session opens with.

///

/// [`SYSTEM_INSTRUCTIONS`] first and unchanged, then the tools — because a

/// The staged instructions first and unchanged, then the tools — because a

/// model that is told it has no tools when it has five will not use them, and

/// one told it has tools it does not have will claim to have run them. The

/// list is generated from what was actually declared, so the two cannot

/// disagree.

pub fn system_prompt(tools: &[ToolDefinition]) -> String {

    let mut lines = vec![SYSTEM_INSTRUCTIONS.to_string(), String::new()];

    let mut lines = vec![prompt::CODER_LITE_INSTRUCTIONS.to_string(), String::new()];

    if tools.is_empty() {

        lines.push(prompt::CODER_LITE_NO_TOOLS.to_string());

    } else {

        lines.push(

            "You have no tools in this session: you cannot read or write files, run commands, or \

             reach anything outside this conversation. Say plainly when something would need a \

             tool you do not have."

                .to_string(),

            prompt::CODER_LITE_TOOL_LIST_HEADER.replace("{count}", &tools.len().to_string()),

        );

    } else {

        lines.push(format!("You have {} tools, and no others:", tools.len()));

        for tool in tools {

            lines.push(format!("- `{}`", tool.name));

        }

        lines.push(String::new());

        lines.push(

            "That list is complete: a capability not on it is one you do not have. Read a tool's \

             description before assuming what it covers. Never say you ran something you did not \

             run."

                .to_string(),

        );

        lines.push(prompt::CODER_LITE_TOOL_LIST_CLOSING.to_string());

    }

    lines.join("\n")

}

    fn the_system_prompt_opens_with_the_terse_instructions_unchanged() {

        let prompt = system_prompt(&[]);

        assert!(

            prompt.starts_with(SYSTEM_INSTRUCTIONS),

            prompt.starts_with(prompt::CODER_LITE_INSTRUCTIONS),

            "the instructions were not carried verbatim: {prompt}"

        );

        assert!(SYSTEM_INSTRUCTIONS.contains("no greetings"));

        assert!(SYSTEM_INSTRUCTIONS.contains("no unnecessary padding"));

        assert!(prompt::CODER_LITE_INSTRUCTIONS.contains("no greetings"));

        assert!(prompt::CODER_LITE_INSTRUCTIONS.contains("no unnecessary padding"));

    }

    /// A model told it has tools it does not have will claim to have run them.

{

  "system_prompt.no_tools": "You are OpenAgents Coder. Do not say you are from Google, Anthropic, OpenAI, or any other company. Do not mention your model, training, or architecture. Respond as a neutral, terse terminal: no greetings, no \"As an AI\", no explanations of your role, and no unnecessary padding. Use short sentences and dense, factual output. Answer questions directly. Output only code and minimal context when asked for code.\n\nYou have no tools in this session: you cannot read or write files, run commands, or reach anything outside this conversation. Say plainly when something would need a tool you do not have.",

  "system_prompt.one_tool": "You are OpenAgents Coder. Do not say you are from Google, Anthropic, OpenAI, or any other company. Do not mention your model, training, or architecture. Respond as a neutral, terse terminal: no greetings, no \"As an AI\", no explanations of your role, and no unnecessary padding. Use short sentences and dense, factual output. Answer questions directly. Output only code and minimal context when asked for code.\n\nYou have 1 tools, and no others:\n- `alpha`\n\nThat list is complete: a capability not on it is one you do not have. Read a tool's description before assuming what it covers. Never say you ran something you did not run.",

  "system_prompt.two_tools": "You are OpenAgents Coder. Do not say you are from Google, Anthropic, OpenAI, or any other company. Do not mention your model, training, or architecture. Respond as a neutral, terse terminal: no greetings, no \"As an AI\", no explanations of your role, and no unnecessary padding. Use short sentences and dense, factual output. Answer questions directly. Output only code and minimal context when asked for code.\n\nYou have 2 tools, and no others:\n- `alpha`\n- `beta`\n\nThat list is complete: a capability not on it is one you do not have. Read a tool's description before assuming what it covers. Never say you ran something you did not run."

}

//! coder-lite's own voice, pinned byte for byte.

//!

//! The system prompt this crate composes is a staged artifact

//! (`surfaces/coder/system-prompt.v1.json`, OpenAgentsInc/openagents#122): a

//! change to it is meant to be a diff over that artifact with a measured

//! delta behind it, never a quiet edit in passing. This test composes the

//! prompt from fixed inputs and compares it with `coder-surfaces-golden.json`,

//! so moving the text out of `runtime.rs` and into the artifact had to be a

//! move and nothing else.

//!

//! Re-pin deliberately, with `UPDATE_CODER_SURFACES_GOLDEN=1 cargo test -p

//! coder-lite --test coder_surfaces_golden`, and only when the change to the

//! text is the change you meant to make.

use std::collections::BTreeMap;

use std::path::PathBuf;

use coder_lite::runtime::system_prompt;

use openagents_cli::tools::ToolDefinition;

fn declared(name: &str) -> ToolDefinition {

    ToolDefinition {

        name: name.to_string(),

        description: format!("A declared {name}."),

        parameters: serde_json::json!({"type": "object"}),

    }

}

fn captured() -> BTreeMap<String, String> {

    let mut out = BTreeMap::new();

    out.insert("system_prompt.no_tools".to_string(), system_prompt(&[]));

    out.insert(

        "system_prompt.one_tool".to_string(),

        system_prompt(&[declared("alpha")]),

    );

    out.insert(

        "system_prompt.two_tools".to_string(),

        system_prompt(&[declared("alpha"), declared("beta")]),

    );

    out

}

#[test]

fn the_composed_prompt_matches_the_pinned_golden() {

    let golden_path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))

        .join("tests")

        .join("coder-surfaces-golden.json");

    let captured = captured();

    if std::env::var("UPDATE_CODER_SURFACES_GOLDEN").is_ok() {

        std::fs::write(

            &golden_path,

            format!("{}\n", serde_json::to_string_pretty(&captured).unwrap()),

        )

        .unwrap();

        return;

    }

    let raw = std::fs::read_to_string(&golden_path).expect("the golden file is checked in");

    let expected: BTreeMap<String, String> = serde_json::from_str(&raw).unwrap();

    assert_eq!(captured, expected);

}

pub mod resume;

pub mod runtime;

pub mod signals;

pub mod surfaces;

pub mod tools;

pub mod trace;

pub mod trace_client;

pub fn capability_tool_definition() -> crate::tools::ToolDefinition {

    crate::tools::ToolDefinition {

        name: "capability".to_string(),

        description: "Discover and load installed plugin capabilities: sandboxed, digest-pinned \

             WebAssembly programs this machine already holds for common agent work. Before writing \

             a script for a task, search here first — a capability that covers it is bounded, \

             reviewable, and returns structured output. Call with `query` describing what you need \

             to get the best matches; then call again with `name` set to the exact returned name \

             to load it and make its dedicated tool available. Every later call to the loaded \

             capability uses that exact name as the tool name."

            .to_string(),

        description: crate::surfaces::tool_descriptions::RUST_CAPABILITY.to_string(),

        parameters: serde_json::json!({

            "type": "object",

            "properties": {

/// and the observer usually outlives the call that installed it.

pub type ToolObserver = Arc<dyn Fn(ToolEvent) + Send + Sync>;

pub const THREAD_LANE_NOTICE: &str =

    "You answer through the OpenAgents inference proxy, on a thread opened for this session. \

    Every round of tool calls re-sends the whole conversation to a metered model, so batch \

    independent commands into one call and keep large dumps out of the transcript.";

pub const THREAD_LANE_NOTICE: &str = crate::surfaces::system_prompt::CODER_LANE_THREAD;

pub const LOCAL_LANE_NOTICE: &str =

    "You answer from a model running on this machine through Ollama. Nothing in this \

    conversation leaves the machine and nothing is metered, but the context window is a \

    fraction of a hosted model's, so keep large dumps out of the transcript.";

pub const LOCAL_LANE_NOTICE: &str = crate::surfaces::system_prompt::CODER_LANE_LOCAL_RUST;

/// Where an Ollama server listens unless `OPENAGENTS_OLLAMA_HOST` says otherwise.

pub const OLLAMA_HOST: &str = "http://127.0.0.1:11434";

        } else {

            THREAD_LANE_NOTICE

        };

        use crate::surfaces::system_prompt as prompt;

        let mut lines = vec![

            format!("You are `openagents coder`, a coding assistant in a terminal. {notice}"),

            prompt::CODER_OPENING.replace("{lane}", notice),

            "".to_string(),

            "Answer very concisely unless the reader asks for a longer response.".to_string(),

            prompt::CODER_CONCISION.to_string(),

            "".to_string(),

        ];

        if tool_defs.is_empty() {

            lines.push(prompt::CODER_NO_TOOLS.to_string());

        } else {

            lines.push(

                "You have no tools in this session: you cannot read or write files, run commands, or \

                reach anything outside this conversation. Answer from what the reader tells you, and \

                say plainly when something would need a tool you do not have.".to_string()

                prompt::CODER_TOOL_LIST_HEADER_RUST

                    .replace("{count}", &tool_defs.len().to_string()),

            );

        } else {

            lines.push(format!(

                "You have {} tools, and no others:",

                tool_defs.len()

            ));

            for t in tool_defs {

                lines.push(format!("- `{}`", t.name));

            }

            lines.push("".to_string());

            lines.push(

                "That list is complete: a capability not on it is one you do not have, whatever a model \

                like you usually has. Read a tool's description before assuming what it covers. Where \

                a description says what a child agent can do, that is the child's capability and not \

                yours. Never say you ran something you did not run.".to_string()

            );

            lines.push(prompt::CODER_TOOL_LIST_CLOSING.to_string());

        }

        // Skill injection. The `skill` tool's catalog is names and

// @generated by scripts/coder-surfaces.mjs — do not edit.

//

// The staged coder text surfaces (`surfaces/coder/`), embedded at build

// time. Editing a sentence here is editing a build output: the artifact

// is the source, `pnpm run build:coder-surfaces` is the build, and

// `pnpm run check:coder-surfaces` refuses a tree where the two disagree.

//

//! Staged coder text surfaces, embedded from `surfaces/coder/`.

/// The system prompt surface: `surfaces/coder/system-prompt.v1.json`.

pub mod system_prompt {

    /// `coder_lite.instructions`

    pub const CODER_LITE_INSTRUCTIONS: &str = "You are OpenAgents Coder. Do not say you are from Google, Anthropic, OpenAI, or any other company. Do not mention your model, training, or architecture. Respond as a neutral, terse terminal: no greetings, no \"As an AI\", no explanations of your role, and no unnecessary padding. Use short sentences and dense, factual output. Answer questions directly. Output only code and minimal context when asked for code.";

    /// `coder_lite.no_tools`

    pub const CODER_LITE_NO_TOOLS: &str = "You have no tools in this session: you cannot read or write files, run commands, or reach anything outside this conversation. Say plainly when something would need a tool you do not have.";

    /// `coder_lite.tool_list_header`

    pub const CODER_LITE_TOOL_LIST_HEADER: &str = "You have {count} tools, and no others:";

    /// `coder_lite.tool_list_closing`

    pub const CODER_LITE_TOOL_LIST_CLOSING: &str = "That list is complete: a capability not on it is one you do not have. Read a tool's description before assuming what it covers. Never say you ran something you did not run.";

    /// `coder.opening`

    pub const CODER_OPENING: &str = "You are `openagents coder`, a coding assistant in a terminal. {lane}";

    /// `coder.concision`

    pub const CODER_CONCISION: &str = "Answer very concisely unless the reader asks for a longer response.";

    /// `coder.no_tools`

    pub const CODER_NO_TOOLS: &str = "You have no tools in this session: you cannot read or write files, run commands, or reach anything outside this conversation. Answer from what the reader tells you, and say plainly when something would need a tool you do not have.";

    /// `coder.tool_list_header.rust`

    pub const CODER_TOOL_LIST_HEADER_RUST: &str = "You have {count} tools, and no others:";

    /// `coder.tool_list_closing`

    pub const CODER_TOOL_LIST_CLOSING: &str = "That list is complete: a capability not on it is one you do not have, whatever a model like you usually has. Read a tool's description before assuming what it covers. Where a description says what a child agent can do, that is the child's capability and not yours. Never say you ran something you did not run.";

    /// `coder.lane.local.rust`

    pub const CODER_LANE_LOCAL_RUST: &str = "You answer from a model running on this machine through Ollama. Nothing in this conversation leaves the machine and nothing is metered, but the context window is a fraction of a hosted model's, so keep large dumps out of the transcript.";

    /// `coder.lane.thread`

    pub const CODER_LANE_THREAD: &str = "You answer through the OpenAgents inference proxy, on a thread opened for this session. Every round of tool calls re-sends the whole conversation to a metered model, so batch independent commands into one call and keep large dumps out of the transcript.";

}

/// The tool-description surface: `surfaces/coder/tool-descriptions.v1.json`.

pub mod tool_descriptions {

    /// `rust.shell`

    pub const RUST_SHELL: &str = "Run a shell command on this machine. The working directory is {cwd}, so paths are relative to it and you do not need to ask where you are. Returns combined stdout and stderr with the exit code. Batch independent commands into one call with && instead of one call each: every call replays the conversation so far.";

    /// `rust.skill`

    pub const RUST_SKILL: &str = "Read one of this repository skill procedures: a written procedure with conventions, commands, and rules. Call it before doing work a skill covers. Skills available:{skills}";

    /// `rust.openagents`

    pub const RUST_OPENAGENTS: &str = "Run the OpenAgents CLI commands (issue, project, repo, auth, etc.). Pass the arguments as a list without openagents itself.";

    /// `rust.delegate`

    pub const RUST_DELEGATE: &str = "Run one prompt on independent child coding agents in parallel and return what each one found or did. Use it when work splits into parts that do not depend on each other: several files to change the same way, several hypotheses to check, several tests to run down. Each child is a full coding agent with its own shell tool, working in a git worktree of its own so children cannot overwrite each other, and it starts with no context from this conversation and cannot ask questions — so the prompt has to be self-contained. Every child runs the same prompt and each is told separately which number it is, so write the prompt for whichever child reads it: say \"read the file at your own number\" rather than naming one child. Children run on {lane} and on this session's budget. Prefer one call with a count over several calls, and prefer `shell` over this for a single command — a child agent is for work worth a whole agent, not one line of output. At most {max_count} children.";

    /// `rust.capability`

    pub const RUST_CAPABILITY: &str = "Discover and load installed plugin capabilities: sandboxed, digest-pinned WebAssembly programs this machine already holds for common agent work. Before writing a script for a task, search here first — a capability that covers it is bounded, reviewable, and returns structured output. Call with `query` describing what you need to get the best matches; then call again with `name` set to the exact returned name to load it and make its dedicated tool available. Every later call to the loaded capability uses that exact name as the tool name.";

}

/// Every staged surface and the digest of the artifact this was built from.

///

/// A run records these so a bench row names exactly which text produced it.

pub const SURFACE_DIGESTS: [(&str, &str); 3] = [

    ("system-prompt", "sha256:8f0fbbbb38f4ce609a09fe2ba4e03ca160ff2c0d0f698dd4676c2bf940ded849"),

    ("tool-descriptions", "sha256:513c7518c72ba8c9959e517ea9f1262d7d3ee6b08452ddb48568bdabf6383c1b"),

    ("catalog-lines", "sha256:98a96bcf6acfd5847bc1bddcc575761af71be7ea144f3584b3594b24b2f80911"),

];

    pub child: crate::delegate::ChildOptions,

}

use crate::surfaces::tool_descriptions as text;

pub struct HarnessToolRegistry {

    pub cwd: PathBuf,

    /// Discovered skills by name, in catalog order.

        let mut tools = vec![

            ToolDefinition {

                name: "shell".to_string(),

                description: format!(

                    "Run a shell command on this machine. The working directory is {}, so paths are \

                    relative to it and you do not need to ask where you are. Returns combined stdout \

                    and stderr with the exit code. Batch independent commands into one call with && \

                    instead of one call each: every call replays the conversation so far.",

                    self.cwd.display()

                ),

                description: text::RUST_SHELL.replace("{cwd}", &self.cwd.display().to_string()),

                parameters: serde_json::json!({

                    "type": "object",

                    "properties": {

            },

            ToolDefinition {

                name: "skill".to_string(),

                description: format!("Read one of this repository skill procedures: a written procedure with conventions, commands, and rules. Call it before doing work a skill covers. Skills available:{}", skill_list),

                description: text::RUST_SKILL.replace("{skills}", &skill_list),

                parameters: serde_json::json!({

                    "type": "object",

                    "properties": {

            },

            ToolDefinition {

                name: "openagents".to_string(),

                description: "Run the OpenAgents CLI commands (issue, project, repo, auth, etc.). Pass the arguments as a list without openagents itself.".to_string(),

                description: text::RUST_OPENAGENTS.to_string(),

                parameters: serde_json::json!({

                    "type": "object",

                    "properties": {

        if let Some(gate) = &self.delegation {

            tools.push(ToolDefinition {

                name: "delegate".to_string(),

                description: format!(

                    "Run one prompt on independent child coding agents in parallel and return what \

                    each one found or did. Use it when work splits into parts that do not depend on \

                    each other: several files to change the same way, several hypotheses to check, \

                    several tests to run down. Each child is a full coding agent with its own shell \

                    tool, working in a git worktree of its own so children cannot overwrite each \

                    other, and it starts with no context from this conversation and cannot ask \

                    questions — so the prompt has to be self-contained. Every child runs the same \

                    prompt and each is told separately which number it is, so write the prompt for \

                    whichever child reads it: say \"read the file at your own number\" rather than \

                    naming one child. Children run on {} and on this session's budget. Prefer one \

                    call with a count over several calls, and prefer `shell` over this for a single \

                    command — a child agent is for work worth a whole agent, not one line of \

                    output. At most {} children.",

                    gate.lane, gate.max_count

                ),

                description: text::RUST_DELEGATE

                    .replace("{lane}", &gate.lane)

                    .replace("{max_count}", &gate.max_count.to_string()),

                parameters: serde_json::json!({

                    "type": "object",

                    "properties": {

{

  "system_prompt.local.no_tools": "You are `openagents coder`, a coding assistant in a terminal. You answer from a model running on this machine through Ollama. Nothing in this conversation leaves the machine and nothing is metered, but the context window is a fraction of a hosted model's, so keep large dumps out of the transcript.\n\nAnswer very concisely unless the reader asks for a longer response.\n\nYou have no tools in this session: you cannot read or write files, run commands, or reach anything outside this conversation. Answer from what the reader tells you, and say plainly when something would need a tool you do not have.",

  "system_prompt.thread.no_tools": "You are `openagents coder`, a coding assistant in a terminal. You answer through the OpenAgents inference proxy, on a thread opened for this session. Every round of tool calls re-sends the whole conversation to a metered model, so batch independent commands into one call and keep large dumps out of the transcript.\n\nAnswer very concisely unless the reader asks for a longer response.\n\nYou have no tools in this session: you cannot read or write files, run commands, or reach anything outside this conversation. Answer from what the reader tells you, and say plainly when something would need a tool you do not have.",

  "system_prompt.thread.two_tools": "You are `openagents coder`, a coding assistant in a terminal. You answer through the OpenAgents inference proxy, on a thread opened for this session. Every round of tool calls re-sends the whole conversation to a metered model, so batch independent commands into one call and keep large dumps out of the transcript.\n\nAnswer very concisely unless the reader asks for a longer response.\n\nYou have 2 tools, and no others:\n- `alpha`\n- `beta`\n\nThat list is complete: a capability not on it is one you do not have, whatever a model like you usually has. Read a tool's description before assuming what it covers. Where a description says what a child agent can do, that is the child's capability and not yours. Never say you ran something you did not run.",

  "tool.capability": "Discover and load installed plugin capabilities: sandboxed, digest-pinned WebAssembly programs this machine already holds for common agent work. Before writing a script for a task, search here first — a capability that covers it is bounded, reviewable, and returns structured output. Call with `query` describing what you need to get the best matches; then call again with `name` set to the exact returned name to load it and make its dedicated tool available. Every later call to the loaded capability uses that exact name as the tool name.",

  "tool.delegate": "Run one prompt on independent child coding agents in parallel and return what each one found or did. Use it when work splits into parts that do not depend on each other: several files to change the same way, several hypotheses to check, several tests to run down. Each child is a full coding agent with its own shell tool, working in a git worktree of its own so children cannot overwrite each other, and it starts with no context from this conversation and cannot ask questions — so the prompt has to be self-contained. Every child runs the same prompt and each is told separately which number it is, so write the prompt for whichever child reads it: say \"read the file at your own number\" rather than naming one child. Children run on the parent lane and on this session's budget. Prefer one call with a count over several calls, and prefer `shell` over this for a single command — a child agent is for work worth a whole agent, not one line of output. At most 8 children.",

  "tool.openagents": "Run the OpenAgents CLI commands (issue, project, repo, auth, etc.). Pass the arguments as a list without openagents itself.",

  "tool.shell": "Run a shell command on this machine. The working directory is /fixed/cwd, so paths are relative to it and you do not need to ask where you are. Returns combined stdout and stderr with the exit code. Batch independent commands into one call with && instead of one call each: every call replays the conversation so far.",

  "tool.skill": "Read one of this repository skill procedures: a written procedure with conventions, commands, and rules. Call it before doing work a skill covers. Skills available:"

}

//! The optimizable text this crate declares, pinned byte for byte.

//!

//! The system prompt, the lane notices, and the built-in tool descriptions are

//! staged artifacts (`surfaces/coder/`, OpenAgentsInc/openagents#122): a

//! change to any of them is meant to be a diff over an artifact with a

//! measured delta behind it, never a quiet edit in passing. This test is the

//! second half of that: it composes each surface from fixed inputs and

//! compares the result with `coder-surfaces-golden.json`, so moving the text

//! out of these files and into the artifact had to be a move and nothing else.

//!

//! Re-pin deliberately, with `UPDATE_CODER_SURFACES_GOLDEN=1 cargo test -p

//! openagents-cli --test coder_surfaces_golden`, and only when the change to

//! the text is the change you meant to make.

use std::collections::BTreeMap;

use std::path::PathBuf;

use openagents_cli::delegate::ChildOptions;

use openagents_cli::runtime::{CoderRuntimeSession, Lane};

use openagents_cli::tools::{DelegationGate, HarnessToolRegistry, ToolDefinition};

/// A directory that does not exist, so no plugin catalog is discovered and

/// the composed text depends on nothing outside this file.

const FIXED_CWD: &str = "/fixed/cwd";

/// Skills are discovered from `$HOME/.agents/skills` as well as the workspace,

/// so the machine running this test would otherwise decide what the `skill`

/// declaration says. Point `HOME` at an empty directory first: the surface

/// under test is the sentence around the catalog, not the catalog.

fn without_local_skills() -> tempfile::TempDir {

    let empty = tempfile::tempdir().unwrap();

    unsafe { std::env::set_var("HOME", empty.path()) };

    empty

}

fn registry() -> HarnessToolRegistry {

    HarnessToolRegistry::with_delegation(

        Some(PathBuf::from(FIXED_CWD)),

        DelegationGate {

            lane: "the parent lane".to_string(),

            user_token: None,

            max_count: 8,

            child: ChildOptions::default(),

        },

    )

}

fn session(lane: Lane) -> CoderRuntimeSession {

    CoderRuntimeSession::new(

        lane,

        Some("https://example.invalid/api/v1".to_string()),

        None,

        HarnessToolRegistry::new(Some(PathBuf::from(FIXED_CWD))),

    )

}

fn declared(name: &str) -> ToolDefinition {

    ToolDefinition {

        name: name.to_string(),

        description: format!("A declared {name}."),

        parameters: serde_json::json!({"type": "object"}),

    }

}

fn captured() -> BTreeMap<String, String> {

    let mut out = BTreeMap::new();

    let two = [declared("alpha"), declared("beta")];

    out.insert(

        "system_prompt.local.no_tools".to_string(),

        session(Lane::Local(String::new())).build_system_prompt(&[]),

    );

    out.insert(

        "system_prompt.thread.no_tools".to_string(),

        session(Lane::OxAlpha).build_system_prompt(&[]),

    );

    out.insert(

        "system_prompt.thread.two_tools".to_string(),

        session(Lane::OxAlpha).build_system_prompt(&two),

    );

    for tool in registry().list_tools() {

        out.insert(format!("tool.{}", tool.name), tool.description);

    }

    out

}

#[test]

fn the_declared_text_matches_the_pinned_golden() {

    let _empty_home = without_local_skills();

    let golden_path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))

        .join("tests")

        .join("coder-surfaces-golden.json");

    let captured = captured();

    if std::env::var("UPDATE_CODER_SURFACES_GOLDEN").is_ok() {

        std::fs::write(

            &golden_path,

            format!("{}\n", serde_json::to_string_pretty(&captured).unwrap()),

        )

        .unwrap();

        return;

    }

    let raw = std::fs::read_to_string(&golden_path).expect("the golden file is checked in");

    let expected: BTreeMap<String, String> = serde_json::from_str(&raw).unwrap();

    for (key, want) in &expected {

        let got = captured

            .get(key)

            .unwrap_or_else(|| panic!("`{key}` is no longer declared"));

        assert_eq!(got, want, "`{key}` changed");

    }

    assert_eq!(

        captured.keys().collect::<Vec<_>>(),

        expected.keys().collect::<Vec<_>>(),

        "the set of declared surfaces changed"

    );

}

  "note": "Heuristic false-green LEADS, not findings. A finding requires a demonstrated reproduction (surviving mutation via mutation-runner). Do not treat a candidate as a confirmed false green. Coverage-theater leads may include tests that delegate their assertion to a custom helper the classifier does not recognise; verify before acting.",

  "sourceDigest": "sha256:dd810dd48c5bdbc9becd7fcc01dd41a4ca2abf0b2d6f6a545907247f6e3e8361",

  "summary": {

    "filesScanned": 2503,

    "filesScanned": 2505,

    "candidateCount": 16,

    "byMode": {

      "false_green_coverage_theater": 15,

{

  "schemaVersion": "1",

  "repository": "OpenAgentsInc/openagents",

  "sourceDigest": "sha256:5ef645157ec7a0f6f2beca87dffd96dde98e6966272a12b95febff453a3d246a",

  "sourceDigest": "sha256:931a55aba01fd586c019996b1f02bf4d383179c895bc0053a5ed770bac5deb7b",

  "surfaces": [

    {

      "id": "app:@openagentsinc/acceptance-runner",

      "oracles": [

        {

          "type": "test",

          "ref": "packages/openagents-cli (90 tracked test files)"

          "ref": "packages/openagents-cli (91 tracked test files)"

        },

        {

          "type": "behavior-contract",

      "oracles": [

        {

          "type": "test",

          "ref": "packages/coder-effectiveness (8 tracked test files)"

          "ref": "packages/coder-effectiveness (9 tracked test files)"

        }

      ],

      "obligation": {

# The candidate: one object for a review proposal and an optimizer mutation

Date: 2026-08-26. Status: the format of record for

OpenAgentsInc/openagents#122, #121, and #123. Companions:

`docs/coder/autoimprove.md` §3 and §7.6, `docs/coder/runbook.md`,

`docs/coder/best-practices.md`, and the analysis

`docs/coder/2026-08-26-dspy-gepa-coder-optimization.md` §4.

A candidate is a proposed change to the coder's optimizable text, carrying

everything needed to judge it: which surfaces it edits, where it came from,

which model family it was written or evolved against, the evidence behind it,

and how it would be confirmed or refuted.

The standing law it exists to serve: **an optimizer output is a candidate,

never a deployment.** A candidate becomes a change the way every other lever

does — a fresh worktree, a landing commit stating the measured delta, the

review, the ledger.

## 1. Why there is one format and not two

`autoimprove.md` §7.6 says the optimizer lane shares the review schema "so a

reflection and a mutation are the same object". If a review proposal and a

GEPA mutation were different shapes, the Pareto pool could not hold both, a

human cycle could not seed the optimizer, and every consumer would need two

readers. So the schema is defined once.

The definition lives in code, at

`packages/openagents-cli/src/coder-review-candidate.ts`, under the schema id

`openagents.coder_candidate.v1`. That file is the normative artifact; this

document explains it and pins the vocabulary the `surfaces` field draws on.

A review proposal is a candidate whose `lineage.origin` is `review`; an

optimizer mutation is one whose origin is `optimizer`; a hand-written cycle

lever is `human`. Nothing else about the object changes between them.

## 2. The shape

```

CoderCandidate {

  schema:        "openagents.coder_candidate.v1"

  candidateId:   "candidate:<8 hex>"      // computed, never supplied

  lever: {

    axis:        "process" | "plugin" | "harness" | "optimizer" | "routing" | "ledger"

    summary:     string                   // one sentence naming the change

  }

  surfaces:      [{ surface: string, diff: string }]

  lineage: {

    origin:      "review" | "optimizer" | "human"

    parent:      string | null            // the candidateId this came from

    producedBy:  string                   // e.g. "coder review-run:<reviewId>"

  }

  transferLabel: { modelFamily: string, lane: string }

  evidence:      [{ ref: string, note: string }]

  risk:          string

  verification:  { suite: string, metric: string, expectedDirection: "up" | "down" | "unchanged" }

}

```

Three fields carry most of the weight.

**`transferLabel`** is ledger O5 and the evolve-the-harness finding behind it:

code mechanisms transferred across model families and tuned prompts did not.

A candidate evolved against one family is not evidence for another, and the

label is what stops a pool from quietly pretending otherwise.

**`evidence`** is checked, not decorative.

`autoimprove.md` §6 lists "confident review without understanding" as a failure

mode. The parser refuses a proposal with no evidence, and refuses one whose

refs do not resolve against the artifacts the producer was actually given. The

ref grammar is small on purpose, because every scheme in it has to be

resolvable: `trial:<task>#step-<id>`, `trial:<task>#outcome`,

`row:<suite>#<recordedAt>`, `ledger:<id>`, `diff:<path>`.

**`candidateId`** is FNV-1a over the candidate's own facts — an identity for a

pool entry, not a receipt. `bench-results` owns tamper-evidence; borrowing its

`receipt:` vocabulary here would suggest this digest carries the same weight.

## 3. The surface vocabulary

`surfaces[].surface` names a staged artifact from `surfaces/coder/index.json`.

The whole current vocabulary:

| `surface` | Artifact | What it holds |

| --- | --- | --- |

| `system-prompt` | `surfaces/coder/system-prompt.v1.json` | The instructions, the concision sentence, the no-tools and tool-list sentences, and the lane notices, for all three harnesses |

| `tool-descriptions` | `surfaces/coder/tool-descriptions.v1.json` | The description of each declared tool, plus the per-model-family emphasis overrides |

| `catalog-lines` | `surfaces/coder/catalog-lines.v1.json` | Each installed plugin's catalog line, keyed by plugin id |

`diff` is a unified diff over that artifact file where one exists, and the

proposed text otherwise. The artifact's `text` map is flat and keyed, so a

one-sentence change is a one-line diff and reads as one.

A surface a candidate does not touch is simply absent from the array. A

candidate touching none of them is legitimate — the `plugin`, `process`, and

`routing` axes change code, skills, or procedure rather than staged text — and

its `surfaces` array is empty.

### The catalog-lines surface is a mirror, not a move

Stated plainly, because it changes how a candidate against it is applied. The

system prompt and the tool descriptions were string literals in

`crates/coder-lite`, `crates/openagents-cli`, and `packages/openagents-cli`;

staging them moved the text out of code and into the artifact, and the

artifact is now where it is edited.

A plugin's catalog line was never a literal. It is the top-level `description`

of `plugins/<id>/manifest.json`, discovered at runtime by `discover_catalog()`

(`crates/openagents-cli/src/plugins.rs`) and its TypeScript equivalent. The

manifest stays where that text is edited. `catalog-lines.v1.json` mirrors those

descriptions into one diffable object with a content digest, so an optimizer

has a single file to diff and a bench row has a single digest to record — and

`pnpm run check:coder-surfaces` fails when a manifest and the mirror disagree.

So: applying a candidate against `system-prompt` or `tool-descriptions` means

patching the artifact. Applying one against `catalog-lines` means patching the

named `plugins/<id>/manifest.json`. Both then need the rebuild.

## 4. Applying a candidate

1. Patch the artifact (or, for `catalog-lines`, the manifest).

2. `pnpm run build:coder-surfaces` — re-pins `surfaces/coder/index.json` and

   regenerates the embedded modules the two CLIs compile.

3. Run the suite named in `verification.suite`. The run announces its staged

   text as `[oa:surfaces <id>=<digest>,…]`, `bench-results` records those

   digests on the row, and `pnpm run effectiveness:compare` names the change as

   a variable when two compared rows carry different pins.

4. Land or discard on the measured delta, per `runbook.md`.

Skipping step 2 is the failure this staging exists to prevent, and it is a

named check rather than a silence: `check:coder-surfaces` runs inside

`check:fast` and refuses a tree where an artifact and its build disagree.

## 5. A worked example

A real observation from the staging work, kept here as a candidate rather than

as a change: the `shell` tool description has forked between the two harnesses.

The TypeScript one steers the model toward an installed capability before it

writes a script and carries a paragraph of token economy; the Rust one carries

neither. A candidate proposing to close that gap looks like this.

```json

{

  "schema": "openagents.coder_candidate.v1",

  "candidateId": "candidate:computed",

  "lever": {

    "axis": "harness",

    "summary": "Give the Rust shell description the capability-first steer the TypeScript one already carries."

  },

  "surfaces": [

    {

      "surface": "tool-descriptions",

      "diff": "--- a/surfaces/coder/tool-descriptions.v1.json\n+++ b/surfaces/coder/tool-descriptions.v1.json\n@@\n-    \"rust.shell\": \"Run a shell command on this machine. The working directory is {cwd}, …\",\n+    \"rust.shell\": \"Run a shell command on this machine. The working directory is {cwd}, … When an installed capability covers the task — the `capability` tool names what is installed — load and call it instead of scripting the same thing here: it is sandboxed, bounded, and returns structured output. …\",\n"

    }

  ],

  "lineage": {

    "origin": "human",

    "parent": null,

    "producedBy": "openagents#122 staging"

  },

  "transferLabel": {

    "modelFamily": "unmeasured",

    "lane": "unmeasured"

  },

  "evidence": [

    {

      "ref": "diff:surfaces/coder/tool-descriptions.v1.json",

      "note": "The two harnesses' `shell` descriptions, side by side in one artifact, which is what made the fork visible."

    },

    {

      "ref": "ledger:P3",

      "note": "A plugin competes for rank in a five-result search; a shell description that never mentions the capability tool is one reason a search never happens."

    }

  ],

  "risk": "The steer is unmeasured on the Rust harness. It may cost tokens on tasks no installed capability covers, and it lengthens a description that is currently short.",

  "verification": {

    "suite": "tb2-quick",

    "metric": "successRate",

    "expectedDirection": "up"

  }

}

```

Note what the object refuses to pretend. `transferLabel` says `unmeasured`

rather than naming a family, because this candidate came from reading two

files and not from a run. Under ledger O5 that is a candidate worth screening

and not a change worth landing — which is the whole point of the format.

## 6. What is deliberately not here

- **No optimizer.** #123 owns the GEPA lane; this document owns the object it

  emits.

- **No adoption rule.** `runbook.md` owns the acceptance gate and

  `best-practices.md` owns the ledger operations. A candidate that passes its

  verification is still a candidate until a cycle lands it.

- **No parameter-level tool text.** The staged `tool-descriptions` surface

  holds each tool's own description and the family overrides. The JSON-Schema

  `description` of an individual argument is still a literal in code, and

  staging it is a later slice rather than a silent part of this one.

  "type": "module",

  "scripts": {

    "check:vp2-node-runtime": "node scripts/vp2-node-runtime-guard.mjs",

    "build:coder-surfaces": "node scripts/coder-surfaces.mjs --write",

    "check:coder-surfaces": "node scripts/coder-surfaces.mjs",

    "check:agent-client-protocol": "pnpm --dir packages/agent-client-protocol run check:generated",

    "check:agent-client-protocol-conformance": "pnpm --dir packages/agent-client-protocol-conformance run check:artifacts",

    "check:all-work-contract": "pnpm --dir packages/all-work-contract run check:generated && cargo test -p openagents-all-work-contract",

    "agent-computer:codex-auth": "node --import tsx apps/pylon/deploy/agent-computer/native-codex-auth.ts",

    "deploy:aiur": "pnpm --dir apps/aiur run deploy",

    "check": "pnpm run fmt:check && pnpm run lint && pnpm run check:fast && pnpm run typecheck && pnpm run test",

    "check:fast": "vp lint --quiet && pnpm run check:all-work-contract && pnpm run check:agent-client-protocol && pnpm run check:agent-client-protocol-conformance && pnpm run check:codex-app-server-protocol && pnpm run check:ste:public && pnpm run check:ste-public-semantics && node scripts/vp1-retired-money-surface-guard.mjs . && node scripts/zero-supported-bun-guard.mjs . && node scripts/dse-single-authority-guard.mjs . && node scripts/google-cloud-authority-guard.mjs && node scripts/sarah-participant-join-authority-guard.mjs . && node scripts/uncalled-production-symbol-guard.mjs . && node scripts/cli-invocability-guard.mjs . && pnpm run check:documented-route-mounts && pnpm run check:assure-repo && pnpm run check:assure-repo-audit && pnpm run check:assure-repo-drift",

    "check:fast": "vp lint --quiet && pnpm run check:all-work-contract && pnpm run check:agent-client-protocol && pnpm run check:agent-client-protocol-conformance && pnpm run check:codex-app-server-protocol && pnpm run check:ste:public && pnpm run check:ste-public-semantics && node scripts/vp1-retired-money-surface-guard.mjs . && node scripts/zero-supported-bun-guard.mjs . && node scripts/dse-single-authority-guard.mjs . && node scripts/google-cloud-authority-guard.mjs && node scripts/sarah-participant-join-authority-guard.mjs . && node scripts/uncalled-production-symbol-guard.mjs . && node scripts/cli-invocability-guard.mjs . && pnpm run check:coder-surfaces && pnpm run check:documented-route-mounts && pnpm run check:assure-repo && pnpm run check:assure-repo-audit && pnpm run check:assure-repo-drift",

    "check:afs-boundaries": "node --import tsx scripts/check-afs-boundaries.ts",

    "check:afs-apple-fm-version-drift": "node --import tsx scripts/check-afs-apple-fm-version-drift.ts",

    "check:documented-route-mounts": "pnpm --dir apps/openagents.com/workers/api run test src/routing/documented-route-mounts.test.ts",

 *    job, and it already has a third verdict for the cases nothing measured.

 */

import { surfacePinOf } from "./results-store.ts";

import type { BenchResultRow } from "./results-store.ts";

export type DeltaDirection = "better" | "worse" | "unchanged" | "unpriced" | "unknown";

  if (axis === "recordedAt" && models.length > 1) {

    notes.push(`model also varies (${models.join(", ")})`);

  }

  // The staged text is a variable like any other (OpenAgentsInc/openagents#122).

  // Named on both axes: a lane comparison assumes the prompt is held still

  // while the lane changes, and a trend step that changed the prompt is a

  // cycle whose delta belongs to that change and to nothing else in the step.

  const pins = distinct(rows.map(surfacePinOf));

  if (pins.length > 1) {

    notes.push(`staged text also varies (${pins.join(" | ")})`);

  }

  if (rows.some((row) => surfacePinOf(row) === null) && pins.length > 0) {

    notes.push("at least one row names no staged text, so what it measured cannot be identified");

  }

  if (bases.includes("operator_placeholder")) {

    notes.push(

      "at least one row is priced from operator placeholder rates, so its cost is provisional",

      suite: "tb2-cross-section",

      lane: "proxy",

      runDigest: "effectiveness:test",

        surfaceDigests: null,

      trials: [

        {

          task: "fix-git",

          toolCalls: 1,

          wallClockSeconds: 60,

          threadId: null,

          surfaceDigests: null,

          exception: null,

        },

      ],

  readonly suite: string;

  readonly lane: string;

  readonly runDigest: string;

  /**

   * The staged text surfaces the run composed from, by content digest, or

   * `null` when the trials announced none or disagreed.

   */

  readonly surfaceDigests: Readonly<Record<string, string>> | null;

  readonly jobId: string | null;

  readonly models: ReadonlyArray<string>;

  readonly agentVersions: ReadonlyArray<string>;

    suite: run.suite,

    lane: run.lane,

    runDigest: run.runDigest,

    surfaceDigests: run.surfaceDigests,

    jobId: run.jobId,

    models: distinct(run.trials.map((trial) => trial.modelId)),

    agentVersions: distinct(run.trials.map((trial) => trial.agentVersion)),

/** The coder's `--plain` thread announcement, the same contract bench parses. */

const THREAD_LINE = /\[oa:thread ([0-9a-fA-F-]{36})\]/u;

/**

 * The coder's `--plain` staged-text announcement

 * (OpenAgentsInc/openagents#122), emitted beside the thread line.

 *

 * Read from the trial rather than from the repository, because the repository

 * at scoring time is not the repository the run happened on. A trial from a

 * CLI that predates the announcement carries no pin, and the row then records

 * none rather than a borrowed one.

 */

const SURFACES_LINE = /\[oa:surfaces ([^\]]+)\]/u;

/** What a verifier decided about one trial. */

export type TrialOutcome = "accepted" | "rejected" | "ungraded";

  readonly wallClockSeconds: number | null;

  /** The forge thread the trial ran in, when the coder announced one. */

  readonly threadId: string | null;

  /**

   * The staged text surfaces this trial composed its prompt and tool

   * declarations from, by content digest. `null` when the trial announced

   * none.

   */

  readonly surfaceDigests: Readonly<Record<string, string>> | null;

  /** The typed error Harbor classified, when the trial raised one. */

  readonly exception: string | null;

}

   * report says so rather than letting a reader assume.

   */

  readonly runDigest: string;

  /**

   * The staged text every trial agreed on, or `null` when the trials announced

   * none or disagreed.

   *

   * Disagreement is recorded as absence rather than as one of the two answers:

   * a job whose trials ran different prompts measured no single prompt, and a

   * row that named either half would be naming text that produced some of the

   * outcomes it reports.

   */

  readonly surfaceDigests: Readonly<Record<string, string>> | null;

  readonly trials: ReadonlyArray<TrialRecord>;

}

    trials.push(readTrial(entry, trialDir, trialResult));

  }

  const surfaceDigests = agreedSurfaceDigests(trials);

  return {

    jobId: readString(readField(jobResult, "id")),

    suite: options.suite,

    lane: options.lane,

    runDigest: runDigestOf(trials, options),

    runDigest: runDigestOf(trials, options, surfaceDigests),

    surfaceDigests,

    trials,

  };

};

    toolCalls: usage.toolCalls,

    wallClockSeconds: wallClockOf(trialResult),

    threadId: threadIdOf(trialDir),

    surfaceDigests: surfaceDigestsOf(trialDir),

    exception: readString(readField(readField(trialResult, "exception_info"), "exception_type")),

  };

};

  return match?.[1] ?? null;

};

/** The staged text one trial announced, or `null` when it announced none. */

const surfaceDigestsOf = (trialDir: string): Readonly<Record<string, string>> | null => {

  const path = join(trialDir, "agent", "coder.txt");

  if (!existsSync(path)) return null;

  const match = SURFACES_LINE.exec(readFileSync(path, "utf8"));

  if (match?.[1] === undefined) return null;

  const digests: Record<string, string> = {};

  for (const pair of match[1].split(",")) {

    const at = pair.indexOf("=");

    if (at <= 0) continue;

    digests[pair.slice(0, at).trim()] = pair.slice(at + 1).trim();

  }

  return Object.keys(digests).length === 0 ? null : digests;

};

/**

 * The staged text the whole job ran on, when every trial agrees.

 *

 * One disagreeing trial makes the job's pin `null`. Two prompts in one job is

 * a job that measured neither of them, and the honest column for that is

 * empty.

 */

const agreedSurfaceDigests = (

  trials: ReadonlyArray<TrialRecord>,

): Readonly<Record<string, string>> | null => {

  const announced = trials

    .map((trial) => trial.surfaceDigests)

    .filter((digests): digests is Readonly<Record<string, string>> => digests !== null);

  if (announced.length === 0 || announced.length !== trials.length) return null;

  const first = JSON.stringify(Object.entries(announced[0]!).toSorted());

  const agreed = announced.every(

    (digests) => JSON.stringify(Object.entries(digests).toSorted()) === first,

  );

  return agreed ? announced[0]! : null;

};

/**

 * The recipe pin. Deliberately independent of the `harbor:` digest

 * The recipe pin, including the staged text surfaces. Deliberately

 * independent of the `harbor:` digest

 * `bench/post_gym_run.py` computes: that one hashes a Python-serialised config

 * and this one hashes an explicit list of the facts that make two runs

 * comparable, so claiming they agree would be a claim neither can keep.

 */

const runDigestOf = (trials: ReadonlyArray<TrialRecord>, options: ReadHarborJobOptions): string => {

const runDigestOf = (

  trials: ReadonlyArray<TrialRecord>,

  options: ReadHarborJobOptions,

  surfaceDigests: Readonly<Record<string, string>> | null,

): string => {

  const source = JSON.stringify({

    suite: options.suite,

    lane: options.lane,

    tasks: trials.map((trial) => trial.task).toSorted(),

    agentVersions: distinct(trials.map((trial) => trial.agentVersion)),

    models: distinct(trials.map((trial) => trial.modelId)),

    // The staged text is part of the recipe, so two runs that differ only in

    // the prompt do not share a digest and are not read as the same run.

    surfaces: surfaceDigests === null ? null : Object.entries(surfaceDigests).toSorted(),

  });

  return `effectiveness:${createHash("sha256").update(source).digest("hex")}`;

};

  test("throws on a row written under another schema", () => {

    writeFileSync(store, `${JSON.stringify({ schema: "something.else.v1" })}\n`, "utf8");

    expect(() => readResultRows(store)).toThrow(/expected openagents\.bench_result\.v2/u);

    expect(() => readResultRows(store)).toThrow(

      /expected openagents\.bench_result\.v3 or openagents\.bench_result\.v2/u,

    );

  });

  test("names a v1 row for what it is rather than reading it as a v2 one", () => {

import type { CriterionVerdict, ThresholdGate } from "./thresholds.ts";

/**

 * Bumped from v1 when the suite pin became mandatory. A v1 row carried no

 * `suiteId` or `suiteDigest`, so nothing in it says which pinned task list it

 * measured — readable as history, not comparable to a v2 row, and

 * {@link readResultRows} says so by name rather than by silently coercing it.

 * Bumped from v2 when a row had to name the staged text it measured

 * (OpenAgentsInc/openagents#122). A v3 row carries `surfaceDigests`; a v2 row

 * does not, and the difference is exactly "we did not record this" rather than

 * "this run used no staged text".

 *

 * v1 was the bump before it, when the suite pin became mandatory.

 */

export const BENCH_RESULT_SCHEMA = "openagents.bench_result.v3";

/**

 * The predecessor this store still reads.

 *