Skip to content

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

Python
16.9 KB
Raw Blame
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);
}