Skip to content

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

Python

Strip provider citation markers from ACP text

justrach312c01d81c60
diff --git a/src/acp_citations.zig b/src/acp_citations.zig
new file mode 100644
index 00000000..40f2bd1b
--- /dev/null
+++ b/src/acp_citations.zig
@@ -0,0 +1,179 @@
+//! 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);
+}
diff --git a/src/acp_engine.zig b/src/acp_engine.zig
index 8d8d0b75..f9c080ca 100644
--- a/src/acp_engine.zig
+++ b/src/acp_engine.zig
@@ -177,6 +177,7 @@ fn promptTurn(d: *Dispatch, arena: Allocator, w: *Io.Writer, req: proto.Request)
break :blk d.session_id orelse "";
};
if (d.bind_session) |bind| bind(d.ctx, sid);
+ @import("acp_citations.zig").endTurn(sid); // a failed turn must not leave a marker open
const config_before = configOptions(d, arena) catch |err| return turnError(d, w, req, err);
const workspace_before = acp_workspace.snapshot(d.workspace, arena);
const text = try flattenPrompt(arena, if (obj) |o| o.get("prompt") else null);
diff --git a/src/acp_protocol.zig b/src/acp_protocol.zig
index 1a66037f..0b3ceb0e 100644
--- a/src/acp_protocol.zig
+++ b/src/acp_protocol.zig
@@ -185,7 +185,12 @@ pub fn writeNotification(w: *Io.Writer, method: []const u8, params: anytype) !vo
}
/// One `agent_message_chunk` notification (the v0 final-text update).
-pub fn writeSessionUpdate(w: *Io.Writer, session_id: []const u8, text: []const u8) !void {
+/// Provider citation markers are removed on the way out (acp_citations.zig).
+pub fn writeSessionUpdate(w: *Io.Writer, session_id: []const u8, raw: []const u8) !void {
+ const cleaned = @import("acp_citations.zig").filter(session_id, .message, raw);
+ defer cleaned.deinit();
+ const text = cleaned.text;
+ if (text.len == 0 and raw.len != 0) return; // the chunk was all marker
const v2 = @import("acp_v2.zig");
if (v2.on()) return v2.writeChunk(w, session_id, false, text);
try writeNotification(w, "session/update", .{
diff --git a/src/acp_replay.zig b/src/acp_replay.zig
index d32770f6..9a2b97f5 100644
--- a/src/acp_replay.zig
+++ b/src/acp_replay.zig
@@ -34,7 +34,10 @@ fn visibleText(arena: Allocator, value: Value) ![]const u8 {
return result.items;
}
-fn message(w: *Io.Writer, sid: []const u8, role: []const u8, text: []const u8) !void {
+fn message(w: *Io.Writer, sid: []const u8, role: []const u8, raw: []const u8) !void {
+ const cleaned = @import("acp_citations.zig").whole(raw);
+ defer cleaned.deinit();
+ const text = cleaned.text;
if (text.len == 0) return;
if (v2.on()) {
// Full-content upserts need no `content: []` reset before them.
diff --git a/src/acp_stream.zig b/src/acp_stream.zig
index 95529a3b..49ac06df 100644
--- a/src/acp_stream.zig
+++ b/src/acp_stream.zig
@@ -52,7 +52,11 @@ pub fn titleFor(name: []const u8, input: Value) []const u8 {
return name;
}
-pub fn writeThought(w: *Io.Writer, session_id: []const u8, text: []const u8) !void {
+pub fn writeThought(w: *Io.Writer, session_id: []const u8, raw: []const u8) !void {
+ const cleaned = @import("acp_citations.zig").filter(session_id, .thought, raw);
+ defer cleaned.deinit();
+ const text = cleaned.text;
+ if (text.len == 0 and raw.len != 0) return; // the chunk was all marker
if (v2.on()) return v2.writeChunk(w, session_id, true, text);
try proto.writeNotification(w, "session/update", .{
.sessionId = session_id,
@@ -400,6 +404,35 @@ test "translateEvent: reasoning and text become chunks" {
try testing.expect(std.mem.indexOf(u8, w.buffered(), "agent_message_chunk") != null);
}
+test "translateEvent: a citation marker split across text events never reaches the client" {
+ defer @import("acp_citations.zig").endTurn("sess-9");
+ var buf: [2048]u8 = undefined;
+ var w: Io.Writer = .fixed(&buf);
+ var arena_state = std.heap.ArenaAllocator.init(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(Value, a, line, .{});
+ _ = try translateEvent(&w, "sess-9", ev, &id_buf, &next);
+ }
+ const out = w.buffered();
+ try testing.expect(std.mem.indexOf(u8, out, "\u{E200}") == null and std.mem.indexOf(u8, out, "\u{E201}") == null);
+ try testing.expect(std.mem.indexOf(u8, out, "turn3search0") == null and std.mem.indexOf(u8, out, "search0") == null);
+ try testing.expect(std.mem.indexOf(u8, out, "cite") == null);
+ try testing.expect(std.mem.indexOf(u8, out, "Rotate them. ") != null and std.mem.indexOf(u8, out, " Done.") != null);
+ try testing.expect(std.mem.indexOf(u8, out, "checked ") != null);
+ // The all-marker delta sends nothing: two message chunks, one thought.
+ try testing.expectEqual(@as(usize, 2), std.mem.count(u8, out, "agent_message_chunk"));
+ try testing.expectEqual(@as(usize, 1), std.mem.count(u8, out, "agent_thought_chunk"));
+}
+
test "translateEvent: a transient-retry text event is an agent_message_chunk" {
var buf: [1024]u8 = undefined;
var w: Io.Writer = .fixed(&buf);
diff --git a/src/acp_v2_prompt.zig b/src/acp_v2_prompt.zig
index b8d60eb7..90dbd2bf 100644
--- a/src/acp_v2_prompt.zig
+++ b/src/acp_v2_prompt.zig
@@ -45,6 +45,7 @@ pub fn promptTurn(d: *engine.Dispatch, arena: Allocator, w: *Io.Writer, req: pro
const Outcome = union(enum) { stop: []const u8, failed: []const u8 };
fn run(d: *engine.Dispatch, arena: Allocator, w: *Io.Writer, sid: []const u8, text: []const u8, prompt: ?std.json.Value) Outcome {
+ @import("acp_citations.zig").endTurn(sid); // a failed turn must not leave a marker open
if (d.slash) |slash| {
const reply = slash(d.ctx, arena, text) catch |err| return failure(d, err);
if (reply) |plain| {
diff --git a/src/tui_acp.zig b/src/tui_acp.zig
index b0695262..d1bc49a5 100644
--- a/src/tui_acp.zig
+++ b/src/tui_acp.zig
@@ -446,8 +446,11 @@ test "transcript sink: citations in reasoning answer and completion args reset o
try std.testing.expectEqualStrings("why\nanswer args!fresh", buf[0..stream.len.load(.acquire)]);
var aw: Io.Writer.Allocating = .init(std.testing.allocator);
defer aw.deinit();
+ // The ACP wire itself now carries no markers (acp_citations.zig), so
+ // every ACP client matches this transcript.
try writeUpdate(&aw.writer, "s1", .{ .text_delta = .{ .text = answer } });
- try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "\u{E200}") != null);
+ try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "\u{E200}") == null);
+ try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "answer") != null);
}
test "transcript sink correlates parallel results using original engine call IDs" {