Skip to content

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

Python
8.9 KB
Raw Blame
//! The shared agent turn loop, including explicit non-completing handoffs.

const std = @import("std");
const Agent = @import("agent.zig").Agent;
const main_mod = @import("main.zig");
const empty_completion = @import("agent_empty_completion.zig");
const turn_inbox = @import("turn_inbox.zig");

pub fn run(self: *Agent, root_turn_prepared: *std.atomic.Value(bool)) anyerror![]const u8 {
    defer @import("jev_effort_state.zig").finishTurn(self);
    errdefer self.jev_effort_pending.invalidate(self.io);
    @import("jev_auto.zig").beginTurn(self); // ADR 0246: Jev picks this turn's effort; finishTurn puts it back
    self.async_tools_armed = !self.sub and self.eval_cmd == null;
    defer self.async_tools_armed = false;
    defer @import("agent_async_tools.zig").reset(self);
    if (!self.sub) @import("peer_idle.zig").noteTurnStart();
    defer if (!self.sub) @import("peer_idle.zig").noteTurnEnd();
    var pending_work = empty_completion.PendingWork.begin(self);
    var bounced_answer: empty_completion.BounceAnswer = .{};
    var length: @import("agent_length.zig").State = .{};
    self.empty_completion_retries = 0;
    self.length_cutoffs = 0; // agent_length_cutoff.zig: rewinds this turn
    self.completed = null;
    self.yielded = null;
    self.read_miss.reset();
    self.tool_repeat.reset();
    @import("named_work.zig").beginTurn(self);
    try self.ensureRootTools(self.provider.kind);
    var task_scope = @import("task_intent.zig").State.begin(self);
    if (!self.sub and !root_turn_prepared.swap(false, .acq_rel)) @import("cancel_source.zig").clear();
    var review_deadline = try @import("review_deadline.zig").start(self);
    defer review_deadline.stop();
    while (true) {
        try task_scope.beforeRequest(self);
        if (try @import("turn_chrome.zig").beforeRequest(self)) |paused| return review_deadline.finish(paused);
        // Esc during a tool join lands here; root consumes, subagents bail.
        if (Agent.esc_cancel.load(.acquire)) {
            if (!self.sub) Agent.esc_cancel.store(false, .release);
            return error.Interrupted;
        }
        // Peer mail, job/schedule wakes, and REPL steer land here so a
        // follow-up typed during tools is the next user message in this
        // turn rather than the next prompt after runTurn returns.
        try turn_inbox.deliver(self);
        // #193: pre-send overflow gate. A single turn's tool-output burst can
        // push the input past the model's wall before the between-turns 80%
        // meter (last_context_tokens, server-reported) catches up. Estimate the
        // full input locally and compact BEFORE sending so we never ship an
        // over-cap request (codex run_pre_sampling_compact / opencode isOverflow).
        const over_compact = self.inputOverCompactThreshold();
        @import("compact_backoff.zig").step(&self.compact_backoff, self.history_rewrites, over_compact);
        if (over_compact and !readBatchFirst(self) and !compactionHeld(self)) {
            // Bracket the compaction with codex-WS resets, mirroring how every
            // other compactOrRecover call site is bookended by runTurn's
            // closeCodexWs (299 + defer 300). Mid-turn the WS can be live with a
            // prev_id / codex_sent_upto watermark keyed to the pre-trim history:
            // (1) the first reset lets compact()'s own summary request (it calls
            // request() at agent_compact.zig:267, after shrinking history at
            // 259-260) run against a clean session — a stale prev_id makes the
            // server re-prepend the full pre-trim context, defeating or
            // overflowing the summary itself; (2) the second re-anchors so the
            // next in-turn request() re-sends the trimmed full input, not a delta
            // keyed to dropped messages (same closeCodexWs-after-trim reason as
            // the in-turn recovery at agent_request.zig:273).
            self.closeCodexWs();
            // Match the between-turn policy: at the ordinary compactAt
            // threshold, a transient/empty summary must not immediately drop
            // real history. Destructive recovery is reserved for >=95%.
            const recovery_meter = self.effectiveContextTokens();
            self.autocompact(recovery_meter);
            self.closeCodexWs();
        }
        // ADR 0030: showcase rlm once the existing compact meter is
        // actually large. Schema rides the tail; head bytes stay put.
        if (!self.sub) {
            const fold = @import("native_fold.zig");
            if (fold.noticeContext(self.effectiveContextTokens(), self.provider.compactAt())) {
                self.invalidateRootTools();
                try self.ensureRootTools(self.provider.kind);
            }
        }
        if (self.sub) try self.synthesis.beforeRequest(self);
        const hist_len = self.messages.items.len;
        const root = self.request(if (self.text_only and !self.synthesis.keepsCatalog(self)) null else self.toolsJson()) catch |err| {
            if (try @import("agent_length_cutoff.zig").recoverRunaway(self, err, hist_len)) continue;
            return review_deadline.finish(try @import("agent_model_loop.zig").finishError(self, err));
        };
        // request() may compact history; capture this reply's actual boundary.
        // Keep reasoning available to recovery, then exclude non-replayable
        // empty length replies on every exit before another call or save.
        const reply_start = self.messages.items.len;
        defer @import("agent_length_cutoff.zig").discardEmptyReply(self, root, reply_start);
        const done = try length.step(self, root);
        if (done == null) if (self.tool_repeat.stopText()) |stop| { // #1706: every wire's tool batch lands here
            try self.say("{s}\n", .{stop});
            _ = @import("tool_call_repair.zig").endsTurn(self, stop);
            return review_deadline.finish(stop);
        };
        if (done) |final_text| {
            if (self.yielded != null) return review_deadline.finish(final_text);
            if (@import("tool_call_repair.zig").endsTurn(self, final_text)) return review_deadline.finish(final_text); // final: no retry/nudge
            // Retry empty replies; reconcile plain finals with live work (#745).
            if (try bounced_answer.retry(self, final_text, hist_len)) continue;
            if (try @import("named_work.zig").handle(self, final_text)) continue;
            if (try pending_work.finish(self, bounced_answer.finish(self, final_text))) |text| {
                if (self.feedback) |inbox| if (!inbox.tryFinish(self.io)) continue;
                settleFinal(self);
                return review_deadline.finish(text);
            }
            continue;
        }
        self.empty_completion_retries = 0;
    }
}

