@itookit/dsht 0.3.7 → 0.5.1

package/dist/slash/registry.js

@@ -0,0 +1,177 @@
+/** Command discovery catalog shared by Tab completion and the `/help` panel. */
+export const COMMAND_HINTS = [
+    { command: '/ws', usage: '[name or ID]', description: 'List/switch workspaces; --delete name removes registration' },
+    { command: '/resume', usage: '[title or ID]', description: 'List/switch sessions; --delete ID archives with confirmation' },
+    { command: '/model', usage: '[provider model [effort]]', description: 'Choose a model and reasoning effort for subsequent requests' },
+    { command: '/new', description: 'Create a session in the selected workspace' },
+    { command: '/copy', description: 'Freeze for native selection; Esc resumes (Ctrl+S shortcut)' },
+    { command: '/latest', description: 'Return to the live conversation' },
+    { command: '/older', description: 'Load earlier history' },
+    { command: '/history', usage: '[text]', description: 'List your prompts, optionally filtered' },
+    { command: '/prompt', usage: '[text]', description: 'Use a saved shortcut prompt, or save the text as one' },
+    { command: '/search', usage: 'text', description: 'Search history page by page and open a match' },
+    { command: '/ssearch', usage: 'text', description: 'Search sessions in the current workspace' },
+    { command: '/wsearch', usage: 'text', description: 'Search sessions across all workspaces' },
+    { command: '/compact', description: 'Compact older history while the session is idle' },
+    { command: '/cancel', description: 'Cancel the active turn' },
+    { command: '/queue', description: 'View and remove pending input' },
+    { command: '/plan', usage: '[off|message]', description: 'Enter or leave host plan mode' },
+    { command: '/goal', usage: '[action|objective]', description: 'View or manage the host task goal' },
+    { command: '/permission', usage: '[preset]', description: 'View or switch the host permission preset' },
+    { command: '/feedback', usage: 'text', description: 'Record feedback about the session' },
+    { command: '/handoff', description: 'Delete local HANDOFF.md, then have the agent write a handoff' },
+    { command: '/loop', usage: '[name|stop] [score] [tries]', description: 'Run a loop.yaml record; confirm defaults; stop/answer/abort', exactOnly: true },
+    { command: '/export', usage: '[local.zip]', description: 'Save the session log ZIP to a new local file' },
+    { command: '/export-html', usage: '[local.html]', description: 'Save loaded conversation with diagrams and math as offline HTML' },
+    { command: '/coredump', usage: '[tag]', description: 'Write a V8 heap snapshot for memory diagnosis' },
+    { command: '/allow', description: 'Approve the pending request once', exactOnly: true },
+    { command: '/deny', description: 'Reject the pending request', exactOnly: true },
+    { command: '/status', description: 'Show full session status details' },
+    { command: '/cost', description: 'Show cost estimates and refresh usage' },
+    { command: '/think', usage: '[seq or live]', description: 'Inspect reasoning with user prompt summaries' },
+    { command: '/help', description: 'Show this command list' },
+    { command: '/quit', description: 'Exit dsht', exactOnly: true },
+];
+/** Command names only, in catalog order. */
+export const COMMANDS = COMMAND_HINTS.map(hint => hint.command);
+/** Command column text per hint, aligned in the `/help` panel. */
+export const COMMAND_LABELS = COMMAND_HINTS.map(hint => hint.usage === undefined ? hint.command : `${hint.command} ${hint.usage}`);
+/** Widest command column, so descriptions start on one column. */
+export const COMMAND_LABEL_WIDTH = Math.max(...COMMAND_LABELS.map(label => label.length)) + 2;
+/** Commands that may only run when typed in full; a prefix of one is never executed on Enter. */
+const EXACT_ONLY = new Set(COMMAND_HINTS.filter(hint => hint.exactOnly).map(hint => hint.command));
+/** Commands whose name starts with one token, in catalog order.
+ * @param token - First word of a draft, such as `/pro`.
+ * @returns Matching command names, empty when the token names nothing.
+ */
+export function commandMatches(token) {
+    return COMMANDS.filter(command => command.startsWith(token));
+}
+/** Resolve one typed command token to the command it names.
+ *
+ * An exact command resolves to itself. A prefix that matches exactly one command resolves to that
+ * command too, so Enter can run it without typing the whole name; an unknown or ambiguous token,
+ * and any prefix of an `exactOnly` command, resolves to undefined so the draft stays as typed.
+ * @param token - First word of a draft, without its arguments.
+ * @returns The command name, or undefined when the token does not name one command.
+ */
+export function resolveCommand(token) {
+    if (COMMANDS.includes(token))
+        return token;
+    const matches = commandMatches(token);
+    const only = matches.length === 1 ? matches[0] : undefined;
+    return only !== undefined && !EXACT_ONLY.has(only) ? only : undefined;
+}
+/** Routing policy per parsed command kind.
+ *
+ * The pipeline reads this table instead of enumerating kinds itself, so a new command declares its
+ * constraints next to its syntax and no other module learns about it. A kind absent here has no
+ * constraint and may run from any screen, even while an answer is pending.
+ */
+/** A command that would write to the conversation another turn is already writing.
+ *
+ * `compact`, `handoff` and a `/loop` run each submit work of their own to the same session, so starting
+ * one mid-turn would interleave two writers on one conversation. The list is deliberately short: the
+ * host owns the busy rules of its own commands (`/plan`, `/goal`, `/model`, …), and a client-side deny
+ * there would contradict what the host would have accepted.
+ */
+/** A command that writes to the conversation another turn is writing: it runs when that turn ends.
+ *
+ * These are the operator's own commands — a compaction, a handoff, a review to start — and refusing
+ * them outright would make "I want this next" impossible to express while an agent works.
+ */
+const QUEUES_WHILE_RUNNING = { duringTurn: 'queue', duringLoop: 'queue' };
+/** A command that must not run while another turn or loop owns the conversation at all. */
+const CONFLICTS_WITH_RUNNING = { duringTurn: 'deny', duringLoop: 'deny' };
+/** Commands that answer the operator or the host and must reach the session while it is busy.
+ *
+ * `whileBusy: 'run'` is the foreground-slot equivalent: cancelling an agent turn or settling the
+ * interaction holding it is independent of whatever long operation the client is showing, and the
+ * operator must never be told to wait for an export before they can stop the agent.
+ */
+const ANSWERS_WHILE_RUNNING = { duringTurn: 'run', duringLoop: 'run' };
+const ANSWERS_WHILE_BUSY = { whileBusy: 'run' };
+export const COMMAND_POLICY = {
+    shell: { requiresSession: true },
+    models: { requiresSession: true },
+    queue: { requiresSession: true, requiresNoInteraction: true },
+    history: { requiresSession: true },
+    historySearch: { requiresSession: true },
+    prompts: { requiresSession: true },
+    // Reading reasoning while the agent works is the point of the panel.
+    think: { requiresSession: true, ...ANSWERS_WHILE_RUNNING },
+    panel: { ...ANSWERS_WHILE_RUNNING },
+    copy: { ...ANSWERS_WHILE_RUNNING },
+    // Cancelling the turn, or settling the interaction that is holding it, must never be refused.
+    cancel: { ...ANSWERS_WHILE_RUNNING, ...ANSWERS_WHILE_BUSY },
+    approval: { ...ANSWERS_WHILE_RUNNING, ...ANSWERS_WHILE_BUSY },
+    compact: { requiresSession: true, ...QUEUES_WHILE_RUNNING },
+    handoff: { requiresSession: true, requiresNoInteraction: true, ...QUEUES_WHILE_RUNNING },
+    loop: { requiresSession: true, requiresNoInteraction: true, ...QUEUES_WHILE_RUNNING },
+    // A record list is a surface for the draft being typed; by the time a turn ends, the operator has
+    // moved on, so offering it later would be noise rather than help.
+    loops: { requiresSession: true, requiresNoInteraction: true, ...CONFLICTS_WITH_RUNNING },
+    // The host decides whether its own registered commands may run while a turn is in flight.
+    hostCommand: { requiresSession: true, requiresNoInteraction: true },
+    // Stopping is a control-lane action: it stays allowed while an approval waits, and while the very
+    // line it is meant to interrupt still owns the controller, because that is exactly when it is needed.
+    loopStop: { requiresSession: true, control: true, ...ANSWERS_WHILE_RUNNING, ...ANSWERS_WHILE_BUSY },
+    // Answering a paused run and ending it must both work while the loop is what is running.
+    loopAnswer: { requiresSession: true, ...ANSWERS_WHILE_RUNNING, ...ANSWERS_WHILE_BUSY },
+    export: { requiresSession: true },
+    exportHtml: { requiresSession: true },
+};
+/** Longest common prefix of the candidate commands, so Tab can extend an ambiguous draft.
+ * @param values - Command candidates.
+ * @returns The shared leading prefix.
+ */
+export function commonPrefix(values) {
+    let prefix = values[0] ?? '';
+    for (const value of values) {
+        let index = 0;
+        while (index < prefix.length && index < value.length && prefix[index] === value[index])
+            index++;
+        prefix = prefix.slice(0, index);
+    }
+    return prefix;
+}
+/** Complete the leading slash command; an ambiguous draft extends to the shared prefix.
+ * @param input - Current composer draft.
+ * @returns The completed draft, or undefined when nothing can be completed.
+ */
+export function completeCommand(input) {
+    if (!input.startsWith('/') || input.includes(' '))
+        return undefined;
+    const matches = COMMANDS.filter(command => command.startsWith(input));
+    const only = matches.length === 1 ? matches[0] : undefined;
+    if (only !== undefined)
+        return `${only} `;
+    const prefix = commonPrefix(matches);
+    return prefix.length > input.length ? prefix : undefined;
+}
+/** Commands matching the current draft, shown under the composer.
+ * @param input - Current composer draft.
+ * @returns Candidate command names.
+ */
+export function suggestedCommands(input) {
+    return COMMANDS.filter(command => input.startsWith('/') && !input.includes(' ') && command.startsWith(input));
+}
+/** The catalog entry whose arguments the draft is currently typing.
+ *
+ * A usage line is only useful once the name is settled and arguments have begun, so this requires
+ * whitespace after a token that names one command: `/model ` hints the model command, while `/co `
+ * names none and `/think` is still completing a name. A unique prefix counts, because the same prefix
+ * already runs that command.
+ * @param input - Current composer draft.
+ * @returns The command's hint, or undefined when no arguments are being typed.
+ */
+export function argumentHint(input) {
+    if (!input.startsWith('/'))
+        return undefined;
+    const space = input.search(/\s/);
+    if (space <= 0)
+        return undefined;
+    const token = input.slice(0, space);
+    const command = COMMANDS.includes(token) ? token : resolveCommand(token);
+    return command === undefined ? undefined : COMMAND_HINTS.find(hint => hint.command === command);
+}

