graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Subagent activity on ACP. By default (mode `progress`) a child's work is
//! shown as standard `tool_call_update`s on its parent's tool call
//! (acp_subagent_progress.zig). The draft child-session stream (mode `draft`)
//! is used only when the client negotiated `subagents` and graff runs with
//! GRAFF_ACP_DRAFT_SUBAGENTS=1. Either way a child is exposed only while its
//! parent prompt is active.
const std = @import("std");
const Io = std.Io;
const main = @import("main.zig");
const sink = @import("engine_sink.zig");
const stream = @import("acp_stream.zig");
const proto = @import("acp_protocol.zig");
const util = @import("util.zig");
const progress = @import("acp_subagent_progress.zig");
pub const Mode = enum { draft, progress };
pub const State = struct {
out: *Io.Writer,
parent: []const u8,
output_lock: *Io.Mutex,
mode: Mode = .draft,
};
var active: ?*State = null;
/// Connection-owned extension state. Unlike `active`, this survives parent
/// prompt boundaries so detached workers can keep reporting their progress.
pub const BackgroundState = struct {
out: *Io.Writer,
output_lock: *Io.Mutex,
parent: []const u8 = "",
enabled: bool = false,
generation: u64 = 0,
};
var background: ?*BackgroundState = null;
var next_background_generation: u64 = 0;
/// Owned by the detached child, rather than the mutable ACP dispatch session.
pub const BackgroundHandle = struct {
parent: []const u8,
generation: u64,
parent_call_id: []const u8,
};
pub fn installBackground(io: Io, state: *BackgroundState) void {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
next_background_generation +%= 1;
state.generation = next_background_generation;
background = state;
}
/// Detach before the ACP transport is destroyed. Child jobs can still finish
/// during the parent process's final reap, but must not write to a dead pipe.
pub fn uninstallBackground(io: Io) void {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
background = null;
}
pub fn configureBackground(io: Io, parent: []const u8, enabled: bool) void {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
const state = background orelse return;
state.parent = parent;
state.enabled = enabled;
}
fn backgroundSendLocked(io: Io, handle: BackgroundHandle, id: []const u8, seq: u64, event: anytype) bool {
const state = background orelse return false;
if (state.generation != handle.generation) return false;
state.output_lock.lockUncancelable(io);
defer state.output_lock.unlock(io);
proto.writeNotification(state.out, "graff/subagent_event", .{
.parentSessionId = handle.parent,
.subagentSessionId = id,
.parentToolCallId = handle.parent_call_id,
.seq = seq,
.event = event,
}) catch return false;
state.out.flush() catch {};
return true;
}
fn backgroundSend(io: Io, handle: BackgroundHandle, id: []const u8, seq: u64, event: anytype) bool {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
return backgroundSendLocked(io, handle, id, seq, event);
}
pub fn announceBackground(a: std.mem.Allocator, io: Io, id: []const u8, name: []const u8, task: []const u8, parent_call_id: []const u8, provider: []const u8, model: []const u8) ?BackgroundHandle {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
const state = background orelse return null;
if (!state.enabled or state.parent.len == 0) return null;
const handle: BackgroundHandle = .{
.parent = a.dupe(u8, state.parent) catch return null,
.generation = state.generation,
.parent_call_id = parent_call_id,
};
var title: [768]u8 = undefined;
if (!backgroundSendLocked(io, handle, id, 0, .{
.type = "spawn",
.name = progress.displayName(&title, name, model),
.task = util.utf8Prefix(task, 2048),
.provider = provider,
.model = model,
})) return null;
return handle;
}
pub fn finishBackground(io: Io, handle: BackgroundHandle, id: []const u8, seq: u64, outcome: []const u8) void {
_ = backgroundSend(io, handle, id, seq, .{ .type = "terminal", .state = outcome });
}
pub fn eligible(kind: []const u8, depth: u8, detached: bool) bool {
return depth == 0 and !detached and std.mem.eql(u8, kind, "subagent");
}
pub fn install(io: Io, state: *State) void {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
active = state;
}
pub fn uninstall(io: Io) void {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
active = null;
}
pub fn announce(io: Io, id: []const u8, name: []const u8, task: []const u8, parent_call_id: []const u8, provider: []const u8, model: []const u8) bool {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
const state = active orelse return false;
if (state.mode != .draft) return false;
state.output_lock.lockUncancelable(io);
defer state.output_lock.unlock(io);
var title: [768]u8 = undefined;
proto.writeNotification(state.out, "session/update", .{ .sessionId = state.parent, .update = .{
.sessionUpdate = "subagent_update",
.subagentSessionId = id,
.name = progress.displayName(&title, name, model),
.task = util.utf8Prefix(task, 2048),
._meta = .{ .@"graff/parentToolCallId" = parent_call_id, .@"graff/subagent" = .{ .name = name, .provider = provider, .model = model } },
} }) catch return false;
state.out.flush() catch {};
return true;
}
/// Whether this child should stream standard progress onto its parent's tool
/// call: a top-level `subagent` with a known parent call, in a prompt whose
/// client did not choose the draft child-session stream.
pub fn progressFor(io: Io, kind: []const u8, depth: u8, parent_call_id: []const u8) bool {
if (depth != 0 or parent_call_id.len == 0 or !std.mem.eql(u8, kind, "subagent")) return false;
if (!progress.enabled()) return false;
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
const state = active orelse return false;
return state.mode == .progress;
}
pub fn finish(io: Io, id: []const u8, outcome: []const u8, parent_call_id: []const u8) void {
main.g_gui_mu.lockUncancelable(io);
defer main.g_gui_mu.unlock(io);
const state = active orelse return;
state.output_lock.lockUncancelable(io);
defer state.output_lock.unlock(io);
proto.writeNotification(state.out, "session/update", .{ .sessionId = state.parent, .update = .{
.sessionUpdate = "subagent_update",
.subagentSessionId = id,
.state = outcome,
._meta = .{ .@"graff/parentToolCallId" = parent_call_id },
} }) catch return;
state.out.flush() catch {};
}
/// Fan out the child's semantic events to its own ACP session, retaining the
/// existing recorder sink for graff/agents inspection and terminal frontends.
pub const ChildSink = struct {
id: []const u8,
io: Io,
recorder: ?sink.EngineSink = null,
background_handle: ?BackgroundHandle = null,
seq: u64 = 1,
progress: ?progress.Progress = null,
pub fn engineSink(self: *ChildSink) sink.EngineSink {
return .{ .ctx = self, .vt = &vtable };
}
const vtable: sink.VTable = .{ .emit = emit, .durable = false };
fn emit(ctx: *anyopaque, stamped: sink.Stamped) void {
const self: *ChildSink = @ptrCast(@alignCast(ctx));
if (self.recorder) |record| record.vt.emit(record.ctx, stamped);
if (self.background_handle) |handle| {
self.emitBackground(stamped, handle);
return;
}
if (self.progress != null) {
self.emitProgress(stamped);
return;
}
main.g_gui_mu.lockUncancelable(self.io);
defer main.g_gui_mu.unlock(self.io);
const state = active orelse return;
state.output_lock.lockUncancelable(self.io);
defer state.output_lock.unlock(self.io);
const w = state.out;
switch (stamped.event) {
.reasoning_delta => |v| stream.writeThought(w, self.id, v.text) catch return,
.text_delta => |v| stream.writeMessage(w, self.id, v.text) catch return,
.tool_call_announced => |v| {
if (v.ask_user or std.mem.eql(u8, v.name, "attempt_completion")) return;
stream.writeToolCall(w, self.id, v.id, v.name, v.input) catch return;
},
.tool_result => |v| {
if (v.ask_user or std.mem.eql(u8, v.name, "attempt_completion")) return;
stream.writeToolDone(w, self.id, v.id, v.is_error or v.cancelled, v.text, v.run_task) catch return;
},
.tool_rejected => |v| stream.writeToolDone(w, self.id, v.id, true, v.message, null) catch return,
else => return,
}
w.flush() catch {};
}
fn emitProgress(self: *ChildSink, stamped: sink.Stamped) void {
const p = &self.progress.?;
const tool_event = switch (stamped.event) {
.text_delta => |v| blk: {
p.addText(v.text);
break :blk false;
},
.tool_call_announced => |v| blk: {
if (v.ask_user or std.mem.eql(u8, v.name, "attempt_completion")) return;
p.toolLine(v.name, v.input);
break :blk true;
},
.tool_result => |v| blk: {
if (!(v.is_error or v.cancelled)) return;
var b: [progress.line_max]u8 = undefined;
p.addLine(std.fmt.bufPrint(&b, "✗ {s} failed", .{v.name}) catch "✗ failed");
break :blk true;
},
.tool_rejected => blk: {
p.addLine("✗ tool call rejected");
break :blk true;
},
else => return,
};
if (!p.due(util.unixMs(self.io), tool_event)) return;
self.publishProgress("running");
}
fn publishProgress(self: *ChildSink, state_label: []const u8) void {
const p = &(self.progress orelse return);
main.g_gui_mu.lockUncancelable(self.io);
defer main.g_gui_mu.unlock(self.io);
const state = active orelse return;
state.output_lock.lockUncancelable(self.io);
defer state.output_lock.unlock(self.io);
progress.write(state.out, state.parent, p, state_label) catch return;
state.out.flush() catch {};
}
/// Publish identity before the first text/tool event (reasoning can take time).
pub fn startProgress(self: *ChildSink) void {
self.publishProgress("running");
}
/// The child's last word on its parent's tool call. The parent's own tool
/// result, when it has one, follows and replaces this.
pub fn finishProgress(self: *ChildSink, outcome: []const u8) void {
const p = &(self.progress orelse return);
p.addLine(if (std.mem.eql(u8, outcome, "completed")) "✓ finished" else if (std.mem.eql(u8, outcome, "cancelled")) "■ cancelled" else "✗ failed");
self.publishProgress(outcome);
}
fn emitBackground(self: *ChildSink, stamped: sink.Stamped, handle: BackgroundHandle) void {
var arena_state = std.heap.ArenaAllocator.init(std.heap.page_allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
var bytes: Io.Writer.Allocating = .init(a);
defer bytes.deinit();
const w = &bytes.writer;
switch (stamped.event) {
.reasoning_delta => |v| stream.writeThought(w, self.id, v.text) catch return,
.text_delta => |v| stream.writeMessage(w, self.id, v.text) catch return,
.tool_call_announced => |v| {
if (v.ask_user or std.mem.eql(u8, v.name, "attempt_completion")) return;
stream.writeToolCall(w, self.id, v.id, v.name, v.input) catch return;
},
.tool_result => |v| {
if (v.ask_user or std.mem.eql(u8, v.name, "attempt_completion")) return;
stream.writeToolDone(w, self.id, v.id, v.is_error or v.cancelled, v.text, v.run_task) catch return;
},
.tool_rejected => |v| stream.writeToolDone(w, self.id, v.id, true, v.message, null) catch return,
else => return,
}
const parsed = std.json.parseFromSliceLeaky(std.json.Value, a, w.buffered(), .{}) catch return;
const params = parsed.object.get("params") orelse return;
if (params != .object) return;
const update = params.object.get("update") orelse return;
if (backgroundSend(self.io, handle, self.id, self.seq, .{ .type = "update", .update = update }))
self.seq += 1;
}
};
test "negotiated child stream announces before activity and terminates on parent" {
var buffer: [8192]u8 = undefined;
var out: Io.Writer = .fixed(&buffer);
const io = std.testing.io;
var output_lock: Io.Mutex = .init;
var state: State = .{ .out = &out, .parent = "parent", .output_lock = &output_lock };
install(io, &state);
defer uninstall(io);
try std.testing.expect(announce(io, "child", "Scout", "Inspect the code", "spawn-1", "fixture", "reader-model"));
var child: ChildSink = .{ .id = "child", .io = io };
const emit_sink = child.engineSink();
emit_sink.emit(io, .{ .reasoning_delta = .{ .text = "I will inspect it" } });
emit_sink.emit(io, .{ .tool_call_announced = .{ .id = "read-1", .name = "read_file", .input = .null } });
emit_sink.emit(io, .{ .tool_result = .{ .id = "read-1", .name = "read_file", .text = "contents", .is_error = false } });
emit_sink.emit(io, .{ .text_delta = .{ .text = "Found the cause" } });
finish(io, "child", "completed", "spawn-1");
const wire = out.buffered();
const announced = std.mem.indexOf(u8, wire, "\"subagentSessionId\":\"child\"") orelse return error.MissingAnnouncement;
const thought = std.mem.indexOf(u8, wire, "agent_thought_chunk") orelse return error.MissingThought;
const call = std.mem.indexOf(u8, wire, "\"toolCallId\":\"read-1\"") orelse return error.MissingTool;
const answer = std.mem.indexOf(u8, wire, "Found the cause") orelse return error.MissingAnswer;
const terminal = std.mem.indexOf(u8, wire, "\"state\":\"completed\"") orelse return error.MissingTerminal;
try std.testing.expect(announced < thought and thought < call and call < answer and answer < terminal);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"sessionId\":\"child\"") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"graff/parentToolCallId\":\"spawn-1\"") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"name\":\"Scout · reader-model\"") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"model\":\"reader-model\"") != null);
}
test "draft child sessions exclude detached and nested workers" {
try std.testing.expect(eligible("subagent", 0, false));
try std.testing.expect(!eligible("subagent", 0, true));
try std.testing.expect(!eligible("subagent", 1, false));
try std.testing.expect(!eligible("workflow_task", 0, false));
}
test "default progress mode streams the child's work onto the parent tool call" {
var buffer: [16384]u8 = undefined;
var out: Io.Writer = .fixed(&buffer);
const io = std.testing.io;
var output_lock: Io.Mutex = .init;
var state: State = .{ .out = &out, .parent = "parent", .output_lock = &output_lock, .mode = .progress };
install(io, &state);
defer uninstall(io);
// The draft announcement is not used in progress mode.
try std.testing.expect(!announce(io, "child", "Scout", "Inspect", "spawn-1", "fixture", "reader-model"));
try std.testing.expect(progressFor(io, "subagent", 0, "spawn-1"));
try std.testing.expect(!progressFor(io, "subagent", 1, "spawn-1"));
try std.testing.expect(!progressFor(io, "subagent", 0, ""));
var child: ChildSink = .{ .id = "child", .io = io, .progress = .{ .parent_call_id = "spawn-1", .child_id = "child", .name = "Scout", .provider = "fixture", .model = "reader-model" } };
child.startProgress();
try std.testing.expect(std.mem.indexOf(u8, out.buffered(), "\"title\":\"Scout · reader-model\"") != null);
const emit_sink = child.engineSink();
var input: std.json.ObjectMap = .empty;
defer input.deinit(std.testing.allocator);
try input.put(std.testing.allocator, "path", .{ .string = "src/main.zig" });
emit_sink.emit(io, .{ .tool_call_announced = .{ .id = "read-1", .name = "read_file", .input = .{ .object = input } } });
emit_sink.emit(io, .{ .tool_result = .{ .id = "read-1", .name = "bash", .text = "boom", .is_error = true } });
child.finishProgress("completed");
const wire = out.buffered();
try std.testing.expect(std.mem.indexOf(u8, wire, "\"sessionUpdate\":\"tool_call_update\"") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"toolCallId\":\"spawn-1\"") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "read_file: src/main.zig") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "bash failed") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "finished") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"sessionId\":\"parent\"") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"model\":\"reader-model\"") != null);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"provider\":\"fixture\"") != null);
// No child session, no draft updates, and no status flip on the parent call.
try std.testing.expect(std.mem.indexOf(u8, wire, "subagent_update") == null);
try std.testing.expect(std.mem.indexOf(u8, wire, "\"status\"") == null);
}