@cspeach/cli 0.6.0

package/dist/tools/web/web_search.js

@@ -0,0 +1,195 @@
+// cspeach-cli/src/tools/web/web_search.ts
+/**
+ * web_search — Phase 3 / Chunk 3C2 web-search tool (Brave provider).
+ *
+ * Wraps Brave Search API to let the agent find SAP-relevant pages.
+ * Reuses _web-shared.validateUrl + DNS-pinned lookup for defense-in-depth
+ * on the api.search.brave.com endpoint — even with a hardcoded endpoint,
+ * validateUrl closes the DNS-hijack class of attack at zero extra design
+ * complexity.
+ *
+ * Auth: CSPEACH_BRAVE_SEARCH_KEY env var. Missing → structured setup
+ * instruction error, NOT an exception. Key is never logged or echoed
+ * in any error envelope.
+ *
+ * Operational caps:
+ *   - 10 s wall-clock timeout
+ *   - 256 KB streamed response cap
+ *   - Default 10 results, hard max 20 (Brave's per-query limit)
+ *
+ * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_WEB_SEARCH=on.
+ * isMutating: false — reads only.
+ */
+import * as https from 'node:https';
+import { registerTool } from '../index.js';
+import { validateUrl, BlockedHostError, BlockedProtocolError, MalformedUrlError, } from './_web-shared.js';
+export const BRAVE_ENDPOINT = 'https://api.search.brave.com/res/v1/web/search';
+export const USER_AGENT = 'cspeach/0.5 (+https://cspeach.dev)';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_RESPONSE_BYTES = 256_000;
+const DEFAULT_COUNT = 10;
+const MAX_COUNT = 20;
+export async function webSearchHandler(args, _ctx, opts = {}) {
+    // Input validation
+    if (!args.query || typeof args.query !== 'string' || args.query.trim().length === 0) {
+        return { content: 'error: query is required (non-empty string)', is_error: true };
+    }
+    const apiKey = process.env.CSPEACH_BRAVE_SEARCH_KEY;
+    if (!apiKey) {
+        return {
+            content: 'error: web_search requires CSPEACH_BRAVE_SEARCH_KEY. Get a free key at https://api.search.brave.com/app/keys and set CSPEACH_BRAVE_SEARCH_KEY=<your_key> in your environment.',
+            is_error: true,
+        };
+    }
+    const count = Math.min(Math.max(typeof args.count === 'number' && args.count > 0 ? Math.floor(args.count) : DEFAULT_COUNT, 1), MAX_COUNT);
+    const timeoutMs = opts._timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // Build the full endpoint URL with query parameters
+    const queryUrl = `${BRAVE_ENDPOINT}?q=${encodeURIComponent(args.query.trim())}&count=${count}`;
+    // Validate the endpoint URL through _web-shared (HTTPS + DNS pin)
+    let validated;
+    try {
+        validated = await validateUrl(queryUrl, { deps: opts._deps });
+    }
+    catch (err) {
+        if (err instanceof BlockedHostError || err instanceof BlockedProtocolError || err instanceof MalformedUrlError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // Make the request
+    const result = await fetchBrave(validated, apiKey, timeoutMs);
+    if (result.kind === 'error') {
+        // Sanity: scrub the API key from any error message in case it leaked
+        // through (shouldn't, but defense-in-depth — the test asserts this).
+        const message = result.message.split(apiKey).join('***');
+        return { content: `error: ${message}`, is_error: true };
+    }
+    // Non-2xx status → structured error
+    if (result.statusCode < 200 || result.statusCode >= 300) {
+        const bodyPreview = truncate(result.body, 1024);
+        // Scrub API key from error body (defense-in-depth)
+        const safePreview = bodyPreview.split(apiKey).join('***');
+        return {
+            content: `error: Brave API returned status ${result.statusCode}.\n${safePreview}`,
+            is_error: true,
+        };
+    }
+    // Parse the JSON
+    let parsed;
+    try {
+        parsed = JSON.parse(result.body);
+    }
+    catch (err) {
+        return {
+            content: `error: failed to parse Brave response JSON — ${err instanceof Error ? err.message : String(err)}`,
+            is_error: true,
+        };
+    }
+    const results = parsed.web?.results ?? [];
+    if (results.length === 0) {
+        return { content: `0 results for query "${args.query}".` };
+    }
+    // Format the result list for the agent
+    const lines = [`${results.length} result(s) for "${args.query}":`, ''];
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        lines.push(`${i + 1}. ${r.title ?? '(no title)'}`);
+        lines.push(`   ${r.url ?? '(no url)'}`);
+        if (r.description)
+            lines.push(`   ${truncate(r.description, 200)}`);
+        lines.push('');
+    }
+    return { content: lines.join('\n').trimEnd() };
+}
+function truncate(s, maxLen) {
+    if (s.length <= maxLen)
+        return s;
+    return s.slice(0, maxLen) + '… [truncated]';
+}
+async function fetchBrave(validated, apiKey, timeoutMs) {
+    return new Promise((resolve) => {
+        let buf = '';
+        let bufBytes = 0;
+        let truncated = false;
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(r);
+        };
+        const req = https.request({
+            method: 'GET',
+            hostname: validated.url.hostname,
+            port: validated.url.port ? Number(validated.url.port) : 443,
+            path: `${validated.url.pathname}${validated.url.search}`,
+            // https.request `lookup` field is typed `LookupFunction` whose
+            // opts parameter is `LookupOptions`; our pinnedLookup uses
+            // `LookupOneOptions`. The shapes are structurally compatible at
+            // runtime (we never set `all: true` so the single-address contract
+            // holds) — the cast bridges the @types/node strictness only.
+            lookup: validated.pinnedLookup,
+            headers: {
+                'X-Subscription-Token': apiKey,
+                Accept: 'application/json',
+                'Accept-Encoding': 'identity',
+                'User-Agent': USER_AGENT,
+            },
+        }, (res) => {
+            res.on('data', (chunk) => {
+                if (truncated)
+                    return;
+                const remaining = MAX_RESPONSE_BYTES - bufBytes;
+                if (remaining <= 0) {
+                    truncated = true;
+                    res.destroy?.();
+                    settle({ kind: 'response', statusCode: res.statusCode ?? 0, body: buf });
+                    return;
+                }
+                if (chunk.length <= remaining) {
+                    buf += chunk.toString('utf-8');
+                    bufBytes += chunk.length;
+                }
+                else {
+                    buf += chunk.slice(0, remaining).toString('utf-8');
+                    bufBytes += remaining;
+                    truncated = true;
+                    res.destroy?.();
+                    settle({ kind: 'response', statusCode: res.statusCode ?? 0, body: buf });
+                }
+            });
+            res.on('end', () => {
+                settle({ kind: 'response', statusCode: res.statusCode ?? 0, body: buf });
+            });
+            res.on('error', (err) => {
+                settle({ kind: 'error', message: `response stream error: ${err.message}` });
+            });
+        });
+        req.setTimeout(timeoutMs, () => {
+            settle({ kind: 'error', message: `timeout after ${timeoutMs} ms — request aborted` });
+            req.destroy();
+        });
+        req.on('error', (err) => {
+            settle({ kind: 'error', message: `request error: ${err.message}` });
+        });
+        req.end();
+    });
+}
+registerTool({
+    name: 'web_search',
+    description: 'Search the web via Brave Search API. Returns title + URL + description per result, up to 20 results. ' +
+        'Requires CSPEACH_BRAVE_SEARCH_KEY environment variable. ' +
+        'Defaults to 10 results; pass count to override (max 20).',
+    isMutating: false,
+    category: 'web',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Search query string. Required.' },
+            count: { type: 'number', description: 'Number of results to return. Default 10, max 20.' },
+        },
+        required: ['query'],
+    },
+    handler: (args, ctx) => webSearchHandler(args, ctx),
+});

