subconscious-cli 6.0.1 → 6.2.0

package/README.md

@@ -4,25 +4,59 @@ Log in to Subconscious, then run coding agents against the Subconscious gateway.
 
 ## Quick start
 
+Install with npm:
+
 ```bash
 npm install -g subconscious-cli
+```
+
+Or install on macOS or Linux without npm:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/subconscious-systems/subconscious/main/scripts/install.sh | bash
+```
+
+Then log in and launch an agent:
+
+```bash
 subc login
-subc marathon
+subc opencode
 subc claude
 ```
 
+The curl installer downloads the `subconscious-cli` tarball from the npm
+registry, checks it against the registry's integrity hash, and installs it in
+`~/.local/share/subconscious-cli` with a `subc` link in `~/.local/bin`. It does
+not need npm, so a registry policy that blocks `npm install -g` does not stop
+it. Node.js 18 or newer must already be installed, because `subc` runs on it.
+If `~/.local/bin` is not on your `PATH`, the installer prints the line to add.
+Run it again to reinstall or update. These variables change its defaults:
+
+| Variable | Default |
+| --- | --- |
+| `SUBC_VERSION` | `latest` (a version such as `6.1.0`, or a dist-tag) |
+| `SUBC_INSTALL_DIR` | `~/.local/share/subconscious-cli` |
+| `SUBC_BIN_DIR` | `~/.local/bin` |
+| `SUBC_REGISTRY` | `https://registry.npmjs.org` |
+
+On Windows, use npm (see [Native Windows support](#native-windows-support)).
+
+subc does not install the coding agents. Install each agent you use from its
+vendor. If an agent is missing, `subc <agent>` prints its install command and
+official install page, then exits with status 127.
+
 Every interactive `subc` command checks npm for a newer CLI release. When an
 update is available, a notice shows the installed and latest versions and lets
 you select **Update now** or **Skip for now** with the arrow keys and Enter.
 Each option describes what it will do, and the active option is highlighted.
-Update runs `npm install -g subconscious-cli@latest`; Skip continues the
-requested command.
+Update runs `npm install -g subconscious-cli@latest`, or the curl installer
+again if that is how subc was installed; Skip continues the requested command.
 Non-interactive commands automatically skip, and registry errors and timeouts
 never block the requested command. Set `SUBC_DISABLE_UPDATE_CHECK=1` to suppress
 the check in offline automation.
 
 Login creates both the saved credential and a ready-to-use `default` profile,
-so Subconscious Code, Claude Code, Codex, OpenCode, and DeepSeek Harness can launch immediately.
+so OpenCode, Claude Code, Codex, and DeepSeek Harness can launch immediately.
 Persistent editor and Pi integrations are installed per agent:
 
 ```bash
@@ -53,8 +87,8 @@ Every command accepts `help` as a subcommand. These only read the selected
 profile; they do not authenticate, install, configure, or launch anything:
 
 ```bash
+subc opencode help
 subc claude help
-subc marathon help
 subc codex help
 subc cursor help
 subc config help
@@ -69,7 +103,6 @@ gateway environment applied for that process. Arguments pass through as usual:
 
 ```bash
 subc claude --continue
-subc marathon -- -p "fix the tests"
 subc codex exec "write a test"
 subc opencode
 subc pi
@@ -105,8 +138,9 @@ Update with `npm.cmd install -g subconscious-cli@latest` or `subc.cmd upgrade --
 
 If PowerShell's execution policy blocks npm-generated `.ps1` entry points, use
 `npm.cmd` and `subc.cmd` or run the same commands in Command Prompt. No policy
-change is required. Pi must already be installed; other terminal agents offer
-their Windows installer when missing in an interactive terminal.
+change is required. subc does not install the agents on Windows either. If an
+agent is missing, subc prints its install command and official install page,
+then exits with status 127.
 
 Native executables and standard npm `.cmd` shims are supported. The launcher
 invokes the underlying executable or Node entry point directly, preserving
@@ -129,19 +163,6 @@ VS Code's secret store and prompts for its key. Its configuration goes under
 `%APPDATA%\Code\User` (or Code - Insiders/VSCodium). Rerun install after moving
 your Node installation, because hooks record the absolute Node executable path.
 
-To install the native x64 `marathon.exe` (stable releases starting with 0.1.4), clear
-any preview version pin from the current PowerShell session:
-
-```powershell
-Remove-Item Env:SC_CODE_VERSION -ErrorAction SilentlyContinue
-subc.cmd marathon install
-subc.cmd marathon
-```
-
-The installer requires the selected release's Windows asset and SHA-256
-checksum; it reports a clear error if unavailable and never downloads a Unix
-binary as a fallback. Windows ARM64 binaries are not currently published.
-
 Run `npm run test:windows` from the repository root for the separate Windows suite. The
 Windows CI job also builds/tests the Go TUI. Existing Unix tests and runbooks
 remain separate and unchanged.
@@ -152,15 +173,132 @@ The packaged integrations live in `bin/runbook`.
 
 | Command | Behavior |
 | --- | --- |
-| `subc marathon` | Launch Subconscious Code with the active gateway, key, model, and DLR transport |
+| `subc opencode` | Launch OpenCode with the runbook provider, client header, and context/output limits |
 | `subc claude` | Launch Claude Code with the runbook environment, context limits, subagent limits, and OTEL usage reporting |
 | `subc codex` | Launch Codex with the runbook provider, temporary model catalog, and surgically merged compaction hooks |
-| `subc opencode` | Launch OpenCode with the runbook provider, client header, and context/output limits |
-| `subc cursor install` | Install/update Cursor conversation and compaction hooks |
+| `subc cursor install` | Install/update Cursor conversation and compaction hooks (Cursor desktop app and IDE only — the Cursor CLI is not supported) |
 | `subc copilot install` | Install/update the VS Code custom endpoint and Copilot hooks |
 | `subc pi` | Refresh the Pi provider from the live catalog, then launch |
 | `subc dsh` | Launch the DeepSeek Harness Web UI with a temporary provider populated from the live catalog |
 
+## Headless runs
+
+`subc <agent> headless PROMPT [args...]` runs one task without a terminal UI and exits with the agent's status. It works for `claude`, `codex`, `opencode`, `pi`, and `dsh`, and uses the same setup as an interactive launch. It never prompts: there is no update check, a missing agent fails with its install command, stdin is not read, and stdout carries only the agent's own output. Remaining arguments go to the agent, for example `subc claude headless "fix the failing test" --output-format stream-json --verbose`. subc reads `-p`/`--profile` and `--model` itself; put agent options with those names after `--`.
+
+The agents keep their own permission defaults, so a run that should edit files usually needs the agent's permission flags in `[args...]`. For example, `codex exec` uses a read-only sandbox and requires a git repository unless given `--skip-git-repo-check`.
+
+Model, endpoint, and key resolve as for any launch, so a logged-in user needs nothing extra. To point a run somewhere else:
+
+| Input | How to set it |
+| --- | --- |
+| Model | `--model`, or `SUBCONSCIOUS_MODEL` |
+| Endpoint | `SUBCONSCIOUS_BASE_URL`. In a headless run every agent uses it, including Claude Code (`CLAUDE_GATEWAY_URL` is ignored). |
+| Key | `SUBCONSCIOUS_API_KEY`, otherwise the `subc login` key |
+
+```bash
+SUBCONSCIOUS_BASE_URL=https://gateway.example SUBCONSCIOUS_API_KEY=... \
+  subc codex headless "fix the failing test" --model subconscious/deepseek-v4.1-flash-marathon
+```
+
+The endpoint must speak the same APIs as the Subconscious gateway: Anthropic Messages for Claude Code, OpenAI Responses for Codex, and OpenAI Chat Completions for the others.
+
+| Agent | Runs |
+| --- | --- |
+| `claude` | `claude -p -- PROMPT` |
+| `codex` | `codex exec -- PROMPT` |
+| `opencode` | `opencode run`, with the prompt on stdin |
+| `pi` | `pi --print`, with the prompt on stdin |
+| `dsh` | `dsh --profile headless`, with the prompt on stdin |
+
+The prompt is always the argument after `headless`, including for `dsh`, which no longer reads a task piped into subc. Where the table says stdin, subc passes the prompt that way so it reaches the agent unchanged even when it starts with `-` or `@`. On Windows only `dsh` supports headless runs.
+
+The exit status is the agent's own. Pi 1.0.1 exits 1 when the model request fails in its default text output, but 0 with `--mode json`, so check its JSON output for errors. Pi also trims whitespace around a prompt it reads from stdin.
+
+A blank prompt, and `-h` or `--help` anywhere in a headless run, are refused so a scripted run never reports success without doing the task.
+
+Stopping subc with SIGTERM or SIGHUP stops the agent too. SIGKILL cannot be forwarded, so a runner that may kill subc should start it in its own process group and kill the group.
+
+## Harness manifest
+
+`subc harness-manifest` prints how this version of subc installs, configures, and launches each agent above, so other tools can copy the setup exactly instead of re-implementing it.
+
+```bash
+subc harness-manifest --json   # full manifest
+subc harness-manifest          # summary table in a terminal, JSON when piped
+```
+
+The manifest is built when the command runs, from the agent files subc ships (`bin/runbook/<id>/agent.json`). Those files are what the launcher itself executes: launch and headless argv, flags, input defaults, env, and Codex `-c` overrides come from them, so the manifest describes what runs on macOS and Linux. Windows builds its own Codex catalog and `-c` list. The command adds `cli_version` from `package.json`.
+
+| Field | Meaning |
+| --- | --- |
+| `schema_version` | Raised when a field is renamed, removed, or changes meaning. New fields do not raise it. |
+| `cli_version` | The installed `subconscious-cli` version. |
+| `tokens` | Placeholders used in values (listed below). |
+| `runbook_env` | What subc passes to every launch: `order` of the layers, `inherited` sources (profile values, then `process.env`), `fixed` values set last, `runbook_scripts` extras, and `per_harness` extras (Claude's model picker and `SUBC_CLAUDE_SETTINGS`). |
+| `harnesses.<id>` | One entry per agent. |
+
+Each `harnesses.<id>` entry has:
+
+| Field | Meaning |
+| --- | --- |
+| `install` | `method`, `package` or `repository`, `version` or `channel`, `minimum_version`, release `targets`, the per-OS `commands`, and `url`, the vendor's official install page. subc shows `commands` and `url` and never runs them. |
+| `prerequisites` | Commands the runbook needs, such as `jq`, with what needs them and whether they are required. `a\|b` means either one. |
+| `binary` | Executable name, or `null` for IDE integrations. |
+| `launch` | `argv` template, `headless_argv` for `subc <agent> headless` (absent when unsupported), `headless_stdin` when the prompt is passed on stdin instead, `headless_platforms` (`darwin`, `linux`, `win32`) where it works, `resume` and `handoff` argv for `subc sessions`, Codex's `config_flag`, and whether a launch also writes persistent files. |
+| `inputs` | Profile or environment variables subc reads for the agent, with `default`, `flag`, `aliases`, and profile metadata. `export: true` inputs are also passed to the agent and listed in `env`. |
+| `env` | Variables the agent receives: `value`, what it is (`description`), and the `override` variables that win when set. |
+| `config` | Files, directories, `-c` overrides (with `condition`), flags, and JSON-in-env. |
+| `capabilities.compaction` | `default`, plus `on`, `off`, and `threshold`, each with the exact knob and whether subc sets it (`set_by_subc`). |
+| `capabilities.mcp` | Whether subc configures MCP, and which transports. |
+| `capabilities.headers` | Headers sent and on which requests. |
+| `capabilities.hooks` | Hook events installed, what each posts, and where. |
+
+A compaction knob has `kind`, `name`, `value`, and `override`. When `kind` is `config-field` or `model-catalog-field`, `config` names the `config` entry (its `path` or `name`) that holds it. `threshold.semantics` says what the number means: `window` is the context size the agent compacts against (Claude Code, OpenCode, Pi, DeepSeek Harness, Copilot); `trigger` is the token count that starts compaction (Codex).
+
+Enumerated values:
+
+| Field | Values |
+| --- | --- |
+| `install.method` | `npm`, `user`, `null` |
+| `compaction.default` | `on`, `unknown` |
+| knob `kind` | `env`, `cli-config`, `config-field`, `model-catalog-field`, `null` |
+| `threshold.semantics` | `window`, `trigger` |
+| `config[].kind` | `file`, `dir`, `cli-flag`, `cli-config`, `env-json` |
+| `config[].lifetime` | `launch` (removed or not written to disk), `persistent`, `legacy` (left by older setups) |
+
+Placeholders:
+
+| Token | Meaning |
+| --- | --- |
+| `{baseUrl}`, `{baseUrlV1}` | Gateway origin, and the origin followed by `/v1` |
+| `{apiKey}`, `{model}` | The agent's API key (its own key input, else `API_KEY`) and the launch model |
+| `${NAME}` | The value of env var `NAME` at launch; left in place only where it has no default |
+| `{catalog}`, `{catalog[N]}` | All live catalog models (newline-separated), or the one at index N (clamped to the last) |
+| `{args}`, `{config}` | Passed-through arguments, and Codex's `-c` overrides |
+| `{prompt}` | The task given to `subc <agent> headless` |
+| `{sessionId}`, `{sessionFile}` | A local session's ID or file, for `launch.resume` |
+| `{tempFile}`, `{tmp}` | A temporary file the runbook writes (its `config` entry says whether it is removed), the system temp directory |
+| `{opencodeConfig}`, `{claudeSettings}` | Documents shown in the matching `config` entries |
+| `{target}` | A release target triple from `install.targets` or `install.windows_targets` |
+| `{binDir}`, `{PATH}`, `<install dirs>` | Parts of the `PATH` subc builds |
+| `<agent key>` | The agent-specific API key input, such as `CODEX_API_KEY` |
+| `<id>`, `models[]` | Any catalog model ID, and every element of a models array |
+| `<runbook>` | The installed `bin/runbook` directory |
+| `<VS Code user dir>` | The VS Code user settings directory |
+
+`verified: false` means subc does not set the value, or cannot prove its effect; a `note` says which. Entries describing files a runbook writes (the Codex catalog, Pi's `models.json`, the DeepSeek overlay, Copilot's provider, hooks) are descriptions of that script; values they take from inputs are filled in from the input defaults.
+
+## Long screenshot sessions
+
+Coding agents resend every screenshot on every turn, so a long computer-use or screenshot session grows until the gateway refuses it. For vision models, subc applies one rule in Pi and OpenCode before a request leaves the machine: keep the newest screenshots, up to 30 and about 25 MiB in total, and put the text `image` where older ones were. It never removes more than one screenshot per turn, because Subconscious Cache reuses around one removed screenshot, not several; a big screenshot can take the total past 25 MiB for a few turns while it catches up, and only past 30 MiB does it drop straight back to 25. The gateway applies the same rule, so it receives exactly what its own window would produce, and Subconscious Cache still reuses the rest of the conversation: each turn only reads the new screenshot.
+
+| Agent | How subc applies it |
+| --- | --- |
+| OpenCode | A plugin loaded from the launch config (`bin/runbook/opencode/subconscious-image-window.ts`) that gives the provider a trimming `fetch`. |
+| Pi | An extension installed with the provider (`bin/runbook/image-window/index.ts`, on `before_provider_request`). |
+
+The rule is in `bin/runbook/image-window/window.js`. `SUBCONSCIOUS_IMAGE_WINDOW_SOFT_MIB` and `SUBCONSCIOUS_IMAGE_WINDOW_HARD_MIB` change the two limits (defaults 25 and 30). Text-only models are left alone, and a request the integrations do not recognize is sent unchanged.
+
 ## Sessions and cross-harness handoff
 
 Run `subc` and choose **Coding sessions**, or list the same local catalog from
@@ -174,7 +312,7 @@ subc sessions resume codex:SESSION_ID --harness opencode
 ```
 
 The catalog discovers recent sessions written locally by Claude Code, Codex,
-OpenCode, Pi, and Subconscious Code. It shows each session's originating
+OpenCode, and Pi. It shows each session's originating
 harness, title, last activity, project directory, and model when the harness
 records one. Selecting the original harness uses its native resume mechanism.
 
@@ -190,26 +328,12 @@ conversation stores do not expose a stable local resume interface. A session
 whose local transcript is missing remains available for native resume but does
 not offer cross-harness destinations.
 
-If Subconscious Code, Claude Code, Codex, OpenCode, or DeepSeek Harness is missing, an interactive terminal offers
-to install it before launching. Pi refreshes its Subconscious provider on every
+subc never installs OpenCode, Claude Code, Codex, DeepSeek Harness, or Pi. If
+one is missing, subc prints its install command and official install page, then
+exits with status 127, in interactive and headless runs alike. Pi refreshes its Subconscious provider on every
 `subc pi` launch while preserving all other providers in `models.json`; its
 executable must already be installed.
 
-`subc marathon install` detects the operating system and architecture, then downloads
-and checksum-verifies the matching precompiled release from
-`subconscious-systems/subconscious-code`. Apple Silicon and Intel macOS plus
-x86_64 and ARM64 Linux and Windows x64 are supported; Cargo is not required.
-
-Starting with CLI 4.1.1, `subc marathon` is the native agent command. On Windows,
-the installer writes `marathon.exe`, avoiding the system `sc.exe` command.
-`subc sc` remains a compatibility alias but never launches Windows service
-control. Older pinned release binaries are also installed as `marathon.exe`.
-Starting with CLI 4.1.2 and native agent 0.1.6, macOS and Linux also install
-and launch `marathon`. Existing `.sc` settings, sessions, and `SC_*` variables
-are preserved on every platform. Shell behavior is unchanged. Older Unix
-release archives are installed under the new name; existing `sc` files are
-left untouched. `subc sc` remains a compatibility alias on every platform.
-
 `subc codex` disables Codex apps and plugin tools for that launch by default so
 requests remain below the gateway's 128-tool limit. Core coding tools remain
 available. Use `subc codex --external-tools` to opt back in when targeting a
@@ -264,7 +388,7 @@ rewritten. Run a one-shot task with `subc dsh headless "PROMPT"`.
 ```
 
 The file is mode `600` and contains the shared gateway URL, API key, model,
-optional per-agent key overrides, and all Subconscious Code/Claude/Codex/OpenCode/Pi/Copilot/
+optional per-agent key overrides, and all Claude/Codex/OpenCode/Pi/Copilot/
 DeepSeek Harness context and output settings used by the packaged runbook scripts.
 
 ```bash

package/bin/agent-data.js

@@ -0,0 +1,278 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const RUNBOOK_DIR = fileURLToPath(
+  new URL('./runbook/', import.meta.url),
+);
+
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
+const PLATFORMS = new Set(['darwin', 'linux', 'win32']);
+const MODES = new Set(['launch', 'setup']);
+const SETUP_ACTIONS = new Set(['install', 'status', 'uninstall']);
+const INPUT_TYPES = new Set([
+  'secret',
+  'integer',
+  'text',
+  'choice',
+  'url',
+  'model',
+]);
+
+function readJson(relative) {
+  const file = new URL(`./runbook/${relative}`, import.meta.url);
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch (error) {
+    throw new Error(`Cannot read bin/runbook/${relative}: ${error.message}`);
+  }
+}
+
+function check(condition, where, message) {
+  if (!condition) throw new Error(`Invalid ${where}: ${message}`);
+}
+
+const isObject = (value) =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const isStringList = (value) =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string');
+
+function validateEntry(entry, where, { needsValue = false } = {}) {
+  check(isObject(entry), where, 'expected an object');
+  check(ENV_NAME.test(entry.name ?? ''), where, `bad name ${entry.name}`);
+  if (needsValue) check('value' in entry, where, `${entry.name} has no value`);
+  if (entry.type !== undefined)
+    check(INPUT_TYPES.has(entry.type), where, `bad type ${entry.type}`);
+  if (entry.override !== undefined)
+    check(isStringList(entry.override), where, `${entry.name} override`);
+  if (entry.aliases !== undefined)
+    check(isStringList(entry.aliases), where, `${entry.name} aliases`);
+  if (entry.flag !== undefined)
+    check(/^--[a-z][a-z-]*$/.test(entry.flag), where, `bad flag ${entry.flag}`);
+  if (entry.strict)
+    check(isStringList(entry.choices), where, `${entry.name} needs choices`);
+}
+
+function validateLaunch(launch, where) {
+  check(isObject(launch), where, 'launch agents need a launch block');
+  for (const key of ['argv', 'headless_argv', 'resume', 'handoff']) {
+    if (launch[key] === undefined) continue;
+    check(
+      isStringList(launch[key]) && launch[key].length > 0,
+      where,
+      `launch.${key} must be a non-empty list of strings`,
+    );
+  }
+  check(launch.argv !== undefined, where, 'launch.argv is required');
+  for (const key of ['mode_word', 'headless_stdin', 'config_flag'])
+    if (launch[key] !== undefined)
+      check(typeof launch[key] === 'string', where, `launch.${key}`);
+  if (launch.headless_argv) {
+    const platforms = launch.headless_platforms;
+    check(
+      isStringList(platforms) && platforms.every((p) => PLATFORMS.has(p)),
+      where,
+      'launch.headless_platforms must list darwin, linux, or win32',
+    );
+  }
+}
+
+function validateInstall(install, where) {
+  check(isObject(install), where, 'install block is required');
+  check(
+    typeof install.url === 'string' && install.url.startsWith('https://'),
+    where,
+    'install.url must be an https:// link to the official install page',
+  );
+  const { commands } = install;
+  if (commands === null) return;
+  check(
+    isObject(commands),
+    where,
+    'install.commands must be an object or null',
+  );
+  for (const [os, command] of Object.entries(commands)) {
+    check(PLATFORMS.has(os), where, `install.commands.${os} is not an OS`);
+    check(
+      typeof command === 'string' && command,
+      where,
+      `install.commands.${os}`,
+    );
+  }
+}
+
+function validateRunbook(runbook, where) {
+  check(isObject(runbook), where, 'runbook block is required');
+  check(MODES.has(runbook.mode), where, `bad runbook.mode ${runbook.mode}`);
+  const actions = runbook.setup_actions ?? [];
+  check(
+    isStringList(actions) && actions.every((a) => SETUP_ACTIONS.has(a)),
+    where,
+    'runbook.setup_actions may only list install, status, uninstall',
+  );
+  check(
+    actions.length === 0 || typeof runbook.setup_script === 'string',
+    where,
+    'setup actions need runbook.setup_script',
+  );
+}
+
+/** Check one agent file; throws with the file and the first problem found. */
+export function validateAgent(agent, id) {
+  const where = `bin/runbook/${id}/agent.json`;
+  check(isObject(agent), where, 'expected an object');
+  check(agent.id === id, where, `id must be ${id}`);
+  for (const key of ['command', 'name', 'description', 'protocol'])
+    check(typeof agent[key] === 'string' && agent[key], where, `${key}`);
+  check(isStringList(agent.aliases), where, 'aliases must be a list');
+  validateInstall(agent.install, where);
+  check(isObject(agent.help), where, 'help block is required');
+  check(Array.isArray(agent.help.options), where, 'help.options');
+  validateRunbook(agent.runbook, where);
+  if (agent.runbook.mode === 'launch') validateLaunch(agent.launch, where);
+  for (const key of ['prerequisites', 'inputs', 'env', 'config'])
+    check(Array.isArray(agent[key]), where, `${key} must be a list`);
+  for (const input of agent.inputs) validateEntry(input, `${where} inputs`);
+  check(
+    !agent.config.some((entry) => entry.kind === 'cli-config') ||
+      typeof agent.launch?.config_flag === 'string',
+    where,
+    'cli-config entries need launch.config_flag',
+  );
+  for (const entry of agent.env)
+    validateEntry(entry, `${where} env`, { needsValue: true });
+  const caps = agent.capabilities;
+  check(isObject(caps) && isObject(caps.compaction), where, 'capabilities');
+  return agent;
+}
+
+function loadShared() {
+  const shared = readJson('shared.json');
+  check(isStringList(shared.agents), 'shared.json', 'agents must be ids');
+  check(isObject(shared.defaults), 'shared.json', 'defaults is required');
+  for (const input of shared.inputs ?? [])
+    validateEntry(input, 'shared.json inputs');
+  return shared;
+}
+
+const shared = loadShared();
+
+export const DEFAULTS = Object.freeze(shared.defaults);
+export const PACKAGED_MODELS = Object.freeze(
+  DEFAULTS.models?.length ? [...DEFAULTS.models] : [DEFAULTS.model],
+);
+export const MODEL_CAPABILITIES = Object.freeze(
+  shared.model_capabilities ?? {},
+);
+export const SHARED_INPUTS = Object.freeze(shared.inputs ?? []);
+
+export const AGENTS = Object.freeze(
+  shared.agents.map((id) => validateAgent(readJson(`${id}/agent.json`), id)),
+);
+
+const SHARED_BY_NAME = new Map(SHARED_INPUTS.map((i) => [i.name, i]));
+
+export function agentById(id) {
+  return AGENTS.find((agent) => agent.id === id) ?? null;
+}
+
+/** An agent's inputs, each merged over the shared input of the same name. */
+export function agentInputs(agent) {
+  return agent.inputs.map((input) => ({
+    ...(SHARED_BY_NAME.get(input.name) || {}),
+    ...input,
+  }));
+}
+
+export function agentBinary(agent) {
+  return agent.launch?.argv?.[0] ?? null;
+}
+
+/** Per-OS install commands with `{package}` filled in, or null. */
+export function installCommands(agent) {
+  const { commands, package: name } = agent.install;
+  if (!commands) return null;
+  return Object.fromEntries(
+    Object.entries(commands).map(([os, command]) => [
+      os,
+      name ? command.replaceAll('{package}', name) : command,
+    ]),
+  );
+}
+
+/**
+ * The install command and official install page to show when the agent's
+ * binary is missing. subc prints these and never runs them. Windows never
+ * borrows the Linux command.
+ */
+export function installAdvice(agent, platform = process.platform) {
+  const commands = installCommands(agent);
+  const command =
+    commands?.[platform] ?? (platform === 'win32' ? null : commands?.linux);
+  return { command: command ?? null, url: agent.install.url };
+}
+
+/** The API key input that overrides API_KEY for this agent, if any. */
+export function agentKeyName(agent) {
+  return (
+    agent.inputs.find(
+      (input) => input.type === 'secret' && input.name !== 'API_KEY',
+    )?.name ?? null
+  );
+}
+
+export function agentCommandName(agent) {
+  return agent.command || agent.id;
+}
+
+export function agentSetupActions(agent) {
+  return agent.runbook?.setup_actions ?? [];
+}
+
+/** Where the agent's own installer puts its binary, if it says. */
+export function agentInstallDirs(agent, environment, home) {
+  const { install_dir: dir, install_dir_env: envName } = agent.install;
+  const configured = envName ? environment[envName]?.trim() : '';
+  if (configured) return [path.resolve(configured)];
+  return dir ? [path.resolve(home, dir.replace(/^~[/\\]/, ''))] : [];
+}
+
+const WHOLE_REF = /^\$\{([A-Z_][A-Z0-9_]*)\}$/;
+const REF = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+
+/**
+ * Replace `${NAME}` references with `lookup(NAME)`, keeping the referenced
+ * value's type when the reference is the whole string. Unknown names stay.
+ */
+export function resolveRefs(value, lookup) {
+  if (typeof value === 'string') {
+    const whole = WHOLE_REF.exec(value);
+    if (whole) {
+      const target = lookup(whole[1]);
+      return target === undefined ? value : resolveRefs(target, lookup);
+    }
+    return value.replace(REF, (match, name) => {
+      const target = lookup(name);
+      return target === undefined ? match : String(resolveRefs(target, lookup));
+    });
+  }
+  if (Array.isArray(value))
+    return value.map((item) => resolveRefs(item, lookup));
+  if (isObject(value))
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        resolveRefs(item, lookup),
+      ]),
+    );
+  return value;
+}
+
+/** Look up an input's default or an env entry's value by name. */
+export function staticLookup(agent) {
+  const values = new Map();
+  for (const entry of agent.env) values.set(entry.name, entry.value);
+  for (const input of agentInputs(agent))
+    if (input.default !== undefined) values.set(input.name, input.default);
+  return (name) => values.get(name);
+}