Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

38.5 KB
Raw Blame
/**
 * Agent providers — the CLI a worker runs on. The app is no longer Claude-only:
 * a worker can run Claude Code, the OpenAI Codex CLI (`codex`), Kimi Code
 * (`kimi`), xAI Grok (`grok`), the Antigravity CLI (`agy`, Gemini models), or
 * any custom command.
 * Each provider declares how to build its spawn command (model/auto-mode flags) and
 * whether it accepts the hive's Claude-specific identity injection
 * (`--append-system-prompt` + `--settings`).
 *
 * Shared between main and renderer; keep it dependency-free (no electron, no UI).
 * Mirrors the shape of the upstream provider-preset work (PR #47 / issue #21) so
 * the two reconcile cleanly — this build adds the `antigravity` preset alongside
 * the existing `codex` preset.
 */
import type { CmdGroup } from './claudeCommands';
import { COMMAND_GROUPS as CLAUDE_COMMAND_GROUPS } from './claudeCommands';
import { CODEX_COMMAND_GROUPS } from './codexCommands';
import { GROK_COMMAND_GROUPS } from './grokCommands';

// NOTE: 'claw' (claw-code) was removed as a selectable provider — its upstream is
// an unmaintained "museum exhibit" repo, not a production CLI. Re-add a supported
// fork here (plus its preset/models/logo) after review. The proxy-bridge tier it
// shared with qwen stays in place for qwen.
export type AgentProvider =
  | 'claude'
  | 'codex'
  | 'grok'
  | 'kimi'
  | 'gemini'
  | 'antigravity'
  | 'qwen'
  | 'opencode'
  | 'crush'
  | 'pi'
  | 'copilot'
  | 'cursor'
  | 'custom';

/** Structured descriptor for how a NON-hiveAware provider gets hive lifecycle
 *  events (live status + Stop→inbox-drain + cost), introduced alongside the legacy
 *  `hookBridge` so call sites can switch on `bridge.kind` without a big-bang
 *  rewrite. Two kinds:
 *   - 'hooks'  → a config-file hook shim is installed (agy/codex). Derived from the
 *               legacy `hookBridge` by `bridgeOf`, so agy/codex keep working with no
 *               preset change.
 *   - 'proxy'  → the CLI has NO hook surface (qwen), so a loopback reverse-proxy
 *               sidecar observes its LLM traffic and SYNTHESIZES the same HIVE_SOCK
 *               payloads the shims emit. `api` selects the usage/tool-call shape
 *               (OpenAI vs Anthropic), `baseUrlEnv` is the env var the CLI reads for
 *               its upstream base URL (the sidecar's loopback URL is injected there),
 *               and `inboxDelivery` is how mail reaches it ('terminal' work-order
 *               handoff today; 'serve' reserved for a future HTTP push path). */
export type BridgeDescriptor =
  | { kind: 'hooks'; shim: 'agy' | 'codex' | 'pi' | 'opencode' | 'grok' | 'gemini' }
  | {
      kind: 'proxy';
      api: 'openai' | 'anthropic';
      baseUrlEnv: string;
      inboxDelivery: 'terminal' | 'serve';
    };