package/dist/tools/write-mode.js

@@ -0,0 +1,22 @@
+/**
+ * Tools that mutate SAP-side state. Advisory mode short-circuits these;
+ * everything else (reads, quality checks, lock/snapshot control primitives)
+ * runs normally.
+ *
+ * Source of truth: ZCSPEACH SICF pivot spec §6.4 rows marked "W" (write).
+ * Does NOT include W-ctrl rows (lock/unlock/snapshot) because those are
+ * state-management primitives, not SAP data writes.
+ */
+export const WRITE_TOOLS = new Set([
+    'sap_create_object',
+    'sap_set_source',
+    'sap_update_method',
+    'sap_delete_object',
+    'sap_activate',
+    'sap_message_maintain',
+    'sap_service_binding_publish',
+    'sap_transport_release',
+]);
+export function isWriteTool(name) {
+    return WRITE_TOOLS.has(name);
+}

package/dist/ui/app.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { Box, useInput } from 'ink';
+import crypto from 'node:crypto';
+import { Header } from './header.js';
+import { Sidebar } from './sidebar.js';
+import { Body } from './body.js';
+import { Footer } from './footer.js';
+import { ApprovalModal } from './approval-modal.js';
+import { CommandPalette } from './command-palette.js';
+import { RichErrorBox } from './rich-error-box.js';
+import { SessionTimeline, toTimelineEntry } from './session-timeline.js';
+import { approvalEmitter } from './approval-emitter.js';
+import { errorEmitter } from './error-emitter.js';
+import { SapStateContext, globalStore } from './sap-state-store.js';
+import { coachingPickerEmitter } from './coaching-picker-emitter.js';
+import { CoachingPicker } from './widgets/coaching-picker.js';
+export function App({ chunkEmitter, onSubmit, onSlashTrigger, onHistoryTrigger, getToolCalls, writeMode }) {
+    // Approval-modal overlay state (H-new-4). Populated by approvalEmitter
+    // subscription; rendered as the last child so it overlays correctly.
+    const [pendingApproval, setPendingApproval] = useState(null);
+    const [coachingPending, setCoachingPending] = useState(null);
+    // Task 25: slash palette overlay state.
+    const [showPalette, setShowPalette] = useState(false);
+    const [paletteResult, setPaletteResult] = useState('');
+    // Task 27: error stack overlay state.
+    const [errorStack, setErrorStack] = useState([]);
+    // Task 29: session timeline overlay state.
+    const [showTimeline, setShowTimeline] = useState(false);
+    const [footerValue, setFooterValue] = useState('');
+    useEffect(() => {
+        const onReq = (req) => setPendingApproval(req);
+        approvalEmitter.on('request', onReq);
+        return () => {
+            approvalEmitter.off('request', onReq);
+        };
+    }, []);
+    useEffect(() => {
+        const onRequest = (req) => {
+            setCoachingPending(req);
+        };
+        coachingPickerEmitter.on('request', onRequest);
+        return () => {
+            coachingPickerEmitter.off('request', onRequest);
+        };
+    }, []);
+    useEffect(() => {
+        const onError = (err) => {
+            const id = crypto.randomUUID();
+            setErrorStack((s) => [...s, { ...err, id }]);
+            setTimeout(() => {
+                setErrorStack((s) => s.filter((e) => e.id !== id));
+            }, 5000);
+        };
+        errorEmitter.on('error', onError);
+        return () => { errorEmitter.off('error', onError); };
+    }, []);
+    // `?` key opens the timeline when the footer is empty and no other overlay
+    // is active. Gating ensures TextInput captures `?` as a literal character
+    // when the user is typing.
+    useInput((input, _key) => {
+        if (input === '?' && footerValue === '')
+            setShowTimeline(true);
+    }, { isActive: !showPalette && !showTimeline && !pendingApproval && !coachingPending });
+    const clearApproval = () => setPendingApproval(null);
+    const handleSlashTrigger = () => {
+        setShowPalette(true);
+        onSlashTrigger?.();
+    };
+    const handleHistoryTrigger = () => {
+        setShowTimeline(true);
+        onHistoryTrigger?.();
+    };
+    const timelineEntries = showTimeline && getToolCalls
+        ? getToolCalls()
+            .filter((c) => c.completed === true)
+            .map(toTimelineEntry)
+        : [];
+    return (_jsx(SapStateContext.Provider, { value: globalStore, children: _jsxs(Box, { flexDirection: "column", height: "100%", children: [_jsx(Header, { writeMode: writeMode }), _jsxs(Box, { flexDirection: "row", flexGrow: 1, children: [_jsx(Body, { chunkEmitter: chunkEmitter }), _jsx(Sidebar, {})] }), _jsx(Footer, { onSubmit: onSubmit, onSlashTrigger: handleSlashTrigger, onHistoryTrigger: handleHistoryTrigger, paletteResult: paletteResult, onValueChange: setFooterValue }), showPalette && (_jsx(Box, { position: "absolute", marginTop: 1, marginLeft: 2, children: _jsx(CommandPalette, { onSelect: (s) => {
+                            setPaletteResult(s);
+                            setShowPalette(false);
+                        }, onCancel: () => setShowPalette(false) }) })), errorStack.map((e, i) => (_jsx(Box, { position: "absolute", marginTop: i * 6, children: _jsx(RichErrorBox, { code: e.code, message: e.body, hint: e.hint, severity: "error" }) }, e.id))), showTimeline && (_jsx(Box, { position: "absolute", marginTop: 1, marginLeft: 2, children: _jsx(SessionTimeline, { entries: timelineEntries, onClose: () => setShowTimeline(false) }) })), coachingPending && (_jsx(Box, { position: "absolute", marginTop: 2, marginLeft: 2, children: _jsx(CoachingPicker, { params: coachingPending.params, onResolve: (result) => {
+                            coachingPending.resolve(result);
+                            setCoachingPending(null);
+                        } }) })), pendingApproval && (_jsx(Box, { position: "absolute", marginTop: 2, marginLeft: 2, children: _jsx(ApprovalModal, { change: pendingApproval.change, effectiveRisk: pendingApproval.effectiveRisk, transport: pendingApproval.transport, onApply: () => {
+                            pendingApproval.resolve({ approved: true });
+                            clearApproval();
+                        }, onSkip: () => {
+                            pendingApproval.resolve({ approved: false, reason: 'skipped' });
+                            clearApproval();
+                        }, onDiff: () => { }, onCancel: () => {
+                            pendingApproval.resolve({ approved: false, reason: '__cancel_turn__' });
+                            clearApproval();
+                        } }) }))] }) }));
+}

