@kdonev/termscape 0.1.0 → 0.1.1

package/README.md

@@ -8,9 +8,10 @@ hub exposes. Agents can look each other up, send each other messages, spawn
 helpers into their workspace, and check on each other's terminals. A message
 from one agent is delivered by typing it into the other's terminal, immediately.
 
-Local-first: the hub runs on your machine, binds loopback only, and the UI is a
-browser tab. Other machines run the same hub as a daemon and appear on the same
-canvas.
+Local-first: the hub runs on your machine and the UI is a browser tab. It binds
+every interface, so the canvas opens on your phone or a second screen as well —
+with its token; `--listen loopback` keeps it to this machine. Other machines run
+the same hub as a daemon and appear on the same canvas.
 
 ## Getting started
 
@@ -23,9 +24,21 @@ if you would rather it did not; the URL is printed either way. Nothing is
 installed system-wide: state lives in `~/.termscape`, and deleting that
 directory is the uninstall.
 
+The hub is reachable from your network, so the same URL — token and all — opens
+the canvas on a phone or a second screen. Attaching another machine is a
+separate opt-in; see [Adding another machine](#adding-another-machine). To keep
+the hub to this machine entirely:
+
+```bash
+npx @kdonev/termscape --listen loopback
+```
+
 Slide out the **machines** panel: every machine, the workspaces on it, and
 the agents in each. Point a workspace at a folder there, and start an agent
-in it.
+in it. Adding, editing and removing all open a dialog over the canvas, so the
+node you acted on stays where it was and a refusal — a folder that is not
+there, a rename the addresses will not allow — arrives in the dialog next to
+the field, with what you typed still in it.
 
 - **Scroll** to pan, **Ctrl/⌘ + scroll** to zoom, **Ctrl/⌘ + 1** to fit,
   **Ctrl/⌘ + 2** to zoom to one terminal
@@ -35,6 +48,8 @@ in it.
   ordinary pace is left alone
 - Below 60% zoom terminals become preview cards — zoom in to interact
 - Clicking an agent in the panel brings the canvas to it
+- Clicking the canvas closes the panel, as does **Escape** — which closes the
+  panel first and clears the selection only once it is shut
 
 ## Requirements
 
@@ -66,8 +81,11 @@ next window.
 
 ## Adding another machine
 
-Start the hub so the other machine can see it, then let that machine come to
-you:
+The hub is already reachable from your network, but it does not hand out join
+links until asked. `/join` is the one page served without your token — it has
+to be typed by hand on a machine that has nothing yet — so being reachable and
+being enrollable are kept as two separate permissions. Turn the second one on,
+then let the other machine come to you:
 
 ```bash
 npx @kdonev/termscape --listen lan
@@ -134,9 +152,10 @@ have actually changed, and checks that tree really loads before trusting it.
 
 Two things worth knowing:
 
-- `--listen` is opt-in and off by default. With it, your hub is reachable on
-  that network, and anyone who can load the join page can attach a machine to
-  your canvas. Every other route still requires the token.
+- The **join page** is opt-in and off by default; `--listen lan` is what turns
+  it on. With it, anyone who can reach your hub can load that page and attach a
+  machine to your canvas. Every other route still requires the token, and being
+  reachable — which a default install already is — grants none of this.
 - Each download carries a single-use key that expires in 15 minutes. Once a
   machine has joined it keeps a durable token in `~/.termscape/host-token` and
   rejoins by itself after a reboot or a dropped link — its agents keep running
@@ -158,15 +177,61 @@ tunnel. Same protocol, opposite direction.
 | `read_screen` | look at another agent's terminal without interrupting it |
 | `set_status` | label your own window so the human can see what you are doing |
 | `stop_agent` | stop an agent you spawned |
+| `propose_template` | ask the human to save a way of starting an agent, under a name |
+
+`propose_template` is the only one that asks rather than does. A template
+changes how *future* agents are launched, on every machine, with nobody
+necessarily watching — so the canvas shows it to a human, who can edit it
+before accepting or decline it outright. The tool returns as soon as they have
+been shown it rather than blocking until they answer, and the decision is typed
+back into the agent's terminal. Nothing is stored unless someone says yes.
 
 Every agent is also given a brief explaining its address, its peers, and that
 text arriving as `[from <address>] ...` is a colleague rather than the human.
 
 ## Agent profiles
 
-An agent CLI is configuration, not code. Built-ins are `claude` and `shell`
-(a plain terminal, no agent wiring). Override or add profiles in
-`~/.termscape/agents.toml`:
+An agent CLI is configuration, not code. Built-ins are `claude`, `codex`,
+`gemini`, `opencode` and `shell`.
+
+Every one of them except `shell` is wired to the hub's MCP endpoint: each gets an
+address, a brief and the `send_message` tool set. They arrive there by four
+different routes, because no two of these CLIs configure an MCP server the same
+way — and **none of them writes to a file you own**, so there is nothing left
+behind when a session ends or when the hub is killed rather than stopped.
+
+| agent | how it reaches the hub | brief | resume |
+| --- | --- | --- | --- |
+| `claude` | `--mcp-config` on a generated file | `--append-system-prompt-file` | `--resume <uuid>` |
+| `codex` | `-c mcp_servers.…` overrides, one run only | typed in at startup | restarts clean |
+| `gemini` | `GEMINI_CLI_SYSTEM_SETTINGS_PATH` at a generated file | typed in at startup | restarts clean |
+| `opencode` | `OPENCODE_CONFIG_CONTENT`, no file anywhere | typed in at startup | restarts clean |
+
+The last three are typed at rather than handed a brief because none of them can
+*append* to its system prompt — Codex's `base_instructions` and Gemini's
+`GEMINI_SYSTEM_MD` each replace the whole thing, which would cost the agent its
+own tool instructions. None of the three is resumable either: Codex mints a
+session id it will not accept from us, and Gemini accepts one but resumes by
+list index instead. They restart clean, and are briefed again when they do.
+
+Two details worth knowing, because both are easy to get wrong:
+
+- **Codex's bearer token goes in the environment, never `-c`.** Config
+  overrides land in the command line, where any other user on the machine can
+  read them. `bearer_token_env_var` exists precisely for this.
+- **opencode is configured entirely from the environment.** Its config is
+  handed over as a string, merged with your own rather than replacing it, so
+  your models, themes and your own MCP servers survive the session. Note that
+  `opencode mcp add` is *not* how this is done: that command writes to
+  `~/.config/opencode/opencode.json` and ignores `OPENCODE_CONFIG` while doing
+  it. Setting the variable also stops opencode writing its default config file
+  on start, so a session leaves nothing behind at all.
+
+`shell` is the one profile that is not an agent, and it is not one in a way no
+flag can fix: it runs a shell, so text typed at it is executed rather than read.
+It gets no brief, and its profile says so rather than relying on a default.
+
+Override or add profiles in `~/.termscape/agents.toml`:
 
 ```toml
 [my-agent]
@@ -175,8 +240,100 @@ args = ["--mcp-config", "{{mcp_config_path}}"]
 status = "heuristic"          # or "hooks", for exact turn boundaries
 ready_hint = "[$#>%] ?$"      # prompt regex, for the idle indicator
 inject = "bracketed"          # bracketed paste, or "raw"
+brief = "typed"               # "flag" if it can append a system prompt,
+                              # "none" for a terminal that would execute one
+version_args = ["--version"]  # how to ask its version, for the panel
+models_args = ["models"]      # optional: one model per line on stdout
+models = ["opus", "sonnet"]   # the answer when it has no listing command
+model_args = ["--model", "{{model}}"]    # how it spells a model, if it takes one
+effort_args = ["--effort", "{{effort}}"] # and an effort
+efforts = ["low", "high"]                # the levels it documents
 ```
 
+### Templates
+
+The picker offers **templates**, not CLIs. A template is an agent plus a model,
+an effort and an opening instruction — a saved answer to all four, picked once
+instead of typed every time. Every agent gets a bare template under its own
+name, so `claude` and `shell` are still there and nothing that worked stops
+working.
+
+Templates are a root of their own in the panel, next to the machines — they are
+config rather than a place, and one template is used on every machine, so it
+does not live under one. **+ template** makes one, `edit` changes it, `×`
+removes it. The list sits below the machines and starts collapsed: machines are
+what you work in every day, templates are what you set up once and then forget.
+
+They can also be written by hand, and a hand-written one wins:
+
+```toml
+[template.reviewer]
+agent  = "claude"
+model  = "opus"
+effort = "high"
+prompt = "Review the diff on this branch for correctness bugs. Report, do not fix."
+```
+
+- Templates made in the panel are stored in `state.db`, the same place
+  workspaces and hosts already live. `agents.toml` is a second, read-only
+  source: the hub never writes it, so a formatter cannot eat the comments and
+  ordering of a file you edit by hand.
+- When both declare the same name **the file wins**, and the dialog refuses the
+  name rather than storing a row that would never appear. Someone who wrote a
+  template by hand meant it.
+- An agent's own bare template is derived, not stored. Editing one makes a
+  stored template that shadows it; removing that reveals the bare one again
+  rather than leaving a gap.
+- Removing a template takes nothing from the agents it already started. They
+  keep their model, their effort and their ability to resume, because a session
+  records what its template resolved to rather than looking it up again.
+
+Three words, kept apart deliberately: an **agent** is the CLI program, a
+**template** is what you pick from the list, and a **session** is one running
+instance with an address and a window.
+
+- **A template holds values, not arguments.** Claude Code takes `--model` and
+  `--effort`; opencode takes `-m provider/model` and has no effort setting on
+  its TUI at all; Codex takes `-m` but spells effort as a config override,
+  `-c model_reasoning_effort=…`, because it has no `--effort` flag. So the
+  template says *which* model, and the agent declares how to spell it. An agent that declares nothing takes nothing, and a template
+  asking for a model or an effort it cannot spell is a configuration error
+  reported when the file loads — visible in the dialog, not a flag silently
+  dropped at launch.
+- **The first instruction is typed in once the CLI is up**, not passed as an
+  argument, and it does not repeat when a session is resumed. It is how the
+  session started, not what it is.
+- **A resumed session comes back on the model it left with.** What the template
+  resolved to is recorded on the session, because resume rebuilds the command
+  line rather than replaying it — and because a template can be edited
+  afterwards.
+- **Starting an agent on another machine sends values, not a template name.**
+  The two machines do not share config, so the name is resolved here first.
+
+### What is actually installed
+
+Each machine probes its own `PATH` and reports back, so the panel shows, per
+machine, which agents are there, what version each is, and the models it
+offers. That is per machine on purpose: a host has its own `PATH`, and starting
+an agent it does not have used to fail at launch inside a terminal window,
+where the error reads like the hub is broken.
+
+- A declared agent that is **not** installed stays in the list, greyed out,
+  naming the command that was not found — rather than vanishing, which looks
+  like the config was ignored.
+- Models are enumerated where the CLI can be asked (`opencode models` returns
+  a few hundred) and declared in the profile where it cannot. Claude Code has
+  no listing command; its `--help` documents the aliases instead, and it takes
+  a full model name as readily as an alias. Codex is declared too, for a
+  different reason: `codex debug models` does render the real catalog, but it
+  is a debug command answering with half a megabyte of JSON rather than the
+  one-per-line stdout the profile reads, so the profile carries the slugs that
+  catalog marks visible. In every case a full model name outside the list is
+  still accepted — the list is what the dropdown suggests, never a limit.
+- Probing runs after the hub is already serving and never blocks it. The first
+  page load usually shows *checking…*, and fills in a moment later. **check
+  again** in the start-an-agent dialog re-probes every machine.
+
 ## State and restart
 
 SQLite at `~/.termscape/state.db` holds everything needed to redraw the canvas
@@ -213,7 +370,13 @@ Agents can type into each other's terminals and spawn more agents. That is the
 feature, and it is the risk surface: an agent that reads a hostile repository
 could be talked into sending an attacker's text to a peer.
 
-- The hub binds `127.0.0.1` only, never a network interface. Remote hubs too.
+- The hub binds every interface, so the canvas is reachable from your network —
+  but only with its token, which is minted per run and never printed anywhere
+  the network can read. `--listen loopback` narrows it to this machine.
+- A hub running `--headless` — one that joined a canvas, or was deployed over
+  ssh and is reached through its tunnel — stays on `127.0.0.1` regardless.
+- `/join` is the only route served without the token, and it is off unless you
+  passed `--listen lan`.
 - Every agent gets its own bearer token. The sender of a message is taken from
   that token, never from the arguments, so attribution cannot be forged.
 - Messages are length-capped, rate-limited per sender, and always arrive with a

package/dist/agents/detect.d.ts

@@ -0,0 +1,27 @@
+import { EventEmitter } from 'node:events';
+import type { AgentProfileInfo } from '../protocol/index.js';
+import type { ProfileRegistry } from './profiles.js';
+export declare class AgentDetector extends EventEmitter {
+    private readonly profiles;
+    private known;
+    private readonly cache;
+    private running;
+    constructor(profiles: ProfileRegistry);
+    /**
+     * What is known right now, without probing anything.
+     *
+     * Never async, and never empty: a profile that has not been probed yet is
+     * reported with `available: null`, which the panel draws as "checking".
+     * Detection must not be able to hold up a hub starting or a page loading.
+     */
+    snapshot(): AgentProfileInfo[];
+    /**
+     * Probe every profile. Safe to call from anywhere, including on a timer or
+     * from the browser; concurrent calls share the one run in flight rather
+     * than spawning every CLI twice.
+     */
+    refresh(): Promise<AgentProfileInfo[]>;
+    private run;
+    private probe;
+}
+//# sourceMappingURL=detect.d.ts.map

package/dist/agents/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/agents/detect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,eAAe,CAAC;AAkDnE,qBAAa,aAAc,SAAQ,YAAY;IAKjC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,OAAO,CAA4C;gBAE9B,QAAQ,EAAE,eAAe;IAItD;;;;;;OAMG;IACH,QAAQ,IAAI,gBAAgB,EAAE;IAI9B;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAQxB,GAAG;YAWH,KAAK;CA8DpB"}

package/dist/agents/detect.js

@@ -0,0 +1,210 @@
+import { EventEmitter } from 'node:events';
+import { execFile } from 'node:child_process';
+import { extname } from 'node:path';
+import { platform } from 'node:process';
+import { which } from './resolve.js';
+/**
+ * What is actually installed on this machine, and what each one can be
+ * pointed at.
+ *
+ * The picker used to offer whatever agents.toml declared, whether or not the
+ * command existed, and said nothing about models. Two things make that worse
+ * than it sounds. A declared agent that is not installed fails at launch,
+ * inside a terminal window on the canvas, where the error reads like the hub
+ * is broken. And a model has to be typed from memory, which is how you find
+ * out that the CLI spells it differently than you thought.
+ *
+ * This answers both, per machine - and per machine is the point, because a
+ * host has its own PATH and this hub's answer says nothing about it.
+ */
+/**
+ * How long any one probe gets before it is killed.
+ *
+ * Generous on purpose, and measured rather than guessed. `opencode models` was
+ * about 16 seconds on Windows through the .cmd shim npm installs when this was
+ * written; on opencode 1.18.29 it is nearer 38, which is how the old 30-second
+ * bound came to report a CLI with no models at all rather than its 367.
+ *
+ * That is the argument for erring long, not for chasing the number: a tighter
+ * bound does not make anything faster, it just turns a working CLI into one
+ * that reports no version and no models. Nothing waits on detection - it
+ * starts after the hub is already serving and the browser is told when each
+ * answer lands - so the only thing a long timeout costs is a late answer from
+ * a CLI that was never going to reply.
+ */
+const PROBE_TIMEOUT_MS = 90_000;
+/** Nobody scrolls a dropdown past this, and 395 lines is a real answer. */
+const MAX_MODELS = 500;
+export class AgentDetector extends EventEmitter {
+    profiles;
+    known = new Map();
+    cache = new Map();
+    running = null;
+    constructor(profiles) {
+        super();
+        this.profiles = profiles;
+    }
+    /**
+     * What is known right now, without probing anything.
+     *
+     * Never async, and never empty: a profile that has not been probed yet is
+     * reported with `available: null`, which the panel draws as "checking".
+     * Detection must not be able to hold up a hub starting or a page loading.
+     */
+    snapshot() {
+        return this.profiles.list().map((p) => this.known.get(p.id) ?? unprobed(p));
+    }
+    /**
+     * Probe every profile. Safe to call from anywhere, including on a timer or
+     * from the browser; concurrent calls share the one run in flight rather
+     * than spawning every CLI twice.
+     */
+    refresh() {
+        if (this.running)
+            return this.running;
+        this.running = this.run().finally(() => {
+            this.running = null;
+        });
+        return this.running;
+    }
+    async run() {
+        // In parallel: each of these is a process spawn that mostly sits waiting,
+        // and doing them in series makes the first load as slow as their sum.
+        const found = await Promise.all(this.profiles.list().map((p) => this.probe(p)));
+        const next = new Map(found.map((info) => [info.id, info]));
+        const changed = !same(this.known, next);
+        this.known = next;
+        if (changed)
+            this.emit('changed', found);
+        return found;
+    }
+    async probe(profile) {
+        const base = unprobed(profile);
+        const path = which(profile.command);
+        if (!path) {
+            // Stays in the list rather than vanishing: a declared agent that
+            // silently disappeared looks like the config was ignored, and the
+            // command that was not found is the thing worth showing.
+            return {
+                ...base,
+                available: false,
+                detail: `not found on PATH: ${profile.command}`,
+            };
+        }
+        const version = profile.versionArgs
+            ? await run(path, profile.versionArgs, profile.probeEnv).catch(() => null)
+            : null;
+        const key = `${path}|${version ?? ''}`;
+        const cached = this.cache.get(profile.id);
+        if (cached?.key === key) {
+            return {
+                ...base,
+                available: true,
+                commandPath: path,
+                version,
+                models: cached.models,
+                modelSource: cached.source,
+            };
+        }
+        const listed = profile.modelsArgs
+            ? await run(path, profile.modelsArgs, profile.probeEnv).catch(() => null)
+            : null;
+        let models = [];
+        let source = 'none';
+        if (listed !== null) {
+            models = listed
+                .split(/\r?\n/)
+                .map((l) => l.trim())
+                .filter((l) => l.length > 0)
+                .slice(0, MAX_MODELS);
+            source = 'listed';
+        }
+        if (models.length === 0 && profile.models?.length) {
+            // Either the CLI has no listing command, or its command failed. The
+            // declared list is the answer in both cases.
+            models = profile.models;
+            source = 'declared';
+        }
+        this.cache.set(profile.id, { key, models, source });
+        return {
+            ...base,
+            available: true,
+            commandPath: path,
+            version,
+            models,
+            modelSource: source,
+        };
+    }
+}
+/**
+ * A profile before anything has been asked of it.
+ *
+ * `shell` is the exception that is born answered: it is whatever COMSPEC or
+ * SHELL points at, it is always there, and there is nothing to probe.
+ */
+function unprobed(p) {
+    const detectable = p.versionArgs !== undefined || p.modelsArgs !== undefined;
+    return {
+        id: p.id,
+        description: p.description,
+        mcp: p.mcp,
+        resumable: !!p.resumeArgs,
+        command: p.command,
+        commandPath: null,
+        available: detectable ? null : true,
+        version: null,
+        detail: null,
+        models: p.models ?? [],
+        modelSource: p.models?.length ? 'declared' : 'none',
+        takesModel: p.modelArgs !== undefined,
+        takesEffort: p.effortArgs !== undefined,
+        efforts: p.efforts ?? [],
+    };
+}
+/**
+ * Run one probe and return its stdout.
+ *
+ * Timed and killed rather than awaited indefinitely: the whole promise of
+ * this file is that a CLI which hangs on `--version` costs a slow dropdown
+ * and not a hub that will not boot. Windows shims (.cmd/.bat) are not
+ * executable images, so they go through cmd.exe exactly as spawning an agent
+ * does - `shell: true` would be the short version and would also hand the
+ * command line to a shell that reinterprets it.
+ */
+function run(path, args, env) {
+    const ext = extname(path).toLowerCase();
+    const viaCmd = platform === 'win32' && (ext === '.cmd' || ext === '.bat');
+    const file = viaCmd ? (process.env.COMSPEC ?? 'cmd.exe') : path;
+    const argv = viaCmd ? ['/c', path, ...args] : args;
+    return new Promise((resolve, reject) => {
+        execFile(file, argv, {
+            timeout: PROBE_TIMEOUT_MS,
+            windowsHide: true,
+            maxBuffer: 4 * 1024 * 1024,
+            // Inherited and then overlaid: a probe still needs PATH and HOME to
+            // find and run anything at all.
+            env: env ? { ...process.env, ...env } : process.env,
+        }, (err, stdout) => {
+            // Some CLIs print their version and exit non-zero, or write it to
+            // stderr and nothing to stdout. Stdout with content wins over the
+            // exit code; nothing on stdout is a failure whatever the code said.
+            const out = stdout.trim();
+            if (out)
+                resolve(out);
+            else
+                reject(err ?? new Error('no output'));
+        });
+    });
+}
+/** Whether two detection results are the same, so nothing is broadcast. */
+function same(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [id, x] of a) {
+        const y = b.get(id);
+        if (!y || JSON.stringify(x) !== JSON.stringify(y))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=detect.js.map

package/dist/agents/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/agents/detect.ts"],"names":[],"mappings":"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"}

package/dist/agents/profiles.d.ts

@@ -16,19 +16,129 @@ export interface AgentProfile {
     /** Regex matched against the last non-empty line when status = heuristic. */
     readyHint?: string;
     inject: InjectMode;
+    /**
+     * How the brief reaches the agent.
+     *
+     * `flag` - the profile's own args point at `{{brief_path}}`, the way Claude
+     * Code's `--append-system-prompt-file` does. The brief is part of the
+     * system prompt and the agent never sees it as a turn.
+     *
+     * `typed` - the CLI has no way to *append* to its system prompt, so the
+     * brief is typed into the terminal once the CLI is up, ahead of any opening
+     * instruction. Both of the other wired CLIs are in this position, and for
+     * the same reason: Codex's `base_instructions` and Gemini's
+     * `GEMINI_SYSTEM_MD` each *replace* the whole system prompt rather than add
+     * to it, so using either would cost the agent its own tool instructions -
+     * a far worse trade than a first turn that arrives as text.
+     *
+     * `none` - nothing is sent. `shell` is the reason this value exists and it
+     * is not a value any agent should want: a shell *executes* what is typed at
+     * it, so a brief there is not context, it is a series of commands that fail
+     * loudly.
+     *
+     * Absent means `flag` for a wired agent - what every profile written before
+     * this did - and `none` for an unwired one, because `mcp: false` has always
+     * meant "a plain terminal" and a profile that declared one should not start
+     * having text typed into it. An unwired agent that *is* an agent says
+     * `brief = "typed"` and gets the shorter brief: no tool list, because it has
+     * no tools, but it is still told its address and still told that a
+     * `[from ...]` line is a colleague rather than the human.
+     */
+    brief?: 'flag' | 'typed' | 'none';
     /**
      * Argument template used to bring a session back with its prior
      * conversation. `{{uuid}}` is replaced with agent_session_uuid. When absent,
      * the profile is not resumable and restarts clean.
      */
     resumeArgs?: string[];
+    /**
+     * Environment for the *detection* probes only, not for a session.
+     *
+     * Detection runs these CLIs on a machine whose owner may never have run them
+     * by hand, so a probe that leaves something behind is the hub writing to
+     * somebody's home directory uninvited. `opencode models` does exactly that -
+     * it creates ~/.config/opencode/opencode.jsonc - and this is how it is told
+     * not to.
+     */
+    probeEnv?: Record<string, string>;
+    /**
+     * How to ask this CLI its version. Its stdout is shown to the user and is
+     * also the cache key for the model list, so a CLI that updates underneath
+     * us re-lists rather than serving last week's answer.
+     */
+    versionArgs?: string[];
+    /**
+     * How to ask this CLI what models it can be pointed at: one
+     * `provider/model` (or bare name) per line on stdout. Absent when the CLI
+     * has no such command, which is the common case.
+     */
+    modelsArgs?: string[];
+    /**
+     * The answer for a CLI that cannot be asked. Claude Code is the example:
+     * it has no listing command, and its --help documents the aliases instead.
+     * Used only when `modelsArgs` is absent or its command fails.
+     */
+    models?: string[];
+    /**
+     * How this agent spells a model on the command line. `{{model}}` carries
+     * the value a template chose.
+     *
+     * A template holds *values*, not argv, because no two of these agents agree:
+     * Claude Code takes `--model`, opencode takes `-m provider/model`. So the
+     * template says which model and the agent says how to write it down.
+     *
+     * Absent means the agent takes no model here, and a template that names one
+     * for it is a configuration error reported at load rather than a flag
+     * silently dropped at launch. The whole fragment disappears when a template
+     * leaves the value unset - it does not expand to an empty string.
+     */
+    modelArgs?: string[];
+    /** The same for effort, with `{{effort}}`. */
+    effortArgs?: string[];
+    /** The effort levels this agent documents, for the dialog to offer. */
+    efforts?: string[];
 }
 /**
  * Built-in profiles. All Claude Code flags here are verified against the CLI:
  * --mcp-config, --strict-mcp-config, --session-id, --settings,
  * --append-system-prompt-file, --resume.
+ *
+ * Codex and Gemini are wired too, and every flag and key below was verified
+ * against the CLI actually installed - codex-cli 0.153.4 and gemini 0.58.0 -
+ * rather than written from memory. Both reach the hub the same way Claude
+ * Code does, over one streamable-HTTP MCP server carrying a bearer token, and
+ * neither needs a byte written to config the user owns:
+ *
+ * - **Codex** takes `-c <dotted.key>=<toml>` on any invocation, so the server
+ *   is declared in argv for the one run. The token is *not* in argv - it goes
+ *   in the environment, and `bearer_token_env_var` names the variable to read
+ *   it from, which keeps it out of every process listing on the machine.
+ * - **Gemini** has no per-run config flag, but
+ *   `GEMINI_CLI_SYSTEM_SETTINGS_PATH` repoints its system settings layer at a
+ *   file of our choosing, which the hub generates per session.
+ *
+ * - **opencode** turned out to be the least invasive of the three and was
+ *   assumed to be the hardest. It reads its entire config from
+ *   `OPENCODE_CONFIG_CONTENT`, so nothing is written anywhere at all, and what
+ *   it is given is merged with the user's own config rather than replacing it.
+ *   The assumption that it had no per-run route came from reading
+ *   `opencode mcp add` - which does write to the user's file, and ignores
+ *   `OPENCODE_CONFIG` when it does - and mistaking that command for the only
+ *   way in.
+ *
+ * `shell` is the only profile left that is not an agent, and it is not one in
+ * a way no flag can fix: it runs a shell, so text typed at it is executed
+ * rather than read.
  */
 export declare const BUILTIN_PROFILES: Record<string, AgentProfile>;
+/**
+ * How this profile's brief travels, with the defaults applied.
+ *
+ * One place, because three callers need the same answer and the interesting
+ * part is the default rather than the field: absent means `flag` for a wired
+ * agent and `none` for an unwired one.
+ */
+export declare function briefMode(p: AgentProfile): 'flag' | 'typed' | 'none';
 export declare class ProfileRegistry {
     private profiles;
     constructor(profiles?: Record<string, AgentProfile>);

package/dist/agents/profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/agents/profiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,GAAG,EAAE,OAAO,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAOD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA8CzD,CAAC;AAEF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAA+B;gBAEnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAInD,oEAAoE;IACpE,MAAM,CAAC,IAAI,IAAI,eAAe;IA8B9B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAIpC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY;IAMjC,IAAI,IAAI,YAAY,EAAE;IAItB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAIjC;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI5E;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAElF"}
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/agents/profiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,GAAG,EAAE,OAAO,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAItB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAIlB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAoNzD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAEpE;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAA+B;gBAEnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAInD,oEAAoE;IACpE,MAAM,CAAC,IAAI,IAAI,eAAe;IAyC9B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAIpC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY;IAMjC,IAAI,IAAI,YAAY,EAAE;IAItB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAIjC;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI5E;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAElF"}