graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
ACP: report compaction with compaction_update
justrach9a43ec5b6465
diff --git a/build.zig b/build.zigindex 6a129d9e..aaaca53a 100644--- a/build.zig+++ b/build.zig@@ -180,6 +180,9 @@ pub fn build(b: *std.Build) void {const acp_slash_typo_test = b.addSystemCommand(&.{ "python3", "scripts/test-acp-slash-typo.py" });acp_slash_typo_test.addArtifactArg(exe);test_step.dependOn(&acp_slash_typo_test.step);+ const acp_compaction_test = b.addSystemCommand(&.{ "python3", "scripts/test-acp-compaction.py" });+ acp_compaction_test.addArtifactArg(exe);+ test_step.dependOn(&acp_compaction_test.step);const run_tool_budget_test = b.addSystemCommand(&.{ "python3", "scripts/test-run-tool-budget.py" });run_tool_budget_test.addArtifactArg(exe);test_step.dependOn(&run_tool_budget_test.step);diff --git a/docs/acp-compatibility.md b/docs/acp-compatibility.mdindex 39598906..14f5f6ca 100644--- a/docs/acp-compatibility.md+++ b/docs/acp-compatibility.md@@ -36,6 +36,7 @@ optional feature or draft extension is enabled.| Client filesystem and terminals | These are optional negotiated ACP facilities, not a requirement that local harness tools be replaced by client tools. The local tool implementation does not imply support for every client-side method. | Capability negotiation and the upstream v1 schema || Usage | Connection usage is a namespaced extension. It preserves unknown totals and is not a standard ACP v1 billing contract. | `scripts/test-acp-usage.py`, ADR 0182 || Subagents | Default: a top-level subagent streams its work onto the parent tool call as standard `tool_call_update` content (a rolling log of its tool calls, failures and message tail), with no `status` change and `_meta["graff/subagent"]` = `{sessionId, name, state}`; `GRAFF_ACP_SUBAGENT_PROGRESS=0` disables it. Opt-in preview: the proposed child-session stream (client `subagents` capability plus `GRAFF_ACP_DRAFT_SUBAGENTS=1`) replaces it for foreground children. Detached workers also keep `graff/agents` inspection. Child history is not yet replayed on `session/load`. | `scripts/test-acp-subagent-update.py`, ADR 0194, ADR 0205 |+| Compaction | When the root agent compacts (automatically, `/compact`, or server-side), graff sends `compaction_update` `{compactionId, status}`: `in_progress`, then one of `completed` (a local summary rides `summary` as a text block), `failed` (with `error`) or `cancelled`. A provider that compacted in-stream gets one `completed`. ACP v1 marks this unstable, so it is sent only to clients that advertise `clientCapabilities.session.compaction`; ACP v2 clients always get it. | `src/acp_compaction.zig`, `scripts/test-acp-compaction.py` || Transport | ACP uses JSON-RPC over stdio. HTTP/2 checks exercise the model request transport behind ACP; they do not redefine ACP as an HTTP/2 protocol. | `scripts/test-acp-http2.py`, `scripts/test-acp-http2-retry.py` |## ACP v2 preview (`GRAFF_ACP_V2=1`)diff --git a/scripts/test-acp-compaction.py b/scripts/test-acp-compaction.pynew file mode 100644index 00000000..f042b2d7--- /dev/null+++ b/scripts/test-acp-compaction.py@@ -0,0 +1,66 @@+#!/usr/bin/env python3+"""Offline: /compact over ACP reports compaction_update only to clients that+advertise clientCapabilities.session.compaction (ACP v1)."""+import json, os, queue, signal, subprocess, sys, tempfile, threading, time+from pathlib import Path+sys.path.insert(0, str(Path(__file__).resolve().parent / 'eval'))+from mock_model import ScriptedModel+++def run(binary, opted):+ script = [{'text': 'A hash map stores key/value pairs.'}, {'text': 'Summary: the user asked about hash maps; answered.'}]+ model = ScriptedModel(script)+ with tempfile.TemporaryDirectory(prefix='acp-compaction-') as temp:+ env = {k: v for k, v in os.environ.items() if not k.endswith('_API_KEY')}+ config = Path(temp) / 'mcp.json'+ config.write_text('{"mcpServers":{}}')+ env.update(HOME=temp, AI_GATEWAY_API_KEY='local', GRAFF_MCP_CONFIG=str(config), GRAFF_NO_TELEMETRY='1', GRAFF_FLEET='off', GRAFF_NO_SMOLIFY='1', GRAFF_NO_CODEDB_GUARD='1')+ port = model.start(0)+ env['GRAFF_VERCEL_URL'] = f'http://127.0.0.1:{port}/v1/chat/completions'+ proc = subprocess.Popen([binary, 'acp', '--model', 'vercel', '--old', '--no-lean', '--yolo'], cwd=temp, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, start_new_session=True)+ messages = queue.Queue()+ threading.Thread(target=lambda: [messages.put(l) for l in proc.stdout] and messages.put(None), daemon=True).start()++ def call(id, method, params):+ proc.stdin.write(json.dumps({'jsonrpc': '2.0', 'id': id, 'method': method, 'params': params}) + '\n')+ proc.stdin.flush()+ updates, deadline = [], time.monotonic() + 30+ while True:+ line = messages.get(timeout=max(.01, deadline - time.monotonic()))+ assert line is not None, 'ACP worker exited'+ try:+ m = json.loads(line)+ except ValueError:+ continue+ if m.get('id') == id and 'method' not in m:+ return m, updates+ u = m.get('params', {}).get('update', {})+ if u.get('sessionUpdate', '').startswith('compaction'):+ updates.append(u)+ try:+ caps = {'session': {'compaction': {}}} if opted else {}+ call(1, 'initialize', {'protocolVersion': 1, 'clientCapabilities': caps})+ result, _ = call(2, 'session/new', {'cwd': temp, 'mcpServers': []})+ sid = result['result']['sessionId']+ call(3, 'session/prompt', {'sessionId': sid, 'prompt': [{'type': 'text', 'text': 'What is a hash map?'}]})+ reply, updates = call(4, 'session/prompt', {'sessionId': sid, 'prompt': [{'type': 'text', 'text': '/compact'}]})+ assert reply.get('result', {}).get('stopReason') == 'end_turn', reply+ if not opted:+ assert updates == [], updates+ print('PASS ACP compaction: no updates for a client without the capability', flush=True)+ return+ assert [u['status'] for u in updates] == ['in_progress', 'completed'], updates+ assert updates[0]['compactionId'] == updates[1]['compactionId'], updates+ summary = updates[1]['summary'][0]+ assert summary['type'] == 'text' and summary['text'].strip(), updates+ print('PASS ACP compaction: in_progress then completed with the summary', flush=True)+ finally:+ os.killpg(proc.pid, signal.SIGKILL)+ proc.wait(timeout=3)+ model.stop()+++if __name__ == '__main__':+ binary = str(Path(sys.argv[1] if len(sys.argv) > 1 else 'zig-out/bin/graff').resolve())+ run(binary, True)+ run(binary, False)diff --git a/src/acp.zig b/src/acp.zigindex a00d5881..25d2c087 100644--- a/src/acp.zig+++ b/src/acp.zig@@ -80,6 +80,11 @@ fn liveSlash(ctx: *anyopaque, arena: Allocator, text: []const u8) anyerror!?[]coreturn try engine.stripSgr(arena, aw.writer.buffered());}if (command_catalog.match(text) == null and command_catalog.commandWord(text) == null) return null;+ // /compact reports compaction_update like an automatic one.+ var lock: Io.Mutex = .init;+ var compaction: @import("acp_compaction.zig").Sink = .{ .out = live.out, .output_lock = &lock, .io = live.root.io, .session_id = live.session_id };+ @import("acp_compaction.zig").install(&compaction);+ defer @import("acp_compaction.zig").uninstall();try main_mod.handleCommand(live.root, live.keys, arena, std.mem.trim(u8, text, " \t\r\n"), &aw.writer);return try engine.stripSgr(arena, aw.writer.buffered());}diff --git a/src/acp_compaction.zig b/src/acp_compaction.zignew file mode 100644index 00000000..d38492a3--- /dev/null+++ b/src/acp_compaction.zig@@ -0,0 +1,171 @@+//! ACP `compaction_update`: tell the client when the root agent compacts its+//! context, so it can show "Compacting…" and then "Context compacted" (or the+//! failure) instead of a context meter that silently drops.+//!+//! ACP v1 marks the update unstable: an agent may send it only when the client+//! advertised `clientCapabilities.session.compaction` at initialize. ACP v2+//! needs no capability. Anything else gets nothing from this module.+//!+//! A live ACP prompt turn installs a sink (acp_live_turn.zig); every+//! compaction site calls `start`, which is inert without one. A `Run` sends+//! `in_progress` once and exactly one final status, even on error paths.++const std = @import("std");+const Io = std.Io;+const Value = std.json.Value;++var client_opted_in = std.atomic.Value(bool).init(false);++/// From the `initialize` params: does this client take v1 compaction updates?+pub fn noteInitialize(params: ?Value) void {+ client_opted_in.store(advertises(params), .release);+}++fn advertises(params: ?Value) bool {+ const p = params orelse return false;+ if (p != .object) return false;+ const caps = p.object.get("clientCapabilities") orelse return false;+ if (caps != .object) return false;+ const session = caps.object.get("session") orelse return false;+ if (session != .object) return false;+ const compaction = session.object.get("compaction") orelse return false;+ return compaction == .object or (compaction == .bool and compaction.bool);+}++pub fn enabled() bool {+ return client_opted_in.load(.acquire) or @import("acp_v2.zig").on();+}++pub const Sink = struct {+ out: *Io.Writer,+ output_lock: *Io.Mutex,+ io: Io,+ session_id: []const u8,+ /// The agent's buffered event writer: flushed first so this update lands+ /// after everything the turn already produced.+ events: ?*Io.Writer = null,+ next: u32 = 0,+ active: bool = false,+};++var g_sink: ?*Sink = null;++pub fn install(sink: *Sink) void {+ g_sink = sink;+}++pub fn uninstall() void {+ g_sink = null;+}++pub const Status = enum { completed, failed, cancelled };++pub const Run = struct {+ sink: ?*Sink = null,+ id_buf: [32]u8 = undefined,+ id_len: usize = 0,++ fn id(self: *const Run) []const u8 {+ return self.id_buf[0..self.id_len];+ }++ /// Close this compaction. Later calls do nothing, so a success path and a+ /// deferred failure path can both call it.+ pub fn finish(self: *Run, status: Status, summary: ?[]const u8, err_text: ?[]const u8) void {+ const sink = self.sink orelse return;+ self.sink = null;+ sink.active = false;+ send(sink, self.id(), @tagName(status), summary, err_text);+ }+};++/// Begin a compaction for the root agent. Inert for subagents, title calls,+/// clients without the capability, outside a live ACP turn, and when one is+/// already open (the outer compaction owns the report).+pub fn start(is_root: bool) Run {+ if (!is_root or !enabled()) return .{};+ const sink = g_sink orelse return .{};+ if (sink.active) return .{};+ sink.active = true;+ sink.next +%= 1;+ var run: Run = .{ .sink = sink };+ const written = std.fmt.bufPrint(&run.id_buf, "compaction-{d}", .{sink.next}) catch "compaction";+ run.id_len = written.len;+ send(sink, run.id(), "in_progress", null, null);+ return run;+}++/// A compaction the provider already finished on its own (in-stream).+pub fn completedNow(is_root: bool) void {+ var run = start(is_root);+ run.finish(.completed, null, null);+}++fn send(sink: *Sink, id: []const u8, status: []const u8, summary: ?[]const u8, err_text: ?[]const u8) void {+ if (sink.events) |events| events.flush() catch {};+ sink.output_lock.lockUncancelable(sink.io);+ defer sink.output_lock.unlock(sink.io);+ write(sink.out, sink.session_id, id, status, summary, err_text) catch return;+ sink.out.flush() catch {};+}++pub fn write(w: *Io.Writer, sid: []const u8, id: []const u8, status: []const u8, summary: ?[]const u8, err_text: ?[]const u8) !void {+ var s: std.json.Stringify = .{ .writer = w, .options = .{ .emit_null_optional_fields = false } };+ const Block = struct { type: []const u8 = "text", text: []const u8 };+ const blocks: ?[1]Block = if (summary) |text| .{.{ .text = text }} else null;+ try s.write(.{ .jsonrpc = "2.0", .method = "session/update", .params = .{+ .sessionId = sid,+ .update = .{+ .sessionUpdate = "compaction_update",+ .compactionId = id,+ .status = status,+ .summary = blocks,+ .@"error" = err_text,+ },+ } });+ try w.writeByte('\n');+}++test "v1 clients opt in with clientCapabilities.session.compaction" {+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena.deinit();+ const a = arena.allocator();+ const yes = try std.json.parseFromSliceLeaky(Value, a, "{\"clientCapabilities\":{\"session\":{\"compaction\":{}}}}", .{});+ const no = try std.json.parseFromSliceLeaky(Value, a, "{\"clientCapabilities\":{\"fs\":{}}}", .{});+ try std.testing.expect(advertises(yes));+ try std.testing.expect(!advertises(no));+ try std.testing.expect(!advertises(null));+}++test "a run sends in_progress once and one final status, only when opted in" {+ var buf: [2048]u8 = undefined;+ var out: Io.Writer = .fixed(&buf);+ var lock: Io.Mutex = .init;+ var sink: Sink = .{ .out = &out, .output_lock = &lock, .io = std.testing.io, .session_id = "s1" };+ install(&sink);+ defer uninstall();+ defer client_opted_in.store(false, .release);++ client_opted_in.store(false, .release);+ var off = start(true);+ off.finish(.completed, null, null);+ try std.testing.expectEqual(@as(usize, 0), out.buffered().len);++ client_opted_in.store(true, .release);+ var run = start(true);+ var nested = start(true); // the outer compaction owns the report+ nested.finish(.failed, null, "inner");+ var child = start(false); // subagents never report+ child.finish(.failed, null, "child");+ run.finish(.completed, "Kept the plan; dropped old tool output.", null);+ run.finish(.failed, null, "late"); // already closed+ const text = out.buffered();+ try std.testing.expectEqual(@as(usize, 2), std.mem.count(u8, text, "compaction_update"));+ try std.testing.expect(std.mem.indexOf(u8, text, "\"compactionId\":\"compaction-1\",\"status\":\"in_progress\"}") != null);+ try std.testing.expect(std.mem.indexOf(u8, text, "\"status\":\"completed\",\"summary\":[{\"type\":\"text\",\"text\":\"Kept the plan; dropped old tool output.\"}]") != null);+ try std.testing.expect(std.mem.indexOf(u8, text, "inner") == null and std.mem.indexOf(u8, text, "late") == null);++ out = .fixed(&buf);+ completedNow(true);+ try std.testing.expectEqual(@as(usize, 2), std.mem.count(u8, out.buffered(), "compaction_update"));+}diff --git a/src/acp_engine.zig b/src/acp_engine.zigindex f9c080ca..e296a373 100644--- a/src/acp_engine.zig+++ b/src/acp_engine.zig@@ -248,6 +248,7 @@ pub fn handlePreAuthLine(arena: Allocator, w: *Io.Writer, line: []const u8) !voiconst req = parseRequest(arena, line) orelse return;if (std.mem.eql(u8, req.method, "initialize")) {v2.negotiate(req.params, 0);+ @import("acp_compaction.zig").noteInitialize(req.params);return respondInitialize(w, req, false);}return respondError(w, req, err_auth_required, acp_auth.required_message);@@ -258,6 +259,7 @@ pub fn handleLine(d: *Dispatch, arena: Allocator, w: *Io.Writer, line: []const uif (std.mem.eql(u8, req.method, "initialize")) {v2.negotiate(req.params, d.seed);@import("acp_elicit.zig").configure(req.params);+ @import("acp_compaction.zig").noteInitialize(req.params);// The draft child-session RFD is a v1 shape; v2 gets tool-call progress.d.subagents = !v2.on() and supportsSubagents(req.params);d.background_subagents = supportsBackgroundSubagents(req.params);diff --git a/src/acp_live_turn.zig b/src/acp_live_turn.zigindex eb769a29..3108791a 100644--- a/src/acp_live_turn.zig+++ b/src/acp_live_turn.zig@@ -77,6 +77,9 @@ pub const LiveTurn = struct {sink.init(self.root.gpa, self.out, &self.session_id, &self.saw_text);sink.output_lock = &output_lock;sink.output_io = self.root.io;+ var compaction: @import("acp_compaction.zig").Sink = .{ .out = self.out, .output_lock = &output_lock, .io = self.root.io, .session_id = self.session_id, .events = &sink.writer };+ @import("acp_compaction.zig").install(&compaction);+ defer @import("acp_compaction.zig").uninstall();// Standard progress on the parent tool call by default; the draft// child-session stream only when both sides opted in (ADR 0194/0205).const draft = self.dispatch != null and self.dispatch.?.subagents and self.dispatch.?.draft_subagents_enabled;diff --git a/src/agent_compact.zig b/src/agent_compact.zigindex 8b4bc3c2..9214bf33 100644--- a/src/agent_compact.zig+++ b/src/agent_compact.zig@@ -199,6 +199,8 @@ pub fn compact(self: *Agent) anyerror!usize {var progress = @import("compact_status.zig").begin(self);defer progress.end(self);+ var acp_run = @import("acp_compaction.zig").start(!self.sub and self.call_kind != .title);+ defer acp_run.finish(.failed, null, "compaction did not complete; history unchanged"); // no-op after success// The handoff summary is internal — don't stream it to the terminal.const was_quiet = self.stream_quiet;const was_compaction_request = self.compaction_request;@@ -236,6 +238,7 @@ pub fn compact(self: *Agent) anyerror!usize {self.goal_note_fp = 0; // the injected goal note died with the old history - re-state in full (#318)self.history_rewrites +%= 1; // readers of pasted state (the /loop checklist gate) re-carry it (#318)installed_summary = true;+ acp_run.finish(.completed, summary, null);// #445: the history the model was reading is gone and the durable file is// now the only place its exact wording survives, so THIS is where the #410// transcript line starts being worth its tokens. It rides this boundarydiff --git a/src/agent_server_compact.zig b/src/agent_server_compact.zigindex 69835102..ffe051a3 100644--- a/src/agent_server_compact.zig+++ b/src/agent_server_compact.zig@@ -311,15 +311,18 @@ pub fn manualCompact(self: *Agent) anyerror!usize {if (!main_mod.json_mode and @import("repl.zig").g_debug) try self.say("[compacting ~{d} tokens with OpenAI…]\n", .{pending_tokens});var progress = @import("compact_status.zig").begin(self);defer progress.end(self);+ var acp_run = @import("acp_compaction.zig").start(!self.sub and self.call_kind != .title);const result = switch (route) {.standalone => compactStandalone(self),.in_stream => compactInStream(self),.local => unreachable,} catch |err| {progress.end(self);+ acp_run.finish(if (err == error.Interrupted or err == error.Canceled) .cancelled else .failed, null, @errorName(err));return fallbackLocal(self, err);};progress.end(self);+ acp_run.finish(.completed, null, null);if (!main_mod.json_mode) try self.say("Compacted context.\n", .{});return result;}@@ -386,6 +389,7 @@ pub fn pruneIf(self: *Agent, server_arm: bool) bool {self.goal_note_fp = 0;self.history_rewrites +%= 1; // breaks the codex chain → next request re-anchorsnotePrune(dropped);+ @import("acp_compaction.zig").completedNow(!self.sub and self.call_kind != .title);if (!main_mod.json_mode) {if (@import("repl.zig").g_debug)self.say("[server compacted context: {d} earlier item(s) now carried by the model's compaction state]\n", .{dropped}) catch {}@@ -464,6 +468,8 @@ pub fn explicitCompact(self: *Agent) bool {}const body = buildCompactBody(self) catch return false;defer self.gpa.free(body);+ var acp_run = @import("acp_compaction.zig").start(!self.sub and self.call_kind != .title);+ defer acp_run.finish(.failed, null, "server compaction was refused or failed");var cp = self.provider;cp.url = compact_url;if (!main_mod.json_mode and @import("repl.zig").g_debug) self.say("[compacting server-side: {d} item(s)…]\n", .{self.messages.items.len}) catch {};@@ -474,7 +480,9 @@ pub fn explicitCompact(self: *Agent) bool {return false;};defer self.gpa.free(resp);- return installCompactionItem(self, resp);+ if (!installCompactionItem(self, resp)) return false;+ acp_run.finish(.completed, null, null);+ return true;}/// Parse a compact-endpoint response and restart history from output[0].