Skip to content

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

Python

compaction: the client summary stays the default; gateway pruning is opt-in

justrachdabe5add2218
diff --git a/docs/adr/0260-clef-compaction-replaces-client-summary.md b/docs/adr/0260-clef-compaction-replaces-client-summary.md
new file mode 100644
index 00000000..b83fa842
--- /dev/null
+++ b/docs/adr/0260-clef-compaction-replaces-client-summary.md
@@ -0,0 +1,45 @@
+# 0260. Client-summary compaction goes through the gateway's Clef endpoint when eligible
+
+Status: accepted 2026-10-06; default superseded by 0261 (Clef stays opt-in, the client summary is the compactor)
+
+## Context
+
+`compact()` summarized history with the session model: one request asked to
+both discover working state and narrate it, and the summarizer optimized for
+a readable account — dropping the exact lines, ruled-out approaches, and
+identifiers the next turn needs verbatim (the retry-loop failure the
+`evals/compact_ab` comparison documents). The two-pass mixture
+(`GRAFF_COMPACT_MIX`) narrows that loss but still rewrites history as prose.
+
+The gateway already serves `POST /v1/compact`: Clef decision models score
+every tool call with keep/drop (`noul`) questions and prune only tool
+calls/results. Text messages stay verbatim and in order — nothing is
+rewritten. Measured on the gateway's fixtures: clef keep-recall 89%, probes
+100%, reduction ~21%.
+
+## Decision
+
+- `GRAFF_CLEF_COMPACT=1` arms the gateway path (default off until measured).
+ Eligible sessions are `codegraff`-provider with a credential; review turns
+ never compact. `agent_clef_compact.zig` translates wire history to the
+ gateway transcript shape, POSTs `/v1/compact` (model `clef-flash`, prune
+ mode), and applies the returned decisions by `tool_use_id`/`call_id`
+ (`drop_call` removes both halves, `drop_result` truncates the output).
+- It replaces ONLY the client summarizer: the hook sits at the top of
+ `compact()`, and every OpenAI-family server path (direct-OpenAI standalone
+ `/responses/compact`, Codex/ChatGPT in-stream directive, xAI explicit
+ endpoint, blob-anchored histories) never reaches it. Any gateway failure —
+ or a prune that removes nothing — falls through to the existing summary,
+ transactionally, so a broken endpoint can never wedge the session.
+- Privacy: the transcript (tool output included) is sent to the gateway's
+ hosted decision models. The knob is opt-in; enabling it is the
+ disclosure.
+
+## Consequences
+
+One extra gateway call per compaction when armed (input tokens at clef-flash
+rates, output free — far cheaper than a frontier summary). Unknown decision
+actions are applied as keep (safety-first, mirroring the gateway's drop bar).
+Revisit when the arm has production recall numbers against the summary
+baseline; the `#compact-ab` telemetry shape (`prune_items` vs
+`summary_chars`) fits a third arm unchanged.
diff --git a/docs/adr/0261-client-summary-stays-the-compactor.md b/docs/adr/0261-client-summary-stays-the-compactor.md
new file mode 100644
index 00000000..0d335a4d
--- /dev/null
+++ b/docs/adr/0261-client-summary-stays-the-compactor.md
@@ -0,0 +1,52 @@
+# 0261. The client summary stays the compactor; Clef pruning is opt-in
+
+Status: accepted 2026-10-07. Supersedes 0260's default.
+
+## Context
+
+0260 added a gateway path (`POST /v1/compact`, Clef keep/drop decisions over
+tool calls) ahead of the client summary in `compact()`, and the code shipped
+it default-on while the ADR said default-off. `evals/clef_exp` then measured
+five arms — Clef prune, client summary, two-pass mix, Clef-then-mix, and no
+compaction — across three hosted chat-wire models, plus an archive mode
+(`GRAFF_CLEF_ARCHIVE`) that stubs pruned outputs to session artifacts
+instead of deleting them, and a recall variant where facts exist only in
+deleted-after-read tool output.
+
+What it showed:
+
+- The client summary works. Each install shrank history by about a third;
+ an earlier reading that it "pin-degrades and never installs" misread
+ `compact_cut`'s `unresolved` trace field.
+- Clef rarely prunes. Most Clef-arm compactions were `clef_compact_noop`
+ followed by the summary fallback, so the arm paid for decision calls and
+ then ran the summary anyway. On the recall variant it pruned nothing, and
+ archive mode never engaged.
+- Answer quality did not separate the compacting arms in Clef's favor. On
+ the recall variant the summary arm scored highest of the compacting arms.
+- Graff already keeps a recoverable copy of every tool output: the session
+ transcript (#441). Models recovered "lost" facts by grepping it on every
+ arm, so archive mode adds a path, not data.
+- Not compacting stays cheapest; every rewrite busts the prompt cache.
+
+## Decision
+
+- `GRAFF_CLEF_COMPACT` defaults OFF (`agent_clef_compact.g_enabled = false`).
+ `compact()` uses the client summary; `GRAFF_CLEF_COMPACT=1` arms the
+ gateway path for experiments, with the same fall-through-to-summary on any
+ failure or noop. `GRAFF_CLEF_ARCHIVE=1` stays an experiment-only modifier.
+- The pre-compaction note-to-self (#391) is unchanged and stays visible: it
+ carries working state a summary drops across long sessions.
+- First-party Responses routes (direct API, gateway GPT models, the
+ ChatGPT-plan sign-in) compact only through the provider's own compaction
+ and never reach `compact()` — neither the summary nor Clef (ADR 0259). Any refactor
+ of `compactOrRecover` (e.g. the `agent_compact_recover.zig` split) must
+ keep the `serverOnly(provider)` branch that enforces this.
+
+## Consequences
+
+No gateway decision call, and no transcript sent to the gateway, on default
+compactions — which also retires 0260's missing disclosure notice. The Clef
+code stays for measurement. Revisit if a task shape shows the summary losing
+information that Clef keeps: the recall variant should block the session
+transcript first, since today it lets every arm recover pruned output.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 3e8e67e1..cabe9d2d 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -285,6 +285,8 @@ record only when you need the evidence or the edge cases.
| [0257](0257-a-slimmed-comment-list-names-its-issue.md) | A slimmed MCP comment list keeps the issue id its rows share (`{issue, n, latest_author}`), so parallel results name what they describe. |
| [0258](0258-gemini-chat-sends-repo-context-once.md) | On the Codegraff chat wire, Gemini root turns send the project instructions and layout as the conversation's first user message (ADR 0243's split), so the system prompt every request repeats no longer carries them. |
| [0259](0259-openai-routes-compact-only-server-side.md) | First-party Responses routes (direct API, Codegraff GPT, ChatGPT plan) compact only server-side: no client-summary fallback while the server arm is on. A compaction item's `encrypted_content` is metered at 16 bytes/token, not as text, so a blob-anchored history does not re-compact every step. |
+| [0260](0260-clef-compaction-replaces-client-summary.md) | `GRAFF_CLEF_COMPACT=1` routes client-summary compactions through the gateway's server-side `POST /v1/compact` (Clef decision-model pruning, text verbatim); OpenAI-family server paths are untouched and any failure falls back to the summary. |
+| [0261](0261-client-summary-stays-the-compactor.md) | The client summary stays the compactor: `GRAFF_CLEF_COMPACT` defaults off (Clef rarely pruned and mostly fell back to the summary in measurement); first-party Responses routes use only the provider's own compaction. Supersedes 0260's default. |
## When to write one
diff --git a/evals/clef_exp/README.md b/evals/clef_exp/README.md
new file mode 100644
index 00000000..e5fc502d
--- /dev/null
+++ b/evals/clef_exp/README.md
@@ -0,0 +1,148 @@
+# Clef compaction experiment: prune vs summary on deepseek-v4-flash
+
+Clone of the `evals/compact_ab` shape, aimed at the Clef gateway arm
+(`src/agent_clef_compact.zig`, `GRAFF_CLEF_COMPACT`). Question: on a chat-wire
+model where the old server arm is inert, which client-side strategy preserves
+audit recall best per dollar — Clef prune, classic summary, two-pass mix,
+Clef-then-mix, or nothing?
+
+## Run
+
+```bash
+python3 evals/clef_exp/gen_corpus.py # $CLEF_EXP_DIR/src (default /tmp/clef_exp)
+python3 evals/clef_exp/gen_turns.py # $CLEF_EXP_DIR/turns.txt (13 turns)
+bash evals/clef_exp/run_wave.sh wave 5 # one trial per arm in parallel
+python3 evals/clef_exp/score_wave.py # recall + wall + cost from traces
+```
+
+`GRAFF_BIN` overrides the binary (default `$HOME/codegraff/zig-out/bin/graff`).
+Cost comes from trace `usage` events priced per model row; see `score_wave.py`.
+
+## Arms
+
+| arm | env |
+|---|---|
+| clef | `GRAFF_CLEF_COMPACT=1 GRAFF_COMPACT_PCT=1` (default off, ADR 0261) |
+| client | `GRAFF_CLEF_COMPACT=0 GRAFF_COMPACT_PCT=1` |
+| mix | `GRAFF_CLEF_COMPACT=0 GRAFF_COMPACT_MIX=1 GRAFF_COMPACT_PCT=1` |
+| clefmix | `GRAFF_CLEF_COMPACT=1 GRAFF_COMPACT_MIX=1 GRAFF_COMPACT_PCT=1` |
+| clefarc | `GRAFF_CLEF_COMPACT=1 GRAFF_CLEF_ARCHIVE=1 GRAFF_COMPACT_PCT=1` |
+| none | `GRAFF_CLEF_COMPACT=0 GRAFF_COMPACT_PCT=100` |
+
+All arms also set `GRAFF_SERVER_COMPACT=0 GRAFF_TOOL_HANDLE_BYTES=1048576`.
+
+## Results (deepseek-v4-flash, 2 trials/arm, 2026-10-06)
+
+| run | score | clef prunes | wall | api calls | peak input | cost |
+|---|---|---|---|---|---|---|
+| none5 | 10/10 | — | 133s | 45 | 63K | $0.030 |
+| none6 | 10/10 | — | 115s | 52 | 67K | $0.032 |
+| clef5 | 10/10 | 1 | 501s | 153 | 31K | $0.185 |
+| clef6 | 10/10 | 0 | 716s | 177 | 33K | $0.274 |
+| client5 | 10/10 | — | 745s | 204 | 100K | $0.284 |
+| client6 | 10/10 | — | 329s | 117 | 51K | $0.111 |
+| mix5 | 10/10 | — | 737s | 209 | 40K | $0.251 |
+| mix6 | 10/10 | — | 625s | 188 | 26K | $0.225 |
+| clefmix5 | 10/10 | 5 | 775s | 209 | 23K | $0.266 |
+| clefmix6 | 10/10 | 2 | 836s | 196 | 24K | $0.309 |
+
+Recall tied at 10/10 everywhere at this scale — the task does not separate
+recall, only cost and history control.
+
+Read: compacting at all costs 4–9x more than not compacting
+(cache-read history at $0.006/1M is nearly free, and every rewrite busts
+the cache), matching the earlier `compact_ab` finding on gpt-5.6-sol that
+compaction is insurance, not a free lunch. Among compacting arms cost is
+comparable; `clefmix` prunes most (5+2) but costs the most.
+
+**Correction (2026-10-07):** an earlier version of this section said client
+summaries "pin-degrade" and almost never install. Wrong: `compact_cut`'s
+`unresolved:true` is a trace field, and the summary proceeds unless
+`pinDegrade` returns `.silent`/`.announce` (`src/agent_compact.zig`). Measured
+on the main-agent `usage` line before vs after each `prefix_bust:"compact"`:
+
+| arm | compactions | median shrink | shrank >5% |
+|---|---|---|---|
+| client summary | 78 | 32% | 55 |
+| clef (all models) | 112 | 37% | 92 |
+| clefarc (wave 8) | 7 | 41% | 5 |
+
+Most clef-arm compactions are the summary *fallback* after
+`clef_compact_noop`, so the clef row is mostly the summary too; Clef's own
+prunes installed only a handful of times. The peak-input gap above (23–33K vs
+51–100K) is single-trial noise — GLM and Kimi reverse it. The summary is a
+working ~1/3 compactor; Clef has not beaten it here.
+
+Caveats: wave-1 exposed and fixed a real bug — partial `drop_call` on a
+multi-call assistant message orphaned surviving results and wedged the
+session in a gateway-400 loop (`applyDecisions` now degrades partial drops
+to truncation, with unit tests on both wires). `clef5`/`clef6`/`mix6` wrote
+a correct answer.md but exited without DONE (tail showed a mid-reply
+compaction), so `done` is not a reliable signal. Single-prompt runs never
+compact twice (compact_cut pin_degrade); the 13-turn shape is load-bearing.
+
+## Cross-model spot-checks (clef/client/none trio, same 13-turn shape)
+
+| run | score | clef prunes | wall | peak input | cost |
+|---|---|---|---|---|---|
+| glm none | 10/10 | — | 693s | 70K | $0.041 |
+| glm clef | 10/10 | 0 | 747s | 77K | $0.062 |
+| glm client | 10/10 | — | 859s | 42K | $0.070 |
+| kimi none | 10/10 | — | 558s | 99K | $0.348 |
+| kimi clef | 10/10 | 1 | 642s | 97K | $0.402 |
+| kimi client | 10/10 | — | 864s | 66K | $0.474 |
+
+Same ordering on both models: none cheapest, clef in the middle, client
+most expensive — though client summaries DID install (10 of 16 attempts on
+kimi-client, 12 of 14 on glm-client; see the correction above) and held
+peak input lowest on both. Two model-behavior notes: (1) costs cluster on GLM
+because the gateway barely cache-reads it ($0.04–0.07 across arms). (2) Kimi at
+$0.95/4 per 1M makes everything ~10x deepseek in absolute terms, but the
+relative ordering holds. Driver takes `CLEF_MODEL=` for any codegraff alias
+(`trio` mode runs clef/client/none); scorer prices each trace line at its
+own model row.
+
+## Archive vs delete (`arc` mode, deepseek-v4-flash, wave 8)
+
+| run | score | clef prunes | peak input | freed | archive reads | cost |
+|---|---|---|---|---|---|---|
+| none8 | 10/10 | — | 90K | — | — | $0.063 |
+| clef8 (delete) | 10/10 | 0 (10 noops → summary) | 53K | 0 | — | $0.070 |
+| clefarc8 (archive) | 10/10 | 1 (7 outputs archived) | 76K | 9.9KB | 0 | $0.069 |
+
+Archive mode works end to end (artifacts written, pairing intact, no wedge)
+and costs the same, but on this task it barely matters: Clef archived small
+1.6–2.6KB outputs and the model never went back for them. This task cannot
+separate the arms — every answer value is restated verbatim in assistant
+text, which nothing prunes. See the recall variant below.
+
+## Recall variant (`gen_recall.py`, `recall` mode, deepseek-v4-flash, wave 1)
+
+Facts live only in tool output: each turn is `cat src/logs/run-NN.log && rm
+…` with a reply of `OK`, then filler, then 10 questions (7 from logs 1–5,
+3 controls from logs 3/7/8). Logs are ~20KB, under the per-output cap, so
+the #409 send-time spill never fires.
+
+```bash
+CLEF_EXP_DIR=/tmp/clef_recall python3 evals/clef_exp/gen_recall.py
+CLEF_EXP_DIR=/tmp/clef_recall bash evals/clef_exp/run_wave.sh recall 1
+CLEF_EXP_DIR=/tmp/clef_recall python3 evals/clef_exp/score_wave.py
+```
+
+| run | score | clef prunes | peak input | cost |
+|---|---|---|---|---|
+| none1 | 10/10 | — | 102K | $0.047 |
+| client1 | 9/10 | — | 63K | $0.120 |
+| clef1 | 4/10 | 0 (16 noops → summary) | 55K | $0.089 |
+| clefarc1 | 3/10 | 0 (27 noops → summary) | 21K | $0.127 |
+
+Read: Clef pruned nothing on any arm, so every compaction was the summary
+fallback and archive mode never engaged — the Clef arms paid for decision
+calls that changed nothing. The spread among compacting arms is how hard
+the final turn dug, not what compaction kept: client and clef both recovered
+values by grepping the session's own `.graff/sessions/*.transcript.jsonl`
+(#441), which keeps every tool output whatever compaction does (clef1's grep
+returned two correct values it then reported UNKNOWN). client1's one miss is
+a log the model refused to run. Graff already has a recoverable archive for
+every arm — the transcript — so Clef's archive stub adds a path, not data.
+Outcome: ADR 0261, the client summary stays the compactor; Clef is opt-in.
diff --git a/evals/clef_exp/gen_corpus.py b/evals/clef_exp/gen_corpus.py
new file mode 100644
index 00000000..036b17a5
--- /dev/null
+++ b/evals/clef_exp/gen_corpus.py
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Generate the clef-exp corpus into $CLEF_EXP_DIR/src (default /tmp/clef_exp).
+
+Scaled-up clone of evals/compact_ab/gen_compact_bench.py: the deepseek-v4-flash
+window is 1M and the forced threshold is GRAFF_COMPACT_PCT=1 -> 10k tokens.
+Six files x ~80KB each; with the 1MB handle threshold every read lands inline,
+and the send-time 40KB per-output spill plus assistant verbatim quotes (see
+gen_turns.py) accumulate history deterministically past the threshold.
+
+Otherwise identical shape to compact_ab: planted audit-anchor constants
+mid-file (12 total, 10 asked), questions spanning all six files so
+post-compaction recall of EARLY files is what separates the arms.
+"""
+import json, os, random
+
+BASE = os.environ.get("CLEF_EXP_DIR", "/tmp/clef_exp")
+SRC = os.path.join(BASE, "src")
+rng = random.Random(20261006)
+
+FILES = ["alpha", "beta", "gamma", "delta", "epsilon", "foxtrot"]
+WORDS = ("meridian harlow pistil cinder vortex lattice ember quorum "
+ "solace thresh welkin bramble copse falcon garnet hollow "
+ "indigo jasper kindle lantern marrow numen obsidian palisade "
+ "tundra umbra vale wistful xenon yarrow zephyr acorn birch "
+ "cedar drift elm fern grove heath iris juniper kelp larch").split()
+
+def filler_fn(name, i):
+ acc = rng.randint(2, 9)
+ lines = [f"fn {name}_{i:03d}(ledger: *Ledger, entry: Entry) !u64 {{"]
+ lines.append(f" var acc: u64 = entry.checksum ^ {rng.randint(100, 999)};")
+ for j in range(rng.randint(3, 6)):
+ op = rng.choice(["+", "-", "^", "*"])
+ lines.append(f" acc = acc {op} (@as(u64, {rng.randint(3, 977)}) +% ledger.salt[{j} % 8]);")
+ lines.append(f" if (acc % {rng.randint(3, 17)} == 0) acc +%= {rng.randint(11, 555)};")
+ lines.append(f" return acc *% {acc};")
+ lines.append("}")
+ return "\n".join(lines)
+
+facts = {} # const name -> value (string form)
+used = set()
+
+def plant(lines, fname):
+ word = rng.choice([w for w in WORDS if w not in used])
+ used.add(word)
+ cname = f"{word.upper()}_{fname.upper()[:6]}"
+ if rng.random() < 0.5:
+ val = str(rng.randint(10_000, 99_999))
+ decl = f'pub const {cname}: u64 = {val}; // audit anchor'
+ else:
+ val = f"{word}-{rng.randint(100, 999)}"
+ decl = f'pub const {cname} = "{val}"; // audit anchor'
+ pos = rng.randint(len(lines) // 4, 3 * len(lines) // 4)
+ lines.insert(pos, decl)
+ facts[cname] = val
+
+os.makedirs(SRC, exist_ok=True)
+for fidx, fname in enumerate(FILES):
+ lines = [
+ f"//! {fname}.zig — archival ledger segment {fidx} of the benchmark codebase.",
+ "",
+ "const std = @import(\"std\");",
+ "const Ledger = @import(\"ledger.zig\").Ledger;",
+ "const Entry = @import(\"ledger.zig\").Entry;",
+ "",
+ ]
+ for i in range(150): # ~1600+ lines of filler per file (~85KB each)
+ lines.append(filler_fn(fname, i))
+ lines.append("")
+ plant(lines, fname)
+ plant(lines, fname) # two facts per file, 12 total
+ with open(os.path.join(SRC, f"{fname}.zig"), "w") as f:
+ f.write("\n".join(lines) + "\n")
+
+with open(os.path.join(SRC, "ledger.zig"), "w") as f:
+ f.write("//! shared types\n\npub const Ledger = struct { salt: [8]u64 };\n"
+ "pub const Entry = struct { checksum: u64, route: u32 };\n")
+
+with open(os.path.join(BASE, "facts.json"), "w") as f:
+ json.dump(facts, f, indent=2)
+
+items = list(facts.items())
+questions = []
+for qi, fi in enumerate(range(10), 1):
+ cname, _ = items[fi]
+ ffile = next(fname for fname in FILES if fname.upper()[:6] == cname.split("_")[-1])
+ questions.append((qi, cname, ffile))
+
+with open(os.path.join(BASE, "questions.json"), "w") as f:
+ json.dump([{"q": q, "const": c, "file": fn, "expect": facts[c]} for q, c, fn in questions], f, indent=2)
+
+total = sum(os.path.getsize(os.path.join(SRC, fn)) for fn in os.listdir(SRC))
+print(f"generated {len(os.listdir(SRC))} files, {total/1024:.0f} KB total, {len(facts)} facts, 10 questions")
diff --git a/evals/clef_exp/gen_recall.py b/evals/clef_exp/gen_recall.py
new file mode 100644
index 00000000..b5c4ce92
--- /dev/null
+++ b/evals/clef_exp/gen_recall.py
@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Recall variant: facts live ONLY in tool output, and the source is gone.
+
+The main task (gen_corpus.py + gen_turns.py) ties at 10/10 on every arm
+because each turn restates the anchor values in assistant text, which
+nothing prunes. Here each read turn is `cat src/logs/run-NN.log && rm ...` with a
+reply of exactly "OK": the facts exist only in that one tool result, and
+re-running the tool cannot recover them. After the reads, filler turns
+push history over the threshold again, then the last turn asks about facts
+from every log (early logs are the ones compaction should have touched).
+
+What can still answer: the live tool result (none, or a kept output), the
+summary text (client / clef fallback), the #391 pre-compaction note, or an
+archived artifact (clefarc). Delete-mode drops have nothing to fall back on.
+
+Each log stays well under the 40KB per-output cap so the send-time #409
+spill never fires — otherwise every arm would get an artifact path for free.
+
+Writes $CLEF_EXP_DIR (default /tmp/clef_recall): src/logs/*.log,
+questions.json, facts.json, turns.txt. Run with
+`CLEF_EXP_DIR=/tmp/clef_recall bash evals/clef_exp/run_wave.sh recall N`.
+"""
+import json, os, random
+
+BASE = os.environ.get("CLEF_EXP_DIR", "/tmp/clef_recall")
+LOGS = os.path.join(BASE, "src", "logs")
+rng = random.Random(20261007)
+N_LOGS = 8
+LINES = 170 # ~20KB per log, under the 40KB per-output cap
+
+SVCS = ["ledger", "billing", "auth", "router", "search", "notify", "export", "queue"]
+LEVELS = ["INFO"] * 8 + ["DEBUG"] * 3 + ["WARN"]
+OWNERS = ("harlow pistil cinder vortex lattice ember quorum solace welkin "
+ "bramble falcon garnet jasper kindle marrow obsidian").split()
+
+def rid():
+ return "".join(rng.choice("abcdef0123456789") for _ in range(12))
+
+def noise(ts, svc):
+ lvl = rng.choice(LEVELS)
+ return (f"2026-10-06T{ts // 3600:02d}:{ts // 60 % 60:02d}:{ts % 60:02d}Z {lvl:<5} "
+ f"svc={svc} req={rid()} route=/v{rng.randint(1, 3)}/{rng.choice(SVCS)} "
+ f"status={rng.choice([200, 200, 200, 201, 204, 304, 404, 429, 500])} "
+ f"latency={rng.randint(2, 900)}ms bytes={rng.randint(80, 90000)} "
+ f"shard={rng.randint(0, 63)} retry={rng.randint(0, 3)}")
+
+# Two kinds of planted fact per log: an incident id + owner (one line) and a
+# rollback token (another line). Values are unguessable and appear once.
+facts, questions = {}, []
+os.makedirs(LOGS, exist_ok=True)
+for i in range(1, N_LOGS + 1):
+ name = f"run-{i:02d}.log"
+ svc = SVCS[i - 1]
+ ts = 3600 * (i + 1)
+ lines = []
+ for _ in range(LINES):
+ ts += rng.randint(1, 9)
+ lines.append(noise(ts, svc))
+ inc = f"INC-{rng.randint(10000, 99999)}"
+ owner = rng.choice(OWNERS)
+ tok = f"rbk-{rng.choice('kqzxvw')}{rng.randint(100, 999)}-{rng.randint(1000, 9999)}"
+ a, b = sorted(rng.sample(range(LINES // 5, 4 * LINES // 5), 2))
+ lines[a] = lines[a].split(" svc=")[0].replace("INFO ", "WARN ").replace("DEBUG", "WARN ") + \
+ f" svc={svc} incident opened id={inc} owner={owner} cause=shard-skew"
+ lines[b] = lines[b].split(" svc=")[0] + f" svc={svc} rollback token issued token={tok} scope=shard-{rng.randint(0, 63)}"
+ with open(os.path.join(LOGS, name), "w") as f:
+ f.write("\n".join(lines) + "\n")
+ facts[f"{name}:incident"] = inc
+ facts[f"{name}:token"] = tok
+
+# 10 questions: incident ids from logs 1-5 (early: compacted away) and
+# rollback tokens from logs 1-3 and 7-8 (7-8 are recent: a control).
+plan = [(i, "incident") for i in (1, 2, 3, 4, 5)] + [(i, "token") for i in (1, 2, 3, 7, 8)]
+for q, (i, kind) in enumerate(plan, 1):
+ name = f"run-{i:02d}.log"
+ what = "incident id opened" if kind == "incident" else "rollback token issued"
+ questions.append({"q": q, "const": what, "file": name, "expect": facts[f"{name}:{kind}"]})
+
+with open(os.path.join(BASE, "facts.json"), "w") as f:
+ json.dump(facts, f, indent=2)
+with open(os.path.join(BASE, "questions.json"), "w") as f:
+ json.dump(questions, f, indent=2)
+
+turns = []
+for i in range(1, N_LOGS + 1):
+ name = f"src/logs/run-{i:02d}.log"
+ turns.append(
+ f"Shift handover, log {i} of {N_LOGS}. Run exactly this one shell command and nothing else: "
+ f"cat {name} && rm {name} . The log is one-shot (it is deleted after reading, that is expected). "
+ "Do not summarize it, do not take notes, do not write any file. Reply with exactly: OK"
+ )
+for k in range(3): # filler: grow history past the threshold after the last read
+ turns.append(
+ "Unrelated warm-up, no tools: write a 400-word plain-prose explanation of how "
+ f"{['exponential backoff', 'consistent hashing', 'write-ahead logging'][k]} works. "
+ "Do not mention the logs."
+ )
+skel = " ".join(f"Q{q['q']}: <value>" for q in questions)
+qlist = " ".join(f"Q{q['q']}: the {q['const']} in {q['file']}?" for q in questions)
+turns.append(
+ "The logs are deleted and cannot be re-run. Answer from what you saw earlier in this session "
+ "(you may read any file this session itself saved, but src/logs/ is gone). "
+ f"Write answer.md with EXACTLY 10 lines, <value> replaced by the exact value, or UNKNOWN if you "
+ f"no longer have it — do not guess. No prose, no fences. Lines: {skel} Questions: {qlist} Then reply DONE."
+)
+with open(os.path.join(BASE, "turns.txt"), "w") as f:
+ f.write("\n".join(turns) + "\n")
+
+sizes = [os.path.getsize(os.path.join(LOGS, n)) for n in sorted(os.listdir(LOGS))]
+print(f"{N_LOGS} logs, {min(sizes)//1024}-{max(sizes)//1024}KB each, {len(questions)} questions, {len(turns)} turns -> {BASE}")
diff --git a/evals/clef_exp/gen_turns.py b/evals/clef_exp/gen_turns.py
new file mode 100644
index 00000000..6694a96a
--- /dev/null
+++ b/evals/clef_exp/gen_turns.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Generate $CLEF_EXP_DIR/turns.txt: 13 single-line turns for one session.
+
+History growth comes from ASSISTANT text, which is never spilled and never
+pruned by Clef (text stays verbatim — only tool calls/results are prune
+candidates). Each of the 6 read turns demands the full verbatim text of the
+3 functions before AND after each of the 2 anchors (~12 functions x ~700B
+~= 8-10KB of reply text per turn). The model is pre-authorized to copy file
+content verbatim (without it, it negotiates instead of complying).
+
+This sharpens the experiment: the quoted functions are exactly what
+client-summary rewrites as prose versus what Clef keeps verbatim. Recall
+of the anchor VALUES after several compactions is the score.
+"""
+import json, os
+
+BASE = os.environ.get("CLEF_EXP_DIR", "/tmp/clef_exp")
+FILES = ["alpha", "beta", "gamma", "delta", "epsilon", "foxtrot"]
+qs = json.load(open(os.path.join(BASE, "questions.json")))
+skel = " ".join("Q%d: <value>" % q["q"] for q in qs)
+qlist = " ".join("Q%d: value of %s in src/%s.zig?" % (q["q"], q["const"], q["file"]) for q in qs)
+AUTH = ("You are pre-authorized to copy file content verbatim into your "
+ "replies — this IS the task. Do not ask for confirmation, just do it. ")
+
+turns = []
+for f in FILES:
+ turns.append(
+ AUTH + "Read src/%s.zig with EXACTLY ONE read_file call (no ranges, no shell cat, no grep). "
+ "Find the two audit-anchor constants. Reply with: "
+ "(1) each anchor's exact name, exact value, and line number; "
+ "(2) the FULL verbatim text of the 3 functions immediately before AND the 3 functions immediately after EACH anchor "
+ "(12 function bodies total, copied character-for-character, each with its line range). "
+ "Do not summarize or elide the function bodies." % f
+ )
+turns.append(
+ AUTH + "Write answer.md with EXACTLY 10 lines, <value> replaced by the exact value from your earlier reads. "
+ "No prose, no fences, no extra lines. Lines: %s "
+ "Questions: %s "
+ "The two foxtrot anchors are decoys, answer only Q1-Q10. Integers bare, strings WITH quotes. Then reply DONE." % (skel, qlist)
+)
+
+with open(os.path.join(BASE, "turns.txt"), "w") as fh:
+ fh.write("\n".join(turns) + "\n")
+print("%d turns written" % len(turns))
diff --git a/evals/clef_exp/run_wave.sh b/evals/clef_exp/run_wave.sh
new file mode 100755
index 00000000..fc33e66e
--- /dev/null
+++ b/evals/clef_exp/run_wave.sh
@@ -0,0 +1,74 @@
+#!/bin/bash
+# Clef compaction experiment driver: 5 arms x N trials on deepseek-v4-flash
+# via the codegraff gateway at a forced-low compaction threshold (10k tokens,
+# GRAFF_COMPACT_PCT=1 on the 1M window). Shape cloned from evals/compact_ab.
+#
+# Each run is ONE session fed 13 turns on stdin (see gen_turns.py): 6 files x
+# (anchor turn + verbatim-context turn), then the answer turn. Multi-turn is
+# load-bearing: a single-prompt tool loop never compacts more than once (the
+# unresolved opening user message pins history via compact_cut pin_degrade),
+# while the between-turns gate compacts every turn over threshold.
+#
+# Corpus + turns live in $B (default /tmp/clef_exp); generate with
+# gen_corpus.py then gen_turns.py. GRAFF_TOOL_HANDLE_BYTES=1MB keeps every
+# read inline (no handle paging), so per-turn 40KB send-time stubs plus
+# assistant verbatim quotes accumulate history deterministically.
+#
+# Arms (deepseek is chat-wire, so the old server arm is inert here):
+# clef : gateway /v1/compact prune (GRAFF_CLEF_COMPACT=1; default off, ADR 0261)
+# client : classic single-pass summary (GRAFF_CLEF_COMPACT=0)
+# mix : two-pass extract+synthesis summary (GRAFF_COMPACT_MIX=1 + CLEF=0)
+# clefmix: clef prune, summary fallback WITH mix (both knobs on)
+# clefarc: clef prune in archive mode (GRAFF_CLEF_ARCHIVE=1): calls stay,
+# pruned outputs become a stub + artifact path instead of deleted
+# none : no compaction baseline (PCT=100, CLEF=0)
+set -u
+B=${CLEF_EXP_DIR:-/tmp/clef_exp}
+GRAFF=${GRAFF_BIN:-$HOME/codegraff/zig-out/bin/graff}
+MODEL=${CLEF_MODEL:-deepseek-v4-flash}
+TRIAL_TAG=${CLEF_TRIAL:-1}
+mkdir -p $B/runs
+
+run_one() {
+ local arm=$1 trial=$2
+ local d=$B/runs/${MODEL##*/}-${arm}${trial}
+ rm -rf "$d"; mkdir -p "$d"; cp -r $B/src "$d"/
+ local envs="GRAFF_TOOL_HANDLE_BYTES=1048576 GRAFF_COMPACT_PCT=1 GRAFF_SERVER_COMPACT=0"
+ case $arm in
+ clef) envs="$envs GRAFF_CLEF_COMPACT=1";; # default is off (ADR 0261)
+ client) envs="$envs GRAFF_CLEF_COMPACT=0";;
+ mix) envs="$envs GRAFF_CLEF_COMPACT=0 GRAFF_COMPACT_MIX=1";;
+ clefmix) envs="$envs GRAFF_CLEF_COMPACT=1 GRAFF_COMPACT_MIX=1";; # clef first, mix summary on noop
+ clefarc) envs="$envs GRAFF_CLEF_COMPACT=1 GRAFF_CLEF_ARCHIVE=1";; # clef prune, archive instead of delete
+ none) envs="GRAFF_TOOL_HANDLE_BYTES=1048576 GRAFF_COMPACT_PCT=100 GRAFF_SERVER_COMPACT=0 GRAFF_CLEF_COMPACT=0";;
+ esac
+ echo "== ${arm}${trial} start $(date +%H:%M:%S)"
+ local t0=$(date +%s)
+ (cd "$d" && env $envs "$GRAFF" --yolo --new --model $MODEL < $B/turns.txt > out.log 2>&1)
+ local rc=$?
+ echo "$(( $(date +%s) - t0 ))" > "$d/wall_seconds"
+ echo "== ${arm}${trial} exit=$rc wall=$(cat $d/wall_seconds)s"
+}
+
+if [ "${1:-}" = "wave" ]; then
+ # one trial per arm in parallel (wave $2)
+ run_one clef "$2" & run_one client "$2" & run_one mix "$2" & run_one clefmix "$2" & run_one none "$2" & wait
+elif [ "${1:-}" = "arc" ]; then
+ # archive-vs-delete: clef (delete) vs clefarc (archive) vs none baseline
+ run_one clef "$2" & run_one clefarc "$2" & run_one none "$2" & wait
+elif [ "${1:-}" = "recall" ]; then
+ # recall variant (gen_recall.py, CLEF_EXP_DIR=/tmp/clef_recall): facts only
+ # in deleted-after-read tool output; does each arm still know them?
+ run_one client "$2" & run_one clef "$2" & run_one clefarc "$2" & run_one none "$2" & wait
+elif [ "${1:-}" = "trio" ]; then
+ # cross-model shape: clef/client/none only (mix arms already priced on
+ # deepseek; the question here is prune-vs-summary-vs-nothing per model)
+ run_one clef "$2" & run_one client "$2" & run_one none "$2" & wait
+else
+ for trial in 1 2; do
+ for arm in clef client mix clefmix none; do
+ run_one $arm $trial
+ done
+ done
+fi
+echo "ALL DONE"
diff --git a/evals/clef_exp/score_wave.py b/evals/clef_exp/score_wave.py
new file mode 100644
index 00000000..6cdc3cfc
--- /dev/null
+++ b/evals/clef_exp/score_wave.py
@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Score clef-exp runs: recall + compaction counts + wall + cost from traces.
+
+Recall: answer.md graded against questions.json (Q-numbered lines first;
+value-set fallback for models that write the right values in the wrong
+format — format compliance reported separately in `fmt`).
+
+Cost: summed from the session trace `usage` events (server-billed input split
+into ordinary/cache_read/cache_write + output), priced per model row at the
+gateway tariff. The usage events carry provider+model, so each line is priced
+at its own row — clef-flash decision calls ($0.09/1M in, $0 out) separate
+from deepseek turns.
+"""
+import json, os, re, sys, glob
+
+B = os.environ.get("CLEF_EXP_DIR", "/tmp/clef_exp")
+qs = json.load(open(f"{B}/questions.json"))
+
+# (per-1M USD): (ordinary_in, cache_read_in, cache_write_in, out)
+TARIFF = {
+ "deepseek-v4-flash": (0.15, 0.006, 0.15, 0.6),
+ "deepseek-flash": (0.15, 0.006, 0.15, 0.6),
+ "glm-5.3-flash": (0.15, 0.006, 0.15, 0.5),
+ "kimi-k2.6": (0.95, 0.006, 0.95, 4.0),
+ "minimax-m3": (0.3, 0.006, 0.3, 1.2),
+ "clef-flash": (0.09, 0.0, 0.09, 0.0),
+}
+DEFAULT_TARIFF = (0.15, 0.006, 0.15, 0.6)
+
+def price(model, ordinary, read, write, out):
+ t = TARIFF.get(model, DEFAULT_TARIFF)
+ toks = (ordinary + read + write + out) / 1e6
+ usd = (ordinary * t[0] + read * t[1] + write * t[2] + out * t[3]) / 1e6
+ return toks, usd
+
+def archive_reads(d):
+ """Tool calls whose arguments name an archived output (GRAFF_CLEF_ARCHIVE
+ stubs cite .graff/sessions/<s>/artifacts/tool-N.txt): did the model go
+ back for what compaction set aside?"""
+ n = 0
+ def walk(v):
+ nonlocal n
+ if isinstance(v, dict):
+ a = v.get("arguments")
+ if isinstance(a, str) and "artifacts/tool-" in a:
+ n += 1
+ for x in v.values():
+ walk(x)
+ elif isinstance(v, list):
+ for x in v:
+ walk(x)
+ for f in glob.glob(os.path.join(d, ".graff/sessions/*.session.json")):
+ try:
+ walk(json.load(open(f, errors="replace")))
+ except (json.JSONDecodeError, OSError):
+ pass
+ return n
+
+def score_run(d):
+ out = {"run": os.path.basename(d.rstrip("/"))}
+ log = open(os.path.join(d, "out.log"), errors="replace").read()
+ out["clef_prunes"] = log.count("[gateway compacted context")
+ out["clef_noops"] = log.count("clef_compact_noop")
+ out["client_compacts"] = log.count("[history compacted to") + log.count("[compacting ~")
+ out["done"] = "DONE" in log
+ wall = os.path.join(d, "wall_seconds")
+ out["wall"] = open(wall).read().strip() + "s" if os.path.exists(wall) else "?"
+ path = os.path.join(d, "answer.md")
+ answers = {}
+ if os.path.exists(path):
+ for line in open(path, errors="replace"):
+ m = re.match(r"Q(\d+):\s*(.+?)\s*$", line)
+ if m:
+ answers[int(m.group(1))] = m.group(2)
+ # Fallback: the model wrote values without Q-numbers (bare, CONST=val,
+ # or prose). Grade on value-set recall: every expected value appearing
+ # anywhere in the file counts. Format compliance is reported separately.
+ blob = open(path, errors="replace").read() if os.path.exists(path) else ""
+ if not answers:
+ # No answer.md: the model sometimes prints the 10 lines instead of
+ # writing the file. Take the LAST block of Q-lines in the reply; the
+ # blob stays those lines only (out.log never echoes tool output, but
+ # the value-set fallback must not see anything beyond the answer).
+ for line in log.splitlines():
+ m = re.match(r"\s*Q(\d+):\s*(.+?)\s*$", line)
+ if m and "<value>" not in m.group(2):
+ if int(m.group(1)) == 1:
+ answers = {}
+ answers[int(m.group(1))] = m.group(2)
+ blob = "\n".join(answers.values())
+ out["from_reply"] = bool(answers)
+ out["format_ok"] = len(answers) == 10
+ correct, wrong = 0, []
+ for q in qs:
+ got = answers.get(q["q"])
+ exp = q["expect"]
+ ok = got is not None and (got == exp or got.strip('"') == exp.strip('"'))
+ if not ok and blob and exp in blob:
+ ok = True # right value, wrong line format
+ if ok:
+ correct += 1
+ else:
+ wrong.append(f'Q{q["q"]}({q["file"]}): got {got!r} want {exp!r}')
+ out["score"] = f"{correct}/10"
+ out["wrong"] = wrong
+ # cost from usage trace events (server-billed, per model row)
+ toks = usd = 0.0
+ reqs = 0
+ peak_in = 0
+ freed = 0
+ for tr in glob.glob(os.path.join(d, ".graff/traces/*.jsonl")):
+ for line in open(tr, errors="replace"):
+ try:
+ ev = json.loads(line)
+ except json.JSONDecodeError:
+ continue
+ if ev.get("ev") == "clef_compact_applied":
+ m = re.search(r"bytes_freed=(\d+)", ev.get("detail", ""))
+ freed += int(m.group(1)) if m else 0
+ if ev.get("ev") == "usage":
+ model = ev.get("model", "") or ""
+ reqs += 1
+ if not ev.get("from_sub"):
+ peak_in = max(peak_in, ev.get("input_tokens", 0) or 0)
+ # usage input_tokens already includes cache read+write; split
+ # back out: ordinary = input - read - write
+ ordinary = max(0, (ev.get("input_tokens", 0) or 0)
+ - (ev.get("cache_read_tokens", 0) or 0)
+ - (ev.get("cache_write_tokens", 0) or 0))
+ t, u = price(model, ordinary,
+ ev.get("cache_read_tokens", 0) or 0,
+ ev.get("cache_write_tokens", 0) or 0,
+ ev.get("output_tokens", 0) or 0)
+ toks += t
+ usd += u
+ out["api_calls"] = reqs
+ out["peak_in"] = f"{peak_in // 1000}K"
+ out["freed"] = f"{freed // 1000}K"
+ out["arc_reads"] = archive_reads(d)
+ out["mtok"] = round(toks, 3)
+ out["usd"] = round(usd, 4)
+ return out
+
+runs = sorted(glob.glob(f"{B}/runs/*/"), key=os.path.getmtime)
+if len(sys.argv) > 1:
+ runs = [d for d in runs if any(a in d for a in sys.argv[1:])]
+print(f"{'run':<10} {'score':<6} {'fmt':<4} {'clefPr':<6} {'noop':<4} {'cliCmp':<6} {'done':<5} {'wall':<6} {'api':<4} {'mtok':<6} {'usd':<7} {'peak':<5} {'freed':<6} {'arcRd':<5}")
+for d in runs:
+ r = score_run(d)
+ print(f"{r['run']:<10} {r['score']:<6} {str(r['format_ok']):<4} {r['clef_prunes']:<6} {r['clef_noops']:<4} {r['client_compacts']:<6} "
+ f"{str(r['done']):<5} {r['wall']:<6} {r['api_calls']:<4} {r['mtok']:<6} {r['usd']:<7} {r['peak_in']:<5} {r['freed']:<6} {r['arc_reads']:<5}")
+ for w in r["wrong"]:
+ print(" ", w)
diff --git a/src/agent_clef_archive.zig b/src/agent_clef_archive.zig
new file mode 100644
index 00000000..81794761
--- /dev/null
+++ b/src/agent_clef_archive.zig
@@ -0,0 +1,108 @@
+//! Archive, don't delete: the Clef prune arm's recoverable mode.
+//!
+//! Without it, a gateway `drop_call` removes the call and its result from
+//! history, and a `drop_result` keeps the first few hundred characters and
+//! destroys the rest. With `GRAFF_CLEF_ARCHIVE=1`, both become a stub: the
+//! call stays (pairing never changes), the result keeps its head, and the full
+//! bytes go to the session's artifact dir (#409's spill, same budget and
+//! sweep) with the absolute path in the stub, so the next turn can read or
+//! grep what was pruned instead of re-running the tool.
+//!
+//! No durable session (a subagent, an unwired process) or a spent spill
+//! budget falls back to the plain truncation marker — never worse than the
+//! delete-mode stub.
+
+const std = @import("std");
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+
+const tool_spill = @import("tool_spill.zig");
+
+/// GRAFF_CLEF_ARCHIVE=1/true/on arms archive mode (session_settings.applyEnvKnobs).
+/// Default off while the experiment runs (evals/clef_exp arm `clefarc`).
+pub var g_enabled: bool = false;
+
+/// Replace the output string in `m.<field>` with its first `head_chars` plus a
+/// marker. With `session` durable, the full output is archived first and the
+/// marker cites its path; otherwise it is the plain truncation marker.
+/// Returns bytes freed (0 when the output was already short).
+pub fn stubOutput(alloc: Allocator, m: *Value, field: []const u8, head_chars: usize, session: []const u8) usize {
+ if (m.* != .object) return 0;
+ const obj = &m.object;
+ const o = obj.get(field) orelse return 0;
+ if (o != .string or o.string.len <= head_chars) return 0;
+ const full = o.string;
+ const head = utf8Head(full, head_chars);
+ const path: ?[]const u8 = if (session.len > 0) tool_spill.spill(alloc, session, full) else null;
+ const stub = if (path) |p|
+ std.fmt.allocPrint(alloc, "{s}…[archived by compaction: kept first {d} of {d} chars; the FULL output is at {s} — read or grep that file if you need the rest instead of re-running the tool]", .{ head, head.len, full.len, p }) catch return 0
+ else
+ std.fmt.allocPrint(alloc, "{s}…[truncated: kept first {d} of {d} chars]", .{ head, head.len, full.len }) catch return 0;
+ if (stub.len >= full.len) return 0; // a marker longer than what it replaces frees nothing
+ obj.put(alloc, field, .{ .string = stub }) catch return 0;
+ return full.len - stub.len;
+}
+
+/// The longest prefix of `s` within `max` bytes that does not split a UTF-8
+/// sequence (a lone continuation byte is invalid JSON-string content upstream).
+fn utf8Head(s: []const u8, max: usize) []const u8 {
+ if (s.len <= max) return s;
+ var n = max;
+ while (n > 0 and (s[n] & 0xC0) == 0x80) n -= 1;
+ return s[0..n];
+}
+
+// ── tests ────────────────────────────────────────────────────────────────
+
+const testing = std.testing;
+
+test "stubOutput archives the full output and the stub cites its path" {
+ const io = testing.io;
+ var tmp = testing.tmpDir(.{ .iterate = true });
+ defer tmp.cleanup();
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ tool_spill.resetForTest();
+ defer tool_spill.resetForTest();
+ tool_spill.enable(.{ .io = io, .dir = tmp.dir, .base_abs = "" });
+
+ const big = try a.alloc(u8, 4096);
+ @memset(big, 'x');
+ @memcpy(big[3000..][0..9], "NEEDLE254");
+ var obj: std.json.ObjectMap = .empty;
+ try obj.put(a, "role", .{ .string = "tool" });
+ try obj.put(a, "content", .{ .string = big });
+ var m: Value = .{ .object = obj };
+
+ try testing.expect(stubOutput(a, &m, "content", 100, "s1") > 0);
+ const stub = m.object.get("content").?.string;
+ try testing.expect(std.mem.indexOf(u8, stub, "archived by compaction") != null);
+ try testing.expect(std.mem.indexOf(u8, stub, "tool-0.txt") != null);
+ try testing.expect(std.mem.indexOf(u8, stub, "NEEDLE254") == null);
+ const saved = try tmp.dir.readFileAlloc(io, ".graff/sessions/s1/artifacts/tool-0.txt", testing.allocator, .limited(1 << 20));
+ defer testing.allocator.free(saved);
+ try testing.expectEqualStrings(big, saved);
+}
+
+test "stubOutput without a durable session is the plain truncation" {
+ tool_spill.resetForTest();
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var obj: std.json.ObjectMap = .empty;
+ const ys = @import("util.zig").repeatBytes("y", 1000);
+ try obj.put(a, "output", .{ .string = &ys });
+ var m: Value = .{ .object = obj };
+ try testing.expect(stubOutput(a, &m, "output", 10, "") > 0);
+ const stub = m.object.get("output").?.string;
+ try testing.expect(std.mem.indexOf(u8, stub, "truncated: kept first 10 of 1000") != null);
+ // Already short: untouched, nothing freed.
+ try testing.expectEqual(@as(usize, 0), stubOutput(a, &m, "output", 10_000, ""));
+}
+
+test "utf8Head never splits a multi-byte sequence" {
+ try testing.expectEqualStrings("a", utf8Head("aé", 2)); // é is 2 bytes at [1..3]
+ try testing.expectEqualStrings("aé", utf8Head("aéb", 3));
+ try testing.expectEqualStrings("ab", utf8Head("ab", 5));
+}
diff --git a/src/agent_clef_compact.zig b/src/agent_clef_compact.zig
new file mode 100644
index 00000000..caa7a591
--- /dev/null
+++ b/src/agent_clef_compact.zig
@@ -0,0 +1,500 @@
+//! Clef-driven compaction client: the gateway's server-side POST /v1/compact
+//! as this repo's replacement for the client-side summary (agent_compact.zig).
+//!
+//! The endpoint prunes stale tool calls/results with the Clef decision models
+//! instead of summarizing: text messages stay verbatim and in order, only
+//! tool calls/results are candidates for removal. Response shape:
+//! `{model, mode, messages: [{role, text, toolUses[], toolResults?[]}], decisions[], stats, usage}`.
+//!
+//! Policy: OpenAI-family server paths are untouched (direct OpenAI standalone
+//! `/responses/compact`, Codex/ChatGPT in-stream directive, xAI explicit
+//! endpoint) — this arm replaces ONLY the client summarizer. Eligibility is
+//! the codegraff gateway provider with a credential; every failure (network,
+//! non-2xx, malformed) returns false and the caller falls back to the client
+//! summary, so a broken endpoint can never wedge the session.
+//!
+//! Wire-format note: local history holds provider wire items (Responses
+//! function_call/function_call_output, chat tool_calls/role:tool). The gateway
+//! wants `{role, text, toolUses[{tool_use_id, tool, input}], toolResults?[{tool_use_id, text}]}`.
+//! Translation pairs calls with outputs by call_id/tool_use_id; application
+//! maps the returned decisions back the same way (drop_call removes both,
+//! drop_result truncates the output to truncateHeadChars).
+
+const std = @import("std");
+const Io = std.Io;
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+
+const Agent = @import("agent.zig").Agent;
+const main_mod = @import("main.zig");
+const http = @import("http.zig");
+const providers = @import("providers.zig");
+const archive = @import("agent_clef_archive.zig"); // GRAFF_CLEF_ARCHIVE: stub + artifact instead of delete
+
+/// GRAFF_CLEF_COMPACT=1 (any value but 0/false/off) arms the gateway
+/// /v1/compact path (session_settings.applyEnvKnobs). Default OFF: the client
+/// summary is the compactor (ADR 0261). OpenAI-family server paths stay
+/// untouched regardless.
+pub var g_enabled: bool = false;
+
+pub fn enabled() bool {
+ return g_enabled;
+}
+
+/// True when this session may compact through the gateway: knob on, provider
+/// is the codegraff gateway, and a credential is present. Subagents share the
+/// root provider so they inherit eligibility; review turns never compact.
+pub fn eligible(self: *const Agent) bool {
+ if (!g_enabled) return false;
+ if (self.review_mode) return false;
+ if (!std.mem.eql(u8, self.provider.id, "codegraff")) return false;
+ return self.provider.api_key.len > 0;
+}
+
+/// Gateway compact URL derived from the session provider's chat URL:
+/// `.../v1/chat/completions` and `.../v1/responses` both trim to `.../v1/compact`.
+/// Null when the URL has no recognizable v1 root, so a custom override can
+/// never route the transcript somewhere unexpected.
+pub fn compactUrl(arena: Allocator, provider_url: []const u8) ?[]const u8 {
+ const root = if (std.mem.indexOf(u8, provider_url, "/v1/")) |i| provider_url[0 .. i + 3] else return null;
+ return std.fmt.allocPrint(arena, "{s}/compact", .{root}) catch null;
+}
+
+/// One translated message in the gateway transcript shape.
+pub const GwMessage = struct {
+ role: []const u8, // "user" | "assistant"
+ text: []const u8,
+ toolUses: std.ArrayList(GwUse),
+ toolResults: std.ArrayList(GwResult),
+};
+
+const GwUse = struct {
+ tool_use_id: []const u8,
+ tool: []const u8,
+ input_json: Value,
+};
+
+const GwResult = struct {
+ tool_use_id: []const u8,
+ text: []const u8,
+};
+
+fn strField(obj: std.json.ObjectMap, name: []const u8) ?[]const u8 {
+ const v = obj.get(name) orelse return null;
+ return if (v == .string) v.string else null;
+}
+
+/// Translate wire history items into gateway messages. Responses items carry
+/// their own type; chat assistant tool_calls[] fold into uses on their
+/// message and role:tool items become pending outputs. Text accumulates onto
+/// the current message; reasoning/compaction items are skipped (the gateway
+/// decides over tool calls, and opaque blobs must never leave the session).
+pub fn translateHistory(arena: Allocator, items: []const Value, out: *std.ArrayList(GwMessage)) !void {
+ var pending_outputs: std.ArrayList(GwResult) = .empty;
+ for (items) |m| {
+ if (m != .object) continue;
+ const obj = m.object;
+ if (strField(obj, "type")) |t| {
+ if (std.mem.eql(u8, t, "function_call")) {
+ const cid = strField(obj, "call_id") orelse continue;
+ const name = strField(obj, "name") orelse "tool";
+ const args_s = strField(obj, "arguments") orelse "{}";
+ const input = std.json.parseFromSliceLeaky(Value, arena, args_s, .{}) catch Value{ .object = .empty };
+ var msg = GwMessage{ .role = "assistant", .text = "", .toolUses = .empty, .toolResults = .empty };
+ try msg.toolUses.append(arena, .{ .tool_use_id = cid, .tool = name, .input_json = input });
+ try out.append(arena, msg);
+ continue;
+ }
+ if (std.mem.eql(u8, t, "function_call_output")) {
+ const cid = strField(obj, "call_id") orelse continue;
+ const text = strField(obj, "output") orelse "";
+ try pending_outputs.append(arena, .{ .tool_use_id = cid, .text = text });
+ continue;
+ }
+ if (std.mem.eql(u8, t, "compaction") or std.mem.eql(u8, t, "compaction_summary") or std.mem.eql(u8, t, "reasoning")) continue;
+ }
+ const role = strField(obj, "role") orelse continue;
+ if (!std.mem.eql(u8, role, "user") and !std.mem.eql(u8, role, "assistant") and !std.mem.eql(u8, role, "tool")) continue;
+ const text = providers.extractText(arena, m);
+ if (std.mem.eql(u8, role, "tool")) {
+ const cid = strField(obj, "tool_call_id") orelse "";
+ if (cid.len > 0) try pending_outputs.append(arena, .{ .tool_use_id = cid, .text = text });
+ continue;
+ }
+ var msg = GwMessage{ .role = role, .text = text, .toolUses = .empty, .toolResults = .empty };
+ if (obj.get("tool_calls")) |tc| {
+ if (tc == .array) for (tc.array.items) |call| {
+ if (call != .object) continue;
+ const f = call.object.get("function") orelse continue;
+ if (f != .object) continue;
+ const cid = strField(call.object, "id") orelse continue;
+ const name = strField(f.object, "name") orelse "tool";
+ const args_s = strField(f.object, "arguments") orelse "{}";
+ const input = std.json.parseFromSliceLeaky(Value, arena, args_s, .{}) catch Value{ .object = .empty };
+ try msg.toolUses.append(arena, .{ .tool_use_id = cid, .tool = name, .input_json = input });
+ };
+ }
+ try out.append(arena, msg);
+ }
+ // Attach outputs to the message holding their call; orphan outputs ride
+ // the nearest following assistant message, else a trailing user message.
+ for (pending_outputs.items) |r| {
+ var attached = false;
+ for (out.items) |*msg| {
+ for (msg.toolUses.items) |u| {
+ if (std.mem.eql(u8, u.tool_use_id, r.tool_use_id)) {
+ msg.toolResults.append(arena, r) catch continue;
+ attached = true;
+ break;
+ }
+ }
+ if (attached) break;
+ }
+ if (!attached) {
+ for (out.items) |*msg| {
+ if (std.mem.eql(u8, msg.role, "assistant")) {
+ msg.toolResults.append(arena, r) catch continue;
+ attached = true;
+ break;
+ }
+ }
+ }
+ if (!attached) {
+ var msg = GwMessage{ .role = "user", .text = "", .toolUses = .empty, .toolResults = .empty };
+ msg.toolResults.append(arena, r) catch continue;
+ out.append(arena, msg) catch continue;
+ }
+ }
+}
+
+/// Serialize the translated messages as the /v1/compact `messages` array.
+pub fn writeMessages(s: *std.json.Stringify, messages: []const GwMessage) !void {
+ try s.beginArray();
+ for (messages) |m| {
+ try s.beginObject();
+ try s.objectField("role");
+ try s.write(m.role);
+ try s.objectField("text");
+ try s.write(m.text);
+ try s.objectField("toolUses");
+ try s.beginArray();
+ for (m.toolUses.items) |u| {
+ try s.beginObject();
+ try s.objectField("tool_use_id");
+ try s.write(u.tool_use_id);
+ try s.objectField("tool");
+ try s.write(u.tool);
+ try s.objectField("input");
+ try s.write(u.input_json);
+ try s.endObject();
+ }
+ try s.endArray();
+ if (m.toolResults.items.len > 0) {
+ try s.objectField("toolResults");
+ try s.beginArray();
+ for (m.toolResults.items) |r| {
+ try s.beginObject();
+ try s.objectField("tool_use_id");
+ try s.write(r.tool_use_id);
+ try s.objectField("text");
+ try s.write(r.text);
+ try s.endObject();
+ }
+ try s.endArray();
+ }
+ try s.endObject();
+ }
+ try s.endArray();
+}
+
+/// Build the POST /v1/compact body: model + translated messages. Hybrid mode
+/// is left off — the gateway default (prune) is the arm under trial; the
+/// summary leg would reintroduce the summarizer this replaces.
+pub fn compactBody(arena: Allocator, messages: []const GwMessage) ![]u8 {
+ var aw: Io.Writer.Allocating = .init(arena);
+ errdefer aw.deinit();
+ var s: std.json.Stringify = .{ .writer = &aw.writer };
+ try s.beginObject();
+ try s.objectField("model");
+ try s.write("clef-flash");
+ try s.objectField("messages");
+ try writeMessages(&s, messages);
+ try s.endObject();
+ return aw.toOwnedSlice();
+}
+
+pub const Decision = struct {
+ tool_use_id: []const u8,
+ action: []const u8, // "keep" | "drop_result" | "drop_call"
+};
+
+/// Parse the gateway response's decisions array. Unknown actions are kept
+/// (safety-first, mirroring the gateway's own drop bar): only explicit
+/// drop_result/drop_call prune.
+pub fn parseDecisions(arena: Allocator, response: []const u8) ![]Decision {
+ const parsed = try std.json.parseFromSliceLeaky(Value, arena, response, .{ .allocate = .alloc_always });
+ if (parsed != .object) return error.InvalidCompactionResponse;
+ const arr = parsed.object.get("decisions") orelse return error.InvalidCompactionResponse;
+ if (arr != .array) return error.InvalidCompactionResponse;
+ var out: std.ArrayList(Decision) = .empty;
+ for (arr.array.items) |d| {
+ if (d != .object) continue;
+ const id = strField(d.object, "tool_use_id") orelse continue;
+ const action = strField(d.object, "action") orelse "keep";
+ try out.append(arena, .{ .tool_use_id = id, .action = action });
+ }
+ return out.toOwnedSlice(arena);
+}
+
+fn isListed(ids: []const []const u8, id: []const u8) bool {
+ if (id.len == 0) return false;
+ for (ids) |known| if (std.mem.eql(u8, known, id)) return true;
+ return false;
+}
+
+/// Truncate a tool output value in place, keeping valid call/output pairing
+/// (the message stays, only its bytes shrink). Mirrors the gateway's own
+/// `…[truncated: kept first N of M chars]` marker.
+fn truncateOutputValue(alloc: Allocator, m: *Value, field: []const u8, head_chars: usize) usize {
+ if (m.* != .object) return 0;
+ const obj = &m.object;
+ const o = obj.get(field) orelse return 0;
+ if (o != .string or o.string.len <= head_chars) return 0;
+ const head = o.string[0..head_chars];
+ const note = std.fmt.allocPrint(alloc, "{s}…[truncated: kept first {d} of {d} chars]", .{ head, head_chars, o.string.len }) catch return 0;
+ if (note.len >= o.string.len) return 0;
+ const freed = o.string.len - note.len;
+ obj.put(alloc, field, .{ .string = note }) catch return 0;
+ return freed;
+}
+
+/// What applyDecisions changed: messages removed outright, and outputs
+/// shrunk to a stub (truncated, or archived in GRAFF_CLEF_ARCHIVE mode).
+pub const Applied = struct {
+ removed: usize = 0,
+ shrunk: usize = 0,
+ bytes_freed: usize = 0,
+
+ pub fn progressed(self: Applied) bool {
+ return self.removed > 0 or self.bytes_freed > 0;
+ }
+
+ fn shrink(self: *Applied, agent: *Agent, m: *Value, field: []const u8, head_chars: usize, session: []const u8, archiving: bool) void {
+ const alloc = agent.messageMutationAlloc();
+ const freed = if (archiving)
+ archive.stubOutput(alloc, m, field, head_chars, session)
+ else
+ truncateOutputValue(alloc, m, field, head_chars);
+ if (freed == 0) return;
+ self.shrunk += 1;
+ self.bytes_freed += freed;
+ }
+};
+
+/// Apply gateway decisions to the live wire history in place. drop_call
+/// removes the call AND its paired output; drop_result truncates the output
+/// to `head_chars`. Pairing is by call_id/tool_use_id on both wire formats.
+/// Returns what changed (removed messages, shrunk outputs, bytes freed).
+///
+/// Archive mode (GRAFF_CLEF_ARCHIVE=1): every drop_call is applied as a
+/// drop_result, and each shrunk output's full bytes are archived to the
+/// session's artifact dir with the path in the stub — nothing leaves history
+/// unrecoverably, and pairing never changes.
+///
+/// Atomicity rule (chat wire): an assistant message's tool_calls[] is an
+/// all-or-nothing unit for the gateway. Dropping only SOME calls out of one
+/// message orphans the surviving results (a role:tool result whose call is
+/// gone is a 400 on the next send — the wave-1 clef1 wedge). So a
+/// drop_call fires only when EVERY call id in that message is listed; a
+/// partial listing degrades to drop_result truncation on the listed outputs.
+/// Responses items are already one-call-per-item, so they drop singly.
+pub fn applyDecisions(self: *Agent, decisions: []const Decision, head_chars: usize) Applied {
+ var drop_calls: std.ArrayList([]const u8) = .empty;
+ var drop_results: std.ArrayList([]const u8) = .empty;
+ const archiving = archive.g_enabled;
+ for (decisions) |d| {
+ const is_call = std.mem.eql(u8, d.action, "drop_call");
+ if (is_call) drop_calls.append(self.gpa, d.tool_use_id) catch continue;
+ // Archive mode: a drop_call is also a drop_result, which the rule
+ // below already turns into "keep the call, stub the output".
+ if (std.mem.eql(u8, d.action, "drop_result") or (is_call and archiving))
+ drop_results.append(self.gpa, d.tool_use_id) catch continue;
+ }
+ defer drop_calls.deinit(self.gpa);
+ defer drop_results.deinit(self.gpa);
+ var applied: Applied = .{};
+ if (drop_calls.items.len == 0 and drop_results.items.len == 0) return applied;
+ const session = if (archiving) @import("tool_spill.zig").sessionFor(self.sub, self.session_name) else "";
+
+ // Degrade partial chat-wire drop_calls to drop_results BEFORE mutating:
+ // collect every call id that shares an assistant message with an
+ // unlisted sibling; those ids truncate instead of dropping. An explicit
+ // gateway drop_result on the same id degrades identically.
+ for (self.messages.items) |m| {
+ if (m != .object) continue;
+ if (strField(m.object, "role")) |role| {
+ if (!std.mem.eql(u8, role, "assistant")) continue;
+ const tc = m.object.get("tool_calls") orelse continue;
+ if (tc != .array or tc.array.items.len < 2) continue;
+ var all_listed = true;
+ var any_listed = false;
+ for (tc.array.items) |call| {
+ if (call != .object) continue;
+ const cid = strField(call.object, "id") orelse continue;
+ if (isListed(drop_calls.items, cid)) {
+ any_listed = true;
+ } else {
+ all_listed = false;
+ }
+ }
+ if (any_listed and !all_listed) {
+ for (tc.array.items) |call| {
+ if (call != .object) continue;
+ const cid = strField(call.object, "id") orelse continue;
+ if (!isListed(drop_calls.items, cid)) continue;
+ var already = false;
+ for (drop_results.items) |r| if (std.mem.eql(u8, r, cid)) {
+ already = true;
+ break;
+ };
+ if (!already) drop_results.append(self.gpa, cid) catch continue;
+ }
+ }
+ }
+ }
+ // A drop_call that is also a drop_result (degraded partial above, or an
+ // explicit gateway drop_result on the same id) truncates; only a
+ // drop_call with NO drop_result on the same id removes its messages.
+ var w: usize = 0;
+ for (self.messages.items) |*m| {
+ if (m.* != .object) {
+ self.messages.items[w] = m.*;
+ w += 1;
+ continue;
+ }
+ const obj = &m.object;
+ // Responses function_call / function_call_output.
+ if (strField(obj.*, "type")) |t| {
+ if (std.mem.eql(u8, t, "function_call")) {
+ const cid = strField(obj.*, "call_id") orelse "";
+ if (isListed(drop_calls.items, cid) and !isListed(drop_results.items, cid)) {
+ applied.removed += 1;
+ continue;
+ }
+ }
+ if (std.mem.eql(u8, t, "function_call_output")) {
+ const cid = strField(obj.*, "call_id") orelse "";
+ if (isListed(drop_calls.items, cid) and !isListed(drop_results.items, cid)) {
+ applied.removed += 1;
+ continue;
+ }
+ if (isListed(drop_results.items, cid)) applied.shrink(self, m, "output", head_chars, session, archiving);
+ }
+ self.messages.items[w] = m.*;
+ w += 1;
+ continue;
+ }
+ // Chat assistant tool_calls[] + role:tool results. The pre-pass
+ // above already degraded every partial listing, so reaching this
+ // point with a listed id means the whole message is listed: drop it
+ // and its results together, keeping pairing valid.
+ if (strField(obj.*, "role")) |role| {
+ if (std.mem.eql(u8, role, "assistant")) {
+ if (obj.get("tool_calls")) |tc| {
+ if (tc == .array) {
+ var drop_whole = false;
+ for (tc.array.items) |call| {
+ if (call != .object) continue;
+ const cid = strField(call.object, "id") orelse continue;
+ if (isListed(drop_calls.items, cid) and !isListed(drop_results.items, cid)) {
+ drop_whole = true;
+ applied.removed += 1;
+ break;
+ }
+ }
+ if (drop_whole) continue;
+ }
+ }
+ }
+ if (std.mem.eql(u8, role, "tool")) {
+ const cid = strField(obj.*, "tool_call_id") orelse "";
+ if (isListed(drop_calls.items, cid) and !isListed(drop_results.items, cid)) {
+ applied.removed += 1;
+ continue;
+ }
+ if (isListed(drop_results.items, cid)) applied.shrink(self, m, "content", head_chars, session, archiving);
+ }
+ }
+ self.messages.items[w] = m.*;
+ w += 1;
+ }
+ self.messages.shrinkRetainingCapacity(w);
+ return applied;
+}
+
+/// Single call-site for compact(): eligible sessions try the gateway first
+/// (returns the new history length on a prune); anything else is null and
+/// the caller falls through to the client summary. Keeps agent_compact.zig
+/// under the 600-line ceiling.
+/// POST the translated history to the gateway and apply the returned
+/// decisions. True when history was pruned; ANY failure returns false with
+/// history untouched, so the caller falls back to the client summary.
+pub fn tryCompact(self: *Agent) ?usize {
+ if (!eligible(self)) return null;
+ if (!compactViaGateway(self)) return null;
+ return self.messages.items.len;
+}
+
+pub fn compactViaGateway(self: *Agent) bool {
+ if (!eligible(self)) return false;
+ if (self.messages.items.len == 0) return false;
+ var arena_state = std.heap.ArenaAllocator.init(self.gpa);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ const url = compactUrl(arena, self.provider.url) orelse return false;
+
+ var translated: std.ArrayList(GwMessage) = .empty;
+ translateHistory(arena, self.messages.items, &translated) catch return false;
+ if (translated.items.len == 0) return false;
+ const body = compactBody(arena, translated.items) catch return false;
+
+ var gw = self.provider;
+ gw.url = url;
+ var conv_buf: [96]u8 = undefined;
+ const conv = @import("http_headers.zig").requestCacheKey(self.io, self.label, self, self.provider, &conv_buf);
+ const resp = http.postWatched(self.gpa, self.io, self.client, gw, body, conv) catch |err| {
+ if (self.tracer) |tr| tr.note("clef_compact_failed", @errorName(err));
+ return false;
+ };
+ defer self.gpa.free(resp);
+ const decisions = parseDecisions(arena, resp) catch {
+ if (self.tracer) |tr| tr.note("clef_compact_failed", resp[0..@min(resp.len, 200)]);
+ return false;
+ };
+ const applied = applyDecisions(self, decisions, 300);
+ if (!applied.progressed()) {
+ // Nothing pruned: not a failure, but not progress either. Report it
+ // so the caller can decide (the client summary may still shrink text).
+ if (self.tracer) |tr| tr.note("clef_compact_noop", "");
+ return false;
+ }
+ self.last_context_tokens = 0;
+ self.context_local_tokens = 0;
+ self.goal_note_fp = 0;
+ self.history_rewrites +%= 1;
+ if (self.pending_goal_note == null)
+ self.pending_goal_note = @import("goal_flow.zig").compactionSnapshot(self.arena, self) catch null;
+ if (self.tracer) |tr| {
+ var nb: [96]u8 = undefined;
+ tr.note("clef_compact_applied", std.fmt.bufPrint(&nb, "removed={d} shrunk={d} bytes_freed={d} archive={}", .{ applied.removed, applied.shrunk, applied.bytes_freed, archive.g_enabled }) catch "");
+ }
+ if (!main_mod.json_mode) {
+ if (archive.g_enabled)
+ self.say("[gateway compacted context: {d} tool output(s) archived by clef, {d} bytes freed]\n", .{ applied.shrunk, applied.bytes_freed }) catch {}
+ else
+ self.say("[gateway compacted context: {d} tool message(s) pruned by clef]\n", .{applied.removed}) catch {};
+ }
+ return true;
+}
+
+// Tests live in agent_clef_compact_tests.zig (the 600-line ceiling).
diff --git a/src/agent_clef_compact_tests.zig b/src/agent_clef_compact_tests.zig
new file mode 100644
index 00000000..7ebc7082
--- /dev/null
+++ b/src/agent_clef_compact_tests.zig
@@ -0,0 +1,209 @@
+//! Tests for agent_clef_compact.zig (split out for the 600-line ceiling).
+
+const std = @import("std");
+const Value = std.json.Value;
+const Agent = @import("agent.zig").Agent;
+const clef = @import("agent_clef_compact.zig");
+const archive = @import("agent_clef_archive.zig");
+const compactUrl = clef.compactUrl;
+const translateHistory = clef.translateHistory;
+const parseDecisions = clef.parseDecisions;
+const applyDecisions = clef.applyDecisions;
+const eligible = clef.eligible;
+const GwMessage = clef.GwMessage;
+const Decision = clef.Decision;
+
+const testing = std.testing;
+
+test "compactUrl derives /v1/compact from chat and responses gateway URLs" {
+ const a = testing.allocator;
+ const chat = compactUrl(a, "https://gateway.codegraff.com/v1/chat/completions").?;
+ defer a.free(chat);
+ const resp = compactUrl(a, "https://gateway.codegraff.com/v1/responses").?;
+ defer a.free(resp);
+ try testing.expectEqualStrings("https://gateway.codegraff.com/v1/compact", chat);
+ try testing.expectEqualStrings("https://gateway.codegraff.com/v1/compact", resp);
+ try testing.expect(compactUrl(a, "https://example.com/no-version-here") == null);
+}
+
+test "translateHistory pairs Responses calls with outputs" {
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const items = try std.json.parseFromSliceLeaky(Value, a,
+ \\[{"role":"user","content":"fix it"},
+ \\ {"type":"function_call","call_id":"c1","name":"bash","arguments":"{}"},
+ \\ {"type":"function_call_output","call_id":"c1","output":"ok"}]
+ , .{});
+ var out: std.ArrayList(GwMessage) = .empty;
+ try translateHistory(a, items.array.items, &out);
+ try testing.expectEqual(@as(usize, 2), out.items.len);
+ try testing.expectEqual(@as(usize, 1), out.items[1].toolUses.items.len);
+ try testing.expectEqualStrings("c1", out.items[1].toolUses.items[0].tool_use_id);
+ try testing.expectEqual(@as(usize, 1), out.items[1].toolResults.items.len);
+ try testing.expectEqualStrings("ok", out.items[1].toolResults.items[0].text);
+}
+
+test "parseDecisions keeps unknown actions (safety-first)" {
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const ds = try parseDecisions(a,
+ \\{"model":"clef-flash","mode":"prune","messages":[],"decisions":[{"tool_use_id":"c1","action":"drop_call"},{"tool_use_id":"c2","action":"frobnicate"}],"stats":{},"usage":{}}
+ );
+ try testing.expectEqual(@as(usize, 2), ds.len);
+ try testing.expectEqualStrings("drop_call", ds[0].action);
+ try testing.expectEqualStrings("frobnicate", ds[1].action); // applied as keep
+}
+
+test "eligible: knob on + codegraff provider + key; review never" {
+ const saved = clef.g_enabled;
+ defer clef.g_enabled = saved;
+ clef.g_enabled = true;
+ var agent: Agent = undefined;
+ agent.review_mode = false;
+ agent.provider = .{ .id = "codegraff", .kind = .openai, .auth = .bearer, .url = "", .api_key = "k", .model = "m", .context = 100_000 };
+ try testing.expect(eligible(&agent));
+ agent.provider.id = "codex";
+ try testing.expect(!eligible(&agent));
+ agent.provider.id = "codegraff";
+ agent.provider.api_key = "";
+ try testing.expect(!eligible(&agent));
+ agent.provider.api_key = "k";
+ agent.review_mode = true;
+ try testing.expect(!eligible(&agent));
+ clef.g_enabled = false;
+ agent.review_mode = false;
+ try testing.expect(!eligible(&agent));
+}
+
+test "applyDecisions degrades a partial chat drop_call to truncation (wave-1 wedge)" {
+ // One assistant message with two calls; the gateway lists only c1 for
+ // drop_call. Dropping the whole message would orphan c2's result (a 400
+ // on the next send); instead c1's output truncates and nothing is
+ // removed.
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const items = try std.json.parseFromSliceLeaky(Value, a,
+ \\[{"role":"user","content":"go"},
+ \\ {"role":"assistant","content":"","tool_calls":[
+ \\ {"id":"c1","type":"function","function":{"name":"read","arguments":"{}"}},
+ \\ {"id":"c2","type":"function","function":{"name":"read","arguments":"{}"}}]},
+ \\ {"role":"tool","tool_call_id":"c1","content":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"},
+ \\ {"role":"tool","tool_call_id":"c2","content":"BBBB"}]
+ , .{});
+ var agent: Agent = undefined;
+ agent.gpa = testing.allocator;
+ agent.message_mutation_arena = a;
+ agent.messages = std.json.Array.init(a);
+ try agent.messages.appendSlice(items.array.items);
+ const ds = [_]Decision{.{ .tool_use_id = "c1", .action = "drop_call" }};
+ const removed = applyDecisions(&agent, &ds, 2).removed;
+ try testing.expectEqual(@as(usize, 0), removed);
+ try testing.expectEqual(@as(usize, 4), agent.messages.items.len);
+ // c1's output truncated in place; c2 untouched.
+ try testing.expectEqualStrings("BBBB", agent.messages.items[3].object.get("content").?.string);
+ const c1out = agent.messages.items[2].object.get("content").?.string;
+ try testing.expect(std.mem.startsWith(u8, c1out, "AA"));
+ try testing.expect(std.mem.indexOf(u8, c1out, "truncated") != null);
+}
+
+test "applyDecisions drops a fully-listed chat message with its results" {
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const items = try std.json.parseFromSliceLeaky(Value, a,
+ \\[{"role":"user","content":"go"},
+ \\ {"role":"assistant","content":"","tool_calls":[
+ \\ {"id":"c1","type":"function","function":{"name":"read","arguments":"{}"}},
+ \\ {"id":"c2","type":"function","function":{"name":"read","arguments":"{}"}}]},
+ \\ {"role":"tool","tool_call_id":"c1","content":"AAAA"},
+ \\ {"role":"tool","tool_call_id":"c2","content":"BBBB"},
+ \\ {"role":"assistant","content":"done"}]
+ , .{});
+ var agent: Agent = undefined;
+ agent.gpa = testing.allocator;
+ agent.message_mutation_arena = a;
+ agent.messages = std.json.Array.init(a);
+ try agent.messages.appendSlice(items.array.items);
+ const ds = [_]Decision{
+ .{ .tool_use_id = "c1", .action = "drop_call" },
+ .{ .tool_use_id = "c2", .action = "drop_call" },
+ };
+ const removed = applyDecisions(&agent, &ds, 2).removed;
+ try testing.expectEqual(@as(usize, 3), removed);
+ try testing.expectEqual(@as(usize, 2), agent.messages.items.len);
+}
+
+test "applyDecisions drops Responses pairs singly (no atomicity grouping)" {
+ // Responses wire: one call per item, so a single drop_call removes
+ // exactly its call + output pair even with surviving siblings.
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const items = try std.json.parseFromSliceLeaky(Value, a,
+ \\[{"role":"user","content":"go"},
+ \\ {"type":"function_call","call_id":"c1","name":"read","arguments":"{}"},
+ \\ {"type":"function_call_output","call_id":"c1","output":"AAAA"},
+ \\ {"type":"function_call","call_id":"c2","name":"read","arguments":"{}"},
+ \\ {"type":"function_call_output","call_id":"c2","output":"BBBB"},
+ \\ {"role":"assistant","content":"done"}]
+ , .{});
+ var agent: Agent = undefined;
+ agent.gpa = testing.allocator;
+ agent.message_mutation_arena = a;
+ agent.messages = std.json.Array.init(a);
+ try agent.messages.appendSlice(items.array.items);
+ const ds = [_]Decision{.{ .tool_use_id = "c1", .action = "drop_call" }};
+ const removed = applyDecisions(&agent, &ds, 2).removed;
+ try testing.expectEqual(@as(usize, 2), removed);
+ try testing.expectEqual(@as(usize, 4), agent.messages.items.len);
+ // c2's pair survives intact.
+ try testing.expectEqualStrings("c2", agent.messages.items[1].object.get("call_id").?.string);
+ try testing.expectEqualStrings("BBBB", agent.messages.items[2].object.get("output").?.string);
+}
+
+test "archive mode keeps a dropped call and archives its output (GRAFF_CLEF_ARCHIVE)" {
+ const tool_spill = @import("tool_spill.zig");
+ const io = testing.io;
+ var tmp = testing.tmpDir(.{ .iterate = true });
+ defer tmp.cleanup();
+ tool_spill.resetForTest();
+ defer tool_spill.resetForTest();
+ tool_spill.enable(.{ .io = io, .dir = tmp.dir, .base_abs = "" });
+ const saved = archive.g_enabled;
+ defer archive.g_enabled = saved;
+ archive.g_enabled = true;
+
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const items = try std.json.parseFromSliceLeaky(Value, a,
+ \\[{"role":"user","content":"go"},
+ \\ {"role":"assistant","content":"","tool_calls":[
+ \\ {"id":"c1","type":"function","function":{"name":"read","arguments":"{}"}}]},
+ \\ {"role":"tool","tool_call_id":"c1","content":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZ"},
+ \\ {"role":"assistant","content":"done"}]
+ , .{});
+ var agent: Agent = undefined;
+ agent.gpa = testing.allocator;
+ agent.message_mutation_arena = a;
+ agent.sub = false;
+ agent.session_name = "s9";
+ agent.messages = std.json.Array.init(a);
+ try agent.messages.appendSlice(items.array.items);
+ const ds = [_]Decision{.{ .tool_use_id = "c1", .action = "drop_call" }};
+ const applied = applyDecisions(&agent, &ds, 4);
+ // Nothing removed: the call and its (stubbed) result both stay, so pairing holds.
+ try testing.expectEqual(@as(usize, 0), applied.removed);
+ try testing.expectEqual(@as(usize, 1), applied.shrunk);
+ try testing.expect(applied.progressed());
+ try testing.expectEqual(@as(usize, 4), agent.messages.items.len);
+ const stub = agent.messages.items[2].object.get("content").?.string;
+ try testing.expect(std.mem.startsWith(u8, stub, "AAAA"));
+ try testing.expect(std.mem.indexOf(u8, stub, "archived by compaction") != null);
+ const full = try tmp.dir.readFileAlloc(io, ".graff/sessions/s9/artifacts/tool-0.txt", testing.allocator, .limited(1 << 20));
+ defer testing.allocator.free(full);
+ try testing.expect(std.mem.endsWith(u8, full, "Z"));
+}
diff --git a/src/agent_compact.zig b/src/agent_compact.zig
index 676c5447..199dedbb 100644
--- a/src/agent_compact.zig
+++ b/src/agent_compact.zig
@@ -118,6 +118,8 @@ pub fn compactPrelude(self: *Agent) ?usize {
pub fn compact(self: *Agent) anyerror!usize {
// An opaque item anywhere in history needs the server, never a local summary.
if (@import("compaction_window.zig").latestBlob(self.messages.items) != null) return error.ServerCompactionRequired;
+ // Clef gateway pruning replaces the client summary when eligible.
+ if (@import("agent_clef_compact.zig").tryCompact(self)) |n| return n;
const fork = @import("cache_fork.zig").begin(self); // ADR 0220: read the cached history, not rewrite it
defer @import("cache_fork.zig").end();
const pending_tokens = compactPrelude(self) orelse {
@@ -389,7 +391,8 @@ pub fn dropPriorTurnReasoning(self: *Agent) usize {
/// Re-pair the meter after removing locally measurable context. The server-only
/// delta remains intact, while the current local component reflects the trim.
-fn accountForReclaimedTokens(self: *Agent, reclaimed_tokens: u64) void {
+/// Pub for agent_compact_recover.zig (same split that moved the recovery tail).
+pub fn accountForReclaimedTokens(self: *Agent, reclaimed_tokens: u64) void {
if (reclaimed_tokens == 0) return;
self.rebaseContextMeter();
}
@@ -469,132 +472,8 @@ pub fn capOversizedToolOutputs(self: *Agent, cap: usize) usize {
return reclaimed;
}
-/// Last-resort context recovery when compact() itself can't run — typically
-/// because the history already overflows the window, so the summarization
-/// request overflows too and fails. Drops the oldest messages at a safe
-/// boundary; returns the count dropped (0 if none). Conservatively reduce the
-/// authoritative meter only by the locally measurable reclaimed tokens: hidden
-/// server-side reasoning may make the true reduction larger, but must never let
-/// a partial trim blind the next pre-send gate.
-pub fn emergencyTrim(self: *Agent) usize {
- if (emergencyCutIndex(self.messages.items)) |cut| {
- const before_tokens = self.fullInputEstimateTokens();
- var fresh = std.json.Array.init(self.arena);
- for (self.messages.items[cut..]) |m| fresh.append(m) catch return 0;
- self.messages = fresh;
- self.goal_note_fp = 0; // trimmed history may have carried the goal note (#318)
- self.history_rewrites +%= 1; // and the run's checklist gate's pasted copies (#318)
- // No synthetic message exists here to hang the standing state on (unlike
- // compact()'s handoff), so it rides the next turn's one-shot slot. Only
- // when that slot is free: a queued /goal replace|clear note is the USER's
- // instruction and outranks the harness restating itself (#318).
- if (self.pending_goal_note == null)
- self.pending_goal_note = goal_flow.compactionSnapshot(self.arena, self) catch null;
- const after_tokens = self.fullInputEstimateTokens();
- accountForReclaimedTokens(self, before_tokens -| after_tokens);
- return cut;
- }
- // #163: no clean user turn to cut at (a runaway tool loop). Don't wedge the
- // session — reclaim context by truncating the oldest tool outputs in place,
- // keeping every call/output pair valid. Nonzero = recovered. This too is a
- // rewrite: the stubbed outputs may include the last todo_write render the
- // suppressed run note points the model at (#318).
- if (trimOldestToolOutputs(self) > 0) {
- self.history_rewrites +%= 1;
- if (self.pending_goal_note == null)
- self.pending_goal_note = goal_flow.compactionSnapshot(self.arena, self) catch null;
- return 1;
- }
- return 0;
-}
-
-/// Auto-compaction with recovery. compact() summarizes the whole history in
-/// one request; once context overflows the window that request overflows too
-/// and fails — historically swallowed silently, wedging the session so every
-/// later turn failed at the same huge token count (issue #88). Surface the
-/// failure and, when `trim_on_fail`, emergency-trim so the next turn has
-/// room. Best-effort; never throws into the REPL loop.
-pub fn repeatedOpaqueCompactionFailure(self: *Agent, err: anyerror) bool {
- const opaque_transport = err == error.ApiError and self.last_request_write_failed;
- if (opaque_transport)
- self.compact_transport_failures +|= 1
- else
- self.compact_transport_failures = 0;
- const threshold = self.provider.compactAt();
- const effective = self.effectiveContextTokens();
- const locally_over_window = self.provider.context > 0 and self.fullRequestEstimateTokens() >= self.provider.context;
- return opaque_transport and
- threshold > 0 and
- self.compact_transport_failures >= 2 and
- (self.provider.nearContextLimit(effective) or locally_over_window);
-}
-
-/// #379: two consecutive COMPLETED-but-unusable summaries (empty or truncated)
-/// are provably not transport noise — the model, at this context size, is not
-/// going to produce one, and without escalation the over-cap history is
-/// re-shipped forever. Unlike compact_transport_failures this counter survives
-/// a complete response; only a usable summary (or a trim) resets it.
-pub fn repeatedEmptySummaryFailure(self: *Agent, err: anyerror) bool {
- const unusable = err == error.EmptySummary or err == error.IncompleteSummary;
- if (unusable) self.compact_summary_failures +|= 1 else self.compact_summary_failures = 0;
- const threshold = self.provider.compactAt();
- return unusable and threshold > 0 and
- self.compact_summary_failures >= 2 and
- self.effectiveContextTokens() >= threshold;
-}
-
-pub fn compactOrRecover(self: *Agent, trim_on_fail: bool) void {
- if (compact_cut.lastIsResolved(self.messages.items)) {
- self.compact_pin_degraded = false;
- compact_cut.resetStall(&self.compact_stall);
- }
- if (self.compact_pin_degraded and !trim_on_fail) return;
- const has_opaque = @import("compaction_window.zig").latestBlob(self.messages.items) != null;
- const result = if (has_opaque or server_compact.serverOnly(self.provider)) server_compact.manualCompact(self) else self.compact();
- if (result) |_| {
- self.compact_transport_failures = 0;
- return;
- } else |err| {
- switch (err) {
- error.Interrupted => {
- self.compact_transport_failures = 0;
- return; // user hit Esc mid-compaction
- },
- error.EmptySummary, error.IncompleteSummary, error.ActivePromptPinned => {}, // compact() already explained it
- else => {
- if (main_mod.json_mode)
- self.emit(.{ .type = "error", .message = std.fmt.allocPrint(self.arena, "auto-compaction failed: {s}", .{@errorName(err)}) catch "auto-compaction failed" })
- else
- self.say("[auto-compaction failed: {t}]\n", .{err}) catch {};
- },
- }
- if (has_opaque) return; // server failed: preserve its canonical window, never emergency-trim it
- const repeated_opaque_overflow = repeatedOpaqueCompactionFailure(self, err);
- const repeated_empty_summary = repeatedEmptySummaryFailure(self, err);
- // The caller's policy is computed before compact() makes its summary
- // request. Override it only for a concrete provider overflow rejection,
- // after two consecutive WriteFailed compaction attempts when the
- // effective meter is near 95% (or local bytes prove over-window), or
- // after two complete-but-unusable summaries while over compact@ (#379).
- // The first failure and ordinary transport outages preserve history.
- if (!trim_on_fail and !self.last_request_context_overflow and !repeated_opaque_overflow and !repeated_empty_summary) return;
- const dropped = self.emergencyTrim();
- if (dropped > 0) {
- self.compact_transport_failures = 0;
- self.compact_summary_failures = 0;
- // #445: a trim is the harsher half of the same boundary — the model
- // lost that history WITHOUT even a summary standing in for it, so
- // the transcript line is worth more here, not less. Hooked at this
- // call site rather than inside emergencyTrim() because the direct
- // emergencyTrim callers drive partially-initialized test agents.
- prompts.noteSessionCompacted(self, self.arena);
- @import("hot_context.zig").afterCompact(self);
- if (main_mod.json_mode)
- self.emit(.{ .type = "compact", .ok = true, .trimmed = dropped })
- else
- self.say("[context emergency-trimmed: dropped {d} old message(s) so the session can continue]\n", .{dropped}) catch {};
- } else if (!main_mod.json_mode) {
- self.say("[warning: context too large to compact and could not be trimmed safely]\n", .{}) catch {};
- }
- }
-}
+/// Re-exported recovery entry points (agent_compact_recover.zig owns them).
+pub const emergencyTrim = @import("agent_compact_recover.zig").emergencyTrim;
+pub const repeatedOpaqueCompactionFailure = @import("agent_compact_recover.zig").repeatedOpaqueCompactionFailure;
+pub const repeatedEmptySummaryFailure = @import("agent_compact_recover.zig").repeatedEmptySummaryFailure;
+pub const compactOrRecover = @import("agent_compact_recover.zig").compactOrRecover;
diff --git a/src/agent_compact_recover.zig b/src/agent_compact_recover.zig
new file mode 100644
index 00000000..bc87c2a9
--- /dev/null
+++ b/src/agent_compact_recover.zig
@@ -0,0 +1,153 @@
+//! Last-resort context recovery when compact() itself can't run.
+//!
+//! Split from agent_compact.zig for the 600-line ceiling: the summary path
+//! owns history rewriting, this module owns what happens when the summary
+//! request itself cannot run (overflow) or twice proves unusable. Re-exported
+//! through agent_compact so existing call sites and tests keep compiling.
+
+const std = @import("std");
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+
+const main_mod = @import("main.zig");
+const agent_mod = @import("agent.zig");
+const Agent = agent_mod.Agent;
+const goal_flow = @import("goal_flow.zig");
+const prompts = @import("prompts.zig");
+const compact_cut = @import("compact_cut.zig");
+const compact = @import("agent_compact.zig");
+const server_compact = @import("agent_server_compact.zig");
+
+const emergencyCutIndex = compact_cut.emergencyCutIndex;
+
+/// Last-resort context recovery when compact() itself can't run — typically
+/// because the history already overflows the window, so the summarization
+/// request overflows too and fails. Drops the oldest messages at a safe
+/// boundary; returns the count dropped (0 if none). Conservatively reduce the
+/// authoritative meter only by the locally measurable reclaimed tokens: hidden
+/// server-side reasoning may make the true reduction larger, but must never let
+/// a partial trim blind the next pre-send gate.
+pub fn emergencyTrim(self: *Agent) usize {
+ if (emergencyCutIndex(self.messages.items)) |cut| {
+ const before_tokens = self.fullInputEstimateTokens();
+ var fresh = std.json.Array.init(self.arena);
+ for (self.messages.items[cut..]) |m| fresh.append(m) catch return 0;
+ self.messages = fresh;
+ self.goal_note_fp = 0; // trimmed history may have carried the goal note (#318)
+ self.history_rewrites +%= 1; // and the run's checklist gate's pasted copies (#318)
+ // No synthetic message exists here to hang the standing state on (unlike
+ // compact()'s handoff), so it rides the next turn's one-shot slot. Only
+ // when that slot is free: a queued /goal replace|clear note is the USER's
+ // instruction and outranks the harness restating itself (#318).
+ if (self.pending_goal_note == null)
+ self.pending_goal_note = goal_flow.compactionSnapshot(self.arena, self) catch null;
+ const after_tokens = self.fullInputEstimateTokens();
+ compact.accountForReclaimedTokens(self, before_tokens -| after_tokens);
+ return cut;
+ }
+ // #163: no clean user turn to cut at (a runaway tool loop). Don't wedge the
+ // session — reclaim context by truncating the oldest tool outputs in place,
+ // keeping every call/output pair valid. Nonzero = recovered. This too is a
+ // rewrite: the stubbed outputs may include the last todo_write render the
+ // suppressed run note points the model at (#318).
+ if (compact.trimOldestToolOutputs(self) > 0) {
+ self.history_rewrites +%= 1;
+ if (self.pending_goal_note == null)
+ self.pending_goal_note = goal_flow.compactionSnapshot(self.arena, self) catch null;
+ return 1;
+ }
+ return 0;
+}
+
+/// Auto-compaction with recovery. compact() summarizes the whole history in
+/// one request; once context overflows the window that request overflows too
+/// and fails — historically swallowed silently, wedging the session so every
+/// later turn failed at the same huge token count (issue #88). Surface the
+/// failure and, when `trim_on_fail`, emergency-trim so the next turn has
+/// room. Best-effort; never throws into the REPL loop.
+pub fn repeatedOpaqueCompactionFailure(self: *Agent, err: anyerror) bool {
+ const opaque_transport = err == error.ApiError and self.last_request_write_failed;
+ if (opaque_transport)
+ self.compact_transport_failures +|= 1
+ else
+ self.compact_transport_failures = 0;
+ const threshold = self.provider.compactAt();
+ const effective = self.effectiveContextTokens();
+ const locally_over_window = self.provider.context > 0 and self.fullRequestEstimateTokens() >= self.provider.context;
+ return opaque_transport and
+ threshold > 0 and
+ self.compact_transport_failures >= 2 and
+ (self.provider.nearContextLimit(effective) or locally_over_window);
+}
+
+/// #379: two consecutive COMPLETED-but-unusable summaries (empty or truncated)
+/// are provably not transport noise — the model, at this context size, is not
+/// going to produce one, and without escalation the over-cap history is
+/// re-shipped forever. Unlike compact_transport_failures this counter survives
+/// a complete response; only a usable summary (or a trim) resets it.
+pub fn repeatedEmptySummaryFailure(self: *Agent, err: anyerror) bool {
+ const unusable = err == error.EmptySummary or err == error.IncompleteSummary;
+ if (unusable) self.compact_summary_failures +|= 1 else self.compact_summary_failures = 0;
+ const threshold = self.provider.compactAt();
+ return unusable and threshold > 0 and
+ self.compact_summary_failures >= 2 and
+ self.effectiveContextTokens() >= threshold;
+}
+
+pub fn compactOrRecover(self: *Agent, trim_on_fail: bool) void {
+ if (compact_cut.lastIsResolved(self.messages.items)) {
+ self.compact_pin_degraded = false;
+ compact_cut.resetStall(&self.compact_stall);
+ }
+ if (self.compact_pin_degraded and !trim_on_fail) return;
+ const has_opaque = @import("compaction_window.zig").latestBlob(self.messages.items) != null;
+ // ADR 0259: first-party Responses routes compact only server-side, so they
+ // never reach compact() (the client summary, or Clef's hook at its top).
+ const result = if (has_opaque or server_compact.serverOnly(self.provider)) server_compact.manualCompact(self) else self.compact();
+ if (result) |_| {
+ self.compact_transport_failures = 0;
+ return;
+ } else |err| {
+ switch (err) {
+ error.Interrupted => {
+ self.compact_transport_failures = 0;
+ return; // user hit Esc mid-compaction
+ },
+ error.EmptySummary, error.IncompleteSummary, error.ActivePromptPinned => {}, // compact() already explained it
+ else => {
+ if (main_mod.json_mode)
+ self.emit(.{ .type = "error", .message = std.fmt.allocPrint(self.arena, "auto-compaction failed: {s}", .{@errorName(err)}) catch "auto-compaction failed" })
+ else
+ self.say("[auto-compaction failed: {t}]\n", .{err}) catch {};
+ },
+ }
+ if (has_opaque) return; // server failed: preserve its canonical window, never emergency-trim it
+ const repeated_opaque_overflow = repeatedOpaqueCompactionFailure(self, err);
+ const repeated_empty_summary = repeatedEmptySummaryFailure(self, err);
+ // The caller's policy is computed before compact() makes its summary
+ // request. Override it only for a concrete provider overflow rejection,
+ // after two consecutive WriteFailed compaction attempts when the
+ // effective meter is near 95% (or local bytes prove over-window), or
+ // after two complete-but-unusable summaries while over compact@ (#379).
+ // The first failure and ordinary transport outages preserve history.
+ if (!trim_on_fail and !self.last_request_context_overflow and !repeated_opaque_overflow and !repeated_empty_summary) return;
+ const dropped = self.emergencyTrim();
+ if (dropped > 0) {
+ self.compact_transport_failures = 0;
+ self.compact_summary_failures = 0;
+ // #445: a trim is the harsher half of the same boundary — the model
+ // lost that history WITHOUT even a summary standing in for it, so
+ // the transcript line is worth more here, not less. Hooked at this
+ // call site rather than inside emergencyTrim() because the direct
+ // emergencyTrim callers drive partially-initialized test agents.
+ prompts.noteSessionCompacted(self, self.arena);
+ @import("hot_context.zig").afterCompact(self);
+ if (main_mod.json_mode)
+ self.emit(.{ .type = "compact", .ok = true, .trimmed = dropped })
+ else
+ self.say("[context emergency-trimmed: dropped {d} old message(s) so the session can continue]\n", .{dropped}) catch {};
+ } else if (!main_mod.json_mode) {
+ self.say("[warning: context too large to compact and could not be trimmed safely]\n", .{}) catch {};
+ }
+ }
+}
diff --git a/src/main.zig b/src/main.zig
index 53551369..ab1fa750 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -584,7 +584,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = @import("learn_delete.zig"); // #303: its tests were dead until listed here
_ = .{ @import("additional_tests.zig"), @import("req_stats.zig"), @import("exact_reply.zig"), @import("rlm_order_tests.zig"), @import("async_tool_policy.zig"), @import("agent_async_tools.zig"), @import("request_usage_attempts.zig"), @import("learn_formal.zig") };
_ = @import("goal_pacing_autonomous_test.zig");
- _ = @import("goal_state.zig");
+ _ = .{ @import("goal_state.zig"), @import("agent_compact_recover.zig"), @import("agent_clef_compact.zig"), @import("agent_clef_compact_tests.zig"), @import("agent_clef_archive.zig") }; // + compaction recovery split, Clef arm (ADR 0260/0261)
_ = @import("goal_persist_tests.zig");
_ = @import("agent_render_cleanup.zig");
_ = .{ @import("goal_flow.zig"), @import("shell_identity.zig") };
diff --git a/src/session_settings.zig b/src/session_settings.zig
index 2c278ff6..485963b6 100644
--- a/src/session_settings.zig
+++ b/src/session_settings.zig
@@ -31,6 +31,7 @@ const mcp_schema_gate = @import("mcp_schema_gate.zig"); // GRAFF_STABLE_CATALOG
const no_local_tools = @import("no_local_tools.zig"); // #330: GRAFF_NO_LOCAL_TOOLS
const tool_handle = @import("tool_handle.zig"); // #440: GRAFF_TOOL_HANDLE_BYTES
const server_compact = @import("agent_server_compact.zig"); // GRAFF_SERVER_COMPACT + #compact-ab assignment
+const clef_compact = @import("agent_clef_compact.zig"); // GRAFF_CLEF_COMPACT → g_enabled
const provider_mod = @import("provider.zig");
const xai_hosted = @import("xai_hosted.zig"); // GRAFF_XAI_X_SEARCH
const skills = @import("skills.zig");
@@ -221,6 +222,21 @@ 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");
@import("compact_mix.zig").g_enabled = !off;
}
+ // GRAFF_CLEF_COMPACT=1 (any value but 0/false/off) routes client-summary
+ // compactions through the gateway's POST /v1/compact (Clef decision-model
+ // pruning). Default off: the client summary is the compactor (ADR 0261).
+ // First-party Responses routes never reach either (ADR 0259).
+ if (environ_map.get("GRAFF_CLEF_COMPACT")) |v| {
+ const off = std.mem.eql(u8, v, "0") or std.ascii.eqlIgnoreCase(v, "false") or std.ascii.eqlIgnoreCase(v, "off");
+ clef_compact.g_enabled = !off;
+ }
+ // GRAFF_CLEF_ARCHIVE=1/true/on: Clef prunes keep the call and archive the
+ // full output to the session's artifact dir (path in the stub) instead of
+ // deleting it. Default off while evals/clef_exp prices it.
+ if (environ_map.get("GRAFF_CLEF_ARCHIVE")) |v| {
+ const off = std.mem.eql(u8, v, "0") or std.ascii.eqlIgnoreCase(v, "false") or std.ascii.eqlIgnoreCase(v, "off");
+ @import("agent_clef_archive.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 edd1a3ba..eccd9850 100644
--- a/src/session_settings_tests.zig
+++ b/src/session_settings_tests.zig
@@ -55,6 +55,8 @@ const knobs = [_]Knob{
.{ .name = "GRAFF_TOOL_HANDLE_BYTES", .value = "8192" },
.{ .name = "GRAFF_COMPACT_PCT", .value = "55" },
.{ .name = "GRAFF_COMPACT_MIX", .value = "1" },
+ .{ .name = "GRAFF_CLEF_COMPACT", .value = "1" },
+ .{ .name = "GRAFF_CLEF_ARCHIVE", .value = "1" },
.{ .name = "GRAFF_WS_DEBUG", .value = "1" },
.{ .name = "GRAFF_WS_FORCE_FAIL_ONCE", .value = "1" },
.{ .name = "GRAFF_WS_FORCE_FAIL_COUNT", .value = "3" },
@@ -120,6 +122,8 @@ const Saved = struct {
x_search: bool,
job_idle: job_idle.Policy,
compact_mix: bool,
+ clef_compact: bool,
+ clef_archive: bool,
fn capture() Saved {
return .{
@@ -153,6 +157,8 @@ const Saved = struct {
.x_search = @import("xai_hosted.zig").enabled,
.job_idle = job_idle.policy,
.compact_mix = @import("compact_mix.zig").g_enabled,
+ .clef_compact = @import("agent_clef_compact.zig").g_enabled,
+ .clef_archive = @import("agent_clef_archive.zig").g_enabled,
};
}
@@ -188,6 +194,8 @@ const Saved = struct {
@import("xai_hosted.zig").enabled = s.x_search;
job_idle.policy = s.job_idle;
@import("compact_mix.zig").g_enabled = s.compact_mix;
+ @import("agent_clef_compact.zig").g_enabled = s.clef_compact;
+ @import("agent_clef_archive.zig").g_enabled = s.clef_archive;
}
};
diff --git a/src/tool_spill.zig b/src/tool_spill.zig
index b93326d6..e36ac616 100644
--- a/src/tool_spill.zig
+++ b/src/tool_spill.zig
@@ -133,8 +133,9 @@ pub const Note = struct {
/// Write `full` to this session's artifact dir; the ABSOLUTE path on success.
/// Null — i.e. plain truncation — when no durable session is wired, when the
-/// per-session budget is spent, or when any part of the write fails.
-fn spill(arena: Allocator, session: []const u8, full: []const u8) ?[]const u8 {
+/// per-session budget is spent, or when any part of the write fails. Public
+/// for agent_clef_archive.zig, which archives pruned outputs the same way.
+pub fn spill(arena: Allocator, session: []const u8, full: []const u8) ?[]const u8 {
const sink = g_sink orelse return null;
if (!safeName(session)) return null;
if (!reserve(full.len)) return null;