@itookit/dsht 0.3.8 → 0.5.2

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/slash/types.d.ts

@@ -0,0 +1,126 @@
+/** Command values shared by syntax, discovery and admission; no parser dependency. */
+/** One parsed command; every side effect stays with the caller. */
+export type Command = {
+    kind: 'ignore';
+} | {
+    kind: 'copy';
+} | {
+    kind: 'quit';
+} | {
+    kind: 'panel';
+    panel: 'cost' | 'status' | 'help';
+} | {
+    kind: 'remove';
+    target: 'workspace' | 'session';
+    query: string;
+} | {
+    kind: 'navigate';
+    target: 'workspace' | 'session';
+    query?: string;
+} | {
+    kind: 'latest';
+} | {
+    kind: 'models';
+    args: string[];
+} | {
+    kind: 'queue';
+} | {
+    kind: 'newSession';
+}
+/** Open the saved-prompt picker, or save the following text as a shortcut prompt. */
+ | {
+    kind: 'prompts';
+} | {
+    kind: 'savePrompt';
+    text: string;
+} | {
+    kind: 'history';
+    query: string;
+} | {
+    kind: 'sessionSearch';
+    command: '/ssearch' | '/wsearch';
+    query: string;
+} | {
+    kind: 'historySearch';
+    query: string;
+} | {
+    kind: 'think';
+    target: string;
+} | {
+    kind: 'older';
+} | {
+    kind: 'compact';
+}
+/** Clear the client's own HANDOFF.md, then ask the agent to write a fresh session handoff. */
+ | {
+    kind: 'handoff';
+}
+/** Start the client-driven scored loop for one `loop.yaml` record. */
+ | {
+    kind: 'loop';
+    name: string;
+    options: LoopOptions;
+}
+/** Offer the `loop.yaml` records so one can be chosen instead of typed. */
+ | {
+    kind: 'loops';
+}
+/** Stop the running loop, running or paused. */
+ | {
+    kind: 'loopStop';
+}
+/** Answer a paused run, so the current artifact is judged again with the operator's addition. */
+ | {
+    kind: 'loopAnswer';
+    text: string;
+} | {
+    kind: 'cancel';
+} | {
+    kind: 'approval';
+    allowed: boolean;
+} | {
+    kind: 'hostCommand';
+    line: string;
+}
+/** A local `!` command, run on this machine rather than the host. */
+ | {
+    kind: 'shell';
+    command: string;
+} | {
+    kind: 'export';
+    destination?: string;
+} | {
+    kind: 'exportHtml';
+    destination?: string;
+} | {
+    kind: 'coredump';
+    tag?: string;
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'prompt';
+    text: string;
+};
+/** Options carried by `/loop`.
+ *
+ * Only the fields the operator actually typed are present, so the syntax layer validates each value
+ * it sees and the application owns the defaults — command line first, then the record's `defaults`,
+ * then the global ones.
+ */
+export interface LoopOptions {
+    /** First step to run; default 1. */
+    from?: number;
+    /** Last step to run; default the record's last step. */
+    to?: number;
+    /** Passing score per step, 0-10 and possibly fractional; default the record's, else 8. */
+    score?: number;
+    /** Attempts allowed per step; default the record's, else 10. */
+    tries?: number;
+    /** Values that replace the record's own `vars` for this run, such as the document under review.
+     *
+     * The interactive form fills this in; the command line has no syntax for it, because the record —
+     * not the syntax layer — is what knows which names exist.
+     */
+    vars?: Readonly<Record<string, string>>;
+}

package/dist/slash/types.js

@@ -0,0 +1 @@
+export {};

package/dist/state.d.ts

@@ -1,32 +1,28 @@
-/** 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 { SessionState } from './session/state.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 {
+export interface State extends SessionState {
     version: number;
-    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[];
+    /** 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;
     controlError?: string;
     modelError?: string;
     presetError?: string;
     presets?: ObjectValue[];
     defaultModel?: ObjectValue;
-    /** Record, prompt index, composer, view and interaction state of the selected session. */
-    session: SessionInfo;
+    /** Local `!` runs, published so the UI never reads the shell service object. */
+    shell: ShellSnapshot;
 }
-/** The state contract every domain controller writes through. */
+/** Application state access used by connection orchestration. Feature domains use their own ports. */
 export interface ControllerStore {
-    /** Current immutable state snapshot. */
+    /** Current application snapshot; nested session data remains owned by the session domain. */
     readonly state: State;
     /** Publish a state patch and notify observers. */
     update(patch: Partial<State>): void;
@@ -34,6 +30,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

@@ -1,9 +1,10 @@
-/** Application state shared by the controller facade and every domain controller. */
+/** Application composition of session state and the other domains' published snapshots. */
 import { SessionInfo } from "./session/info.js";
 /** Build the initial state before any connection exists.
  * @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/client.d.ts

@@ -18,7 +18,7 @@ interface Listener {
     item(value: Json | undefined): void;
     end(error?: Error): void;
 }
-/** A single authenticated host connection; close before reconnecting or exiting. */
+/** One client lifetime. Peer disconnects allow reconnect; close permanently ends the lifetime. */
 export declare class Client {
     readonly timeoutMs: number;
     readonly base: URL;
@@ -27,6 +27,7 @@ export declare class Client {
     private socket;
     private listeners;
     private lifetime;
+    private closeTask?;
     constructor(base: string, timeoutMs?: number);
     /** Exchange a startup token only at GET / and retain the server's cookie expiration. */
     authenticate(token: string): Promise<void>;
@@ -58,9 +59,9 @@ export declare class Client {
     /** Archived session IDs from the latest authoritative workspace baseline. */
     archivedSessionIds: ReadonlySet<string>;
     /** List workspaces by consuming and cancelling the authoritative opening baseline. */
-    listWorkspaces(): Promise<ObjectValue[]>;
+    listWorkspaces(signal?: AbortSignal): Promise<ObjectValue[]>;
     /** List visible sessions, optionally filtering by the workspace's accounted IDs. */
-    listSessions(workspaceId?: string): Promise<ObjectValue[]>;
+    listSessions(workspaceId?: string, signal?: AbortSignal): Promise<ObjectValue[]>;
     /** Close all streams, abort in-flight HTTP, and await the physical socket's closure. */
     close(): Promise<void>;
     private signal;