Skip to content

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

Python
15.5 KB
Raw Blame
//! Run until idle. A root reply that would end the run while work it started
//! in the background is still running does not end it: the run waits for that
//! work to report, then continues with the result. Only a reply with nothing
//! running ends the run.
//!
//! Headless surfaces only: `-p`, and the non-interactive mainloop behind
//! `--json`, `graff serve` and piped stdin. Nothing else wakes those sessions
//! again, so a background build's exit notice used to die with the process.
//! The TUI, the line REPL and ACP start a new turn when background work
//! reports (idle_wake_sources.zig), so they end the turn instead.
//!
//! Live work is a running shell job that will post an exit notice, and a
//! background subagent the root started. A server never reports, so a job
//! that is persistent, pinned, detached or listening on a TCP port does not
//! count. While waiting, a heartbeat wakes the model after `heartbeat_ms`
//! without news so it can check on work that may be stuck; after
//! `max_quiet_beats` heartbeats in a row with no result and no tool call, the
//! run stops waiting.

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;

const Agent = @import("agent.zig").Agent;
const jobs = @import("jobs.zig");
const subagent = @import("subagent.zig");
const job_notify = @import("job_notify.zig");
const session_wake = @import("session_wake.zig");
const tool_pulse = @import("tool_pulse.zig");
const util = @import("util.zig");

/// Set by the headless entry points (session_run.runOneshotPrompt, mainloop.run).
pub var enabled: bool = false;

/// Silence before a heartbeat. GRAFF_HEARTBEAT_SECS overrides; 0 turns it off.
pub var heartbeat_ms: u64 = 10 * std.time.ms_per_min;

/// Heartbeats in a row with no result and no tool call before the run stops
/// waiting: the model has looked that many times and only chose to wait.
const max_quiet_beats: u8 = 3;
const poll_ms = 200;
/// A finished subagent's report rides its wake up to this size.
const report_cap: usize = 6 * 1024;

/// Seconds; unparseable values are ignored, 0 disables, a week is the cap.
pub fn applyEnv(environ_map: anytype) void {
    const v = environ_map.get("GRAFF_HEARTBEAT_SECS") orelse return;
    const secs = std.fmt.parseInt(u64, std.mem.trim(u8, v, " \t"), 10) catch return;
    heartbeat_ms = @min(secs, 7 * 24 * 3600) * std.time.ms_per_s;
}

/// The run's state across the waits of one root turn.
pub const Hold = struct {
    quiet_beats: u8 = 0,
    calls_at_beat: u64 = 0,

    /// Where a final reply would end the root turn. True continues the turn:
    /// a result or a heartbeat is queued for the next request.
    pub fn wait(self: *Hold, agent: *Agent) !bool {
        if (!enabled or agent.sub or agent.review_mode or agent.text_only or agent.completed != null) return false;
        const io = agent.io;
        if (agent.tool_calls_this_turn != self.calls_at_beat) self.quiet_beats = 0; // it acted since the last beat
        var scratch = std.heap.ArenaAllocator.init(agent.gpa);
        defer scratch.deinit();
        const a = scratch.allocator();
        const work = try Work.snapshot(agent.gpa, io, a);
        var since: ?i64 = null;
        while (true) {
            if (Agent.esc_cancel.load(.acquire)) return error.Interrupted;
            // The client sent its next request: the turn ends and that request
            // runs; its first step boundary delivers whatever has reported.
            if (@import("json_inbox.zig").waiting()) return false;
            // Read before the notices: work that ends after this read is caught
            // on the next pass, and work that ended before it already queued its
            // notice (done and the notice share the jobs lock).
            const live = work.live(io);
            if (job_notify.pending(io) or try deliver(agent)) {
                self.quiet_beats = 0;
                return true;
            }
            if (!live) return false;
            const now = util.unixMs(io);
            const started = since orelse blk: {
                if (self.quiet_beats >= max_quiet_beats) {
                    try agent.say("[stopped waiting: background work is still running after {d} heartbeats with no news]\n", .{max_quiet_beats});
                    if (agent.tracer) |t| t.note("run_idle", "quiet cap");
                    return false;
                }
                try agent.say("[waiting for background work to report: {s}]\n", .{try work.describe(io, a)});
                if (agent.tracer) |t| t.note("run_idle", "waiting");
                since = now;
                break :blk now;
            };
            if (heartbeat_ms > 0 and now - started >= @as(i64, @intCast(heartbeat_ms))) {
                self.quiet_beats += 1;
                self.calls_at_beat = agent.tool_calls_this_turn;
                session_wake.inject(agent, try heartbeatText(a, @intCast(now - started), try work.describe(io, a)));
                if (agent.tracer) |t| t.note("run_idle", "heartbeat");
                return true;
            }
            io.sleep(.fromMilliseconds(poll_ms), .awake) catch return false;
        }
    }
};