export interface AgentProviderPreset {
  id: AgentProvider;
  label: string;
  /** The binary spawned when the user hasn't typed a custom command. */
  defaultCommand: string;
  /** Slash / CLI command reference for this provider. */
  commandGroups: CmdGroup[];
  /** Environment variable to set for non-interactive / first-run suppression. */
  nonInteractiveEnv?: Record<string, string>;
  /** Flag(s) appended to the command string when auto mode is active.
   *  Kept alongside `autoFlag` (same value) for the HEAD consumers that read
   *  `autoModeFlag` via `autoModeFlagForProvider`. */
  autoModeFlag: string;
  /** Show a model picker and splice the model into the command. */
  supportsModel: boolean;
  /** Flag that selects the session model, e.g. `--model`. */
  modelFlag?: string;
  /** Flag appended when the floor is in auto (skip-permissions) mode.
   *  PR #54 consumers read this; mirrors `autoModeFlag`. */
  autoFlag?: string;
  /** Claude Code accepts the hive identity injection (`--append-system-prompt`
   *  + hook `--settings`). Other CLIs don't — they spawn with the shared AGENT_*
   *  env only. Gates the Claude-specific spawn injection in hive.ensureAgent.
   *  NOTE: this gates the *Claude-only* flag path specifically — it is NOT the
   *  same as "participates in the hive". A non-hiveAware provider can still be a
   *  full hive citizen (live status + guarded idle delivery) via a `hookBridge`. */
  hiveAware: boolean;
  /** Which config-file lifecycle-hook bridge a NON-hiveAware provider uses to get
   *  the same live status that Claude gets from `--settings`:
   *    - 'agy'   → installAgyHooks() writes ~/.gemini/.../hooks.json (translating
   *                shim, because agy's stdin/stdout shape differs from Claude's).
   *    - 'codex' → installCodexHooks() writes a per-agent CODEX_HOME config and
   *                reuses the Claude `cth-hook` shim verbatim (Codex's hook payload
   *                + response contract are already Claude-shaped).
   *    - 'grok'  → installGrokHooks() installs an AGENT_ID-scoped adapter for
   *                Grok's camelCase lifecycle payloads.
   *  Claude leaves this undefined (it uses its native `--settings` path, gated by
   *  hiveAware); `custom` leaves it undefined (no bridge → no hooks). This is the
   *  single switch hive.ensureAgent dispatches on to wire the bridge. */
  hookBridge?: 'agy' | 'codex' | 'grok';
  /** Structured bridge descriptor (the forward-looking replacement for the legacy
   *  `hookBridge`). Set explicitly only for PROXY-tier providers (qwen) that
   *  have no hook file to install; agy/codex leave it undefined and `bridgeOf`
   *  derives `{kind:'hooks'}` from their `hookBridge`. claude/custom leave it
   *  undefined (no bridge). Prefer `bridgeOf(provider)` over reading this directly. */
  bridge?: BridgeDescriptor;
  /** The model the GOD orchestrator ("Michael") defaults to when this provider
   *  powers it — surfaced as the picker default and the advisory "give Michael a
   *  longer-context, higher-capability model". `modelForRole` resolves the GOD
   *  model as `config.godModel ?? preset.recommendedOrchestratorModel ?? MODEL_GOD`.
   *  Advisory + user-overridable. */
  recommendedOrchestratorModel?: string;
  /** Whether the router may DELIVER inbox mail to this provider (vs bouncing it
   *  to the god). Requires lifecycle status so the renderer can deliver only at a
   *  safe idle prompt: Claude natively, Antigravity/Codex/Grok via hook bridges.
   *  A hookless custom provider cannot expose safe-idle state, so mail bounces.
   *  Distinct from hiveAware: agy/codex/grok are NOT hiveAware (no Claude injection)
   *  but CAN receive inbox via their bridge. */
  canReceiveInbox: boolean;
  /** For non-hive-aware CLIs that still take an INITIAL prompt to orient the
   *  session (Antigravity's `agy -i "<prompt>"`), the flag to pass it under. The
   *  hive identity+protocol rides in as the first turn — the closest thing to
   *  Claude's `--append-system-prompt` these CLIs offer. undefined means this
   *  provider has no flag form; positional delivery must be declared explicitly
   *  with `positionalInitialPrompt`. */
  initialPromptFlag?: string;
  /** How the hive protocol seed is delivered for a CLI that takes NEITHER a flag
   *  nor a positional seed. `'type-into-tui'` = the CLI is a bare interactive TUI
   *  that rejects a positional initial prompt (Crush: its first positional is read
   *  as a Cobra SUBCOMMAND → `Unknown command "You are…"`), so the harness must NOT
   *  append the protocol to argv — it spawns the bare TUI and hands the protocol
   *  back as `seedPrompt`, which the renderer types into the TUI's editor after boot
   *  (through the SAME per-pty write-chain as the inbox-wake nudge, so they can't
   *  collide). Absent/undefined = today's flag-or-positional behavior. (ondev-b) */
  seedDelivery?: 'type-into-tui';
  /** This CLI accepts the initial hive prompt as a trailing positional argument.
   *  Codex/Grok/Pi do; Kimi/custom do not, so they must spawn bare when no prompt
   *  flag exists instead of receiving an invalid positional argument. */
  positionalInitialPrompt?: boolean;
  /** Flag to resume a prior session on respawn, given the recorded session id
   *  (Claude `--resume <sid>`, Antigravity `--conversation <id>`). undefined = no
   *  resume support, spawn fresh. */
  resumeFlag?: string;
  /** Shell command that installs this provider's engine CLI when it's missing,
   *  e.g. `npm install -g @anthropic-ai/claude-code`. When set, the missing-CLI
   *  path may RUN it visibly in the agent terminal (after pre-spawn detection);
   *  when undefined, the user is shown a manual instruction only and nothing is
   *  auto-run. MUST be a trusted, hardcoded constant — never user/manifest input. */
  installCommand?: string;
  /** A SELF-CONTAINED installer that needs no Node/npm at all, per platform.
   *
   *  `installCommand` is `npm install -g …` for every provider, which silently
   *  assumes npm — i.e. node — is already on the machine. When it isn't, the
   *  missing-CLI banner prints a command that CANNOT succeed, so the user watches
   *  an installer fail instead of an app work. Where the vendor ships a native
   *  installer we run that instead (see buildMissingCliScript's ladder).
   *
   *  Trusted, hardcoded constants — never user/manifest input. MUST contain no
   *  double-quotes: the Windows form is wrapped verbatim in `cmd /d /s /c "…"`. */
  nativeInstallCommand?: { posix: string; win32: string };
  /** Optional docs URL surfaced as a manual-setup hint in the missing-CLI banner. */
  docsUrl?: string;
  /** Extra argv tokens that count as an explicit permission stance (so the auto
   *  flag is not appended). Defaults to the auto flag's own leading token. */
  autoStanceTokens?: string[];
  resumeSubcommand?: string; // CLIs that resume via a subcommand instead of a flag (Codex: `codex resume [OPTIONS] [SESSION_ID]`)
}

