Skip to content

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.md
new file mode 100644
index 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.md
index 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 one
diff --git a/src/agent_request_body_responses.zig b/src/agent_request_body_responses.zig
index 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 0243
try 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 id
try s.endArray();
if (tools) |t| {
diff --git a/src/hot_context.zig b/src/hot_context.zig
index 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.zig
index 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.zig
new file mode 100644
index 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.zig
new file mode 100644
index 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);
+}