Skip to content

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

Python
6.7 KB
Raw Blame
//! Standard ACP v1 subagent progress (ADR 0205). While a child works, its
//! parent's `agent` tool call receives `tool_call_update`s whose `content` is
//! a short rolling log of what the child is doing: each tool it calls, any
//! failure, and the tail of the message it is writing. Every ACP client
//! renders tool call content, so this needs no capability or flag. Updates
//! carry no `status`: the parent's own tool result decides that, and a
//! detached child's spawn call stays completed instead of spinning forever.

const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const proto = @import("acp_protocol.zig");
const stream = @import("acp_stream.zig");
const util = @import("util.zig");

pub const max_lines = 12;
pub const line_max = 160;
pub const tail_max = 280;
/// Text deltas publish at most this often; tool events publish immediately.
pub const text_interval_ms: i64 = 400;

pub const Progress = struct {
    parent_call_id: []const u8,
    child_id: []const u8,
    name: []const u8,
    provider: []const u8 = "",
    model: []const u8 = "",
    lines: [max_lines][line_max]u8 = undefined,
    lens: [max_lines]usize = @splat(0),
    count: usize = 0,
    tail: [tail_max]u8 = undefined,
    tail_len: usize = 0,
    last_ms: i64 = 0,

    pub fn addLine(p: *Progress, text: []const u8) void {
        const slot = p.count % max_lines;
        const cut = util.utf8Prefix(text, line_max);
        var n: usize = 0;
        for (cut) |c| {
            p.lines[slot][n] = if (c == '\n' or c == '\r' or c == '\t') ' ' else c;
            n += 1;
        }
        p.lens[slot] = n;
        p.count += 1;
        // A new step starts a new message; the old tail belongs to the step before.
        p.tail_len = 0;
    }

    /// Keep the last `tail_max` bytes of the message being written, cut on a
    /// UTF-8 boundary.
    pub fn addText(p: *Progress, delta: []const u8) void {
        if (delta.len >= tail_max) {
            var start = delta.len - tail_max;
            while (start < delta.len and (delta[start] & 0xC0) == 0x80) start += 1;
            const rest = delta[start..];
            @memcpy(p.tail[0..rest.len], rest);
            p.tail_len = rest.len;
            return;
        }
        const keep = @min(p.tail_len, tail_max - delta.len);
        var start = p.tail_len - keep;
        while (start < p.tail_len and (p.tail[start] & 0xC0) == 0x80) start += 1;
        std.mem.copyForwards(u8, p.tail[0 .. p.tail_len - start], p.tail[start..p.tail_len]);
        const base = p.tail_len - start;
        @memcpy(p.tail[base..][0..delta.len], delta);
        p.tail_len = base + delta.len;
    }

    pub fn toolLine(p: *Progress, name: []const u8, input: Value) void {
        var buf: [line_max]u8 = undefined;
        const title = stream.titleFor(name, input);
        const line = if (std.mem.eql(u8, title, name))
            std.fmt.bufPrint(&buf, "▸ {s}", .{name}) catch name
        else
            std.fmt.bufPrint(&buf, "▸ {s}: {s}", .{ name, util.utf8Prefix(title, line_max - name.len - 8) }) catch name;
        p.addLine(line);
    }

    /// Oldest to newest, then the message tail.
    pub fn render(p: *const Progress, buf: []u8) []const u8 {
        var w: Io.Writer = .fixed(buf);
        const first = if (p.count > max_lines) p.count - max_lines else 0;
        var i = first;
        while (i < p.count) : (i += 1) {
            const slot = i % max_lines;
            if (i > first) w.writeAll("\n") catch break;
            w.writeAll(p.lines[slot][0..p.lens[slot]]) catch break;
        }
        if (p.tail_len > 0) {
            if (p.count > 0) w.writeAll("\n\n") catch {};
            w.writeAll(std.mem.trim(u8, p.tail[0..p.tail_len], " \n")) catch {};
        }
        return w.buffered();
    }

    pub fn due(p: *Progress, now_ms: i64, tool_event: bool) bool {
        if (!tool_event and now_ms - p.last_ms < text_interval_ms) return false;
        p.last_ms = now_ms;
        return true;
    }
};

/// Keep the resolved model visible even in clients without extension badges.
pub fn displayName(buf: []u8, name: []const u8, model: []const u8) []const u8 {
    if (model.len == 0) return name;
    return std.fmt.bufPrint(buf, "{s} · {s}", .{ util.utf8Prefix(name, 256), util.utf8Prefix(model, 256) }) catch name;
}

/// One progress update on the parent's tool call, in the parent's session.
pub fn write(w: *Io.Writer, parent_session: []const u8, p: *const Progress, state: []const u8) !void {
    var buf: [max_lines * (line_max + 1) + tail_max + 8]u8 = undefined;
    var title: [768]u8 = undefined;
    try proto.writeNotification(w, "session/update", .{
        .sessionId = parent_session,
        .update = .{
            .sessionUpdate = "tool_call_update",
            .toolCallId = p.parent_call_id,
            .title = displayName(&title, p.name, p.model),
            .content = .{
                .{ .type = "content", .content = .{ .type = "text", .text = p.render(&buf) } },
            },
            ._meta = .{ .@"graff/subagent" = .{ .sessionId = p.child_id, .name = p.name, .state = state, .provider = p.provider, .model = p.model } },
        },
    });
}

/// GRAFF_ACP_SUBAGENT_PROGRESS=0 turns the stream off.
pub fn enabled() bool {
    const v = std.c.getenv("GRAFF_ACP_SUBAGENT_PROGRESS") orelse return true;
    return !std.mem.eql(u8, std.mem.span(v), "0");
}

test "the log keeps the newest steps and a UTF-8-safe message tail" {
    var p: Progress = .{ .parent_call_id = "spawn-1", .child_id = "sa-1", .name = "Scout" };
    var i: usize = 0;
    while (i < max_lines + 3) : (i += 1) {
        var b: [32]u8 = undefined;
        p.addLine(std.fmt.bufPrint(&b, "step {d}", .{i}) catch unreachable);
    }
    var out: [4096]u8 = undefined;
    const text = p.render(&out);
    try std.testing.expect(std.mem.indexOf(u8, text, "step 0\n") == null);
    try std.testing.expect(std.mem.startsWith(u8, text, "step 3"));
    try std.testing.expect(std.mem.endsWith(u8, text, "step 14"));
    var long: [600]u8 = undefined;
    for (&long, 0..) |*c, k| c.* = if (k % 3 == 0) 0xE2 else if (k % 3 == 1) 0x96 else 0xB8; // "▸" repeated
    p.addText(&long);
    try std.testing.expect(p.tail_len <= tail_max);
    try std.testing.expect(std.unicode.utf8ValidateSlice(p.tail[0..p.tail_len]));
    p.addText("done.");
    try std.testing.expect(std.mem.endsWith(u8, p.tail[0..p.tail_len], "done."));
    try std.testing.expect(std.unicode.utf8ValidateSlice(p.tail[0..p.tail_len]));
}

test "text publishes on an interval, tool events at once" {
    var p: Progress = .{ .parent_call_id = "c", .child_id = "s", .name = "n" };
    try std.testing.expect(p.due(1000, false));
    try std.testing.expect(!p.due(1100, false));
    try std.testing.expect(p.due(1150, true));
    try std.testing.expect(p.due(1600, false));
}