graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Route gateway Messages-wire models through the native Messages API
justrachdb80e8852bf6
diff --git a/docs/adr/0255-codegraff-claude-uses-native-messages.md b/docs/adr/0255-codegraff-claude-uses-native-messages.mdnew file mode 100644index 00000000..6c003b1f--- /dev/null+++ b/docs/adr/0255-codegraff-claude-uses-native-messages.md@@ -0,0 +1,26 @@+# 0255. Codegraff Claude models use the native Messages endpoint++Status: accepted 2026-10-06++## Context++ADR 0003 sent every Claude alias on the codegraff provider through Chat+Completions, translated by the gateway. The translation loses the pieces the+Claude turn depends on: thinking blocks and their signatures on replay,+thinking block binding, images inside tool results, the 1-hour cache TTL, and+the model's full output budget.++## Decision++`usesMessages` (provider_codegraff.zig) routes Claude aliases on codegraff to+the gateway's native Messages endpoint, and the provider builds as the+Anthropic wire with bearer auth. `claude_wire.isClaudeApi` is the single+predicate for "this request speaks the real Claude Messages API" — the direct+Anthropic provider or a codegraff Claude alias — so request-body, header, and+cache code share one check. Other Anthropic-format providers keep their own+paths.++## Evidence++codegraff_messages_tests.zig pins the header set and byte-identical request+body against the direct provider's output.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex ae92a3b7..56e8ceab 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -13,7 +13,7 @@ record only when you need the evidence or the edge cases.|---|---|| [0001](0001-structured-outputs-are-a-formatting-step.md) | Structured output is a final formatting step. Never constrain the agentic phase with a schema grammar, and do not use `--output-schema` unless a program consumes the result. || [0002](0002-xai-defaults-to-the-responses-wire.md) | xAI runs on the Responses wire by default (WS turns + on-socket `previous_response_id`). Compaction is the client summarizer, not xAI's blob endpoint. `GRAFF_XAI_WIRE=chat` opts out. |-| [0003](0003-codegraff-wire-follows-model-capability.md) | Codegraff uses Responses + WS for GPT-5.6+ (incl. GPT-6 Astra / Codex `gpt-5.6-*`) and grok-4.6; Claude, Gemini, and other aliases stay on Chat Completions. |+| [0003](0003-codegraff-wire-follows-model-capability.md) | Codegraff uses Responses + WS for GPT-5.6+ (incl. GPT-6 Astra / Codex `gpt-5.6-*`) and grok-4.6; Claude aliases use native Messages (0255); Gemini and other aliases stay on Chat Completions. || [0004](0004-peer-speech-is-a-working-set.md) | Peer speech is pull: a one-line `[peer]` wake in history, bodies in the inbox ring; compact drops spent injects and never treats them as the human. || [0005](0005-standing-goal-lives-in-the-prefix.md) | Standing goal is one prefix line; the user-message essay injects on change only, never every N turns. || [0006](0006-workspace-switch-is-a-tool.md) | Mid-session worktree switch is a real `workspace` tool; a skill cannot move file-tool cwd. |@@ -280,6 +280,7 @@ record only when you need the evidence or the edge cases.| [0251](0251-tool-results-inline-up-to-64-kib.md) | Tool results inline up to 64 KiB (was 16 KiB); `effectiveThreshold` still clamps to half the context window, so small windows are unchanged. The codedb small-read exemption follows the same number. || [0253](0253-an-interactive-session-signs-in-to-chatgpt-again.md) | When a ChatGPT request is rejected and the refresh cannot replace the token, an interactive root session opens the browser sign-in, waits up to three minutes and retries once; `-p`, piped, `--json`, ACP and sub-agents never do. One unfinished sign-in ends it for the process. || [0254](0254-imported-conversations-use-the-configured-route.md) | Imported Claude history uses the configured graff provider and credentials; source models are metadata, and foreign tool results remain historical receipts. |+| [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. |## When to write onediff --git a/src/agent_request_body.zig b/src/agent_request_body.zigindex 1923e7c4..c4773c9f 100644--- a/src/agent_request_body.zig+++ b/src/agent_request_body.zig@@ -34,8 +34,8 @@ pub fn buildBody(self: *Agent, tools_in: ?[]const u8, force_tool: bool, stream:switch (self.provider.kind) {.anthropic => {const is_kimi = std.mem.eql(u8, self.provider.id, "kimi");- const is_claude = std.mem.eql(u8, self.provider.id, "anthropic");const claude = @import("claude_wire.zig"); // ADR 0219+ const is_claude = claude.isClaudeApi(self.provider.id, self.provider.model);try s.objectField("max_tokens");try s.write(if (is_claude) claude.maxTokens(self.provider.model, self.reasoning, max_tokens) else max_tokens);if (stream) {@@ -83,7 +83,7 @@ pub fn buildBody(self: *Agent, tools_in: ?[]const u8, force_tool: bool, stream:try s.objectField("system");const sys = try @import("agent_request_body_responses.zig").schemaAwarePrompt(self);const cc = @import("cache_ttl.zig").control(self); // #1320: 1h when calls outlive 5m- if (std.mem.eql(u8, self.provider.id, "anthropic") or is_kimi) {+ if (is_claude or is_kimi) {try s.beginArray();try s.beginObject();try s.objectField("type");@@ -121,7 +121,7 @@ pub fn buildBody(self: *Agent, tools_in: ?[]const u8, force_tool: bool, stream:// Cache the conversation prefix too (not just system) on the real// Anthropic API and Kimi's declared Anthropic transport. Kimi also// normalizes all string content into Anthropic text blocks.- const cache_msgs = std.mem.eql(u8, self.provider.id, "anthropic") or is_kimi;+ const cache_msgs = is_claude or is_kimi;try writeAnthropicMessages(&s, self.messages, if (cache_msgs) cc else null, is_kimi);},.openai => {diff --git a/src/agent_request_body_responses.zig b/src/agent_request_body_responses.zigindex c6155ba3..851147f4 100644--- a/src/agent_request_body_responses.zig+++ b/src/agent_request_body_responses.zig@@ -180,7 +180,7 @@ pub fn schemaAwarePrompt(self: *Agent) ![]const u8 {// enforces server-side on the formatting turn — same light prompt as// Responses. minimax / kimi-anthropic stay on the tool.const anthropic_tool_mode = self.provider.kind == .anthropic and- (self.sox_json_object or !std.mem.eql(u8, self.provider.id, "anthropic"));+ (self.sox_json_object or !@import("claude_wire.zig").isClaudeApi(self.provider.id, self.provider.model));if ((self.provider.kind == .openai and self.sox_json_object) or anthropic_tool_mode) return std.mem.concat(self.scratchAlloc(), u8, &.{base,"\n\nA JSON output schema is enforced on your final answer. Use tools first to gather every fact you need — never guess values. This provider cannot enforce the schema server-side, so satisfy it yourself: call the structured_output tool when it is offered, otherwise reply with a single JSON object, matching exactly this schema: ",@@ -252,7 +252,7 @@ pub fn writeStructuredOutputTool(s: *std.json.Stringify, schema_json: []const u8/// structured_output tool, and a learned sox flag falls back to it too./// True when it wrote `output_config`, with `effort` inside it (ADR 0219).pub fn writeAnthropicSchema(s: *std.json.Stringify, self: *const Agent, schema_json: []const u8, effort: ?[]const u8) !bool {- if (std.mem.eql(u8, self.provider.id, "anthropic") and !self.sox_json_object) {+ if (@import("claude_wire.zig").isClaudeApi(self.provider.id, self.provider.model) and !self.sox_json_object) {try writeAnthropicOutputConfig(s, schema_json, effort);return true;}diff --git a/src/cache_fork.zig b/src/cache_fork.zigindex 066db74f..5dae6df0 100644--- a/src/cache_fork.zig+++ b/src/cache_fork.zig@@ -53,7 +53,7 @@ pub fn end() void {/// Whether the cache still holds this conversation's prefix and a fork of the/// whole history fits the window.pub fn warm(self: *Agent) bool {- if (self.provider.kind != .anthropic or !std.mem.eql(u8, self.provider.id, "anthropic")) return false;+ if (self.provider.kind != .anthropic or !claude.isClaudeApi(self.provider.id, self.provider.model)) return false;if (self.last_request_context_overflow or self.compact_summary_failures > 0) return false;const started = self.request_started orelse return false;const window = if (@import("cache_ttl.zig").asksLong(self.provider.id, self.provider.model)) warm_long_ms else warm_ms;diff --git a/src/cache_ttl.zig b/src/cache_ttl.zigindex f461b057..034d822c 100644--- a/src/cache_ttl.zig+++ b/src/cache_ttl.zig@@ -48,7 +48,7 @@ fn opensTurn(items: []const std.json.Value) bool {/// The Anthropic API, and Anthropic models through OpenRouter (#1284), take a/// TTL; other Anthropic-format providers keep the default.pub fn takesTtl(provider_id: []const u8, model: []const u8) bool {- return std.mem.eql(u8, provider_id, "anthropic") or+ return @import("claude_wire.zig").isClaudeApi(provider_id, model) or(std.mem.eql(u8, provider_id, "openrouter") and std.mem.startsWith(u8, model, "anthropic/"));}@@ -190,3 +190,10 @@ test "#1320: a zero-read request names its likely cause" {test {_ = @import("openrouter_cache.zig");}++test "codegraff Claude takes the TTL like the direct Anthropic API" {+ try std.testing.expect(takesTtl("codegraff", "claude-opus-5-5"));+ try std.testing.expect(takesTtl("codegraff", "claude-sonnet-5-5"));+ try std.testing.expect(!takesTtl("codegraff", "gpt-6-sol"));+ try std.testing.expect(!takesTtl("codegraff", "mimo-v2.6-pro"));+}diff --git a/src/claude_wire.zig b/src/claude_wire.zigindex ea10dcaa..9c7fe386 100644--- a/src/claude_wire.zig+++ b/src/claude_wire.zig@@ -25,6 +25,14 @@ pub const Version = struct { family: Family, major: u16, minor: u16 };/// The beta that enables `thinking.block_binding`.pub const binding_beta = "thinking-binding-controls-2026-08-01";+/// Requests that speak the real Anthropic Messages API: the direct anthropic+/// provider, and Claude models on the codegraff gateway (native /v1/messages).+/// Other Anthropic-format providers (minimax, kimi) keep their own quirks.+pub fn isClaudeApi(provider_id: []const u8, model: []const u8) bool {+ return std.mem.eql(u8, provider_id, "anthropic") or+ @import("provider_codegraff.zig").usesMessages(provider_id, model);+}+/// Parse `claude-opus-5-5`, `claude-sonnet-4-6-20260101`, `claude-fable-5`.pub fn version(model: []const u8) ?Version {const rest = if (std.mem.startsWith(u8, model, "claude-")) model["claude-".len..] else return null;diff --git a/src/codegraff_messages_tests.zig b/src/codegraff_messages_tests.zignew file mode 100644index 00000000..6ca8a856--- /dev/null+++ b/src/codegraff_messages_tests.zig@@ -0,0 +1,39 @@+//! Codegraff gateway + Claude = the native Messages wire end to end: headers,+//! body, cache TTL. Split into its own module because the touched files are at+//! the 600-line ceiling.++const std = @import("std");+const Provider = @import("provider.zig").Provider;+const http_headers = @import("http_headers.zig");+const claude = @import("claude_wire.zig");+const responses_body = @import("agent_request_body_responses.zig");++test "codegraff Claude sends bearer + anthropic-version + binding beta, never x-api-key" {+ const io = std.testing.io;+ var buf: [12]std.http.Header = undefined;+ const p: Provider = .{ .id = "codegraff", .kind = .anthropic, .auth = .bearer, .url = "", .api_key = "k", .model = "claude-opus-5-5", .context = 1_000_000 };+ const headers = http_headers.providerHeaders(io, p, "Bearer k", &buf);+ try std.testing.expectEqual(@as(usize, 3), headers.len);+ try std.testing.expectEqualStrings("authorization", headers[0].name);+ try std.testing.expectEqualStrings("Bearer k", headers[0].value);+ try std.testing.expectEqualStrings("anthropic-version", headers[1].name);+ try std.testing.expectEqualStrings("anthropic-beta", headers[2].name);+ try std.testing.expectEqualStrings(claude.binding_beta, headers[2].value);+}++test "codegraff Claude writes the identical Messages body the Anthropic API gets" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ var direct = try responses_body.testAgentFor(a, "anthropic", .anthropic, "claude-opus-5-5");+ var gateway = try responses_body.testAgentFor(a, "codegraff", .anthropic, "claude-opus-5-5");+ const ab = try direct.buildBody(null, false, true, true);+ defer std.testing.allocator.free(ab);+ const gb = try gateway.buildBody(null, false, true, true);+ defer std.testing.allocator.free(gb);+ try std.testing.expectEqualStrings(ab, gb);+ // The Claude-shaped fields the compat layer used to lose are present.+ try std.testing.expect(std.mem.indexOf(u8, gb, "\"max_tokens\":64000") != null);+ try std.testing.expect(std.mem.indexOf(u8, gb, "cache_control") != null);+ try std.testing.expect(std.mem.indexOf(u8, gb, "\"tool_choice\"") == null);+}diff --git a/src/http_headers.zig b/src/http_headers.zigindex 27e86398..9634f2fc 100644--- a/src/http_headers.zig+++ b/src/http_headers.zig@@ -232,7 +232,7 @@ pub fn providerHeadersWithConv(io: Io, provider: Provider, bearer: []const u8, b// ADR 0219: the beta that goes with the body's thinking.block_binding,// on the Anthropic API and the models that check it (claude_wire).const claude = @import("claude_wire.zig");- if (std.mem.eql(u8, provider.id, "anthropic") and claude.bindsThinking(provider.model)) {+ if (claude.isClaudeApi(provider.id, provider.model) and claude.bindsThinking(provider.model)) {buf[count] = .{ .name = "anthropic-beta", .value = claude.binding_beta };count += 1;}diff --git a/src/main.zig b/src/main.zigindex 029616d4..97f4f58b 100644--- a/src/main.zig+++ b/src/main.zig@@ -565,7 +565,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu_ = .{ @import("session_catalog.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig"), @import("oauth_chatgpt.zig"), @import("chatgpt_reauth.zig") }; // per-model guidance (Astra, GPT-5.6); ChatGPT plan sign-in (ADR 0253)_ = .{ @import("agent_empty_completion.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig") };- _ = .{ @import("provider_routing_tests.zig"), @import("history_wire.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };+ _ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("history_wire.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };_ = .{ @import("list_dir_nearmiss.zig"), @import("tool_preview_tests.zig") };_ = @import("repo_map.zig");_ = @import("agent_overflow_tests.zig"); // #414: and, through it, agent_overflow.zig's table testsdiff --git a/src/provider.zig b/src/provider.zigindex d574ed33..7ae665e5 100644--- a/src/provider.zig+++ b/src/provider.zig@@ -178,6 +178,7 @@ fn resolvedUrl(spec: ProviderSpec, model: []const u8) []const u8 {if (std.mem.eql(u8, spec.id, "xai")) return g_xai_url_override orelse if (g_xai_responses) xai_responses_url else spec.url;if (std.mem.eql(u8, spec.id, "zai")) return g_zai_url_override orelse spec.url;if (std.mem.eql(u8, spec.id, "vercel")) return g_vercel_url_override orelse spec.url;+ if (@import("provider_codegraff.zig").usesMessages(spec.id, model)) return @import("provider_codegraff.zig").messages_url;if (@import("provider_codegraff.zig").usesResponses(spec.id, model)) return @import("provider_codegraff.zig").responses_url;return spec.url;}@@ -273,7 +274,7 @@ pub const Provider = struct {const is_xai_responses = std.mem.eql(u8, spec.id, "xai") and g_xai_responses;return .{.id = spec.id,- .kind = if (is_kimi_anthropic) .anthropic else if (is_xai_responses or @import("provider_codegraff.zig").usesResponses(spec.id, model)) .responses else spec.kind,+ .kind = if (is_kimi_anthropic or @import("provider_codegraff.zig").usesMessages(spec.id, model)) .anthropic else if (is_xai_responses or @import("provider_codegraff.zig").usesResponses(spec.id, model)) .responses else spec.kind,.auth = if (is_kimi_anthropic) .x_api_key else spec.auth,.url = resolvedUrl(spec, model),.api_key = base.api_key,@@ -369,7 +370,7 @@ pub const Keys = struct {const is_xai_responses = std.mem.eql(u8, spec.id, "xai") and g_xai_responses;return .{.id = spec.id,- .kind = if (is_kimi_anthropic) .anthropic else if (is_xai_responses or @import("provider_codegraff.zig").usesResponses(spec.id, model)) .responses else spec.kind,+ .kind = if (is_kimi_anthropic or @import("provider_codegraff.zig").usesMessages(spec.id, model)) .anthropic else if (is_xai_responses or @import("provider_codegraff.zig").usesResponses(spec.id, model)) .responses else spec.kind,.auth = if (is_kimi_anthropic) .x_api_key else spec.auth,.url = resolvedUrl(spec, model),.api_key = key,@@ -568,3 +569,22 @@ test "contextWindowFor (#203): GRAFF_CONTEXT overrides only an unknown/local modtry std.testing.expect(pricing.isKnownModel("anthropic", "claude-opus-4-8"));try std.testing.expect(contextWindowFor("anthropic", "claude-opus-4-8") != 8192);}++test "codegraff Claude builds as the native Messages wire, bearer auth" {+ const keys: Keys = .{ .values = @splat("k") };+ const spec = specFor("codegraff").?;+ const p = keys.build(spec, "k", "claude-opus-5-5");+ try std.testing.expectEqual(Provider.Kind.anthropic, p.kind);+ try std.testing.expectEqual(Provider.Auth.bearer, p.auth);+ try std.testing.expectEqualStrings(@import("provider_codegraff.zig").messages_url, p.url);+ try std.testing.expectEqualStrings("claude-opus-5-5", p.model);+ // GPT on the gateway keeps Responses; a non-native alias keeps chat.+ const g = keys.build(spec, "k", "gpt-6-sol");+ try std.testing.expectEqual(Provider.Kind.responses, g.kind);+ const m = keys.build(spec, "k", "mimo-v2.6-pro");+ try std.testing.expectEqual(Provider.Kind.openai, m.kind);+ // withModel inherits the same mapping for a /model switch onto Claude.+ const switched = g.withModel("claude-sonnet-5-5");+ try std.testing.expectEqual(Provider.Kind.anthropic, switched.kind);+ try std.testing.expectEqualStrings(@import("provider_codegraff.zig").messages_url, switched.url);+}diff --git a/src/provider_codegraff.zig b/src/provider_codegraff.zigindex c1049a50..044d276c 100644--- a/src/provider_codegraff.zig+++ b/src/provider_codegraff.zig@@ -3,17 +3,28 @@const std = @import("std");pub const responses_url = "https://gateway.codegraff.com/v1/responses";+pub const messages_url = "https://gateway.codegraff.com/v1/messages";/// The gateway exposes every alias on Chat Completions, but only native OpenAI-/// and xAI aliases on Responses. Claude and Gemini return 400 there — keep-/// those on Chat Completions. OpenAI GPT-5.6+ (including Codex `gpt-5.6-*`-/// and GPT-6 `gpt-6-astra`) and grok-4.6 are the native set.+/// and xAI aliases on Responses — Gemini returns 400 there and stays on Chat+/// Completions, and Claude goes to the native Messages endpoint (usesMessages).+/// OpenAI GPT-5.6+ (including Codex `gpt-5.6-*` and GPT-6 `gpt-6-astra`) and+/// grok-4.6 are the Responses set.pub fn usesResponses(provider_id: []const u8, model: []const u8) bool {if (!std.mem.eql(u8, provider_id, "codegraff")) return false;if (openaiGptFamily(model)) return true;return std.mem.eql(u8, model, "grok-4.6");}+/// Claude aliases on the gateway speak the native Anthropic Messages API+/// (POST /v1/messages): thinking blocks and signatures, tool_result images,+/// and the 1h cache TTL all survive where Chat Completions translation lost+/// them. The model id must be a Claude name graff can wire.+pub fn usesMessages(provider_id: []const u8, model: []const u8) bool {+ if (!std.mem.eql(u8, provider_id, "codegraff")) return false;+ return @import("claude_wire.zig").version(model) != null;+}+/// GPT-5.6 and every later GPT generation, including Codex suffixes/// (`gpt-5.6-sol`) and GPT-6 names (`gpt-6-astra`). Earlier GPT aliases/// (`gpt-5.5`, `gpt-4o`, `gpt-oss-*`) stay on Chat Completions.@@ -39,8 +50,21 @@ test "Codegraff Responses allowlist matches the public gateway contract" {for ([_][]const u8{ "gpt-5.6", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra", "gpt-6-sol", "gpt-6.5", "grok-4.6" }) |model|try std.testing.expect(usesResponses("codegraff", model));- for ([_][]const u8{ "gpt-5.5", "gpt-4o", "gpt-oss-120b", "grok-4.3", "claude-opus-4.8", "gemini-3.7-flash", "glm-5.3-flash" }) |model|+ for ([_][]const u8{ "gpt-5.5", "gpt-4o", "gpt-oss-120b", "grok-4.3", "gemini-3.7-flash", "glm-5.3-flash" }) |model|try std.testing.expect(!usesResponses("codegraff", model));try std.testing.expect(!usesResponses("openai", "gpt-5.6"));try std.testing.expect(!usesResponses("openai", "gpt-6-astra"));}++test "Codegraff Messages allowlist: Claude aliases only, and only on codegraff" {+ for ([_][]const u8{ "claude-opus-5-5", "claude-sonnet-5-5", "claude-fable-5" }) |model|+ try std.testing.expect(usesMessages("codegraff", model));++ for ([_][]const u8{ "gpt-6-sol", "gpt-5.6", "grok-4.6", "glm-5.3-flash", "gemini-3.7-flash" }) |model|+ try std.testing.expect(!usesMessages("codegraff", model));+ // Claude names on a direct provider keep their own route.+ try std.testing.expect(!usesMessages("anthropic", "claude-opus-5-5"));+ try std.testing.expect(!usesMessages("openrouter", "anthropic/claude-sonnet-4.6"));+ // A Claude alias on codegraff is Messages, never Responses.+ try std.testing.expect(!usesResponses("codegraff", "claude-opus-5-5"));+}diff --git a/src/rlm_query.zig b/src/rlm_query.zigindex f3091cfa..963166e8 100644--- a/src/rlm_query.zig+++ b/src/rlm_query.zig@@ -119,7 +119,7 @@ pub fn buildBody(gpa: Allocator, provider: Provider, prompt: []const u8) ![]u8 {// ADR 0219: a Claude model that thinks by default spends max_tokens// on thinking first; 256 left no answer. Room, and little thinking.const claude = @import("claude_wire.zig");- const thinks = std.mem.eql(u8, provider.id, "anthropic") and claude.thinksByDefault(provider.model);+ const thinks = claude.isClaudeApi(provider.id, provider.model) and claude.thinksByDefault(provider.model);try s.objectField("max_tokens");try s.write(if (thinks) @as(u32, 4096) else max_out_tokens);if (thinks and claude.takesEffort(provider.model)) {