package/dist/ui/approval-emitter.js

@@ -0,0 +1,10 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Singleton request channel from `approvals/render.ts` (producer) to `<App>`
+ * (consumer). App subscribes in a useEffect and pushes the request into its
+ * `pendingApproval` state to render `<ApprovalModal>` as an overlay.
+ *
+ * Never spawn a sibling Ink root for the modal — that fights the main <App>
+ * for stdout and corrupts the Ink frame.
+ */
+export const approvalEmitter = new EventEmitter();

package/dist/ui/approval-modal.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+const LABEL_MAP = {
+    delete_op: 'delete op detected',
+    prod_namespace: 'PROD namespace',
+    shared_transport: 'transport shared by 3+ devs',
+    atc_failed_24h: 'ATC failed in last 24h',
+    non_prod_override: 'auto-approve policy: never',
+    escalated_in_session: '>5 changes this session',
+};
+function opIcon(op) {
+    const icons = { create: 'A', modify: 'M', delete: 'D', activate: '>', release: '^' };
+    return icons[op] ?? '?';
+}
+function riskColor(level) {
+    return level === 'high' ? 'red' : level === 'medium' ? 'yellow' : 'green';
+}
+export function ApprovalModal({ change, effectiveRisk, transport, onApply, onSkip, onDiff, onCancel }) {
+    const [showingDiff, setShowingDiff] = useState(false);
+    useInput((input, key) => {
+        if (showingDiff) {
+            if (key.escape) {
+                setShowingDiff(false);
+            }
+            return;
+        }
+        if (input === 'a' || input === 'y') {
+            onApply();
+            return;
+        }
+        if (input === 's' || input === 'n') {
+            onSkip();
+            return;
+        }
+        if (input === 'd') {
+            setShowingDiff(true);
+            onDiff();
+            return;
+        }
+        if (input === 'c' || key.escape) {
+            onCancel();
+            return;
+        }
+    });
+    if (showingDiff && change.diff) {
+        return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, children: "Diff \\u2014 Esc to return" }), change.diff.split('\n').map((line, i) => (_jsx(Text, { color: line.startsWith('+') ? 'green' : line.startsWith('-') ? 'red' : 'gray', children: line }, i)))] }));
+    }
+    const raisedLabel = effectiveRisk.raisedBy
+        .map((r) => LABEL_MAP[r] ?? r)
+        .join(', ');
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: riskColor(effectiveRisk.level), paddingX: 2, paddingY: 1, children: [_jsx(Text, { bold: true, children: "Approval requested" }), _jsxs(Box, { marginTop: 1, children: [_jsxs(Text, { bold: true, color: riskColor(effectiveRisk.level), children: [" ", opIcon(change.op), " "] }), _jsx(Text, { bold: true, children: change.object }), _jsxs(Text, { color: "gray", children: [" (", change.type, ")"] })] }), _jsxs(Text, { color: riskColor(effectiveRisk.level), children: ["Risk: ", effectiveRisk.level, raisedLabel ? `  (raised from low: ${raisedLabel})` : ''] }), transport && _jsxs(Text, { color: "gray", children: ["Transport: ", transport] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { children: "[a] Apply   [d] Show diff" }), _jsx(Text, { children: "[s] Skip    [c] Cancel turn" })] })] }));
+}

