Skip to content

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

Python
8.5 KB
Raw Blame
//! ACP text without provider citation markers.
//!
//! With hosted web search, GPT models cite results with private-use markers
//! such as `\u{E200}cite\u{E202}turn3search0\u{E201}`. graff's own TUI strips
//! them on the client side (tui_acp_updates.zig), so every other ACP client
//! rendered them as boxes plus stray words. Filtering where agent text leaves
//! over ACP keeps every client 1:1 with the terminal.
//!
//! The filter is stateful per session and channel: a streamed marker can
//! straddle two deltas, and a per-chunk strip would leave `cite` and
//! `turn3search0` visible. The session transcript keeps the provider payload.

const std = @import("std");
const cite_markup = @import("cite_markup.zig");

pub const Channel = enum { message, thought };

const Slot = struct {
    used: bool = false,
    key: u64 = 0,
    channel: Channel = .message,
    stream: cite_markup.Stream = .{},
};

// Sessions a single ACP process streams at once (root plus live children).
// When all are taken the oldest slot is reused; the worst case is one marker
// split across that session's next two deltas.
const max_slots = 64;
var slots: [max_slots]Slot = @splat(.{});
var next_evict: usize = 0;
var lock: std.atomic.Value(bool) = .init(false);

fn acquire() void {
    while (lock.cmpxchgWeak(false, true, .acquire, .monotonic) != null) std.atomic.spinLoopHint();
}

fn release() void {
    lock.store(false, .release);
}

fn keyOf(session_id: []const u8) u64 {
    return std.hash.Wyhash.hash(0, session_id);
}

fn find(key: u64, channel: Channel) ?*Slot {
    for (&slots) |*slot| if (slot.used and slot.key == key and slot.channel == channel) return slot;
    return null;
}

fn claim(key: u64, channel: Channel) *Slot {
    const slot = for (&slots) |*s| {
        if (!s.used) break s;
    } else blk: {
        const s = &slots[next_evict];
        next_evict = (next_evict + 1) % max_slots;
        break :blk s;
    };
    slot.* = .{ .used = true, .key = key, .channel = channel };
    return slot;
}

pub const Cleaned = struct {
    text: []const u8,
    owned: ?[]u8 = null,

    pub fn deinit(self: Cleaned) void {
        if (self.owned) |buf| std.heap.page_allocator.free(buf);
    }
};

/// `text` with citation markers removed, continuing any marker the previous
/// chunk on this session and channel left open. Allocates only when a marker
/// byte is present or one is still open.
pub fn filter(session_id: []const u8, channel: Channel, text: []const u8) Cleaned {
    acquire();
    defer release();
    const key = keyOf(session_id);
    const existing = find(key, channel);
    const idle = if (existing) |s| s.stream.pending == 0 and !s.stream.in_annotation else true;
    if (idle and std.mem.indexOfScalar(u8, text, 0xEE) == null) return .{ .text = text };
    const slot = existing orelse claim(key, channel);
    // Each byte emits at most itself plus the (at most two) held lead bytes.
    const buf = std.heap.page_allocator.alloc(u8, text.len + 2) catch return .{ .text = text };
    var n: usize = 0;
    var out: [3]u8 = undefined;
    for (text) |b| {
        const piece = slot.stream.byte(b, &out);
        @memcpy(buf[n..][0..piece.len], piece);
        n += piece.len;
    }
    return .{ .text = buf[0..n], .owned = buf };
}

/// Stateless strip for text that is complete on its own (replayed history).
pub fn whole(text: []const u8) Cleaned {
    if (!cite_markup.contains(text)) return .{ .text = text };
    const buf = cite_markup.dupe(std.heap.page_allocator, text) catch return .{ .text = text };
    return .{ .text = buf, .owned = buf };
}

/// A turn is over: forget this session's open markers so the next turn
/// starts clean. An unfinished marker at the end of a turn is dropped.
pub fn endTurn(session_id: []const u8) void {
    acquire();
    defer release();
    const key = keyOf(session_id);
    for (&slots) |*slot| if (slot.used and slot.key == key) {
        slot.* = .{};
    };
}

fn collect(buf: *std.ArrayList(u8), session_id: []const u8, channel: Channel, chunk: []const u8) !void {
    const cleaned = filter(session_id, channel, chunk);
    defer cleaned.deinit();
    try buf.appendSlice(std.testing.allocator, cleaned.text);
}