package/dist/state.d.ts

@@ -1,26 +1,34 @@
 /** Application state shared by the controller facade and every domain controller. */
 import { SessionInfo } from './session/info.ts';
-import type { HistorySearch, RemovalTarget } from './session/types.ts';
+import type { HistorySearch, PendingInteraction, RemovalTarget } from './session/types.ts';
+import type { ShellSnapshot } from './shell/index.ts';
 import type { ObjectValue } from './transport/wire.ts';
 /** State shared by the picker and conversation view. */
 export interface State {
     version: number;
+    /** The last failure the application recorded, for a diagnostic line and a refusal's reason.
+     *
+     * Internal on purpose (13.2-D2): a command's failure fact is its `CommandResult.outcome` plus the
+     * trace, and this is only what a connection, a session stream or an action envelope left behind.
+     * Whether an operation is running is not stored here — that is `queries.foreground`.
+     */
+    lastFailure: string;
     online: boolean;
-    busy: boolean;
     screen: 'workspaces' | 'sessions' | 'chat' | 'path';
     status: string;
-    error: string;
     workspaces: ObjectValue[];
     sessions: ObjectValue[];
     showAllSessions: boolean;
     workspaceId?: string;
     sessionId?: string;
-    pending: ObjectValue[];
+    pending: PendingInteraction[];
     controlError?: string;
     modelError?: string;
     presetError?: string;
     presets?: ObjectValue[];
     defaultModel?: ObjectValue;
+    /** Local `!` runs, published so the UI never reads the shell service object. */
+    shell: ShellSnapshot;
     /** Record, prompt index, composer, view and interaction state of the selected session. */
     session: SessionInfo;
 }
