Skip to content

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

Python
18.4 KB
Raw Blame
//! grok-build TaskCompleted / system-reminder for background bash (ADR 0010
//! follow-up). A finished job queues one notice. `deliver` injects a wake at
//! the next root step boundary; `takeWake` is the idle TUI auto-turn.

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

const agent_mod = @import("agent.zig");
const engine_sink = @import("engine_sink.zig");
const tool_pulse = @import("tool_pulse.zig");
const Agent = agent_mod.Agent;

/// Tail kept on the notice so an idle wake can continue without polling (#1154).
const output_cap: usize = 3072;

pub const Notice = struct {
    id: u64,
    exit_code: ?u8 = null,
    killed: bool = false,
    idle: bool = false, // the idle policy stopped it (#199): no auto-turn wake
    preview: [48]u8 = undefined,
    preview_len: u8 = 0,
    output: [output_cap]u8 = undefined,
    output_len: u16 = 0,
    output_truncated: bool = false,
};

/// ACP (and any other idle loop) sets this so a finished job wakes the
/// session immediately, not only on the next poll. Must not re-enter jobs
/// or this module: the pump may still hold the jobs mutex.
pub var on_queued: ?*const fn () void = null;

const cap: usize = 16;
var mu: Io.Mutex = .init;
var ring: [cap]Notice = undefined;
var count: usize = 0;
/// Legacy bounded dismiss-before-record credits (ADR 0061). The production
/// pump no longer relies on these: done + queue and consumption share the
/// jobs mutex, so eviction cannot resurrect a consumed completion (#728).
var dismissed: [cap]u64 = undefined;
var dismissed_len: usize = 0;

/// Unit fixtures must join their job pumps before clearing notification state.
pub fn resetForTest(io: Io) void {
    if (!@import("builtin").is_test) @compileError("test-only notification reset");
    mu.lockUncancelable(io);
    defer mu.unlock(io);
    count = 0;
    dismissed_len = 0;
}

fn clipCmd(cmd: []const u8) struct { buf: [48]u8, len: u8 } {
    const t = std.mem.trim(u8, cmd, " \t\r\n");
    const keep: u8 = @intCast(@min(t.len, 48));
    var buf: [48]u8 = @splat(0);
    @memcpy(buf[0..keep], t[0..keep]);
    return .{ .buf = buf, .len = keep };
}

/// One human/model line for a finished job.
pub fn line(buf: []u8, n: Notice) []const u8 {
    const cmd = n.preview[0..n.preview_len];
    if (n.idle) {
        return std.fmt.bufPrint(buf, "[job {d} stopped idle: {s}]", .{ n.id, cmd }) catch buf[0..0];
    }
    if (n.killed) {
        return std.fmt.bufPrint(buf, "[job {d} killed: {s}]", .{ n.id, cmd }) catch buf[0..0];
    }
    if (n.exit_code) |c| {
        return std.fmt.bufPrint(buf, "[job {d} exited {d}: {s}]", .{ n.id, c, cmd }) catch buf[0..0];
    }
    return std.fmt.bufPrint(buf, "[job {d} ended: {s}]", .{ n.id, cmd }) catch buf[0..0];
}

fn clipOutput(src: []const u8) struct { buf: [output_cap]u8, len: u16, truncated: bool } {
    var buf: [output_cap]u8 = undefined;
    if (src.len <= output_cap) {
        @memcpy(buf[0..src.len], src);
        return .{ .buf = buf, .len = @intCast(src.len), .truncated = false };
    }
    @memcpy(buf[0..output_cap], src[src.len - output_cap ..]);
    return .{ .buf = buf, .len = output_cap, .truncated = true };
}

fn wakeLine(buf: []u8, n: Notice) []const u8 {
    var head: [96]u8 = undefined;
    const h = line(&head, n);
    if (n.idle) return std.fmt.bufPrint(buf, "{s} — silent and unread past the idle stop; rerun it only if it is still needed.", .{h}) catch h;
    const out = n.output[0..n.output_len];
    const body: []const u8 = if (out.len == 0) "(no output)" else out;
    const note: []const u8 = if (n.output_truncated) "\n[older output omitted]" else "";
    return std.fmt.bufPrint(buf, "{s}\n{s}{s}\nContinue the task from this result. do not poll.", .{ h, body, note }) catch h;
}

