Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
41.1 KB
Raw Blame
//! The Agent struct, its state, and its smallest methods. Larger methods are
//! split into `agent_*.zig` siblings and member-aliased back into the struct.
//! Live process/session globals are reached through main_mod; focused helpers
//! are imported directly from their owning modules.
const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const main_mod = @import("main.zig");
const provider_mod = @import("provider.zig");
const Provider = provider_mod.Provider;
const ReasoningEffort = main_mod.ReasoningEffort;
const ws = @import("ws.zig"); // codex Responses WS transport (delta continuation held across a turn)
const mcp = @import("mcp.zig");
const approvals_mod = @import("approvals.zig");
/// Shared approval state, re-exported for startup helpers (#429).
pub const Approvals = approvals_mod.Approvals;
const trace = @import("trace.zig");
const tools_mod = @import("tools.zig");
const vision = @import("vision.zig");
const prompts = @import("prompts.zig");
const tool_render = @import("agent_tool_render.zig");
const schema = @import("schema.zig");
const no_local_tools = @import("no_local_tools.zig"); // #330: --no-local-tools picks the gated subagent catalogs
const models_cache = @import("models_cache.zig");
const keys_cli = @import("keys_cli.zig");
const run_budget_mod = @import("run_budget.zig");
// agent_prompt.zig owns the width-budgeted status line (#209); aliased below.
const prompt_ui = @import("agent_prompt.zig");
const agent_tests = @import("agent_tests.zig");
const goal_state = @import("goal_state.zig");
pub const TodoItem = struct {
    content: []const u8,
    status: []const u8,
    epoch: u64 = 0, // the goal epoch that authored this item (#318); 0 = no goal
    retired: bool = false, // a LATER user ask retired this finished item (#394): kept as the session's archive, invisible to every epoch-scoped query
    ask_fp: u64 = 0, // #1545: fingerprint of the user request this item was first written under; "cancelled" needs a newer one (0 = legacy/restored)
    reason: []const u8 = "", // #1520: why a "cancelled" item was withdrawn or delegated; required, shown with it (todo_cancel.zig)
    /// Completed or cancelled: no longer open work. A cancelled item is parked, never verified (goal_verify.taskVerified refuses it).
    pub fn closed(t: TodoItem) bool {
        return std.mem.eql(u8, t.status, "completed") or std.mem.eql(u8, t.status, "cancelled");
    }
};
/// Governed-run status for a standing /goal (#223). Only `.active` steers turns;
/// pause/resume and the run continuation gate (#226) key off the others.
pub const GoalStatus = enum { active, paused, blocked, complete };
/// A structured standing objective: the /goal text plus its lifecycle status and
/// created/updated timestamps. Replaces the bare `?[]const u8` so /goal can
/// pause/resume/report and persist a real state machine across resumes. The
/// `objective` string is owned by the session arena (like the old goal string).
pub const Goal = struct {
    objective: []const u8,
    status: GoalStatus = .active,
    epoch: u64 = 0, // monotonic per session; todos are stamped with it so a replaced goal cannot bequeath its checklist (#318)
    standing: bool = false, // seeded by --goal: steering policy for the WHOLE session that the model can never retire; only the user can, with /goal clear|pause|<new> (#318)
    created_ms: i64 = 0,
    updated_ms: i64 = 0,
    // Effort snapshots for task-outcome telemetry (task_outcome.zig): session
    // counters at goal-set time, diffed at completion/abandon.
    turns_at_set: u64 = 0,
    calls_at_set: u64 = 0,
    compacts_at_set: u64 = 0,
};
/// One agent: a message history plus the POST/tool-dispatch loop. The root
/// agent prints to stdout; subagents (sub = true) run on pool threads and
/// log through std.debug.print, which locks stderr and is thread-safe.
pub const Agent = struct {
    host_gate_mutex: Io.Mutex = .init, // agent_tool_gate.hostGate: an rlm host call gates on a pool thread
    gpa: Allocator,
    arena: Allocator,
    async_tools_armed: bool = false,
    async_tools: ?*@import("agent_async_tools.zig").State = null,
    /// #124: per-turn parse garbage (SSE envelopes, isStreamEnd) lives here and
    /// is reset each request() so the root session arena stays bounded. Null on
    /// subagents/one-shots (scratchAlloc() falls back to arena).
    scratch_arena: ?*std.heap.ArenaAllocator = null,
    /// Optional allocator for a temporary request transaction. compact() points
    /// this at its arena so failed summaries do not leak message rewrites or
    /// partial response trees into the long-lived session arena.
    message_mutation_arena: ?Allocator = null,
    io: Io,
    client: *std.http.Client,
    provider: Provider,
    subagent_provider: ?Provider = null, // optional model pin for every direct child/workflow/judge
    feedback: ?*@import("subagent_feedback.zig").Inbox = null,
    subagent_provider_explicit: bool = false, // #371: --subagent-*/GRAFF_SUBAGENT_*/--no-subagent-tier freeze it; a DERIVED default re-follows /model (providers.applyProviderInner)
    subagent_cross_provider: bool = false, // user explicitly allowed the pin to cross a provider/data boundary
    messages: std.json.Array,
    // Codex Responses WS delta transport: one WS held ACROSS user turns (codex_chain.zig), sending previous_response_id + only new items. Reset by closeCodexWs.
    codex_ws: ?*ws.WsClient = null,
    codex_prev_id: ?[]const u8 = null, // last response.id (gpa-owned); null = re-anchor with full input
    /// Codex WS prewarm in flight (openai/codex `generate:false`): the writer emits no input/transport fields, so the server prepares instructions+tools state that turn 1 chains onto.
    ws_prewarm: bool = false,
    codex_sent_upto: usize = 0, // messages the server already holds; delta = messages[codex_sent_upto..]
    codex_chain_rewrites: u32 = 0, // history_rewrites when the chain was anchored; a later compaction/trim invalidates it
    codex_props_fp: u64 = 0, // request properties the server anchored on (model/effort/fast/tools/instructions)
    codex_ws_used_ms: i64 = 0, // .awake-clock ms of the WS's last successful use; gates the idle preemptive re-anchor (#codex-ws)
    codex_ws_opened_ms: i64 = 0, // first connect time; xAI/codex WS hard-cap is 25 minutes
    ix_chain: @import("interactions_chain.zig").Chain = .{}, // Interactions previous_interaction_id chain (interactions_chain.zig)
    sub: bool,
    /// This agent is served NO tools at all — the `tools` field is omitted
    /// from the request rather than sent empty, which every provider accepts.
    /// Set for the variant judge: its own design comment says it "only
    /// reads/reasons over text handed to it, never the filesystem", but it was
    /// handed the full subagent catalog anyway and duly spent ~3 calls per
    /// score re-reading files it had already been given. With no tools it must
    /// answer from the excerpt in one call, which is what it was designed for.
    text_only: bool = false,
    synthesis: @import("workflow_synthesis.zig").State = .{},
    read_only: bool = false, // informational child: reads kept, writes refused (#1360, agent_tool_gate)
    label: []const u8,
    out: ?*Io.Writer,
    in: ?*Io.Reader = null, // stdin, root only — backs the ask_user tool
    /// Frontend event sink (#422). Null = resolved per emission from the
    /// process mode (engine_sink.forAgent); set to inject a custom frontend.
    sink: ?@import("engine_sink.zig").EngineSink = null,
    registry: ?*mcp.Registry = null,
    permission: ?@import("engine_permission.zig").Handler = null,
    approvals: ?*approvals_mod.Approvals = null, // shared bash-approval state, set by main()
    tracer: ?*trace.Tracer = null, // shared JSONL event trace, set by main()
    run_budget: ?*run_budget_mod.RunBudget = null, // shared invocation-wide call/concurrency ceiling
    depth: u8 = 0, // root/auxiliary = 0; delegated child = 1
    call_kind: run_budget_mod.CallKind = .root,
    last_cache_read: u64 = 0, // KV-cache read tokens from the latest response
    repo_map_snapshot: ?[]const u8 = null, // the resumed layout only; current instructions stay live
    sys_normal: []const u8 = prompts.main_system_prompt, // root system prompt (+ project instructions)
    sys_override: ?[]const u8 = null, // per-child custom prompt or transient isolated-review base
    task_prompt: ?[]const u8 = null, // a subagent's mandate, pinned once before the first history rewrite so compaction can restate it verbatim (recentContextStart can keep no verbatim suffix for a child - its only clean user turn is index 0)
    agent_cwd: ?[]const u8 = null, // subagent-only (#276 P0-1): absolute path of this agent's isolated git worktree, threaded through ToolCtx per tool call instead of a process-wide chdir — parallel siblings each keep their own
    tools_used: trace.ToolSink = .{}, // external tool calls this agent made (per turn for the root)
    tool_calls_this_turn: u64 = 0,
    read_miss: @import("read_miss.zig").Tracker = .{}, // #1116: same-prefix / incrementing read_file misses
    tool_repeat: @import("tool_repeat.zig").Tracker = .{}, // #1706: identical batches in a row end the turn
    model_calls_this_turn: u64 = 0,
    handle_note_shown: bool = false, // #541: the handle-protocol lesson rides this agent's FIRST handle, once
    seen_tool_keys: std.ArrayList([]const u8) = .empty, // root-only per-turn dedupe keys
    cite_stream: @import("terminal_citations.zig").State = .{}, // display-only, independent prose channels
    md_buf: std.ArrayList(u8) = .empty, // current incomplete streamed line (markdown rendering)
    md_cite: @import("cite_markup.zig").Stream = .{}, // display-only, survives split citation markers
    md_fence: bool = false, // inside a ``` code fence while streaming
    md_kind: MdKind = .classify, // incremental renderer: current line's classification
    md_span: MdSpan = .normal, // incremental renderer: inline **bold**/`code` span state
    md_table: std.ArrayList([]const u8) = .empty, // buffered table rows (gpa-duped), aligned+rendered when the table ends
    md_word: std.ArrayList(u8) = .empty, // prose wrap: pending word (incl. style bytes)
    md_word_vis: usize = 0, // its visible width
    md_col: usize = 0, // visible column on the current prose line
    md_indent: usize = 0, // hanging indent for wrapped continuation lines
    md_width: usize = 0, // cached termCols() for the current line (0 = unset)
    snapshots: ?*tools_mod.Snapshots = null, // file-edit history for /rewind (root only)
    pending_image: ?vision.PendingImage = null, // last staged image (history nav)
    pending_images: [16]vision.PendingImage = @splat(.{ .media_type = "", .b64 = "", .label = "" }),
    pending_image_len: u8 = 0, // queued pastes for this turn (#580)
    home: []const u8 = "", // $HOME, for /key persistence (set by main)
    model_catalog: ?models_cache.LazyCodexCatalog = null, // demand-loaded dynamic Codex rows (root only)
    stored_keys_loaded: bool = true, // false after an explicit-provider launch; model surfaces fill the remaining Keychain slots
    keep_context: bool = true, // carry the conversation across wire-format model switches (/keepcontext)
    reasoning: ReasoningEffort = .medium, // reasoning/thinking depth — xai, codex, deepseek, codegraff (/effort, /reasoning)
    jev_effort_pending: @import("jev_effort_state.zig").Pending = .{},
    fast: bool = false, // codex "fast" mode → priority service_tier (/fast)
    fallback_allow: []const []const u8 = &.{}, // explicit cross-provider allowlist from .harness/settings.json
    fallback_active: bool = false, // current provider/model is a temporary fallback, not the saved preference
    fallback_blocked: bool = false, // startup found a cross-provider fallback that is not allowlisted yet
    ultracode_mode: bool = false,
    review_mode: bool = false,
    show_thinking: bool = true, // stream the model's reasoning live in the TUI (/thinking); off = spinner only
    ai_title: bool = true, // AI-generate the tab/session title from the first prompt (/title)
    ai_recap: bool = true, // AI one-line status recap at turn end (settings: session_recap)
    goal: ?Goal = null, // structured objective + status lifecycle (/goal, #223)
    goal_note_fp: u64 = 0, // last-injected standing-goal note fingerprint (goal_state.steeringGate, #318)
    goal_note_age: u32 = 0, // turns since that note was last injected (refresh interval)
    pending_goal_note: ?[]const u8 = null, // one-shot supersession note for the next turn (/goal replace|clear)
    startup_effort_notice: ?[]const u8 = null, // ACP presents a corrected stale effort setting after session/new
    completion_gate_armed: bool = false, // attempt_completion was refused; the promised second call closes the goal. Persists ACROSS turns (a model emits one per turn) until the checklist or goal changes (#318)
    completion_refused: bool = false, // a refused attempt_completion this turn: work the model must react to, so the run must not read the turn as zero-tool (#318)
    todos_dirty: bool = false, // todo_write ran in THIS process: a checklist restored from disk is persisted state, never evidence that the current prompt is done (#318)
    goal_flag: ?[]const u8 = null, // --goal objective verbatim: re-applied over EVERY loadSession, including /resume, so the flag's contract survives restores (#318)
    loop_deadline_ms: ?i64 = null, // the running /goal run's wall-clock deadline (goal_pacing.LoopClock); read by the subagent spawn path so a child inherits it. Run-local: never saved, cleared on stop/steer
    history_rewrites: u32 = 0, // bumped by compact()/emergencyTrim; state pasted into the dead history (e.g. the run's checklist copy) must be re-carried (#318)
    worker_family: ?[]const u8 = null,
    worker_id: ?[]const u8 = null,
    session_name: []const u8 = "last", // autosave/resume target (<name>.session.json)
    session_parent: ?[]const u8 = null, // clone-on-write ancestry: this session branched from <parent>
    session_title: ?[]const u8 = null, // human-readable title/rename metadata
    sys_base: []const u8 = "", // #381: the last BASE handed to prompts.setSystemPrompts, WITHOUT the playbook block — what a mid-session constraint re-composes from (playbook_glue.refreshRoot)
    sys_strict: []const u8 = prompts.main_system_prompt_strict,
    sys_ultra: []const u8 = prompts.main_system_prompt ++ prompts.ultracode_system_note, // #326: comptime defaults only — prompts.setSystemPrompts() is the sole production writer
    sys_ultra_strict: []const u8 = prompts.main_system_prompt_ultra_strict, // composes onto sys_strict, never replaces it
    tools_anthropic: []const u8 = schema.tools_anthropic_sub,
    tools_openai: []const u8 = schema.tools_openai_sub,
    tools_responses: []const u8 = schema.tools_responses_sub,
    tools_interactions: []const u8 = @import("schema_interactions.zig").tools_interactions_sub,
    worker_tools: []const u8 = "", // ADR 0227: a spawned child's catalog plus the MCP tools its root loaded (worker_mcp.inherit); empty = the static child catalog
    todos: std.ArrayList(TodoItem) = .empty,
    pending_nudged_fp: ?u64 = null, // #1545: fingerprint of the open set the reconciliation guard last nudged; a repeat plain final on an unchanged checklist stops instead of re-reminding
    eval_cmd: ?[]const u8 = null, // --eval: shell command that scores the current output (eval-driven loop)
    eval_target: u8 = 90, // --until: stop when the score reaches this (0-100)
    eval_niche: []const u8 = "", // --niche: fleet niche this eval session optimizes; tags submitted scores into a promotable (niche × tier × suite) cell
    eval_judge: ?[]const u8 = null, // --judge: LLM-as-judge rubric, min()-blended with the --eval score (runJudge). Dormant until a CLI flag sets it.
    eval_iter: u32 = 0, // eval-loop iteration counter (scores log)
    eval_best: f64 = -1, // best score seen this session (-1 = none yet)
    eval_verified: bool = false, // latest workspace state has a target-meeting verifier result
    eval_repair_pending: bool = false, // a contradiction blocks completion until a fresh green eval
    eval_repair_grants: u8 = 0, // RED continuations consumed (agent_steps.grantRepairTurn); reset by any green eval, capped by eval_control.max_repair_grants
    eval_fp: ?[32]u8 = null, // #412: worktree fingerprint at the last RED eval (verify_fingerprint.Digest); an identical tree skips the re-verify instead of paying for it
    strict: bool = false,
    completed: ?[]const u8 = null,
    yielded: ?[]const u8 = null, // turn-local handoff, never a completed goal
    last_context_tokens: u64 = 0,
    context_local_tokens: u64 = 0, // local request estimate paired with last_context_tokens
    last_usage_includes_output: bool = false, // fresh usage covers response items step* is about to append
    /// Detail of the most recent API error — carried into the --json `error`
    /// event, which otherwise only knows "api error".
    last_api_error: ?[]const u8 = null,
    last_api_reauth: ?@import("auth_recovery.zig").Recovery = null,
    /// Text streamed so far in the current request — on Esc-interrupt this is
    /// what survives into history (with an "[interrupted]" marker appended).
    partial_text: std.ArrayList(u8) = .empty,
    stream_quiet: bool = false, // mute live paint (one-shot / compact); transport still streams
    compaction_request: bool = false, // the current model call is the synthetic compaction-summary request
    server_compaction_request: bool = false, // force one explicit Codex in-stream compaction pass
    compaction_window: @import("compaction_window.zig").State = .{}, // durable standalone-window provenance
    responses_output_limit: ?u32 = null, // auxiliary override (title=64); compaction always uses 4096
    last_request_context_overflow: bool = false, // explicit provider rejection, not an inferred meter threshold
    last_request_write_failed: bool = false, // transport gave up specifically with WriteFailed this request
    compact_transport_failures: u8 = 0, // bounded escape for repeated opaque over-cap WriteFailed/network failures
    compact_summary_failures: u8 = 0, // #379: consecutive complete-but-unusable (empty/truncated) summaries
    compact_pin_degraded: bool = false, // #581: pinned suffix over budget — skip+say once per unresolved turn
    compact_stall: @import("compact_cut.zig").Stall = .{}, // #706: same-boundary no-progress cuts
    compact_backoff: @import("compact_backoff.zig").Backoff = .{}, // #1686: compactions that bought no room
    empty_completion_retries: u8 = 0, // degenerate empty completions re-asked this turn (agent_empty_completion.zig)
    length_cutoffs: u8 = 0, // cut-off or runaway replies rewound this turn (agent_length_cutoff.zig)
    named_work_nudges: u8 = 0, // named-file / zero-tool nudge this turn (named_work.zig)
    named_work_task: []const u8 = "", // this turn's user text; arena-owned, never a child pointer
    named_work_settled: []const u8 = "", // mention already nudged or tooled
    precompact_note_gen: ?u32 = null, // #391: one pre-compaction note per history generation
    ws_off: bool = false, // codex ws transport disabled for this session after a handshake/transport fallback to SSE (#codex-ws)
    ws_api_error_pending: bool = false, // terminal WS error awaits Responses parsing/tracing; socket is already retired
    ws_transport_failures: u8 = 0, // consecutive WS failures; retry once before latching persistent SSE
    streamed_text: bool = false, // the last request printed its text live
    stall: @import("http_stall.zig").State = .{}, // #680: reconnects made this request (each widens the between-lines budget) + the budget that last tripped
    request_started: ?Io.Timestamp = null, // operational TTFT origin for the active model call (#602)
    first_token_traced: bool = false,
    thinking_open: bool = false, // a live "Thinking" reasoning block is currently streaming (/thinking)
    thinking_rows: usize = 0, // on-screen rows the live Thinking block spans (#75 collapse)
    thinking_col: usize = 0, // running column within the block, for soft-wrap counting
    thinking_overflow: bool = false, // block scrolled past the screen -> don't erase on collapse
    thinking_folded: bool = false, // user folded the live Thinking block (#92)
    thinking_text: std.ArrayList(u8) = .empty, // buffered reasoning, so a fold can unfold (#92)
    thinking_cite: @import("cite_markup.zig").Stream = .{},
    ai_title_done: bool = false, // the one-time AI tab-title call has run this session
    title_generation: u64 = 0, // invalidates detached results across /clear, /new, and manual /rename
    session_recap: ?@import("recap.zig").Recap = null, // last turn-end recap (#419): the session_recap wire event, and /status's recap line
    recap_generation: u64 = 0, // bumped at every turn start: supersedes detached recap jobs still in flight (#419)
    arg_live: ArgLive = .{}, // live attempt_completion/ask_user argument text
    streamed_args: ArgTool = .none, // which meta tool's prose streamed live this request
    streamed_args_len: usize = 0, // raw bytes emitted for it (gates re-print suppression)
    cap_new: bool = false, // provider rejected max_tokens → use max_completion_tokens
    sox_json_object: bool = false, // #543/#550: rejected json_schema / output_config → tool or json_object + schema-in-prompt
    effort_rejected: bool = false, // model rejected reasoning_effort → drop it (e.g. gpt-5.5 on chat/completions wants /v1/responses)
    output_schema: ?[]const u8 = null, // --output-schema: JSON schema the final answer must satisfy (response_format / text.format, #502)
    next_ask_id: u64 = 1,
    tui_header_shown: bool = false,

    // Width-budgeted status-line rendering lives in agent_prompt.zig (#209,
    // 600-line goal); member-aliased so `self.prompt()` still reads as one
    // of Agent's own methods.
    pub const prompt = prompt_ui.prompt;

    // say()/sayApiError() human-facing lines and emit() — the structured
    // --json JSONL writer — live in agent_output.zig (#422, 600-line cap).
    // Member-aliased so `self.say(...)`/`self.emit(...)` resolve unchanged.
    pub const say = @import("agent_output.zig").say;
    pub const sayApiError = @import("agent_output.zig").sayApiError;
    pub const emit = @import("agent_output.zig").emit;

    pub fn systemPrompt(self: *const Agent) []const u8 {
        if (self.review_mode or self.sub) return @import("prompt_text.zig").withAuthority(self.arena, self.sys_override orelse if (self.sub) prompts.sub_system_prompt else self.sys_normal);
        // #326: ultra composes onto normal/strict rather than replacing it.
        return if (self.strict) (if (prompts.ultracodeActive(self)) self.sys_ultra_strict else self.sys_strict) else (if (prompts.ultracodeActive(self)) self.sys_ultra else self.sys_normal);
    }

    /// Whether the active provider honors a reasoning-effort hint: the
    /// Responses API (codex, native xAI) via reasoning.effort, and the
    /// OpenAI-compatible providers that expose a thinking or effort control,
    /// including native xAI chat, MiMo, the codegraff gateway, and deepseek.
    pub fn effortApplies(self: *const Agent) bool {
        return schema.providerTakesEffort(self.provider.kind, self.provider.id, self.provider.model);
    }

    /// Whether this turn should put reasoning_effort on the wire.
    /// Flash / Gemini send `low` for the unset default (ADR 0046) — omitting
    /// the field still bills reasoning_tokens. /effort still applies.
    pub fn sendReasoningEffort(self: *const Agent) bool {
        return self.effortApplies() and !self.effort_rejected;
    }

    pub fn usesLiveTransport(_: *const Agent) bool {
        return true; // #682: stall-watched path; paint mute is out/stream_quiet
    }

    pub fn toolsJson(self: *const Agent) []const u8 {
        return @import("agent_catalog.zig").toolsJson(self);
    }
    pub const ensureRootTools = @import("agent_catalog.zig").ensureRootTools;
    pub const invalidateRootTools = @import("agent_catalog.zig").invalidateRootTools;
    pub noinline fn ensureModelCatalog(self: *Agent, keys: provider_mod.Keys) void {
        if (self.model_catalog) |*catalog|
            catalog.ensure(self.io, self.gpa, self.arena, self.home, keys.get("codex") orelse "", keys.codex_account);
    }

    pub fn reloadModelCatalog(self: *Agent, keys: provider_mod.Keys) void {
        if (self.model_catalog) |*catalog| catalog.invalidate();
        self.ensureModelCatalog(keys);
    }

    pub noinline fn ensureStoredKeys(self: *Agent, keys: *provider_mod.Keys) void {
        if (self.stored_keys_loaded) return;
        if (self.home.len != 0) keys_cli.loadMissingStoredKeys(self.io, self.gpa, self.arena, self.home, keys, .all);
        self.stored_keys_loaded = true;
    }

    /// Close the held codex Responses WS session and reset the delta state, so the
    /// next request re-anchors with full input. The chain now spans user turns
    /// (codex_chain.zig guards it), so this is for errors, idle and compaction.
    pub fn closeCodexWs(self: *Agent) void {
        if (self.codex_ws) |c| {
            c.deinit(self.gpa);
            self.codex_ws = null;
        }
        if (self.codex_prev_id) |p| {
            self.gpa.free(p);
            self.codex_prev_id = null;
        }
        self.codex_sent_upto = 0;
        self.codex_ws_opened_ms = 0;
    }

    pub fn runTurn(self: *Agent) anyerror![]const u8 {
        return @import("agent_turn.zig").run(self, &root_turn_prepared);
    }

    // The provider round trip (request/buildBody + usage/cost recording +
    // Codex/Responses SSE reassembly) lives in agent_request.zig (#123,
    // 600-line goal). Member-aliased so self.request(...)/etc. resolve unchanged.
    pub const request = @import("agent_request.zig").request;
    pub const inputOverCompactThreshold = @import("agent_request.zig").inputOverCompactThreshold;
    pub const fullInputEstimateTokens = @import("agent_request.zig").fullInputEstimateTokens;
    pub const fullRequestEstimateTokens = @import("agent_request.zig").fullRequestEstimateTokens;
    pub const contextEstimate = @import("agent_request.zig").contextEstimate;
    pub const contextEstimateFromInputBytes = @import("agent_request.zig").contextEstimateFromInputBytes;
    pub const effectiveContextTokens = @import("agent_request.zig").effectiveContextTokens;
    pub const pairContextMeterWithCurrentLocal = @import("agent_request.zig").pairContextMeterWithCurrentLocal;
    pub const rebaseContextMeter = @import("agent_request.zig").rebaseContextMeter;
    pub const recordUsage = @import("agent_request.zig").recordUsage;
    pub const usageInt = @import("agent_request.zig").usageInt;
    pub const recordCost = @import("agent_request.zig").recordCost;
    pub const ResponsesResult = @import("agent_request.zig").ResponsesResult;
    pub const parseResponses = @import("agent_request.zig").parseResponses;
    pub const errorMessage = @import("agent_request.zig").errorMessage;
    pub const recordUsageResponses = @import("agent_request.zig").recordUsageResponses;
    pub const buildBody = @import("agent_request.zig").buildBody;
    // Non-streaming response parsing (step*) + SSE-stream reassembly
    // (assemble*) live in agent_steps.zig (#123, 600-line goal).
    // Member-aliased so self.stepAnthropic(...)/etc. resolve unchanged.
    pub const stepResponses = @import("agent_steps.zig").stepResponses;
    pub const stepAnthropic = @import("agent_steps.zig").stepAnthropic;
    pub const stepOpenAI = @import("agent_steps.zig").stepOpenAI;
    pub const assembleStream = @import("agent_steps.zig").assembleStream;
    pub const assembleAnthropic = @import("agent_steps.zig").assembleAnthropic;
    pub const assembleOpenAI = @import("agent_steps.zig").assembleOpenAI;

    // Tool-call dispatch (runTools, the human-approval gate, meta-tool
    // handling, tool-call/result UX lines) lives in agent_tools.zig (#123,
    // 600-line goal). Member-aliased so self.runTools(...)/etc. resolve
    // unchanged.
    pub const runTools = @import("agent_tools.zig").runTools;
    pub const rejectToolCall = @import("agent_tools.zig").rejectToolCall;
    pub const toolDedupeKey = @import("agent_tools.zig").toolDedupeKey;
    pub const emitToolRejected = @import("agent_tools.zig").emitToolRejected;
    pub const gateTool = @import("agent_tools.zig").gateTool;
    pub const firstWord = @import("agent_tools.zig").firstWord;
    pub const handleMeta = @import("agent_tools.zig").handleMeta;
    pub const askUser = @import("ask_user.zig").askUser;
    pub const emitAskUser = @import("ask_user.zig").emitAskUser;
    pub const sayToolUse = @import("agent_tools.zig").sayToolUse;
    pub const sayToolResult = @import("agent_tools.zig").sayToolResult;
    pub const renderTodos = goal_state.renderTodos; // body in goal_state.zig (600-line cap)

    // Context management (compaction/emergency-trim) and the --eval/--until
    // eval-driven loop (+ optional LLM-as-judge) live in agent_compact.zig
    // (#123, 600-line goal). Member-aliased so self.compact(...)/etc.
    // resolve unchanged.
    pub const runEval = @import("agent_compact.zig").runEval;
    pub const appendEvalLog = @import("agent_compact.zig").appendEvalLog;
    pub const runJudge = @import("agent_compact.zig").runJudge;
    pub const compact = @import("agent_compact.zig").compact;
    pub const recentContextStart = @import("agent_compact.zig").recentContextStart;
    pub const cleanUserTurn = @import("agent_compact.zig").cleanUserTurn;
    pub const emergencyCutIndex = @import("agent_compact.zig").emergencyCutIndex;
    pub const emergencyTrim = @import("agent_compact.zig").emergencyTrim;
    pub const compactOrRecover = @import("agent_compact.zig").compactOrRecover;
    pub const manualCompact = @import("agent_server_compact.zig").manualCompact;
    pub const autocompact = @import("agent_server_compact.zig").autocompact;
    pub const autocompactResumed = @import("agent_server_compact.zig").autocompactResumed;
    pub const capOversizedToolOutputs = @import("agent_compact.zig").capOversizedToolOutputs;

    // The live streaming path (thinking spinner, live "Thinking" reasoning
    // block, and postStream itself — the root agent's streaming POST) lives
    // in agent_stream.zig (#123, 600-line goal). Member-aliased so
    // self.postStream(...)/etc. resolve unchanged. g_spin_stop/g_spin_future
    // below stay here (never alias a `var`).
    // ── thinking spinner ────────────────────────────────────────────────
    // An animated indicator on the root agent's line while the model is
    // silent: from request send, through connect + time-to-first-token,
    // and through reasoning-model thinking deltas (which print nothing) —
    // cleared the moment the first visible text byte streams (printDelta)
    // or the stream ends (postStream's defer). Root + interactive TTY only;
    // single-threaded start/stop, polling the stop flag every 20ms on the
    // pool so stopping is near-instant. Picked via /animation (ported in
    // spirit from arpagon/pi-animations, MIT), persists in settings.json.
    pub var g_spin_stop: std.atomic.Value(bool) = .init(true);
    pub var g_spin_future: ?Io.Future(void) = null;
    pub const spinnerTask = @import("agent_stream_render.zig").spinnerTask;
    pub const spinnerStart = @import("agent_stream_render.zig").spinnerStart;
    pub const spinnerStop = @import("agent_stream_render.zig").spinnerStop;
    pub const streamThinking = @import("agent_stream_render.zig").streamThinking;
    pub const closeThinkingBlock = @import("agent_stream_render.zig").closeThinkingBlock;
    pub const toggleThinkingFold = @import("agent_stream_render.zig").toggleThinkingFold;
    pub const postStream = @import("agent_stream.zig").postStream;
    pub const postStreamWithClient = @import("agent_stream.zig").postStreamWithClient;
    pub const printDelta = @import("agent_stream.zig").printDelta;
    pub const traceFirstToken = @import("agent_observability.zig").firstToken;
    // Codex Responses-over-WebSocket transport (+ its fresh-client SSE fallback
    // wrapper postLive) lives in agent_ws.zig (#codex-ws). Member-aliased.
    pub const postResponsesWs = @import("agent_ws.zig").postResponsesWs;
    pub const postLive = @import("agent_ws.zig").postLive;
    pub const wsEligible = @import("agent_ws.zig").wsEligible;
    /// Esc-during-tools cancellation. postStream only watches stdin while an
    /// HTTP stream is live, so a long tool join (bash, a subagent fan-out, a
    /// whole workflow) used to be Esc-deaf — exactly when turns feel longest.
    /// While the root awaits tool futures, escWatchTask polls stdin from the
    /// pool; Esc sets esc_cancel, which subagents poll between SSE lines and
    /// turn iterations, and the root consumes at its next loop head as
    /// error.Interrupted.
    pub var esc_cancel: std.atomic.Value(bool) = .init(false);
    var root_turn_prepared: std.atomic.Value(bool) = .init(false);
    pub var esc_watch_done: std.atomic.Value(bool) = .init(true);

    /// Clear stale cancellation before the root becomes externally cancellable;
    /// runTurn consumes the marker without erasing a cancellation arriving later.
    pub fn prepareRootTurn() void {
        @import("cancel_source.zig").clear(); // flag + source (#728)
        @import("job_wait.zig").followup_pending.store(false, .release);
        root_turn_prepared.store(true, .release);
    }

    // Esc-cancel handling (the stdin scanner + steering-buffer capture +
    // interruptible sleep) lives in agent_interrupt.zig (#123, 600-line
    // goal). Member-aliased so self.sleepInterruptible(...)/etc. resolve
    // unchanged. esc_cancel/esc_watch_done above stay here (never alias a
    // `var`); ssePayload/sseIndex live there too since they're only
    // consumed alongside the interrupt-watch plumbing in postStream.
    /// Allocator for per-turn transient scratch (#124): the reset-per-request
    /// scratch arena when set (root), else the session arena (subagents/one-shot).
    pub fn scratchAlloc(self: *Agent) Allocator {
        return if (self.scratch_arena) |sa| sa.allocator() else self.arena;
    }

    pub const messageMutationAlloc = @import("agent_alloc.zig").messageMutationAlloc;

    pub const escWatchTask = @import("agent_interrupt.zig").escWatchTask;
    pub const escPressed = @import("agent_interrupt.zig").escPressed;
    pub const drainSteerStdin = @import("agent_interrupt.zig").drainSteerStdin;
    pub const drainStdin = @import("agent_interrupt.zig").drainStdin;
    pub const rawNonblockStdin = @import("agent_interrupt.zig").rawNonblockStdin;
    pub const restoreStdin = @import("agent_interrupt.zig").restoreStdin;
    pub const sleepInterruptible = @import("agent_interrupt.zig").sleepInterruptible;
    pub const ssePayload = @import("agent_interrupt.zig").ssePayload;
    pub const sseIndex = @import("agent_interrupt.zig").sseIndex;

    // Live streaming of attempt_completion/ask_user tool-argument prose (the
    // ArgLive byte-scanner) lives in agent_argstream.zig (#123, 600-line
    // goal). Member-aliased so self.arg_live's type + the streaming callbacks
    // resolve unchanged regardless of physical file.
    pub const ArgTool = @import("agent_argstream.zig").ArgTool;
    pub const ArgLive = @import("agent_argstream.zig").ArgLive;
    pub const argToolFor = @import("agent_argstream.zig").argToolFor;
    pub const argField = @import("agent_argstream.zig").argField;
    pub const outputIndex = @import("agent_argstream.zig").outputIndex;
    pub const argLiveDelta = @import("agent_argstream.zig").argLiveDelta;
    pub const emitArgText = @import("agent_argstream.zig").emitArgText;
    pub const argStreamedFully = @import("agent_argstream.zig").argStreamedFully;

    // The incremental streaming markdown renderer (byte-at-a-time line
    // classifier + non-streaming renderMdLine) lives in agent_render.zig
    // (#123, 600-line goal). Member-aliased so `self.streamMarkdown(...)`
    // and the field types below resolve unchanged regardless of physical
    // file.
    pub const MdKind = @import("agent_render.zig").MdKind;
    pub const MdSpan = @import("agent_render.zig").MdSpan;
    pub const streamMarkdown = @import("agent_render.zig").streamMarkdown;
    pub const inlineVisibleLen = @import("agent_render.zig").inlineVisibleLen;
    pub const codepointCount = @import("agent_render.zig").codepointCount;
    pub const flushStreamTail = @import("agent_render.zig").flushStreamTail;
    pub const renderMdLine = @import("agent_render.zig").renderMdLine;
    pub const renderInline = @import("agent_render.zig").renderInline;
    pub const mdByte = @import("agent_render.zig").mdByte;
    pub const mdTryClassify = @import("agent_render.zig").mdTryClassify;
    pub const mdStartProse = @import("agent_render.zig").mdStartProse;
    pub const mdSpanByte = @import("agent_render.zig").mdSpanByte;
    pub const mdWrapByte = @import("agent_render.zig").mdWrapByte;
    pub const mdStyle = @import("agent_render.zig").mdStyle;
    pub const mdFlushWord = @import("agent_render.zig").mdFlushWord;
    pub const mdWrapBreak = @import("agent_render.zig").mdWrapBreak;
    pub const mdWidth = @import("agent_render.zig").mdWidth;
    pub const mdSpanEnd = @import("agent_render.zig").mdSpanEnd;
    pub const mdFinishLine = @import("agent_render.zig").mdFinishLine;
    pub const flushTable = @import("agent_table.zig").flushTable;
    pub const fitWidths = @import("agent_table.zig").fitWidths;
    pub const atomEnd = @import("agent_table.zig").atomEnd;
    pub const wrapCell = @import("agent_table.zig").wrapCell;
    pub const isTableSeparator = @import("agent_table.zig").isTableSeparator;
    pub const isTableRowLine = @import("agent_table.zig").isTableRowLine;
};

