graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Post-arg-parse setup helpers carved out of main() (600-line goal, #123
//! follow-up — the last file over the line goal). Only the setup that is
//! SAFELY separable lives here: pure computations over env/disk/arena that
//! return plain values, with no stack-address capture.
//!
//! DANGLING-POINTER TRAP (why the rest of main()'s setup stays in main()):
//! `tracer`/`traj`/`telem` are stack-allocated in main() and hold pointers
//! into OTHER main()-stack-allocated storage (`trace_writer`/`traj_writer`,
//! which themselves wrap stack buffers, and `&client`). A helper that
//! constructed those structs itself would return a value whose pointer
//! fields point into the HELPER's own stack frame — invalid the instant the
//! helper returns. So that construction (and the MCP-registry/approvals/
//! hooks/theme block, which is additionally tangled with several `defer`s
//! and a mid-block early `return` for --selftest-spinner) is intentionally
//! left inline in main(), per the split's own guidance: don't force an
//! extraction that can't be done without an address-capture or defer-order
//! hazard.
//!
//! Back-imports main (as main_mod, the established convention) only where a
//! helper's signature needs main.zig's own re-exported types (Provider is
//! provider.zig-resident and imported directly below instead). Sibling-
//! imports provider/keys_cli/oauth/pricing/serde/skills/prompts directly —
//! all already `pub` for their existing cross-module callers — so nothing
//! needed a fresh pub-flip for this split.
const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const builtin = @import("builtin");
const mcp = @import("mcp.zig");
const provider_mod = @import("provider.zig");
const keys_cli = @import("keys_cli.zig");
const oauth = @import("oauth.zig");
const models_cache = @import("models_cache.zig");
const pricing_db = @import("pricing_db.zig");
const kimi_catalog = @import("kimi_catalog.zig");
const router_config = @import("router_config.zig");
const router_catalog = @import("router_catalog.zig");
const serde = @import("serde.zig");
const skills = @import("skills.zig");
const skill_docs = @import("skill_docs.zig");
const fleet = @import("fleet.zig"); // g_home: resolved before any prompt build (session_run.initApprovalsHooksFleet)
const prompts = @import("prompts.zig");
const learn_store = @import("learn_store.zig");
const learn_bootstrap = @import("learn_bootstrap.zig");
const learn_auto = @import("learn_auto.zig");
const build_options = @import("build_options"); // .learn: is `graff learn` in this build
const imagegen = @import("imagegen.zig"); // #352: codex-skill detection + the personal-tier skill mirror
const plugins = @import("plugins.zig");
const startup_keys = @import("startup_keys.zig");
pub const ResolvedKeys = startup_keys.ResolvedKeys;
pub const storedKeyMayAffectSelection = startup_keys.storedKeyMayAffectSelection;
pub const startupStoredKeyScope = startup_keys.startupStoredKeyScope;
pub const resolveSubagentProvider = startup_keys.resolveSubagentProvider;
pub const resolveKeys = startup_keys.resolveKeys;
/// Root system-prompt layering, frozen at startup so it stays
/// KV-cache-friendly: built-in base (or its --system-prompt replacement),
/// then project instructions from the first of AGENTS.md/HARNESS.md/
/// CLAUDE.md found in the cwd, then --append-system-prompt text, then one
/// capability line per active optional skill, then one usage note per
/// connected MCP server. `quiet` suppresses startup diagnostics; interactive
/// callers clear it only for GRAFF_REPL_DEBUG, while JSON and one-shot modes
/// always keep stdout clean. Carved out of main()'s
/// former inline block verbatim — pure over io/arena, returns everything by
/// value, so it's safe to call from outside main()'s own stack frame.
/// The last edge of the learning loop: a genome this workspace actually
/// promoted becomes the root prompt, not just a subagent persona. Generation 0
/// is the unmodified snapshot of some build's own prompt, so only a promoted
/// generation takes over — otherwise a freshly initialized store would pin an
/// older build's wording forever. Corrupt or foreign state fails closed.
fn learnedRootPolicy(io: Io, arena: Allocator) ?learn_store.ActiveAgent {
const learned = learn_store.loadActiveAgent(io, arena) orelse return null;
if (learned.generation == 0) return null;
if (!std.mem.eql(u8, learned.name, learn_bootstrap.root_policy_agent)) return null;
if (std.mem.trim(u8, learned.prompt, " \t\r\n").len == 0) return null;
if (!learn_store.validId(learned.genome_id)) return null;
return learned;
}
pub fn buildSystemPrompt(
io: Io,
arena: Allocator,
out: *Io.Writer,
system_prompt_flag: ?[]const u8,
append_system_flag: ?[]const u8,
quiet: bool,
unattended: bool,
mcp_tools: []const mcp.Tool,
codedbpro_licensed: bool,
learned_policy_env: ?[]const u8,
environ: anytype,
) ![]const u8 {
// #421: settle the git_repo gate before the base composes — commit/PR
// authoring guidance is only sent where a repository exists to act on.
prompts.probeGitRepo(io);
// A learned policy is used unless this session opted out of it.
const learned: ?learn_store.ActiveAgent = if (comptime !build_options.learn)
null
else if (system_prompt_flag == null and learn_auto.enabled(learned_policy_env)) learnedRootPolicy(io, arena) else null;
if (learned) |policy| if (!quiet) {
try out.print("root policy: learned generation {d} ({s})\n", .{ policy.generation, policy.genome_id[0..12] });
try out.flush();
};
const base_prompt: []const u8 = system_prompt_flag orelse
if (learned) |policy| policy.prompt else try prompts.baseForSession(arena); // #421: built-in base minus the segments whose capability this process lacks
var sys_normal: []const u8 = base_prompt;
for ([_][]const u8{ "AGENTS.md", "HARNESS.md", "CLAUDE.md" }) |fname| {
const body = Io.Dir.cwd().readFileAlloc(io, fname, arena, .limited(64 * 1024)) catch continue;
const trimmed = std.mem.trim(u8, body, " \t\r\n");
if (trimmed.len == 0) continue;
const capped = @import("context_limits.zig").applyAlloc(arena, trimmed, @import("context_limits.zig").agents_md_bytes);
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n# Project instructions (from {s})\n{s}", .{ base_prompt, fname, capped });
@import("hot_context.zig").noteBaked(fname, capped); // #1333: later edits arrive as keyed updates
if (!quiet) {
try out.print("loaded project instructions from {s} ({d} bytes)\n", .{ fname, trimmed.len });
try out.flush();
}
break;
}
if (append_system_flag) |extra| {
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ sys_normal, extra });
}
// Repo map (repo_map.zig): the top of the working tree, so the model reads
// the files it needs instead of spending opening turns on ls/find.
// Lean one-shots name their files; the map is an interactive opener
// and was prefix bytes on every -p turn (ADR 0024).
if (environ.get("GRAFF_NO_REPO_MAP") == null and !@import("no_local_tools.zig").lean) {
if (@import("repo_map.zig").segment(io, arena)) |map| sys_normal = try std.fmt.allocPrint(arena, "{s}{s}", .{ sys_normal, map });
}
if (unattended) sys_normal = try std.fmt.allocPrint(arena, "{s}{s}", .{ sys_normal, prompts.unattended_note });
// ADR 0030 / 0011: do not splice rlm_spec.system_note onto the always-on
// prefix. Small turns must not advertise rlm/sPTC; discovery is the
// catalog tail after showcase (--rlm, a wide native batch, or context
// ≥50% of compactAt).
// Codex-style skills: one capability line per installed optional
// companion (skills_registry) — metadata in context, --help on demand.
// Lean one-shots do not need companion essays (ADR 0024 prefix tax).
const lean = @import("no_local_tools.zig").lean;
if (!lean) {
for (skills.skills_registry) |sk| {
if (sk.note.len == 0 or !skills.skillActive(io, sk)) continue;
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ sys_normal, sk.note });
}
// Same idea for known MCP servers: a usage note enters the context only
// when the server actually connected this session (consent given, spawn
// succeeded). Native tools remain the fallback either way.
for (skills.mcp_notes) |mn| {
if (!skills.mcpServerConnected(mcp_tools, mn.server)) continue;
const note = skills.codedbproNote(mn.server, codedbpro_licensed, mn.note);
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ sys_normal, note });
}
}
// #352: mirror the Codex imagegen skill into ~/.harness/skills BEFORE the
// scan below, so the copied playbook is in this session's catalog. The same
// call decides whether `imagegen` is advertised (tool_gates.zig) and which
// of its two engines this machine can actually run.
imagegen.detect(io, arena, .{ .codex_home = environ.get("CODEX_HOME"), .home = fleet.g_home, .openai_api_key = environ.get("OPENAI_API_KEY"), .tmp_dir = environ.get("TMPDIR") });
if (imagegen.available and !quiet) {
try out.print("imagegen: Codex skill found — tool enabled ({s}), playbook at {s}\n", .{ imagegen.engineSummary(), imagegen.skill_dir });
try out.flush();
}
// Markdown skills (skill_docs.zig): names + trigger descriptions only.
// Pinned once into the system-prompt prefix so later turns hit the
// prompt cache (Codex: old prompt is an exact prefix of the new one).
// The `skill` tool rescans without rewriting this prefix.
if (!lean) {
skill_docs.g_skills = skill_docs.load(io, arena, fleet.g_home);
const skill_catalog = skill_docs.promptCatalog(arena, skill_docs.g_skills);
if (skill_catalog.len > 0) {
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ sys_normal, skill_catalog });
}
for (skill_docs.g_skills) |sk| if (sk.source == .project) {
skill_docs.g_workspace_skills = true;
};
} else {
// Lean leaves out the personal catalog, but not the skills this
// workspace ships: a task that says "use the X skill" must see it.
const local = skill_docs.loadProject(io, arena, fleet.g_home);
if (local.len > 0) {
skill_docs.g_skills = local;
skill_docs.g_workspace_skills = true;
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ sys_normal, skill_docs.promptCatalog(arena, local) });
}
}
// #326: this returns the composed BASE only. prompts.setSystemPrompts()
// (called once by buildRootAgent, the sole consumer) derives
// sys_normal/sys_strict/sys_ultra/sys_ultra_strict from it — the single
// funnel every later mutation (repl, set_agent, set_system_prompt) must
// also go through, so none of the four ever go stale independently.
// #629: --experiment is armed before this runs; the spawn mandate rides
// sys_base so a later playbook refresh cannot drop it.
if (@import("experiment_pool.zig").directive()) |d|
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ sys_normal, d });
return sys_normal;
}
const args = @import("args.zig");
const acp_preauth = @import("acp_preauth.zig");
const mcp_cli = @import("mcp_cli.zig");
const learn_cli = @import("learn_cli.zig");
const cli = @import("cli.zig");
const jobs = @import("jobs.zig");
const job_registry = @import("job_registry.zig"); // #199
const cube = @import("cube.zig");
const schema = @import("schema.zig");
const serve = @import("serve.zig");
const remote_control = @import("remote_control.zig"); // #722: serve without a listener
const remote_client = @import("remote_client.zig"); // #722: `graff remote …`
const main_mod = @import("main.zig");
/// The session-child settings `graff serve` and `graff remote-control` share:
/// both spawn the same `<exe> --json` children from the same flags.
fn serveConfig(flags: args.Flags, environ: anytype) serve.ServeConfig {
return .{
.host = flags.host_flag,
.port = flags.port_flag,
.token = flags.token_flag orelse environ.get("HARNESS_SERVE_TOKEN") orelse environ.get("GRAFF_SERVE_TOKEN"),
.yolo = flags.yolo_flag,
.model = flags.model_flag,
.subagent_provider = flags.subagent_provider_flag,
.subagent_model = flags.subagent_model_flag,
.allow_cross_provider_subagents = flags.allow_cross_provider_subagents_flag,
.no_subagent_tier = flags.no_subagent_tier_flag,
.system_prompt = flags.system_prompt_flag,
.append_system_prompt = flags.append_system_flag,
.max_tool_calls = main_mod.max_tool_calls,
.max_model_calls = main_mod.max_model_calls,
.dedupe_tool_calls = main_mod.dedupe_tool_calls,
};
}
/// A credentialed ACP launch returns the exact ResolvedKeys value used before
/// #613. Only a launch with no usable provider enters the lightweight loop;
/// every other terminal trajectory keeps resolveKeys' existing fatal behavior.
pub fn resolveKeysOrRunAcpPreAuth(io: Io, gpa: Allocator, arena: Allocator, init: std.process.Init, flags: args.Flags) !?ResolvedKeys {
const worker_hint = flags.subagent_provider_flag orelse init.environ_map.get("GRAFF_SUBAGENT_PROVIDER");
// Before key resolution: the startup catalog load reads it (catalog_selection.startupLoads).
if (flags.allow_cross_provider_subagents_flag) @import("subagent_selection.zig").g_cross_provider_consent = true;
const is_acp = flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "acp");
if (!is_acp) return try resolveKeys(io, gpa, arena, init.environ_map, flags.model_flag, worker_hint);
if (try startup_keys.resolveKeysOptional(io, gpa, arena, init.environ_map, flags.model_flag, worker_hint)) |resolved| return resolved;
try acp_preauth.run(io, gpa, main_mod.harness_version);
return null;
}
/// `graff models` lists, `graff refresh` is `graff models refresh`, `graff route` dry-runs seating.
pub const CatalogCommand = enum { none, list, refresh, route };
pub fn catalogCommand(name: []const u8) CatalogCommand {
if (std.mem.eql(u8, name, "models")) return .list;
if (std.mem.eql(u8, name, "refresh")) return .refresh;
if (std.mem.eql(u8, name, "route")) return .route;
return .none;
}
/// The early subcommand/flag branches that exit before any credential
/// resolution or Agent construction happens — `--help`/`--version`, `key`,
/// `mcp add`, `login`, `serve`, `update`, `worktree` (list/merge), `sandboxes`,
/// `cube`, `refresh`, and `--schema`. Moved verbatim out of main() (600-line goal,
/// #123 follow-up). Returns true when a branch handled the run and main()
/// should return immediately without going any further (credential
/// resolution, Agent construction, the REPL/turn loop, ...).
pub fn runSubcommand(io: Io, gpa: Allocator, arena: Allocator, init: std.process.Init, flags: args.Flags) !bool {
// `--help` / `--version`: handled before any subcommand dispatch, so
// `harness login --help` prints usage instead of starting an OAuth flow.
if (flags.help_flag or flags.version_flag) {
var hbuf: [4096]u8 = undefined;
var hw = Io.File.stdout().writer(io, &hbuf);
try @import("cli_text.zig").print(gpa, &hw.interface, flags.help_flag, main_mod.harness_version);
try hw.interface.flush();
return true;
}
if (flags.oneshot_prompt == null and flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "tui"))
std.process.fatal("use graff tui [arguments]: put tui before its flags", .{});
router_config.load(io, arena) catch |err|
std.process.fatal("invalid {s}: {s}", .{ router_config.path, @errorName(err) });
// #402: pin THE codex credential directory ($CODEX_HOME, else ~/.codex) before
// anything can read or write auth.json — `graff login` is dispatched below,
// and every later reader (startup, /login, the mid-turn refresh, subagents)
// resolves through this one answer instead of guessing.
oauth.initCodexHome(arena, init.environ_map.get("CODEX_HOME"), keys_cli.homeEnv(init.environ_map));
// #477: same pin for the kimi/xai credential files, so home-less side
// agents (the pre-compaction note, title, reflect) resolve the ONE file
// the login flow writes instead of "/.kimi/...".
oauth.initHome(keys_cli.homeEnv(init.environ_map) orelse "");
job_registry.home = keys_cli.homeEnv(init.environ_map) orelse ""; // #199: ownership records for background jobs
@import("sim_ledger.zig").init(arena, io, keys_cli.homeEnv(init.environ_map) orelse "", init.environ_map); // #407
@import("sim_pasteboard.zig").init(init.environ_map); // #1801
// #1267: tool children get graff's environment minus its credentials.
// After router_config.load (its key is one of them), before `serve` and
// the other subcommands below can spawn a tool.
@import("tool_env.zig").init(arena, init.environ_map);
@import("gui_background.zig").install(io, keys_cli.homeEnv(init.environ_map) orelse "", @import("gui_background.zig").real_open); // #832
// #557: same pin for GRAFF_PRICES_PATH, before `graff models` is dispatched
// below — the hydration points (router_catalog, models_cache) all sit well
// under the last call that still holds the environment.
pricing_db.initOverride(init.environ_map.get("GRAFF_PRICES_PATH"));
// `harness key set <provider> <key>` / `harness key list`: safe key store
// (macOS Keychain, else a 0600 file). Exits after.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "key")) {
const home = keys_cli.homeEnv(init.environ_map) orelse std.process.fatal("no HOME/USERPROFILE", .{});
try keys_cli.keyCommand(io, gpa, arena, home, flags.positionals.items[1..]);
return true;
}
// MCP list/login read the workspace config merged with the user-level
// ~/.codegraff/mcp.json (hence environ_map, for the GRAFF_MCP_CONFIG
// override); add still writes workspace-only. OAuth login validates HOME itself.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "mcp")) {
const home = keys_cli.homeEnv(init.environ_map) orelse "";
// CLI never reaches session_settings.applyEnvKnobs; honor the same
// GRAFF_NO_PLUGINS gate the REPL / --json session uses.
plugins.applyEnv(init.environ_map);
try mcp_cli.mcpCommand(io, gpa, arena, home, init.environ_map, flags.positionals.items[1..]);
return true;
}
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "computer")) {
const home = keys_cli.homeEnv(init.environ_map) orelse "";
try @import("computer_cli.zig").command(io, gpa, arena, home, flags.positionals.items[1..]);
return true;
}
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "plugins")) {
const home = keys_cli.homeEnv(init.environ_map) orelse "";
plugins.applyEnv(init.environ_map);
try plugins.command(io, arena, home, flags.positionals.items[1..]);
return true;
}
// `graff learn ...`: local immutable policy learning. It runs before key
// resolution and normal session construction; configured child tools get
// only their explicitly allowlisted environment.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "learn")) {
if (comptime !build_options.learn)
std.process.fatal("learn: `graff learn` is not included in this build", .{});
learn_cli.command(io, gpa, arena, init, flags.positionals.items[1..]) catch |err|
std.process.fatal("learn: {s}", .{@errorName(err)});
return true;
}
// `harness login [name] [--refresh]`: OAuth login. Default target is
// codegraff (device-code flow, writes ~/.simple-harness-codegraff.json);
// `chatgpt` is the plan's sign-in (chatgpt-new, ADR 0229); `codex` (or
// --refresh) runs the Codex PKCE/refresh flow → ~/.codex/auth.json.
// args.loginTarget owns the names.
if (flags.login_flag) {
const home = keys_cli.homeEnv(init.environ_map) orelse std.process.fatal("no HOME/USERPROFILE", .{});
if (flags.claude_agent_login) @import("claude_agent_login.zig").login(io, arena, init.environ_map, home) catch std.process.exit(1) else if (flags.anthropic_console_login) try @import("anthropic_profile.zig").login(io, arena, init.environ_map, home) else if (flags.anthropic_login) try @import("oauth_anthropic.zig").login(io, gpa, arena, home, flags.refresh_flag) else if (flags.chatgpt_login) try @import("oauth_chatgpt.zig").login(io, gpa, arena, home) else if (flags.xai_login) try oauth.xaiLogin(io, gpa, arena, home) else if (flags.kimi_login) try oauth.kimiLogin(io, gpa, arena, home, flags.kimi_region) else if (flags.zai_login) try oauth.zaiLogin(io, gpa, arena, home) else if (flags.codex_login or flags.refresh_flag) try oauth.codexLogin(io, gpa, arena, home, flags.refresh_flag) else try oauth.codegraffLogin(io, gpa, arena, home);
return true;
}
// `graff logout chatgpt`: revoke the plan's refresh token, clear the tokens.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "logout")) {
const home = keys_cli.homeEnv(init.environ_map) orelse std.process.fatal("no HOME/USERPROFILE", .{});
const target = if (flags.positionals.items.len > 1) flags.positionals.items[1] else "";
if (std.mem.eql(u8, @import("args.zig").loginTarget(target) orelse "", "claude-agent")) {
try @import("claude_agent_login.zig").logout(io, arena, home);
return true;
}
const plan = std.mem.eql(u8, @import("args.zig").loginTarget(target) orelse "", "chatgpt-new");
if (!plan) std.process.fatal("graff logout supports: chatgpt, claude-agent", .{});
try @import("oauth_chatgpt.zig").logout(io, gpa, arena, home);
return true;
}
// `harness serve`: HTTP/NDJSON bridge over the --json protocol — each
// session is a `harness --json` child of this same binary. Keys are
// loaded by the children, not here.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "serve")) {
const exe = std.process.executablePathAlloc(io, arena) catch
std.process.fatal("serve: cannot resolve own executable path", .{});
try serve.serveMain(gpa, io, serveConfig(flags, init.environ_map), exe);
return true;
}
// `graff remote-control [--name <n>]`: the serve supervisor with no
// listener — dials OUT to the gateway with the `graff login` key and takes
// commands from the account's relay (#722). Same session children as serve.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "remote-control")) {
const home = keys_cli.homeEnv(init.environ_map) orelse std.process.fatal("no HOME/USERPROFILE", .{});
const cg_key = init.environ_map.get("CODEGRAFF_API_KEY") orelse oauth.loadCodegraffKey(io, arena, home) orelse
std.process.fatal("remote-control: no codegraff key — run `graff login` first", .{});
const exe = std.process.executablePathAlloc(io, arena) catch
std.process.fatal("remote-control: cannot resolve own executable path", .{});
try remote_control.remoteControlMain(gpa, io, .{
.base = init.environ_map.get("GRAFF_REMOTE_BASE") orelse main_mod.codegraff_device_base,
.key = cg_key,
.home = home,
.name = flags.name_flag,
.hostname_env = init.environ_map.get("COMPUTERNAME") orelse init.environ_map.get("HOSTNAME"),
.serve = serveConfig(flags, init.environ_map),
}, exe);
return true;
}
// `graff remote [sessions|agents|new|send|answer|tail|cancel|close]`: drive
// the sessions of any machine running `graff remote-control` on this login.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "remote")) {
const cg_key = init.environ_map.get("CODEGRAFF_API_KEY") orelse
(if (keys_cli.homeEnv(init.environ_map)) |home| oauth.loadCodegraffKey(io, arena, home) else null) orelse
std.process.fatal("remote: no codegraff key — run `graff login` first", .{});
const base = init.environ_map.get("GRAFF_REMOTE_BASE") orelse main_mod.codegraff_device_base;
try remote_client.command(io, gpa, arena, base, cg_key, flags.positionals.items[1..], .{ .model = flags.model_flag, .yolo = flags.yolo_flag });
return true;
}
// `harness update [--force|--check]`: self-update to the latest GitHub
// release. Version-checked (skips if already current), reuses install.sh
// for the actual download/codesign/atomic swap. Exits after.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "update")) {
// --check never installs, so --force has no effect on it — reject the
// contradictory combination up front rather than silently ignoring one.
if (flags.update_force and flags.update_check)
std.process.fatal("--force and --check are mutually exclusive — use `graff update` (without --check) to install", .{});
if (flags.update_beta) {
if (flags.update_force) std.process.fatal("--force is not supported with --beta", .{});
try cli.updateBetaCommand(io, gpa, arena, init.environ_map, flags.update_check);
} else {
try cli.updateCommand(io, gpa, arena, init.environ_map, flags.update_force, flags.update_check);
}
return true;
}
// `graff worktree list` / `graff worktree merge <name>`: manage the per-tab
// scratch worktrees that -w creates. merge squash-lands a tab's work as one
// clean commit on the current branch, then removes the worktree + branch.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "worktree")) {
try jobs.worktreeCommand(gpa, io, arena, flags.positionals.items[1..]);
return true;
}
// `graff harness-tree …`: the harness (instructions, skills, subagents,
// scripts, hooks) as one value: show, digest, check, apply, diff.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "harness-tree")) {
try @import("harness_tree_cli.zig").command(io, arena, flags.positionals.items[1..]);
return true;
}
// `graff servers [stop <pid>|prune]`: background servers graff started —
// this session's or an earlier one's (#199).
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "servers")) {
try @import("servers_cmd.zig").command(gpa, io, arena, flags.positionals.items[1..]);
return true;
}
// `graff peer <list|send|inbox>`: the device's agent rooms for any agent
// with a shell (Claude Code, Codex, scripts), not only graff sessions.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "peer")) {
try @import("peer_cli.zig").command(gpa, io, arena, init.environ_map.get("HOME") orelse "", init.environ_map.get("GRAFF_PEER_NAME"), flags.positionals.items[1..]);
return true;
}
// `graff keys …`: the end-to-end encrypted login vault (harness ADR 0005).
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "keys")) {
try @import("keys_vault_cli.zig").command(gpa, io, arena, init.environ_map.get("HOME") orelse "", init.environ_map, flags.positionals.items[1..]);
return true;
}
// `graff sandboxes [stop <id>]`: list the account's gateway sandboxes or
// spin one down. Key resolution mirrors a normal run: CODEGRAFF_API_KEY
// env first, else the `graff login` file via loadCodegraffKey.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "sandboxes")) {
const cg_key = init.environ_map.get("CODEGRAFF_API_KEY") orelse
(if (keys_cli.homeEnv(init.environ_map)) |home| oauth.loadCodegraffKey(io, arena, home) else null) orelse
std.process.fatal("sandboxes: no codegraff key — run `graff login` first", .{});
try cube.sandboxesCommand(io, gpa, arena, cg_key, flags.positionals.items[1..]);
return true;
}
// `graff cube [new|status|stop]`: a personal cloud graff — a gateway
// sandbox running `graff serve` behind a Daytona preview URL. This is the
// broker the iOS app mirrors; any serve client can attach with the
// printed base + token.
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "cube")) {
const cg_key = init.environ_map.get("CODEGRAFF_API_KEY") orelse
(if (keys_cli.homeEnv(init.environ_map)) |home| oauth.loadCodegraffKey(io, arena, home) else null) orelse
std.process.fatal("cube: no codegraff key — run `graff login` first", .{});
try cube.cubeCommand(io, gpa, arena, cg_key, flags.positionals.items[1..]);
return true;
}
// `graff models [refresh]` / `graff refresh` / `graff route <model>…`:
// print the catalog or pull fresh metadata; route dry-runs seating.
const catalog = if (flags.positionals.items.len > 0) catalogCommand(flags.positionals.items[0]) else .none;
if (catalog != .none) {
const home = keys_cli.homeEnv(init.environ_map) orelse std.process.fatal("no HOME/USERPROFILE", .{});
const codex_home = oauth.codexHomeDir(arena, home) orelse "";
const codex_auth = oauth.loadCodexAuthFrom(io, arena, codex_home);
const refreshing = catalog == .refresh or (flags.positionals.items.len > 1 and
(std.mem.eql(u8, flags.positionals.items[1], "refresh") or
std.mem.eql(u8, flags.positionals.items[1], "--refresh") or
std.mem.eql(u8, flags.positionals.items[1], "update")));
models_cache.loadCodexCatalog(
io,
gpa,
arena,
home,
codex_home,
if (codex_auth) |auth| auth.token else "",
if (codex_auth) |auth| auth.account else "",
refreshing,
true,
);
const kimi_token = init.environ_map.get("KIMI_API_KEY") orelse oauth.loadKimiOAuth(io, gpa, arena, home, false, null) orelse "";
_ = kimi_catalog.load(io, gpa, arena, kimi_token);
var router_keys: provider_mod.Keys = .{ .values = @splat(null) };
for (provider_mod.provider_specs, &router_keys.values, &router_keys.sources) |spec, *value, *source| {
if (!router_catalog.dynamic(spec)) continue;
// Prefer flat-rate device logins over env keys so `graff models`
// sees the same SuperGrok/Kimi session the REPL would, and so
// always-live xAI catalog GETs send X-XAI-Token-Auth.
if (spec.login == .xai_device) {
if (oauth.loadXaiOAuth(io, gpa, arena, home, false, null)) |tok| {
value.* = tok;
source.* = .login;
continue;
}
} else if (spec.login == .kimi_device) {
if (oauth.loadKimiOAuth(io, gpa, arena, home, false, null)) |tok| {
value.* = tok;
source.* = .login;
continue;
}
} else if (spec.login == .zai_cli) {
if (oauth.loadZaiOAuth(io, gpa, arena, home, false, null)) |tok| {
value.* = tok;
source.* = .login;
continue;
}
} else if (spec.login == .chatgpt_browser) {
if (@import("oauth_chatgpt.zig").loadChatgptOAuth(io, gpa, arena, home, false, null)) |tok| {
value.* = tok;
source.* = .login;
continue;
}
} else if (spec.login == .codegraff_device) {
if (oauth.loadCodegraffKey(io, arena, home)) |tok| {
value.* = tok;
source.* = .login;
continue;
}
}
if (init.environ_map.get(spec.env_key)) |env_key| {
value.* = env_key;
source.* = .environment;
} else if (keys_cli.loadStoredKey(io, arena, home, spec.id)) |stored| {
value.* = stored;
source.* = .stored;
}
}
if (provider_mod.additional_router) |spec| {
router_keys.router_value = init.environ_map.get(spec.env_key) orelse
keys_cli.loadStoredKey(io, arena, home, spec.id);
router_keys.router_source = if (router_keys.router_value != null) .stored else .none;
}
router_catalog.loadAll(io, gpa, arena, home, router_keys, refreshing);
const refresh_args = [_][]const u8{"refresh"};
switch (catalog) {
.route => try @import("route_check.zig").command(io, gpa, arena, init.environ_map, flags.positionals.items[1..]),
.refresh => try models_cache.command(io, gpa, arena, home, &refresh_args),
.list => try models_cache.command(io, gpa, arena, home, flags.positionals.items[1..]),
.none => unreachable,
}
return true;
}
// `--schema`: print the machine-readable interface and exit. Still no keys,
// network, or MCP — so it works anywhere (CI codegen calls this). The one
// reads are router catalog caches a normal run already wrote: the GUI
// builds its model picker from this output, so without it the picker shows
// a release-old snapshot of a list the gateway changes on its own schedule.
// No cache (CI, fresh install) → the baked table, byte-identical to before.
if (flags.schema_flag) {
router_catalog.loadCachedAll(io, arena, keys_cli.homeEnv(init.environ_map) orelse "");
var sbuf: [8 * 1024]u8 = undefined;
var sw = Io.File.stdout().writer(io, &sbuf);
try schema.emitSchema(&sw.interface);
return true;
}
if (!main_mod.json_mode and flags.oneshot_prompt == null and init.environ_map.get("GRAFF_REPL_DEBUG") != null)
@import("server_diagnostics.zig").warnStartup(arena, io);
return false;
}