/// Standalone notification convenience (tests). The job pump MUST split
/// queue (under jobs mutex) from publish (outside it); calling this after
/// exposing done reintroduces #728. Publication is UI, not a model wake.
pub fn record(io: Io, id: u64, exit_code: ?u8, killed: bool, cmd: []const u8, idle: bool) void {
    queue(io, id, exit_code, killed, cmd, idle, "");
    publish(io, id, exit_code, killed);
}

/// Exit codes of recently finished jobs, kept after their notice is read or
/// dismissed, so the PR check ledger can resolve a check that finished in the
/// background however its exit reached the model (#1326). Killed and
/// idle-stopped jobs record no code.
const Exit = struct { id: u64, code: ?u8 };
const exits_cap = 64;
var exits: [exits_cap]Exit = undefined;
var exits_len: usize = 0;
var exits_next: usize = 0;

fn noteExitLocked(id: u64, code: ?u8) void {
    exits[exits_next] = .{ .id = id, .code = code };
    exits_next = (exits_next + 1) % exits_cap;
    exits_len = @min(exits_len + 1, exits_cap);
}

/// The exit code of a recently finished job; null when unknown, killed, or
/// still running.
pub fn exitCode(io: Io, id: u64) ?u8 {
    mu.lockUncancelable(io);
    defer mu.unlock(io);
    for (exits[0..exits_len]) |e| if (e.id == id) return e.code;
    return null;
}

/// Queue while holding the jobs mutex, in the same critical section as done.
/// Consumers hold jobs -> notification mutex in that same order. Never call
/// a frontend here: it may re-enter jobOutput.
pub fn queue(io: Io, id: u64, exit_code: ?u8, killed: bool, cmd: []const u8, idle: bool, output: []const u8) void {
    const clipped = clipCmd(cmd);
    const tail = clipOutput(output);
    const n = Notice{
        .id = id,
        .exit_code = exit_code,
        .killed = killed,
        .idle = idle,
        .preview = clipped.buf,
        .preview_len = clipped.len,
        .output = tail.buf,
        .output_len = tail.len,
        .output_truncated = tail.truncated,
    };
    mu.lockUncancelable(io);
    noteExitLocked(id, if (killed or idle) null else exit_code);
    var queued = false;
    if (dismissedIndex(id)) |i| {
        std.mem.copyForwards(u64, dismissed[i .. dismissed_len - 1], dismissed[i + 1 .. dismissed_len]);
        dismissed_len -= 1;
    } else {
        if (count == cap) {
            std.mem.copyForwards(Notice, ring[0 .. cap - 1], ring[1..cap]);
            count = cap - 1;
        }
        ring[count] = n;
        count += 1;
        queued = true;
    }
    mu.unlock(io);
    if (queued) if (on_queued) |hook| hook();
}

/// Frontend-only publication AFTER releasing the jobs mutex. No wake is queued.
pub fn publish(io: Io, id: u64, exit_code: ?u8, killed: bool) void {
    if (engine_sink.hostedSink()) |sink| {
        sink.emit(io, .{ .job_completed = .{ .id = id, .exit_code = exit_code, .killed = killed } });
    }
}

/// Caller holds `mu`.
fn dismissedIndex(id: u64) ?usize {
    for (dismissed[0..dismissed_len], 0..) |d, i| if (d == id) return i;
    return null;
}

