@platless/axom-cli 0.1.0

package/dist/workstation/acp/binaryInstall.js

@@ -0,0 +1,411 @@
+/**
+ * Download, verify and unpack a `binary`-distributed ACP adapter — the counterpart to
+ * `installProbe.ts` (npx) and `uvxInstall.ts` (uvx), and the piece that makes those adapters
+ * installable at all. Before this module, `registry/launch.ts` refused every `binary` agent
+ * outright; on the live registry snapshot this task was built against, that is 16 of 39 agents.
+ *
+ * ## The shape of a `binary` distribution
+ *
+ * It is not one archive. `RegistryAgent.distribution.binary` (`BinaryDistribution`,
+ * `registryTypes.ts`) is a `Partial<Record<..six platform triples.., BinaryTarget>>` — up to six
+ * entries keyed `darwin-aarch64` / `darwin-x86_64` / `linux-aarch64` / `linux-x86_64` /
+ * `windows-aarch64` / `windows-x86_64`, and missing entries are normal: on the snapshot this was
+ * verified against, coverage across the 18 agents that ship a binary distribution is
+ * darwin-aarch64 18/18, linux-x86_64 18/18, windows-x86_64 18/18, darwin-x86_64 16/18,
+ * linux-aarch64 16/18, and windows-aarch64 only 9/18. "No archive for this platform" is therefore a
+ * real, expected outcome for roughly a third of these agents on some machines, not an edge case —
+ * {@link installBinary} reports it as its own answer rather than an error, and never even calls
+ * `fetch` when it is the answer.
+ *
+ * Each target carries `archive` (a URL), `cmd` (a path *inside* the unpacked archive — `./goose`,
+ * `./dist-package/cursor-agent`, `agy_acp_server.par`), optional `args`/`env`, and — for roughly
+ * half the entries, `antigravity-acp` and `cursor` among them — no `sha256` at all.
+ *
+ * ## The checksum rule
+ *
+ * When the registry publishes a `sha256`, it must match or the install fails outright and nothing
+ * is written under {@link InstallBinaryOptions.root}. When it publishes none, the install proceeds
+ * anyway — refusing would make half the binary-distributed catalogue permanently uninstallable —
+ * but the result says so via `checksumVerified: false`. Nothing here may report an unverified
+ * download as checked; that is precisely the distinction {@link InstallOutcome} exists to preserve.
+ *
+ * ## Layout: several versions can coexist
+ *
+ * Installs land at `<root>/<registryAgent>/<version>/`, one directory per version, the same
+ * side-by-side layout npm's own `_npx` cache keeps for npx-distributed adapters. Picking one
+ * installed version when several are present reuses `installProbe.ts`'s
+ * {@link pickInstalledVersion} rather than reimplementing that rule a second time — see
+ * {@link installedBinaryVersion}.
+ *
+ * ## Unpacking without a new dependency
+ *
+ * Three archive formats are in use (`.tar.gz`, `.tar.bz2`, `.zip`) and this deliberately does not
+ * add a tar/zip library to do it: every `tar` this was checked against — GNU tar (Linux) and the
+ * bsdtar that ships as `/usr/bin/tar` on macOS and as `tar.exe` on Windows since 10 (1803) — reads
+ * the compression off the archive's own magic bytes for `-xf`, no `-z`/`-j` needed, which covers
+ * both tar formats on every platform uniformly — though on a slim Linux image "reads the
+ * compression" still means shelling out to `bzip2`/`xz`, which a `-slim` base does not ship;
+ * `docker/axom-workstation/Dockerfile` installs them for exactly this reason. `.zip` tries `unzip`
+ * first (which is *not* on every image either — this repo's own workstation image lacked it, and
+ * 33 of the registry's binary targets are `.zip`) and falls back to `tar -xf` — which is what lets a
+ * Windows host extract a `.zip` via its bundled bsdtar even with no `unzip` anywhere on it; when
+ * *both* fail on a `.zip` (a Linux workstation without `unzip`, where GNU tar cannot read zip at
+ * all), the error names what is missing instead of surfacing GNU tar's confusing parse failure.
+ * See {@link extractArchive}.
+ *
+ * ## Not every `archive` is an archive
+ *
+ * A live registry snapshot has four `binary` entries (`sigit` among them) whose `archive` field
+ * points at a bare, unpacked executable — a raw ELF or PE, not a `.tar.gz`/`.zip` — because that is
+ * literally what the upstream project publishes as a GitHub release asset. Extraction is decided
+ * per target rather than assumed: a recognised archive extension settles it outright; anything else
+ * is sniffed by its first bytes (gzip/bzip2/xz/zip magic) once it is on disk, because a URL with no
+ * extension at all could still be a tarball and guessing from the URL alone would repeat this same
+ * mistake. Whatever is not an archive by either test is placed as-is at
+ * `<installDir>/<basename of the archive URL>` and marked executable — that filename is exactly
+ * what `BinaryTarget.cmd` refers to. See {@link isArchiveFile}.
+ */
+import { createHash } from 'node:crypto';
+import { createWriteStream, promises as fs, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { pickInstalledVersion } from './installProbe.js';
+import { runTimedCommand } from './timedCommand.js';
+const PLATFORM_SEGMENT = {
+    darwin: 'darwin',
+    linux: 'linux',
+    win32: 'windows',
+};
+const ARCH_SEGMENT = {
+    arm64: 'aarch64',
+    x64: 'x86_64',
+};
+/**
+ * Maps Node's own `process.platform`/`process.arch` vocabulary onto one of the registry's six
+ * platform-triple keys, or `undefined` for anything the registry does not describe at all (every
+ * platform Node runs on that is not one of the three OSes above, or an architecture other than the
+ * two 64-bit ones the registry ships for).
+ */
+export function platformTriple(platform, arch) {
+    const os = PLATFORM_SEGMENT[platform];
+    const cpu = ARCH_SEGMENT[arch];
+    return os && cpu ? `${os}-${cpu}` : undefined;
+}
+/** The archive target for one platform triple, or `undefined` when the registry has none — normal, see the module doc. */
+export function binaryTargetFor(agent, triple) {
+    return agent.distribution.binary?.[triple];
+}
+/**
+ * How many redirects one archive download may follow. Five is well past what any real host needs
+ * (GitHub uses exactly one) and still bounds a redirect loop, which is the thing the old
+ * `redirect: 'error'` policy was reaching for — see {@link fetchArchive}.
+ */
+const MAX_ARCHIVE_REDIRECTS = 5;
+/** The redirect statuses a download must follow. 304 is deliberately absent: it is not a redirect. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * The version of `registryAgent` installed under `root`, chosen the same way `installProbe.ts`'s
+ * `npxCacheVersion` chooses among several npx-cached versions:
+ * `pinned` when it is among the directories found (so an exact match is never shadowed by a newer
+ * sibling), else the greatest by semver, unparseable versions sorting last by string.
+ *
+ * `pinned` is optional and normally omitted by `registry/launch.ts` (a `BinaryTarget` carries no
+ * per-target version to pin against — the registry pins the *agent*, via `RegistryAgent.version`,
+ * not the archive), which is why an installed binary agent with only one version on disk is the
+ * common case this resolves without needing it at all.
+ *
+ * Reads the directory once; a `root` or `<root>/<registryAgent>` that does not exist yet (nothing
+ * installed) is not an error — it answers `undefined`, the same as an empty directory.
+ */
+export function installedBinaryVersion(registryAgent, root, pinned) {
+    let entries;
+    try {
+        entries = readdirSync(path.join(root, registryAgent), { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    const versions = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    return pickInstalledVersion(versions, pinned);
+}
+/**
+ * Fetches `url`, following redirects itself, up to {@link MAX_ARCHIVE_REDIRECTS} hops.
+ *
+ * ## Why this follows redirects at all
+ *
+ * It used to pass `redirect: 'error'`, copied from `artifact.ts`'s `downloadVerified` — "refuse
+ * redirects rather than follow them silently". That reasoning does not survive contact with the
+ * registry: a `BinaryTarget.archive` is a third-party URL, and on the live snapshot **14 of the 19
+ * agents publishing a `linux-x86_64` archive host it on `github.com`**, whose release-asset URLs
+ * answer 302 to `release-assets.githubusercontent.com` on every single request. `redirect: 'error'`
+ * therefore did not harden those downloads, it made them impossible — `amp-acp`, `goose`, `junie`,
+ * `kilo`, `kimi`, `opencode`, `vtcode` and seven more failed with a bare `fetch failed`, and the
+ * reader was left to configure something no configuration could fix.
+ *
+ * ## What is kept from that policy
+ *
+ * Both halves of what refusing was actually buying, made explicit instead of implicit:
+ *
+ * - **A loop cannot run forever.** The hop count is capped here, and the `AbortSignal` is created
+ *   once by the caller and passed to every hop, so {@link ARCHIVE_DOWNLOAD_TIMEOUT_MS} remains the
+ *   budget for the whole chain rather than resetting per hop.
+ * - **No silent downgrade.** Every hop must land on `https:`. A redirect to `http:` — or to any
+ *   other scheme — is refused rather than followed, which is the case "silently" was really about.
+ *
+ * The checksum rule is unchanged and orthogonal: where the registry publishes a `sha256`, it is
+ * verified against whatever the final hop delivered, so a redirect cannot substitute other bytes.
+ * Error text never repeats a redirect target — GitHub's carries a signed URL token.
+ */
+async function fetchArchive(url, fetchImpl, signal) {
+    let current = url;
+    for (let hop = 0; hop <= MAX_ARCHIVE_REDIRECTS; hop += 1) {
+        const response = await fetchImpl(current, { redirect: 'manual', signal });
+        if (!REDIRECT_STATUSES.has(response.status))
+            return { ok: true, response };
+        const location = response.headers.get('location');
+        if (!location)
+            return { ok: false, error: `HTTP ${response.status} carried no Location header.` };
+        let next;
+        try {
+            next = new URL(location, current);
+        }
+        catch {
+            return { ok: false, error: `HTTP ${response.status} carried a Location that is not a usable URL.` };
+        }
+        if (next.protocol !== 'https:') {
+            return { ok: false, error: `refused to follow a redirect to a non-HTTPS location (${next.protocol}).` };
+        }
+        current = next.toString();
+    }
+    return { ok: false, error: `more than ${MAX_ARCHIVE_REDIRECTS} redirects.` };
+}
+/**
+ * Whole-request budget for one archive download, body included — the `AbortSignal` handed to
+ * `fetch` aborts the response stream too, not just the headers.
+ *
+ * Matches `installProbe.ts`'s `ADAPTER_INSTALL_TIMEOUT_MS` deliberately: until this module was
+ * wired into `AcpAgents.install` it had no production caller at all, and the 60s it carried while
+ * unreachable would have cut off the very archives it exists to fetch (binary adapters are whole
+ * agents — `opencode`, `cursor-agent`, `goose` — not thin wrappers). The budget is here to bound a
+ * download that will never finish, not one that is merely large.
+ */
+const ARCHIVE_DOWNLOAD_TIMEOUT_MS = 300_000;
+/**
+ * Budget for unpacking one already-downloaded archive with `tar`/`unzip` — the step after the
+ * download above, previously run via blocking `execFileSync` with no bound at all.
+ *
+ * Matches {@link ARCHIVE_DOWNLOAD_TIMEOUT_MS} deliberately, the same way that constant matches
+ * `installProbe.ts`'s `ADAPTER_INSTALL_TIMEOUT_MS`: extraction is normally seconds even for a large
+ * archive (it is local disk I/O, not a network transfer), but "normally fast" is not a bound — a
+ * wedged filesystem or a pathological archive must not be able to hang this daemon's event loop for
+ * longer than the download step right above it is already allowed to take.
+ */
+const ARCHIVE_EXTRACT_TIMEOUT_MS = 300_000;
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function hasEntries(dir) {
+    try {
+        return readdirSync(dir).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** The archive's own file name off its URL, for the scratch download file — falls back to a fixed name if the URL is unparseable. */
+function archiveFileName(url) {
+    try {
+        return path.basename(new URL(url).pathname) || 'archive';
+    }
+    catch {
+        return path.basename(url) || 'archive';
+    }
+}
+const ARCHIVE_EXTENSIONS = ['.tar.gz', '.tgz', '.tar.bz2', '.tbz2', '.tar.xz', '.txz', '.zip'];
+/** Magic-byte prefixes for the archive formats this module ever has to extract. */
+const ARCHIVE_SIGNATURES = [
+    [0x1f, 0x8b], // gzip
+    [0x42, 0x5a, 0x68], // bzip2
+    [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00], // xz
+    [0x50, 0x4b, 0x03, 0x04], // zip
+];
+function matchesArchiveSignature(head) {
+    return ARCHIVE_SIGNATURES.some((sig) => head.length >= sig.length && sig.every((byte, i) => head[i] === byte));
+}
+/**
+ * Whether the file at `archivePath` (already downloaded and checksum-verified) is an archive at
+ * all — see the module doc's "Not every `archive` is an archive" section. A recognised extension on
+ * `sourceUrl` settles it without touching the file; otherwise the first six bytes on disk are
+ * sniffed for gzip/bzip2/xz/zip magic, because an extension-less URL can still be a real tarball.
+ */
+async function isArchiveFile(archivePath, sourceUrl) {
+    const lowerName = archiveFileName(sourceUrl).toLowerCase();
+    if (ARCHIVE_EXTENSIONS.some((ext) => lowerName.endsWith(ext)))
+        return true;
+    const handle = await fs.open(archivePath, 'r');
+    try {
+        const head = Buffer.alloc(6);
+        const { bytesRead } = await handle.read(head, 0, head.length, 0);
+        return matchesArchiveSignature(head.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+const runCommand = async (command, args, timeoutMs) => {
+    const result = await runTimedCommand(command, args, timeoutMs);
+    if (result.ok)
+        return;
+    const error = new Error(result.message);
+    if (result.code)
+        error.code = result.code;
+    throw error;
+};
+/**
+ * `.zip` tries `unzip` first, then falls back to `tar -xf` (bsdtar reads zip; GNU tar does not) —
+ * see the module doc. When `unzip` is missing *and* the `tar` fallback also fails, that combination
+ * means this machine simply cannot open a zip (a bare Linux box with neither), so the error names
+ * both tools and what to install instead of surfacing GNU tar's opaque "not a tar archive" message.
+ */
+async function extractZip(archivePath, destDir, exec, timeoutMs) {
+    let unzipMissing = false;
+    try {
+        await exec('unzip', ['-o', '-q', archivePath, '-d', destDir], timeoutMs);
+        return;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        unzipMissing = true;
+        // No `unzip` on this machine — fall through to `tar`, which (bsdtar on macOS, and Windows's
+        // bundled tar.exe) reads `.zip` too.
+    }
+    try {
+        await exec('tar', ['-xf', archivePath, '-C', destDir], timeoutMs);
+    }
+    catch (err) {
+        if (!unzipMissing)
+            throw err;
+        throw new Error("Cannot extract this .zip archive: neither 'unzip' nor a zip-capable 'tar' (bsdtar) is " +
+            "available on this machine. Install 'unzip' (e.g. 'apt-get install unzip' or " +
+            "'apk add unzip') and retry.");
+    }
+}
+/**
+ * Unpacks one already-downloaded, already-verified archive into `destDir`. See the module doc's
+ * "Unpacking without a new dependency" section for why this shells out to `tar`/`unzip` rather than
+ * parsing archive formats in-process. `timeoutMs` is {@link ARCHIVE_EXTRACT_TIMEOUT_MS} in
+ * production; see that constant for why it matches the download budget above it.
+ */
+async function extractArchive(archivePath, destDir, exec, timeoutMs) {
+    if (archivePath.toLowerCase().endsWith('.zip')) {
+        await extractZip(archivePath, destDir, exec, timeoutMs);
+        return;
+    }
+    await exec('tar', ['-xf', archivePath, '-C', destDir], timeoutMs);
+}
+/**
+ * Fetch, verify and unpack `agent`'s binary adapter for this machine's platform triple. Never
+ * starts the agent — the counterpart to `installNpxPackage`/`installUvTool`'s "download, don't run"
+ * contract.
+ *
+ * ## The three outcomes the brief for this task requires, and why each looks the way it does
+ *
+ * - **No archive for this platform triple**: `binaryTargetFor` finds nothing, `fetch` is never
+ *   called, `ok: false`. Checked before any I/O — the point is that a machine on
+ *   `windows-aarch64` (9/18 coverage — see the module doc) never opens a socket over an archive
+ *   that was never going to exist.
+ * - **Registry publishes a `sha256` and the bytes don't match**: the archive is downloaded into a
+ *   scratch temp directory and hashed while it streams to disk, entirely separate from
+ *   {@link InstallBinaryOptions.root}. A mismatch returns `ok: false` *before* `installDir` is ever
+ *   created — nothing under `root` exists that did not exist before the call — and only the scratch
+ *   directory (never inside `root`) needs cleaning up, which the `finally` below always does.
+ * - **Registry publishes no `sha256`**: the install proceeds — this is not a reason to refuse, see
+ *   the module doc — and the result carries `checksumVerified: false` so nothing downstream can
+ *   mistake "we didn't check" for "we checked and it passed".
+ *
+ * `installDir` already holding files (a previous successful install of this exact version) short-
+ * circuits to `alreadyInstalled: true` before touching the network at all; `checksumVerified` on
+ * that path is `false` because this call verified nothing — it is a fact about *this call*, not a
+ * claim about what a previous one did.
+ */
+export async function installBinary(agent, opts) {
+    const platform = opts.platform ?? process.platform;
+    const arch = opts.arch ?? process.arch;
+    const triple = platformTriple(platform, arch);
+    const target = triple ? binaryTargetFor(agent, triple) : undefined;
+    if (!target) {
+        return { ok: false, error: `Agent '${agent.id}' publishes no archive for ${triple ?? `${platform}-${arch}`}.` };
+    }
+    const version = agent.version;
+    const installDir = path.join(opts.root, agent.id, version);
+    if (hasEntries(installDir)) {
+        return { ok: true, checksumVerified: false, alreadyInstalled: true, version, installDir };
+    }
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        return { ok: false, error: 'No fetch implementation is available to download the adapter archive.' };
+    }
+    const workDir = await fs.mkdtemp(path.join(opts.temporaryDirectory ?? tmpdir(), 'axom-acp-binary-'));
+    try {
+        const archivePath = path.join(workDir, archiveFileName(target.archive));
+        let response;
+        try {
+            // Not reusing `artifact.ts`'s `downloadVerified` — it is shaped around a single trusted,
+            // same-origin management server and a signed `size`/SHA-512 descriptor (`ClientReleaseInfo`),
+            // whereas a `BinaryTarget.archive` is an arbitrary third-party URL verified by an optional
+            // SHA-256 the registry supplies. Different trust model, so the policy is stated here: one
+            // whole-chain budget, a capped number of hops, and HTTPS at every one. See `fetchArchive` for
+            // why following redirects is required rather than merely permitted.
+            const fetched = await fetchArchive(target.archive, fetchImpl, AbortSignal.timeout(ARCHIVE_DOWNLOAD_TIMEOUT_MS));
+            if (!fetched.ok) {
+                return { ok: false, error: `Failed to download adapter archive for '${agent.id}': ${fetched.error}` };
+            }
+            response = fetched.response;
+        }
+        catch (err) {
+            return { ok: false, error: `Failed to download adapter archive for '${agent.id}': ${errorMessage(err)}` };
+        }
+        if (!response.ok || !response.body) {
+            return { ok: false, error: `Failed to download adapter archive for '${agent.id}': HTTP ${response.status}.` };
+        }
+        const hash = createHash('sha256');
+        const source = Readable.fromWeb(response.body);
+        source.on('data', (chunk) => hash.update(chunk));
+        await pipeline(source, createWriteStream(archivePath, { mode: 0o600 }));
+        if (target.sha256) {
+            const digest = hash.digest('hex');
+            if (digest.toLowerCase() !== target.sha256.toLowerCase()) {
+                return {
+                    ok: false,
+                    error: `Downloaded archive for '${agent.id}' failed sha256 verification: the registry pins ` +
+                        `${target.sha256}, the download hashed to ${digest}.`,
+                };
+            }
+        }
+        await fs.mkdir(installDir, { recursive: true });
+        try {
+            if (await isArchiveFile(archivePath, target.archive)) {
+                await extractArchive(archivePath, installDir, opts.exec ?? runCommand, ARCHIVE_EXTRACT_TIMEOUT_MS);
+            }
+            else {
+                // Not an archive at all — the download *is* the program (e.g. `sigit`'s Linux/Windows
+                // targets, see the module doc). Place it under the same name `BinaryTarget.cmd` refers to
+                // and mark it executable; `chmod` is a no-op on Windows but harmless there.
+                const destPath = path.join(installDir, archiveFileName(target.archive));
+                await fs.copyFile(archivePath, destPath);
+                await fs.chmod(destPath, 0o755);
+            }
+        }
+        catch (err) {
+            await fs.rm(installDir, { recursive: true, force: true }).catch(() => undefined);
+            return { ok: false, error: `Failed to unpack adapter archive for '${agent.id}': ${errorMessage(err)}` };
+        }
+        return { ok: true, checksumVerified: Boolean(target.sha256), alreadyInstalled: false, version, installDir };
+    }
+    finally {
+        await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/workstation/acp/configOptions.js

@@ -0,0 +1,257 @@
+/**
+ * daemon 保留 id：agent 只给 `modes`（`SessionModeState`, types.gen.d.ts:2561-2580）而**读者手上还
+ * 没有这个控件**时合成。什么算"已经有了"由 {@link modesAlreadyRepresented} 说了算——包括 agent 自己
+ * 就用这个 id 的情形（agent 的赢，什么都不合成）。
+ */
+export const SYNTHESIZED_MODES_CONFIG_ID = 'acp:modes';
+function toSelectOption(o) {
+    return { value: o.value, name: o.name, ...(o.description != null ? { description: o.description } : {}) };
+}
+/** A sanitized `SessionMode` (`types.gen.d.ts:2590-2613`) uses `id`, not `value` — mapped to {@link SelectOptionWire}'s shape. */
+function modeToSelectOption(mode) {
+    return toSelectOption({ value: mode.id, name: mode.name, description: mode.description });
+}
+/**
+ * True for anything a property can safely be read off — i.e. not `null`/`undefined` and not a
+ * primitive. This is the one runtime check every boundary in this file is built on: reading a
+ * field off `null` (`entry.group`, `option.id`, `modes.availableModes`, …) throws *before* any
+ * `typeof` check ever sees a value, which is exactly the hole this file exists to close.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Maps every item through `fn`, or `null` the moment any one of them does — "every item is
+ * representable, or none of them are kept". This is what makes a malformed entry anywhere in an
+ * `options` array take down the *whole* option (via {@link toWire} returning `null`) rather than a
+ * partially-valid array silently missing one entry, which would be a different (and unannounced)
+ * shape than what the agent actually reported.
+ */
+function mapAllOrNothing(items, fn) {
+    const out = [];
+    for (const item of items) {
+        const mapped = fn(item);
+        if (mapped === null)
+            return null;
+        out.push(mapped);
+    }
+    return out;
+}
+/**
+ * Validates and narrows one raw entry that is supposed to be a `SessionConfigSelectOption`
+ * (`types.gen.d.ts:2676-2699`). `null` when it isn't representable as {@link SelectOptionWire} —
+ * not a record at all, `value`/`name` missing or not strings, or a `description` present but not
+ * a nullable string. Takes `unknown`, not {@link RawEntry}: this is called on elements of a
+ * *nested* `options` array the top-level boundary in {@link normalizeConfigOptions} never looks
+ * at, so nothing upstream has established these are records — `isRecord` here is the only thing
+ * standing between a `null` element and a thrown `TypeError`.
+ */
+function toSelectOptionSafe(entry) {
+    if (!isRecord(entry))
+        return null;
+    if (typeof entry.value !== 'string' || typeof entry.name !== 'string')
+        return null;
+    if (entry.description != null && typeof entry.description !== 'string')
+        return null;
+    return toSelectOption({ value: entry.value, name: entry.name, description: entry.description });
+}
+/**
+ * Same validation, for one raw `SessionConfigSelectGroup` entry (`types.gen.d.ts:2703-2726`): a
+ * record whose `group`/`name` are strings and whose `options` is an array that itself validates
+ * entry-by-entry via {@link toSelectOptionSafe} — a group with a malformed member is exactly as
+ * unrepresentable as a group missing `options` altogether, so both drop the whole option via the
+ * same `null`.
+ *
+ * No `isRecord` check on `entry` itself here (unlike {@link toSelectOptionSafe}) — not an
+ * oversight, a proven invariant: this is only ever reached from `toWire`'s
+ * `mapAllOrNothing(raw, toSelectGroupSafe)`, which is only taken when `groupedCount === raw.length`
+ * — i.e. every element of `raw` already passed `isRecord(entry) && typeof entry.group === 'string'`
+ * to be counted into `groupedCount` in the first place. A repeated check here could never be false;
+ * keeping one anyway would be dead code that reads as protection where none is needed, and could
+ * mislead a future caller into believing this function is safe to call on unvalidated input the way
+ * {@link toSelectOptionSafe} is. If a second call site is ever added, it must re-earn this contract
+ * (or this function must regain the check) rather than assume it for free.
+ */
+function toSelectGroupSafe(entry) {
+    const record = entry;
+    if (typeof record.group !== 'string' || typeof record.name !== 'string' || !Array.isArray(record.options))
+        return null;
+    const options = mapAllOrNothing(record.options, toSelectOptionSafe);
+    if (options === null)
+        return null;
+    return { group: record.group, name: record.name, options };
+}
+/**
+ * 一条 ACP `SessionConfigOption`（types.gen.d.ts:2617-2648）→ 隧道形状。调用者（{@link normalizeConfigOptions}）
+ * 已经保证 `option` 本身是一条 record —— 这里不再重复检查。`id`/`name` 必须是字符串，否则整条丢弃
+ * （`null`）；`description`/`category` 存在但不是字符串时只丢字段本身（它们本来就是 optional），
+ * 不连累整条；`_meta` 一律丢弃；不认识的 `type` 也返回 null。
+ */
+function toWire(option) {
+    if (typeof option.id !== 'string' || typeof option.name !== 'string')
+        return null;
+    const base = {
+        id: option.id,
+        name: option.name,
+        ...(typeof option.description === 'string' ? { description: option.description } : {}),
+        ...(typeof option.category === 'string' ? { category: option.category } : {}),
+    };
+    if (option.type === 'boolean') {
+        if (typeof option.currentValue !== 'boolean')
+            return null;
+        return { ...base, type: 'boolean', currentValue: option.currentValue };
+    }
+    if (option.type === 'select') {
+        if (typeof option.currentValue !== 'string' || !Array.isArray(option.options))
+            return null;
+        const raw = option.options;
+        // `SessionConfigSelectOptions` (types.gen.d.ts:2672) is a union: a flat list of
+        // `SessionConfigSelectOption` (:2676-2699), OR a list of `SessionConfigSelectGroup`
+        // (:2703-2726) — never a mix of both. Grouped entries carry a string `group`; ungrouped ones
+        // don't. `isRecord` guards the property read itself: a `null`/primitive array element is
+        // neither shape and must not throw just for being asked "do you have a `group`?". An array
+        // that mixes the two shapes can't be represented as either arm of the union, so the whole
+        // option is dropped (`null`) rather than emitting some entries one way and others the other.
+        const groupedCount = raw.filter((entry) => isRecord(entry) && typeof entry.group === 'string').length;
+        if (groupedCount !== 0 && groupedCount !== raw.length)
+            return null;
+        const options = groupedCount > 0 ? mapAllOrNothing(raw, toSelectGroupSafe) : mapAllOrNothing(raw, toSelectOptionSafe);
+        if (options === null)
+            return null;
+        return { ...base, type: 'select', currentValue: option.currentValue, options };
+    }
+    return null;
+}
+/**
+ * One raw `SessionMode` entry (`types.gen.d.ts:2590-2613`), sanitized — `null` when it isn't a
+ * record, or `id`/`name` are missing or not strings, or a `description` is present but not a
+ * nullable string.
+ */
+function sanitizeMode(entry) {
+    if (!isRecord(entry))
+        return null;
+    if (typeof entry.id !== 'string' || typeof entry.name !== 'string')
+        return null;
+    if (entry.description != null && typeof entry.description !== 'string')
+        return null;
+    return { id: entry.id, name: entry.name, description: entry.description };
+}
+/**
+ * Boundary-sanitizes `modes` (`SessionModeState`, types.gen.d.ts:2561-2580) into what
+ * {@link normalizeConfigOptions} needs in order to synthesize `acp:modes`, or `null` when it
+ * cannot: `modes` itself isn't a record, `currentModeId` isn't a string, `availableModes` isn't an
+ * array, or — once every entry is individually sanitized via {@link sanitizeMode} — nothing usable
+ * is left. Unlike an `options` array's entries ({@link mapAllOrNothing}'s all-or-nothing rule), one
+ * bad mode entry does not disqualify the good ones next to it; only a `modes` that yields zero
+ * usable entries is treated as though the agent reported no `modes` at all — no synthesis, no
+ * throw, and never a picker with nothing in it.
+ */
+function sanitizeModes(modes) {
+    if (!isRecord(modes) || typeof modes.currentModeId !== 'string' || !Array.isArray(modes.availableModes))
+        return null;
+    const availableModes = modes.availableModes.map(sanitizeMode).filter((m) => m !== null);
+    if (availableModes.length === 0)
+        return null;
+    return { currentModeId: modes.currentModeId, availableModes };
+}
+/**
+ * A `select` option's choices when they are the *flat* arm of `SessionConfigSelectOptions`
+ * (`types.gen.d.ts:2672`), or `null` for anything else — a `boolean` option, or a grouped
+ * (`SessionConfigSelectGroup`) list. Grouped is `null` rather than flattened on purpose: a modes
+ * picker is always flat ({@link modeToSelectOption} over `availableModes`), so a grouped option can
+ * never be the same control, and flattening it would only invent a comparison that has no meaning.
+ *
+ * Discriminating on `'group' in entry` is the same rule {@link toWire} enforced on the way in
+ * (`groupedCount === raw.length` or `0`, never a mix), so one probe of the first entry would do —
+ * `every` is used anyway because that invariant lives in a different function and reading one entry
+ * would silently depend on it.
+ */
+export function flatChoicesOf(option) {
+    if (option.type !== 'select')
+        return null;
+    const entries = option.options;
+    if (!entries.every((entry) => !('group' in entry)))
+        return null;
+    return entries;
+}
+/** Two flat choice lists offering exactly the same things, in the same order, under the same labels. */
+function sameChoices(a, b) {
+    return a.length === b.length && a.every((choice, i) => choice.value === b[i].value && choice.name === b[i].name);
+}
+/**
+ * "This list already gives the reader a control for these modes" — the whole condition under which
+ * nothing is synthesized. Three ways it can be true, and the third is the one measured on a real
+ * workstation:
+ *
+ * 1. **An option in `category: "mode"`.** ACP's own category for a permission policy; Claude Code
+ *    declares one, so it never got a synthesized twin.
+ * 2. **An option already using the reserved {@link SYNTHESIZED_MODES_CONFIG_ID}.** The agent's own
+ *    always wins over the daemon's stand-in for it, whatever it calls itself.
+ * 3. **An option whose choices are, entry for entry, the same list the modes picker would offer.**
+ *    `pi-acp` maps its thinking levels onto ACP session modes *and* declares them as its own
+ *    `thought_level` option: `id: 'thought_level'` and the synthesized `acp:modes` came back
+ *    byte-identical down to the labels (`off/minimal/low/medium/high/xhigh`, all named
+ *    `Thinking: …`), so the page drew the same control twice — once correctly labelled *Thinking*,
+ *    once mislabelled *Mode* with a thinking value selected.
+ *
+ * **Why (3) cannot misfire on an agent whose modes genuinely are a permission policy.** It fires
+ * only when the agent itself already publishes a `select` offering the *identical* `value` sequence
+ * *and* the identical `name` for each of them. Values alone would be too weak — an unrelated
+ * on/off-shaped setting could collide with an on/off-shaped mode set — so the reader-visible labels
+ * have to coincide too, and a permission policy's labels ("Always ask", "Accept edits", "Bypass
+ * permissions") do not coincide entry-for-entry with a model list, a reasoning-effort list, or a
+ * toggle unless that list *is* the mode picker under another id. And an agent that declares a real
+ * permission policy has already been caught by (1) before this is ever reached: `category: "mode"`
+ * is what ACP asks such an option to carry.
+ *
+ * The empty list is explicitly not a match: `sameChoices([], [])` is `true`, and an agent may
+ * legitimately report a `select` with no choices yet (see the "empty options array" case in the
+ * tests). `choices.length === 0` can only arise from a `modes` that {@link sanitizeModes} would
+ * have rejected anyway, so requiring a non-empty list costs nothing and removes a way for an empty
+ * placeholder option to swallow a real mode picker.
+ */
+export function modesAlreadyRepresented(options, choices) {
+    if (options.some((o) => o.category === 'mode' || o.id === SYNTHESIZED_MODES_CONFIG_ID))
+        return true;
+    if (choices.length === 0)
+        return false;
+    return options.some((o) => {
+        const own = flatChoicesOf(o);
+        return own !== null && sameChoices(own, choices);
+    });
+}
+/**
+ * 唯一一条归一化规则：ACP 的 `configOptions` + `modes` → 隧道的 `SessionConfigOptionWire[]`。
+ *
+ * **This function is the trust boundary for agent-supplied session config data.** Nothing upstream
+ * of it validates a `session/new`/`session/load` response before handing it here (checked against
+ * the SDK's own source — `ClientContext.request`'s `mapResponse` is unset for `session/new` and
+ * `session/set_config_option`, and is a bare `response ?? {}` identity for `session/load`; no zod
+ * schema runs against any of the three), so the declared TS parameter types are a *hope*, not a
+ * *guarantee*, about what an external agent process actually sent over stdio. Past this point,
+ * downstream code may assume: every element {@link toWire} receives is a non-null record (never
+ * `null`/`undefined`/a primitive — `configOptions` itself is always treated as an array even if the
+ * agent sent something else entirely); and `cleanModes`, if not `null`, is a record with a string
+ * `currentModeId` and a non-empty array of mode entries each carrying a string `id` and `name`.
+ * Nothing below this function re-derives either guarantee — that is the point of establishing it
+ * once, here.
+ */
+export function normalizeConfigOptions(configOptions, modes) {
+    const rawOptions = Array.isArray(configOptions) ? configOptions.filter(isRecord) : [];
+    const out = rawOptions.map(toWire).filter((o) => o !== null);
+    const cleanModes = sanitizeModes(modes);
+    if (cleanModes) {
+        const choices = cleanModes.availableModes.map(modeToSelectOption);
+        if (!modesAlreadyRepresented(out, choices)) {
+            out.push({
+                id: SYNTHESIZED_MODES_CONFIG_ID,
+                name: 'Mode',
+                category: 'mode',
+                type: 'select',
+                currentValue: cleanModes.currentModeId,
+                options: choices,
+            });
+        }
+    }
+    return out;
+}