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.mdindex 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 explicitstable prefix remains reusable while append-only conversation turns keep theuseful 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 trafficis deterministically spread over four stable role lanes to stay below thedocumented approximately 15 requests/minute per-key guidance while preservingdiff --cc docs/adr/0312-openai-12h-prompt-cache-is-opt-in.mdindex 7a1f1afb,00000000..414d0b6amode 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.mdindex 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 onediff --cc src/agent_request_body_cache_test.zigindex 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 marksconst 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.zigindex 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.jsonvar 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.zigindex a773c17c,00000000..ee28e7aamode 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.zigindex 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 coconst 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.zigindex 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)