graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const agent_mod = @import("agent.zig");
const provider_mod = @import("provider.zig");
const main_mod = @import("main.zig");
const providers = @import("providers.zig");
const telemetry = @import("telemetry.zig");
const session = @import("session.zig");
const stream = @import("acp_stream.zig");
const review = @import("review.zig");
const messages = @import("messages.zig");
const cancel_source = @import("cancel_source.zig");
const trace = @import("trace.zig");
const turn_trace = @import("mainloop_trace.zig");
const proto = @import("acp_protocol.zig");
pub const LiveTurn = struct {
root: *agent_mod.Agent,
keys: *provider_mod.Keys,
out: *Io.Writer,
session_id: []const u8 = "",
saw_text: bool = false,
local_catalog_loaded: bool = false,
prev_turn_id: u64 = 0,
prev_prompt_fp: [16]u8 = @splat(0),
inbox: ?*@import("acp_inbox.zig").Inbox = null,
dispatch: ?*@import("acp_engine.zig").Dispatch = null,
/// Launch `--model`: outranks a loaded session's saved model, as on CLI resume.
model_override: ?provider_mod.Provider = null,
/// The context count the last mid-turn meter carried.
last_meter_used: u64 = 0,
cancelled_source: ?cancel_source.Source = null,
/// Mid-turn `usage_update`, only when the count moved since the last one.
fn stepMeter(ctx: *anyopaque, w: *Io.Writer) void {
const self: *LiveTurn = @ptrCast(@alignCast(ctx));
const meter = @import("acp_context_meter.zig");
const used = self.root.effectiveContextTokens();
const window = self.root.provider.context;
if (window == 0 or used == self.last_meter_used) return;
self.last_meter_used = used;
meter.write(w, self.session_id, used, window, meter.knownCostUsd(self.root.io), @import("context_savings.zig").snap(self.root.io)) catch {};
}
pub fn bindSession(ctx: *anyopaque, session_id: []const u8) void {
const self: *LiveTurn = @ptrCast(@alignCast(ctx));
self.session_id = session_id;
self.root.last_api_reauth = null;
}
pub fn errorRecovery(ctx: *anyopaque, err: anyerror) ?@import("auth_recovery.zig").Recovery {
const self: *LiveTurn = @ptrCast(@alignCast(ctx));
return switch (err) {
error.ApiError, error.ProviderAuthenticationFailed => self.root.last_api_reauth,
else => null,
};
}
pub fn errorMessage(ctx: *anyopaque, err: anyerror) []const u8 {
const self: *LiveTurn = @ptrCast(@alignCast(ctx));
return describeError(err, self.root.last_api_error);
}
pub fn signalCancel() void {
cancel_source.cancel(cancel_source.takeAcp()); // #728, #1611
}
pub fn cancelled() bool {
return agent_mod.Agent.esc_cancel.load(.acquire);
}
pub fn cancelInfo(ctx: *anyopaque) ?@import("acp_engine.zig").Cancellation {
const self: *LiveTurn = @ptrCast(@alignCast(ctx));
const source = self.cancelled_source orelse return null;
return .{ .source = @tagName(source), .message = cancel_source.marker(source) };
}
pub fn run(ctx: *anyopaque, arena: Allocator, text: []const u8) anyerror![]const u8 {
const self: *LiveTurn = @ptrCast(@alignCast(ctx));
self.cancelled_source = null;
var output_lock: Io.Mutex = .init;
if (self.inbox) |inbox| if (inbox.permission) |bridge| bridge.setOutputLock(&output_lock);
defer if (self.inbox) |inbox| if (inbox.permission) |bridge| bridge.setOutputLock(null);
// Receipt marker before any dedup/turn work: a worker that logged its
// recipe but never this line never received its prompt — the stall is
// upstream (client dispatch / bootstrap / transport), not in the turn.
if (self.root.tracer) |tr| tr.note("acp_prompt", self.session_id);
agent_mod.Agent.prepareRootTurn(); // #753: a prior stream cancel must not steal the continuation
if (self.inbox) |inbox| {
if (inbox.permission) |bridge| bridge.begin(self.session_id);
inbox.begin();
}
defer if (self.inbox) |inbox| {
if (inbox.permission) |bridge| bridge.cancel();
inbox.end();
};
// An objective sets state AND starts this turn, unlike lifecycle verbs (#1528).
const goal_pacing = @import("goal_pacing.zig");
const line = std.mem.trim(u8, text, " \t\r\n");
const commands = if (self.dispatch) |d| d.commands else true;
const objective = if (commands) @import("repl_glue.zig").goalPromptFromLine(line) else null;
const auto = if (commands) try goal_pacing.autonomousFromLine(arena, line, objective, false) else null;
var clock: goal_pacing.LoopClock = .{};
defer clock.clear(self.root);
if (auto) |invocation| {
var aw: Io.Writer.Allocating = .init(arena);
try goal_pacing.armAndAnnounce(&clock, self.root, &aw.writer, arena, @import("util.zig").unixMs(self.root.io), invocation.budget());
try main_mod.handleCommand(self.root, self.keys, arena, invocation.goal_line.?, &aw.writer);
const notice = try @import("acp_engine.zig").stripSgr(arena, aw.writer.buffered());
output_lock.lockUncancelable(self.root.io);
defer output_lock.unlock(self.root.io);
try proto.writeSessionUpdate(self.out, self.session_id, try std.fmt.allocPrint(arena, "{s}\n", .{notice}));
try self.out.flush();
}
const review_prompt = if (commands) review.promptFromLine(text) else null;
const issue_report = if (commands) @import("issue_cmd.zig").promptFromLine(text) else null;
const parent_override = self.root.sys_override;
const parent_review_mode = self.root.review_mode;
self.root.review_mode = review_prompt != null;
defer {
self.root.review_mode = parent_review_mode;
self.root.sys_override = parent_override;
}
if (review_prompt != null)
self.root.sys_override = try review.systemPrompt(arena, self.root.sys_normal);
var context = review.Context.begin(arena, self.root, review_prompt != null);
defer if (context.restore(self.root)) self.root.rebaseContextMeter();
if (commands and @import("side_steer.zig").isSideRequest(text))
return @import("side_steer.zig").spawnSide(self.root, arena, null, text);
// Match REPL expansion order: review, issue brief, then goal pacing.
const base_prompt = review_prompt orelse if (issue_report) |report| try @import("issue_cmd.zig").userText(arena, report) else if (auto) |invocation| invocation.prompt else text;
const prompt = try @import("goal_state.zig").applyGoalSteering(arena, self.root, base_prompt);
switch (try @import("turn_dedup.zig").enqueue(self.root, arena, self.out, prompt)) {
.started => {},
.skipped => return "",
.stuck => return @import("turn_dedup.zig").stuck_text,
}
if (telemetry.g_telem) |t| t.beginTurn(@intCast(@min(text.len, std.math.maxInt(u32))), self.root.provider.model);
self.saw_text = false;
var sink: stream.EventSink = undefined;
sink.init(self.root.gpa, self.out, &self.session_id, &self.saw_text);
sink.output_lock = &output_lock;
sink.output_io = self.root.io;
sink.step = .{ .ctx = self, .run = stepMeter };
var compaction: @import("acp_compaction.zig").Sink = .{ .out = self.out, .output_lock = &output_lock, .io = self.root.io, .session_id = self.session_id, .events = &sink.writer };
@import("acp_compaction.zig").install(&compaction);
defer @import("acp_compaction.zig").uninstall();
// Standard progress on the parent tool call by default; the draft
// child-session stream only when both sides opted in (ADR 0194/0205).
const draft = self.dispatch != null and self.dispatch.?.subagents and self.dispatch.?.draft_subagents_enabled;
defer sink.deinit();
var child_state: @import("acp_subagent_live.zig").State = .{ .out = self.out, .parent = self.session_id, .output_lock = &output_lock, .mode = if (draft) .draft else .progress };
@import("acp_subagent_live.zig").install(self.root.io, &child_state);
defer @import("acp_subagent_live.zig").uninstall(self.root.io);
self.root.out = &sink.writer;
main_mod.g_out = &sink.writer;
defer {
sink.writer.flush() catch {};
self.root.out = null;
main_mod.g_out = null;
}
const turn_id: u64 = if (trace.g_traj) |trajectory| blk: {
const id = trajectory.nextId();
trajectory.setTurn(id);
break :blk id;
} else 0;
self.root.tools_used.clear(self.root.io);
self.root.tool_calls_this_turn = 0;
self.root.model_calls_this_turn = 0;
const before = turn_trace.begin(self.root, self.root.io);
turn_trace.recordLive(self.root, text, turn_id, self.prev_turn_id);
const started = Io.Timestamp.now(self.root.io, .awake);
const result = providers.runTurnWithFallback(self.root, self.keys, arena, null);
// Supplemental metadata must not replace the turn outcome or prevent
// trace/session persistence if the client disconnects. Emit on exit,
// after the durable work below, while retaining whole-message locking.
defer {
sink.writer.flush() catch {};
main_mod.g_gui_mu.lockUncancelable(self.root.io);
defer main_mod.g_gui_mu.unlock(self.root.io);
output_lock.lockUncancelable(self.root.io);
defer output_lock.unlock(self.root.io);
@import("acp_usage.zig").writeBestEffort(self.out, self.session_id, &@import("pricing.zig").g_cost, self.root.io);
}
turn_trace.record(self.root, self.root.io, arena, text, turn_id, started, result, self.root.effectiveContextTokens(), before, &self.prev_turn_id, &self.prev_prompt_fp);
const isolated = context.restore(self.root);
if (isolated) {
self.root.review_mode = parent_review_mode;
self.root.sys_override = parent_override;
try self.root.messages.append(try messages.textMessage(arena, "user", text));
self.root.rebaseContextMeter();
}
const final = result catch |err| {
if (err == error.Interrupted or err == error.Canceled) {
self.cancelled_source = cancel_source.take(self.root.tracer);
if (!isolated) try self.root.messages.append(try messages.textMessage(
arena,
"assistant",
cancel_source.marker(self.cancelled_source.?),
));
}
// #1639: like the REPL, a turn the transport ended keeps its
// partial reply and says why, so the next prompt (and a resume)
// sees where the answer stopped instead of no reply at all.
if (!isolated and (err == error.StreamDropped or err == error.StreamStalled)) {
const ended = try @import("stream_reconnect.zig").endedEarlyText(arena, self.root.partial_text.items, err == error.StreamStalled);
try self.root.messages.append(try messages.textMessage(arena, "assistant", ended));
}
if (isolated) {
const marker = if (err == error.Interrupted or err == error.Canceled)
cancel_source.marker(self.cancelled_source.?)
else
try std.fmt.allocPrint(arena, "[review ended early: {s}; findings are incomplete]", .{@errorName(err)});
const partial = std.mem.trim(u8, self.root.partial_text.items, " \t\r\n");
const report = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ partial, marker });
try self.root.messages.append(try messages.textMessage(arena, "assistant", report));
try sink.writer.flush();
output_lock.lockUncancelable(self.root.io);
defer output_lock.unlock(self.root.io);
try proto.writeSessionUpdate(self.out, self.session_id, marker);
}
// #1729: same row as the REPL, so resending this prompt is a new ask.
try @import("turn_dedup.zig").settleFailedTurn(self.root, arena, err);
// #753: an API interruption is a failed turn, not a dead ACP
// process. Save so the next prompt (and a respawn --resume) still
// sees the tool results and the background-agent ledger.
session.saveSession(self.root, self.root.arena, self.root.session_name) catch {};
return err;
};
// The REPL checkpoints after every turn (mainloop); an ACP host's
// conversation deserves the same durability. Without this a text-only
// turn reached .graff/sessions only at stdin EOF, and a tab the host
// killed never did. The root arena, not this turn's: the queued write
// outlives the turn.
if (isolated)
try self.root.messages.append(try messages.textMessage(arena, "assistant", final));
session.saveSessionAsync(self.root, self.root.arena, self.root.session_name) catch {};
// saw_text is "the LAST streamed event was answer text" (tool events
// reset it in the sink): a turn that ended mid-text already delivered
// the answer; one that ended on tools (attempt_completion flows) has
// its answer only in `final`, so that must still go on the wire.
if (self.saw_text) return "";
// A streamed preamble and the final answer are separate paragraphs;
// without the break the client renders "…answering.The three files…".
if (final.len > 0 and sink.streamed_any)
return try std.fmt.allocPrint(arena, "\n\n{s}", .{final});
return final;
}
};
/// What an ACP client shows for a failed turn. An exhausted empty-reply retry
/// carries its own explanation (#1802); a bare error name told the user nothing.
pub fn describeError(err: anyerror, last_api_error: ?[]const u8) []const u8 {
return switch (err) {
error.ApiError, error.ProviderAuthenticationFailed => last_api_error orelse "Provider request failed",
error.EmptyCompletion => last_api_error orelse @import("agent_empty_completion.zig").exhausted_text,
else => @errorName(err),
};
}
test "#1802: an exhausted empty-reply retry is explained, not named" {
const exhausted = @import("agent_empty_completion.zig").exhausted_text;
try std.testing.expectEqualStrings(exhausted, describeError(error.EmptyCompletion, exhausted));
try std.testing.expectEqualStrings(exhausted, describeError(error.EmptyCompletion, null));
try std.testing.expect(std.mem.indexOf(u8, exhausted, "6 times") != null);
try std.testing.expectEqualStrings("Provider request failed", describeError(error.ApiError, null));
try std.testing.expectEqualStrings("Interrupted", describeError(error.Interrupted, "stale"));
}
test "session/prompt receipt is traced even when dedup skips the turn" {
const dedup = @import("turn_dedup.zig");
dedup.resetForTest();
defer dedup.resetForTest();
@import("side_steer.zig").resetForTest();
defer @import("side_steer.zig").resetForTest();
const interactive = @import("subagent_interactive.zig");
const was_notice = interactive.line_notice;
interactive.line_notice = false;
defer interactive.line_notice = was_notice;
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
var aw: Io.Writer.Allocating = .init(a);
defer aw.deinit();
var tracer: trace.Tracer = .{
.io = std.testing.io,
.gpa = std.testing.allocator,
.out = &aw.writer,
.start = Io.Timestamp.now(std.testing.io, .awake),
};
var root: agent_mod.Agent = .{
.gpa = std.testing.allocator,
.arena = a,
.io = std.testing.io,
.client = undefined,
.provider = .{ .id = "xai", .kind = .openai, .auth = .bearer, .url = "", .api_key = "k", .model = "grok-4.6", .context = 100_000 },
.messages = std.json.Array.init(a),
.sub = false,
.label = "test",
.out = null,
.tracer = &tracer,
};
try root.messages.append(try messages.textMessage(a, "user", "hi"));
var keys: provider_mod.Keys = .{ .values = @splat(null) };
var out_buf: [1024]u8 = undefined;
var out: Io.Writer = .fixed(&out_buf);
var live: LiveTurn = .{ .root = &root, .keys = &keys, .out = &out, .session_id = "s1" };
// A back-to-back duplicate skips the model turn entirely — the receipt
// marker must already be in the trace, or a skipped prompt is
// indistinguishable from one the worker never received.
try std.testing.expectEqualStrings("", try LiveTurn.run(&live, a, "hi"));
const logged = aw.writer.buffered();
try std.testing.expect(std.mem.indexOf(u8, logged, "\"acp_prompt\"") != null);
try std.testing.expect(std.mem.indexOf(u8, logged, "s1") != null);
}