commandmate 0.27.0 → 0.28.0

package/dist/server/src/types/opencode-export.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * `opencode export --sanitize` — what it actually removes (Issue #2051)
+ *
+ * The Issue asks for the sanitized export to become an attachment candidate for
+ * the daily report and for `/create-pr`. The name `--sanitize` is not evidence
+ * that it is safe to attach, so 1.18.22 was measured against a session built to
+ * be maximally leaky — a prompt carrying an inline password, and a `read` tool
+ * call over a file of key-shaped strings. Both exports were taken and diffed;
+ * the full record is `docs/design/opencode-server-live-verification.md` §23.
+ *
+ * ## What it removes
+ *
+ * Every field that can carry free text or file content:
+ *
+ * | Field | Sanitized value |
+ * |---|---|
+ * | `info.directory` | `[redacted:session-directory:<sessionID>]` |
+ * | `info.title` | `[redacted:session-title:<sessionID>]` |
+ * | `messages[].info.path.cwd` / `.root` | `[redacted:cwd:<messageID>]` / `[redacted:root:…]` |
+ * | `messages[].parts[].text` | `[redacted:text:<partID>]` — **user and assistant alike** |
+ * | `messages[].parts[].snapshot` | `[redacted:snapshot:<partID>]` |
+ * | `messages[].parts[].state.output` | `[redacted:tool-output:<partID>]` |
+ * | `messages[].parts[].state.title` | `[redacted:tool-title:<partID>]` |
+ * | `messages[].parts[].state.input` | replaced by `{ redacted: "tool-input:<partID>" }` |
+ * | `messages[].parts[].state.metadata` | replaced by `{ redacted: "tool-state-metadata:<partID>" }` |
+ * | `messages[].parts[].metadata` | replaced by `{ redacted: "tool-metadata:<partID>" }` |
+ *
+ * Verified by counting needles: the inline password, the four key-shaped
+ * strings, the read file's name, the operator's username and every path segment
+ * appeared 3–8 times each in the plain export and **zero** times in the
+ * sanitized one.
+ *
+ * ## What it keeps — and why that is the interesting half
+ *
+ * Ids (session / message / part / `callID`), `slug`, `projectID`, `path`,
+ * `agent`, `model.id`, `model.providerID`, `model.variant`, `version`, every
+ * timestamp, every token count, every cost, `finish` reasons, `state.status`,
+ * each part's `type`, the diff `summary` counts — and **the tool names**
+ * (`"read"`), which are not redacted.
+ *
+ * The consequence worth stating plainly: **a sanitized export contains no
+ * conversation at all.** It is not a redacted transcript, it is a metrics and
+ * shape document — how many turns, which tools ran, what it cost, how long it
+ * took. That is a genuinely useful thing to hang off a daily report or a PR, but
+ * it is not the thing "attach the transcript" suggests, so
+ * {@link summarizeOpencodeExport} reduces it to exactly those facts rather than
+ * pretending the JSON is readable.
+ *
+ * Two kept fields needed a judgement call, since the Issue asks for one:
+ *
+ * - **`projectID`** is a hash derived from the session's absolute directory
+ *   (`44b7340824bf…` for the measured path). It is not reversible, but it is a
+ *   stable fingerprint of a path, so two exports from the same checkout can be
+ *   linked. For a daily report and a PR body — both of which already name the
+ *   repository — that is not a disclosure, and it is kept.
+ * - **Tool names** reveal the shape of the work (`read`, `bash`, `edit`). Same
+ *   judgement, same reason, and they are most of the value in the summary.
+ *
+ * ## Why {@link auditOpencodeExportRedaction} exists
+ *
+ * "It is called sanitize" is not a guarantee that `--sanitize` was passed, that
+ * this opencode release still redacts the same fields, or that the bytes on
+ * hand came from that command at all. Every path measured above is checked
+ * before anything is attached, and an export that fails the audit is dropped
+ * rather than published. A later release that stops redacting a field turns
+ * into a missing section, which is the failure worth having.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_EXPORT_SENSITIVE_KEYS = exports.OPENCODE_REDACTION_PREFIX = void 0;
+exports.auditOpencodeExportRedaction = auditOpencodeExportRedaction;
+exports.summarizeOpencodeExport = summarizeOpencodeExport;
+/** The prefix every scalar redaction token measured on 1.18.22 begins with. */
+exports.OPENCODE_REDACTION_PREFIX = '[redacted:';
+/**
+ * Keys whose value must be redacted in a `--sanitize` export.
+ *
+ * Every one was observed carrying either free text or a filesystem path in the
+ * plain export of the same session. `input` and `metadata` are here because
+ * `--sanitize` replaces the whole object rather than its leaves.
+ */
+exports.OPENCODE_EXPORT_SENSITIVE_KEYS = [
+    'directory',
+    'title',
+    'cwd',
+    'root',
+    'text',
+    'snapshot',
+    'output',
+    'input',
+    'metadata',
+];
+function isRedactedScalar(value) {
+    return typeof value === 'string' && value.startsWith(exports.OPENCODE_REDACTION_PREFIX);
+}
+/**
+ * Whether a value is the `{ redacted: "…" }` stand-in `--sanitize` substitutes
+ * for `state.input`, `state.metadata` and `parts[].metadata`.
+ */
+function isRedactedObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === 'redacted';
+}
+/**
+ * Check every measured-sensitive field of a parsed export.
+ *
+ * Absent, `null` and empty-string values pass: a part with no text simply has
+ * none, and `--sanitize` leaves those alone rather than inventing a token for
+ * them. Numbers and booleans pass for the same reason — `truncated: false` is
+ * not a disclosure. What fails is a non-empty string that is not a redaction
+ * token, and an object standing where `--sanitize` would have put its
+ * `{ redacted }` stand-in.
+ *
+ * @param document - A parsed `opencode export` body (either variety)
+ * @returns Every field still readable. Empty means the document is redacted to
+ *   the extent 1.18.22 was measured to redact it
+ */
+function auditOpencodeExportRedaction(document) {
+    const leaks = [];
+    const sensitive = new Set(exports.OPENCODE_EXPORT_SENSITIVE_KEYS);
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            node.forEach((item, index) => walk(item, `${path}[${index}]`));
+            return;
+        }
+        if (typeof node !== 'object' || node === null)
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            const childPath = path === '' ? key : `${path}.${key}`;
+            if (sensitive.has(key)) {
+                if (value === null || value === undefined || value === '')
+                    continue;
+                if (isRedactedScalar(value) || isRedactedObject(value))
+                    continue;
+                if (typeof value === 'number' || typeof value === 'boolean')
+                    continue;
+                leaks.push({
+                    path: childPath,
+                    kind: typeof value === 'string' ? 'plaintext' : 'unredacted-object',
+                });
+                // Not descending: the whole subtree is suspect, and one entry per
+                // offending field reads better than one per leaf beneath it.
+                continue;
+            }
+            walk(value, childPath);
+        }
+    };
+    walk(document, '');
+    return leaks;
+}
+function readNumber(source, key) {
+    const value = source[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function readString(source, key) {
+    const value = source[key];
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Reduce a sanitized export to the facts it still carries.
+ *
+ * Reads defensively throughout: this parses the output of another program's
+ * `--sanitize` path, and a release that renames a field should cost the report
+ * that field rather than throw inside a summary generator.
+ *
+ * @param document - A parsed `opencode export --sanitize` body
+ * @returns The summary, or null when the document has no `info` object at all
+ */
+function summarizeOpencodeExport(document) {
+    const root = asRecord(document);
+    if (root === null)
+        return null;
+    const info = asRecord(root.info);
+    if (info === null)
+        return null;
+    const model = asRecord(info.model);
+    const providerId = model === null ? null : readString(model, 'providerID');
+    const modelId = model === null ? null : readString(model, 'id');
+    const time = asRecord(info.time);
+    let userMessages = 0;
+    let assistantMessages = 0;
+    let toolCalls = 0;
+    const tools = new Set();
+    const messages = Array.isArray(root.messages) ? root.messages : [];
+    for (const entry of messages) {
+        const message = asRecord(entry);
+        if (message === null)
+            continue;
+        const messageInfo = asRecord(message.info);
+        const role = messageInfo === null ? null : readString(messageInfo, 'role');
+        if (role === 'user')
+            userMessages += 1;
+        else if (role === 'assistant')
+            assistantMessages += 1;
+        const parts = Array.isArray(message.parts) ? message.parts : [];
+        for (const rawPart of parts) {
+            const part = asRecord(rawPart);
+            if (part === null)
+                continue;
+            if (readString(part, 'type') !== 'tool')
+                continue;
+            toolCalls += 1;
+            const tool = readString(part, 'tool');
+            if (tool !== null)
+                tools.add(tool);
+        }
+    }
+    return {
+        sessionId: readString(info, 'id'),
+        agent: readString(info, 'agent'),
+        model: providerId !== null && modelId !== null ? `${providerId}/${modelId}` : modelId,
+        version: readString(info, 'version'),
+        cost: readNumber(info, 'cost'),
+        userMessages,
+        assistantMessages,
+        tools: [...tools].sort(),
+        toolCalls,
+        createdAt: time === null ? null : readNumber(time, 'created'),
+        updatedAt: time === null ? null : readNumber(time, 'updated'),
+    };
+}

package/dist/server/src/types/opencode-instance-settings.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * What one opencode instance should be launched and prompted with (Issue #2048).
+ *
+ * Three values the operator chooses per agent instance — the persona, the model
+ * and the model's variant — and the vocabulary the settings UI, the API route,
+ * the database and the launcher all speak. It lives in `src/types` rather than
+ * beside the launcher because the settings pane is a `'use client'` component:
+ * anything it imports must not drag `fs` / `better-sqlite3` into the bundle.
+ *
+ * ## What each field can actually do, measured
+ *
+ * All three were measured against opencode **1.18.22** in an isolated `HOME`
+ * (`docs/design/opencode-server-live-verification.md` §20), and they are **not**
+ * interchangeable:
+ *
+ * | field       | TUI launch flag        | `prompt_async` body | reported back on |
+ * |-------------|------------------------|---------------------|------------------|
+ * | {@link agent}    | `--agent <name>` ✅ | `agent` ✅          | `message.updated.info.agent`, `Session.agent` |
+ * | provider/model   | `-m <p>/<m>` ✅     | `model` ✅          | `info.modelID` / `info.providerID` |
+ * | {@link variant}  | **none** ❌        | `variant` ✅        | `info.variant`, `Session.model.variant` |
+ *
+ * The empty cell is the one that matters. `--variant` exists on `opencode run`
+ * and **not** on the TUI: passing it to the TUI makes opencode print its usage
+ * and exit, so a launch line that carried it would leave the pane with no agent
+ * in it at all. `"agent": { "plan": { "variant": "high" } }` in `opencode.jsonc`
+ * was measured too and did not reach the turn either (`info.variant` absent). So
+ * the variant is applied where opencode does accept it — on the prompt this
+ * server posts — and the launch line never carries it.
+ *
+ * ## Why every value is pattern-checked rather than escaped
+ *
+ * `agent` and `provider`/`model` are interpolated into a **shell command line**
+ * by `prepareOpencodeLaunch`. The same argument `OPENCODE_SESSION_ID_PATTERN`
+ * makes applies verbatim: a value that reached the pane with a space or a quote
+ * in it would be a command injection into the operator's own terminal, and these
+ * values arrive over HTTP. Anything that does not match is refused, because
+ * there is no legitimate opencode id these patterns reject — the four providers
+ * measured publish ids like `claude-sonnet-4.6`, `qwen/qwen3-coder-30b` and
+ * `deepseek-v4-flash:0731`, which is where `/` and `:` come from.
+ *
+ * @module types/opencode-instance-settings
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_OPENCODE_LAUNCH_CATALOG = exports.EMPTY_OPENCODE_INSTANCE_SETTINGS = exports.OPENCODE_VARIANT_PATTERN = exports.OPENCODE_MODEL_ID_PATTERN = exports.OPENCODE_PROVIDER_ID_PATTERN = exports.OPENCODE_AGENT_NAME_PATTERN = void 0;
+exports.hasOpencodeInstanceSettings = hasOpencodeInstanceSettings;
+exports.normalizeOpencodeInstanceSettings = normalizeOpencodeInstanceSettings;
+exports.opencodeModelReference = opencodeModelReference;
+/**
+ * An opencode agent (persona) name, e.g. `build` / `plan`.
+ *
+ * `GET /agent` answered seven on a stock 1.18.22 install and every name was
+ * lower-case alphanumeric; the class is widened to `._-` for the user-defined
+ * agents an operator can add to their config, and no further.
+ */
+exports.OPENCODE_AGENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A provider id, e.g. `github-copilot` / `ollama-cloud` / `opencode`. */
+exports.OPENCODE_PROVIDER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * A model id, e.g. `claude-sonnet-4.6` / `qwen/qwen3-coder-30b` /
+ * `deepseek-v4-flash:0731`.
+ *
+ * `/` and `:` are in the class because measured ids contain them — LMStudio
+ * publishes `org/model` and Ollama Cloud publishes `model:tag`. Neither is a
+ * shell metacharacter, so widening the class here does not widen what can reach
+ * the command line.
+ */
+exports.OPENCODE_MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+/**
+ * A model variant, e.g. `low` / `medium` / `high` / `max` / `minimal` / `none` /
+ * `xhigh`.
+ *
+ * Not an enum: the names come from each model's own `variants` map in
+ * `GET /config/providers`, and the seven above are simply the ones the measured
+ * catalogue happened to contain. opencode does not validate the value either —
+ * a variant of `totally-not-a-variant` was accepted with `204` and echoed back
+ * verbatim on `message.updated.info.variant` (§20.6) — so this pattern is a
+ * bound on what this server will store and send, not a claim about what is real.
+ */
+exports.OPENCODE_VARIANT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+/** The all-unset settings object. Frozen so a caller cannot mutate the default. */
+exports.EMPTY_OPENCODE_INSTANCE_SETTINGS = Object.freeze({ agent: null, providerId: null, modelId: null, variant: null });
+/** Whether anything at all is configured. */
+function hasOpencodeInstanceSettings(settings) {
+    if (!settings)
+        return false;
+    return Boolean(settings.agent || settings.providerId || settings.modelId || settings.variant);
+}
+/** One value, checked against its pattern; anything else becomes null. */
+function acceptToken(value, pattern) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    return pattern.test(trimmed) ? trimmed : null;
+}
+/**
+ * Coerce an untrusted value into settings, dropping anything unusable.
+ *
+ * Field-by-field rather than all-or-nothing: a stored row written by a newer
+ * build, or a request body with one bad field, still yields the settings that
+ * *are* valid instead of silently reverting the instance to opencode's defaults.
+ *
+ * `providerId` and `modelId` are the one pair that stands or falls together —
+ * `-m` takes `provider/model` and half of that is not a model reference — so a
+ * lone half of the pair is dropped.
+ */
+function normalizeOpencodeInstanceSettings(input) {
+    if (typeof input !== 'object' || input === null) {
+        return { ...exports.EMPTY_OPENCODE_INSTANCE_SETTINGS };
+    }
+    const raw = input;
+    const providerId = acceptToken(raw.providerId, exports.OPENCODE_PROVIDER_ID_PATTERN);
+    const modelId = acceptToken(raw.modelId, exports.OPENCODE_MODEL_ID_PATTERN);
+    const paired = providerId !== null && modelId !== null;
+    return {
+        agent: acceptToken(raw.agent, exports.OPENCODE_AGENT_NAME_PATTERN),
+        providerId: paired ? providerId : null,
+        modelId: paired ? modelId : null,
+        variant: acceptToken(raw.variant, exports.OPENCODE_VARIANT_PATTERN),
+    };
+}
+/**
+ * `provider/model`, or null when the pair is not set.
+ *
+ * The spelling `-m` takes and the spelling `opencode models` prints, in one
+ * place so the launch line and the settings pane cannot disagree about it.
+ */
+function opencodeModelReference(settings) {
+    if (!settings?.providerId || !settings.modelId)
+        return null;
+    return `${settings.providerId}/${settings.modelId}`;
+}
+/** The empty catalogue — what a disconnected worktree answers. */
+exports.EMPTY_OPENCODE_LAUNCH_CATALOG = {
+    connected: false,
+    providers: [],
+    agents: [],
+};

package/dist/server/src/types/opencode-share.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * opencode session sharing — the config gate and the URL shape (Issue #2051)
+ *
+ * `POST /session/:id/share` publishes a conversation to opencode's own hosting
+ * under the operator's credentials, and the page it produces is readable by
+ * anyone who has the link. This module holds the two facts the rest of the app
+ * needs in order to decide whether that button may be offered at all, and both
+ * were measured against opencode 1.18.22 rather than read off the Issue —
+ * `docs/design/opencode-server-live-verification.md` §23.
+ *
+ * ## The gate is `share === 'disabled'`, and nothing else
+ *
+ * `GET /config` echoes a `share` key **only when the operator set one**. The
+ * OpenAPI `Config.share` schema is `enum: ["manual", "auto", "disabled"]`, and a
+ * server whose config file has no `share` key answers with the key **absent** —
+ * measured, not inferred. So `undefined` is *unset*, which is not the same
+ * answer as `"disabled"`, and treating the two alike would hide the button on
+ * every default installation.
+ *
+ * The reason this gate has to exist client-side at all is that the server does
+ * not offer a usable one. With `share: "disabled"` configured, `POST /share`
+ * answers **HTTP 500** with `{"name":"UnknownError","data":{"message":
+ * "Unexpected server error. Check server logs for details.","ref":"err_…"}}`.
+ * The real reason (`Error: Sharing is disabled in configuration`) appears only
+ * in the server's own log, and the response carries no code that tells it apart
+ * from any other 500. A caller cannot ask forgiveness here, only permission.
+ *
+ * ## What the returned URL looks like
+ *
+ * Measured: `https://opncd.ai/share/<last 8 characters of the session id>` —
+ * for `ses_fc35f3dadffe2uirJpjJBtxFhy`, `https://opncd.ai/share/jJBtxFhy`. The
+ * Issue body says `opncd.ai/s/<id>`; that spelling does not exist on 1.18.22.
+ * Nothing here hard-codes the host, because the server is the authority on the
+ * URL it minted and a later release may move it; the only requirement enforced
+ * is that it be an absolute `https:` URL, so that a malformed body cannot turn
+ * into a link the UI would render.
+ *
+ * ## Why `session.share` is not "is it shared right now"
+ *
+ * `DELETE /session/:id/share` really does take the page down (the public URL
+ * then renders opencode's own "Not Found" view), but the session record
+ * **keeps** its `share: { url }` afterwards — measured, and it survives a server
+ * restart, so it is persisted rather than cached. `session.share` therefore
+ * means *this session was published at some point*, and a UI that reads it as
+ * current state will report a revoked session as still shared for ever.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_SHARE_MODES = void 0;
+exports.readOpencodeShareMode = readOpencodeShareMode;
+exports.isOpencodeSharingDisabled = isOpencodeSharingDisabled;
+exports.readOpencodeShareUrl = readOpencodeShareUrl;
+/** The values opencode's `Config.share` accepts, from its own OpenAPI. */
+exports.OPENCODE_SHARE_MODES = ['manual', 'auto', 'disabled'];
+/**
+ * The `share` setting a `GET /config` body declares.
+ *
+ * @param config - A parsed `GET /config` body
+ * @returns The configured mode, or `null` when the key is absent or is a word
+ *   this opencode release added and this build does not know. `null` is *not*
+ *   `'disabled'`; see the module comment
+ */
+function readOpencodeShareMode(config) {
+    if (typeof config !== 'object' || config === null || Array.isArray(config))
+        return null;
+    const value = config.share;
+    if (typeof value !== 'string')
+        return null;
+    return exports.OPENCODE_SHARE_MODES.includes(value)
+        ? value
+        : null;
+}
+/**
+ * Whether this server would refuse to publish.
+ *
+ * Deliberately positive only for the one measured refusal. An unreadable
+ * config, an unreachable server and an unset key all answer `false` here, which
+ * lets the operator try; the failure they get back is a plain error, whereas a
+ * button that silently never appears is a feature that looks broken.
+ *
+ * @param mode - From {@link readOpencodeShareMode}
+ */
+function isOpencodeSharingDisabled(mode) {
+    return mode === 'disabled';
+}
+/**
+ * The share URL a `Session` body carries, if it carries a usable one.
+ *
+ * @param session - A parsed `Session` body, e.g. from `POST /session/:id/share`
+ * @returns An absolute `https:` URL, or null
+ */
+function readOpencodeShareUrl(session) {
+    if (typeof session !== 'object' || session === null || Array.isArray(session))
+        return null;
+    const share = session.share;
+    if (typeof share !== 'object' || share === null || Array.isArray(share))
+        return null;
+    const url = share.url;
+    if (typeof url !== 'string' || url === '')
+        return null;
+    // An absolute https URL or nothing: a relative or `javascript:` value reaching
+    // an anchor's href is the one way a malformed body becomes a UI defect.
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    return parsed.protocol === 'https:' ? url : null;
+}

package/dist/server/src/types/terminal-keys.js

@@ -19,7 +19,7 @@
  * Values only — no tmux process access — so this module is safe from any layer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NAVIGATION_KEY_VALUES = void 0;
+exports.TERMINAL_KEY_VALUES = exports.OPENCODE_NAVIGATION_KEY_VALUES = exports.OPENCODE_DIRECT_KEY_VALUES = exports.OPENCODE_LEADER_CHORD_VALUES = exports.OPENCODE_LEADER_KEY = exports.NAVIGATION_KEY_VALUES = void 0;
 /**
  * Navigation keys accepted by the special-keys API and the terminal UI.
  *
@@ -35,3 +35,71 @@ exports.NAVIGATION_KEY_VALUES = [
     // 'q' is the pager quit key (literal char). PageUp/PageDown/Home/End are tmux named keys.
     'PageUp', 'PageDown', 'Home', 'End', 'q',
 ];
+// ---------------------------------------------------------------------------
+// Per-tool vocabularies (Issue #2046)
+// ---------------------------------------------------------------------------
+/**
+ * opencode's leader prefix — the first half of a two-step chord.
+ *
+ * Measured, not assumed: opencode 1.18.22 ships `leader: "ctrl+x"` and
+ * `leader_timeout: 2000` as the defaults in its own binary, and a live TUI on a
+ * private tmux socket answered `C-x` + one letter at the 100 ms
+ * `SPECIAL_KEY_DELAY_MS` the transport already sends multi-key requests with
+ * (3/3 on `C-x` `a`). See `docs/design/opencode-server-live-verification.md` §22.
+ */
+exports.OPENCODE_LEADER_KEY = 'C-x';
+/**
+ * The letters that complete an opencode leader chord, in the order the quick-key
+ * strip renders them.
+ *
+ * These are LITERAL characters, not tmux key names — `tmux send-keys -- a` puts
+ * an `a` through, exactly as `q` has done for the codex pager since #1017. The
+ * one thing that makes them safe to hand to `tmux send-keys` is that they are
+ * fixed single characters chosen here, delivered through `execFile` and never a
+ * shell; the one thing that makes them safe to hand to *opencode* is that the
+ * route only accepts them for a tool that declares them (see
+ * `ICLITool.navigationKeys()`), so an `a` can never reach claude's composer.
+ *
+ * **`b` (`sidebar_toggle`) is deliberately absent.** It is a real opencode
+ * binding and it is the one this Issue measured and refused: §22.3.
+ */
+exports.OPENCODE_LEADER_CHORD_VALUES = [
+    'a', 'l', 'n', 't', 'm', 'g', 'u', 'r', 'c',
+];
+/**
+ * opencode keys that need no leader.
+ *
+ * `C-p` opens the command palette (opencode prints `ctrl+p commands` in its own
+ * footer) and `C-t` cycles the model variant — both confirmed live on 1.18.22.
+ * `Tab` / `BTab` cycle the agent and are already in {@link NAVIGATION_KEY_VALUES}.
+ */
+exports.OPENCODE_DIRECT_KEY_VALUES = ['C-p', 'C-t'];
+/**
+ * Everything an opencode pane may be sent — the base navigation pad plus this
+ * tool's own chords. Returned by `OpenCodeTool.navigationKeys()`.
+ */
+exports.OPENCODE_NAVIGATION_KEY_VALUES = [
+    ...exports.NAVIGATION_KEY_VALUES,
+    exports.OPENCODE_LEADER_KEY,
+    ...exports.OPENCODE_DIRECT_KEY_VALUES,
+    ...exports.OPENCODE_LEADER_CHORD_VALUES,
+];
+/**
+ * The union of every tool's vocabulary — what the tmux transport must be able to
+ * deliver.
+ *
+ * This is NOT what any single request is validated against. Since Issue #2046
+ * the special-keys route validates against the *declaring tool's* set
+ * (`ICLITool.navigationKeys()`), and this list exists so the transport's
+ * allow-list has one place to be checked against. The #2032 invariant is now
+ * stated per tool — every declared key must be deliverable — and
+ * `tests/unit/tmux/special-keys-allowlist-2032.test.ts` plus
+ * `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts` pin both
+ * halves.
+ */
+exports.TERMINAL_KEY_VALUES = [
+    ...exports.NAVIGATION_KEY_VALUES,
+    exports.OPENCODE_LEADER_KEY,
+    ...exports.OPENCODE_DIRECT_KEY_VALUES,
+    ...exports.OPENCODE_LEADER_CHORD_VALUES,
+];

package/dist/types/cli-tool-contracts.d.ts

@@ -13,6 +13,7 @@
  * `.eslintrc.json`'s `no-restricted-imports` rule exists to keep closed. Values
  * and types only — nothing here touches a process.
  */
+import type { TerminalKey } from './terminal-keys';
 /**
  * The key names a {@link KeySequence} step may name.
  *
@@ -103,6 +104,53 @@ export declare function isKeyStep(step: KeySequence): step is Extract<KeySequenc
  * refuses anything else rather than handing an unvalidated string to tmux.
  */
 export declare function isKeySequenceKeyName(name: string): name is KeySequenceKeyName;
+/**
+ * The keys one tool's UI may ask the special-keys API to deliver.
+ *
+ * Returned by `ICLITool.navigationKeys()`. Before Issue #2046 this was a single
+ * module-level list (`NAVIGATION_KEY_VALUES`) that `POST
+ * /api/worktrees/[id]/special-keys` validated EVERY request against, regardless
+ * of which tool the request named. That worked only while every tool wanted the
+ * same twelve keys. opencode does not: its TUI is driven by a `ctrl+x` leader
+ * plus a bare letter, and a bare letter is a character — `a` sent to claude's
+ * pane is an `a` typed into claude's composer, not a command.
+ *
+ * So the vocabulary moved into the tool, and the route now asks the tool it was
+ * given. 設計方針書 §6 ("tool-specific behaviour belongs in the tool class") is
+ * the same reason `describeComposer()` / `captureSpec()` / `gracefulExitSequence()`
+ * exist.
+ *
+ * ## The invariant this must not break (Issue #2032)
+ *
+ * Every key a tool declares must be one `sendSpecialKeys()` will actually hand
+ * to tmux. When the vocabulary was global that was stated as
+ * `NAVIGATION_KEY_VALUES` ⊆ `ALLOWED_SPECIAL_KEYS`; per tool it is the same
+ * statement quantified over the registry, and it is checked the same way —
+ * `isSendableSpecialKey()`. Breaking it restores exactly the #2032 failure: the
+ * route validates a request, answers nothing, and then throws inside the
+ * transport and reports 500.
+ */
+export interface NavigationKeySpec {
+    /**
+     * Every key name this tool's UI may send, including the leader prefix and any
+     * literal characters that complete a chord.
+     */
+    readonly keys: readonly TerminalKey[];
+    /**
+     * The prefix key of this tool's two-step chord, or `null` when it has none.
+     *
+     * opencode alone today (`C-x`, measured default of 1.18.22). The UI reads this
+     * instead of writing `C-x` next to every chord, so a tool whose leader differs
+     * — or a future opencode that renames it — changes one declaration.
+     *
+     * A chord is delivered as TWO array entries in one special-keys request
+     * (`['C-x', 'b']`), which `sendSpecialKeys()` sends one at a time with
+     * `SPECIAL_KEY_DELAY_MS` between them. That is the same sequential-step
+     * discipline `runKeySequence` applies to `KeySequence`, minus the literal/key
+     * distinction the special-keys transport does not have.
+     */
+    readonly leaderKey: TerminalKey | null;
+}
 /**
  * How a tool's input box is located on a captured frame.
  *

package/dist/types/cli-tool-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-tool-contracts.d.ts","sourceRoot":"","sources":["../../src/types/cli-tool-contracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-tool-contracts.d.ts","sourceRoot":"","sources":["../../src/types/cli-tool-contracts.ts"],"names":[],"mappings":"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"}