@kdonev/termscape 0.1.0 → 0.1.2

package/README.md

@@ -8,9 +8,11 @@ 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 — and another machine can attach itself from the join page.
+`--listen loopback` keeps the whole thing to this machine. Other machines run
+the same hub as a daemon and appear on the same canvas.
 
 ## Getting started
 
@@ -23,9 +25,22 @@ 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, and the **+ machine** dialog already
+has a join link in it for the second machine; see
+[Adding another machine](#adding-another-machine). To keep the hub to this
+machine entirely — no join page, nothing off 127.0.0.1:
+
+```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 +50,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,20 +83,18 @@ next window.
 
 ## Adding another machine
 
-Start the hub so the other machine can see it, then let that machine come to
-you:
-
-```bash
-npx @kdonev/termscape --listen lan
-```
+Nothing to turn on: a hub started with no flags at all hands out join links.
+The startup banner prints an `enroll:` URL alongside the usual one, and the
+**+ machine** dialog shows the same URL with a copy button.
 
-(From a clone that is `npm run dev -- --listen lan`, or
-`npm run dev -w @termscape/hub -- --listen lan` if you are calling the
-workspace directly — npm needs the `--` to hand flags to the hub rather than
-reading them itself.)
+That is a deliberate trade and worth knowing about, because `/join` is the one
+page served without your token — it has to be typed by hand on a machine that
+has nothing yet. So on a network you do not trust, anyone who can reach this
+hub can pull the installer and put a machine on your canvas. `--listen
+loopback` is how you say no, and it turns off the network entirely.
 
-The hub prints an `enroll:` URL alongside the usual one. Open it **on the
-machine you want to add** and run the command it shows:
+Open the join URL **on the machine you want to add** and run the command it
+shows:
 
 ```bash
 curl -fsSL http://studio:7777/join.sh | sh    # macOS, Linux
@@ -134,9 +149,12 @@ 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** answers by default, on the same interfaces the canvas does.
+  Anyone who can reach your hub can load that page and attach a machine to your
+  canvas; every *other* route still requires the token. It was opt-in once, and
+  the reason it is not any more is that the add-machine dialog had nothing to
+  show but an instruction to restart the hub with a flag — a feature reachable
+  only that way is a feature nobody uses. `--listen loopback` is the way back.
 - 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
@@ -153,20 +171,72 @@ tunnel. Same protocol, opposite direction.
 |---|---|
 | `whoami` | your address, workspace and working directory |
 | `list_agents` | everyone on the canvas, across every host, and whether they are busy |
+| `list_templates` | the saved ways of starting an agent, and what each one runs |
 | `send_message` | type a message into another agent's terminal, right now |
 | `spawn_agent` | start a helper in your workspace, with an optional first task |
 | `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 |
+
+`list_templates` is what makes `spawn_agent` usable for anything but a bare
+CLI: its `profile` takes a template id, and this is how an agent finds out
+which ids exist. It reports the *names* of the environment variables a template
+sets and never their values, which are credentials more often than not.
+
+`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 +245,116 @@ 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."
+
+# Set for the agents this template starts, on top of what the CLI already gets.
+[template.reviewer.env]
+ANTHROPIC_BASE_URL = "https://proxy.internal"
+```
+
+- 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.
+- **A template can set environment variables**, in the panel as `NAME=value`
+  lines or as a `[template.<name>.env]` table in the file. They are set for the
+  agents that template starts, on top of whatever the CLI would inherit
+  anyway, and they win over what the agent profile sets on the rare name both
+  name. This is where an API key, a base URL or a feature flag that
+  distinguishes two otherwise identical templates belongs — before it, the
+  difference could only live in whichever shell the hub happened to be started
+  from, which is not a per-template answer at all. Like the model, they are
+  recorded on the session, so a resumed agent comes back in the environment it
+  was launched in. An agent proposing a template cannot ask for any: choosing
+  what the next agent's credentials are is not something to review one dialog
+  at a time.
+
+### 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 +391,14 @@ 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 answers by
+  default on every interface the hub bound. `--listen loopback` turns it off,
+  along with the rest of the network.
 - 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
@@ -225,63 +410,10 @@ could be talked into sending an attacker's text to a peer.
 - An agent may only stop agents it spawned.
 - `--dangerously-skip-permissions` is never a default.
 
-## Development
-
-From a clone, rather than the published package:
-
-```bash
-git clone https://github.com/kdonev/termscape.git
-cd termscape
-npm install
-npm run build
-npm run dev           # hub with the built UI
-```
-
-If `npm install` or `npm ci` tries to compile `better-sqlite3` and fails for
-want of a C++ toolchain, install this way instead:
-
-```bash
-npm ci --ignore-scripts && npm rebuild node-pty
-```
-
-Any install that reads `package-lock.json` misses better-sqlite3's
-`gypfile: false` and runs `node-gyp` on a module that already ships working
-prebuilds. Skipping install scripts avoids that; the rebuild puts back the one
-native build that is real, which is a no-op except on Linux. This is what CI
-does. It does not affect anyone installing the published package.
-
-```bash
-npm test              # unit + integration, no LLM required
-npm run typecheck
-npm run dev:web       # vite dev server, expects a hub on :7777
-```
-
-The integration tests spawn real PTYs and drive the real MCP endpoint, so
-`npm test` genuinely exercises message delivery and cross-host routing.
-
-### Known quirks
-
-- On Windows, node-pty prints `AttachConsole failed` to stderr when killing a
-  PTY from a process with no console attached (notably under the test runner).
-  It is noise from a helper process and does not affect behaviour.
-
-### Releasing
-
-The repo is a workspace of three private packages; what gets published is a
-single package assembled by `packages/hub/scripts/pack-npm.mjs` — the hub,
-the built UI it serves, and `@termscape/protocol` bundled inside it.
-
-```bash
-npm run pack:npm      # build everything, then stage and pack the tarball
-```
+## Contributing
 
-Tagging `v<version>` runs `.github/workflows/release.yml`, which refuses a
-tag that disagrees with `packages/hub/package.json`, installs the packed
-tarball on macOS, Windows and Linux and checks each one starts and serves the
-canvas, and only then publishes to npm with provenance. Bump the version in
-`packages/hub/package.json` **and** `HUB_VERSION` in `packages/hub/src/hub.ts`
-together — peer compatibility is gated on the constant, and a test fails if
-the two drift.
+Building from a clone, running the tests and cutting a release:
+see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

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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"}