export const AGENT_PROVIDER_PRESETS: AgentProviderPreset[] = [
  {
    id: 'claude',
    label: 'Claude Code',
    defaultCommand: 'claude',
    commandGroups: CLAUDE_COMMAND_GROUPS,
    autoModeFlag: '--permission-mode bypassPermissions',
    supportsModel: true,
    modelFlag: '--model',
    autoFlag: '--permission-mode bypassPermissions',
    hiveAware: true,
    canReceiveInbox: true,
    // Longest-context Claude variant — matches the "give Michael a bigger model"
    // advisory and the Recommended tag on the orchestrator picker.
    recommendedOrchestratorModel: 'claude-opus-4-8[1m]',
    resumeFlag: '--resume',
    // Official Claude Code install (npm global). Used by the missing-CLI auto-install.
    installCommand: 'npm install -g @anthropic-ai/claude-code',
    // Anthropic's official native installer — a standalone binary, no node/npm.
    // The only rung of the ladder that works on a machine with no Node at all.
    nativeInstallCommand: {
      posix: 'curl -fsSL https://claude.ai/install.sh | bash',
      win32: 'powershell -c irm https://claude.ai/install.ps1 ^| iex'
    },
    docsUrl: 'https://docs.claude.com/en/docs/claude-code'
  },
  {
    id: 'codex',
    label: 'Codex · GPT',
    defaultCommand: 'codex',
    commandGroups: CODEX_COMMAND_GROUPS,
    // Auto mode: never prompt (-a never) but KEEP codex's OS sandbox, scoped to the
    // workspace (-s workspace-write). The app used to spawn with
    // `--dangerously-bypass-approvals-and-sandbox` for one reason only: a hive
    // worker must write to its agent folder at <harnessHome>/hive/agents/<id>/,
    // a different path tree from cwd, which workspace-write blocked. That is a
    // path-layout problem, not a reason to drop the sandbox: codex's documented
    // `--add-dir <DIR>` makes extra directories writable alongside the workspace,
    // and the hive spawn path (hive.ts, which knows the agent dir) appends it.
    // So: approvals off, sandbox on, hive housekeeping still works.
    autoModeFlag: '-a never -s workspace-write',
    autoFlag: '-a never -s workspace-write',
    // Any of these on a command line means the user already chose a posture
    // (including the old full bypass) — do not stack ours on top.
    autoStanceTokens: ['-a', '--ask-for-approval', '-s', '--sandbox', '--full-auto', '--dangerously-bypass-approvals-and-sandbox'],
    // Suppresses first-run interactive prompts (directory-trust gate, installer).
    nonInteractiveEnv: { CODEX_NON_INTERACTIVE: '1' },
    supportsModel: true,
    modelFlag: '--model',
    // Codex is NOT hiveAware in the Claude-flag sense: it has no
    // `--append-system-prompt`/`--settings`. The hive protocol is injected as
    // Codex's INITIAL prompt, which it takes POSITIONALLY (`codex "<prompt>"`) —
    // hence initialPromptFlag is undefined and hive.ts appends it as a trailing arg.
    hiveAware: false,
    // …but Codex DOES expose a Claude-style hooks system (hooks.json / config.toml
    // [hooks]; PreToolUse/PostToolUse/Stop/…), so it gets full hive parity via the
    // 'codex' bridge: a per-agent CODEX_HOME/hooks.json wired to the cth-hook shim
    // (see hive.installCodexHooks). Stop→drain works natively (Codex's Stop honors
    // {decision:'block',reason} = continue-with-prompt, exactly like Claude).
    hookBridge: 'codex',
    // Inbox drains via the codex-hook bridge's Stop→drain (the renderer's idle
    // inbox-wake nudge remains as a harmless fallback for an idle worker).
    canReceiveInbox: true,
    initialPromptFlag: undefined,
    positionalInitialPrompt: true,
    // Codex's long-context coding model for the orchestrator role. // TODO-verify
    // the exact codex CLI model id (couldn't install the codex CLI to confirm).
    recommendedOrchestratorModel: 'gpt-5-codex',
    // Codex resumes via a SUBCOMMAND, not a flag: `codex resume [OPTIONS]
    // [SESSION_ID]`. A `--resume <id>` flag does not exist, which is why restarts
    // used to silently start a brand-new session instead of continuing.
    resumeFlag: undefined,
    resumeSubcommand: 'resume',
    // Official OpenAI Codex CLI install (npm global). Used by the missing-CLI auto-install.
    installCommand: 'npm install -g @openai/codex',
    docsUrl: 'https://github.com/openai/codex'
  },
  {
    id: 'grok',
    label: 'Grok · xAI',
    defaultCommand: 'grok',
    commandGroups: GROK_COMMAND_GROUPS,
    // Grok documents bypassPermissions as the CLI/config spelling of its
    // always-approve mode. Deny rules and lifecycle gates still take precedence.
    autoModeFlag: '--permission-mode bypassPermissions',
    autoFlag: '--permission-mode bypassPermissions',
    supportsModel: true,
    modelFlag: '--model',
    hiveAware: false,
    // Grok supports Claude-compatible lifecycle events but sends camelCase
    // payloads. The bridge normalizes them before forwarding to HookServer.
    hookBridge: 'grok',
    canReceiveInbox: true,
    // `grok [PROMPT]` accepts the initial hive protocol as a positional prompt.
    positionalInitialPrompt: true,
    // Grok resumes interactively with `grok --resume <session-id-or-title>`.
    resumeFlag: '--resume'
  },
  {
    id: 'kimi',
    label: 'Kimi Code',
    defaultCommand: 'kimi',
    commandGroups: [],
    // Kimi --auto handles every approval and does not stop to ask questions,
    // matching Munder Difflin's autonomous Claude/Codex default.
    autoModeFlag: '--auto',
    autoFlag: '--auto',
    supportsModel: true,
    modelFlag: '--model',
    hiveAware: false,
    // Kimi's interactive TUI has no positional initial-prompt form. It supports
    // lifecycle hooks, but Munder Difflin does not yet install a Kimi hook bridge,
    // so mail must bounce rather than being delivered with no drain path.
    canReceiveInbox: false
  },
  {
    // Google's official Gemini CLI. Unlike Antigravity (`agy`), this is the
    // open-source `@google/gemini-cli` binary and uses Gemini's native settings
    // hooks (BeforeTool/AfterTool/BeforeAgent/AfterAgent/SessionStart).
    id: 'gemini',
    label: 'Gemini CLI',
    defaultCommand: 'gemini',
    commandGroups: [],
    // `--yolo` is deprecated upstream; approval-mode is the current spelling.
    autoModeFlag: '--approval-mode=yolo',
    autoFlag: '--approval-mode=yolo',
    supportsModel: true,
    modelFlag: '--model',
    hiveAware: false,
    bridge: { kind: 'hooks', shim: 'gemini' },
    canReceiveInbox: true,
    // Keep the TUI alive after processing the hive protocol seed.
    initialPromptFlag: '-i',
    recommendedOrchestratorModel: 'pro',
    resumeFlag: '--resume',
    installCommand: 'npm install -g @google/gemini-cli',
    docsUrl: 'https://github.com/google-gemini/gemini-cli'
  },
  {
    id: 'antigravity',
    label: 'Antigravity · Gemini',
    defaultCommand: 'agy',
    commandGroups: [],
    autoModeFlag: '--dangerously-skip-permissions',
    supportsModel: true,
    modelFlag: '--model',
    autoFlag: '--dangerously-skip-permissions',
    hiveAware: false,
    hookBridge: 'agy', // installAgyHooks() → ~/.gemini/.../hooks.json (translating shim)
    canReceiveInbox: true, // via the agy-hook bridge (Stop→drain); verified agy honors hook decisions
    initialPromptFlag: '-i', // agy --prompt-interactive: orient the session, then continue
    recommendedOrchestratorModel: 'Gemini 3.1 Pro (High)', // agy takes the display-name label
    resumeFlag: '--conversation' // agy: resume a previous conversation by ID
  },
  {
    // qwen-code — the Qwen CLI (a gemini-cli fork) driving any OpenAI-compatible
    // endpoint (OPENAI_BASE_URL). It has no hook surface, so it rides a PROXY
    // bridge (bridge.kind==='proxy'), with the OpenAI usage/tool-call shape.
    id: 'qwen',
    label: 'Qwen (local available)',
    defaultCommand: 'qwen',
    commandGroups: [],
    // gemini-cli heritage: --yolo auto-approves all actions. // TODO-verify
    autoModeFlag: '--yolo',
    supportsModel: true,
    modelFlag: '--model',
    autoFlag: '--yolo',
    hiveAware: false,
    // SPIKE/TODO-verify: confirm qwen-code reads OPENAI_BASE_URL for its upstream
    // ('serve' inboxDelivery is reserved for a later qwen-serve HTTP push path).
    bridge: { kind: 'proxy', api: 'openai', baseUrlEnv: 'OPENAI_BASE_URL', inboxDelivery: 'terminal' },
    canReceiveInbox: true,
    // gemini-cli style interactive-orient flag. // TODO-verify
    initialPromptFlag: '-i',
    // Qwen's long-context coder model for the orchestrator. // TODO-verify
    recommendedOrchestratorModel: 'qwen3-coder-plus',
    resumeFlag: undefined
  },
  {
    // OpenCode — the TypeScript AI coding agent (opencode.ai / anomalyco/opencode,
    // ex sst/opencode). NOT the archived Go opencode-ai/opencode (→ Crush). Run as
    // its interactive TUI in a PTY (like codex), oriented by --prompt.
    id: 'opencode',
    label: 'OpenCode',
    defaultCommand: 'opencode',
    commandGroups: [],
    // OpenCode's TUI exposes no skip-permissions FLAG; headless auto-approve is a
    // config concern (permission:allow). To keep auto-mode gated behind the floor
    // `config.autoMode` toggle (Pam guardrail #2), the permission JSON is NOT a
    // static nonInteractiveEnv — spawnAgentCore builds OPENCODE_CONFIG_CONTENT
    // dynamically (permission:allow only when autoMode is on; + a local provider
    // block when a base-URL is set). So no auto flag is spliced onto the command.
    autoModeFlag: '',
    autoFlag: '',
    supportsModel: true,
    modelFlag: '--model', // value form: provider/model, e.g. anthropic/claude-sonnet-4-5
    hiveAware: false, // no --append-system-prompt/--settings; protocol rides in via --prompt
    // NATIVE PLUGIN bridge (god Decision 1): OpenCode has no Claude-shaped Stop hook,
    // but its plugin API DOES expose a real lifecycle event (session.idle). A bundled
    // per-agent plugin drains the inbox on idle and posts HIVE_SOCK payloads — the
    // same Stop→drain semantics as codex's hooks, provider-agnostic, no traffic
    // interception. Modeled as a `hooks` bridge with a new `opencode` shim so it
    // reuses the existing hooks dispatch arm (installOpenCodePlugin, sibling of
    // installCodexHooks). The config-injection proxy is the documented fallback only.
    bridge: { kind: 'hooks', shim: 'opencode' },
    // god-eligible. NOTE: the plugin bridge is architecturally verified (event surface
    // + payload contract) but its live runtime (auto-load + session.idle firing +
    // injection) is UNVERIFIED pending BYOK keys / a local LLM. The renderer idle
    // inbox-wake nudge (useHive.ts) is the guaranteed fallback so a god still drains.
    canReceiveInbox: true,
    initialPromptFlag: '--prompt', // opencode --prompt "<orchestrator/worker brief>"
    // NO recommended model — deliberately. This used to preselect
    // `anthropic/claude-sonnet-4-5` under the comment "OpenCode's own default",
    // which was wrong on both halves: it is not OpenCode's default, and it is a
    // BYOK slug that resolves only for a user who has authenticated Anthropic
    // inside OpenCode. Without that key OpenCode SILENTLY falls back to whatever
    // it can reach (observed live on Windows: "DeepSeek V4 Flash Free" via
    // OpenCode Zen) while every surface in this app went on reporting Claude
    // Sonnet 4.5 — the picker said one model, the agent ran another, and nothing
    // flagged the divergence. Undefined means buildSpawnCommand emits no
    // `--model` at all, so OpenCode uses the model the user actually configured;
    // every BYOK slug in the OpenCode model catalog stays one click away for
    // whoever has the key.
    recommendedOrchestratorModel: undefined,
    // Capturing the TUI session id for resume is unverified; spawn fresh on respawn
    // (protocol re-injected as the initial prompt), matching codex.
    resumeFlag: undefined,
    installCommand: 'npm install -g opencode-ai@latest', // trusted, hardcoded
    // Node-free installers, for the rung that runs when npm is absent AND no Node
    // installer could be resolved (offline / unsupported platform) — until now
    // OpenCode had none, so that rung printed a manual hint and installed nothing.
    // Both are trusted, hardcoded constants and contain no double-quotes (the
    // win32 form is wrapped verbatim in `cmd /d /s /c "…"`).
    //
    // Unlike Claude, OpenCode ships NO standalone Windows one-liner: opencode.ai
    // serves the POSIX install script but has no `install.ps1` (verified 404), and
    // its docs list Chocolatey/Scoop as the Windows-native routes. `-y` because the
    // banner runs the command unattended in the agent terminal. Honest limitation:
    // this rung needs Chocolatey already present; when it isn't, the user sees
    // choco's own "not recognized" error plus the banner's existing "run the
    // command above manually" fallback — no worse off than the manual-only text.
    nativeInstallCommand: {
      posix: 'curl -fsSL https://opencode.ai/install | bash',
      win32: 'choco install opencode -y'
    },
    docsUrl: 'https://opencode.ai/docs'
  },
  {
    // Crush — Charmbracelet's Go TUI coding agent (charmbracelet/crush), successor to
    // the archived Go opencode-ai/opencode. Non-hiveAware. Its hook surface is
    // Claude-shaped but exposes ONLY PreToolUse today (NO Stop/SessionEnd) — so a
    // hooks bridge can't drain on turn-end. Hence a PROXY bridge (qwen tier): a
    // loopback sidecar observes its LLM traffic and SYNTHESIZES the Stop→drain.
    id: 'crush',
    label: 'Crush · Charm',
    defaultCommand: 'crush',
    commandGroups: [],
    // No CODEX_NON_INTERACTIVE analogue. First-run onboarding is suppressed by the
    // harness-written per-agent CRUSH_GLOBAL_CONFIG (provider+model+key pre-seeded),
    // set in env at spawn by installCrushConfig — NOT via this field.
    nonInteractiveEnv: undefined,
    autoModeFlag: '--yolo', // -y: accept all permissions (dangerous; unsandboxed). Gated by config.autoMode.
    autoFlag: '--yolo',
    supportsModel: true,
    modelFlag: '--model', // value format: provider/model-id, e.g. anthropic/claude-..., openai/gpt-4o
    hiveAware: false,
    // PROXY bridge. baseUrlEnv is an INTENTIONALLY INERT sentinel: Crush has NO
    // base-URL env override, so the generic proxy env-rewrite does nothing for it.
    // Real routing is via a per-agent CRUSH_GLOBAL_CONFIG whose provider base_url
    // points at the loopback (installCrushConfig, special-cased in the proxy arm).
    // Do NOT "fix" this to a real env var — it would have no effect.
    bridge: { kind: 'proxy', api: 'openai', baseUrlEnv: 'CRUSH_PROXY_BASE_URL', inboxDelivery: 'terminal' },
    // OpenAI-WIRE default so the out-of-box Crush god routes through the proxy
    // cleanly (the proxy serves one wire-shape; an anthropic/* default would route to
    // the wrong upstream — Dwight verify-crush MF1). Advisory/editable; non-OpenAI-wire
    // Crush-via-proxy is on-device live-verify. // exact long-context id humanQA
    recommendedOrchestratorModel: 'openai/gpt-4o',
    // god-eligible via the proxy bridge (terminal inbox delivery on synthesized idle).
    // Live runtime (proxy parse of Crush traffic + synthesized Stop) is UNVERIFIED
    // pending keys; the renderer idle nudge is the guaranteed drain fallback.
    canReceiveInbox: true,
    // Bare `crush` is an interactive Bubble Tea TUI on a Cobra root command: the
    // first positional is parsed as a SUBCOMMAND, so a positional seed dies with
    // `unknown command "You are…"` (ondev-b live repro / spec-crush MF3). Crush has
    // NO --prompt flag either. So neither flag nor positional works → deliver the
    // protocol by TYPING it into the TUI after boot (renderer nudge path).
    initialPromptFlag: undefined,
    seedDelivery: 'type-into-tui',
    resumeFlag: '--session', // Crush supports resume by id (also --continue for most-recent)
    installCommand: 'npm install -g @charmland/crush', // trusted, hardcoded (brew/go/winget also valid)
    docsUrl: 'https://github.com/charmbracelet/crush'
  },
  {
    // Pi (Pi Coding Agent, earendil-works; npm @earendil-works/pi-coding-agent).
    // Terminal-first, headless-driveable, 15-provider BYOK. Non-hiveAware, but has a
    // rich pi.on(event) lifecycle (tool_call→PreToolUse, agent_end→Stop, …). Bridged
    // via a bundled per-agent extension (installPiHooks) that posts HIVE_SOCK payloads
    // and auto-approves tools — a `hooks` bridge with a new `pi` shim.
    id: 'pi',
    label: 'Pi',
    defaultCommand: 'pi',
    commandGroups: [],
    // pi has NO yolo flag. `--approve` is per-run PROJECT trust (accept the cwd so pi
    // doesn't prompt to trust the folder); the actual tool auto-allow lives INSIDE the
    // bridge extension's tool_call handler, which respects the floor auto-state via
    // HIVE_AUTO_APPROVE env (Pam guardrail #5). Gated by config.autoMode like the rest.
    autoModeFlag: '--approve',
    autoFlag: '--approve',
    // Suppress first-run version-check / telemetry chatter in the PTY. // humanQA exact names
    nonInteractiveEnv: { PI_SKIP_VERSION_CHECK: '1', PI_TELEMETRY: '0' },
    supportsModel: true,
    modelFlag: '--model', // value form: provider/model, e.g. anthropic/claude-sonnet-4-5 (thinking via :high)
    hiveAware: false,
    // HOOKS bridge via the new `pi` shim (installPiHooks). NOTE: only the structured
    // `bridge` is set (NOT the legacy hookBridge) — bridgeOf returns preset.bridge
    // first, so a hookBridge:'pi' would be dead weight + force a second union widening.
    bridge: { kind: 'hooks', shim: 'pi' },
    recommendedOrchestratorModel: 'anthropic/claude-sonnet-4-5',
    // god-eligible. Live runtime (whether the extension auto-continues from agent_end,
    // or we lean on the renderer idle nudge) is UNVERIFIED pending keys. Renderer nudge
    // is the guaranteed drain fallback either way.
    canReceiveInbox: true,
    initialPromptFlag: undefined,
    // Pi's documented `pi [options] [messages...]` form accepts the hive protocol
    // as its initial user message while leaving the interactive session alive.
    positionalInitialPrompt: true,
    resumeFlag: '--session',
    // --ignore-scripts: don't run the package's postinstall on the user's machine.
    installCommand: 'npm install -g --ignore-scripts @earendil-works/pi-coding-agent',
    docsUrl: 'https://pi.dev/docs/latest'
  },
  {
    // GitHub Copilot CLI (`copilot`, npm @github/copilot). Driven in print mode:
    // `copilot -p "<prompt>" -s --allow-all-tools --no-ask-user [--model]`, the
    // documented non-interactive shape (single prompt, clean stdout, exits when
    // done). Non-hiveAware: it has no --append-system-prompt/--settings, so the
    // hive identity+protocol rides in as the initial prompt via `-p`.
    id: 'copilot',
    label: 'Copilot',
    defaultCommand: 'copilot',
    commandGroups: [],
    // Non-interactive autonomy: -s prints only the agent's final response (clean
    // stdout), --allow-all-tools never blocks on a permission prompt (env:
    // COPILOT_ALLOW_ALL), --no-ask-user disables the ask_user tool so it never
    // stops to ask. Gated by the floor `config.autoMode` toggle like the rest.
    autoModeFlag: '-s --allow-all-tools --no-ask-user',
    autoFlag: '-s --allow-all-tools --no-ask-user',
    supportsModel: true,
    modelFlag: '--model', // e.g. claude-sonnet-4.5 (default), gpt-5.4, or 'auto'
    hiveAware: false, // no --append-system-prompt/--settings; protocol rides in via -p
    initialPromptFlag: '-p', // copilot -p "<orchestrator/worker brief>" runs it non-interactively
    recommendedOrchestratorModel: 'claude-sonnet-4.5', // Copilot's default; user may pick gpt-5.4
    // Copilot supports session resume by id (`--resume=<id>`); attached only when a
    // prior session id was recorded (no hook bridge captures it yet → best-effort).
    resumeFlag: '--resume',
    // Print mode exits per turn and there is no hook bridge to drain on idle, so a
    // copilot worker can't receive routed inbox mail (it bounces to the god).
    canReceiveInbox: false,
    installCommand: 'npm install -g @github/copilot', // trusted, hardcoded
    docsUrl: 'https://docs.github.com/copilot/concepts/agents/about-copilot-cli'
  },
  {
    // Cursor Agent CLI (`cursor-agent`, https://cursor.com/docs/cli). The official
    // installer puts `cursor-agent` on PATH; `agent` is a shorter alias. Interactive
    // TUI by default (no `-p`), so the session stays alive for hive mail via the
    // renderer idle / work-order path — same class as Crush. Print mode (`-p`) is
    // available for scripts but exits per turn; this preset intentionally does
    // NOT use `-p` so Michael and workers remain god-eligible / inbox-capable.
    // Models (including cheap gpt-5.6-luna-*) bill against Cursor credits via the
    // logged-in CLI — there is no separate "plain OpenAI API" path for Luna.
    id: 'cursor',
    label: 'Cursor',
    defaultCommand: 'cursor-agent',
    commandGroups: [],
    // --force/--yolo: allow tool calls without confirmations. --trust: skip the
    // workspace trust prompt so unattended Mac Mini spawns do not stall. Gated by
    // the floor config.autoMode toggle like every other engine.
    autoModeFlag: '--force --trust',
    autoFlag: '--force --trust',
    supportsModel: true,
    modelFlag: '--model', // e.g. gpt-5.6-luna-high, auto, composer-2.5
    hiveAware: false,
    // No Cursor hook bridge yet — mail delivery uses the terminal work-order /
    // idle-nudge fallback (same honesty as Crush before its proxy is verified).
    canReceiveInbox: true,
    // `cursor-agent` parses early argv as Cobra-style commands (login, models, mcp, …).
    // A long hive protocol string must NOT ride as a positional — type it into
    // the TUI after boot instead (Crush pattern).
    initialPromptFlag: undefined,
    seedDelivery: 'type-into-tui',
    recommendedOrchestratorModel: 'gpt-5.6-luna-high',
    resumeFlag: '--resume',
    // Official install is a curl|bash script (not npm). Prefer the native rung so
    // a node-free machine can still self-heal. Trusted hardcoded constants only.
    nativeInstallCommand: {
      posix: 'curl https://cursor.com/install -fsS | bash',
      win32: 'irm https://cursor.com/install?win32=true | iex'
    },
    docsUrl: 'https://cursor.com/docs/cli/install'
  },
  {
    id: 'custom',
    label: 'Custom',
    defaultCommand: '',
    commandGroups: [],
    autoModeFlag: '',
    supportsModel: false,
    autoFlag: '',
    hiveAware: false,
    canReceiveInbox: false // no inbox-drain path → mail bounces to the god
  }
];

