Skip to content

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.zig
index 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.md
index 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.py
new file mode 100644
index 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.zig
index 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!?[]co
return 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.zig
new file mode 100644
index 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.zig
index 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) !voi
const 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 u
if (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.zig
index 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.zig
index 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 boundary
diff --git a/src/agent_server_compact.zig b/src/agent_server_compact.zig
index 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-anchors
notePrune(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].