/// A root turn that ends with its answer settles the human task (#1137):
/// ambient peer mail then waits for the next human prompt instead of
/// reopening it. A yielded turn is a handoff, already latched harder; a
/// stopped tool loop did not finish the task and settles nothing.
fn settleFinal(self: *Agent) void {
    if (!self.sub) @import("peer_idle.zig").noteFinalAnswer();
}

/// #1686: the previous compaction left the context over the line; wait for
/// real growth (or the 95% wall) instead of compacting on every step.
fn compactionHeld(self: *Agent) bool {
    const context = self.effectiveContextTokens();
    const backoff = @import("compact_backoff.zig");
    switch (backoff.gate(&self.compact_backoff, context, self.provider.context, self.provider.nearContextLimit(context))) {
        .compact => return false,
        .hold => return true,
        .hold_started => {
            if (self.tracer) |tr| tr.note("compact", "held: the last compaction left the context over the line");
            if (!main_mod.json_mode) self.say("[compaction freed too little room; compacting again once the context grows]\n", .{}) catch {};
            return true;
        },
    }
}

/// Over the compaction line, but the history ends on a tool batch the model
/// has not read and almost everything else is that batch. A compaction keeps
/// the batch verbatim (compact_cut.unreadToolBatch), so it could only
/// summarize the small prefix in front of it: a summary round trip that buys
/// little. Send the request instead and compact once the model has read the
/// batch. Near the window (95%) the ordinary recovery runs regardless.
fn readBatchFirst(self: *Agent) bool {
    const compact_cut = @import("compact_cut.zig");
    const items = self.messages.items;
    if (compact_cut.unreadToolBatch(items) == null) return false;
    if (self.provider.nearContextLimit(self.effectiveContextTokens())) return false;
    const start = compact_cut.recentContextStart(items, @import("agent_compact.zig").recent_context_tokens);
    const prefix = compact_cut.suffixTokens(items[0..start], 0);
    if (prefix >= self.provider.compactAt() / 4) return false;
    if (self.tracer) |tr| tr.note("compact", "deferred: the model has not read the newest tool results");
    return true;
}