Skip to content

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

Python

Merge origin/main into the OpenAI 12h cache branch; 12h is opt-in (ADR 0312)

justrachb87dc610d315
diff --cc docs/adr/0009-gpt-5-6-explicit-prompt-cache-boundary.md
index 8e8ee401,e9b7747f..a15174c9
--- a/docs/adr/0009-gpt-5-6-explicit-prompt-cache-boundary.md
+++ b/docs/adr/0009-gpt-5-6-explicit-prompt-cache-boundary.md
@@@ -29,9 -29,8 +29,9 @@@ unsupported parameter, so its supporte
- Root sessions use `prompt_cache_options.mode = "implicit"`: the explicit
stable prefix remains reusable while append-only conversation turns keep the
useful latest-message checkpoint. Subagents use `mode = "explicit"` so their
- unique task suffix is not written at 1.25× input price. Both use the documented
- 30-minute TTL.
+ unique task suffix is not written at 1.25× input price. The request TTL
- stays 30 minutes; ADR 0298 puts `ttl: "12h"` on the stable-prefix
++ stays 30 minutes; ADR 0312 can put `ttl: "12h"` (opt-in) on the stable-prefix
+ breakpoint (configurable via `GRAFF_OPENAI_CACHE_TTL`).
- Root OpenAI/Codex requests keep the durable project key. Child prefix traffic
is deterministically spread over four stable role lanes to stay below the
documented approximately 15 requests/minute per-key guidance while preserving
diff --cc docs/adr/0312-openai-12h-prompt-cache-is-opt-in.md
index 7a1f1afb,00000000..414d0b6a
mode 100644,000000..100644
--- a/docs/adr/0312-openai-12h-prompt-cache-is-opt-in.md
+++ b/docs/adr/0312-openai-12h-prompt-cache-is-opt-in.md
@@@ -1,36 -1,0 +1,42 @@@
- # 0298. OpenAI Platform 12-hour prompt cache on the stable prefix
++# 0312. OpenAI Platform 12-hour prompt cache on the stable prefix is opt-in
+
- Status: accepted 2026-10-21
++Status: accepted 2026-11-02 (proposed 2026-10-21 as 0298)
+
+## Context
+
+On 2026-10-20 OpenAI added a 12-hour minimum lifetime for prompt-cache
+writes on GPT-5.6 and later, in the Responses API only. A 12-hour write
+costs 2.5× uncached input; a 30-minute write stays 1.25×. Reads stay 0.1×
+(0.05× on GPT-6.1 Sol). Chat Completions currently accepts only `ttl:
+"30m"`; sending `12h` there, or to older models, is a 400
+`invalid_request_error`. Older models keep the separate
+`prompt_cache_retention` parameter.
+
+ADR 0009 already marks graff's stable instructions/tools prefix with an
+explicit breakpoint and uses a 30-minute request TTL. Long-lived sessions
+pay to rewrite that prefix after a 30-minute gap.
+
+## Decision
+
- - On the direct OpenAI Responses route for GPT-5.6 and later, the stable
- prefix breakpoint sends `prompt_cache_breakpoint.ttl = "12h"`. The
- request keeps `prompt_cache_options.ttl = "30m"` for session context.
- The current user turn is never marked.
++- On the direct OpenAI Responses route for GPT-5.6 and later, with 12h
++ selected, the stable prefix breakpoint sends
++ `prompt_cache_breakpoint.ttl = "12h"`. The request keeps
++ `prompt_cache_options.ttl = "30m"` for session context. The current user
++ turn is never marked.
+- `GRAFF_OPENAI_CACHE_TTL` / `.harness/settings.json` `openai_cache_ttl`
- select `12h` (default), `30m` (ADR 0009 bytes), or `off`.
++ select `30m` (default, ADR 0009 bytes), `12h`, or `off`.
++- 12h is opt-in until a live probe records it. The API reference still
++ documents only `"30m"`, an unsupported value is a 400 on every request,
++ and a 12-hour write costs 2.5× uncached input against 1.25×, so the
++ default changes only after `scripts/openai_cache_retention_probe write`
++ succeeds and a later `--check` shows the prefix still cached.
+- Chat Completions, Codex, ChatGPT-new, xAI, and models before GPT-5.6
+ receive no new fields.
+- `prompt_cache_key` is unchanged. Usage parses `cached_tokens`,
+ `cache_write_tokens`, and `cache_write_tokens_details`.
+
+## Consequences
+
- The cold prefix write costs 2.5× instead of 1.25× when 12h is on. A later
++With the default nothing changes on the wire. The cold prefix write costs 2.5× instead of 1.25× when 12h is on. A later
+request hours later can still read that prefix. Codex remains on its
+keyed automatic path: it 400s on `prompt_cache_options`.
diff --cc docs/adr/README.md
index 4a1ba7b4,0716838e..d1df2ed4
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@@ -19,7 -19,7 +19,7 @@@ record only when you need the evidence
| [0006](0006-workspace-switch-is-a-tool.md) | Mid-session worktree switch is a real `workspace` tool; a skill cannot move file-tool cwd. |
| [0007](0007-plugins-are-read-in-place.md) | Cursor/Claude/Grok/Codex plugins and MCP are read in place (Claude/Cursor cache via installed_plugins.json, Codex via config.toml PluginStore, never walked); skills stay on-demand; MCP stays consent-gated. |
| [0008](0008-synthetic-evals-use-external-verifiers.md) | Synthetic coding evals promote only external-verifier passes; model judges may tiebreak correctness, never decide it. |
- | [0009](0009-gpt-5-6-explicit-prompt-cache-boundary.md) | GPT-5.6 OpenAI Platform marks the stable prefix explicitly; Codex and xAI stay on their supported keyed automatic-cache paths. 12h lifetime: [0298](0298-openai-12h-prompt-cache.md). |
-| [0009](0009-gpt-5-6-explicit-prompt-cache-boundary.md) | GPT-5.6 OpenAI Platform marks the stable prefix explicitly; Codex and xAI stay on their supported keyed automatic-cache paths. |
++| [0009](0009-gpt-5-6-explicit-prompt-cache-boundary.md) | GPT-5.6 OpenAI Platform marks the stable prefix explicitly; Codex and xAI stay on their supported keyed automatic-cache paths. 12h lifetime (opt-in): [0312](0312-openai-12h-prompt-cache-is-opt-in.md). |
| [0010](0010-background-jobs-wait-for-exit.md) | `bash_output`/`agent_output` `wait_ms>0` blocks until exit (10h cap); do not poll every 30s. |
| [0011](0011-prompt-cache-max-is-visible.md) | Prompt-cache max is on: stable catalog by default; `/cache` is the HUD; `/btw` rides the parent prefix; children share role-lane `x-grok-conv-id` / `prompt_cache_key` (not the root id). |
| [0012](0012-overflow-handles-named-limits-extra-roots.md) | Fat tool results become `tr_N` handles; named `--context-limit` caps prefix bytes; `--add-dir` extra roots are PathConfine allow-lists, not cwd/skill/session sources. |
@@@ -315,7 -315,28 +315,29 @@@
| [0295](0295-worker-native-turns-share-the-chat-step.md) | Experimental Worker-native turns share the native chat step; JSPI supplies bounded host I/O, not a proxy or a second agent loop. |
| [0296](0296-worker-tasks-own-remote-sandbox-cleanup.md) | Worker/DO tasks retain the agent loop and delegate Linux execution to remote sandboxes with explicit ownership, deletion and bounded leases. |
| [0297](0297-sdk-managed-replay-reuses-the-relay.md) | The fetch-only managed SDK reuses account relay/device tapes; prompt retries are explicit, durability limits are stated, and content-free OTLP export remains opt-in and observational. |
- | [0298](0298-openai-12h-prompt-cache.md) | OpenAI Responses GPT-5.6+ puts a 12h explicit breakpoint on the stable prefix and keeps a 30m request default; Chat Completions and older models get no new fields. |
+ | [0298](0298-peer-send-wakes-are-bounded.md) | A `graff peer send` live wake is concurrent and bounded by one shared deadline; misses are reported and the durable room post still succeeds. |
+
+ | [0299](0299-conversation-history-forks-are-explicit.md) | `fork_from` explicitly snapshots current, project-local saved, or family-owned worker history into independent children; lightweight delegation stays the default and `retained` remains opt-in across subagents and workflows. |
+
+ | [0300](0300-workflow-synthesis-has-a-report-boundary.md) | Synthesis gets bounded evidence requests and a final report-only request; cancelled or exhausted workers are not restarted and failed stages retain prior evidence. |
+ | [0298](0298-recurrence-reports-update-issue-state.md) | A current unresolved recurrence reopens the canonical resolved issue; comments alone do not complete reporting, intentional closures remain respected, and final state is verified. |
+ | [0299](0299-tool-commands-launch-apps-in-the-background.md) | On macOS tool commands' `open` launches apps without activating them (a `-g` shim first on the tool PATH); `GRAFF_GUI_FOREGROUND=1` on a command is the explicit foreground opt-in. |
+ | [0300](0300-a-session-shuts-down-the-simulators-it-booted.md) | Shell commands that look like simulator work are bracketed by booted-device snapshots; devices a session booted are leased under `~/.codegraff/simulators/` and shut down when the last live leaseholder ends, never devices booted before. `GRAFF_KEEP_SIMULATORS=1` opts out. |
+
+ | [0301](0301-failed-requests-settle-the-pending-turn.md) | Exhausted request retries leave a truthful failure boundary in history so an identical prompt can run after reconnecting, including after save/load; duplicate-host protection and bounded retries stay unchanged. |
+ | [0302](0302-terminal-repl-chrome-stays-in-the-terminal.md) | Refine the line REPL's terminal sinks: quiet status hierarchy, mode-first width priority and active-work emphasis, without native windows or changing the editor, engine or external fullscreen client. |
+
+ | [0303](0303-terminal-markdown-and-worker-inspection.md) | The line REPL renders inline emphasis and offers a temporary mouse/keyboard `/workers` inspector over the existing bounded ACP child feed, without replacing the editor or changing engine behavior. |
+ | [0304](0304-file-tools-allow-in-root-symlinks.md) | File tools allow canonical in-root symlinks, reject escaping or unresolved links, and retain lexical confinement and missing write targets; the check is not an atomic sandbox. |
+ | [0305](0305-cancelled-checklist-items-carry-a-reason.md) | A `cancelled` todo needs a short reason or the write is rejected whole; it stays listed with that reason, stops blocking completion and never counts as verified. A verification item can be cancelled after a newer user message or an answered `ask_user`. |
+ | [0306](0306-model-catalogs-never-hold-startup.md) | Boot and `graff/models` never wait on a catalog GET past a budget: cached catalogs activate now and refresh behind on detached workers whose only output is the disk cache; only uncached ones wait, together, up to 800ms. |
+ | [0307](0307-resumed-sessions-keep-their-compaction-state-count.md) | A session saves the provider's count of its compaction state, scoped to provider, model, size and digest; loading reapplies it before rebasing the meter, so a restart neither inflates the meter nor forces a compaction. |
+ | [0309](0309-claude-agent-runs-the-users-claude.md) | Claude Agent runs the user's own `claude` over the SDK control protocol: graff's tools as an in-process MCP server with held calls, graff's history as the source of truth, never reading Claude Code's login. |
+ | [0310](0310-auth-failures-name-the-rejected-credential.md) | A terminal auth rejection names the seat that failed: sign-in text keeps "sign in again"; key and promoted-key texts say "API key was rejected" and never the signed-out phrases. Key seats carry `{"kind":"api_key_rejected","provider":…}` (v1 `-32603` data, v2 `_meta["graff/recovery"]`); `reauth_required` is unchanged. |
+ | [0311](0311-tool-refresh-and-addressed-wakes.md) | Claude Agent refreshes a changed tool list with MCP `tools/list_changed` (served before anything else; fresh session if not re-read in 15 s) instead of removing and re-adding its server, which failed held calls. `attempt_completion` settles a task like a final answer: room mail waits for the next human prompt, addressed mail can still start a turn; `yield_turn` stays strict. A peer wake preloads `peer_message`. |
++| [0312](0312-openai-12h-prompt-cache-is-opt-in.md) | OpenAI Responses GPT-5.6+ can put a 12h explicit breakpoint on the stable prefix (`GRAFF_OPENAI_CACHE_TTL=12h` or `openai_cache_ttl`); the default stays 30m (ADR 0009 bytes) until a live probe confirms OpenAI accepts the field and keeps the entry. Usage parses cache writes by TTL. |
+
+ | [0302](0302-sse-idle-watchdogs-follow-body-byte-progress.md) | SSE idle watchdogs observe partial body-byte progress, while separate unfinished-event time and size bounds preserve recovery. |
## When to write one
diff --cc src/agent_request_body_cache_test.zig
index 4277ae35,e0613474..9deef82f
--- a/src/agent_request_body_cache_test.zig
+++ b/src/agent_request_body_cache_test.zig
@@@ -43,112 -25,56 +43,157 @@@ test "GPT-5.6 and later Platform marks
const wb = try worker.buildBody(null, false, true, true);
defer std.testing.allocator.free(wb);
try std.testing.expect(std.mem.indexOf(u8, wb, "\"prompt_cache_options\":{\"mode\":\"explicit\",\"ttl\":\"30m\"}") != null);
+ try std.testing.expect(std.mem.indexOf(u8, wb, "\"prompt_cache_breakpoint\":{\"mode\":\"explicit\",\"ttl\":\"12h\"}") != null);
+
+ var sol = try bodies.testAgentFor(a, "openai", .responses, "gpt-6.1-sol");
+ const sb = try sol.buildBody(null, false, true, true);
+ defer std.testing.allocator.free(sb);
+ try std.testing.expect(std.mem.indexOf(u8, sb, "\"prompt_cache_breakpoint\":{\"mode\":\"explicit\",\"ttl\":\"12h\"}") != null);
+}
+
+test "OpenAI cache TTL 30m keeps the previous GPT-5.6 Responses bytes" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ cache.setOverride(.thirty_m);
+ defer cache.clearOverride();
- var codex = try bodies.testAgentFor(a, "codex", .responses, "gpt-5.6-sol");
- const cb = try codex.buildBody(null, false, true, true);
- defer std.testing.allocator.free(cb);
- try std.testing.expect(std.mem.indexOf(u8, cb, "prompt_cache_options") == null);
- try std.testing.expect(std.mem.indexOf(u8, cb, "prompt_cache_breakpoint") == null);
-
- var astra_codex = try bodies.testAgentFor(a, "codex", .responses, "gpt-6-astra");
- const ac = try astra_codex.buildBody(null, false, true, true);
- defer std.testing.allocator.free(ac);
- try std.testing.expect(std.mem.indexOf(u8, ac, "prompt_cache_options") == null);
- try std.testing.expect(std.mem.indexOf(u8, ac, "prompt_cache_breakpoint") == null);
-
- var older = try bodies.testAgentFor(a, "openai", .responses, "gpt-5.5");
- const old = try older.buildBody(null, false, true, true);
- defer std.testing.allocator.free(old);
- try std.testing.expect(std.mem.indexOf(u8, old, "prompt_cache_breakpoint") == null);
- try std.testing.expect(std.mem.indexOf(u8, old, "prompt_cache_options") == null);
+ const ob = try bodyOf(a, "openai", .responses, "gpt-5.6");
+ defer std.testing.allocator.free(ob);
+ try std.testing.expect(std.mem.indexOf(u8, ob, "\"prompt_cache_options\":{\"mode\":\"implicit\",\"ttl\":\"30m\"}") != null);
+ try std.testing.expect(std.mem.indexOf(u8, ob, "\"prompt_cache_breakpoint\":{\"mode\":\"explicit\"}") != null);
+ try std.testing.expect(std.mem.indexOf(u8, ob, "\"ttl\":\"12h\"") == null);
+}
+
+test "OpenAI cache TTL off sends no Platform cache fields" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ cache.setOverride(.off);
+ defer cache.clearOverride();
+ const ob = try bodyOf(a, "openai", .responses, "gpt-5.6");
+ defer std.testing.allocator.free(ob);
+ try expectNoCacheFields(ob);
+}
+
+test "Chat Completions and older models stay byte-identical across TTL settings" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ defer cache.clearOverride();
+
+ cache.setOverride(.twelve_h);
+ const chat_12 = try bodyOf(a, "openai", .openai, "gpt-5.6");
+ defer std.testing.allocator.free(chat_12);
+ const old_12 = try bodyOf(a, "openai", .responses, "gpt-5.5");
+ defer std.testing.allocator.free(old_12);
+ const chat4_12 = try bodyOf(a, "openai", .openai, "gpt-4o");
+ defer std.testing.allocator.free(chat4_12);
+ const codex_12 = try bodyOf(a, "codex", .responses, "gpt-5.6-sol");
+ defer std.testing.allocator.free(codex_12);
+
+ cache.setOverride(.thirty_m);
+ const chat_30 = try bodyOf(a, "openai", .openai, "gpt-5.6");
+ defer std.testing.allocator.free(chat_30);
+ const old_30 = try bodyOf(a, "openai", .responses, "gpt-5.5");
+ defer std.testing.allocator.free(old_30);
+ const chat4_30 = try bodyOf(a, "openai", .openai, "gpt-4o");
+ defer std.testing.allocator.free(chat4_30);
+ const codex_30 = try bodyOf(a, "codex", .responses, "gpt-5.6-sol");
+ defer std.testing.allocator.free(codex_30);
+
+ cache.setOverride(.off);
+ const chat_off = try bodyOf(a, "openai", .openai, "gpt-5.6");
+ defer std.testing.allocator.free(chat_off);
+ const old_off = try bodyOf(a, "openai", .responses, "gpt-5.5");
+ defer std.testing.allocator.free(old_off);
+ const codex_off = try bodyOf(a, "codex", .responses, "gpt-5.6-sol");
+ defer std.testing.allocator.free(codex_off);
+
+ try std.testing.expectEqualStrings(chat_12, chat_30);
+ try std.testing.expectEqualStrings(chat_12, chat_off);
+ try std.testing.expectEqualStrings(old_12, old_30);
+ try std.testing.expectEqualStrings(old_12, old_off);
+ try std.testing.expectEqualStrings(chat4_12, chat4_30);
+ try std.testing.expectEqualStrings(codex_12, codex_30);
+ try std.testing.expectEqualStrings(codex_12, codex_off);
+ try expectNoCacheFields(chat_12);
+ try expectNoCacheFields(old_12);
+ try expectNoCacheFields(chat4_12);
+ try expectNoCacheFields(codex_12);
+}
+
+test "model x API x setting gate matrix" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ defer cache.clearOverride();
+
+ const Case = struct { id: []const u8, kind: @import("provider.zig").Provider.Kind, model: []const u8, ttl: cache.Ttl, want_12h: bool, want_options: bool };
+ const cases = [_]Case{
+ .{ .id = "openai", .kind = .responses, .model = "gpt-5.6", .ttl = .twelve_h, .want_12h = true, .want_options = true },
+ .{ .id = "openai", .kind = .responses, .model = "gpt-6-sol", .ttl = .twelve_h, .want_12h = true, .want_options = true },
+ .{ .id = "openai", .kind = .responses, .model = "gpt-5.6", .ttl = .thirty_m, .want_12h = false, .want_options = true },
+ .{ .id = "openai", .kind = .responses, .model = "gpt-5.6", .ttl = .off, .want_12h = false, .want_options = false },
+ .{ .id = "openai", .kind = .responses, .model = "gpt-5.5", .ttl = .twelve_h, .want_12h = false, .want_options = false },
+ .{ .id = "openai", .kind = .openai, .model = "gpt-5.6", .ttl = .twelve_h, .want_12h = false, .want_options = false },
+ .{ .id = "openai", .kind = .openai, .model = "gpt-6.1-sol", .ttl = .twelve_h, .want_12h = false, .want_options = false },
+ .{ .id = "codex", .kind = .responses, .model = "gpt-5.6-sol", .ttl = .twelve_h, .want_12h = false, .want_options = false },
+ .{ .id = "chatgpt-new", .kind = .responses, .model = "gpt-6.1-sol", .ttl = .twelve_h, .want_12h = false, .want_options = false },
+ .{ .id = "xai", .kind = .responses, .model = "grok-4.6", .ttl = .twelve_h, .want_12h = false, .want_options = false },
+ };
+ for (cases) |c| {
+ cache.setOverride(c.ttl);
+ const b = try bodyOf(a, c.id, c.kind, c.model);
+ defer std.testing.allocator.free(b);
+ const has_12h = std.mem.indexOf(u8, b, "\"ttl\":\"12h\"") != null;
+ const has_options = std.mem.indexOf(u8, b, "prompt_cache_options") != null;
+ try std.testing.expectEqual(c.want_12h, has_12h);
+ try std.testing.expectEqual(c.want_options, has_options);
+ }
}
+
+ test "workflow synthesis report keeps chat and Responses cache prefixes" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const catalog = "[{\"type\":\"function\",\"function\":{\"name\":\"ping\",\"description\":\"fixture\",\"parameters\":{\"type\":\"object\"}}}]";
+ for ([_]@import("provider.zig").Provider.Kind{ .openai, .responses }) |kind| {
+ var agent = try bodies.testAgentFor(a, "openai", kind, "gpt-5.6");
+ agent.sub = true;
+ agent.label = "synthesize";
+ agent.synthesis = .{ .enabled = true, .requests = 7 };
+ try agent.synthesis.beforeRequest(&agent);
+ const before = try agent.buildBody(catalog, true, true, true);
+ defer std.testing.allocator.free(before);
+ try agent.synthesis.beforeRequest(&agent);
+ const after = try agent.buildBody(if (agent.synthesis.keepsCatalog(&agent)) catalog else null, true, true, true);
+ defer std.testing.allocator.free(after);
+ const first = try std.json.parseFromSliceLeaky(std.json.Value, a, before, .{});
+ const report = try std.json.parseFromSliceLeaky(std.json.Value, a, after, .{});
+ try std.testing.expectEqualStrings(
+ try std.json.Stringify.valueAlloc(a, first.object.get("tools").?, .{}),
+ try std.json.Stringify.valueAlloc(a, report.object.get("tools").?, .{}),
+ );
+ try std.testing.expectEqualStrings(first.object.get("prompt_cache_key").?.string, report.object.get("prompt_cache_key").?.string);
+ const first_prefix = if (kind == .responses) first.object.get("instructions").? else first.object.get("messages").?.array.items[0];
+ const report_prefix = if (kind == .responses) report.object.get("instructions").? else report.object.get("messages").?.array.items[0];
+ try std.testing.expectEqualStrings(
+ try std.json.Stringify.valueAlloc(a, first_prefix, .{}),
+ try std.json.Stringify.valueAlloc(a, report_prefix, .{}),
+ );
+ try std.testing.expectEqualStrings("required", first.object.get("tool_choice").?.string);
+ try std.testing.expectEqualStrings("none", report.object.get("tool_choice").?.string);
+ }
+ }
++
++test "ADR 0312: the default sends no 12h ttl (opt-in until a live probe)" {
++ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
++ defer arena.deinit();
++ cache.clearOverride();
++ try std.testing.expectEqual(cache.Ttl.thirty_m, cache.default_ttl);
++ const b = try bodyOf(arena.allocator(), "openai", .responses, "gpt-5.6");
++ defer std.testing.allocator.free(b);
++ try std.testing.expect(std.mem.indexOf(u8, b, "\"prompt_cache_breakpoint\":{\"mode\":\"explicit\"}") != null);
++ try std.testing.expect(std.mem.indexOf(u8, b, "\"ttl\":\"12h\"") == null);
++}
diff --cc src/agent_request_body_responses.zig
index 020fc758,f359267e..5e799e17
--- a/src/agent_request_body_responses.zig
+++ b/src/agent_request_body_responses.zig
@@@ -29,10 -29,19 +29,10 @@@ pub fn write(self: *Agent, s: *std.json
var ckbuf: [96]u8 = undefined;
try s.objectField("prompt_cache_key");
try s.write(http_headers.requestCacheKey(self.io, self.label, self, self.provider, &ckbuf));
- const explicit_cache = supportsExplicitPromptCache(self);
- if (explicit_cache) {
- try s.objectField("prompt_cache_options");
- try s.beginObject();
- try s.objectField("mode");
- // Root conversations grow append-only, so retain the useful implicit
- // latest-message breakpoint. One-shot children cache only the shared
- // system+tools prefix and avoid paying to write each unique task suffix.
- try s.write(if (self.sub) "explicit" else "implicit");
- try s.objectField("ttl");
- try s.write("30m");
- try s.endObject();
- }
+ const oai_cache = @import("openai_prompt_cache.zig");
+ // Root keeps implicit latest-message (30m). Children are explicit-only so
- // a unique task suffix is not written. ADR 0298 puts 12h on the prefix.
++ // a unique task suffix is not written. ADR 0312 can put 12h on the prefix (opt-in).
+ if (oai_cache.active(self)) try oai_cache.writeOptions(s, self.sub);
// Held-socket delta: previous_response_id + only the new items. xAI's
// published WS contract supports this with store:false via the in-memory
// connection cache; a not-found / 25-min close / drop re-anchors.
diff --cc src/openai_prompt_cache.zig
index a773c17c,00000000..ee28e7aa
mode 100644,000000..100644
--- a/src/openai_prompt_cache.zig
+++ b/src/openai_prompt_cache.zig
@@@ -1,221 -1,0 +1,223 @@@
+//! OpenAI Platform prompt-cache TTL for GPT-5.6+ Responses.
+//!
+//! ADR 0009 already marks the stable prefix. This module adds the Oct 2026
+//! 12-hour lifetime on that breakpoint and keeps the request default at 30
+//! minutes for session context. Chat Completions and older models must not
+//! receive these fields: 12h is a 400 there.
+
+const std = @import("std");
+const Io = std.Io;
+const Agent = @import("agent.zig").Agent;
+const Provider = @import("provider.zig").Provider;
+
+pub const env_name = "GRAFF_OPENAI_CACHE_TTL";
+pub const settings_key = "openai_cache_ttl";
+
+pub const Ttl = enum {
+ off,
+ thirty_m,
+ twelve_h,
+
+ pub fn label(self: Ttl) []const u8 {
+ return switch (self) {
+ .off => "off",
+ .thirty_m => "30m",
+ .twelve_h => "12h",
+ };
+ }
+};
+
- pub const default_ttl: Ttl = .twelve_h;
++/// 30m sends ADR 0009's bytes. 12h stays opt-in until a live probe shows
++/// OpenAI accepts the field and keeps the entry (ADR 0312).
++pub const default_ttl: Ttl = .thirty_m;
+
+threadlocal var override_ttl: ?Ttl = null;
+var saved_ttl: ?Ttl = null;
+
+pub fn parse(text: []const u8) ?Ttl {
+ const t = std.mem.trim(u8, text, " \t\r\n");
+ if (t.len == 0) return null;
+ if (eqlAny(t, &.{ "off", "0", "false", "none", "disable" })) return .off;
+ if (eqlAny(t, &.{ "30m", "30", "30-min", "30min" })) return .thirty_m;
+ if (eqlAny(t, &.{ "12h", "12", "12-hour", "12hour" })) return .twelve_h;
+ return null;
+}
+
+pub fn setOverride(ttl: Ttl) void {
+ override_ttl = ttl;
+}
+
+pub fn clearOverride() void {
+ override_ttl = null;
+}
+
+pub fn current() Ttl {
+ if (override_ttl) |ttl| return ttl;
+ if (envTtl()) |ttl| return ttl;
+ return saved_ttl orelse default_ttl;
+}
+
+pub fn applyStartup(io: Io, arena: std.mem.Allocator) void {
+ saved_ttl = loadSaved(io, arena);
+}
+
+/// Direct OpenAI Responses on GPT-5.6 and later. Codex rejected these fields;
+/// Chat Completions and older models 400 on `ttl: "12h"`.
+pub fn supported(provider_id: []const u8, kind: Provider.Kind, model: []const u8) bool {
+ return std.mem.eql(u8, provider_id, "openai") and
+ kind == .responses and
+ @import("provider_codegraff.zig").openaiGptFamily(model);
+}
+
+pub fn active(self: *const Agent) bool {
+ return supported(self.provider.id, self.provider.kind, self.provider.model) and current() != .off;
+}
+
+pub fn writeOptions(s: *std.json.Stringify, explicit_only: bool) !void {
+ try s.objectField("prompt_cache_options");
+ try s.beginObject();
+ try s.objectField("mode");
+ try s.write(if (explicit_only) "explicit" else "implicit");
+ try s.objectField("ttl");
+ try s.write("30m");
+ try s.endObject();
+}
+
+/// Stable developer anchor after top-level instructions. Tools are part of
+/// the rendered prefix; the current user turn is never marked.
+pub fn writeAnchor(s: *std.json.Stringify) !void {
+ try s.beginObject();
+ try s.objectField("type");
+ try s.write("message");
+ try s.objectField("role");
+ try s.write("developer");
+ try s.objectField("content");
+ try s.beginArray();
+ try s.beginObject();
+ try s.objectField("type");
+ try s.write("input_text");
+ try s.objectField("text");
+ try s.write("The preceding instructions and available tools are the stable operating context for this session.");
+ try s.objectField("prompt_cache_breakpoint");
+ try s.beginObject();
+ try s.objectField("mode");
+ try s.write("explicit");
+ if (current() == .twelve_h) {
+ try s.objectField("ttl");
+ try s.write("12h");
+ }
+ try s.endObject();
+ try s.endObject();
+ try s.endArray();
+ try s.endObject();
+}
+
+pub const Usage = struct {
+ cached: i64 = 0,
+ written: i64 = 0,
+ write_30m: i64 = 0,
+ write_12h: i64 = 0,
+};
+
+pub fn readResponsesUsage(usage: std.json.ObjectMap) Usage {
+ return readDetails(usage, "input_tokens_details", 0);
+}
+
+pub fn readChatUsage(usage: std.json.ObjectMap) Usage {
+ return readDetails(usage, "prompt_tokens_details", usageInt(usage, "prompt_cache_hit_tokens"));
+}
+
+pub fn billTwelveHour(self: *Agent, usage: Usage) void {
+ if (usage.write_12h > 0) {
+ @import("prompt_cache_hud.zig").noteWriteSplit(@intCast(usage.write_12h), @intCast(@max(usage.write_30m, 0)));
+ @import("usage_trace.zig").noteWriteSplit(usage.write_12h, usage.write_30m);
+ }
+ if (usage.write_12h <= 0 or @import("billing.zig").forProvider(self.provider) != .priced) return;
+ const p = @import("pricing.zig").priceForProvider(self.provider.id, self.provider.model) orelse return;
+ const extra = @import("pricing_cache.zig").twelveHourWriteExtraUsd(p, self.provider.model, usage.write_12h);
+ if (extra == 0) return;
+ const pricing = @import("pricing.zig");
+ pricing.g_cost.mutex.lockUncancelable(self.io);
+ defer pricing.g_cost.mutex.unlock(self.io);
+ pricing.g_cost.usd += extra;
+}
+
+fn readDetails(usage: std.json.ObjectMap, field: []const u8, cached_in: i64) Usage {
+ var out: Usage = .{ .cached = cached_in };
+ const details = usage.get(field) orelse return out;
+ if (details != .object) return out;
+ if (out.cached == 0) out.cached = usageInt(details.object, "cached_tokens");
+ out.written = usageInt(details.object, "cache_write_tokens");
+ if (details.object.get("cache_write_tokens_details")) |split| if (split == .object) {
+ out.write_30m = usageInt(split.object, "ttl_30m_tokens");
+ out.write_12h = usageInt(split.object, "ttl_12h_tokens");
+ };
+ return out;
+}
+
+fn usageInt(obj: std.json.ObjectMap, name: []const u8) i64 {
+ if (obj.get(name)) |v| if (v == .integer and v.integer > 0) return v.integer;
+ return 0;
+}
+
+fn envTtl() ?Ttl {
+ const raw = std.c.getenv(env_name) orelse return null;
+ return parse(std.mem.span(raw));
+}
+
+fn loadSaved(io: Io, arena: std.mem.Allocator) ?Ttl {
+ const data = Io.Dir.cwd().readFileAlloc(io, @import("harness_policy.zig").settings_path, arena, .limited(1 << 20)) catch return null;
+ const v = std.json.parseFromSliceLeaky(std.json.Value, arena, data, .{ .allocate = .alloc_always }) catch return null;
+ if (v != .object) return null;
+ const saved = v.object.get(settings_key) orelse return null;
+ if (saved != .string) return null;
+ return parse(saved.string);
+}
+
+fn eqlAny(text: []const u8, names: []const []const u8) bool {
+ for (names) |n| if (std.ascii.eqlIgnoreCase(text, n)) return true;
+ return false;
+}
+
+test "TTL parse accepts the documented knobs" {
+ try std.testing.expectEqual(Ttl.off, parse("off").?);
+ try std.testing.expectEqual(Ttl.thirty_m, parse("30m").?);
+ try std.testing.expectEqual(Ttl.twelve_h, parse("12h").?);
+ try std.testing.expect(parse("tomorrow") == null);
+}
+
+test "12h is Responses GPT-5.6+ on the OpenAI provider only" {
+ const Kind = Provider.Kind;
+ try std.testing.expect(supported("openai", .responses, "gpt-5.6"));
+ try std.testing.expect(supported("openai", .responses, "gpt-5.6-luna"));
+ try std.testing.expect(supported("openai", .responses, "gpt-6-astra"));
+ try std.testing.expect(supported("openai", .responses, "gpt-6.1-sol"));
+ try std.testing.expect(!supported("openai", .responses, "gpt-5.5"));
+ try std.testing.expect(!supported("openai", .responses, "gpt-4o"));
+ try std.testing.expect(!supported("openai", .openai, "gpt-5.6"));
+ try std.testing.expect(!supported("openai", .openai, "gpt-6-sol"));
+ try std.testing.expect(!supported("codex", .responses, "gpt-5.6-sol"));
+ try std.testing.expect(!supported("chatgpt-new", .responses, "gpt-6.1-sol"));
+ try std.testing.expect(!supported("xai", .responses, "grok-4.6"));
+ try std.testing.expect(!supported("codegraff", .responses, "gpt-5.6"));
+ _ = Kind;
+}
+
+test "usage details expose cached_tokens and both write lifetimes" {
+ const gpa = std.testing.allocator;
+ const body =
+ \\{"input_tokens":12000,"input_tokens_details":{"cached_tokens":4000,"cache_write_tokens":7000,
+ \\ "cache_write_tokens_details":{"ttl_30m_tokens":3000,"ttl_12h_tokens":4000}}}
+ ;
+ var parsed = try std.json.parseFromSlice(std.json.Value, gpa, body, .{});
+ defer parsed.deinit();
+ const u = readResponsesUsage(parsed.value.object);
+ try std.testing.expectEqual(@as(i64, 4000), u.cached);
+ try std.testing.expectEqual(@as(i64, 7000), u.written);
+ try std.testing.expectEqual(@as(i64, 3000), u.write_30m);
+ try std.testing.expectEqual(@as(i64, 4000), u.write_12h);
+}
+
+test {
+ _ = @import("openai_cache_retention.zig");
+}
diff --cc src/pricing_cache.zig
index b234b2cb,accb4baf..704c531f
--- a/src/pricing_cache.zig
+++ b/src/pricing_cache.zig
@@@ -6,8 -6,6 +6,8 @@@ const std = @import("std")
const five_minute_write: f64 = 1.25;
/// Anthropic's 1-hour cache write (ADR 0220).
const one_hour_write: f64 = 2.0;
- /// OpenAI GPT-5.6+ Responses 12-hour cache write (ADR 0298).
++/// OpenAI GPT-5.6+ Responses 12-hour cache write (ADR 0312).
+const twelve_hour_write: f64 = 2.5;
/// USD for one request (negative token counts clamp to zero). Cache writes are
/// separate from ordinary input: GPT-5.6 and Anthropic ephemeral caches bill
@@@ -58,12 -45,3 +58,12 @@@ test "ADR 0220: a 1-hour cache write co
const flat = @import("pricing_gateway.zig").rows[0];
try std.testing.expectEqual(@as(f64, 0), hourWriteExtraUsd(flat, flat.name, 100_000, 100_000));
}
+
- test "ADR 0298: a 12-hour OpenAI cache write costs 2.5x input" {
++test "ADR 0312: a 12-hour OpenAI cache write costs 2.5x input" {
+ const sol = @import("pricing.zig").priceFor("gpt-6.1-sol").?;
+ // 100k tokens: usdForUsage already charged 1.25x of $2/MTok = $0.25; +1.25x more at 12h.
+ try std.testing.expectApproxEqAbs(@as(f64, 0.25), usdForUsage(sol, "gpt-6.1-sol", 0, 0, 100_000, 0), 1e-9);
+ try std.testing.expectApproxEqAbs(@as(f64, 0.25), twelveHourWriteExtraUsd(sol, "gpt-6.1-sol", 100_000), 1e-9);
+ try std.testing.expectEqual(@as(f64, 0), twelveHourWriteExtraUsd(sol, "gpt-6.1-sol", 0));
+ try std.testing.expectEqual(@as(f64, 0), twelveHourWriteExtraUsd(sol, "gpt-4o", 100_000));
+}
diff --cc src/prompt_cache_hud.zig
index 26ef0c71,20bc931f..57435bcd
--- a/src/prompt_cache_hud.zig
+++ b/src/prompt_cache_hud.zig
@@@ -235,7 -223,6 +235,7 @@@ pub fn render(w: *Io.Writer) !void
}
try w.writeAll(
\\ remaining max
- \\ GRAFF_OPENAI_CACHE_TTL 12h (default) / 30m / off; OpenAI Responses GPT-5.6+
++ \\ GRAFF_OPENAI_CACHE_TTL 30m (default) / 12h / off; OpenAI Responses GPT-5.6+
\\ GRAFF_STABLE_CATALOG=0 opt out: loads rewrite tools JSON (stable is the default)
\\ /goal /never /strict each prefix rewrite is one miss; compaction already pays one
\\ leave skill bodies and file: paths out of the prefix (already the default)