@platless/axom-cli 0.1.0

package/dist/workstation/acp/timedCommand.js

@@ -0,0 +1,47 @@
+/**
+ * One place that spawns a bounded, non-blocking subprocess and reports a timeout as its own
+ * distinguishable outcome — shared by `uvxInstall.ts`'s `defaultRunUv` (probes and installs `uv`)
+ * and `binaryInstall.ts`'s default `ExecuteCommand` (extracts a downloaded archive with `tar`/
+ * `unzip`). Both used to go through `execFileSync`, which blocks Node's single event loop for the
+ * whole run — on this daemon that loop also carries the tunnel to the server, its heartbeats, and
+ * every live agent session, so a stalled `uv tool install` or a hung `tar` froze all of it, for as
+ * long as the stall lasted, since neither call carried a timeout at all.
+ *
+ * `execFile` (the callback form, not `execFileSync`) never blocks the loop, and its own `timeout`
+ * option kills the child once the budget is spent. The one thing that option does not do on its own
+ * is say so clearly: a killed child's callback error looks, at a glance, like any other non-zero
+ * exit. This wraps that distinction up front — `timedOut: true` plus a message naming the command,
+ * its args, and the budget — so neither caller has to re-derive it, and neither can mistake a
+ * timeout for a silent success or an indistinguishable ordinary failure.
+ */
+import { execFile } from 'node:child_process';
+/**
+ * Runs `command args`, bounded by `timeoutMs`. A run that does not finish in time is killed (Node's
+ * default `SIGTERM`) and reported as `{ ok: false, timedOut: true, message }`, the message naming
+ * what timed out and after how long — never thrown, so every caller keeps the "never blocks, never
+ * throws" contract `defaultRunUv`/`runCommand` document for themselves.
+ *
+ * `code` carries through the child's `ENOENT` (command not found) so callers that branch on it —
+ * `binaryInstall.ts`'s zip-extraction fallback — keep working unchanged; it is `undefined` on a
+ * timeout, which is never `ENOENT`.
+ */
+export function runTimedCommand(command, args, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile(command, args, { encoding: 'utf8', timeout: timeoutMs, windowsHide: true }, (error, stdout) => {
+            if (!error) {
+                resolve({ ok: true, stdout: stdout.toString() });
+                return;
+            }
+            const err = error;
+            if (err.killed) {
+                resolve({
+                    ok: false,
+                    timedOut: true,
+                    message: `${command} ${args.join(' ')} did not finish within ${timeoutMs}ms.`,
+                });
+                return;
+            }
+            resolve({ ok: false, timedOut: false, message: err.message, code: err.code });
+        });
+    });
+}

package/dist/workstation/acp/uvxInstall.js

