dsh-ssh-tui 0.8.3 → 0.8.4-rc.2

package/lib/types/doctor.d.ts

@@ -30,7 +30,11 @@ export interface DoctorCheck {
 export interface DoctorRouting {
     provider?: string;
     model?: string;
-    /** Every provider id the llm-pi-ai section configures. */
+    /**
+     * Every route exposed by the live adapter directory or configured under
+     * `llm-pi-ai.providers`. Presence is registration/configuration evidence,
+     * not a network probe.
+     */
     routes: readonly string[];
     /** Model ids the selected provider's route lists. */
     routeModels: readonly string[];
@@ -50,6 +54,14 @@ export interface DoctorFacts {
         roster: boolean;
         /** `codeRuntime` — what the PTC preset mounts. */
         codeRuntime: boolean;
+        /**
+         * `tools.get('ask_user_question')` — the actual registration, not the row
+         * text. Absent on snapshots taken before this field existed, where the
+         * textual check remains the fallback.
+         */
+        askUserTool?: boolean;
+        /** `tools.get('present')` — the other half of the 0.1.7 agent plane. */
+        presentTool?: boolean;
     };
     /** The profile patch. `readable` is false when it does not exist yet. */
     patch: {

package/lib/types/dsh-compat.d.ts

@@ -9,9 +9,10 @@
  * here picks the API that is actually present so one build runs on either
  * host line.
  */
+import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { Context } from '@deepseek-ai/cordis';
 import type { ContextFormed } from '@deepseek-ai/dsh-llm';
-import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import type z from '@deepseek-ai/schemastery';
 /**
@@ -294,3 +295,21 @@ export declare function streamChunkOf(frame: unknown, fallback?: {
 export declare function listenHostEvent(ctx: {
     on: (event: never, handler: never) => unknown;
 }, event: string, handler: (...args: unknown[]) => unknown): () => void;
+/**
+ * Wind down the selected direct children of one parent, under both names the
+ * subagent service has shipped.
+ *
+ * 0.2.1-rc.2 renamed `drainContinuableChildren(parent, childIds)` to
+ * `drainChildren(parent, childIds)` — same contract (release the selected
+ * resident direct children of one exact live parent, leaving its other children
+ * admitted). Both 0.2.0 rcs and 0.2.1-rc.2 are declared, so the call site asks
+ * for whichever spelling the host has instead of pinning one and failing to
+ * compile on the other. A composition without the service at all resolves: the
+ * caller has already handled "no service", and this keeps the helper total.
+ *
+ * @param subagents - the host's subagent service.
+ * @param parent - the exact live parent whose children are being released.
+ * @param childIds - durable direct-child ids to release when resident.
+ * @returns once every selected activation released its execution handle.
+ */
+export declare function drainChildSubagents(subagents: Context['subagents'], parent: Agent, childIds: readonly SessionId[]): Promise<void>;

package/lib/types/footer-budget.d.ts

@@ -83,15 +83,6 @@ export interface FooterStripInput {
         long: string;
         short: string;
     };
-    /**
-     * The Host-local echo: the last thing this Host confirmed to the reader
-     * (`/theme` switched, a preset saved, a copy landed).
-     *
-     * Not history (AD-13) and not telemetry: it is an acknowledgement, so it is the
-     * lowest-priority chip on the row — the first thing a narrow terminal gives up, and
-     * never at the cost of the link, the activity, the quota or the context reading.
-     */
-    echo?: string;
     /** Whether the terminal must be painted with ASCII glyphs. */
     ascii?: boolean;
     /** Colour depth the accents are downgraded for. */

package/lib/types/input-reader.d.ts

@@ -0,0 +1,198 @@
+/**
+ * How long a read that could still grow into a sequence is held.
+ *
+ * The window is what makes a lone `ESC` (the reader pressed Escape) different from
+ * the first byte of a sequence the terminal is still sending. W-1 moved the timer,
+ * not the number: changing it changes how Escape feels, and that is a separate
+ * decision with its own evidence.
+ */
+export declare const ESCAPE_HOLD_MS = 60;
+/**
+ * One framed unit of input.
+ *
+ * The vocabulary is deliberately small — four kinds carry text, one carries the
+ * released Escape, one carries a device reply — because the Reader's job is to say
+ * *what arrived*, not what it means. `key` and `burst` reach the same routing today;
+ * they are distinguished because the Router (W-2) has to decide "one key" versus
+ * "several keys in one read" (the read-coalescing gaps G-1/G-2 live exactly there).
+ */
+export type InputFrame = 
+/** One complete terminal unit: a control byte, a full CSI sequence, or a lone ESC. */
+{
+    kind: 'key';
+    sequence: string;
+}
+/** A read of ordinary typing. It may carry several keys — W-3 splits it. */
+ | {
+    kind: 'burst';
+    text: string;
+}
+/** Text to be typed exactly as it is (a sequence tail, an Alt remainder, a release). */
+ | {
+    kind: 'literal';
+    text: string;
+}
+/** The payload between paste markers. */
+ | {
+    kind: 'paste';
+    text: string;
+}
+/** The held read turned out to be the Escape key itself. */
+ | {
+    kind: 'escape';
+}
+/** A device reply (cursor position) — input to the prober, never to an owner. */
+ | {
+    kind: 'reply';
+    sequence: string;
+};
+export interface InputReaderOptions {
+    /** A read that survived decoding and reply filtering. */
+    onRead: (text: string) => void;
+    /** A frame the Reader produced on its own: paste traffic, or a released hold. */
+    onFrame: (frame: InputFrame) => void;
+    /**
+     * How long a stalled paste may hold the reader before it is abandoned.
+     *
+     * A seam for tests only — the default is the release value. A test that waited the
+     * real two seconds kept a whole file's process alive alongside the others and was
+     * enough to unbalance a timer-sensitive paint test on a Windows runner.
+     */
+    pasteMarkerHoldMs?: number;
+}
+/**
+ * How long a paste may sit with half a marker before the reader gives up on it.
+ *
+ * This is a watchdog, not a key hold: a paste is a stream, and its close marker may
+ * arrive in a second chunk after a slow terminal, a ConPTY or a loaded runner — on
+ * Windows CI the gap was over 200 ms, and expiring that early typed the marker's tail
+ * into the draft and left the session inside the paste. So the window is generous.
+ * When it does expire the reader does not just release the tail as payload, it
+ * **leaves the paste**: a paste that never closed must not keep the keyboard as its
+ * payload for the rest of the session.
+ */
+export declare const PASTE_MARKER_HOLD_MS = 2000;
+export declare class InputReader {
+    private readonly options;
+    private readonly decoder;
+    private readonly guard;
+    /** A read that may still grow (escape assembly). */
+    private held;
+    private holdTimer;
+    /** Inside `ESC[200~ … ESC[201~`. */
+    private inPaste;
+    /**
+     * The tail of a read that ended *inside* a paste marker (`…ESC[20`), waiting for
+     * its other half.
+     */
+    private pasteTail;
+    private pasteTailTimer;
+    constructor(options: InputReaderOptions);
+    /** One read of bytes: decode it, drop device replies, hand the rest on. */
+    push(chunk: Buffer): void;
+    /** The read with any held prefix in front of it. The hold window is over. */
+    assemble(text: string): string;
+    /**
+     * The frames of one read, whichever kind it is.
+     *
+     * A read is what the terminal happened to send, not what the reader pressed: a
+     * fast typist, a slow link or ConPTY can put several keys in one read. This is the
+     * one place that decides where one unit ends and the next begins; everything above
+     * it (Router, owners) sees complete units only, and nothing above it re-parses the
+     * bytes (AD-20 §4.4, §6).
+     */
+    read(text: string): InputFrame[];
+    /**
+     * Frame one paste read, holding back a marker it cut in half.
+     *
+     * A terminal writes bytes, not reads: `ESC[201~` can arrive as `…ESC[20` and `1~`.
+     * Framed naively, the first read swallows `ESC[20` as payload and the second one
+     * carries no marker at all — so `inPaste` never clears and **every later key is
+     * pasted text**: Esc stops closing a dialog, `/exit` stops exiting. Found by
+     * `scripts/tui-paste-probe.mjs` on CI, where the pty chunked the write exactly
+     * there. The fix is the same rule the escape ladder already uses — a read that
+     * could still grow is held, and released as payload if its other half never comes.
+     */
+    private framePaste;
+    private armPasteTail;
+    private cancelPasteTail;
+    /**
+     * One non-paste read, split into complete units.
+     *
+     * The rules, and why each one exists:
+     *
+     *   - **A complete CSI/SS3 sequence is one unit.** `ESC [ 5 ~ ESC [ 5 ~` is two page
+     *     keys, not one unnameable read (G-1). A sequence the read cuts short stays one
+     *     piece: `hold()` has already claimed it if it could still grow, and a trailing
+     *     `ESC [` must reach the hold again rather than be split into `ESC` + `[`.
+     *   - **An Alt chord is one unit.** `ESC` plus exactly one printable character is
+     *     Alt+that key, so `ESC 1 x` is the chord Alt+1 *and then* `x` — never the text
+     *     `1x` (G-3), and never a chord that swallows the character behind it.
+     *   - **A control byte is one unit, CR/LF pair as one Enter.** `\x10\x10` is two
+     *     presses of a rebound key (G-2/G-8), and Windows' CRLF is one key.
+     *   - **A run of ordinary characters is one unit.** Splitting typing per character
+     *     would make a pasted `yes` answer a confirm dialog character by character,
+     *     which is the boundary W-0 pinned (`yes-typed-at-dialog`). Keymap lookup on a
+     *     whole run is still exactly what a run means: text.
+     *   - **A burst the paste heuristic claims stays whole.** A console without
+     *     bracketed paste sends a paste as ordinary bytes with line breaks in them;
+     *     that read has to reach the paste path intact (`looksLikePasteBurst`).
+     */
+    units(text: string): InputFrame[];
+    /**
+     * Whether a read is paste traffic: inside a paste, or carrying a marker.
+     *
+     * Asked before anything else, exactly as the inline check it replaces was: while
+     * inside a paste, CR/LF are literal characters rather than submit.
+     */
+    isPasteTraffic(combined: string): boolean;
+    /**
+     * The frames of one paste read, in order: payload inside the markers as `paste`,
+     * everything outside them as `literal` (which is what the inline version typed
+     * directly, without a keymap lookup).
+     *
+     * Only complete markers are handled here: `framePaste` holds back a read that ends
+     * inside one, because a marker whose two halves land in two reads would otherwise
+     * leave the reader inside the paste for the rest of the session.
+     */
+    frames(combined: string): InputFrame[];
+    /**
+     * Keep a read that could still grow into a sequence.
+     * @returns true when it was held (the caller stops there), false when the read is
+     *   complete as it stands.
+     */
+    hold(combined: string): boolean;
+    /**
+     * Whether one read is a paste from a console that cannot say so.
+     *
+     * A burst carrying more than one line break is not a human pressing Enter twice —
+     * they cannot press it twice inside one read. This is the fallback's one rule, and
+     * it lives here so every caller applies the same one.
+     */
+    static looksLikePasteBurst(text: string): boolean;
+    /** Whether a complete read is a device reply rather than input. */
+    isDeviceReply(text: string): boolean;
+    /** Classify one complete read by shape. */
+    classify(text: string): InputFrame;
+    /**
+     * Hand over a held reply tail now.
+     *
+     * The guard releases on its own window; this is for a caller that already knows
+     * the tail is stale — `scripts/bench-b2.mjs` drives keystrokes faster than the
+     * hold, and a measurement that waited for the window would be measuring the wait.
+     */
+    releaseReplyTail(): void;
+    /** Drop the holds and the reply filter (display detached, teardown). */
+    stop(): void;
+    private cancelHold;
+    /**
+     * What a held read turned out to be.
+     *
+     * Verbatim from the inline timer it replaces: a lone `ESC` is the Escape key, an
+     * `ESC O` without its final byte is Alt+O, an escape sequence that never completed
+     * is consumed silently (its `ESC` must not read as a cancel), and anything else is
+     * typed. The last branch is unreachable for the shapes `isEscapePrefix` accepts —
+     * it is kept because "unreachable today" is not a reason to change a release.
+     */
+    private releaseHold;
+}

package/lib/types/input-router.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The InputRouter: one unit in, exactly one owner out.
+ *
+ * W-1 taught the TUI *what arrived* (`InputFrame`). This module answers the other
+ * question — *who takes it* — and it is the only place that may. The four owners
+ * (Screen, Surface, Composer, Workspace) each have an adapter in `tui.ts`; an
+ * adapter may read its own state, but it may not decide cross-owner ownership
+ * again, and it may not hand a unit on to the next owner when it does not use it
+ * (AD-20 §4.3, §4.5 F-1/F-6).
+ *
+ * The decision is a pure function of `(unit kind, unit, ownership snapshot)`: no
+ * app state is read or written, nothing is painted, no transcript row is pushed,
+ * and the snapshot is a plain object the caller keeps and overwrites, so a
+ * keystroke costs no allocation (W-2 is a hot-path migration).
+ *
+ * The rules are the ones `tui.ts` already applied inline, moved here verbatim —
+ * including one asymmetry that is **recorded debt, not a decision**:
+ *
+ *   1. `Ctrl+L` is handled by the Screen when a Screen is up and by the Composer
+ *      otherwise; the repaint has two implementations and W-2 does not merge them
+ *      (AD-20 §6: only a test that proves both owners repaint identically may).
+ *      W-3b.2 owns that one.
+ *
+ * W-3b.1 closed the other asymmetry this module used to record:
+ * `SURFACE_COMPOSER_KEYS` sent `Home`/`End`/`Delete`/kitty-`Ctrl+Shift+C` to the
+ * composer while a Surface was up. The Surface owns them now, like every other unit,
+ * and its adapter decides what they mean — the field it borrowed, or nothing.
+ *
+ * @module dsh-ssh-tui/input-router
+ */
+/** Who takes a unit. Exactly one of these, per unit, decided here. */
+export type Owner = 'screen' | 'surface' | 'composer' | 'workspace';
+/**
+ * The unit classes the ladder dispatches.
+ *
+ * `text` and `control` are the composer's own shapes, `sequence` is a complete
+ * CSI/SS3 unit, `paste` is a payload with its markers already off, and `escape` is
+ * the released lone Escape. `burst` frames never reach this module as a whole: the
+ * ladder types them character by character, so every character is routed on its own
+ * (which is also what lets a Surface answer `y` and the composer take the `es`).
+ */
+export type UnitKind = 'text' | 'control' | 'sequence' | 'paste' | 'escape';
+/** The read-only ownership state a decision may look at. */
+export interface OwnershipSnapshot {
+    /** The Screen that is up, if any (its kind, for reports). */
+    screenKind: string | undefined;
+    /** The Surface (dialog) that is up, if any. */
+    surfaceKind: string | undefined;
+    /**
+     * …and whether that Surface owns a borrowed text field.
+     *
+     * Part of the contract's vocabulary, and no rule branches on it since W-3b.1:
+     * whether a Surface borrowed a field decides what its *adapter* does with an
+     * editing key, not who owns the key.
+     */
+    surfaceHasField: boolean;
+    /** The composer's field is empty — the focus ring's precondition. */
+    composerEmpty: boolean;
+    /** The transcript has collapsible cards — the focus ring's other precondition. */
+    workspaceCards: boolean;
+}
+export declare class InputRouter {
+    /** The one cross-owner decision. One unit in, one owner out. */
+    route(kind: UnitKind, unit: string, view: OwnershipSnapshot): Owner;
+    /**
+     * With nothing layered over the workspace, the Composer owns text and its editing
+     * keys, and the Workspace owns the transcript: the mouse, the page keys, and the
+     * focus ring — which an arrow reaches only while the field is empty and there is a
+     * card to land on (otherwise the same arrow browses history, and history is the
+     * composer's).
+     */
+    private composerOrWorkspace;
+}

package/lib/types/preset-rows.d.ts

@@ -133,7 +133,14 @@ export declare function analyzePatch(text: string): PatchAnalysis;
  * @returns the later occurrences, in file order.
  */
 export declare function duplicatePatchRows(rows: readonly PatchRowRef[]): PatchRowRef[];
-/** Whether a patch already declares one roster row, by id or by module name. */
+/**
+ * Whether a patch already addresses one roster row, by id or by module name.
+ *
+ * Every kind counts: an override or a disable targets the row just as an insert
+ * does. A repair must leave an intentional `- id: present` / `disabled: true`
+ * alone instead of mounting the same id a second time; the later entry would
+ * either collide with it or silently undo the user's choice.
+ */
 export declare function patchNamesRow(rows: readonly PatchRowRef[], row: RosterRow): boolean;
 /** The roster rows a patch does not declare yet. */
 export declare function missingRosterRows(rows: readonly PatchRowRef[], candidates?: readonly RosterRow[]): RosterRow[];
@@ -159,6 +166,8 @@ export interface PatchRepair {
  * @param missing - the roster rows to mount; defaults to the 0.1.5 set.
  * @param generation - which host line the profile boots on.
  * @returns the new text, or `undefined` when nothing has to change.
+ * @throws when `existing` is not valid YAML; appending to a broken patch would
+ * make it longer without making it bootable.
  */
 export declare function planRosterRepair(existing: string, missing?: readonly RosterRow[], generation?: HostGeneration): PatchRepair | undefined;
 /**
@@ -175,26 +184,32 @@ export declare function planDuplicateRepair(existing: string): PatchRepair | und
 /**
  * Mount the roster in one profile, unless it is already composed.
  *
- * Idempotent: a profile whose patch already names the roster row (one bundling
- * `@deepseek-ai/dsh-web-app`, for example) is left untouched. The write is a
- * plain whole-file replace because the file is small and read once at boot; a
+ * Idempotent: a profile whose patch already addresses the roster row (one
+ * bundling `@deepseek-ai/dsh-web-app`, for example) is left untouched. An
+ * existing file is backed up before the small whole-file replace; a
  * half-written patch would only be seen by the next launch.
  * @param home - the harness home carrying `profiles/`.
  * @param profile - the profile to patch.
  * @param missing - the rows to mount; defaults to the 0.1.5 set.
  * @param generation - which host line the profile boots on.
+ * @param stamp - filename-safe backups stamp, injectable for tests.
  * @returns `present` when the row already exists, else `written`.
+ * @throws when the existing patch cannot be read, is not valid YAML, or cannot
+ * be backed up; a file that cannot be preserved is not overwritten.
  */
-export declare function ensureRosterRows(home: string, profile: string, missing?: readonly RosterRow[], generation?: HostGeneration): Promise<'present' | 'written'>;
+export declare function ensureRosterRows(home: string, profile: string, missing?: readonly RosterRow[], generation?: HostGeneration, stamp?: string): Promise<'present' | 'written'>;
 /**
  * Write a repaired patch next to a copy of the previous content.
  *
- * `/doctor` changes a file the user owns, so the old text is kept beside it
- * before anything is replaced. A file that does not exist yet needs no backup.
+ * `/doctor` and the automatic repair change a file the user owns, so the old
+ * text is kept beside it before anything is replaced. A source that vanished
+ * between the read and the copy needs no backup; any other backup failure
+ * aborts before the write, leaving the original untouched.
  * @param path - the patch file to replace.
  * @param text - the new content.
  * @param stamp - filename-safe timestamp for the backup, injectable for tests.
  * @returns the backup path, or `undefined` when there was nothing to back up.
+ * @throws when the backup cannot be written; the destination is not touched.
  */
 export declare function writePatchWithBackup(path: string, text: string, stamp?: string): Promise<string | undefined>;
 /** The patch text the roster block would produce on its own, for callers that report it. */

package/lib/types/terminal-input.d.ts

@@ -37,10 +37,24 @@ export declare function stripCursorReplies(text: string): {
  * typed. A read that ends in the middle of a possible reply is held back (see
  * `flush()`) so `ESC [ 1` + `7;1R` cannot become visible digits either.
  */
+export interface TerminalInputFilterOptions {
+    /**
+     * Whether a read is bracketed-paste traffic.
+     *
+     * The filter asks instead of sniffing the markers itself: paste framing has one
+     * owner (the Reader), and a marker literal here would be a second one. It matters
+     * because a paste's close marker ends in `ESC[20` — the shape of a half-arrived
+     * cursor reply — so holding that tail cuts the marker in half and the Reader stays
+     * inside the paste for the rest of the session.
+     */
+    isPasteTraffic?: (text: string) => boolean;
+}
 export declare class TerminalInputFilter {
+    private readonly options;
     private held;
     /** The most recent cursor reply this filter swallowed, if any. */
     lastReply: string | undefined;
+    constructor(options?: TerminalInputFilterOptions);
     push(text: string): {
         forward: string;
         replies: number;
@@ -60,7 +74,7 @@ export declare class TerminalInputGuard {
     private readonly holdMs;
     private readonly filter;
     private timer;
-    constructor(emit: (text: string) => void, holdMs?: number);
+    constructor(emit: (text: string) => void, holdMs?: number, options?: TerminalInputFilterOptions);
     /** Feed one decoded read; anything that is not a reply reaches `emit`. */
     push(text: string): void;
     /** Hand a half-arrived sequence over (its window passed; it is typing). */