/// Step boundary (turn_inbox) and the wait: a finished background subagent
/// the root started wakes the run with its report. Interactive roots own
/// their children and get subagent_interactive's wake instead.
pub fn deliver(agent: *Agent) !bool {
    if (!enabled or agent.sub) return false;
    var texts: std.ArrayList([]u8) = .empty;
    defer {
        for (texts.items) |t| agent.gpa.free(t);
        texts.deinit(agent.gpa);
    }
    try takeReports(agent.gpa, agent.io, &texts);
    for (texts.items) |t| session_wake.inject(agent, t);
    return texts.items.len > 0;
}

/// Unread reports of finished root children, marked read. `agent_output`
/// still returns a report in full after this.
fn takeReports(gpa: Allocator, io: Io, texts: *std.ArrayList([]u8)) !void {
    const reg = &subagent.g_agent_jobs;
    reg.mutex.lockUncancelable(io);
    defer reg.mutex.unlock(io);
    for (reg.list.items) |job| {
        if (!rootChild(job) or !job.done or job.notified) continue;
        const status = try subagent.agentStatusText(gpa, job.id, true, job.is_error, job.usage, job.result);
        defer gpa.free(status);
        try texts.ensureUnusedCapacity(gpa, 1);
        texts.appendAssumeCapacity(try reportWake(gpa, job.id, status));
        job.notified = true;
    }
}

fn reportWake(gpa: Allocator, id: u32, status: []const u8) ![]u8 {
    if (status.len <= report_cap)
        return std.fmt.allocPrint(gpa, "{s}\nContinue the task from this result.", .{status});
    return std.fmt.allocPrint(gpa, "{s}\n[report cut at {d} bytes; agent_output id {d} returns all of it]\nContinue the task from this result.", .{ util.utf8Prefix(status, report_cap), report_cap, id });
}

/// A background child of a headless root: interactive roots set `owner`,
/// and a child's own children belong to it.
fn rootChild(job: *const subagent.AgentJob) bool {
    return job.owner == null and !job.ctx.from_sub;
}

fn heartbeatText(a: Allocator, silent_ms: u64, running: []const u8) ![]const u8 {
    var ebuf: [16]u8 = undefined;
    return std.fmt.allocPrint(a, "[heartbeat: no news from background work for {s}. Still running: {s}. Check on anything that may be stuck (action=output or agent_output for a snapshot, action=kill to stop a job), or end your reply to keep waiting.]", .{ tool_pulse.formatElapsed(&ebuf, silent_ms), running });
}

