graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! 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);
}