export function isAgentProvider(value: unknown): value is AgentProvider {
  return (
    value === 'claude' ||
    value === 'codex' ||
    value === 'grok' ||
    value === 'kimi' ||
    value === 'gemini' ||
    value === 'antigravity' ||
    value === 'qwen' ||
    value === 'opencode' ||
    value === 'crush' ||
    value === 'pi' ||
    value === 'copilot' ||
    value === 'cursor' ||
    value === 'custom'
  );
}

export function normalizeAgentProvider(value: unknown): AgentProvider | undefined {
  return isAgentProvider(value) ? value : undefined;
}

export function providerPreset(provider: AgentProvider): AgentProviderPreset {
  return AGENT_PROVIDER_PRESETS.find((p) => p.id === provider) ?? AGENT_PROVIDER_PRESETS[0];
}

export function isClaudeProvider(provider: AgentProvider | undefined): boolean {
  return provider === 'claude';
}

/** Whether this provider takes the hive's Claude-only identity injection. */
export function isHiveAwareProvider(provider: AgentProvider | undefined): boolean {
  return providerPreset(provider ?? 'claude').hiveAware;
}

/** Whether the router may deliver inbox mail to this provider (else bounce to
 *  the god). True when lifecycle status supports guarded idle delivery; false
 *  for hookless custom commands. */