test "a whole citation marker is removed and plain text passes through untouched" {
    defer endTurn("s-whole");
    const plain = filter("s-whole", .message, "no markers here");
    defer plain.deinit();
    try std.testing.expect(plain.owned == null);
    try std.testing.expectEqualStrings("no markers here", plain.text);
    const cited = filter("s-whole", .message, "Rotate them first. \u{E200}cite\u{E202}turn3search0\u{E201}");
    defer cited.deinit();
    try std.testing.expectEqualStrings("Rotate them first. ", cited.text);
}

test "a marker split across deltas leaves no cite or turn words behind" {
    defer endTurn("s-split");
    var buf: std.ArrayList(u8) = .empty;
    defer buf.deinit(std.testing.allocator);
    // Split inside the word, and inside the UTF-8 bytes of a marker glyph.
    for ([_][]const u8{ "Done.\u{E200}ci", "te\u{E202}turn3sea", "rch0\xee", "\x88\x81 Next." }) |chunk|
        try collect(&buf, "s-split", .message, chunk);
    try std.testing.expectEqualStrings("Done. Next.", buf.items);
}

test "channels and sessions keep separate state" {
    defer endTurn("s-a");
    defer endTurn("s-b");
    var answer: std.ArrayList(u8) = .empty;
    defer answer.deinit(std.testing.allocator);
    var thought: std.ArrayList(u8) = .empty;
    defer thought.deinit(std.testing.allocator);
    var other: std.ArrayList(u8) = .empty;
    defer other.deinit(std.testing.allocator);
    try collect(&answer, "s-a", .message, "A\u{E200}cite\u{E202}tu");
    try collect(&thought, "s-a", .thought, "thinking");
    try collect(&other, "s-b", .message, "other session");
    try collect(&answer, "s-a", .message, "rn0search1\u{E201}B");
    try std.testing.expectEqualStrings("AB", answer.items);
    try std.testing.expectEqualStrings("thinking", thought.items);
    try std.testing.expectEqualStrings("other session", other.items);
}

test "other private-use glyphs are kept" {
    defer endTurn("s-pua");
    const kept = filter("s-pua", .message, "icon \u{E000} and \u{E1FF}");
    defer kept.deinit();
    try std.testing.expectEqualStrings("icon \u{E000} and \u{E1FF}", kept.text);
}

test "endTurn drops an unfinished marker so the next turn starts clean" {
    const open = filter("s-end", .message, "tail \u{E200}cite\u{E202}turn9");
    defer open.deinit();
    try std.testing.expectEqualStrings("tail ", open.text);
    endTurn("s-end");
    const next = filter("s-end", .message, "fresh text");
    defer next.deinit();
    try std.testing.expect(next.owned == null);
    try std.testing.expectEqualStrings("fresh text", next.text);
}

test "whole strips replayed history without session state" {
    const cleaned = whole("History \u{E200}cite\u{E202}turn0view0\u{E201}line");
    defer cleaned.deinit();
    try std.testing.expectEqualStrings("History line", cleaned.text);
}

test "translateEvent: a citation marker split across text events never reaches the client" {
    defer endTurn("sess-9");
    var buf: [2048]u8 = undefined;
    var w: std.Io.Writer = .fixed(&buf);
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    var id_buf: [64]u8 = @splat(0);
    var next: u32 = 0;
    for ([_][]const u8{
        "{\"type\":\"reasoning\",\"text\":\"checked \\ue200cite\\ue202turn1search0\\ue201\"}",
        "{\"type\":\"text\",\"text\":\"Rotate them. \\ue200cite\\ue202tur\"}",
        "{\"type\":\"text\",\"text\":\"n3search0\\ue201\"}",
        "{\"type\":\"text\",\"text\":\" Done.\"}",
    }) |line| {
        const ev = try std.json.parseFromSliceLeaky(std.json.Value, a, line, .{});
        _ = try @import("acp_stream.zig").translateEvent(&w, "sess-9", ev, &id_buf, &next);
    }
    const out = w.buffered();
    try std.testing.expect(std.mem.indexOf(u8, out, "\u{E200}") == null and std.mem.indexOf(u8, out, "\u{E201}") == null);
    try std.testing.expect(std.mem.indexOf(u8, out, "turn3search0") == null and std.mem.indexOf(u8, out, "search0") == null);
    try std.testing.expect(std.mem.indexOf(u8, out, "cite") == null);
    try std.testing.expect(std.mem.indexOf(u8, out, "Rotate them. ") != null and std.mem.indexOf(u8, out, " Done.") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "checked ") != null);
    // The all-marker delta sends nothing: two message chunks, one thought.
    try std.testing.expectEqual(@as(usize, 2), std.mem.count(u8, out, "agent_message_chunk"));
    try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, out, "agent_thought_chunk"));
}