agent-tempo 1.0.1

package/dist/http/writes.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WRITE_ACTIONS = exports.WRITE_BODY_MAX = void 0;
+exports.isWriteAction = isWriteAction;
+exports.handleWriteRoute = handleWriteRoute;
+const responses_1 = require("./responses");
+const validation_1 = require("../utils/validation");
+const body_1 = require("./body");
+Object.defineProperty(exports, "WRITE_BODY_MAX", { enumerable: true, get: function () { return body_1.WRITE_BODY_MAX; } });
+/**
+ * Names of the write actions exposed under `/v1/ensembles/:ensemble/<action>`.
+ *
+ * Two semantic groups, kept in this order so the table reads top-to-bottom
+ * by surface intent:
+ * - **Ensemble-scoped** (cue / pause / play / release / recruit) — the
+ *   original PR-7a #340 surface; bodies don't carry `playerId`.
+ * - **Per-player destructive** (restart / destroy / detach / recall) —
+ *   added so the dashboard's PlayerDetail action row can wire to live
+ *   mutations. Bodies are uniform `{ playerId, reason? }` (plus per-action
+ *   extras); the ensemble lives in the URL.
+ */
+exports.WRITE_ACTIONS = [
+    'cue',
+    'pause',
+    'play',
+    'release',
+    'recruit',
+    'restart',
+    'destroy',
+    'detach',
+    'recall',
+];
+/** Type guard — narrows an arbitrary string to a known `WriteAction`. */
+function isWriteAction(s) {
+    return exports.WRITE_ACTIONS.includes(s);
+}
+/**
+ * Top-level dispatch — called from `server.ts` when the URL matches
+ * `/v1/ensembles/:ensemble/<action>` with a known `<action>`. The
+ * caller has already bearer/CORS-gated the request; this function
+ * trusts the gates and focuses on body parsing + per-action routing.
+ */
+async function handleWriteRoute(req, res, client, ensemble, action) {
+    if ((0, validation_1.validateEnsembleName)(ensemble) !== null) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'invalid-ensemble-name', ensemble });
+    }
+    // `pause` / `play` / `release` / `recruit` accept an empty body or a
+    // small JSON object; `cue` requires the `{ to, message }` body.
+    // Parse universally so unknown fields surface as clean 400s.
+    const body = await (0, body_1.readJsonBody)(req);
+    if (body === body_1.BODY_TOO_LARGE) {
+        return (0, responses_1.errorResponse)(res, 413, { error: 'body-too-large', limit: body_1.WRITE_BODY_MAX });
+    }
+    if (body === body_1.BODY_INVALID_JSON) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'invalid-json' });
+    }
+    try {
+        switch (action) {
+            case 'cue': return await handleCue(res, client, ensemble, body);
+            case 'pause': return await handlePause(res, client, ensemble);
+            case 'play': return await handlePlay(res, client, ensemble, body);
+            case 'release': return await handleRelease(res, client, ensemble, body);
+            case 'recruit': return await handleRecruit(res, client, ensemble, body);
+            case 'restart': return await handleRestart(res, client, ensemble, body);
+            case 'destroy': return await handleDestroy(res, client, ensemble, body);
+            case 'detach': return await handleDetach(res, client, ensemble, body);
+            case 'recall': return await handleRecall(res, client, ensemble, body);
+        }
+    }
+    catch (err) {
+        return mapWriteError(res, action, ensemble, err);
+    }
+}
+// ── Per-action handlers ──────────────────────────────────────────────────
+async function handleCue(res, client, ensemble, body) {
+    const to = (0, body_1.stringField)(body, 'to');
+    const message = (0, body_1.stringField)(body, 'message');
+    if (!to)
+        return (0, responses_1.errorResponse)(res, 400, { error: 'missing-field', field: 'to' });
+    if (!message)
+        return (0, responses_1.errorResponse)(res, 400, { error: 'missing-field', field: 'message' });
+    if ((0, validation_1.validatePlayerName)(to) !== null) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'invalid-player-name', field: 'to' });
+    }
+    if (message.length > validation_1.MESSAGE_MAX) {
+        return (0, responses_1.errorResponse)(res, 413, { error: 'message-too-long', limit: validation_1.MESSAGE_MAX });
+    }
+    // `sendAsMaestro` writes through the maestro session's outbox so the
+    // chat row shows `role: 'maestro-out'` — matches the dashboard's
+    // "you, the operator" semantic. `sendMessage` is conductor-sourced
+    // and would mis-label the row.
+    await client.ensureMaestroSession(ensemble);
+    await client.sendAsMaestro(ensemble, to, message);
+    (0, responses_1.jsonResponse)(res, 202, { ok: true, ensemble, to });
+}
+async function handlePause(res, client, ensemble) {
+    await client.pause(ensemble);
+    (0, responses_1.jsonResponse)(res, 202, { ok: true, ensemble });
+}
+async function handlePlay(res, client, ensemble, body) {
+    // `release` is opt-in; only forward when explicitly true so the client
+    // method's optional-prop signature stays meaningful.
+    const release = body.release === true;
+    const opts = release ? { release: true } : undefined;
+    await client.play(ensemble, opts);
+    (0, responses_1.jsonResponse)(res, 202, { ok: true, ensemble, released: release });
+}
+async function handleRelease(res, client, ensemble, body) {
+    const playerId = (0, body_1.stringField)(body, 'playerId');
+    if (playerId !== undefined && (0, validation_1.validatePlayerName)(playerId) !== null) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'invalid-player-name', field: 'playerId' });
+    }
+    const result = await client.release(ensemble, playerId);
+    (0, responses_1.jsonResponse)(res, 200, result);
+}
+async function handleRecruit(res, client, ensemble, body) {
+    const name = (0, body_1.stringField)(body, 'name');
+    const workDir = (0, body_1.stringField)(body, 'workDir');
+    if (!name)
+        return (0, responses_1.errorResponse)(res, 400, { error: 'missing-field', field: 'name' });
+    if (!workDir)
+        return (0, responses_1.errorResponse)(res, 400, { error: 'missing-field', field: 'workDir' });
+    if ((0, validation_1.validatePlayerName)(name) !== null) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'invalid-player-name', field: 'name' });
+    }
+    const agent = (0, body_1.stringField)(body, 'agent');
+    // Dev-mode parity with the MCP `recruit` tool: `'mock'` is only valid when
+    // `AGENT_TEMPO_DEV_MODE=1`. The mock adapter's registry registration is
+    // also dev-gated (ADR 0014 §7 gate 2); rejecting here gives a clearer 400
+    // than the registry's downstream "Unknown adapter" error.
+    const allowed = (0, body_1.allowedAgentsForCurrentMode)();
+    if (agent !== undefined && !(0, body_1.isAllowedAgent)(agent, allowed)) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'invalid-agent', allowed });
+    }
+    // Pluck each optional field once so the spread below doesn't run
+    // `stringField` twice per key.
+    const playerType = (0, body_1.stringField)(body, 'playerType');
+    const host = (0, body_1.stringField)(body, 'host');
+    const initialMessage = (0, body_1.stringField)(body, 'initialMessage');
+    const systemPrompt = (0, body_1.stringField)(body, 'systemPrompt');
+    const result = await client.recruit(ensemble, {
+        name,
+        workDir,
+        ...(agent !== undefined && (0, body_1.isAllowedAgent)(agent, allowed) ? { agent } : {}),
+        ...(playerType !== undefined ? { playerType } : {}),
+        ...(host !== undefined ? { host } : {}),
+        ...(initialMessage !== undefined ? { initialMessage } : {}),
+        ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+        ...(body.isConductor === true ? { isConductor: true } : {}),
+        ...(body.held === true ? { held: true } : {}),
+    });
+    (0, responses_1.jsonResponse)(res, 202, result);
+}
+// ── Per-player destructive actions ──────────────────────────────────────
+//
+// Each handler validates `playerId` (required) + optional `reason` and
+// shims to the matching TempoClient method. Body shape is uniform:
+// `{ playerId: string; reason?: string }`. Errors flow through
+// `mapWriteError` so a missing player surfaces as 404.
+async function handleRestart(res, client, ensemble, body) {
+    const playerId = (0, body_1.requirePlayerId)(res, body);
+    if (!playerId)
+        return;
+    // `reason` isn't part of `RestartClientOpts` (the client carries audit
+    // strings via `invokerPlayerId`); accepted in the body for consistency
+    // with the other player actions but currently a no-op pass-through.
+    // Surface remains future-compatible — if `reason` lands in
+    // RestartClientOpts later, the field is already accepted.
+    const result = await client.restart(ensemble, playerId);
+    (0, responses_1.jsonResponse)(res, 202, result);
+}
+async function handleDestroy(res, client, ensemble, body) {
+    const playerId = (0, body_1.requirePlayerId)(res, body);
+    if (!playerId)
+        return;
+    const reason = (0, body_1.stringField)(body, 'reason');
+    // Single-player destroy returns void — give the dashboard a stable
+    // shape to read (`{ ok: true, ensemble, playerId }`) so action-row
+    // mutations can confirm success without sniffing for `undefined`.
+    await client.destroy(ensemble, playerId, reason);
+    (0, responses_1.jsonResponse)(res, 202, { ok: true, ensemble, playerId });
+}
+async function handleDetach(res, client, ensemble, body) {
+    const playerId = (0, body_1.requirePlayerId)(res, body);
+    if (!playerId)
+        return;
+    // `reason` is accepted on the body for shape parity with the other
+    // per-player actions but the client method doesn't carry it (matches
+    // `restart`'s posture — future-compatible if the signature gains it).
+    //
+    // `detach` accepts `deadlineMs` (graceful drain window). Optional —
+    // TempoClient defaults when omitted. Strict-validate the type so
+    // proxy-stringified JSON values like `"8000"` fast-fail with a clean
+    // 400 instead of silently dropping into the default. Matches the
+    // strict body-validation philosophy at the file header.
+    let deadlineMs;
+    if (body.deadlineMs !== undefined) {
+        if (typeof body.deadlineMs !== 'number' || !Number.isFinite(body.deadlineMs)) {
+            return (0, responses_1.errorResponse)(res, 400, { error: 'invalid-field', field: 'deadlineMs' });
+        }
+        deadlineMs = body.deadlineMs;
+    }
+    await client.detach(ensemble, playerId, deadlineMs);
+    (0, responses_1.jsonResponse)(res, 202, { ok: true, ensemble, playerId });
+}
+async function handleRecall(res, client, ensemble, body) {
+    const playerId = (0, body_1.requirePlayerId)(res, body);
+    if (!playerId)
+        return;
+    // Recall is read-only (it returns the player's message timeline) but
+    // groups with the destructive actions for routing because the dashboard
+    // surfaces it on the same PlayerDetail action row. 200 (not 202)
+    // because the result is the operation, not a queued effect.
+    //
+    // The dashboard's `RecallResult` consumer expects a count, not the raw
+    // arrays — projecting `received` + `sent` lengths here keeps the wire
+    // payload tight and avoids leaking inbox + sent-history shape into the
+    // browser-side type. Callers wanting the full timeline use the MCP
+    // `recall` tool / TempoClient method directly.
+    const result = await client.recall(ensemble, playerId);
+    const messages = result.received.length + result.sent.length;
+    (0, responses_1.jsonResponse)(res, 200, { ok: true, ensemble, playerId, messages });
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Map a thrown error from a TempoClient call to an HTTP response.
+ * Recognises the "no session" / "no maestro" / "no ensemble" error
+ * messages the existing client throws and surfaces them as 404 so
+ * dashboard error UIs can show a meaningful message instead of a 500.
+ */
+function mapWriteError(res, action, ensemble, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/no session found|no maestro|workflow not found/i.test(message)) {
+        return (0, responses_1.errorResponse)(res, 404, { error: 'session-not-found', action, ensemble, detail: message });
+    }
+    if (/Unknown agent type/i.test(message)) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'unknown-agent-type', action, ensemble, detail: message });
+    }
+    return (0, responses_1.errorResponse)(res, 500, { error: 'write-failed', action, ensemble, detail: message });
+}