/// The background work a run waits on, captured when it starts waiting.
const Work = struct {
    jobs: std.ArrayList(JobRef) = .empty,
    agents: std.ArrayList(AgentRef) = .empty,

    const JobRef = struct { id: u64, cmd: []const u8, started_ms: i64 };
    const AgentRef = struct { id: u32, label: []const u8 };

    fn snapshot(gpa: Allocator, io: Io, a: Allocator) !Work {
        var w: Work = .{};
        var candidates: std.ArrayList(struct { ref: JobRef, pid: i32 }) = .empty;
        {
            const reg = &jobs.g_jobs;
            reg.mutex.lockUncancelable(io);
            defer reg.mutex.unlock(io);
            for (reg.list.items) |job| {
                // quiet: still in its foreground wait, the tool call is live.
                if (job.done or job.quiet or job.persistent or job.pinned or job.detach) continue;
                try candidates.append(a, .{ .ref = .{ .id = job.id, .cmd = try a.dupe(u8, job.cmd), .started_ms = job.started_ms }, .pid = job.group_pid });
            }
        }
        // lsof runs outside the lock. A listening process group is a server.
        for (candidates.items) |c| {
            if (c.pid != 0 and @import("job_registry.zig").listenPorts(gpa, io, a, c.pid).len > 0) continue;
            try w.jobs.append(a, c.ref);
        }
        const reg = &subagent.g_agent_jobs;
        reg.mutex.lockUncancelable(io);
        defer reg.mutex.unlock(io);
        for (reg.list.items) |job| {
            if (rootChild(job) and !job.done) try w.agents.append(a, .{ .id = job.id, .label = try a.dupe(u8, job.label) });
        }
        return w;
    }

    fn live(w: Work, io: Io) bool {
        {
            const reg = &jobs.g_jobs;
            reg.mutex.lockUncancelable(io);
            defer reg.mutex.unlock(io);
            for (w.jobs.items) |ref| {
                for (reg.list.items) |job| if (job.id == ref.id and !job.done) return true;
            }
        }
        const reg = &subagent.g_agent_jobs;
        reg.mutex.lockUncancelable(io);
        defer reg.mutex.unlock(io);
        for (w.agents.items) |ref| if (reg.find(ref.id)) |job| if (!job.done) return true;
        return false;
    }

    /// `job 3 (zig build test, 12m)` style, for the waiting line and the heartbeat.
    fn describe(w: Work, io: Io, a: Allocator) ![]const u8 {
        var aw: Io.Writer.Allocating = .init(a);
        const now = util.unixMs(io);
        for (w.jobs.items, 0..) |ref, i| {
            var ebuf: [16]u8 = undefined;
            const age: u64 = @intCast(@max(0, now - ref.started_ms));
            try aw.writer.print("{s}job {d} ({s}, {s})", .{ if (i == 0) "" else ", ", ref.id, util.utf8Prefix(ref.cmd, 48), tool_pulse.formatElapsed(&ebuf, age) });
        }
        for (w.agents.items, 0..) |ref, i| {
            try aw.writer.print("{s}agent {d} ({s})", .{ if (i == 0 and w.jobs.items.len == 0) "" else ", ", ref.id, util.utf8Prefix(ref.label, 48) });
        }
        return aw.written();
    }
};

test "GRAFF_HEARTBEAT_SECS: seconds, 0 turns it off, junk is ignored" {
    const saved = heartbeat_ms;
    defer heartbeat_ms = saved;
    const Env = struct {
        v: ?[]const u8,
        pub fn get(self: @This(), name: []const u8) ?[]const u8 {
            return if (std.mem.eql(u8, name, "GRAFF_HEARTBEAT_SECS")) self.v else null;
        }
    };
    applyEnv(Env{ .v = "90" });
    try std.testing.expectEqual(@as(u64, 90_000), heartbeat_ms);
    applyEnv(Env{ .v = "junk" });
    try std.testing.expectEqual(@as(u64, 90_000), heartbeat_ms);
    applyEnv(Env{ .v = "0" });
    try std.testing.expectEqual(@as(u64, 0), heartbeat_ms);
}

test "a running background job is live work until it ends, and then its notice is queued" {
    if (@import("builtin").os.tag == .windows) return error.SkipZigTest;
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    jobs.g_jobs = .{};
    defer jobs.jobsReap(gpa, io);
    var buf: [4096]u8 = undefined;
    while (job_notify.takeWake(io, &buf) != null) {}
    var scratch = std.heap.ArenaAllocator.init(gpa);
    defer scratch.deinit();
    const id = (try jobs.spawnJob(gpa, io, "sleep 0.3; echo run-idle-done")).id;
    const work = try Work.snapshot(gpa, io, scratch.allocator());
    try std.testing.expectEqual(@as(usize, 1), work.jobs.items.len);
    try std.testing.expect(work.live(io));
    const line = try work.describe(io, scratch.allocator());
    try std.testing.expect(std.mem.indexOf(u8, line, "sleep 0.3") != null);
    var waited: u32 = 0;
    while (work.live(io) and waited < 100) : (waited += 1) io.sleep(.fromMilliseconds(50), .awake) catch {};
    try std.testing.expect(!work.live(io));
    try std.testing.expect(job_notify.pending(io));
    const wake = job_notify.takeWake(io, &buf).?;
    try std.testing.expect(std.mem.indexOf(u8, wake, "run-idle-done") != null);
    _ = id;
}