@@ -0,0 +1,248 @@
+/**
+ * The `uv tool` counterpart to `installProbe.ts`: uvx-distributed adapters (`fast-agent`,
+ * `minion-code` — see the ACP registry's `distribution.uvx`) are, from this task on, installed by
+ * us with `uv tool install` rather than launched with `uvx <pkg>`. That switch is the whole point
+ * of this module.
+ *
+ * ## Why the launch path had to change, not just the probe
+ *
+ * `uvx <pkg>` resolves through uv's own ephemeral-environment cache — directories named by a hash
+ * of the resolved environment, a layout this codebase has never verified and has no reason to
+ * trust. "Is it installed, and which version" is unanswerable against that cache the same way it
+ * would be unanswerable against npm's `_npx/<hash>` before `installProbe.ts` existed. `uv tool
+ * install` instead puts the tool under `uv tool dir` — one stable path per machine that `uv tool
+ * list` describes completely — which is the same guarantee `readNpxCache`/`findOnPath` give for the
+ * npx and binary paths. Everything here exists to read that directory the way `installProbe.ts`
+ * reads npm's.
+ *
+ * ## Measured evidence (2026-09-05, uv 0.11.5, macOS aarch64) — this is what the parsing below is
+ * built on, not a guess
+ *
+ * The probe package was `cowsay` — small and uncontroversial — installed and then removed once the
+ * layout was recorded, specifically so this module would not be built against one real registry
+ * package's executable name (see below for why that name is never hardcoded).
+ *
+ * ```
+ * $ uv tool dir
+ * /Users/…/.local/share/uv/tools
+ *
+ * $ uv tool install cowsay
+ *  + cowsay==6.1
+ * Installed 1 executable: cowsay
+ *
+ * $ uv tool list
+ * cowsay v6.1
+ * - cowsay
+ *
+ * $ uv tool list --show-paths
+ * cowsay v6.1 (/Users/…/.local/share/uv/tools/cowsay)
+ * - cowsay (/Users/…/.local/bin/cowsay)
+ * ```
+ *
+ * A second probe, `httpie` — chosen because its declared executables (`http`, `httpie`, `https`)
+ * outnumber and don't all match the package name — settled two questions the `cowsay` probe alone
+ * left open:
+ *
+ * 1. A tool can expose more than one executable. `uv tool list` lists them as indented `- <name>`
+ *    lines under the tool's `<name> vX.Y.Z` header line, one header can be followed by several.
+ * 2. The tool's own venv `bin/` directory (`<uv tool dir>/<pkg>/bin/`) is **not** the set of
+ *    entrypoints — it also holds that venv's private `python`/`pip` and every console script any
+ *    *dependency* installed (`pygmentize`, `markdown-it`, `normalizer`, …, none of them httpie's).
+ *    `readdir`-ing that directory and treating every executable file as an entrypoint would measure
+ *    what uv happened to put in the venv, not what the tool declared. The actual entrypoint set is
+ *    exactly what `uv tool list` reports, confirmed against `~/.local/bin` (`uv tool dir --bin`):
+ *    `ls -la` there showed only the three declared symlinks (`http`, `httpie`, `https`), none of the
+ *    venv's other scripts.
+ *
+ * Consequently every function below runs `uv tool list --show-paths`, never a directory read: that
+ * one flag makes uv report each executable's resolved absolute path directly, which sidesteps
+ * reconstructing `<tool dir>/<pkg>/bin/<exe>` (`Scripts\<exe>.exe` on Windows) by hand.
+ *
+ * ## Picking one entrypoint when a tool declares several
+ *
+ * Neither `fast-agent-acp` nor `minion-code`'s actual entrypoint name has been measured — the brief
+ * for this task explicitly rules out installing them just to read that off, since that would bake
+ * one package's executable name into the source the same way a hardcoded probe would. So this picks
+ * structurally, from what `uv tool list` reports for the requested package, in order: the only
+ * executable when there is exactly one; otherwise the one whose name matches the package name
+ * (true for `httpie` among its three); otherwise **neither** — this refuses rather than guesses.
+ * uv's listing order is stable on one machine but not a documented contract, this path has never
+ * been exercised against either real registry package, and a wrong guess here launches the wrong
+ * binary silently, which is worse than a refusal a caller can act on. See {@link uvToolEntrypoint}
+ * for the resulting three-outcome contract.
+ */
+import { runTimedCommand } from './timedCommand.js';
+/**
+ * Wall-clock budget for one `uv tool list` / `uv tool dir` read — a local, no-network directory
+ * probe, not a download. "A few seconds is generous" for that: 10s leaves ample headroom above
+ * every measured run (low tens of milliseconds — see this module's own doc comment) while still
+ * keeping a genuinely stuck `uv` (a broken shim, a filesystem wedged mid-fsck) from parking
+ * `AcpAgents.roster` or a launch indefinitely.
+ */
+export const UV_PROBE_TIMEOUT_MS = 10_000;
+/**
+ * Wall-clock budget for one `uv tool install <spec>` — a real package download, not a probe.
+ *
+ * Matches `installProbe.ts`'s `ADAPTER_INSTALL_TIMEOUT_MS` and `binaryInstall.ts`'s
+ * `ARCHIVE_DOWNLOAD_TIMEOUT_MS` deliberately, for the same reason `binaryInstall.ts`'s own constant
+ * gives for matching the first of those: this is the third of three siblings (npx, binary archive,
+ * uvx tool) fetching a whole ACP adapter over the network, and there is no reason the one added
+ * last should time out sooner than the other two just because it arrived later.
+ */
+export const UV_TOOL_INSTALL_TIMEOUT_MS = 300_000;
+/**
+ * Default `RunUv`: runs `uv <args>` through {@link runTimedCommand} (never `execFileSync`, see this
+ * type's own doc comment), with every failure — a non-zero exit, `uv` not being on `PATH` at all
+ * (`ENOENT`), or the run exceeding `timeoutMs` — folded into `{ ok: false }` rather than thrown. A
+ * machine without `uv` installed is a normal machine, not an error condition this module gets to
+ * raise; a `uv` that hangs past its budget is reported with a message naming the command and the
+ * budget, not silently swallowed.
+ */
+async function defaultRunUv(args, timeoutMs) {
+    const result = await runTimedCommand('uv', args, timeoutMs);
+    if (result.ok)
+        return { ok: true, stdout: result.stdout };
+    return { ok: false, stdout: '', error: result.message };
+}
+/**
+ * Parses `uv tool list --show-paths` output (also tolerates the plain `uv tool list` form, with no
+ * `(<path>)` suffixes, which is what makes the fixtures above double as fixtures for both). A tool
+ * header line reads `<name> vX.Y.Z` or `<name> vX.Y.Z (<tool dir>)`; each executable line under it
+ * reads `- <name>` or `- <name> (<absolute path>)`. `No tools installed` (uv's output for an empty
+ * roster) matches neither pattern and yields no entries, which is the correct answer.
+ */
+function parseToolList(stdout) {
+    const entries = [];
+    let current;
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const exeMatch = /^-\s+(\S+)(?:\s+\((.+)\))?$/.exec(line);
+        if (exeMatch) {
+            current?.executables.push({ name: exeMatch[1], path: exeMatch[2] ?? '' });
+            continue;
+        }
+        const headerMatch = /^(\S+)\s+v(\S+)(?:\s+\(.+\))?$/.exec(line);
+        if (headerMatch) {
+            current = { name: headerMatch[1], version: headerMatch[2], executables: [] };
+            entries.push(current);
+        }
+    }
+    return entries;
+}
+/**
+ * One `uv tool list --show-paths` snapshot, parsed. This is the single place that actually spawns
+ * `uv` for the "what's installed" question — {@link findTool} delegates to it rather than shelling
+ * out itself, and `AcpAgents.roster` calls it directly, exactly **once per roster build**, so it can
+ * look every uvx-distributed agent up in one snapshot instead of spawning `uv` again per agent (see
+ * that call site's own doc comment for why a per-agent spawn was a defect worth hoisting out of).
+ * `uv` missing, failing, or timing out degrades to `[]` — "nothing installed" — the same as every
+ * other reader of {@link RunUv} in this module; it never throws. `timeoutMs` defaults to
+ * {@link UV_PROBE_TIMEOUT_MS} — this is the probe half of `RunUv`'s two budgets, never the
+ * `uv tool install` one.
+ */
+export async function listUvTools(run = defaultRunUv, timeoutMs = UV_PROBE_TIMEOUT_MS) {
+    const result = await run(['tool', 'list', '--show-paths'], timeoutMs);
+    if (!result.ok)
+        return [];
+    return parseToolList(result.stdout);
+}
+function findToolIn(tools, pkg) {
+    return tools.find((entry) => entry.name === pkg);
+}
+async function findTool(pkg, run) {
+    return findToolIn(await listUvTools(run), pkg);
+}
+/**
+ * The version of `pkg` that `uv tool list` reports as installed, or `undefined` when it is not
+ * installed, or when `uv` itself is missing, fails, or times out.
+ */
+export async function uvToolVersion(pkg, run = defaultRunUv) {
+    return (await findTool(pkg, run))?.version;
+}
+/**
+ * Picks `pkg`'s launchable executable — the one `resolveLaunch`'s uvx branch runs instead of
+ * shelling out to `uvx <pkg>` — out of an already-parsed `uv tool list --show-paths` snapshot
+ * ({@link listUvTools}).
+ *
+ * Three shapes, in order:
+ * 1. Exactly one executable declared → that one, whatever it is named. One candidate is not a
+ *    guess.
+ * 2. Several declared, and one matches the package's own name (true for `httpie` among its three,
+ *    measured) → that one.
+ * 3. Several declared, none matching → **refuse** (`ambiguous`, carrying every candidate name).
+ *    uv's listing order is stable on one machine but is not a documented contract (see the module
+ *    docstring), and this path has never been exercised against a real uvx-distributed agent —
+ *    installing `fast-agent-acp`/`minion-code` to find out was ruled out of scope for this task.
+ *    Guessing the first one and launching it would trade a diagnosable refusal for an ACP handshake
+ *    that hangs or fails for a reason nobody can trace back to this choice, so this reports the
+ *    ambiguity instead of resolving it.
+ *
+ * `not-installed` also covers: no such tool in `uv tool list`, `uv` itself missing or failing, a
+ * matched executable whose recorded path is empty (the plain, no-`--show-paths` form this also
+ * parses carries no paths at all) — none of these are launchable either, and none of them are
+ * ambiguous the way case 3 is.
+ *
+ * Takes the parsed listing rather than a runner on purpose: a caller that already read
+ * `uv tool list` once (`AcpAgents.roster`, so 39 registry entries share one spawn) hands that
+ * result straight in here instead of this function spawning `uv` again per package. {@link
+ * uvToolEntrypoint} is the thin wrapper for the one real caller (the actual launch path) that has
+ * no such snapshot yet and needs to read it fresh.
+ */
+export function uvToolEntrypointFrom(pkg, tools) {
+    const entry = findToolIn(tools, pkg);
+    if (!entry || entry.executables.length === 0)
+        return { ok: false, reason: 'not-installed' };
+    if (entry.executables.length === 1) {
+        const [only] = entry.executables;
+        return only.path ? { ok: true, path: only.path } : { ok: false, reason: 'not-installed' };
+    }
+    const match = entry.executables.find((exe) => exe.name === pkg);
+    if (match) {
+        return match.path ? { ok: true, path: match.path } : { ok: false, reason: 'not-installed' };
+    }
+    return { ok: false, reason: 'ambiguous', candidates: entry.executables.map((exe) => exe.name) };
+}
+/**
+ * `uvToolEntrypointFrom`, but reading `uv tool list --show-paths` itself first — the real launch
+ * path's entry point (`resolveLaunch`'s uvx branch with no pre-fetched listing), where doing its
+ * own `uv` lookup at connect time is correct and expected, unlike the roster path (see {@link
+ * uvToolEntrypointFrom}'s doc comment).
+ */
+export async function uvToolEntrypoint(pkg, run = defaultRunUv) {
+    return uvToolEntrypointFrom(pkg, await listUvTools(run));
+}
+/**
+ * The package name half of a `uv tool install` specifier: `pkg==1.2.3` → `pkg`. Returns the input
+ * unchanged when it carries no `==` pin — the ACP registry is not required to pin `uvx` specifiers
+ * the way it pins `npx` ones (see `registryTypes.ts`'s `UvxDistribution`).
+ */
+export function uvPackageName(spec) {
+    const at = spec.indexOf('==');
+    return at > 0 ? spec.slice(0, at) : spec;
+}
+/** The version half of a `uv tool install` specifier: `pkg==1.2.3` → `1.2.3`; `undefined` with no pin. */
+export function uvPackageVersion(spec) {
+    const at = spec.indexOf('==');
+    return at > 0 ? spec.slice(at + 2) : undefined;
+}
+/**
+ * `uv tool install <spec>` — the uvx counterpart to `installNpxPackage`. Short-circuits to
+ * `alreadyInstalled: true` without spawning `uv tool install` when a quick `uv tool list` probe
+ * (bounded by {@link UV_PROBE_TIMEOUT_MS}) already reports the pinned version — the same "don't
+ * repeat work that's already done" rule `installNpxPackage` follows against the npx cache. The
+ * actual install, when it runs, is a real download and gets {@link UV_TOOL_INSTALL_TIMEOUT_MS}, not
+ * the probe's budget.
+ */
+export async function installUvTool(spec, run = defaultRunUv) {
+    const pkg = uvPackageName(spec);
+    const pinned = uvPackageVersion(spec);
+    if (pinned && (await uvToolVersion(pkg, run)) === pinned) {
+        return { ok: true, alreadyInstalled: true };
+    }
+    const result = await run(['tool', 'install', spec], UV_TOOL_INSTALL_TIMEOUT_MS);
+    if (result.ok)
+        return { ok: true, alreadyInstalled: false };
+    return { ok: false, error: result.error ?? `uv tool install ${spec} failed` };
+}

