graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Send the repo context once on the stateful hosted chat route (ADR 0258)
justrach8c8c99b4cfd3
diff --git a/docs/adr/0258-gemini-chat-sends-repo-context-once.md b/docs/adr/0258-gemini-chat-sends-repo-context-once.mdnew file mode 100644index 00000000..973eb176--- /dev/null+++ b/docs/adr/0258-gemini-chat-sends-repo-context-once.md@@ -0,0 +1,43 @@+# 0258. Gemini on the Codegraff chat wire sends the repo context once++Status: accepted 2026-10-06++## Context++Gemini on the Codegraff chat wire is stateful: each request continues the+conversation on the server and carries only the new turn, but the system+prompt and the tool catalog travel again with every request. Whatever sits in+the system prompt is paid for on every request of a session.++In a real repository a large share of that system prompt is per-repo context:+the project-instructions file and the project layout. In this repository they+are about half of the system prompt, and they never change during a session+except through a compaction fold (ADR 0208) or a resumed layout (ADR 0109).++ADR 0243 already moves exactly these blocks out of the instructions on the+Responses wires, as one developer item ahead of the conversation. A developer+or system message cannot do that on this wire: they join the system prompt.++## Decision++On the Codegraff chat wire, for `gemini-` model ids and root turns, the+per-repo context leaves the system prompt and rides as the conversation's+first user message, framed as standing context rather than a request. It uses+the same blocks and the same split as ADR 0243. Because the server keeps the+conversation, that message reaches the model once per session; the system+prompt that every later request repeats no longer holds it.++Other chat routes, the Responses wires and sub-agents are unchanged.++## Consequences++Every request after a session's first carries a smaller system prompt, by the+size of the project instructions and layout; small repositories gain little.+The system prompt is also identical across repositories.++Project instructions now arrive in a user turn on this route, the place other+coding harnesses put them. Compliance with checkable rules in a project+instructions file (a required first line, tab indentation, a commit-subject+prefix) was the same before and after in eval runs. Revisit if+instruction-following on this route degrades, or if the route stops+continuing conversations server-side.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex cbbbc340..8751d3fb 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -283,6 +283,7 @@ record only when you need the evidence or the edge cases.| [0255](0255-codegraff-claude-uses-native-messages.md) | Claude aliases on codegraff use the native Messages endpoint; `isClaudeApi` is the one predicate for the real Claude wire. || [0256](0256-gemini-takes-fewer-requests-per-task.md) | Gemini models get a working note (chained shell steps, no read-backs, no pasted files, check computed answers) and may batch `attempt_completion` with a final check or write; the completion is recorded only if every batched call succeeded. || [0257](0257-a-slimmed-comment-list-names-its-issue.md) | A slimmed MCP comment list keeps the issue id its rows share (`{issue, n, latest_author}`), so parallel results name what they describe. |+| [0258](0258-gemini-chat-sends-repo-context-once.md) | On the Codegraff chat wire, Gemini root turns send the project instructions and layout as the conversation's first user message (ADR 0243's split), so the system prompt every request repeats no longer carries them. |## When to write onediff --git a/src/agent_request_body.zig b/src/agent_request_body.zigindex c4773c9f..1dbbcee8 100644--- a/src/agent_request_body.zig+++ b/src/agent_request_body.zig@@ -159,12 +159,17 @@ pub fn buildBody(self: *Agent, tools_in: ?[]const u8, force_tool: bool, stream:}try s.objectField("messages");try s.beginArray();+ // ADR 0258: on the stateful Gemini chat wire the per-repo context is+ // the first user message, sent once, not part of every system prompt.+ const repo_context = @import("repo_context.zig");+ const repo = try repo_context.split(self, try @import("agent_request_body_responses.zig").schemaAwarePrompt(self));try s.beginObject();try s.objectField("role");try s.write("system");try s.objectField("content");- try s.write(try @import("agent_request_body_responses.zig").schemaAwarePrompt(self));+ try s.write(repo.instructions);try s.endObject();+ if (repo.context.len != 0) try repo_context.writeChatMessage(&s, self.scratchAlloc(), repo.context);for (self.messages.items) |m| try writeOpenAIMessageNormalized(&s, m);try s.endArray();// The live Kimi catalog declares thinking support and alloweddiff --git a/src/repo_context.zig b/src/repo_context.zigindex 99614269..4117802d 100644--- a/src/repo_context.zig+++ b/src/repo_context.zig@@ -3,6 +3,12 @@//! 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.+//!+//! ADR 0258: Gemini on the Codegraff chat wire continues each conversation on+//! the server and sends only the new turn, while the system prompt goes again+//! with every request. There the context rides as the conversation's first+//! user message instead (a developer or system message would join the system+//! prompt), so it is sent once rather than with every request.const std = @import("std");const Agent = @import("agent.zig").Agent;@@ -13,11 +19,22 @@ pub const Split = struct { instructions: []const u8, context: []const u8 = "" };/// 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;+ if (self.sub) return false;+ if (statefulChat(self)) return true;+ if (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;}+/// ADR 0258: the Codegraff chat wire's Gemini models, which the gateway+/// continues server-side.+pub fn statefulChat(self: *const Agent) bool {+ if (self.provider.kind != .openai or !std.mem.eql(u8, self.provider.id, "codegraff")) return false;+ const model = self.provider.model;+ const bare = model[if (std.mem.lastIndexOfScalar(u8, model, '/')) |i| i + 1 else 0..];+ return std.ascii.startsWithIgnoreCase(bare, "gemini-");+}+/// `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@@ -64,3 +81,16 @@ pub fn writeItem(s: *std.json.Stringify, text: []const u8) !void {try s.endArray();try s.endObject();}++/// ADR 0258: the context as the chat conversation's first user message,+/// framed so the model reads it as standing context rather than a request.+pub const chat_frame = "Repository context for this session (standing instructions and layout, not a request):\n\n";++pub fn writeChatMessage(s: *std.json.Stringify, arena: std.mem.Allocator, text: []const u8) !void {+ try s.beginObject();+ try s.objectField("role");+ try s.write("user");+ try s.objectField("content");+ try s.write(try std.mem.concat(arena, u8, &.{ chat_frame, text }));+ try s.endObject();+}diff --git a/src/repo_context_tests.zig b/src/repo_context_tests.zigindex 54f1c8f1..7e9197b5 100644--- a/src/repo_context_tests.zig+++ b/src/repo_context_tests.zig@@ -81,3 +81,65 @@ test "ADR 0243: the wire body carries the layout as the first developer item; atry 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);}++fn chatRoot(a: std.mem.Allocator, id: []const u8, model: []const u8, layout: []const u8) !@import("agent.zig").Agent {+ var agent = try body.testAgentFor(a, id, .openai, model);+ 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 0258: Gemini on the Codegraff chat wire sends the per-repo context once, as the first user message" {+ 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 agent = try chatRoot(a, "codegraff", "gemini-3.8-flash", 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 messages = parsed.value.object.get("messages").?.array.items;+ try std.testing.expectEqualStrings("system", messages[0].object.get("role").?.string);+ const system = messages[0].object.get("content").?.string;+ try std.testing.expect(std.mem.startsWith(u8, system, "BASE\n\n# Skills\nstatic tail"));+ try std.testing.expect(std.mem.indexOf(u8, system, "# Project") == null);+ try std.testing.expectEqualStrings("user", messages[1].object.get("role").?.string);+ const context = messages[1].object.get("content").?.string;+ try std.testing.expect(std.mem.startsWith(u8, context, repo_context.chat_frame ++ "# Project instructions (from AGENTS.md)\nUse tabs."));+ try std.testing.expect(std.mem.indexOf(u8, context, "logs/auth.log") != null);+ try std.testing.expectEqualStrings("hello", messages[2].object.get("content").?.string);++ // A second repo sends the same system prompt.+ var other = try chatRoot(a, "codegraff", "google/gemini-3.7-flash", layout_b);+ try std.testing.expectEqualStrings((try repo_context.split(&agent, agent.sys_normal)).instructions, (try repo_context.split(&other, other.sys_normal)).instructions);+}++test "ADR 0258: other chat routes and sub-agents keep the per-repo context in the system prompt" {+ 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();+ const routes = [_]struct { id: []const u8, model: []const u8 }{+ .{ .id = "codegraff", .model = "deepseek-v4-flash" },+ .{ .id = "codegraff", .model = "mimo-v2.6-pro" },+ .{ .id = "openrouter", .model = "google/gemini-3.8-flash" },+ };+ for (routes) |r| {+ var agent = try chatRoot(a, r.id, r.model, 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 messages = parsed.value.object.get("messages").?.array.items;+ // The system prompt still holds the blocks (a model note may follow them).+ try std.testing.expect(std.mem.startsWith(u8, messages[0].object.get("content").?.string, agent.sys_normal));+ try std.testing.expectEqual(@as(usize, 2), messages.len);+ }+ var sub = try chatRoot(a, "codegraff", "gemini-3.8-flash", layout_a);+ sub.sub = true;+ try std.testing.expectEqualStrings(sub.sys_normal, (try repo_context.split(&sub, sub.sys_normal)).instructions);+}