test {
    _ = @import("agent_prompt.zig");
    _ = @import("effort_route.zig");
    try agent_tests.lazyRootTools(Agent);
}

fn pendingStateFixture(arena: Allocator) Agent {
    return .{
        .gpa = arena,
        .arena = arena,
        .io = std.testing.io,
        .client = undefined,
        .provider = .{ .id = "test", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "test", .context = 100_000 },
        .messages = .init(arena),
        .sub = false,
        .label = "pending",
        .out = null,
        .tool_calls_this_turn = 3,
        .model_calls_this_turn = 4,
    };
}

test "#1545 a repeat plain final on an unchanged checklist stops without re-reminding" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const PendingWork = @import("agent_empty_completion.zig").PendingWork;
    var self = pendingStateFixture(arena.allocator());
    try self.todos.append(self.arena, .{ .content = "credit grant", .status = "pending" });
    try self.todos.append(self.arena, .{ .content = "roll out", .status = "in_progress" });
    // Turn 1: the one retry.
    var first: PendingWork = .{};
    try std.testing.expect((try first.finish(&self, "stopping")) == null);
    try std.testing.expectEqual(@as(usize, 1), self.messages.items.len);
    // Turn 2 (fresh per-turn state, same checklist): footer, no new message.
    var second: PendingWork = .{};
    const final = (try second.finish(&self, "stopping")).?;
    try std.testing.expect(std.mem.indexOf(u8, final, "Root execution has stopped with 2 open checklist items") != null);
    try std.testing.expectEqual(@as(usize, 1), self.messages.items.len);
    // Re-planned work re-arms: cancelling one item changes the open set.
    self.todos.items[0].status = "cancelled";
    var third: PendingWork = .{};
    try std.testing.expect((try third.finish(&self, "stopping again")) == null);
    try std.testing.expectEqual(@as(usize, 2), self.messages.items.len);
}

