graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
codex: default effort and text verbosity follow the model catalog
justrach8bd3b81faaea
diff --git a/docs/adr/0226-codex-follows-the-catalog-effort-and-verbosity.md b/docs/adr/0226-codex-follows-the-catalog-effort-and-verbosity.mdnew file mode 100644index 00000000..a562afe4--- /dev/null+++ b/docs/adr/0226-codex-follows-the-catalog-effort-and-verbosity.md@@ -0,0 +1,40 @@+# 0226. Codex requests follow the model catalog's default effort and verbosity++Status: accepted 2026-10-01++## Context++The codex model catalog gives each model a default reasoning level and a+default text verbosity, and the route's own client sends both. graff sent+`medium` effort to every codex model the user had not set, and no+`text.verbosity`, so the server's `medium` applied. On a model whose catalog+default is `low` for both, each graff turn reasoned and wrote more than the+route's own client does.++A hill-climb round on wall time against a reference harness measured the+catalog defaults together with ADR 0227. Each change alone moved wall time+within noise. Together they cut it on the train and the held-out split, with+pass rate held.++## Decision++- `pricing.ModelInfo` has `default_verbosity`. The static codex rows carry+ the catalog's default effort and verbosity. `models_cache` reads both for+ the dynamic rows (`default_reasoning_level` or graff's `default_effort`,+ and `default_verbosity`) and writes them back. A value the wire does not+ accept is dropped, not guessed.+- `effort_route.wireEffort`: on the codex provider, `medium` (graff's+ default) is sent as the model's catalog default. Any other level is sent+ as chosen.+- The codex Responses body carries the catalog's `text.verbosity`.+ Compaction summaries and requests with a JSON output schema do not.++## Consequences++On a model whose catalog default is `low`, a turn reasons and writes less+and finishes sooner. `medium` is also the unset value, so an explicit+`/effort medium` on such a model sends the catalog default too; the same+function already maps `medium` this way for some other models. Choose+`high` for deeper reasoning. Revisit if a harder suite loses pass rate at+the catalog default, or when the catalog's defaults change: dynamic rows+follow it, the static rows are updated by hand.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 7f53c6ee..69c5e3f7 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -252,6 +252,7 @@ record only when you need the evidence or the edge cases.| [0223](0223-codex-cache-partition-is-the-account.md) | Codex with a ChatGPT account id partitions the prompt cache by account, not repo: the system+tools prefix carries no cwd, so turn 1 in any repo reads the prefix another repo warmed. Children keep their role lanes on the account base; other providers keep the project key (ADR 0069). || [0224](0224-six-rare-natives-join-the-fold.md) | `render_html`, `agent_message`, `install_agent_tool`, `read_tool_result`, `subagent_resume` and `schedule_task` join `native_fold.folded`: listed by `load_tool_schemas`, auto-loaded on a confident call, no longer paid on every request. || [0225](0225-mcp-load-result-states-the-slim-rule.md) | Every MCP load/search/select result says how large list results are slimmed (identity fields; comment lists become `{n, latest_author}`), so a fresh project does not code against dropped fields. A direct call's slimmed result keeps the full payload as a `read_tool_result` handle; rlm binds stay plain slim JSON. |+| [0226](0226-codex-follows-the-catalog-effort-and-verbosity.md) | On the codex provider, graff's default `medium` effort is sent as the model catalog's default level, and the Responses body carries the catalog's `text.verbosity` (not on compaction or output-schema requests). Any other effort is sent as chosen. |## When to write onediff --git a/src/agent_request_body_responses.zig b/src/agent_request_body_responses.zigindex ae406260..51229aa4 100644--- a/src/agent_request_body_responses.zig+++ b/src/agent_request_body_responses.zig@@ -112,7 +112,15 @@ pub fn write(self: *Agent, s: *std.json.Stringify, tools: ?[]const u8, force_tootry s.write(false);server_compact.noteExposure(self);try server_compact.writeContextManagement(self, s);- if (self.output_schema) |schema_json| try writeTextFormat(s, schema_json);+ if (self.output_schema) |schema_json| try writeTextFormat(s, schema_json) else if (!self.compaction_request and !self.server_compaction_request) {+ if (@import("effort_route.zig").catalogVerbosity(self.provider.id, self.provider.model)) |v| {+ try s.objectField("text");+ try s.beginObject();+ try s.objectField("verbosity");+ try s.write(v);+ try s.endObject();+ }+ }// Prewarm: generate:false and no transport fields — connection setup, not inference (openai/codex).if (self.ws_prewarm) try s.objectField("generate") else try s.objectField("stream");// No top-level max_output_tokens: codex rejects it ("Unsupported parameter") on gpt-5.6-*.diff --git a/src/effort_route.zig b/src/effort_route.zigindex ddaf512d..07466947 100644--- a/src/effort_route.zig+++ b/src/effort_route.zig@@ -108,6 +108,31 @@ pub fn normalize(provider_id: []const u8, model: []const u8, requested: []constreturn requested;}+/// ADR 0226: on the codex route graff's default effort (medium) and text+/// verbosity follow the model's catalog defaults, as the route's own client+/// does. Any other effort is sent as chosen.+fn codexCatalog(provider_id: []const u8, model: []const u8) ?@import("pricing.zig").ModelInfo {+ if (!std.mem.eql(u8, provider_id, "codex")) return null;+ return @import("pricing.zig").modelInfoFor(provider_id, model);+}++pub fn catalogVerbosity(provider_id: []const u8, model: []const u8) ?[]const u8 {+ const info = codexCatalog(provider_id, model) orelse return null;+ return info.default_verbosity;+}++pub const effort_levels = [_][]const u8{ "minimal", "low", "medium", "high", "xhigh", "max" };+pub const verbosity_levels = [_][]const u8{ "low", "medium", "high" };++/// ADR 0226: a catalog default the wire accepts, under graff's compact key+/// or Codex's own; anything else is dropped, not guessed.+pub fn catalogLevel(arena: std.mem.Allocator, obj: std.json.ObjectMap, keys: []const []const u8, allowed: []const []const u8) ?[]const u8 {+ for (keys) |key| if (@import("util.zig").strFieldObj(obj, key)) |v| {+ for (allowed) |level| if (std.mem.eql(u8, v, level)) return arena.dupe(u8, level) catch null;+ };+ return null;+}+pub fn allows(provider_id: []const u8, model: []const u8, tag: []const u8) bool {for (levels(provider_id, model)) |level| if (std.mem.eql(u8, tag, level)) return true;return false;@@ -118,6 +143,7 @@ pub fn allows(provider_id: []const u8, model: []const u8, tag: []const u8) bool/// `max`). Other seats still send ultra as `max` (including OpenAI).pub fn wireEffort(provider_id: []const u8, model: []const u8, requested: []const u8) []const u8 {if (mimoRoute(provider_id, model)) return if (std.mem.eql(u8, requested, "none")) "none" else "high";+ if (std.mem.eql(u8, requested, "medium")) if (codexCatalog(provider_id, model)) |info| if (info.default_effort) |d| return d;if (std.mem.eql(u8, requested, "medium") and omitsDefaultFlashEffort(model)) return "low";if (grokFamily(model)) {if (std.mem.eql(u8, requested, "max") or std.mem.eql(u8, requested, "ultra")) return "high";@@ -216,3 +242,28 @@ test "MiMo exposes only Off and On while legacy positive settings remain On" {try std.testing.expectEqualStrings("low", wireEffort("custom", "mimo-v2.6-flash", "low"));try std.testing.expectEqualStrings("low", wireEffort("zai", "glm-5.3-flash", "medium"));}++test "codex: the default medium follows the model's catalog; explicit levels and other routes do not" {+ try std.testing.expectEqualStrings("low", wireEffort("codex", "gpt-6.1-sol", "medium"));+ try std.testing.expectEqualStrings("high", wireEffort("codex", "gpt-6.1-sol", "high"));+ try std.testing.expectEqualStrings("low", wireEffort("codex", "gpt-6.1-sol", "low"));+ try std.testing.expectEqualStrings("medium", wireEffort("codex", "gpt-6-sol", "medium"));+ try std.testing.expectEqualStrings("medium", wireEffort("openai", "gpt-6.1-sol", "medium"));+ try std.testing.expectEqualStrings("low", catalogVerbosity("codex", "gpt-6.1-sol").?);+ try std.testing.expect(catalogVerbosity("openai", "gpt-6.1-sol") == null);+}++test "codex bodies carry the catalog text verbosity; a compaction summary does not" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ var agent = try @import("agent_request_body_responses.zig").testAgentFor(a, "codex", .responses, "gpt-6.1-sol");+ const body = try agent.buildBody(null, false, true, true);+ defer std.testing.allocator.free(body);+ try std.testing.expect(std.mem.indexOf(u8, body, "\"verbosity\":\"low\"") != null);+ try std.testing.expect(std.mem.indexOf(u8, body, "\"effort\":\"low\"") != null);+ agent.compaction_request = true;+ const summary = try agent.buildBody(null, false, true, true);+ defer std.testing.allocator.free(summary);+ try std.testing.expect(std.mem.indexOf(u8, summary, "\"verbosity\"") == null);+}diff --git a/src/models_cache.zig b/src/models_cache.zigindex 24ff082c..14cc864e 100644--- a/src/models_cache.zig+++ b/src/models_cache.zig@@ -144,6 +144,8 @@ fn parseCodexSnapshot(arena: Allocator, data: []const u8) ?CodexSnapshot {.provider = "codex",.name = arena.dupe(u8, slug) catch continue,.context = context,+ .default_effort = @import("effort_route.zig").catalogLevel(arena, item.object, &.{ "default_effort", "default_reasoning_level" }, &@import("effort_route.zig").effort_levels),+ .default_verbosity = @import("effort_route.zig").catalogLevel(arena, item.object, &.{"default_verbosity"}, &@import("effort_route.zig").verbosity_levels),}) catch continue;}const models = rows.toOwnedSlice(arena) catch return null;@@ -259,7 +261,10 @@ fn writeCodexCache(io: Io, arena: Allocator, home: []const u8, version: []constaw.writer.writeAll("{\"name\":") catch return;var name_stringify: std.json.Stringify = .{ .writer = &aw.writer };name_stringify.write(model.name) catch return;- aw.writer.print(",\"context\":{d}}}", .{model.context}) catch return;+ aw.writer.print(",\"context\":{d}", .{model.context}) catch return;+ if (model.default_effort) |v| aw.writer.print(",\"default_effort\":\"{s}\"", .{v}) catch return;+ if (model.default_verbosity) |v| aw.writer.print(",\"default_verbosity\":\"{s}\"", .{v}) catch return;+ aw.writer.writeByte('}') catch return;}aw.writer.writeAll("]}\n") catch return;for ([_][]const u8{ codexDirPath(arena, home), codexFlatPath(arena, home) }) |path| {diff --git a/src/models_cache_tests.zig b/src/models_cache_tests.zigindex 5ed03bec..2cfe5fdf 100644--- a/src/models_cache_tests.zig+++ b/src/models_cache_tests.zig@@ -70,6 +70,22 @@ pub fn visibleSnapshots(parse_snapshot: anytype) !void {try std.testing.expectEqual(@as(u64, 372_000), snapshot.models[0].context);try std.testing.expectEqualStrings("future-luna", snapshot.models[1].name);try std.testing.expectEqual(@as(u64, 128_000), snapshot.models[1].context);++ // ADR 0226: Codex's own defaults ride along (native keys and graff's+ // compact cache keys); a level the wire does not accept is dropped.+ const defaults = parse_snapshot(arena.allocator(),+ \\{"models":[+ \\ {"slug":"native","visibility":"list","default_reasoning_level":"low","default_verbosity":"low"},+ \\ {"name":"compact","context":272000,"default_effort":"high","default_verbosity":"medium"},+ \\ {"slug":"odd","visibility":"list","default_reasoning_level":"extreme","default_verbosity":"loud"},+ \\ {"slug":"plain","visibility":"list"}]}+ ).?;+ try std.testing.expectEqualStrings("low", defaults.models[0].default_effort.?);+ try std.testing.expectEqualStrings("low", defaults.models[0].default_verbosity.?);+ try std.testing.expectEqualStrings("high", defaults.models[1].default_effort.?);+ try std.testing.expectEqualStrings("medium", defaults.models[1].default_verbosity.?);+ try std.testing.expect(defaults.models[2].default_effort == null and defaults.models[2].default_verbosity == null);+ try std.testing.expect(defaults.models[3].default_effort == null and defaults.models[3].default_verbosity == null);}pub fn versionFloor(floor: []const u8, effective_version: anytype, snapshot_matches: anytype) !void {diff --git a/src/pricing.zig b/src/pricing.zigindex 2c60e7ee..9cb8ba08 100644--- a/src/pricing.zig+++ b/src/pricing.zig@@ -159,6 +159,9 @@ pub const ModelInfo = struct {thinking_support: ThinkingSupport = .unknown,support_efforts: []const []const u8 = &.{},default_effort: ?[]const u8 = null,+ /// Codex catalog `default_verbosity` (ADR 0226): the `text.verbosity` the+ /// route's own client sends for this model.+ default_verbosity: ?[]const u8 = null,};pub const ModelProtocol = enum { provider_default, kimi, anthropic };diff --git a/src/pricing_models.zig b/src/pricing_models.zigindex 7e648c81..fb14ae55 100644--- a/src/pricing_models.zig+++ b/src/pricing_models.zig@@ -57,9 +57,9 @@ pub const rows = [_]ModelInfo{// Offline snapshot only: at startup models_cache.zig replaces the whole// Codex slice from the account-scoped /models response (5-minute cache).// These rows keep Codex usable when auth or discovery is unavailable.- .{ .provider = "codex", .name = "gpt-6-astra", .context = 272_000 },- .{ .provider = "codex", .name = "gpt-6-sol", .context = 272_000 },- .{ .provider = "codex", .name = "gpt-6.1-sol", .context = 272_000 },+ .{ .provider = "codex", .name = "gpt-6-astra", .context = 272_000, .default_effort = "medium", .default_verbosity = "low" },+ .{ .provider = "codex", .name = "gpt-6-sol", .context = 272_000, .default_effort = "medium", .default_verbosity = "low" },+ .{ .provider = "codex", .name = "gpt-6.1-sol", .context = 272_000, .default_effort = "low", .default_verbosity = "low" },.{ .provider = "codex", .name = "gpt-5.6-sol", .context = 272_000 },.{ .provider = "codex", .name = "gpt-5.6-terra", .context = 272_000 },.{ .provider = "codegraff", .name = "muse-spark-1.2", .context = 262_144 },diff --git a/src/prompt_astra.zig b/src/prompt_astra.zigindex eed5155e..0044e2ec 100644--- a/src/prompt_astra.zig+++ b/src/prompt_astra.zig@@ -114,7 +114,14 @@ test "GPT6 emitted requests keep one stable guidance block and refresh on modeltry testing.expect(std.mem.indexOf(u8, instructions, "# GPT-6 Sol working guidance") == null);try testing.expect(std.mem.indexOf(u8, instructions, "# GPT-6.1 Sol working guidance") == null);}- try testing.expectEqualStrings(if (std.mem.eql(u8, model, "mimo-v2.6-flash")) (if (std.mem.eql(u8, provider, "codegraff")) "high" else "low") else "medium", parsed.value.object.get("reasoning").?.object.get("effort").?.string);+ // ADR 0226: on codex the default medium is the catalog's level (low for gpt-6.1-sol).+ const effort: []const u8 = if (std.mem.eql(u8, model, "mimo-v2.6-flash"))+ (if (std.mem.eql(u8, provider, "codegraff")) "high" else "low")+ else if (std.mem.eql(u8, provider, "codex") and std.mem.eql(u8, model, "gpt-6.1-sol"))+ "low"+ else+ "medium";+ try testing.expectEqualStrings(effort, parsed.value.object.get("reasoning").?.object.get("effort").?.string);var followup: std.json.ObjectMap = .empty;try followup.put(a, "role", .{ .string = "user" });try followup.put(a, "content", .{ .string = "continue with the requested work" });