@@ -34,6 +42,8 @@ export interface ControllerStore {
     selection(): number;
     /** Advance the selector generation when the selected workspace or session changes. */
     bumpSelection(): void;
+    /** Whether an operation owns the client's foreground slot right now. */
+    busy(): boolean;
 }
 /** Build the initial state before any connection exists.
  * @returns A fresh state whose transcript is empty and disconnected.

package/dist/state.js

@@ -4,6 +4,7 @@ import { SessionInfo } from "./session/info.js";
  * @returns A fresh state whose transcript is empty and disconnected.
  */
 export function initialState() {
-    return { version: 0, online: false, busy: false, screen: 'workspaces', status: 'Connecting…',
-        error: '', workspaces: [], sessions: [], showAllSessions: false, pending: [], session: new SessionInfo() };
+    return { version: 0, lastFailure: '', online: false, screen: 'workspaces',
+        status: 'Connecting…', workspaces: [], sessions: [], showAllSessions: false, pending: [],
+        shell: { running: false, blocks: [] }, session: new SessionInfo() };
 }

package/dist/text.d.ts

@@ -0,0 +1,28 @@
+/** Terminal text hygiene shared by every layer; it knows nothing about the wire protocol.
+ *
+ * This module is deliberately dependency-free. It lives at the source root so `session/`, `ui/`
+ * and `cli/` can clean remote text without importing the transport domain — the boundary rule that
+ * `ui/` must never reach into `transport/`.
+ */
+/** Remove terminal controls from remote text while retaining line breaks and tabs. */
+export declare function safeText(value: string): string;
+/** Return a displayable error without serializing request headers or credentials. */
+export declare function errorText(error: unknown): string;
+/** Reduce text that must appear in a diagnostic log to a fact that is safe to paste elsewhere.
+ *
+ * A trace or a bug report leaves the machine, so text quoted into one is first stripped of the two
+ * things that most often carry content out with it: absolute paths (which name a user, a project or a
+ * client) and anything shaped like a credential. Whitespace collapses so a multi-line child's output
+ * stays one field, and the result is bounded. This is for *diagnostic* text only: a message the
+ * operator is meant to read in full never goes through it.
+ * @param text - Text captured for diagnosis.
+ * @param limit - Longest result, in characters.
+ * @returns One bounded line with paths and credentials replaced.
+ */
+export declare function sanitizeTraceText(text: string, limit?: number): string;
+/** Fit a tool operation to one terminal row without exposing the result body.
+ * @param text - Tool name, status icon and optional operation.
+ * @param width - Available terminal columns.
+ * @returns A single line with an ellipsis when shortened.
+ */
+export declare function toolLine(text: string, width: number): string;