package/dist/palette/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Pure palette-input classification + filtering helpers.
+ *
+ * Shared between the TUI (`src/tui/commands.ts`) and the dashboard
+ * (`dashboard/src/components/chat/`) so the two surfaces' chat-input
+ * autocomplete machinery stays in lockstep — same prefix detection,
+ * same filtering semantics, same quote-aware tokenizer.
+ *
+ * Extracted from `src/tui/commands.ts` in #471/#472 (dashboard chat-input
+ * TUI parity bundle). The TUI re-exports every symbol from here so existing
+ * callers see no behaviour change. The dashboard imports directly from
+ * `agent-tempo/palette` (Vite alias `agent-tempo` → `../src`).
+ *
+ * **No imports allowed.** Keep this module dependency-free so it
+ * tree-shakes cleanly into the dashboard bundle and runs unmodified in
+ * any JS host (Node, browser, web workers). If you find yourself
+ * reaching for Temporal / MCP / Ink / React / DOM types here, the
+ * helper belongs somewhere else.
+ */
+export interface ParsedCommand {
+    /** Command name (without the leading slash). */
+    name: string;
+    /** Positional arguments after the command name. */
+    args: string[];
+    /** The original raw input string. */
+    raw: string;
+    /**
+     * #109: `true` when tokenization encountered an opening quote that never
+     * closed (e.g. user is mid-typing `/x "hello`). Strictly additive — existing
+     * handlers that don't inspect this field keep their forgiving-input behavior
+     * unchanged. Future strict-mode callers can opt in by checking the flag and
+     * surfacing an error sentinel before dispatch. Absent on well-formed input.
+     */
+    unterminatedQuote?: boolean;
+}
+/**
+ * Quote-aware tokenizer (#109). Splits on whitespace EXCEPT within balanced
+ * `"…"` or `'…'` runs. Backslash escapes are intentionally NOT supported —
+ * the command surface is small and escape handling adds failure modes
+ * (Windows paths mis-escaping, for example). Callers that need literal
+ * quotes inside an argument can use the other quote kind:
+ * `/x "with 'apostrophe'"`.
+ *
+ * Returns `{ tokens, unterminatedQuote }`:
+ *  - Well-formed input:  `unterminatedQuote === false`, all tokens split.
+ *  - Mid-typed input with an open quote (e.g. `/x "hello`): everything still
+ *    flushes as the final token and `unterminatedQuote === true` so downstream
+ *    strict callers can distinguish. The TUI's on-every-keystroke consumer
+ *    ignores the flag — forgiving input by design.
+ *
+ * Exported for unit tests; callers outside this module should use
+ * {@link parseCommand} which wraps this with slash-prefix validation and
+ * command-name lowercasing.
+ */
+export declare function tokenize(input: string): {
+    tokens: string[];
+    unterminatedQuote: boolean;
+};
+/**
+ * Parse raw input into a structured command.
+ * Returns null if input is not a slash command (doesn't start with "/").
+ *
+ * Uses the quote-aware {@link tokenize} helper so
+ * `/schedule create foo cron "0 * * * *"` correctly binds the cron
+ * expression as a single argument (#109). When the input has an
+ * unterminated quote (user mid-typing), the `unterminatedQuote` flag is
+ * surfaced on the returned ParsedCommand — existing callers that ignore
+ * it keep their pre-#109 forgiving behavior.
+ */
+export declare function parseCommand(input: string): ParsedCommand | null;
+/** Commands that take a player name as their first parameter. */
+export declare const PLAYER_PARAM_COMMANDS: ReadonlySet<string>;
+/**
+ * Commands with hardcoded subcommands (shown in autocomplete). Keys are
+ * command names without the leading slash; values are subcommand tokens
+ * the palette shows as completions for the first positional argument.
+ */
+export declare const SUBCOMMAND_MAP: Readonly<Record<string, readonly string[]>>;
+/** What the chat input is currently completing, if anything. */
+export type PaletteMode = 'command' | 'player' | 'player-arg';
+export interface PaletteContext {
+    mode: PaletteMode;
+    /** Lowercased partial token being completed (may be empty). */
+    partial: string;
+    /**
+     * Prefix of the current input that should be preserved when the user
+     * selects a palette item. The selected name is appended to this prefix.
+     * For `command`/`player` modes this is always `'/'` or `'@'`. For
+     * `player-arg` mode this is `/<cmd> ` (note trailing space).
+     */
+    replacePrefix: string;
+}
+/**
+ * Classify the current input for palette-autocomplete purposes.
+ *
+ * The palette is visible in three modes:
+ *   - `command`: user is typing `/` + partial command name (no space yet)
+ *   - `player` : user is typing `@` + partial player name (no space yet)
+ *   - `player-arg`: user typed a {@link PLAYER_PARAM_COMMANDS} command
+ *     followed by a space, and is now typing the first positional
+ *     argument (a player name)
+ *
+ * Returns `null` when the input does not match any palette-eligible shape
+ * (e.g. plain chat, or a second positional arg).
+ *
+ * Pure function — safe to call from React render and unit tests.
+ */
+export declare function classifyPaletteInput(raw: string): PaletteContext | null;
+/**
+ * Map a palette mode to the glyph prefix used when displaying or
+ * inserting an autofill selection.
+ *
+ *   `command` / `player-arg`  → `/`
+ *   `player`                  → `@`
+ *
+ * Centralising the mapping here means renderers (TUI's CommandPalette,
+ * dashboard's AutofillPopup) can't drift from the classifier. If a new
+ * mode lands, the compiler flags every consumer at once.
+ */
+export declare function modeToPrefix(mode: PaletteMode): '/' | '@';
+/**
+ * Filter palette command entries by a typed prefix.
+ * Prefix may optionally include a leading '/' — it's stripped before matching.
+ * An empty prefix returns all commands in order.
+ *
+ * Pure function — safe to call from React render paths and unit tests.
+ */
+export declare function filterPaletteCommands<T extends {
+    name: string;
+}>(commands: readonly T[], filter: string): T[];
+/**
+ * Filter a list of player names by a partial, using prefix + segment match
+ * (e.g. partial `co` matches `conductor` and `tempo-composer`). Exact
+ * matches are excluded (nothing left to complete).
+ *
+ * Pure function — safe to call from React render and unit tests.
+ */
+export declare function filterPlayerNames(names: readonly string[], partial: string): string[];