package/dist/workstation/acp/validate.js

@@ -0,0 +1,134 @@
+/**
+ * The request-shaped event names the platform knows how to answer.
+ *
+ * The suffix is a promise from the bridge: "this event needs exactly one answer". The platform can
+ * only keep that promise for names it has a card for — anything else lands as a generic timeline
+ * item, never parks the run, and leaves the native agent blocked on an answer no UI can give.
+ *
+ * Membership here exempts a name from that blanket rejection and NOTHING else. In particular it does
+ * not exempt the event from its own payload rules: `permission_request`'s required-field checks live
+ * in their own name-keyed branch below and run regardless of what this set says.
+ *
+ * Same-source with the server's `TimelineEventWire.KNOWN_REQUEST_EVENT_NAMES`: adding a request-shaped
+ * event means a named decode branch there and an entry in both sets. That claim is no longer just a
+ * comment -- `validate.test.ts` reads the Kotlin set out of `TimelineEventWire.kt` and diffs it
+ * against this one, which is why this constant is exported. Note this is deliberately NOT
+ * the same list as `ExternalAgentEventApplier.parksRun()`, which also recognizes
+ * `TimelineEvent.UserInteractionRequested` — that type is how the *platform's own* agents raise a
+ * question. Its two wire names behave differently here, and the difference is the suffix, not the
+ * family:
+ *
+ * - `elicitation_request` (`TimelineEvent.InteractionRequested`) is request-shaped and absent from
+ *   the set, so a bridge emitting it is rejected. That stays true after Plan B minted the name:
+ *   the platform now *has* the vocabulary but still has no bridge decode branch for it, so it still
+ *   cannot answer one. Adding it here would exempt it into a generic item — a card with no button.
+ * - `elicitation` (`TimelineEvent.UserInteractionRequested`) carries no request suffix, so this gate
+ *   never looks at it and a bridge emitting it passes through. That is now correct rather than
+ *   merely harmless: `TimelineEventWire.decode` has a named `elicitation` branch that rebuilds the
+ *   typed event, so such a card does park the run and can be answered. The branch is strict —
+ *   anything it cannot rebuild into the platform's own `UserInteractionRequest` (with none of that
+ *   model's invariants relaxed) is dropped rather than landed, because a landed-but-unrebuilt
+ *   payload is byte-identical to a real question card and would render as an answerable card the
+ *   run never parks on. Well-formedness is defined in exactly one place, that decoder; this gate
+ *   deliberately does not carry a second copy of the shape rules to drift from it.
+ */
+export const KNOWN_REQUEST_EVENT_NAMES = new Set(['permission_request']);
+/**
+ * Does this name carry the "answer me exactly once" promise?
+ *
+ * `_request` is the live spelling (ACP request/response semantics). `_requested` is the retired one
+ * and is still caught on purpose: with no compatibility layer, a bridge that has not been upgraded
+ * emits an *unknown* request-shaped event, and it must be rejected rather than pass through as an
+ * ordinary event — the server would land it as a generic item that parks nothing and shows no
+ * buttons, stranding the agent on an answer that can never arrive.
+ */
+function looksLikeRequestEvent(eventName) {
+    return eventName.endsWith('_request') || eventName.endsWith('_requested');
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Validate one bridge-emitted event at the outbound boundary.
+ *
+ * The server also decodes defensively, but it drops silently — a bridge author would only see
+ * "output is mysteriously missing". Rejecting here, with a reason, is what makes a contract
+ * violation debuggable. Returns null when the event is fine.
+ *
+ * Total by design: the disposal contract for a violating event is "drop + diagnostic", never an
+ * exception, so even a hostile payload (throwing getters, Proxies) yields a rejection. Note that
+ * validating getter-bearing payloads is inherently advisory — a getter can return valid values now
+ * and different ones at serialization time.
+ */
+export function validateWireEvent(event) {
+    try {
+        return inspect(event);
+    }
+    catch (err) {
+        return { reason: 'event not inspectable', detail: String(err) };
+    }
+}
+function inspect(event) {
+    if (!nonEmptyString(event?.eventName))
+        return { reason: 'missing eventName' };
+    if (event.eventName === 'final_result') {
+        return {
+            reason: 'bridges must never emit final_result',
+            detail: 'it would terminally close the session run; signal turn end via onTurnDone instead',
+        };
+    }
+    if (looksLikeRequestEvent(event.eventName) && !KNOWN_REQUEST_EVENT_NAMES.has(event.eventName)) {
+        return {
+            reason: `unknown request-shaped event '${event.eventName}'`,
+            detail: 'the _request suffix promises the platform will answer, and it only knows how to answer ' +
+                `${[...KNOWN_REQUEST_EVENT_NAMES].join(', ')}; the server drops this event while the ` +
+                'watermark advances past it, so the agent would wait forever for an answer that can never ' +
+                'be replayed. Ask the user through permission_request, or emit a non-request event name.',
+        };
+    }
+    const payload = event.payload;
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+        return { reason: 'payload must be an object' };
+    }
+    // Keyed on the event name alone, independent of the suffix gate above. `permission_request` is
+    // exempt from that gate (it is in KNOWN_REQUEST_EVENT_NAMES), so these checks are the *only* thing
+    // standing between a malformed approval card and the wire.
+    if (event.eventName === 'permission_request') {
+        if (!nonEmptyString(payload.requestId)) {
+            return { reason: 'invalid permission_request', detail: 'requestId must be a non-empty string' };
+        }
+        // ACP `RequestPermissionRequest.toolCall` (`types.gen.d.ts:108`) is a whole `ToolCallUpdate`
+        // (`:140`), whose only required field is `toolCallId` (`:143`) — everything else absent means
+        // "unchanged". So `toolCallId` is the only thing worth insisting on, and it is worth insisting
+        // on: the server's decoder is `AcpToolCallUpdate.fromWire(...) ?: return null`, a silent frame
+        // drop that takes the whole approval card with it while the agent stays blocked on
+        // `session/prompt`. The flattened spelling this replaced required a top-level `name` and a
+        // synthesized `prompt`; neither is a field ACP has here.
+        const toolCall = payload.toolCall;
+        if (toolCall === null || typeof toolCall !== 'object' || Array.isArray(toolCall)) {
+            return { reason: 'invalid permission_request', detail: 'toolCall must be an object' };
+        }
+        if (!nonEmptyString(toolCall.toolCallId)) {
+            return { reason: 'invalid permission_request', detail: 'toolCall.toolCallId must be a non-empty string' };
+        }
+        const options = payload.options;
+        if (!Array.isArray(options) || options.length === 0) {
+            return {
+                reason: 'invalid permission_request',
+                detail: 'options must be a non-empty array; an option-less card parks the session with no way to answer',
+            };
+        }
+        for (const option of options) {
+            if (option === null || typeof option !== 'object' || Array.isArray(option)) {
+                return { reason: 'invalid permission_request', detail: 'each option must be an object' };
+            }
+            const entry = option;
+            for (const field of ['optionId', 'name', 'kind']) {
+                if (!nonEmptyString(entry[field])) {
+                    return { reason: 'invalid permission_request', detail: `option.${field} must be a non-empty string` };
+                }
+            }
+        }
+    }
+    return null;
+}