/// bash_output just handed the model this job's exit status and remaining
/// output (or bash_kill told it the job is dead), so the wake would only
/// repeat what it has read — and on an idle TUI that wake is a whole model
/// turn, which the model then spends on a `bash_output` snapshot that says
/// "(no new output)". Drop the queued notice; if the pump has not queued it
/// yet, remember the id so `record` skips it. ADR 0061.
pub fn dismiss(io: Io, id: u64) void {
    mu.lockUncancelable(io);
    defer mu.unlock(io);
    var i: usize = 0;
    var found = false;
    while (i < count) {
        if (ring[i].id != id) {
            i += 1;
            continue;
        }
        std.mem.copyForwards(Notice, ring[i .. count - 1], ring[i + 1 .. count]);
        count -= 1;
        found = true;
    }
    if (found or dismissedIndex(id) != null) return;
    if (dismissed_len == cap) {
        std.mem.copyForwards(u64, dismissed[0 .. cap - 1], dismissed[1..cap]);
        dismissed_len = cap - 1;
    }
    dismissed[dismissed_len] = id;
    dismissed_len += 1;
}

/// The tool result for a bash_output wait that ended before the job did.
/// An Esc used to be rendered by setting the elapsed counter to the 10-hour
/// deadline, so the model read "36000s elapsed" for a 36-second wait.
pub fn printRunning(w: *Io.Writer, id: u64, waited_ms: u64, interrupted: bool, persistent: bool) !void {
    var ebuf: [16]u8 = undefined;
    const el = tool_pulse.formatElapsed(&ebuf, waited_ms);
    if (persistent) {
        if (interrupted) {
            try w.print("[job {d}: running · {s} waited, then interrupted — persistent server; parked in the background. You are notified on exit; do not poll]", .{ id, el });
        } else {
            try w.print("[job {d}: running — persistent server; parked in the background. You are notified on exit; do not poll. action=output reads unread bytes]", .{id});
        }
        return;
    }
    if (interrupted) {
        try w.print("[job {d}: running · {s} waited, then interrupted — you are notified on exit; do not call bash_output again]", .{ id, el });
    } else {
        try w.print("[job {d}: running · {s} elapsed — you are notified on exit; do not call bash_output again]", .{ id, el });
    }
}

/// One dim chrome line per tool_pulse threshold while a blocking bash_output
/// wait runs long (#607). ADR 0010 keeps the wait single-hop; this only tells
/// the human it is alive. Presentation pulse: --json drops it, and a session
/// with no bound sink (subagents) stays quiet.
pub fn stillRunning(io: Io, id: u64, waited_ms: u64, unread: usize) void {
    var ebuf: [16]u8 = undefined;
    tool_pulse.emitNotice(io, "· bash_output · job {d} still running · {s} · {d} unread byte(s)", .{ id, tool_pulse.formatElapsed(&ebuf, waited_ms), unread });
}

/// A notice is queued for the next step boundary (run_idle.zig's wait).
pub fn pending(io: Io) bool {
    mu.lockUncancelable(io);
    defer mu.unlock(io);
    return count > 0;
}

/// Drain queued notices into `buf` (step boundary: everything). Null when
/// nothing finished.
pub fn takeWake(io: Io, buf: []u8) ?[]const u8 {
    return drain(io, buf, true);
}

/// The idle-TUI auto-turn: an exit or a kill wakes the model; an idle stop
/// does not — nobody was there for the whole idle budget, and a wake would
/// spend a turn telling nobody (ADR 0061). It waits in the ring for the next
/// real step boundary, where `deliver` hands it over.
pub fn takeIdleWake(io: Io, buf: []u8) ?[]const u8 {
    return drain(io, buf, false);
}

fn drain(io: Io, buf: []u8, idle_too: bool) ?[]const u8 {
    var ids: [cap]u64 = undefined;
    var n_ids: usize = 0;
    const text = drainLocked(io, buf, idle_too, &ids, &n_ids);
    // ADR 0218: these exits reached the model; a restart must not repeat them.
    for (ids[0..n_ids]) |id| @import("jobs.zig").markReported(io, id);
    return text;
}