package/dist/palette/index.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * Pure palette-input classification + filtering helpers.
+ *
+ * Shared between the TUI (`src/tui/commands.ts`) and the dashboard
+ * (`dashboard/src/components/chat/`) so the two surfaces' chat-input
+ * autocomplete machinery stays in lockstep — same prefix detection,
+ * same filtering semantics, same quote-aware tokenizer.
+ *
+ * Extracted from `src/tui/commands.ts` in #471/#472 (dashboard chat-input
+ * TUI parity bundle). The TUI re-exports every symbol from here so existing
+ * callers see no behaviour change. The dashboard imports directly from
+ * `agent-tempo/palette` (Vite alias `agent-tempo` → `../src`).
+ *
+ * **No imports allowed.** Keep this module dependency-free so it
+ * tree-shakes cleanly into the dashboard bundle and runs unmodified in
+ * any JS host (Node, browser, web workers). If you find yourself
+ * reaching for Temporal / MCP / Ink / React / DOM types here, the
+ * helper belongs somewhere else.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBCOMMAND_MAP = exports.PLAYER_PARAM_COMMANDS = void 0;
+exports.tokenize = tokenize;
+exports.parseCommand = parseCommand;
+exports.classifyPaletteInput = classifyPaletteInput;
+exports.modeToPrefix = modeToPrefix;
+exports.filterPaletteCommands = filterPaletteCommands;
+exports.filterPlayerNames = filterPlayerNames;
+/**
+ * Quote-aware tokenizer (#109). Splits on whitespace EXCEPT within balanced
+ * `"…"` or `'…'` runs. Backslash escapes are intentionally NOT supported —
+ * the command surface is small and escape handling adds failure modes
+ * (Windows paths mis-escaping, for example). Callers that need literal
+ * quotes inside an argument can use the other quote kind:
+ * `/x "with 'apostrophe'"`.
+ *
+ * Returns `{ tokens, unterminatedQuote }`:
+ *  - Well-formed input:  `unterminatedQuote === false`, all tokens split.
+ *  - Mid-typed input with an open quote (e.g. `/x "hello`): everything still
+ *    flushes as the final token and `unterminatedQuote === true` so downstream
+ *    strict callers can distinguish. The TUI's on-every-keystroke consumer
+ *    ignores the flag — forgiving input by design.
+ *
+ * Exported for unit tests; callers outside this module should use
+ * {@link parseCommand} which wraps this with slash-prefix validation and
+ * command-name lowercasing.
+ */
+function tokenize(input) {
+    const tokens = [];
+    let cur = '';
+    let inSingle = false;
+    let inDouble = false;
+    // Tracks whether any char has been emitted into `cur` during the current
+    // token — needed so that an explicit empty string (`""`) becomes a real
+    // zero-length token rather than being collapsed with the surrounding
+    // whitespace boundary.
+    let hasContent = false;
+    const flush = () => {
+        if (cur.length > 0 || hasContent) {
+            tokens.push(cur);
+            cur = '';
+            hasContent = false;
+        }
+    };
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            hasContent = true;
+            continue;
+        }
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            hasContent = true;
+            continue;
+        }
+        if (/\s/.test(ch) && !inSingle && !inDouble) {
+            flush();
+            continue;
+        }
+        cur += ch;
+        hasContent = true;
+    }
+    flush();
+    return { tokens, unterminatedQuote: inSingle || inDouble };
+}
+/**
+ * Parse raw input into a structured command.
+ * Returns null if input is not a slash command (doesn't start with "/").
+ *
+ * Uses the quote-aware {@link tokenize} helper so
+ * `/schedule create foo cron "0 * * * *"` correctly binds the cron
+ * expression as a single argument (#109). When the input has an
+ * unterminated quote (user mid-typing), the `unterminatedQuote` flag is
+ * surfaced on the returned ParsedCommand — existing callers that ignore
+ * it keep their pre-#109 forgiving behavior.
+ */
+function parseCommand(input) {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith('/'))
+        return null;
+    const { tokens, unterminatedQuote } = tokenize(trimmed.slice(1));
+    if (tokens.length === 0)
+        return null;
+    const name = tokens[0].toLowerCase();
+    const args = tokens.slice(1);
+    return unterminatedQuote
+        ? { name, args, raw: trimmed, unterminatedQuote: true }
+        : { name, args, raw: trimmed };
+}
+// ── Palette classifier + filter helpers ──
+/** Commands that take a player name as their first parameter. */
+exports.PLAYER_PARAM_COMMANDS = new Set([
+    'worktree',
+    'restart',
+    'destroy',
+    'attachment-info',
+]);
+/**
+ * Commands with hardcoded subcommands (shown in autocomplete). Keys are
+ * command names without the leading slash; values are subcommand tokens
+ * the palette shows as completions for the first positional argument.
+ */
+exports.SUBCOMMAND_MAP = {
+    worktree: ['create', 'remove', 'list'],
+    stage: ['create', 'list', 'cancel'],
+    schedule: ['create', 'delete'],
+    lineup: ['load', 'save'],
+    ensemble: ['save', 'list', 'show'],
+};
+/**
+ * Classify the current input for palette-autocomplete purposes.
+ *
+ * The palette is visible in three modes:
+ *   - `command`: user is typing `/` + partial command name (no space yet)
+ *   - `player` : user is typing `@` + partial player name (no space yet)
+ *   - `player-arg`: user typed a {@link PLAYER_PARAM_COMMANDS} command
+ *     followed by a space, and is now typing the first positional
+ *     argument (a player name)
+ *
+ * Returns `null` when the input does not match any palette-eligible shape
+ * (e.g. plain chat, or a second positional arg).
+ *
+ * Pure function — safe to call from React render and unit tests.
+ */
+function classifyPaletteInput(raw) {
+    const trimmed = raw.trimStart();
+    if (!trimmed)
+        return null;
+    // Command-name completion: "/rec"
+    if (trimmed.startsWith('/') && !trimmed.includes(' ')) {
+        return { mode: 'command', partial: trimmed.slice(1).toLowerCase(), replacePrefix: '/' };
+    }
+    // @-player completion: "@al"
+    if (trimmed.startsWith('@') && !trimmed.includes(' ')) {
+        return { mode: 'player', partial: trimmed.slice(1).toLowerCase(), replacePrefix: '@' };
+    }
+    // Player-arg completion: "/restart co"
+    if (trimmed.startsWith('/') && trimmed.includes(' ')) {
+        const spaceIdx = trimmed.indexOf(' ');
+        const cmd = trimmed.slice(1, spaceIdx).toLowerCase();
+        const afterCmd = trimmed.slice(spaceIdx + 1);
+        // Only surface palette for the FIRST positional arg (no further space yet).
+        if (afterCmd.includes(' '))
+            return null;
+        if (exports.PLAYER_PARAM_COMMANDS.has(cmd)) {
+            return {
+                mode: 'player-arg',
+                partial: afterCmd.toLowerCase(),
+                replacePrefix: `/${cmd} `,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Map a palette mode to the glyph prefix used when displaying or
+ * inserting an autofill selection.
+ *
+ *   `command` / `player-arg`  → `/`
+ *   `player`                  → `@`
+ *
+ * Centralising the mapping here means renderers (TUI's CommandPalette,
+ * dashboard's AutofillPopup) can't drift from the classifier. If a new
+ * mode lands, the compiler flags every consumer at once.
+ */
+function modeToPrefix(mode) {
+    return mode === 'player' ? '@' : '/';
+}
+/**
+ * Filter palette command entries by a typed prefix.
+ * Prefix may optionally include a leading '/' — it's stripped before matching.
+ * An empty prefix returns all commands in order.
+ *
+ * Pure function — safe to call from React render paths and unit tests.
+ */
+function filterPaletteCommands(commands, filter) {
+    const prefix = filter.startsWith('/') ? filter.slice(1) : filter;
+    if (!prefix)
+        return [...commands];
+    const lower = prefix.toLowerCase();
+    return commands.filter((c) => c.name.toLowerCase().startsWith(lower));
+}
+/**
+ * Filter a list of player names by a partial, using prefix + segment match
+ * (e.g. partial `co` matches `conductor` and `tempo-composer`). Exact
+ * matches are excluded (nothing left to complete).
+ *
+ * Pure function — safe to call from React render and unit tests.
+ */
+function filterPlayerNames(names, partial) {
+    const lower = partial.toLowerCase();
+    if (!lower)
+        return [...names];
+    return names.filter((n) => {
+        const l = n.toLowerCase();
+        if (l === lower)
+            return false;
+        return l.startsWith(lower) || l.split('-').some((seg) => seg.startsWith(lower));
+    });
+}