export function canReceiveInbox(provider: AgentProvider | undefined): boolean {
  return providerPreset(provider ?? 'claude').canReceiveInbox;
}

/** The bare executable from a command string ('agy --model x' → 'agy'). */
function commandBinary(command: string | undefined): string {
  const first = (command ?? '').trim().split(/\s+/)[0] ?? '';
  // strip a path + extension so 'C:\...\agy.exe' and '/usr/bin/claude' both map
  const leaf = first.split(/[\\/]/).pop() ?? first;
  return leaf.replace(/\.(exe|cmd|bat|ps1)$/i, '').toLowerCase();
}

/** Infer the provider from a command (or honor an explicit override). */
export function inferAgentProvider(command: string | undefined, explicit?: unknown): AgentProvider {
  const normalized = normalizeAgentProvider(explicit);
  if (normalized) return normalized;
  const bin = commandBinary(command);
  if (bin === 'codex') return 'codex';
  if (bin === 'grok') return 'grok';
  if (bin === 'kimi') return 'kimi';
  if (bin === 'gemini') return 'gemini';
  if (bin === 'agy' || bin === 'antigravity') return 'antigravity';
  if (bin === 'qwen') return 'qwen';
  if (bin === 'opencode') return 'opencode';
  if (bin === 'crush') return 'crush';
  if (bin === 'pi') return 'pi';
  if (bin === 'copilot') return 'copilot';
  // Cursor ships as `cursor-agent`; `agent` is a shorter alias (generic name — check last).
  if (bin === 'cursor-agent') return 'cursor';
  if (bin === 'agent') return 'cursor';
  if (bin === 'claude' || !bin) return 'claude';
  return 'custom';
}