test "only the root's own background children are waited on and reported" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    const saved = subagent.g_agent_jobs;
    subagent.g_agent_jobs = .{};
    defer {
        subagent.g_agent_jobs.list.deinit(gpa);
        subagent.g_agent_jobs = saved;
    }
    var label = "review parser".*;
    const ctx: @import("tools.zig").ToolCtx = .{ .gpa = gpa, .io = io, .client = undefined, .provider = undefined, .registry = null, .from_sub = false, .approvals = null, .tracer = null };
    var mine: subagent.AgentJob = .{ .id = 1, .label = &label, .prompt = &label, .niche = &label, .isolation = .shared_cwd, .isolation_fallback = false, .ctx = ctx };
    var nested_ctx = ctx;
    nested_ctx.from_sub = true;
    var nested: subagent.AgentJob = .{ .id = 2, .label = &label, .prompt = &label, .niche = &label, .isolation = .shared_cwd, .isolation_fallback = false, .ctx = nested_ctx };
    var owned: subagent.AgentJob = .{ .id = 3, .label = &label, .prompt = &label, .niche = &label, .isolation = .shared_cwd, .isolation_fallback = false, .ctx = ctx, .owner = "tui-session" };
    try subagent.g_agent_jobs.list.appendSlice(gpa, &.{ &mine, &nested, &owned });

    var scratch = std.heap.ArenaAllocator.init(gpa);
    defer scratch.deinit();
    const work = try Work.snapshot(gpa, io, scratch.allocator());
    try std.testing.expectEqual(@as(usize, 1), work.agents.items.len);
    try std.testing.expectEqual(@as(u32, 1), work.agents.items[0].id);
    try std.testing.expect(work.live(io));

    var result = "PARSER_OK".*;
    for ([_]*subagent.AgentJob{ &mine, &nested, &owned }) |job| {
        job.done = true;
        job.result = &result;
    }
    try std.testing.expect(!work.live(io));
    var texts: std.ArrayList([]u8) = .empty;
    defer {
        for (texts.items) |t| gpa.free(t);
        texts.deinit(gpa);
    }
    try takeReports(gpa, io, &texts);
    try std.testing.expectEqual(@as(usize, 1), texts.items.len);
    try std.testing.expect(std.mem.indexOf(u8, texts.items[0], "[agent 1: completed") != null);
    try std.testing.expect(std.mem.indexOf(u8, texts.items[0], "PARSER_OK") != null);
    try std.testing.expect(mine.notified and !nested.notified and !owned.notified);
    for (texts.items) |t| gpa.free(t);
    texts.clearRetainingCapacity();
    try takeReports(gpa, io, &texts); // read once
    try std.testing.expectEqual(@as(usize, 0), texts.items.len);
}

test "a long report is cut at the cap and points at agent_output" {
    const gpa = std.testing.allocator;
    const long = try gpa.alloc(u8, report_cap + 100);
    defer gpa.free(long);
    @memset(long, 'x');
    const text = try reportWake(gpa, 9, long);
    defer gpa.free(text);
    try std.testing.expect(std.mem.indexOf(u8, text, "agent_output id 9 returns all of it") != null);
    try std.testing.expect(text.len < report_cap + 200);
}

test "the heartbeat names the silence, the work and both ways forward" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const text = try heartbeatText(arena.allocator(), 10 * std.time.ms_per_min, "job 3 (zig build test, 12m)");
    try std.testing.expect(std.mem.indexOf(u8, text, "10m") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "job 3 (zig build test, 12m)") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "action=kill") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "keep waiting") != null);
}