test "#1545 cancelled items are records: skipped by open/allDone, kept by replace, rendered [-]" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const PendingWork = @import("agent_empty_completion.zig").PendingWork;
    var self = pendingStateFixture(arena.allocator());
    try self.todos.append(self.arena, .{ .content = "live", .status = "pending" });
    try self.todos.append(self.arena, .{ .content = "abandoned", .status = "cancelled" });
    const goals = @import("goal_state.zig");
    try std.testing.expectEqual(@as(usize, 1), goals.openCount(self.todos.items, 0));
    try std.testing.expect(!goals.allDone(self.todos.items, 0));
    self.todos.items[0].status = "completed";
    try std.testing.expect(goals.allDone(self.todos.items, 0));
    // A replace that omits the cancelled item keeps it (retention, like completed).
    // "live" is mentioned so it clears here (applyTodoWrite re-appends it);
    // the cancelled item survives and nothing counts as cancelled-open.
    const incoming = [_][]const u8{"live"};
    const cleared = @import("goal_todo.zig").clearEpochForReplaceEx(&self.todos, 0, &incoming);
    try std.testing.expectEqual(@as(usize, 0), cleared.dropped_open);
    try std.testing.expectEqual(@as(usize, 1), self.todos.items.len);
    try std.testing.expectEqualStrings("abandoned", self.todos.items[0].content);
    const rendered = goals.renderTodos(&self, 0);
    try std.testing.expect(std.mem.indexOf(u8, rendered, "[-] abandoned") != null);
    // And the guard goes quiet: no open work left once live completes; live
    // is completed here, cancelled never counted, so the final passes through.
    var state: PendingWork = .{};
    try std.testing.expectEqualStrings("done", (try state.finish(&self, "done")).?);
    try std.testing.expectEqual(@as(usize, 0), self.messages.items.len);
}