graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
responses: send the repo context as an input item, not in the instructions
justrach2704b0c90fab
diff --git a/docs/adr/0243-repo-context-rides-as-an-input-item-on-responses.md b/docs/adr/0243-repo-context-rides-as-an-input-item-on-responses.mdnew file mode 100644index 00000000..ac03e91b--- /dev/null+++ b/docs/adr/0243-repo-context-rides-as-an-input-item-on-responses.md@@ -0,0 +1,40 @@+# 0243. Repo context rides as an input item on Responses wires that cache the instructions whole++Status: accepted 2026-10-03++## Context++ADR 0223 keys the ChatGPT-plan prompt cache by account so turn 1 in a new+repo reads the shared prefix another repo warmed. Request dumps against that+backend showed what is shared. It renders the tool definitions first and the+instructions after them, and caches the instructions as one unit: two repos+whose instructions differed only in the project layout reused the system and+tools prefix and nothing of the instructions. Changing one paragraph at the+start of the instructions gave the same cached length, so there is no+partial credit inside them.++The instructions carry two per-repo blocks: the project-instructions section+(AGENTS.md and friends) and the project layout. Static text follows them (the+skills list, the constraint block, the model guidance), so every first call+in a new repo paid for the whole instructions uncached.++## Decision++On the Responses wire for `codex`, `chatgpt-new` and `openai`, root turns+send the instructions without those two blocks and send the blocks, in prompt+order, as one developer message ahead of the conversation (the role ADR 0208+gives mid-session context). The message rides with the conversation's first+item: a chained delta already holds it server-side, and a prewarm sends no+input at all. The blocks are the ones the prefix holds now: the instructions+section hot_context tracks across compaction folds, and the layout snapshot+resume restores (ADR 0109). The system prompt itself is unchanged, so other+wires, other providers and subagents send exactly what they sent before.++## Consequences++Instructions are byte-identical across repos with the same capabilities, so+a new repo's first call reads them from the cache; only the repo's own block+is new. The model reads AGENTS.md and the layout from a developer message+instead of the instructions. Revisit if a model treats that message with less+weight than the instructions, or another backend shows the same+whole-instructions caching.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 98265dc7..0c038dfd 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -265,6 +265,7 @@ record only when you need the evidence or the edge cases.| [0236](0236-rlm-takes-json-literals-and-each-maps-plain-values.md) | `rlm` takes JSON array/object literals as arguments and binds (`name = [...]`, bound names allowed inside); its splitters nest `[]`/`{}`; `each(arr, tool[, field])` passes plain items as is, picks `field` from objects (default: an MCP tool's first parameter) and names the fields it found; an unsupported statement lists the forms that work. || [0237](0237-deepseek-thinks-at-its-low-level-by-default.md) | DeepSeek's default effort (`medium`) sends `reasoning_effort: low` with thinking enabled; `/effort low` still turns thinking off (ADR 0054), and `high` and above are unchanged. || [0238](0238-rlm-binds-keep-the-whole-mcp-result.md) | An MCP call inside an rlm script binds the whole result; `print()` shows the slim view (each item of an `each()` bind cut on its own), `project(x, field)` reads any field (`n`/`latest_author` through a comment list's fold), and `write_file` saves the whole result; inside rlm, `read_tool_result("tr_N")` with no range binds a stored result whole. |+| [0243](0243-repo-context-rides-as-an-input-item-on-responses.md) | On the Responses wire for codex, chatgpt-new and openai, root turns send the project-instructions section and the layout as one developer input item ahead of the conversation, so the instructions are byte-identical across repos and cache on turn 1. |## When to write onediff --git a/src/agent_request_body_responses.zig b/src/agent_request_body_responses.zigindex f57b466f..6bbd5b2b 100644--- a/src/agent_request_body_responses.zig+++ b/src/agent_request_body_responses.zig@@ -20,8 +20,9 @@ pub fn write(self: *Agent, s: *std.json.Stringify, tools: ?[]const u8, force_too// stream is required (we buffer + parse the SSE); reasoning items return// encrypted and are passed back per turn.const is_codex = std.mem.eql(u8, self.provider.id, "codex");+ const repo = try @import("repo_context.zig").split(self, try schemaAwarePrompt(self)); // ADR 0243try s.objectField("instructions");- try s.write(try schemaAwarePrompt(self));+ try s.write(repo.instructions);// Sticky cache partition from the first request. xAI's key is a true// per-conversation routing id. OpenAI/Codex instead share deterministic// prefix lanes so repeated workflow roles can reuse the stable prompt.@@ -57,6 +58,7 @@ pub fn write(self: *Agent, s: *std.json.Stringify, tools: ?[]const u8, force_too// this item server-side, so only a full anchor writes it.if (!chain and explicit_cache) try writeCacheAnchor(s);const from = if (chain) self.codex_sent_upto else 0;+ if (from == 0 and !self.ws_prewarm and repo.context.len != 0) try @import("repo_context.zig").writeItem(s, repo.context);if (!self.ws_prewarm) for (self.messages.items[from..]) |m| try @import("session_wake.zig").writeWireInput(s, m, self.provider.model); // prewarm: NO input items; turn 1 chains onto the warmup idtry s.endArray();if (tools) |t| {diff --git a/src/hot_context.zig b/src/hot_context.zigindex 818432f7..36bd0c50 100644--- a/src/hot_context.zig+++ b/src/hot_context.zig@@ -65,6 +65,12 @@ fn section(a: Allocator, name: []const u8, body: []const u8) ![]const u8 {return std.fmt.allocPrint(a, "# Project instructions (from {s})\n{s}", .{ name, body });}+/// The instructions section the prefix holds now (startup's, or the one the+/// last compaction folded in); ADR 0243 lifts it out on Responses wires.+pub fn bakedSection() []const u8 {+ return g.baked_section;+}+/// startup.buildSystemPrompt: the instructions it baked into the prefix.pub fn noteBaked(name: []const u8, body: []const u8) void {g.baked_section = section(g_gpa, name, body) catch "";diff --git a/src/main.zig b/src/main.zigindex 7a65d043..97cdc8c3 100644--- a/src/main.zig+++ b/src/main.zig@@ -591,7 +591,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu_ = @import("goal_todo.zig");_ = @import("goal_pacing.zig");_ = .{ @import("presence_accord.zig"), @import("peer_idle.zig"), @import("acp_idle.zig"), @import("presence_chan.zig"), @import("presence_record.zig"), @import("daddy.zig"), @import("peer_inbox_content_test.zig"), @import("peer_inbox_failure_test.zig"), @import("peer_inbox_storage_test.zig"), @import("peer_inbox_sequence_test.zig"), @import("peer_inbox_snapshot_test.zig") };- _ = @import("acp_agents.zig");+ _ = .{ @import("acp_agents.zig"), @import("repo_context_tests.zig") };_ = .{ @import("subagent_activity.zig"), @import("subagent_interactive.zig"), @import("subagent_recovery.zig"), @import("subagent_retained.zig"), @import("subagent_run_tests.zig") };_ = .{ @import("acp_agent_activity.zig"), @import("acp_subagent_live.zig"), @import("acp_line_writer.zig") };_ = @import("acp_replay.zig");diff --git a/src/repo_context.zig b/src/repo_context.zignew file mode 100644index 00000000..99614269--- /dev/null+++ b/src/repo_context.zig@@ -0,0 +1,66 @@+//! ADR 0243: on the Responses wires whose backend caches the instructions as+//! one unit, the per-repo context (the project-instructions block and the+//! layout) rides as its own developer input item, ahead of the conversation,+//! so the instructions are byte-identical in every repo and turn 1 in a new+//! repo reads them from the cache. Other wires keep them in the instructions.++const std = @import("std");+const Agent = @import("agent.zig").Agent;++pub const Split = struct { instructions: []const u8, context: []const u8 = "" };++/// Root turns on the ChatGPT plan and the OpenAI platform. Their backend+/// renders the tools and then the instructions, and caches the instructions+/// as one unit: a per-repo byte inside them forfeits all of it in a new repo.+pub fn eligible(self: *const Agent) bool {+ if (self.sub or self.provider.kind != .responses) return false;+ for ([_][]const u8{ "codex", "chatgpt-new", "openai" }) |id| if (std.mem.eql(u8, self.provider.id, id)) return true;+ return false;+}++/// `instructions` without the per-repo blocks, and the blocks as one text, in+/// prompt order: the instructions section the prefix holds now (hot_context+/// keeps it in step with compaction folds, ADR 0208) and the layout in the+/// current base (resume may have swapped it, ADR 0109). Unchanged when the+/// agent is not eligible or neither block is present.+pub fn split(self: *Agent, instructions: []const u8) !Split {+ if (!eligible(self)) return .{ .instructions = instructions };+ const arena = self.scratchAlloc();+ var rest = instructions;+ var ctx: std.ArrayList(u8) = .empty;+ const baked = @import("hot_context.zig").bakedSection();+ const blocks = [_]?[]const u8{ if (baked.len != 0) baked else null, @import("session_prompt.zig").snapshot(self) };+ for (blocks) |maybe| {+ const block = maybe orelse continue;+ var at = std.mem.indexOf(u8, rest, block) orelse continue;+ const end = at + block.len;+ // A section composed as "\n\n" ++ section leaves with its separator.+ if (block[0] != '\n' and at >= 2 and std.mem.eql(u8, rest[at - 2 .. at], "\n\n")) at -= 2;+ rest = try std.mem.concat(arena, u8, &.{ rest[0..at], rest[end..] });+ if (ctx.items.len != 0) try ctx.appendSlice(arena, "\n\n");+ try ctx.appendSlice(arena, std.mem.trim(u8, block, "\n"));+ }+ if (ctx.items.len == 0) return .{ .instructions = instructions };+ return .{ .instructions = rest, .context = ctx.items };+}++/// The context as a developer message, the role ADR 0208 gives mid-session+/// context on Responses. Written with the conversation's first item only:+/// chained requests already hold it server-side.+pub fn writeItem(s: *std.json.Stringify, text: []const u8) !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(text);+ try s.endObject();+ try s.endArray();+ try s.endObject();+}diff --git a/src/repo_context_tests.zig b/src/repo_context_tests.zignew file mode 100644index 00000000..54f1c8f1--- /dev/null+++ b/src/repo_context_tests.zig@@ -0,0 +1,83 @@+//! ADR 0243 tests: the per-repo context leaves the instructions on the+//! eligible Responses wires and rides as the first input item.++const std = @import("std");+const repo_context = @import("repo_context.zig");+const hot_context = @import("hot_context.zig");+const body = @import("agent_request_body_responses.zig");++const layout_a = "\n\n# Project layout (working tree at session start, depth 3; may omit later changes)\nlogs/\nlogs/auth.log\n";+const layout_b = "\n\n# Project layout (working tree at session start, depth 3; may omit later changes)\napi/\napi/routes.py\n";+const agents_block = "\n\n# Project instructions (from AGENTS.md)\nUse tabs.";++fn rootWith(a: std.mem.Allocator, id: []const u8, layout: []const u8) !@import("agent.zig").Agent {+ var agent = try body.testAgentFor(a, id, .responses, "gpt-6.1-sol");+ const base = try std.mem.concat(a, u8, &.{ "BASE", agents_block, layout, "\n\n# Skills\nstatic tail" });+ agent.sys_base = base;+ agent.sys_normal = base;+ agent.repo_map_snapshot = layout;+ return agent;+}++test "ADR 0243: instructions drop the per-repo blocks and are identical across repos" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ hot_context.noteBaked("AGENTS.md", "Use tabs.");+ defer hot_context.resetForTest();++ var one = try rootWith(a, "codex", layout_a);+ var two = try rootWith(a, "codex", layout_b);+ const s1 = try repo_context.split(&one, one.sys_normal);+ const s2 = try repo_context.split(&two, two.sys_normal);+ try std.testing.expectEqualStrings("BASE\n\n# Skills\nstatic tail", s1.instructions);+ try std.testing.expectEqualStrings(s1.instructions, s2.instructions);+ try std.testing.expect(std.mem.startsWith(u8, s1.context, "# Project instructions (from AGENTS.md)\nUse tabs.\n\n# Project layout"));+ try std.testing.expect(std.mem.indexOf(u8, s1.context, "logs/auth.log") != null);+ try std.testing.expect(std.mem.indexOf(u8, s2.context, "api/routes.py") != null);+}++test "ADR 0243: other wires, other providers and subagents keep the blocks in the instructions" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ for ([_][]const u8{ "xai", "codegraff" }) |id| {+ var other = try rootWith(a, id, layout_a);+ const s = try repo_context.split(&other, other.sys_normal);+ try std.testing.expectEqualStrings(other.sys_normal, s.instructions);+ try std.testing.expectEqualStrings("", s.context);+ }+ var sub = try rootWith(a, "codex", layout_a);+ sub.sub = true;+ try std.testing.expectEqualStrings(sub.sys_normal, (try repo_context.split(&sub, sub.sys_normal)).instructions);+ var chat = try rootWith(a, "codex", layout_a);+ chat.provider.kind = .openai;+ try std.testing.expectEqualStrings(chat.sys_normal, (try repo_context.split(&chat, chat.sys_normal)).instructions);+}++test "ADR 0243: the wire body carries the layout as the first developer item; a prewarm carries none" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ hot_context.resetForTest(); // no baked instructions: the layout alone moves++ var agent = try rootWith(a, "codex", layout_a);+ const full = try agent.buildBody("[]", false, true, true);+ defer std.testing.allocator.free(full);+ const parsed = try std.json.parseFromSlice(std.json.Value, a, full, .{});+ const instructions = parsed.value.object.get("instructions").?.string;+ try std.testing.expect(std.mem.indexOf(u8, instructions, "# Project layout") == null);+ const input = parsed.value.object.get("input").?.array.items;+ try std.testing.expectEqualStrings("developer", input[0].object.get("role").?.string);+ const text = input[0].object.get("content").?.array.items[0].object.get("text").?.string;+ try std.testing.expect(std.mem.startsWith(u8, text, "# Project layout"));+ try std.testing.expect(std.mem.indexOf(u8, text, "logs/auth.log") != null);+ try std.testing.expectEqualStrings("user", input[1].object.get("role").?.string);++ agent.ws_prewarm = true; // instructions + tools only; turn 1 chains on with the item (from == 0)+ const warm = try agent.buildBody("[]", false, true, true);+ defer std.testing.allocator.free(warm);+ const warm_parsed = try std.json.parseFromSlice(std.json.Value, a, warm, .{});+ try std.testing.expectEqual(@as(usize, 0), warm_parsed.value.object.get("input").?.array.items.len);+ try std.testing.expectEqualStrings(instructions, warm_parsed.value.object.get("instructions").?.string);+}