/** The structured bridge descriptor for how a non-hiveAware provider receives hive
 *  lifecycle events. Returns the preset's explicit `bridge` when set (proxy tier:
 *  qwen); else derives `{kind:'hooks', shim}` from the legacy `hookBridge`
 *  (agy/codex), so those keep working untouched; else undefined (claude uses its
 *  native `--settings` path, custom has no bridge). The single accessor call sites
 *  switch on (`bridge.kind`). */
export function bridgeOf(provider: AgentProvider | undefined): BridgeDescriptor | undefined {
  const preset = providerPreset(provider ?? 'claude');
  if (preset.bridge) return preset.bridge;
  if (preset.hookBridge) return { kind: 'hooks', shim: preset.hookBridge };
  return undefined;
}

export function defaultCommandForProvider(provider: AgentProvider, fallback = ''): string {
  if (provider === 'custom') return fallback;
  return providerPreset(provider).defaultCommand || fallback;
}

/** Returns the preset's auto-mode CLI flag for the given provider. Empty string = no flag. */
export function autoModeFlagForProvider(provider: AgentProvider): string {
  return providerPreset(provider).autoModeFlag ?? '';
}

/** Idempotently append a provider's auto-mode flag to an args array, honoring the
 *  user's global autoMode toggle. The renderer's Add Agent flow bakes this same
 *  flag into the command STRING before a GUI hire ever reaches the shared spawn
 *  core (buildSpawnCommand → tokenizeCommand), so `args` for a GUI spawn already
 *  contains it by the time it gets here — this is a no-op for that path. A
 *  main-only spawn (an ephemeral worker, a voice hire) never passes through that
 *  renderer step, so without this it got neither the flag nor any equivalent,
 *  leaving it in an ask-first posture no one could ever answer. */
