graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Lookup-shape detector. Used to decide a prompt is Q&A vs mutation.
//! The harness does NOT infer low effort from prompt shape: effort is part of
//! the cached prefix and a change may miss the cache and reset the WS chain.
//! Explicit /effort, a worker effort pin, or an optional jev_effort call may
//! change it; Jev applies only at the next request boundary.
const std = @import("std");
/// Case-insensitive substring check, no allocation.
fn containsI(haystack: []const u8, needle: []const u8) bool {
if (needle.len > haystack.len) return false;
var i: usize = 0;
while (i + needle.len <= haystack.len) : (i += 1) {
if (std.ascii.eqlIgnoreCase(haystack[i .. i + needle.len], needle)) return true;
}
return false;
}
const lookup_cues = [_][]const u8{
"what ", "what's", "how do", "how does", "how is", "where ",
"which ", "why ", "explain", "list ", "tell me", "describe",
"show me", "summarize", "who ", "?", "do not modify", "do not change",
"don't change", "read-only",
};
const mutation_cues = [_][]const u8{
"fix", "implement", " add ", "update ", "refactor", "write ",
"create", "delete", "remove ", "rewrite", "build ", "run ",
"commit", "install", "rename", "patch", "bump", "edit ",
"change the", "change this",
// NOTE: bare "modify "/"change " are deliberately absent — read-only tasks
// habitually end with "do not modify any files", and poisoning on that
// phrase would exclude exactly the prompts this router exists for.
};
/// True when a prompt is shaped like a read-only lookup: it carries a question
/// or explanation cue and NO mutation cue. Conservative by construction — a
/// miss just means the turn runs at the session default.
pub fn routesToLowEffort(prompt: []const u8) bool {
if (prompt.len < 12) return false; // "fix it" is short; questions carry words
for (mutation_cues) |cue| if (containsI(prompt, cue)) return false;
for (lookup_cues) |cue| if (containsI(prompt, cue)) return true;
return false;
}
/// Never auto-route. Kept so a caller cannot quietly reintroduce a prefix
/// flip: the gate is closed for root and children alike.
pub fn shouldRouteLookupLow(_: bool, _: bool, _: []const u8) bool {
return false;
}
/// Default `medium` thinking on flash / Gemini is silent seconds of TTFT
/// (ADR 0046). Gemini 3.x maps it to thinking_level; GLM flash through
/// codegraff thinks when the field is omitted. `/effort` still sends.
/// Do not treat this as a 4-tool catalog shrink.
pub fn omitsDefaultFlashEffort(model: []const u8) bool {
if (std.mem.startsWith(u8, model, "gemini")) return true;
// Astra is not flash: medium is a supported effort and must stay medium (#1084).
return std.mem.indexOf(u8, model, "flash") != null;
}
/// grok-4.6 (xAI docs): low | medium | high | xhigh. `max`/`ultra` 400.
pub fn grokFamily(model: []const u8) bool {
return std.mem.startsWith(u8, model, "grok");
}
/// MiMo's current APIs expose thinking as a binary switch. Gateway catalog
/// rows may include a family prefix; inspect the final model component.
/// ADR 0235: the switch is On only at high and above. graff's default
/// (medium) leaves it Off: MiMo thinks at length on every call when it is on.
pub fn mimoFamily(model: []const u8) bool {
const name = if (std.mem.lastIndexOfScalar(u8, model, '/')) |slash| model[slash + 1 ..] else model;
return std.ascii.startsWithIgnoreCase(name, "mimo-");
}
pub fn mimoRoute(provider_id: []const u8, model: []const u8) bool {
return (std.mem.eql(u8, provider_id, "xiaomi") or std.mem.eql(u8, provider_id, "codegraff")) and mimoFamily(model);
}
/// Hide Max/Ultra in the picker when the current seat cannot take them.
pub fn hidesMax(provider_id: []const u8, model: []const u8) bool {
return std.mem.eql(u8, provider_id, "xai") or grokFamily(model);
}
fn openaiFamily(provider_id: []const u8, model: []const u8) bool {
return std.mem.eql(u8, provider_id, "openai") or std.mem.eql(u8, provider_id, "codex") or
std.mem.startsWith(u8, model, "gpt-") or std.mem.startsWith(u8, model, "openai/gpt-");
}
/// Picker tags, not API values: OpenAI's maximum is exposed as Ultra.
/// Keep xAI's stricter allow-list ahead of model-family detection.
pub fn levels(provider_id: []const u8, model: []const u8) []const []const u8 {
if (mimoRoute(provider_id, model)) return &.{ "none", "high" };
if (hidesMax(provider_id, model)) return &.{ "low", "medium", "high", "xhigh" };
if (openaiFamily(provider_id, model)) return &.{ "low", "medium", "high", "xhigh", "ultra" };
return &.{ "low", "medium", "high", "xhigh", "max", "ultra" };
}
/// Accept old saved/typed Max settings without putting Max back in the UI.
/// Ultra keeps its existing wire mapping to `max` and delegation guidance.
pub fn normalize(provider_id: []const u8, model: []const u8, requested: []const u8) []const u8 {
if (mimoRoute(provider_id, model)) {
for ([_][]const u8{ "none", "off", "minimal", "low", "medium" }) |below|
if (std.mem.eql(u8, requested, below)) return "none";
for ([_][]const u8{ "high", "xhigh", "max", "ultra", "on" }) |positive|
if (std.mem.eql(u8, requested, positive)) return "high";
return requested;
}
if (std.mem.eql(u8, requested, "none")) return ""; // unsupported outside MiMo
if (!hidesMax(provider_id, model) and openaiFamily(provider_id, model) and std.mem.eql(u8, requested, "max")) return "ultra";
return 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;
}
/// Wire `reasoning_effort` for an effort-capable provider. Flash / Gemini
/// default `medium` becomes `low`. grok maps max/ultra → high (xAI rejects
/// `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 normalize(provider_id, model, requested);
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";
return requested;
}
if (std.mem.eql(u8, requested, "ultra")) return "max";
return requested;
}
test "lookup prompts route low, mutation prompts and bare commands do not" {
// The three benchmark tasks are the pinned shape: two route low, and the
// one that REGRESSED at low effort (permgate) must not route.
try std.testing.expect(routesToLowEffort("In src/main.zig of this repository, what does the function runEval do, and which other functions or methods does it call? Answer in 4-5 sentences. Do not modify any files."));
try std.testing.expect(routesToLowEffort("In this repository, list the AI model providers graff supports, and for each give its wire-format/auth style and the environment variable for its API key. Be concise. Do not modify any files."));
try std.testing.expect(!routesToLowEffort("In this repository, how does the permission gate decide whether a bash command needs approval, and what rule lets read-only commands run without prompting? Name the key function(s) by name. Answer in 4-5 sentences. Do not modify any files.")); // "run without" — the task that inflated at low
try std.testing.expect(!routesToLowEffort("fix the failing test in agent.zig"));
try std.testing.expect(!routesToLowEffort("implement the feature and update the docs"));
try std.testing.expect(!routesToLowEffort("hi"));
try std.testing.expect(routesToLowEffort("Explain how the permission gate works here?"));
const q = "Explain how the permission gate works here?";
try std.testing.expect(!shouldRouteLookupLow(false, true, q));
try std.testing.expect(!shouldRouteLookupLow(true, true, q));
}
test "flash and Gemini map default medium to low; grok and glm-5.3 stay medium" {
try std.testing.expect(omitsDefaultFlashEffort("glm-5.3-flash"));
try std.testing.expect(omitsDefaultFlashEffort("gemini-3.7-flash"));
try std.testing.expect(omitsDefaultFlashEffort("gemini-3.7-pro"));
try std.testing.expect(omitsDefaultFlashEffort("deepseek-v4-flash"));
try std.testing.expect(!omitsDefaultFlashEffort("grok-4.6"));
try std.testing.expect(!omitsDefaultFlashEffort("glm-5.3"));
try std.testing.expect(!omitsDefaultFlashEffort("deepseek-v4-pro"));
try std.testing.expect(!omitsDefaultFlashEffort("gpt-6-astra"));
try std.testing.expectEqualStrings("medium", wireEffort("openai", "gpt-6-astra", "medium"));
try std.testing.expectEqualStrings("high", wireEffort("openai", "gpt-5.6-sol", "high"));
try std.testing.expectEqualStrings("high", wireEffort("openai", "gpt-6-astra", "high"));
try std.testing.expectEqualStrings("low", wireEffort("zai", "glm-5.3-flash", "medium"));
try std.testing.expectEqualStrings("high", wireEffort("zai", "glm-5.3-flash", "high"));
try std.testing.expectEqualStrings("medium", wireEffort("xai", "grok-4.6", "medium"));
try std.testing.expectEqualStrings("high", wireEffort("xai", "grok-4.6", "ultra"));
try std.testing.expectEqualStrings("high", wireEffort("xai", "grok-4.6", "max"));
try std.testing.expectEqualStrings("xhigh", wireEffort("xai", "grok-4.6", "xhigh"));
try std.testing.expectEqualStrings("xhigh", wireEffort("xai", "grok-4.7", "xhigh"));
try std.testing.expectEqualStrings("high", wireEffort("xai", "grok-4.7", "ultra"));
try std.testing.expect(hidesMax("xai", "grok-4.6"));
try std.testing.expect(hidesMax("xai", "grok-4.7"));
try std.testing.expect(!hidesMax("codex", "gpt-5.6-sol"));
try std.testing.expect(!allows("xai", "grok-4.6", "max"));
try std.testing.expect(allows("xai", "grok-4.6", "high"));
}
// GPT-5.6 (sol / terra / luna, bare alias, gateway names) accepts
// reasoning.effort up to `max`. The picker shows OpenAI's maximum as Ultra, so
// a typed or saved `max` must normalize to that tag and still reach the wire
// as the API value `max`; grok's allow-list keeps rejecting it. Default stays
// `medium` (Agent.reasoning), which the API also documents as its default.
test "GPT-5.6 family: max is accepted (as Ultra) and wired as max; grok still folds it" {
const seats = [_]struct { id: []const u8, model: []const u8 }{
.{ .id = "openai", .model = "gpt-5.6" },
.{ .id = "openai", .model = "gpt-5.6-terra" },
.{ .id = "openai", .model = "gpt-5.6-luna" },
.{ .id = "codex", .model = "gpt-5.6-sol" },
.{ .id = "codegraff", .model = "openai/gpt-5.6-sol" },
};
for (seats) |s| {
try std.testing.expectEqualStrings("ultra", normalize(s.id, s.model, "max"));
try std.testing.expect(allows(s.id, s.model, "ultra"));
try std.testing.expect(allows(s.id, s.model, "xhigh"));
try std.testing.expectEqualStrings("max", wireEffort("openai", s.model, "ultra"));
try std.testing.expectEqualStrings("xhigh", wireEffort("openai", s.model, "xhigh"));
try std.testing.expectEqualStrings("medium", wireEffort("openai", s.model, "medium")); // not a flash/Astra seat: default medium is sent as-is
}
try std.testing.expectEqualStrings("max", normalize("xai", "grok-4.6", "max")); // untouched, then refused
try std.testing.expect(!allows("xai", "grok-4.6", "max"));
try std.testing.expect(!allows("xai", "grok-4.6", "ultra"));
}
test "ADR 0235: MiMo exposes Off and On, and thinks only at high and above" {
for ([_][]const u8{ "mimo-v2.6-flash", "MiMo-V2.6-Pro", "xiaomi/mimo-v2.6-pro" }) |model| {
try std.testing.expect(mimoFamily(model));
const offered = levels("codegraff", model);
try std.testing.expectEqual(@as(usize, 2), offered.len);
try std.testing.expectEqualStrings("none", offered[0]);
try std.testing.expectEqualStrings("high", offered[1]);
try std.testing.expectEqualStrings("none", normalize("xiaomi", model, "off"));
try std.testing.expectEqualStrings("none", wireEffort("codegraff", model, "none"));
for ([_][]const u8{ "minimal", "low", "medium" }) |below| { // medium is graff's default
try std.testing.expectEqualStrings("none", normalize("xiaomi", model, below));
try std.testing.expectEqualStrings("none", wireEffort("codegraff", model, below));
}
for ([_][]const u8{ "high", "xhigh", "max", "ultra", "on" }) |positive| {
try std.testing.expectEqualStrings("high", normalize("xiaomi", model, positive));
try std.testing.expectEqualStrings("high", wireEffort("codegraff", model, positive));
}
}
try std.testing.expectEqualStrings("", normalize("openai", "gpt-6-astra", "none"));
try std.testing.expect(!allows("openai", "gpt-6-astra", "none"));
try std.testing.expect(!allows("custom", "mimo-v2.6-flash", "none"));
try std.testing.expectEqualStrings("", normalize("custom", "mimo-v2.6-flash", "none"));
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);
}