graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! 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);
}