graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Provider specs, resolved request routes, and source-aware credential keys.
//! Re-exported by main.zig for the engine and its clients.
const std = @import("std");
const pricing = @import("pricing.zig");
const contextFor = pricing.contextFor;
/// #203: declare the context window (tokens) for an unknown/local model whose real
/// window graff cannot look up, replacing the conservative default. Applied only
/// when contextFor falls back to default_context (see contextWindowFor) so it can
/// never shrink a known/catalogued window. Set from GRAFF_CONTEXT / GRAFF_CONTEXT_WINDOW.
pub var g_context_override: ?u64 = null;
/// #204: override the auto-compaction threshold as a percent of the window
/// (default 80). null → 80. Unlike codex we allow lowering AND raising (1..100).
pub var g_compact_pct_override: ?u8 = null;
/// #502: xAI defaults to api.x.ai/v1/responses (WS, SSE fallback). Compaction
/// is the client summarizer. GRAFF_XAI_WIRE=chat opts back to chat completions.
pub var g_xai_responses: bool = true;
pub const xai_responses_url = "https://api.x.ai/v1/responses";
pub const xai_compact_url = "https://api.x.ai/v1/responses/compact";
/// The context window for a provider+model, honoring g_context_override for an
/// unknown/local model — i.e. only when contextFor returns the conservative default,
/// never overriding a known window (#203).
fn contextWindowFor(provider_id: []const u8, model: []const u8) u64 {
// Only an unknown/local model (no catalogued window) takes the override, so a
// global GRAFF_CONTEXT can never shrink a known model that happens to be 200k.
if (g_context_override) |ov| if (!pricing.isKnownModel(provider_id, model)) return ov;
return contextFor(provider_id, model);
}
/// One built-in or workspace-configured provider. Built-ins live in
/// provider_specs; one additional OpenAI-compatible router may be loaded from
/// `.graff/.config.router` at startup.
pub const ProviderSpec = struct {
pub const LoginKind = enum { api_key, codegraff_device, codex_device, kimi_device, xai_device, zai_cli, chatgpt_browser, anthropic_browser, claude_cli };
pub const CatalogKind = enum { baked, codex, kimi, openai, anthropic };
id: []const u8,
display_name: []const u8,
kind: Provider.Kind, // wire format
auth: Provider.Auth, // header style
url: []const u8,
env_key: []const u8,
default_model: []const u8,
login: LoginKind = .api_key,
/// #471: a login on this provider buys a FLAT-RATE plan (ChatGPT/Codex,
/// Kimi Code, SuperGrok), so its calls cost nothing per token and must not
/// be priced off the models.dev sheet. Declared here so a new subscription
/// provider is one field rather than a hardcoded id list in a second file.
///
/// It is the login that is flat-rate, not the vendor: an env key or `/key`
/// on the SAME provider still bills per token, so billing.zig reads this
/// only when the credential's `Keys.CredentialSource` is `.login`. The
/// codegraff gateway is deliberately false — its device login draws on
/// metered credits, not a plan.
sub_login: bool = false,
catalog: CatalogKind = .baked,
models_url: []const u8 = "",
takes_effort: bool = false,
};
pub const provider_specs = [_]ProviderSpec{
// Anthropic publishes its live model list at /v1/models (same x-api-key +
// anthropic-version auth as Messages), so new Claude releases appear
// without a rebuild; the baked pricing.zig rows stay the offline fallback.
.{ .id = "anthropic", .display_name = "Anthropic", .kind = .anthropic, .auth = .x_api_key, .url = "https://api.anthropic.com/v1/messages", .env_key = "ANTHROPIC_API_KEY", .default_model = "claude-opus-5-5", .login = .anthropic_browser, .sub_login = true, .catalog = .anthropic, .models_url = "https://api.anthropic.com/v1/models?limit=1000" },
.{ .id = "codegraff", .display_name = "Codegraff", .kind = .openai, .auth = .bearer, .url = "https://gateway.codegraff.com/v1/chat/completions", .env_key = "CODEGRAFF_API_KEY", .default_model = "mimo-v2.6-pro", .login = .codegraff_device, .catalog = .openai, .models_url = "https://gateway.codegraff.com/v1/models", .takes_effort = true },
.{ .id = "deepseek", .display_name = "DeepSeek", .kind = .openai, .auth = .bearer, .url = "https://api.deepseek.com/chat/completions", .env_key = "DEEPSEEK_API_KEY", .default_model = "deepseek-v4-pro", .takes_effort = true },
.{ .id = "openai", .display_name = "OpenAI", .kind = .responses, .auth = .bearer, .url = "https://api.openai.com/v1/responses", .env_key = "OPENAI_API_KEY", .default_model = "gpt-6-sol" },
// Google AI Studio on its first-party Interactions API — the wire Google
// says every new model and agent capability launches on, not the
// OpenAI-compatibility shim. A turn POSTs one Interaction and reads back
// execution steps; `store:false` keeps graff's own history authoritative,
// matching what it already does on the Responses wire.
.{ .id = "google", .display_name = "Google Gemini", .kind = .interactions, .auth = .goog_api_key, .url = "https://generativelanguage.googleapis.com/v1beta/interactions", .env_key = "GEMINI_API_KEY", .default_model = "gemini-3.8-flash", .catalog = .openai, .models_url = "https://generativelanguage.googleapis.com/v1beta/models?pageSize=200", .takes_effort = true },
.{ .id = "minimax", .display_name = "MiniMax", .kind = .anthropic, .auth = .bearer, .url = "https://api.minimax.io/anthropic/v1/messages", .env_key = "MINIMAX_API_KEY", .default_model = "MiniMax-M3" },
// Live list at /v1/models (Bearer, same as chat). Baked rows are the offline floor.
.{ .id = "xiaomi", .display_name = "Xiaomi", .kind = .openai, .auth = .bearer, .url = "https://api.xiaomimimo.com/v1/chat/completions", .env_key = "XIAOMI_API_KEY", .default_model = "mimo-v2.6-pro", .catalog = .openai, .models_url = "https://api.xiaomimimo.com/v1/models" },
.{ .id = "kilo", .display_name = "Kilo Gateway", .kind = .openai, .auth = .bearer, .url = "https://api.kilo.ai/api/gateway/v1/chat/completions", .env_key = "KILO_API_KEY", .default_model = "kilo-auto/small" },
.{ .id = "groq", .display_name = "Groq", .kind = .openai, .auth = .bearer, .url = "https://api.groq.com/openai/v1/chat/completions", .env_key = "GROQ_API_KEY", .default_model = "openai/gpt-oss-120b" },
.{ .id = "cerebras", .display_name = "Cerebras", .kind = .openai, .auth = .bearer, .url = "https://api.cerebras.ai/v1/chat/completions", .env_key = "CEREBRAS_API_KEY", .default_model = "gpt-oss-120b", .catalog = .openai, .models_url = "https://api.cerebras.ai/v1/models", .takes_effort = true },
.{ .id = "mistral", .display_name = "Mistral", .kind = .openai, .auth = .bearer, .url = "https://api.mistral.ai/v1", .env_key = "MISTRAL_API_KEY", .default_model = "mistral-medium-latest" },
// Kimi Code publishes the protocol per model. Missing/`kimi` is the native
// chat-completions wire; a live `protocol: anthropic` row is switched in
// Keys.build to the beta Messages endpoint + x-api-key, matching kimi-code.
.{ .id = "kimi", .display_name = "Kimi", .kind = .openai, .auth = .bearer, .url = kimi_native_url, .env_key = "KIMI_API_KEY", .default_model = "k3", .login = .kimi_device, .sub_login = true, .catalog = .kimi },
// moonshot: the regular Kimi Open Platform (pay-as-you-go API key, not the
// Coding plan). OpenAI-compatible; .cn host for China. kimi-latest tracks
// the newest Kimi. Same /v1/models discovery applies if wired later.
.{ .id = "moonshot", .display_name = "Moonshot", .kind = .openai, .auth = .bearer, .url = "https://api.moonshot.ai/v1/chat/completions", .env_key = "MOONSHOT_API_KEY", .default_model = "kimi-latest" },
// `graff login xai` is a real device-code OAuth flow (oauth.zig), so xAI's
// login is a SuperGrok plan while XAI_API_KEY is metered api.x.ai access.
.{ .id = "xai", .display_name = "xAI", .kind = .openai, .auth = .bearer, .url = "https://api.x.ai/v1/chat/completions", .env_key = "XAI_API_KEY", .default_model = "grok-4.7", .login = .xai_device, .sub_login = true, .catalog = .openai, .models_url = "https://api.x.ai/v1/models" },
.{ .id = "zai", .display_name = "Z.AI", .kind = .openai, .auth = .bearer, .url = "https://api.z.ai/api/paas/v4/chat/completions", .env_key = "ZAI_API_KEY", .default_model = "glm-5.3", .login = .zai_cli, .sub_login = true, .catalog = .openai, .models_url = "https://api.z.ai/api/paas/v4/models", .takes_effort = true },
// OpenAI-compatible Chat Completions with reasoning_effort support.
.{ .id = "meta", .display_name = "Meta", .kind = .openai, .auth = .bearer, .url = "https://api.meta.ai/v1/chat/completions", .env_key = "META_API_KEY", .default_model = "muse-spark-1.2-contributor", .catalog = .openai, .models_url = "https://api.meta.ai/v1/models", .takes_effort = true },
// Vercel AI Gateway: one key, live /models. Coding-agent surface marks
// harness traffic (docs: passthrough to /v1). Image/video are not seats.
.{ .id = "vercel", .display_name = "Vercel AI Gateway", .kind = .openai, .auth = .bearer, .url = "https://ai-gateway.vercel.sh/coding-agent/v1/chat/completions", .env_key = "AI_GATEWAY_API_KEY", .default_model = "alibaba/qwen3.8-27b", .catalog = .openai, .models_url = "https://ai-gateway.vercel.sh/coding-agent/v1/models", .takes_effort = true },
// OpenRouter: one key, live /models. OpenAI chat; HTTP-Referer + X-Title
// (openrouter.ai/docs). Not Anthropic Messages and not image/video gen.
.{ .id = "openrouter", .display_name = "OpenRouter", .kind = .openai, .auth = .bearer, .url = "https://openrouter.ai/api/v1/chat/completions", .env_key = "OPENROUTER_API_KEY", .default_model = "anthropic/claude-sonnet-4.6", .catalog = .openai, .models_url = "https://openrouter.ai/api/v1/models", .takes_effort = true },
.{ .id = "fugu", .display_name = "fugu", .kind = .openai, .auth = .bearer, .url = "https://api.sakana.ai/v1/chat/completions", .env_key = "FUGU_API_KEY", .default_model = "fugu-ultra" },
// Fireworks serves its serverless catalog live (AIP gateway shape:
// pageToken pagination, camelCase contextLength), so new model releases
// appear without a rebuild; the baked pricing.zig rows stay the offline
// fallback and supply windows for models the gateway omits.
.{ .id = "fireworks", .display_name = "fireworks", .kind = .openai, .auth = .bearer, .url = "https://api.fireworks.ai/inference/v1/chat/completions", .env_key = "FIREWORKS_API_KEY", .default_model = "accounts/fireworks/models/deepseek-v4-pro", .catalog = .openai, .models_url = "https://api.fireworks.ai/v1/accounts/fireworks/models?filter=supports_serverless%3Dtrue&pageSize=200" },
// mlx: a local model served by mlx-lm (`mlx_lm.server`) on Apple Silicon —
// OpenAI-compatible, no real key (MLX_API_KEY=local just clears graff's boot gate).
.{ .id = "mlx", .display_name = "mlx", .kind = .openai, .auth = .bearer, .url = "http://127.0.0.1:8080/v1/chat/completions", .env_key = "MLX_API_KEY", .default_model = "mlx-community/Qwen3.6-27B-OptiQ-4bit" },
// lm-studio: the LM Studio app's local OpenAI-compatible server (default :1234).
// Load a model in LM Studio, then `LMSTUDIO_API_KEY=local graff --model lmstudio`.
.{ .id = "lmstudio", .display_name = "lmstudio", .kind = .openai, .auth = .bearer, .url = "http://127.0.0.1:1234/v1/chat/completions", .env_key = "LMSTUDIO_API_KEY", .default_model = "lmstudio" },
// omlx: the oMLX menu-bar app's local server (default :8000). It requires a bearer
// key, lists the downloaded models live, and takes reasoning_effort.
.{ .id = "omlx", .display_name = "oMLX", .kind = .openai, .auth = .bearer, .url = "http://127.0.0.1:8000/v1/chat/completions", .env_key = "OMLX_API_KEY", .default_model = "omlx", .catalog = .openai, .models_url = "http://127.0.0.1:8000/v1/models", .takes_effort = true },
// chatgpt-new: the person's ChatGPT plan through OpenAI's sign-in for
// open-source apps (ADR 0221). The key is the OAuth access token saved by
// `graff login chatgpt`, sent to the public Responses endpoint. Before
// codex on purpose: it is the primary ChatGPT route (ADR 0229), so a bare
// model name and the startup default pick it when both are signed in.
.{ .id = "chatgpt-new", .display_name = "ChatGPT plan (new sign-in)", .kind = .responses, .auth = .bearer, .url = "https://api.openai.com/v1/responses", .env_key = "CHATGPT_NEW_DISABLED", .default_model = "gpt-6.1-sol", .login = .chatgpt_browser, .sub_login = true, .catalog = .openai, .models_url = "https://api.openai.com/v1/models?client_version=0.159.0" },
// codex: ChatGPT login via the Responses API. Its "key" isn't an env var
// — it's the OAuth access token read from CODEX_HOME/auth.json at startup
// (see loadCodexAuth), the same on-disk-credential trick used for the
// codegraff gateway key in ~/forge/.credentials.json.
.{ .id = "codex", .display_name = "Codex (ChatGPT)", .kind = .responses, .auth = .bearer, .url = "https://chatgpt.com/backend-api/codex/responses", .env_key = "CODEX_DISABLED", .default_model = "gpt-6-sol", .login = .codex_device, .sub_login = true, .catalog = .codex },
// claude-agent (ADR 0309): Claude through the user's own `claude` and its login, opted into with
// `graff login claude-agent`. No URL: claude_agent.zig drives the child. The "key" is its path.
.{ .id = "claude-agent", .display_name = "Claude Agent", .kind = .anthropic, .auth = .bearer, .url = "stdio:claude", .env_key = "GRAFF_CLAUDE_AGENT", .default_model = "claude-opus-5-5", .login = .claude_cli, .sub_login = true, .takes_effort = true },
};
/// Optional workspace-local router loaded from `.graff/.config.router`.
/// Its strings are owned by the process arena.
pub var additional_router: ?ProviderSpec = null;
pub fn specCount() usize {
return provider_specs.len + @intFromBool(additional_router != null);
}
pub fn specAt(index: usize) ?ProviderSpec {
if (index < provider_specs.len) return provider_specs[index];
if (index == provider_specs.len) return additional_router;
return null;
}
pub fn specFor(id: []const u8) ?ProviderSpec {
for (provider_specs) |spec| if (std.mem.eql(u8, spec.id, id)) return spec;
if (additional_router) |spec| if (std.mem.eql(u8, spec.id, id)) return spec;
return null;
}
pub const kimi_native_url = "https://api.kimi.com/coding/v1/chat/completions";
pub const kimi_anthropic_url = "https://api.kimi.com/coding/v1/messages?beta=true";
/// Endpoint overrides (GRAFF_CODEX_URL / GRAFF_CHATGPT_URL / GRAFF_XAI_URL /
/// GRAFF_ZAI_URL / GRAFF_VERCEL_URL). Parsed before Keys.build so startup,
/// /model, and session restore share one URL.
pub var g_codex_url_override: ?[]const u8 = null;
pub var g_chatgpt_url_override: ?[]const u8 = null;
pub var g_xai_url_override: ?[]const u8 = null;
pub var g_zai_url_override: ?[]const u8 = null;
pub var g_vercel_url_override: ?[]const u8 = null;
pub const zai_coding_url = "https://api.z.ai/api/coding/paas/v4/chat/completions";
pub const zai_coding_models_url = "https://api.z.ai/api/coding/paas/v4/models";
pub const vercel_v1_url = "https://ai-gateway.vercel.sh/v1/chat/completions";
fn resolvedUrl(spec: ProviderSpec, model: []const u8) []const u8 {
if (std.mem.eql(u8, spec.id, "kimi") and pricing.kimiProtocol(model) == .anthropic) return kimi_anthropic_url;
if (std.mem.eql(u8, spec.id, "codex")) return g_codex_url_override orelse spec.url;
if (std.mem.eql(u8, spec.id, "chatgpt-new")) return g_chatgpt_url_override orelse spec.url;
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;
}
pub const Provider = struct {
id: []const u8,
kind: Kind,
auth: Auth,
url: []const u8,
api_key: []const u8,
model: []const u8,
context: u64,
account: []const u8 = "", // ChatGPT account id, codex/responses only
source: Keys.CredentialSource = .none, // #148: how api_key was obtained — only .login tokens auto-refresh
// Wire format. `responses` is the first-party OpenAI Responses API (direct
// API key or ChatGPT/Codex login) — input items, not chat messages.
// `interactions` is Google's first-party Interactions API: one Interaction
// per turn, carrying an ordered list of execution STEPS (thought /
// model_output / function_call / function_result) rather than chat messages
// or Responses items. Its own SSE vocabulary is step.start/delta/stop.
pub const Kind = enum { anthropic, openai, responses, interactions };
// `goog_api_key` is Google's `x-goog-api-key` header. It is not
// interchangeable with bearer: generativelanguage rejects an API key sent
// as `Authorization: Bearer` with a 401 asking for an OAuth token.
pub const Auth = enum { x_api_key, bearer, goog_api_key };
/// Auto-compact past a percentage (default 80%) of the model's context window.
/// GRAFF_COMPACT_PCT overrides the percentage, clamped to 1..100 (#204). Unlike
/// codex's one-directional clamp, the override may lower OR raise the threshold.
pub fn compactAt(p: Provider) u64 {
if (g_compact_pct_override) |o| return p.context / 100 * @min(o, 100);
const at = p.context / 100 * 80;
return if (isGeminiModel(p.model)) @min(at, gemini_compact_tokens) else at;
}
/// Gemini's default compaction point unless a percentage is set: 80% of its
/// 1M window put ~800k billed tokens on every request near the line (ADR 0272).
pub const gemini_compact_tokens: u64 = 300_000;
pub fn isGeminiModel(model: []const u8) bool {
const bare = if (std.mem.lastIndexOfScalar(u8, model, '/')) |i| model[i + 1 ..] else model;
return std.mem.startsWith(u8, bare, "gemini-");
}
/// The provider's explicit server-side compaction endpoint, if we use it.
/// xAI still *has* POST /v1/responses/compact; we do not call it — the
/// client summarizer outperformed that blob. Codex/OpenAI compact through
/// other routes (in-stream / `/responses/compact`).
pub fn serverCompactUrl(_: Provider) ?[]const u8 {
return null;
}
/// Whether a failed compaction may safely fall back to destructive trimming.
/// Keep this stricter than compactAt(): at 80-95% a transient summary failure
/// should leave history intact and retry later. Subtraction avoids overflow for
/// provider-controlled token counts near u64.max.
pub fn nearContextLimit(p: Provider, tokens: u64) bool {
if (p.context == 0) return false;
return tokens >= p.context - (p.context / 20); // 95%
}
/// #201: absolute ceiling for a single tool output regardless of window size,
/// so a huge-context model still bounds one pathological result. Aligned with
/// codex-rs's proven default (DEFAULT_MAX_OUTPUT_TOKENS = 10_000 ≈ 40 KB at
/// 4 bytes/token); oversized outputs spill to the session artifact dir with a
/// greppable path (#409), so a tighter ceiling costs no information.
const abs_output_cap_bytes: usize = 40 * 1024;
/// #193 follow-up / #201: the largest a SINGLE tool output may be, in serialized
/// bytes, before it is truncated at send time (capOversizedToolOutputs). It must
/// stay small enough that `keep_recent` (=4) such outputs — which
/// trimOldestToolOutputs keeps VERBATIM during in-turn recovery — still leave
/// room for the trimmed remainder + system prompt to fit on retry. At the old
/// `context * 2` (~50% of the window each) four recent outputs pinned ~2x the
/// window, past what recovery could reclaim → wedge (#201). Now window-proportional
/// at ~1/8 of the window in estimated tokens (context/2 bytes at ~4 bytes/token),
/// so 4 recent outputs occupy ~50% of the window, plus an absolute ceiling for
/// very large windows. Large-context models still keep normal tool results
/// untouched; only a result big enough to threaten the window is bounded.
/// 0 (unknown window) disables the cap.
pub fn perOutputCap(p: Provider) usize {
if (p.context == 0) return 0;
const proportional: usize = @intCast(p.context / 2);
return @min(proportional, abs_output_cap_bytes);
}
/// #292: the same credential and the same provider, a different model.
/// Rebuilds exactly the fields Keys.build derives from the model name
/// (wire format, auth style, endpoint, context window) while carrying the
/// already-resolved api_key/account/source across, so a per-persona or
/// per-spawn worker pin needs no `Keys` at the spawn site — and, by
/// construction, cannot change provider. Crossing a provider boundary
/// still goes through Keys/subagentProvider and its explicit consent flag.
pub fn withModel(base: Provider, model: []const u8) Provider {
const spec = specFor(base.id) orelse {
var out = base;
out.model = model;
out.context = contextWindowFor(base.id, model);
return out;
};
const is_kimi_anthropic = std.mem.eql(u8, spec.id, "kimi") and pricing.kimiProtocol(model) == .anthropic;
const is_xai_responses = std.mem.eql(u8, spec.id, "xai") and g_xai_responses;
return .{
.id = spec.id,
.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 (std.mem.eql(u8, spec.id, "anthropic") and base.source.canRefresh()) .bearer else if (is_kimi_anthropic) .x_api_key else spec.auth,
.url = resolvedUrl(spec, model),
.api_key = base.api_key,
.model = model,
.context = contextWindowFor(spec.id, model),
.account = base.account,
.source = base.source,
};
}
};
/// The catalogued provider ids that serve `model`, in spec order, written into
/// `buf`. Lets a caller turn a bare MissingKey into a message naming the login
/// that actually needs repair (#294) — "codex has no credential" rather than
/// the old "see /models", which sent people looking at the wrong thing after an
/// expired ~/.codex/auth.json silently rerouted them to the gateway.
pub fn catalogProvidersFor(buf: [][]const u8, model: []const u8) [][]const u8 {
var n: usize = 0;
for (0..specCount()) |i| {
const spec = specAt(i).?;
if (n >= buf.len) break;
if (!pricing.providerModelInTable(spec.id, model)) continue;
buf[n] = spec.id;
n += 1;
}
return buf[0..n];
}
/// One optional API key per provider_specs entry, read from the environment.
pub const Keys = struct {
pub const CredentialSource = enum {
none,
environment,
login,
profile, // Anthropic Console SDK profile: metered, not a subscription.
stored,
session,
pub fn canRefresh(self: CredentialSource) bool {
return self == .login or self == .profile;
}
pub fn label(self: CredentialSource) []const u8 {
return switch (self) {
.none => "missing",
.environment => "environment",
.login => "OAuth/login",
.profile => "Console profile",
.stored => "secure store",
.session => "this session",
};
}
};
values: [provider_specs.len]?[]const u8,
sources: [provider_specs.len]CredentialSource = @splat(.none),
router_value: ?[]const u8 = null,
router_source: CredentialSource = .none,
codex_account: []const u8 = "", // ChatGPT account id for the codex provider
pub fn get(keys: Keys, provider_id: []const u8) ?[]const u8 {
for (provider_specs, keys.values) |spec, value| {
if (std.mem.eql(u8, spec.id, provider_id)) return value;
}
if (additional_router) |spec|
if (std.mem.eql(u8, spec.id, provider_id)) return keys.router_value;
return null;
}
pub fn source(keys: Keys, provider_id: []const u8) CredentialSource {
for (provider_specs, keys.sources) |spec, source_value| {
if (std.mem.eql(u8, spec.id, provider_id)) return source_value;
}
if (additional_router) |spec|
if (std.mem.eql(u8, spec.id, provider_id)) return keys.router_source;
return .none;
}
pub fn set(keys: *Keys, provider_id: []const u8, value: []const u8, source_value: CredentialSource) bool {
for (provider_specs, &keys.values, &keys.sources) |spec, *slot, *source_slot| {
if (!std.mem.eql(u8, spec.id, provider_id)) continue;
slot.* = value;
source_slot.* = source_value;
return true;
}
if (additional_router) |spec| {
if (std.mem.eql(u8, spec.id, provider_id)) {
keys.router_value = value;
keys.router_source = source_value;
return true;
}
}
return false;
}
pub fn build(keys: Keys, spec: ProviderSpec, key: []const u8, model: []const u8) Provider {
const is_codex = std.mem.eql(u8, spec.id, "codex");
const is_kimi_anthropic = std.mem.eql(u8, spec.id, "kimi") and pricing.kimiProtocol(model) == .anthropic;
const is_xai_responses = std.mem.eql(u8, spec.id, "xai") and g_xai_responses;
return .{
.id = spec.id,
.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 (std.mem.eql(u8, spec.id, "anthropic") and keys.source(spec.id).canRefresh()) .bearer else if (is_kimi_anthropic) .x_api_key else spec.auth,
.url = resolvedUrl(spec, model),
.api_key = key,
.model = model,
.context = contextWindowFor(spec.id, model),
.account = if (is_codex) keys.codex_account else "",
.source = keys.source(spec.id),
};
}
/// The codegraff gateway proxies almost every model, so it is a fallback
/// SEAT rather than a peer of the direct providers. Both routing
/// (`providerFor`) and the startup default (`defaultProvider`) consider it
/// only after every provider the user keyed directly, so a gateway key that
/// merely EXISTS never outranks a credential the user actually chose.
fn isGatewayFallback(provider_id: []const u8) bool {
return std.mem.eql(u8, provider_id, "codegraff");
}
/// Route a model to a provider: first active catalog row whose provider has
/// a key wins (spec order breaks ties). Unknown claude* models go to
/// Anthropic; any other unknown model goes to the codegraff gateway.
pub fn providerFor(keys: Keys, model: []const u8) error{MissingKey}!Provider {
// Prefer a direct provider the user keyed over the codegraff gateway: the
// gateway proxies almost every model, so a low gateway balance would
// otherwise block models the user can serve with their own key. Phase 0:
// direct providers, exact catalog name. Phase 1 (#377): direct providers,
// family-prefixed spelling of their own row — the gateway catalogs
// `kimi-k3` while kimi itself serves `k3`; the flat-rate login must win
// over the gateway for the same model, so the query is rewritten to the
// provider's native spelling. Phase 2: the gateway, exact, as fallback.
// Moonshot's platform id is also `kimi-k3`; when the kimi login is
// present it still wins. When only MOONSHOT_API_KEY is set, phase 0
// seats the moonshot row instead of falling through to the gateway.
// Claude Agent is the Claude plan once chosen (ADR 0309): its models, and its old aliases, route there first.
if (keys.get("claude-agent")) |exe| if (@import("claude_agent_wire.zig").routes(model)) return keys.build(specFor("claude-agent").?, exe, model);
if (keys.get("kimi")) |kimi_key| {
if (pricing.familyAliasEquals("kimi", "k3", model)) {
const spec = specFor("kimi") orelse return error.MissingKey;
return keys.build(spec, kimi_key, "k3");
}
}
for ([_]u8{ 0, 1, 2 }) |phase| {
for (0..specCount()) |i| {
const spec = specAt(i).?;
const key = keys.get(spec.id) orelse continue;
if ((phase == 2) != isGatewayFallback(spec.id)) continue;
for (pricing.models()) |m| {
if (!std.mem.eql(u8, m.provider, spec.id)) continue;
if (if (phase == 1) pricing.familyAliasEquals(spec.id, m.name, model) else std.mem.eql(u8, m.name, model))
return keys.build(spec, key, m.name);
}
}
}
// #294: a model the catalog assigns to specific providers is NOT unknown.
// If none of those providers has a credential, the user's LOGIN is what
// broke — rerouting to the gateway turns "codex login expired" into a
// gateway error about a model codex was supposed to serve. Concretely:
// gpt-5.6-sol exists only under provider `codex`, so an expired
// ~/.codex/auth.json used to route it to gateway.codegraff.com, which
// answers with a 404 or an out-of-credits error — and the user sees a
// CodeGraff balance problem while trying to use Codex.
//
// Only genuinely uncatalogued models keep the gateway fallback below,
// which is what that fallback was always for ("any other unknown model").
if (pricing.modelInTable(model)) return error.MissingKey;
const fallback_id: []const u8 = if (std.mem.startsWith(u8, model, "claude")) "anthropic" else "codegraff";
const spec = specFor(fallback_id) orelse return error.MissingKey;
const key = keys.get(fallback_id) orelse return error.MissingKey;
return keys.build(spec, key, model);
}
/// The startup default: the first provider (in spec order) with a key, on
/// its default model — the codegraff gateway last, mirroring the phase-2
/// demotion `providerFor` already applies.
///
/// #294 fixed the model-ROUTING half of this and left the STARTUP half. The
/// gateway sits at spec index 1 and `startup_keys.resolveKeys` loads its key
/// from ~/.simple-harness-codegraff.json unconditionally, so merely HAVING
/// that file seated every fresh workspace (no --model, no saved model) on
/// gateway.codegraff.com while a valid Codex login or xAI key sat further
/// down the array and lost. The user never picked the gateway, so a session
/// they believed was Codex quietly drew on gateway credits — and a gateway
/// outage broke a session that had no business touching it.
pub fn defaultProvider(keys: Keys) error{MissingKey}!Provider {
for ([_]bool{ false, true }) |gateway_pass| {
for (0..specCount()) |i| {
const spec = specAt(i).?;
if (isGatewayFallback(spec.id) != gateway_pass) continue;
const key = keys.get(spec.id) orelse continue;
return keys.build(spec, key, pricing.providerDefaultModel(spec.id, spec.default_model));
}
}
return error.MissingKey;
}
/// Rebuild a provider from a saved session's (id, model). Falls back to
/// model-based routing if the id is unknown.
pub fn providerById(keys: Keys, id: []const u8, model: []const u8) error{MissingKey}!Provider {
if (specFor(id)) |spec| {
const key = keys.get(id) orelse return error.MissingKey;
return keys.build(spec, key, model);
}
return keys.providerFor(model);
}
};
test "Provider.compactAt: auto-compacts at 80% of the context window (long-horizon trigger)" {
const big = Provider{ .id = "x", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "m", .context = 1_000_000 };
try std.testing.expectEqual(@as(u64, 800_000), big.compactAt());
const small = Provider{ .id = "x", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "m", .context = 200_000 };
try std.testing.expectEqual(@as(u64, 160_000), small.compactAt());
const zero = Provider{ .id = "x", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "m", .context = 0 };
try std.testing.expectEqual(@as(u64, 0), zero.compactAt());
}
test "Provider.nearContextLimit: destructive recovery starts at 95% without overflow math" {
const p: Provider = .{ .id = "x", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "x", .context = 100_000 };
try std.testing.expect(!p.nearContextLimit(94_999));
try std.testing.expect(p.nearContextLimit(95_000));
try std.testing.expect(p.nearContextLimit(std.math.maxInt(u64)));
var unknown = p;
unknown.context = 0;
try std.testing.expect(!unknown.nearContextLimit(std.math.maxInt(u64)));
}
test "Keys.providerFor: known model, claude/gateway fallbacks, missing key" {
const all = Keys{ .values = @splat("k") };
const none = Keys{ .values = @splat(null) };
try std.testing.expectEqualStrings("anthropic", (try all.providerFor("claude-does-not-exist")).id);
try std.testing.expectEqualStrings("codegraff", (try all.providerFor("totally-made-up-model")).id);
try std.testing.expectEqualStrings("gpt-5.5", (try all.providerFor("gpt-5.5")).model);
try std.testing.expectError(error.MissingKey, none.providerFor("claude-opus-4-8"));
}
test "Keys.defaultProvider: first keyed provider on its default model" {
const all = Keys{ .values = @splat("k") };
const p = try all.defaultProvider();
try std.testing.expectEqualStrings("anthropic", p.id); // anthropic leads provider_specs
try std.testing.expectEqualStrings("claude-opus-5-5", p.model);
const none = Keys{ .values = @splat(null) };
try std.testing.expectError(error.MissingKey, none.defaultProvider());
}
test "workspace router behaves like an additional provider" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const saved_router = additional_router;
const saved_models = pricing.active_model_table;
defer {
additional_router = saved_router;
pricing.active_model_table = saved_models;
}
additional_router = .{
.id = "myrouter",
.display_name = "My Router",
.kind = .openai,
.auth = .bearer,
.url = "https://router.example.com/v1/chat/completions",
.env_key = "MYROUTER_API_KEY",
.default_model = "example/model",
.catalog = .openai,
.models_url = "https://router.example.com/v1/models",
};
const rows = [_]pricing.ModelInfo{
.{ .provider = "myrouter", .name = "example/model", .context = 200_000 },
};
try std.testing.expect(pricing.activateProviderModels(arena_state.allocator(), "myrouter", &rows));
var keys: Keys = .{ .values = @splat(null) };
try std.testing.expect(keys.set("myrouter", "token", .session));
try std.testing.expectEqualStrings("token", keys.get("myrouter").?);
try std.testing.expectEqual(Keys.CredentialSource.session, keys.source("myrouter"));
const explicit = try keys.providerById("myrouter", "example/model");
try std.testing.expectEqualStrings("https://router.example.com/v1/chat/completions", explicit.url);
try std.testing.expectEqualStrings("myrouter", (try keys.providerFor("example/model")).id);
try std.testing.expectEqualStrings("myrouter", (try keys.defaultProvider()).id);
var ids: [provider_specs.len + 1][]const u8 = undefined;
const serving = catalogProvidersFor(&ids, "example/model");
try std.testing.expectEqualStrings("myrouter", serving[0]);
}
test "contextWindowFor (#203): GRAFF_CONTEXT overrides only an unknown/local model" {
g_context_override = 8192;
defer g_context_override = null;
// unknown/local model (no catalogued window) → the override applies
try std.testing.expectEqual(@as(u64, 8192), contextWindowFor("lmstudio", "some-local-gguf"));
// a known, catalogued model keeps its real window even with the override set
try 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);
}