fn drainLocked(io: Io, buf: []u8, idle_too: bool, ids: *[cap]u64, n_ids: *usize) ?[]const u8 {
    mu.lockUncancelable(io);
    defer mu.unlock(io);
    if (count == 0) return null;
    var used: usize = 0;
    var keep: usize = 0; // notices left in the ring, compacted in order
    var i: usize = 0;
    while (i < count) : (i += 1) {
        if (!idle_too and ring[i].idle) {
            ring[keep] = ring[i];
            keep += 1;
            continue;
        }
        var one: [4096]u8 = undefined;
        const w = wakeLine(&one, ring[i]);
        if (used > 0) {
            if (used + 1 >= buf.len) break;
            buf[used] = '\n';
            used += 1;
        }
        const n = @min(w.len, buf.len - used);
        @memcpy(buf[used .. used + n], w[0..n]);
        used += n;
        ids[n_ids.*] = ring[i].id;
        n_ids.* += 1;
    }
    while (i < count) : (i += 1) { // what did not fit stays for next time
        ring[keep] = ring[i];
        keep += 1;
    }
    count = keep;
    if (used == 0) return null;
    return buf[0..used];
}

/// Root step-boundary inject (same moment as peer deliverInbound).
pub fn deliver(root: *Agent) void {
    if (root.sub) return;
    @import("subagent_interactive.zig").deliver(root);
    // A parked shell is about to end this turn without another model call.
    // Leave the notice for the idle auto-turn so the result is not swallowed (#1154).
    if (@import("subagent_interactive.zig").yieldPending()) return;
    var buf: [4096]u8 = undefined;
    const text = takeWake(root.io, &buf) orelse return;
    @import("session_wake.zig").inject(root, text);
}

test "line names exit, kill, and abnormal end" {
    const clipped = clipCmd("sleep 5");
    var n = Notice{ .id = 3, .exit_code = 0, .preview = clipped.buf, .preview_len = clipped.len };
    var buf: [80]u8 = undefined;
    try std.testing.expectEqualStrings("[job 3 exited 0: sleep 5]", line(&buf, n));
    n.killed = true;
    try std.testing.expectEqualStrings("[job 3 killed: sleep 5]", line(&buf, n));
    n.killed = false;
    n.exit_code = null;
    try std.testing.expectEqualStrings("[job 3 ended: sleep 5]", line(&buf, n));
}

test "dismiss drops a queued notice, or the one the pump has not queued yet (ADR 0061)" {
    const io = std.testing.io;
    count = 0;
    dismissed_len = 0;
    var buf: [256]u8 = undefined;
    // Queued, then read through bash_output: no wake.
    record(io, 7, 0, false, "sleep 1", false);
    dismiss(io, 7);
    try std.testing.expect(takeWake(io, &buf) == null);
    // Read through bash_output BEFORE the pump queued it: still no wake, and
    // the remembered id is spent by that one record.
    dismiss(io, 8);
    dismiss(io, 8); // a second read of the same finished job is not a second credit
    record(io, 8, 1, false, "false", false);
    try std.testing.expect(takeWake(io, &buf) == null);
    try std.testing.expectEqual(@as(usize, 0), dismissed_len);
    record(io, 8, 1, false, "false", false);
    try std.testing.expect(std.mem.indexOf(u8, takeWake(io, &buf) orelse "", "[job 8 exited 1: false]") != null);
    // Only the dismissed id is dropped; a neighbour in the ring survives.
    record(io, 9, 0, false, "a", false);
    record(io, 10, 0, false, "b", false);
    record(io, 11, 0, false, "c", false);
    dismiss(io, 10);
    const text = takeWake(io, &buf) orelse return error.Empty;
    try std.testing.expect(std.mem.indexOf(u8, text, "[job 9 exited 0: a]") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "job 10") == null);
    try std.testing.expect(std.mem.indexOf(u8, text, "[job 11 exited 0: c]") != null);
}

test "printRunning reports the wait that happened, not the deadline (ADR 0061)" {
    var aw: Io.Writer.Allocating = .init(std.testing.allocator);
    defer aw.deinit();
    try printRunning(&aw.writer, 181, 36_000, true, false);
    try std.testing.expectEqualStrings("[job 181: running · 36s waited, then interrupted — you are notified on exit; do not call bash_output again]", aw.written());
    aw.clearRetainingCapacity();
    try printRunning(&aw.writer, 5, 125_000, false, false);
    try std.testing.expectEqualStrings("[job 5: running · 2m05s elapsed — you are notified on exit; do not call bash_output again]", aw.written());
}