export function argsWithAutoModeFlag(args: string[], autoMode: boolean, provider: AgentProvider): string[] {
  if (!autoMode) return args;
  const flag = autoModeFlagForProvider(provider);
  if (!flag) return args;
  if (hasAutoModeStance(args, provider)) return args;
  return [...args, ...flag.trim().split(/\s+/)];
}

/** True when argv already states a permission posture for this provider: the
 *  auto flag's leading token, or any of the preset's `autoStanceTokens`. Token
 *  match, not substring — copilot's flag starts with `-s`. */
export function hasAutoModeStance(args: string[], provider: AgentProvider): boolean {
  const preset = providerPreset(provider);
  const flag = preset.autoModeFlag ?? '';
  const lead = flag.trim().split(/\s+/)[0];
  const stance = new Set([...(lead ? [lead] : []), ...(preset.autoStanceTokens ?? [])]);
  return args.some((a) => stance.has(a));
}

/** Returns any env vars the provider needs for non-interactive / first-run suppression. */
export function nonInteractiveEnvForProvider(provider: AgentProvider): Record<string, string> {
  return providerPreset(provider).nonInteractiveEnv ?? {};
}

/** Returns the command reference groups for the given provider. */
export function commandGroupsForProvider(provider: AgentProvider): CmdGroup[] {
  return providerPreset(provider).commandGroups ?? [];
}

/** Install metadata for a provider's engine CLI, consumed by the missing-CLI
 *  auto-install path. `command` is the (trusted, hardcoded) installer to run when
 *  present; when undefined the caller shows a manual hint and runs NOTHING. `label`
 *  is the friendly CLI name; `docsUrl` is an optional manual-setup link. */
export interface ProviderInstallInfo {
  command?: string;
  /** A node-free installer for this platform, when the vendor ships one. */
  nativeCommand?: string;
  label: string;
  docsUrl?: string;
}

export function installInfoForProvider(
  provider: AgentProvider,
  platform: string = process.platform
): ProviderInstallInfo {
  const p = providerPreset(provider);
  const native = p.nativeInstallCommand;
  return {
    command: p.installCommand,
    nativeCommand: native ? (platform === 'win32' ? native.win32 : native.posix) : undefined,
    label: p.label,
    docsUrl: p.docsUrl
  };
}