Skip to content

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

Python

compaction: GRAFF_COMPACT_MIX two-pass arm (opt-in)

justrachf81d46db5d9f
diff --git a/evals/compact_ab/README.md b/evals/compact_ab/README.md
index 80457b8d..968a6741 100644
--- a/evals/compact_ab/README.md
+++ b/evals/compact_ab/README.md
@@ -22,8 +22,19 @@ scripted stdin sessions cannot approve writes (#unattended-gate).
|---|---|
| server | `GRAFF_SERVER_COMPACT=1 GRAFF_COMPACT_PCT=6` |
| client | `GRAFF_SERVER_COMPACT=0 GRAFF_COMPACT_PCT=6` |
+| mix | `GRAFF_SERVER_COMPACT=0 GRAFF_COMPACT_MIX=1 GRAFF_COMPACT_PCT=6` |
| none | `GRAFF_SERVER_COMPACT=0 GRAFF_COMPACT_PCT=100` |
+The `mix` arm is the two-pass mixture compactor (`src/compact_mix.zig`): a
+low-effort extract pass mines a state ledger (decisions, dead ends with the
+reason each failed, in-flight identifiers verbatim, next step, open user asks)
+and the synthesis pass weaves it into the handoff summary at session effort.
+Any extract failure falls back to the byte-identical single-pass summary, so
+the arm is baseline-safe in failure behavior and costs one extra low-effort
+call per compaction. The comparison prices whether the ledger improves recall
+(the observed failure shape — erased "already tried that" state causing retry
+loops) enough to pay for that call.
+
`run_compact_bench.sh wave N` runs one trial per arm in parallel; `score_compact_bench.py`
grades `answer.md` against `questions.json` and counts compaction notices.
diff --git a/evals/compact_ab/run_compact_bench.sh b/evals/compact_ab/run_compact_bench.sh
index d1ca7e04..84ef73b9 100644
--- a/evals/compact_ab/run_compact_bench.sh
+++ b/evals/compact_ab/run_compact_bench.sh
@@ -15,6 +15,7 @@ run_one() {
case $arm in
server) envs="GRAFF_SERVER_COMPACT=1 GRAFF_COMPACT_PCT=6";;
client) envs="GRAFF_SERVER_COMPACT=0 GRAFF_COMPACT_PCT=6";;
+ mix) envs="GRAFF_SERVER_COMPACT=0 GRAFF_COMPACT_MIX=1 GRAFF_COMPACT_PCT=6";;
none) envs="GRAFF_SERVER_COMPACT=0 GRAFF_COMPACT_PCT=100";;
esac
envs="$envs GRAFF_TOOL_HANDLE_BYTES=262144"
@@ -28,10 +29,10 @@ run_one() {
if [ "${1:-}" = "wave" ]; then
# one trial per arm in parallel (wave $2)
- run_one server "$2" & run_one client "$2" & run_one none "$2" & wait
+ run_one server "$2" & run_one client "$2" & run_one mix "$2" & run_one none "$2" & wait
else
for trial in 1 2; do
- for arm in server client none; do
+ for arm in server client mix none; do
run_one $arm $trial
done
done
diff --git a/src/agent_compact.zig b/src/agent_compact.zig
index b14c2de3..8f2ec42a 100644
--- a/src/agent_compact.zig
+++ b/src/agent_compact.zig
@@ -19,6 +19,7 @@ const handoff_note = @import("compact_handoff_note.zig"); // #411: both halves o
const peer_context = @import("peer_context.zig"); // ADR 0004: peer injects are not a human turn
const compact_note_glue = @import("compact_note_glue.zig"); // #391
const server_compact = @import("agent_server_compact.zig"); // #compact-ab telemetry
+const compact_mix = @import("compact_mix.zig"); // GRAFF_COMPACT_MIX: two-pass extract+synthesis arm
const messages_mod = @import("messages.zig");
const textMessage = messages_mod.textMessage;
@@ -191,7 +192,7 @@ pub fn compact(self: *Agent) anyerror!usize {
}
};
- try self.messages.append(try textMessage(compact_arena, "user", try handoff_note.summaryRequest(compact_arena, self)));
+ try self.messages.append(try textMessage(compact_arena, "user", try compact_mix.summaryRequest(self, compact_arena))); // mix off: handoff_note's request
// #174: establish the synthetic summary turn before pruning Responses
// reasoning. An active tool loop's reasoning is newer than the real user
// turn and must remain while that loop is in flight, but it becomes prior-
@@ -214,7 +215,7 @@ pub fn compact(self: *Agent) anyerror!usize {
defer self.stream_quiet = was_quiet;
defer self.compaction_request = was_compaction_request;
defer self.message_mutation_arena = was_message_mutation_arena;
- const root = try self.request(@import("cache_fork.zig").tools(self, fork));
+ const root = try compact_mix.synthRequest(self, @import("cache_fork.zig").tools(self, fork));
progress.end(self);
// Any complete transport response proves the previous opaque failure was
// transient/non-wedging, even when its summary text is empty or truncated.
diff --git a/src/agent_request_body_responses.zig b/src/agent_request_body_responses.zig
index 6bbd5b2b..c6155ba3 100644
--- a/src/agent_request_body_responses.zig
+++ b/src/agent_request_body_responses.zig
@@ -97,8 +97,9 @@ pub fn write(self: *Agent, s: *std.json.Stringify, tools: ?[]const u8, force_too
try s.beginObject();
try s.objectField("effort");
// #379: compaction summaries run at low — a high-effort reasoner can
- // complete with only reasoning items and zero output text.
- const effort = if ((self.compaction_request or self.server_compaction_request) and !@import("effort_route.zig").mimoRoute(self.provider.id, self.provider.model)) "low" else @import("effort_route.zig").wireEffort(self.provider.id, self.provider.model, @tagName(self.reasoning));
+ // complete with only reasoning items and zero output text. GRAFF_COMPACT_MIX's
+ // synthesis pass runs at session effort (compact_mix.zig); the guards still apply.
+ const effort = if ((self.compaction_request or self.server_compaction_request) and !@import("compact_mix.zig").synthSessionEffort() and !@import("effort_route.zig").mimoRoute(self.provider.id, self.provider.model)) "low" else @import("effort_route.zig").wireEffort(self.provider.id, self.provider.model, @tagName(self.reasoning));
try s.write(effort);
// summary:auto streams reasoning_summary_text.delta (reasoningDelta already parses it); without it silent reasoning emits NO frames — the stall watchdog cannot tell thinking from a dead socket.
// ADR 0231: nobody watches a -p or piped session's reasoning, and at low effort it stays short, so it goes without.
diff --git a/src/compact_mix.zig b/src/compact_mix.zig
new file mode 100644
index 00000000..b2483d10
--- /dev/null
+++ b/src/compact_mix.zig
@@ -0,0 +1,216 @@
+//! GRAFF_COMPACT_MIX — two-pass "mixture" compaction, experimental arm for the
+//! #compact-ab comparison (`evals/compact_ab`).
+//!
+//! The measured failure of single-pass compaction is NOT prose quality: it is
+//! state loss — the exact line in flight, the approach already ruled out, the
+//! identifier the next turn needs verbatim (see compact_note.zig #391 and the
+//! compact_ab README's retry-loop observation). A single summary request is
+//! asked to both DISCOVER that state and narrate it; a summarizer optimizes for
+//! a readable account and drops exactly the details a working agent cannot
+//! cheaply re-derive.
+//!
+//! The mixture separates the two jobs across two passes with different effort:
+//!
+//! PASS 1 — EXTRACT (pinned low effort, "Jev-low"): pull a terse state ledger
+//! out of the history — decisions, dead ends (with WHY), in-flight identifiers
+//! and numbers VERBATIM, the next step, open user asks. Mechanical work; a
+//! cheap pass is the right tool and low effort cannot "complete with only
+//! reasoning items" (#379's failure) because the ledger is the output.
+//!
+//! PASS 2 — SYNTHESIS (session effort, i.e. whatever /effort or the jev_effort
+//! tool selected): the normal handoff summary, with the ledger injected as a
+//! checklist the summary must carry. The synthesis request is otherwise the
+//! exact request compact() sends today, so the #379 completeness/empty checks
+//! and the transactional history restore keep working unchanged.
+//!
+//! Any extract failure (transport, empty, incomplete) is a NAMED SKIP: the
+//! ledger is null and pass 2 runs the byte-identical single-pass summary
+//! request. The arm can therefore never be worse than the baseline in failure
+//! behavior — only in cost (one extra low-effort call per compaction).
+//!
+//! Effort routing detail: the Responses body writer forces `low` on compaction
+//! requests (agent_request_body_responses.zig, #379). During pass 1 that is
+//! exactly what we want. During pass 2 `synthSessionEffort()` lifts the force
+//! so the session's Jev-selected effort applies; the empty/incomplete guards
+//! remain and the compact_ab comparison prices the trade.
+//!
+//! ADR 0002 / standing rule: this is a CLIENT summarizer path. grok/xAI
+//! compaction stays on it — never xAI's first-party compact endpoint.
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const Agent = @import("agent.zig").Agent;
+const messages_mod = @import("messages.zig");
+const title_mod = @import("title.zig");
+const util = @import("util.zig");
+
+/// Which mixture pass owns the current request. Set around each internal
+/// request by extractLedger() / compact(); `.none` is the steady state.
+pub const Pass = enum { none, extract, synth };
+
+pub var g_enabled: bool = false; // GRAFF_COMPACT_MIX (session_settings.applyEnvKnobs)
+pub var g_pass: Pass = .none;
+
+pub fn enabled() bool {
+ return g_enabled;
+}
+
+pub fn inExtract() bool {
+ return g_pass == .extract;
+}
+
+/// True when the Responses body writer should NOT force low effort: the
+/// synthesis pass of an enabled mixture runs at the session's effort.
+pub fn synthSessionEffort() bool {
+ return g_enabled and g_pass == .synth;
+}
+
+/// Ledger ceiling (~500 tokens): a compaction runs where context is scarce, so
+/// the ledger is a checklist, not a second summary.
+pub const max_ledger_bytes: usize = 2048;
+
+pub fn capLedger(text: []const u8) []const u8 {
+ return util.utf8Prefix(text, max_ledger_bytes);
+}
+
+pub fn extractPrompt() []const u8 {
+ return
+ \\[state-extraction pass — internal, no tools, output the ledger ONLY]
+ \\Extract a terse STATE LEDGER from the conversation above. Answer with only
+ \\the ledger, exactly these five lines, one section per line, no preamble:
+ \\DECISIONS: what was decided and why
+ \\DEAD ENDS: approaches tried and ruled out, each with the reason
+ \\IN FLIGHT: identifiers, numbers, file paths and exact lines currently in use — VERBATIM
+ \\NEXT: the immediate next step
+ \\USER ASK: explicit user requests still open
+ \\Copy every identifier, number and path character-for-character. Use "-" for
+ \\an empty section. Never narrate; this is state, not a summary.
+ ;
+}
+
+/// The synthesis request: today's summary request, plus the ledger as a
+/// checklist the summary must carry. With a null ledger the base is returned
+/// byte-identical, so the fallback path is exactly the single-pass request.
+pub fn composeSummary(arena: Allocator, base: []const u8, ledger: ?[]const u8) ![]const u8 {
+ const l = ledger orelse return base;
+ return std.fmt.allocPrint(arena,
+ \\{s}
+ \\
+ \\[state ledger, extracted from the same conversation by the preceding
+ \\low-effort pass. Carry it into the summary as a checklist, not as text to
+ \\paraphrase: every DEAD ENDS entry must survive as a ruled-out approach, IN
+ \\FLIGHT values must survive character-for-character, and NEXT / USER ASK
+ \\must be reflected in the unfinished-work section. Sections with "-" add
+ \\nothing.]
+ \\
+ \\{s}
+ , .{ base, l });
+}
+
+/// The summary request compact() sends. Off, it is the single-pass request;
+/// on, pass 1 runs first (its exchange never enters history) and pass 2 gets
+/// the ledger woven in.
+pub fn summaryRequest(self: *Agent, arena: Allocator) ![]const u8 {
+ const ledger: ?[]const u8 = if (g_enabled) try extractLedger(self, arena) else null;
+ return composeSummary(arena, try @import("compact_handoff_note.zig").summaryRequest(arena, self), ledger);
+}
+
+/// PASS 2 is compact()'s own summary request, marked so the Responses body
+/// writer runs it at session (Jev) effort when the arm is on.
+pub fn synthRequest(self: *Agent, tools: ?[]const u8) !std.json.ObjectMap {
+ g_pass = .synth;
+ defer g_pass = .none;
+ return self.request(tools);
+}
+
+/// PASS 1: run the extract request over the pending summary window
+/// (`self.messages` already holds it). Best-effort by contract — every failure
+/// is a named skip returning null, and the caller falls back to the
+/// byte-identical single-pass summary. The extract exchange (prompt + any
+/// reply request() appended) is popped before returning, so the history pass 2
+/// sees is unchanged.
+pub fn extractLedger(self: *Agent, arena: Allocator) !?[]const u8 {
+ const agent_compact = @import("agent_compact.zig");
+ const mark = self.messages.items.len;
+ const was_quiet = self.stream_quiet;
+ const was_compaction_request = self.compaction_request;
+ const was_mutation_arena = self.message_mutation_arena;
+ const was_reasoning = self.reasoning;
+ defer {
+ self.stream_quiet = was_quiet;
+ self.compaction_request = was_compaction_request;
+ self.message_mutation_arena = was_mutation_arena;
+ self.reasoning = was_reasoning;
+ g_pass = .none;
+ self.messages.shrinkRetainingCapacity(mark); // scaffolding never enters history
+ }
+ try self.messages.append(try messages_mod.textMessage(arena, "user", extractPrompt()));
+ // The extract prompt is the turn boundary for the same reasoning prune the
+ // synthesis pass performs; running it here makes the later call a no-op.
+ _ = agent_compact.dropPriorTurnReasoning(self);
+ self.stream_quiet = true;
+ self.compaction_request = true;
+ self.message_mutation_arena = arena;
+ self.reasoning = .low; // "Jev-low": mechanical extraction, chat and Responses wires alike
+ g_pass = .extract;
+ // A cache fork (ADR 0220) sends the conversation's own tools so this pass
+ // reads the cached prefix too; otherwise none, like the summary request.
+ const root = self.request(@import("cache_fork.zig").tools(self, @import("cache_fork.zig").shares())) catch return null;
+ if (!agent_compact.summaryResponseComplete(self, root)) return null;
+ const text = std.mem.trim(u8, title_mod.assistantText(self.provider.kind, root), " \t\r\n");
+ if (text.len == 0) return null;
+ return try arena.dupe(u8, capLedger(text));
+}
+
+test "composeSummary with no ledger is byte-identical to the single-pass request" {
+ const a = std.testing.allocator;
+ const base = "summarize the work";
+ try std.testing.expectEqualStrings(base, try composeSummary(a, base, null));
+}
+
+test "composeSummary weaves the ledger in as a checklist" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const out = try composeSummary(a, "BASE", "DECISIONS: keep the pin");
+ try std.testing.expect(std.mem.indexOf(u8, out, "BASE") != null);
+ try std.testing.expect(std.mem.indexOf(u8, out, "DECISIONS: keep the pin") != null);
+ try std.testing.expect(std.mem.indexOf(u8, out, "DEAD ENDS") != null); // the checklist contract
+ try std.testing.expect(std.mem.indexOf(u8, out, "character-for-character") != null);
+}
+
+test "capLedger bounds the ledger at max_ledger_bytes on a UTF-8 boundary" {
+ const small = capLedger("short");
+ try std.testing.expectEqualStrings("short", small);
+ var big: [max_ledger_bytes + 64]u8 = undefined;
+ @memset(&big, 'x');
+ try std.testing.expect(capLedger(&big).len <= max_ledger_bytes);
+}
+
+test "extractPrompt names all five ledger sections and demands verbatim values" {
+ const p = extractPrompt();
+ for ([_][]const u8{ "DECISIONS:", "DEAD ENDS:", "IN FLIGHT:", "NEXT:", "USER ASK:" }) |section|
+ try std.testing.expect(std.mem.indexOf(u8, p, section) != null);
+ try std.testing.expect(std.mem.indexOf(u8, p, "VERBATIM") != null);
+ try std.testing.expect(std.mem.indexOf(u8, p, "no tools") != null);
+}
+
+test "synthSessionEffort lifts forced-low only for a mixture synthesis pass" {
+ const saved_enabled = g_enabled;
+ const saved_pass = g_pass;
+ defer {
+ g_enabled = saved_enabled;
+ g_pass = saved_pass;
+ }
+ g_enabled = false;
+ g_pass = .synth;
+ try std.testing.expect(!synthSessionEffort()); // flag off: behavior unchanged
+ g_enabled = true;
+ g_pass = .none;
+ try std.testing.expect(!synthSessionEffort());
+ g_pass = .extract;
+ try std.testing.expect(!synthSessionEffort()); // pass 1 stays low
+ try std.testing.expect(inExtract());
+ g_pass = .synth;
+ try std.testing.expect(synthSessionEffort());
+}
diff --git a/src/main.zig b/src/main.zig
index f27d22f0..8c8dcbf6 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -571,7 +571,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = @import("agent_gateway_retry.zig"); // #1019: flake vs overflow classification must stay reachable
_ = @import("agent_responses.zig"); // #1019: type:error frame message extraction
_ = @import("agent_server_compact.zig"); // server-side autocompact (codex Responses)
- _ = @import("compact_status.zig");
+ _ = .{ @import("compact_status.zig"), @import("compact_mix.zig") }; // compact status + GRAFF_COMPACT_MIX mixture arm
_ = @import("agent_request_search_tests.zig");
_ = @import("agent_ws_steer.zig");
_ = @import("agent_ws_signal.zig");
diff --git a/src/session_settings.zig b/src/session_settings.zig
index 38175aa0..2c278ff6 100644
--- a/src/session_settings.zig
+++ b/src/session_settings.zig
@@ -215,6 +215,12 @@ pub fn applyEnvKnobs(arena: Allocator, environ_map: anytype) !void {
const off = std.mem.eql(u8, v, "0") or std.ascii.eqlIgnoreCase(v, "false") or std.ascii.eqlIgnoreCase(v, "off");
server_compact.g_server_compact_override = !off;
}
+ // GRAFF_COMPACT_MIX=0/false/off keeps the single-pass summary; anything
+ // else arms the two-pass extract+synthesis arm (#compact-ab mix arm).
+ if (environ_map.get("GRAFF_COMPACT_MIX")) |v| {
+ const off = std.mem.eql(u8, v, "0") or std.ascii.eqlIgnoreCase(v, "false") or std.ascii.eqlIgnoreCase(v, "off");
+ @import("compact_mix.zig").g_enabled = !off;
+ }
// #502: xAI defaults to the Responses wire (api.x.ai/v1/responses) —
// first-party server compaction + WS turns. GRAFF_XAI_WIRE=chat (anything
// but "responses") moves it back to chat completions; unset keeps the default.
diff --git a/src/session_settings_tests.zig b/src/session_settings_tests.zig
index 7d2934b1..edd1a3ba 100644
--- a/src/session_settings_tests.zig
+++ b/src/session_settings_tests.zig
@@ -54,6 +54,7 @@ const knobs = [_]Knob{
.{ .name = "GRAFF_CONTEXT", .value = "123456" },
.{ .name = "GRAFF_TOOL_HANDLE_BYTES", .value = "8192" },
.{ .name = "GRAFF_COMPACT_PCT", .value = "55" },
+ .{ .name = "GRAFF_COMPACT_MIX", .value = "1" },
.{ .name = "GRAFF_WS_DEBUG", .value = "1" },
.{ .name = "GRAFF_WS_FORCE_FAIL_ONCE", .value = "1" },
.{ .name = "GRAFF_WS_FORCE_FAIL_COUNT", .value = "3" },
@@ -118,6 +119,7 @@ const Saved = struct {
stable_catalog: bool,
x_search: bool,
job_idle: job_idle.Policy,
+ compact_mix: bool,
fn capture() Saved {
return .{
@@ -150,6 +152,7 @@ const Saved = struct {
.stable_catalog = mcp_schema_gate.g_stable_catalog,
.x_search = @import("xai_hosted.zig").enabled,
.job_idle = job_idle.policy,
+ .compact_mix = @import("compact_mix.zig").g_enabled,
};
}
@@ -184,6 +187,7 @@ const Saved = struct {
mcp_schema_gate.g_stable_catalog = s.stable_catalog;
@import("xai_hosted.zig").enabled = s.x_search;
job_idle.policy = s.job_idle;
+ @import("compact_mix.zig").g_enabled = s.compact_mix;
}
};