test "printRunning parks a persistent server instead of inviting a wait_ms poll (ADR 0152)" {
    var aw: Io.Writer.Allocating = .init(std.testing.allocator);
    defer aw.deinit();
    try printRunning(&aw.writer, 446, 180_000, false, true);
    try std.testing.expectEqualStrings("[job 446: running — persistent server; parked in the background. You are notified on exit; do not poll. action=output reads unread bytes]", aw.written());
    try std.testing.expect(std.mem.indexOf(u8, aw.written(), "omit wait_ms") == null);
    aw.clearRetainingCapacity();
    try printRunning(&aw.writer, 446, 15_000, true, true);
    try std.testing.expectEqualStrings("[job 446: running · 15s waited, then interrupted — persistent server; parked in the background. You are notified on exit; do not poll]", aw.written());
}

test "#1154: idle wake carries exit status and output, and a pending yield does not swallow it" {
    const io = std.testing.io;
    count = 0;
    dismissed_len = 0;
    const interactive = @import("subagent_interactive.zig");
    interactive.configure(true);
    defer interactive.configure(false);
    interactive.armYield();
    queue(io, 12, 0, false, "zig build test", false, "All 2 tests passed.");
    var agent: Agent = undefined;
    agent.sub = false;
    agent.io = io;
    agent.session_name = "";
    deliver(&agent); // yield is armed: the notice stays queued
    var buf: [4096]u8 = undefined;
    const text = takeIdleWake(io, &buf) orelse return error.Empty;
    try std.testing.expect(std.mem.indexOf(u8, text, "[job 12 exited 0: zig build test]") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "All 2 tests passed.") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "do not poll") != null);
    try std.testing.expect(takeIdleWake(io, &buf) == null);

    var big: [output_cap + 32]u8 = undefined;
    @memset(&big, 'x');
    @memcpy(big[big.len - 8 ..], "TAIL-END");
    queue(io, 13, 1, false, "make", false, &big);
    const tail = takeWake(io, &buf) orelse return error.Empty;
    try std.testing.expect(std.mem.indexOf(u8, tail, "TAIL-END") != null);
    try std.testing.expect(std.mem.indexOf(u8, tail, "[older output omitted]") != null);
    try std.testing.expect(std.mem.indexOf(u8, tail, "[job 13 exited 1: make]") != null);
}

test "takeWake drains and formats the grok-build do-not-poll reminder" {
    const io = std.testing.io;
    count = 0;
    dismissed_len = 0;
    record(io, 1, 0, false, "true", false);
    record(io, 2, 1, false, "false", false);
    var buf: [256]u8 = undefined;
    const text = takeWake(io, &buf) orelse return error.Empty;
    try std.testing.expect(std.mem.indexOf(u8, text, "[job 1 exited 0: true]") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "do not poll") != null);
    try std.testing.expect(std.mem.indexOf(u8, text, "[job 2 exited 1: false]") != null);
    try std.testing.expect(takeWake(io, &buf) == null);
}

test "#199: an idle stop is a step-boundary notice, not an auto-turn wake" {
    const io = std.testing.io;
    count = 0;
    dismissed_len = 0;
    var buf: [512]u8 = undefined;
    record(io, 3, null, true, "npm run dev", true);
    try std.testing.expect(takeIdleWake(io, &buf) == null); // the idle TUI stays idle
    record(io, 4, 0, false, "make", false);
    const idle_text = takeIdleWake(io, &buf) orelse return error.Empty;
    try std.testing.expect(std.mem.indexOf(u8, idle_text, "[job 4 exited 0: make]") != null);
    try std.testing.expect(std.mem.indexOf(u8, idle_text, "job 3") == null); // still queued
    const step_text = takeWake(io, &buf) orelse return error.Empty;
    try std.testing.expect(std.mem.indexOf(u8, step_text, "[job 3 stopped idle: npm run dev]") != null);
    try std.testing.expect(std.mem.indexOf(u8, step_text, "rerun it only if it is still needed") != null);
    try std.testing.expect(takeWake(io, &buf) == null);
}