graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Standing WORK block: the user's mental model of the task, not the
//! harness's todo_write dump. Printed when the checklist changes and again
//! as chrome above `›` (ADR 0021). Raw `[x]/[~]/[ ]` lines stay in the
//! tool result the model sees; they are not conversational.
const std = @import("std");
const Io = std.Io;
const engine_events = @import("engine_events.zig");
const util = @import("util.zig");
const style = &@import("ansi.zig").style;
pub const Item = struct {
content: []const u8,
done: bool = false,
active: bool = false,
/// #1520: withdrawn or delegated. Drawn ⊘ with its reason, outside the done/total count.
cancelled: bool = false,
reason: []const u8 = "",
};
const title_clip: usize = 40;
const item_clip: usize = 48;
const reason_clip: usize = 40;
const max_items: usize = 8;
fn clip(s: []const u8, n: usize) []const u8 {
return util.utf8Prefix(std.mem.trim(u8, s, " \t\r"), n);
}
/// `WORKING {title} done/total` plus a `├`/`└` checklist. Empty input is
/// a no-op so a sink can call this on every prompt without a gate.
pub fn write(w: *Io.Writer, title: []const u8, items: []const Item) void {
if (items.len == 0 and title.len == 0) return;
const shown = if (title.len > 0) clip(title, title_clip) else "work";
var done: usize = 0;
var counted: usize = 0;
for (items) |it| {
if (it.cancelled) continue;
counted += 1;
if (it.done) done += 1;
}
w.print("{s}WORKING{s} {s}{s}{s}{s}", .{ style.muted, style.reset, style.bold, style.text, shown, style.reset }) catch return;
if (counted > 0) w.print(" {s}{d}/{d}{s}", .{ style.muted, done, counted, style.reset }) catch return;
w.writeByte('\n') catch return;
const n = @min(items.len, max_items);
for (items[0..n], 0..) |it, i| {
const branch: []const u8 = if (i + 1 == n) "└ " else "├ ";
if (it.cancelled) {
w.print("{s}{s}⊘ {s}", .{ style.faint, branch, clip(it.content, item_clip) }) catch return;
if (it.reason.len > 0) w.print(" ({s})", .{clip(it.reason, reason_clip)}) catch return;
w.print("{s}\n", .{style.reset}) catch return;
continue;
}
const mark: []const u8 = if (it.done) "✓" else if (it.active)
(if (style.accent.len > 0) "●" else "◌")
else
"○";
const color = if (it.active and !it.done) style.accent else style.muted;
const weight = if (it.active and !it.done) style.bold else "";
w.print("{s}{s}{s}{s}{s}{s} {s}{s}\n", .{
style.faint, branch, style.reset, color, weight, mark, clip(it.content, item_clip), style.reset,
}) catch return;
}
}
pub fn writeFromStanding(w: *Io.Writer, st: engine_events.StandingWork) void {
// Below the checklist, or alone: a parked turn is still working (ADR 0247).
defer writeWaiting(w, st.waiting);
// Keep completed history, but do not redraw a finished checklist as WORKING.
// Use the full counts: an open item may be beyond the displayed slice.
// Cancelled items sit outside the counts (#1520), so all-cancelled is finished too.
if ((st.todos_total > 0 or st.todos.len > 0) and st.todos_done == st.todos_total) return;
var buf: [max_items]Item = undefined;
const n = @min(st.todos.len, buf.len);
for (st.todos[0..n], 0..) |t, i| {
buf[i] = .{ .content = t.content, .done = t.done, .active = t.active, .cancelled = t.cancelled, .reason = t.reason };
}
write(w, st.goal, buf[0..n]);
}
/// ADR 0247: the prompt is back but the task is not over. Names the work the
/// session waits on so the `›` below it does not read as graff having stopped.
fn writeWaiting(w: *Io.Writer, waiting: []const u8) void {
if (waiting.len == 0) return;
w.print("{s}↻{s}{s} waiting on {s} — graff continues when it finishes{s}\n", .{
style.accent, style.reset, style.muted, waiting, style.reset,
}) catch return;
}
/// Parse the model's todo_write dump (`[x]` / `[~]` / `[ ]` lines) into the
/// same block. Unknown lines are ignored so a stray sentence cannot appear.
pub fn writeFromTodoText(w: *Io.Writer, title: []const u8, text: []const u8) void {
var buf: [max_items]Item = undefined;
var n: usize = 0;
var it = std.mem.splitScalar(u8, text, '\n');
while (it.next()) |raw| {
if (n >= buf.len) break;
const line = std.mem.trim(u8, raw, " \t\r");
if (line.len < 4) continue;
const mark = line[0..3];
const rest = std.mem.trim(u8, line[3..], " \t");
if (std.mem.eql(u8, mark, "[x]") or std.mem.eql(u8, mark, "[X]")) {
buf[n] = .{ .content = rest, .done = true };
n += 1;
} else if (std.mem.eql(u8, mark, "[~]")) {
buf[n] = .{ .content = rest, .active = true };
n += 1;
} else if (std.mem.eql(u8, mark, "[ ]")) {
buf[n] = .{ .content = rest };
n += 1;
} else if (std.mem.eql(u8, mark, "[-]")) {
// goal_state.renderTodos writes "[-] content (cancelled: reason)".
const cut = std.mem.lastIndexOf(u8, rest, " (cancelled: ");
const has_reason = cut != null and std.mem.endsWith(u8, rest, ")");
buf[n] = if (has_reason)
.{ .content = rest[0..cut.?], .reason = rest[cut.? + " (cancelled: ".len .. rest.len - 1], .cancelled = true }
else
.{ .content = rest, .cancelled = true };
n += 1;
}
}
if (n == 0) return;
write(w, title, buf[0..n]);
}
test "completed checklist stays out of idle prompt redraws" {
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
const todos = [_]engine_events.StandingTodo{.{ .content = "finished", .done = true }};
var st: engine_events.StandingWork = .{ .todos = &todos, .todos_done = 1, .todos_total = 1 };
writeFromStanding(&aw.writer, st);
try std.testing.expectEqualStrings("", aw.written());
// A finished checklist stays idle even when a goal title remains.
st.goal = "continue the goal";
writeFromStanding(&aw.writer, st);
try std.testing.expectEqualStrings("", aw.written());
aw.clearRetainingCapacity();
st.goal = "";
st.todos_total = 2;
writeFromStanding(&aw.writer, st);
try std.testing.expect(std.mem.indexOf(u8, aw.written(), "WORKING") != null);
}
test "terminal working block highlights active work without hiding waiting" {
const saved = style.*;
style.* = @import("ansi.zig").Style.harness;
defer style.* = saved;
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
const items = [_]engine_events.StandingTodo{
.{ .content = "finished", .done = true },
.{ .content = "current", .active = true },
.{ .content = "next" },
};
writeFromStanding(&aw.writer, .{ .goal = "ship it", .todos = &items, .todos_done = 1, .todos_total = 3, .waiting = "agent 4" });
const text = aw.written();
try std.testing.expect(std.mem.indexOf(u8, text, "\x1b[38;2;154;147;132m✓ finished\x1b[0m") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "\x1b[38;2;232;163;61m\x1b[1m● current\x1b[0m") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "\x1b[38;2;154;147;132m○ next\x1b[0m") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "waiting on agent 4 — graff continues when it finishes") != null);
}
test "empty standing work draws nothing" {
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
write(&aw.writer, "", &.{});
try std.testing.expectEqualStrings("", aw.writer.buffered());
}
test "a checklist is WORKING plus a tree, not [~] dump lines" {
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
writeFromTodoText(&aw.writer, "full Meld test deployment", "[x] inspect\n[~] configure Cloudflare\n[ ] build + validate\n[ ] deploy + verify\n[ ] commit + push\n");
try std.testing.expectEqualStrings(
"WORKING full Meld test deployment 1/5\n" ++
"├ ✓ inspect\n" ++
"├ ◌ configure Cloudflare\n" ++
"├ ○ build + validate\n" ++
"├ ○ deploy + verify\n" ++
"└ ○ commit + push\n",
aw.writer.buffered(),
);
}
test "#1520 a cancelled item is drawn with its reason, outside the done count" {
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
writeFromTodoText(&aw.writer, "ship", "[x] land the fix\n[ ] run the tests\n[-] verify the release (cancelled: delegated to the release session)\n");
try std.testing.expectEqualStrings(
"WORKING ship 1/2\n" ++
"├ ✓ land the fix\n" ++
"├ ○ run the tests\n" ++
"└ ⊘ verify the release (delegated to the release session)\n",
aw.writer.buffered(),
);
aw.clearRetainingCapacity();
// Everything else done: the idle prompt treats the list as finished.
const items = [_]engine_events.StandingTodo{
.{ .content = "land the fix", .done = true },
.{ .content = "verify the release", .cancelled = true, .reason = "delegated" },
};
writeFromStanding(&aw.writer, .{ .todos = &items, .todos_done = 1, .todos_total = 1 });
try std.testing.expectEqualStrings("", aw.written());
}
test "writeFromStanding uses the goal title and active/done marks" {
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
const items = [_]engine_events.StandingTodo{
.{ .content = "inspect", .done = true },
.{ .content = "configure", .active = true },
.{ .content = "deploy" },
};
writeFromStanding(&aw.writer, .{ .goal = "ship it", .todos = &items, .todos_done = 1, .todos_total = 3 });
try std.testing.expectEqualStrings(
"WORKING ship it 1/3\n" ++
"├ ✓ inspect\n" ++
"├ ◌ configure\n" ++
"└ ○ deploy\n",
aw.writer.buffered(),
);
}
test "ADR 0247: a parked turn says what it waits on, with or without a checklist" {
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
const items = [_]engine_events.StandingTodo{
.{ .content = "inspect", .done = true },
.{ .content = "configure inbound replies", .active = true },
};
writeFromStanding(&aw.writer, .{ .todos = &items, .todos_done = 1, .todos_total = 2, .waiting = "terraform plan" });
try std.testing.expectEqualStrings(
"WORKING work 1/2\n" ++
"├ ✓ inspect\n" ++
"└ ◌ configure inbound replies\n" ++
"↻ waiting on terraform plan — graff continues when it finishes\n",
aw.written(),
);
aw.clearRetainingCapacity();
// A finished checklist stays hidden, but the wait does not.
const finished = [_]engine_events.StandingTodo{.{ .content = "inspect", .done = true }};
writeFromStanding(&aw.writer, .{ .todos = &finished, .todos_done = 1, .todos_total = 1, .waiting = "zig build" });
try std.testing.expectEqualStrings("↻ waiting on zig build — graff continues when it finishes\n", aw.written());
aw.clearRetainingCapacity();
writeFromStanding(&aw.writer, .{ .waiting = "agent 4" });
try std.testing.expectEqualStrings("↻ waiting on agent 4 — graff continues when it finishes\n", aw.written());
}