package/dist/text.js

@@ -0,0 +1,55 @@
+/** Terminal text hygiene shared by every layer; it knows nothing about the wire protocol.
+ *
+ * This module is deliberately dependency-free. It lives at the source root so `session/`, `ui/`
+ * and `cli/` can clean remote text without importing the transport domain — the boundary rule that
+ * `ui/` must never reach into `transport/`.
+ */
+import sliceAnsi from 'slice-ansi';
+/** Remove terminal controls from remote text while retaining line breaks and tabs. */
+export function safeText(value) {
+    return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, '');
+}
+/** Return a displayable error without serializing request headers or credentials. */
+export function errorText(error) {
+    return safeText(error instanceof Error ? error.message : String(error));
+}
+/** Reduce text that must appear in a diagnostic log to a fact that is safe to paste elsewhere.
+ *
+ * A trace or a bug report leaves the machine, so text quoted into one is first stripped of the two
+ * things that most often carry content out with it: absolute paths (which name a user, a project or a
+ * client) and anything shaped like a credential. Whitespace collapses so a multi-line child's output
+ * stays one field, and the result is bounded. This is for *diagnostic* text only: a message the
+ * operator is meant to read in full never goes through it.
+ * @param text - Text captured for diagnosis.
+ * @param limit - Longest result, in characters.
+ * @returns One bounded line with paths and credentials replaced.
+ */
+export function sanitizeTraceText(text, limit = 200) {
+    const flat = safeText(text)
+        .replace(/\s+/gu, ' ')
+        .trim()
+        // A URL keeps its origin — that is the diagnosable part — while its path goes.
+        .replace(/\b([a-z][a-z0-9+.-]*:\/\/[^\s/'"]+)(\/[^\s'"]*)?/giu, '$1<path>')
+        // A Windows drive path.
+        .replace(/\b[A-Za-z]:\\[^\s'"]*/gu, '<path>')
+        // A Unix absolute path, only from a boundary and only with a directory part, so an identifier such
+        // as `session/agent-busy` is left alone.
+        .replace(/(^|[\s'"=(:,])(?:\/(?:[^\s'":,)]+\/)+[^\s'":,)]*)/gu, '$1<path>')
+        // Credentials last: a secret can sit inside what the earlier rules replaced.
+        .replace(/\b(?:bearer|token|apikey|api[_-]?key|secret|password|passwd|authorization|cookie)\b\s*[:=]\s*\S+/giu, '<redacted>')
+        .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/gu, '<redacted>')
+        .replace(/\b[A-Fa-f0-9]{32,}\b/gu, '<redacted>');
+    return flat.length <= limit ? flat : `${flat.slice(0, limit)}…`;
+}
+/** Fit a tool operation to one terminal row without exposing the result body.
+ * @param text - Tool name, status icon and optional operation.
+ * @param width - Available terminal columns.
+ * @returns A single line with an ellipsis when shortened.
+ */
+export function toolLine(text, width) {
+    const clean = safeText(text).replace(/\s+/gu, ' ').trim();
+    if (width < 2)
+        return width === 1 ? '…' : '';
+    const clipped = sliceAnsi(clean, 0, width);
+    return clipped.length < clean.length ? sliceAnsi(clean, 0, width - 1) + '…' : clean;
+}

package/dist/transport/events.d.ts

@@ -0,0 +1,104 @@
+/** One place that reads DSH event field names and turns them into semantic host events.
+ *
+ * Raw wire stops here: no `Json`/`ObjectValue` payload survives into a `HostEvent`, so `connection/`,
+ * `session/` and the UI never learn how the host names its fields. Replying `{kind:'next'}` to an
+ * unrecognized waterfall is a wire-level obligation of the host's event chain, so it is modelled as
+ * `waterfall-delegate` rather than silently dropped.
+ */
+import { type Json, type ObjectValue } from './wire.ts';
+/** One selectable answer of a host question, already flattened out of the raw request. */
+export interface QuestionOption {
+    label: string;
+    description?: string;
+}
+/** One question of an `user-questions/request` waterfall. */
+export interface QuestionItem {
+    id: string;
+    header?: string;
+    question: string;
+    detail?: string;
+    multiSelect: boolean;
+    options: readonly QuestionOption[];
+}
+/** A decoded host event with protocol field names already resolved into domain meaning. */
+export type HostEvent = {
+    kind: 'approval-request';
+    eventId: string;
+    sessionId: string;
+    description: string;
+} | {
+    kind: 'question-request';
+    eventId: string;
+    sessionId: string;
+    questions: readonly QuestionItem[];
+}
+/** A waterfall this client does not answer; the caller must reply `next` to keep the host chain moving. */
+ | {
+    kind: 'waterfall-delegate';
+    eventId: string;
+} | {
+    kind: 'cancel';
+    eventId: string;
+} | {
+    kind: 'agent-status';
+    sessionId: string;
+    running: boolean;
+} | {
+    kind: 'catalog-invalidated';
+} | {
+    kind: 'session-error';
+    sessionId: string;
+    error: string;
+} | {
+    kind: 'control';
+    frame: ControlFrame;
+};
+/** One host-owned pending input, flattened to the text the UI shows. */
+export interface QueuedInput {
+    id: string;
+    placement: 'queued' | 'steering' | 'context';
+    text: string;
+}
+/** A capability value the host owns. Individual keys are typed incrementally as they are consumed. */
+export type ProjectionValue = Json;
+/** One session's projection values and the sequence they describe. */
+export interface ProjectionSnapshot {
+    asOfSeq: number;
+    values: Readonly<Record<string, ProjectionValue>>;
+}
+/** One decoded `session/control` frame with protocol field names already resolved. */
+export type ControlFrame = {
+    kind: 'baseline';
+    projections: ReadonlyMap<string, ProjectionSnapshot>;
+    queues: ReadonlyMap<string, readonly QueuedInput[]>;
+    jobs: ReadonlyMap<string, number>;
+} | {
+    kind: 'projection';
+    sessionId: string;
+    key: string;
+    seq: number;
+    value: ProjectionValue;
+} | {
+    kind: 'queue';
+    sessionId: string;
+    items: readonly QueuedInput[];
+} | {
+    kind: 'jobs';
+    sessionId: string;
+    count: number;
+};
+/** Decode one projection baseline, as carried by a `session/control` baseline or a follow snapshot. */
+export declare function projectionSnapshot(value: unknown): ProjectionSnapshot | undefined;
+/** Turn one decoded `session/control` frame into a semantic control frame.
+ * @param value - One decoded `session/control` frame.
+ * @returns The normalized frame.
+ */
+export declare function controlFrame(value: unknown): ControlFrame;
+/** Turn one decoded `$events` frame into a semantic host event.
+ *
+ * Returns `undefined` for anything this client does not act on, including the `ready` handshake,
+ * which belongs to the connection lifecycle rather than to a domain.
+ * @param frame - One decoded `$events` frame.
+ * @returns The normalized event, or undefined when it is not one this client consumes.
+ */
+export declare function hostEvent(frame: ObjectValue): HostEvent | undefined;

package/dist/transport/events.js

@@ -0,0 +1,149 @@
+/** One place that reads DSH event field names and turns them into semantic host events.
+ *
+ * Raw wire stops here: no `Json`/`ObjectValue` payload survives into a `HostEvent`, so `connection/`,
+ * `session/` and the UI never learn how the host names its fields. Replying `{kind:'next'}` to an
+ * unrecognized waterfall is a wire-level obligation of the host's event chain, so it is modelled as
+ * `waterfall-delegate` rather than silently dropped.
+ */
+import { array, errorText, object, string } from "./wire.js";
+/** Host notifications that invalidate the model catalog. */
+const CATALOG_EVENTS = new Set(['llm/adapters-updated', 'settings/document-updated', 'credentials/reference-updated']);
+/** Require a projection watermark rather than accepting a rolled-back value. */
+function sequence(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < -1)
+        throw new Error('Invalid projection watermark');
+    return value;
+}
+/** Flatten one session's pending-input list. */
+function queuedInputs(value) {
+    return array(value).map(raw => {
+        const item = object(raw);
+        if (!['queued', 'steering', 'context'].includes(string(item.placement)))
+            throw new Error('Invalid queue placement');
+        return { id: string(item.id), placement: item.placement,
+            text: array(object(item.message).content).map(object)
+                .map(block => block.type === 'text' ? string(block.text) : `[${string(block.type)}]`).join(' ') };
+    });
+}
+/** Count the jobs the host still considers active. */
+function activeJobs(value) {
+    return array(value).filter(item => ['running', 'stopping'].includes(string(object(item).status))).length;
+}
+/** Decode one projection baseline, as carried by a `session/control` baseline or a follow snapshot. */
+export function projectionSnapshot(value) {
+    if (value === undefined)
+        return undefined;
+    const baseline = object(value);
+    return { asOfSeq: sequence(baseline.asOfSeq), values: object(baseline.values) };
+}
+/** Turn one decoded `session/control` frame into a semantic control frame.
+ * @param value - One decoded `session/control` frame.
+ * @returns The normalized frame.
+ */
+export function controlFrame(value) {
+    const frame = object(value);
+    if (frame.type === 'baseline') {
+        const baseline = object(frame.value);
+        const projections = Object.entries(object(baseline.projections))
+            .map(([id, snapshot]) => [id, projectionSnapshot(snapshot)]);
+        const queues = Object.entries(object(baseline.queues)).map(([id, items]) => [id, queuedInputs(items)]);
+        const jobs = Object.entries(object(baseline.jobs)).map(([id, items]) => [id, activeJobs(items)]);
+        return { kind: 'baseline', projections: new Map(projections), queues: new Map(queues), jobs: new Map(jobs) };
+    }
+    if (frame.type === 'projection' || frame.type === 'queue' || frame.type === 'jobs') {
+        const sessionId = string(frame.sessionId);
+        if (frame.type === 'projection') {
+            if (frame.value === undefined)
+                throw new Error('Missing projection value');
+            return { kind: 'projection', sessionId, key: string(frame.key), seq: sequence(frame.seq), value: frame.value };
+        }
+        if (frame.type === 'queue')
+            return { kind: 'queue', sessionId, items: queuedInputs(frame.items) };
+        // The host names the job rows `jobs`; the loopback fixtures used `items`, so accept either.
+        return { kind: 'jobs', sessionId, count: activeJobs(frame.jobs ?? frame.items) };
+    }
+    throw new Error('Unknown session control frame');
+}
+/** Read a possibly-absent string field without turning protocol drift into a throw. */
+function optionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** Flatten one raw question into the semantic shape the session domain retains. */
+function questionItem(value) {
+    const item = object(value);
+    const options = array(item.options ?? []).map(raw => {
+        const option = object(raw);
+        const description = optionalString(option.description);
+        return { label: string(option.label), ...(description === undefined ? {} : { description }) };
+    });
+    const header = optionalString(item.header);
+    const detail = optionalString(item.detail);
+    return {
+        id: string(item.id),
+        ...(header === undefined ? {} : { header }),
+        question: string(item.question),
+        ...(detail === undefined ? {} : { detail }),
+        multiSelect: item.multiSelect === true,
+        options,
+    };
+}
+/** Decode one `$events` waterfall frame. */
+function waterfallEvent(frame) {
+    const eventId = string(frame.eventId);
+    const sessionId = optionalString(frame.agentId) ?? '';
+    if (frame.event === 'approval/request') {
+        // The approval body is host-defined and currently rendered verbatim; formatting it here keeps
+        // the terminal output byte-identical while removing the raw object from the boundary.
+        return { kind: 'approval-request', eventId, sessionId, description: JSON.stringify(frame.request ?? null, null, 2) };
+    }
+    if (frame.event === 'user-questions/request') {
+        try {
+            const request = object(frame.request);
+            return { kind: 'question-request', eventId, sessionId, questions: array(request.questions ?? []).map(questionItem) };
+        }
+        catch {
+            // A malformed question still has to be settled, or the host's event chain blocks on it.
+            return { kind: 'waterfall-delegate', eventId };
+        }
+    }
+    return { kind: 'waterfall-delegate', eventId };
+}
+/** Decode one `$events` emit frame this client reacts to. */
+function emitEvent(frame) {
+    const name = frame.event;
+    if (name === 'api-session/status') {
+        const args = array(frame.args);
+        if (typeof args[1] !== 'boolean')
+            throw new Error('Invalid session running state');
+        return { kind: 'agent-status', sessionId: string(args[0]), running: args[1] };
+    }
+    if (name === 'api-session/error') {
+        const args = array(frame.args);
+        return { kind: 'session-error', sessionId: optionalString(args[0]) ?? '', error: errorText(args[1]) };
+    }
+    if (typeof name === 'string' && CATALOG_EVENTS.has(name))
+        return { kind: 'catalog-invalidated' };
+    return undefined;
+}
+/** Turn one decoded `$events` frame into a semantic host event.
+ *
+ * Returns `undefined` for anything this client does not act on, including the `ready` handshake,
+ * which belongs to the connection lifecycle rather than to a domain.
+ * @param frame - One decoded `$events` frame.
+ * @returns The normalized event, or undefined when it is not one this client consumes.
+ */
+export function hostEvent(frame) {
+    try {
+        if (frame.type === 'waterfall')
+            return waterfallEvent(frame);
+        if (frame.type === 'cancel')
+            return { kind: 'cancel', eventId: string(frame.eventId) };
+        if (frame.type === 'emit')
+            return emitEvent(frame);
+    }
+    catch {
+        // A frame this client cannot decode is not allowed to fail the whole subscription.
+        return undefined;
+    }
+    return undefined;
+}

package/dist/transport/wire.d.ts

@@ -1,17 +1,9 @@
-/** JSON validation and terminal-safe presentation at the remote boundary. */
-export type Json = null | boolean | number | string | Json[] | {
-    [key: string]: Json;
-};
-export type ObjectValue = {
-    [key: string]: Json;
-};
-/** Require an object from a decoded wire message. */
-export declare function object(value: unknown): ObjectValue;
-/** Require a string field rather than silently accepting protocol drift. */
-export declare function string(value: unknown): string;
-/** Require an array field from the server. */
-export declare function array(value: unknown): Json[];
-/** Remove terminal controls from remote text while retaining line breaks and tabs. */
-export declare function safeText(value: string): string;
-/** Return a displayable error without serializing request headers or credentials. */
-export declare function errorText(error: unknown): string;
+/** The wire's decoding surface.
+ *
+ * The JSON shapes, their strict readers and the displayable error text are dependency-free leaves
+ * (`src/json.ts`, `src/text.ts`), so the UI can name the same types without importing the transport
+ * domain. This module re-exports them as the wire-facing API the features already use.
+ */
+export type { Json, ObjectValue } from '../json.ts';
+export { array, object, string } from '../json.ts';
+export { errorText, safeText } from '../text.ts';

package/dist/transport/wire.js

@@ -1,27 +1,2 @@
-/** Require an object from a decoded wire message. */
-export function object(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error('Expected a JSON object from the server');
-    }
-    return value;
-}
-/** Require a string field rather than silently accepting protocol drift. */
-export function string(value) {
-    if (typeof value !== 'string')
-        throw new Error('Expected a string from the server');
-    return value;
-}
-/** Require an array field from the server. */
-export function array(value) {
-    if (!Array.isArray(value))
-        throw new Error('Expected an array from the server');
-    return value;
-}
-/** Remove terminal controls from remote text while retaining line breaks and tabs. */
-export function safeText(value) {
-    return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, '');
-}
-/** Return a displayable error without serializing request headers or credentials. */
-export function errorText(error) {
-    return safeText(error instanceof Error ? error.message : String(error));
-}
+export { array, object, string } from "../json.js";
+export { errorText, safeText } from "../text.js";