package/dist/ui/ascii-chars.js

@@ -0,0 +1,6 @@
+import { shouldUseUnicodeBoxChars } from '../renderer/tty.js';
+export const UNICODE_BOX = { tl: '\u256D', tr: '\u256E', bl: '\u2570', br: '\u256F', h: '\u2500', v: '\u2502' };
+export const ASCII_BOX = { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|' };
+export function getBoxChars() {
+    return shouldUseUnicodeBoxChars() ? UNICODE_BOX : ASCII_BOX;
+}

package/dist/ui/body.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { useReducer, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { WIDGET_COMPONENTS } from './widgets/component-registry.js';
+import { WIDGET_CONTROL } from './widget-control.js';
+// WIDGET_CONTROL is the longer sentinel (`\x00CSPEACH-WIDGET-V3\x00`) — see M2.
+// RegExp escaping: `\x00` works in JS regex source directly.
+const WIDGET_RE = new RegExp(WIDGET_CONTROL.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+    '(\\d+):(\\w[\\w-]*):([\\w+/=]+)' +
+    WIDGET_CONTROL.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g');
+// Eviction caps (H-new-1).
+const MAX_NODES = 500;
+const MAX_TEXT_LEN = 100_000;
+export const INITIAL_BODY_STATE = { nodes: [], pending: '', nextId: 0, totalTextLen: 0 };
+/**
+ * Parse an incremental chunk into a list of new nodes + any unterminated tail
+ * that should stay in `pending`. Only the NEW content (pending + chunk) is
+ * scanned — previously-parsed nodes are never re-regexed.
+ */
+function parseIncremental(pending, chunk) {
+    const combined = pending + chunk;
+    // If an unterminated WIDGET_CONTROL appears at the tail, defer from that point.
+    const lastOpenerIdx = combined.lastIndexOf(WIDGET_CONTROL);
+    let scannable = combined;
+    let nextPending = '';
+    if (lastOpenerIdx !== -1) {
+        // Check whether there's a matching closer after it.
+        const afterOpener = combined.slice(lastOpenerIdx + WIDGET_CONTROL.length);
+        if (!afterOpener.includes(WIDGET_CONTROL)) {
+            // Unterminated — buffer from the opener onwards.
+            scannable = combined.slice(0, lastOpenerIdx);
+            nextPending = combined.slice(lastOpenerIdx);
+        }
+    }
+    const newNodes = [];
+    const parts = scannable.split(WIDGET_RE);
+    // split with 3 groups produces 4 slots per widget: [text, idx, type, b64, text, ...]
+    for (let i = 0; i < parts.length; i++) {
+        const mod = i % 4;
+        if (mod === 0) {
+            if (parts[i])
+                newNodes.push({ kind: 'text', value: parts[i] });
+        }
+        else if (mod === 1) {
+            const wType = (parts[i + 1] ?? '');
+            const b64 = parts[i + 2] ?? '';
+            try {
+                const data = JSON.parse(Buffer.from(b64, 'base64').toString());
+                if (WIDGET_COMPONENTS[wType]) {
+                    newNodes.push({ kind: 'widget', widgetType: wType, data });
+                }
+                else {
+                    newNodes.push({ kind: 'widget-error' });
+                }
+            }
+            catch {
+                newNodes.push({ kind: 'widget-error' });
+            }
+            i += 2; // skip type + b64; loop's i++ advances past last captured group
+        }
+    }
+    return { newNodes, nextPending };
+}
+export function bodyReducer(state, action) {
+    const { newNodes, nextPending } = parseIncremental(state.pending, action.chunk);
+    let id = state.nextId;
+    let totalTextLen = state.totalTextLen;
+    const appended = newNodes.map((n) => {
+        const withId = { ...n, id: id++ };
+        if (withId.kind === 'text')
+            totalTextLen += withId.value.length;
+        return withId;
+    });
+    let nodes = state.nodes.concat(appended);
+    // Sliding-window eviction: drop oldest nodes until both caps satisfied.
+    while (nodes.length > MAX_NODES || totalTextLen > MAX_TEXT_LEN) {
+        const [evicted, ...rest] = nodes;
+        if (!evicted)
+            break;
+        if (evicted.kind === 'text')
+            totalTextLen -= evicted.value.length;
+        nodes = rest;
+    }
+    return { nodes, pending: nextPending, nextId: id, totalTextLen };
+}
+export const Body = React.memo(function Body({ chunkEmitter }) {
+    const [state, dispatch] = useReducer(bodyReducer, INITIAL_BODY_STATE);
+    useEffect(() => {
+        const handler = (chunk) => dispatch({ chunk });
+        chunkEmitter.on('chunk', handler);
+        return () => { chunkEmitter.off('chunk', handler); };
+    }, [chunkEmitter]);
+    return (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: state.nodes.map((n) => {
+            if (n.kind === 'text')
+                return _jsx(Text, { children: n.value }, n.id);
+            if (n.kind === 'widget') {
+                const Comp = WIDGET_COMPONENTS[n.widgetType];
+                return _jsx(Comp, { data: n.data }, n.id);
+            }
+            return _jsx(Text, { color: "yellow", children: "\\u26A0 widget render error" }, n.id);
+        }) }));
+});

package/dist/ui/coaching-picker-classic.js

@@ -0,0 +1,36 @@
+import { select } from '@inquirer/prompts';
+import { PICK_CANCELLED } from './skill-picker.js';
+const CANCEL_VALUE = '__cancel__';
+/**
+ * Classic-mode coaching picker via inquirer's select prompt. Each choice shows
+ * a single-line `name` (skill + confidence %) in the list; the "Does:" and
+ * "Pick if:" sub-lines appear under the highlighted entry via `description`.
+ * Cancel entry always present at the bottom.
+ *
+ * Ink-mode has a separate implementation — see src/ui/widgets/coaching-picker.tsx.
+ */
+export async function coachingPickerClassic(params) {
+    const choices = params.options.map((opt) => ({
+        name: `/${opt.skill} · ${Math.round(opt.confidence * 100)}%`,
+        value: opt.skill,
+        description: `  Does: ${opt.whatItDoes}\n  Pick if: ${opt.whenToPick}`,
+    }));
+    choices.push({
+        name: '↩ cancel (go back to prompt)',
+        value: CANCEL_VALUE,
+    });
+    const message = `I'm not sure which skill fits for: "${params.prompt.slice(0, 50)}${params.prompt.length > 50 ? '...' : ''}". Pick one:`;
+    const defaultValue = params.preSelect && params.options.length > 0 ? params.options[0].skill : undefined;
+    try {
+        const chosen = await select({ message, choices, default: defaultValue });
+        if (chosen === CANCEL_VALUE)
+            return PICK_CANCELLED;
+        return chosen;
+    }
+    catch (err) {
+        const name = err?.name;
+        if (name === 'ExitPromptError')
+            return PICK_CANCELLED;
+        throw err;
+    }
+}

package/dist/ui/coaching-picker-emitter.js

@@ -0,0 +1,27 @@
+import { EventEmitter } from 'node:events';
+import { PICK_CANCELLED } from './skill-picker.js';
+/**
+ * EventEmitter subclass with a request() helper that returns a Promise
+ * resolved from the overlay's onResolve callback. Deliberately different
+ * shape from approvalEmitter (which is a bare EventEmitter with request()
+ * living elsewhere) — keeping the request contract self-contained in
+ * this file makes the coaching flow easier to reason about cross-callers.
+ * See spec §5.2 for rationale.
+ */
+class CoachingPickerEmitter extends EventEmitter {
+    request(params) {
+        return new Promise((resolve) => {
+            // Defensive: if App hasn't mounted the overlay listener yet (e.g. pre-
+            // render race during startup, or caller invokes outside Ink mode), resolve
+            // immediately with PICK_CANCELLED rather than hang forever. Real usage
+            // always has exactly one listener attached by App.tsx's useEffect.
+            if (this.listenerCount('request') === 0) {
+                resolve(PICK_CANCELLED);
+                return;
+            }
+            const request = { params, resolve };
+            this.emit('request', request);
+        });
+    }
+}
+export const coachingPickerEmitter = new CoachingPickerEmitter();

package/dist/ui/command-palette.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect, useMemo } from 'react';
+import { Box, Text, useInput } from 'ink';
+import TextInput from 'ink-text-input';
+import Fuse from 'fuse.js';
+import { SKILL_CATALOG } from '../skill-catalog.js';
+export function CommandPalette({ onSelect, onCancel }) {
+    const [query, setQuery] = useState('');
+    const [cursor, setCursor] = useState(0);
+    const fuse = useMemo(() => new Fuse(SKILL_CATALOG, { keys: ['name', 'description'], threshold: 0.4 }), []);
+    const results = useMemo(() => query
+        ? fuse.search(query).slice(0, 8).map((r) => r.item)
+        : SKILL_CATALOG.slice(0, 8), [query, fuse]);
+    useEffect(() => { setCursor(0); }, [query]);
+    useInput((_input, key) => {
+        if (key.escape) {
+            onCancel();
+            return;
+        }
+        if (key.upArrow) {
+            setCursor((c) => Math.max(0, c - 1));
+            return;
+        }
+        if (key.downArrow) {
+            setCursor((c) => Math.min(results.length - 1, c + 1));
+            return;
+        }
+        if (key.return && results[cursor]) {
+            onSelect(`/${results[cursor].name} `);
+            return;
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 2, paddingY: 1, width: 60, children: [_jsx(Text, { bold: true, color: "cyan", children: "Command palette" }), _jsx(TextInput, { value: query, onChange: setQuery, placeholder: "Type to filter..." }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: results.map((skill, i) => (_jsxs(Box, { children: [_jsxs(Text, { color: i === cursor ? 'cyan' : 'white', bold: i === cursor, children: [i === cursor ? '\u25B8' : ' ', " /", skill.name.padEnd(20)] }), _jsx(Text, { dimColor: true, children: skill.description })] }, skill.name))) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "Enter: insert  Esc: cancel" }) })] }));
+}

package/dist/ui/error-emitter.js

@@ -0,0 +1,21 @@
+import { EventEmitter } from 'node:events';
+import { shouldUseInk } from '../renderer/tty.js';
+import chalk from 'chalk';
+export const errorEmitter = new EventEmitter();
+/**
+ * Emit an error. In Ink mode, the main App subscribes and pushes the error
+ * into its errorStack state for overlay rendering. In non-TTY / one-shot,
+ * we fall back to chalk.red on stderr — never mount a second Ink root.
+ */
+export function emitError(err) {
+    if (shouldUseInk()) {
+        errorEmitter.emit('error', err);
+    }
+    else {
+        console.error(chalk.red(`[${err.code}] ${err.title}`));
+        if (err.body)
+            console.error(chalk.red(`  ${err.body}`));
+        if (err.hint)
+            console.error(chalk.dim(`  ${err.hint}`));
+    }
+}