Skip to content

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

Python
11.3 KB
Raw Blame
//! 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());
}