@fishwithcat/dsh-tui-app 0.0.0-stage → 0.2.2-alpha.2

package/lib/types/views.d.ts

@@ -0,0 +1,572 @@
+/**
+ * pi-tui components for the terminal surface: the transcript document, the
+ * pinned status bar, and the formatting helpers they share. Every rendered line
+ * is truncated to the viewport width because the renderer treats an over-wide
+ * line as a component defect.
+ * @module @deepseek-ai/dsh-tui-app/views
+ */
+import type { Component, Editor, Focusable, SelectItem, SelectListLayoutOptions, SelectListTheme, TuiMouseEvent, TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TuiTheme } from './ansi.ts';
+import { TerminalTranscript } from './transcript.ts';
+/**
+ * One-line account of a Tool call's arguments.
+ * @param args - the raw arguments JSON string.
+ * @returns a short, human-readable summary on one line.
+ */
+export declare function summarizeToolArguments(args: string): string;
+/**
+ * The transcript document. It renders every row it holds and reuses the rows an
+ * earlier revision already rendered; the surrounding viewport (an
+ * alternate-screen scroll view, or the terminal's own scrollback) owns
+ * scrolling.
+ */
+export declare class TranscriptView implements Component {
+    private readonly transcript;
+    private readonly theme;
+    private document;
+    private rendered;
+    private readonly markdown;
+    private readonly markdownTheme;
+    /**
+     * @param transcript - the model this view renders.
+     * @param theme - the surface theme.
+     */
+    constructor(transcript: TerminalTranscript, theme: TuiTheme);
+    /** Release cached lines and Markdown components, including those of a replaced session. */
+    invalidate(): void;
+    /**
+     * Render the transcript body.
+     *
+     * Only the rows a revision touched are rendered again: a durable entry is
+     * never mutated after the fold appends it, and a live entry is a fresh object
+     * for every frame, so the per-entry cache is keyed by entry identity and
+     * width.
+     * @param width - the viewport width in columns.
+     * @returns one string per row, each within `width`.
+     */
+    render(width: number): string[];
+    /**
+     * One entry's rows at one width, reused until the entry or the width changes.
+     * @param entry - the row to render.
+     * @param width - the viewport width in columns.
+     * @returns the entry's rows, each within `width`.
+     */
+    private entryLines;
+    private renderEntry;
+    private assistantMarkdown;
+    /**
+     * One local shell row: the command with its local/sandbox label, the streamed
+     * output, then the state line. A command may span lines when it was pasted,
+     * so every line after the first starts under the bare indent.
+     */
+    private shellLines;
+    private toolLines;
+    /** One Tool row's heading and body for the card its views resolved to. */
+    private cardLines;
+    /** The ordinary heading: the Tool name and a one-line argument summary. */
+    private nameHeading;
+    /**
+     * A generic card's rows: the Tool's declared title (falling back to the
+     * ordinary name heading) and raw-input summary, then its UI-facing content or
+     * the raw result text.
+     */
+    private genericLines;
+    /**
+     * The parenthesized suffix a generic card shows for its salient raw input.
+     * A title that already spells the input out suppresses the repetition.
+     * @param title - the card's declared title.
+     * @param rawInput - the presenter's salient input.
+     * @returns the suffix, or an empty string when it adds nothing.
+     */
+    private rawInputSuffix;
+    /** A terminal card's rows: description, command heading with cwd and exit state, then output. */
+    private terminalLines;
+    /** The exit-status pill a settled terminal card declares, when it declares one. */
+    private exitPill;
+    /** A mutation's rows: the declared title with +/- totals, then the unified diff. */
+    private diffLines;
+    /** A read card's rows: the title and window extent, then numbered file lines. */
+    private readLines;
+    /** A search card's rows: grouped matched lines or a path list, with the cap signal. */
+    private searchLines;
+    /** The cap signal a truncated search card declares. */
+    private searchCap;
+    /** A web card's rows: the cited sources with the provider answer, or the fetch summary. */
+    private webLines;
+    /**
+     * Indent and bound pre-styled body rows to the viewport width.
+     * @param rows - the already-styled rows.
+     * @param width - the viewport width.
+     * @returns the indented rows, folded when they exceed the body budget.
+     */
+    private boundedRows;
+    /** A mutation's heading: the Tool's own card title and the change's +/- totals. */
+    private diffHeading;
+    /**
+     * A diff card's indented body, folded to a bounded number of rows.
+     * @param card - the built diff card.
+     * @param width - the viewport width.
+     * @returns the indented body lines.
+     */
+    private diffBody;
+    /** One diff row with its role's prefix and style, truncated to the body width. */
+    private diffRow;
+}
+/** Most rows a prompt heading occupies; a longer question keeps its first rows and ends with an ellipsis. */
+export declare const PROMPT_TITLE_MAX_ROWS = 3;
+/** Rows a prompt spends outside its body at most: the wrapped heading and the blank row under it. */
+export declare const PROMPT_PANEL_CHROME_ROWS: number;
+/** Rows a multi-select picker spends on its key hint below the list. */
+export declare const MULTI_SELECT_HINT_ROWS = 1;
+/**
+ * Row budget for one prompt panel on a terminal with `rows` rows left to it.
+ * @param rows - rows available to the panel, excluding any pinned footer.
+ * @param detailed - whether the body carries scrollable detail under a control.
+ * Such a panel may take every available row, because the detail is what the user
+ * must read; a detail-less picker stays capped so a long list does not fill a
+ * tall terminal.
+ * @returns the largest panel height, keeping at least one body row.
+ */
+export declare function promptPanelRows(rows: number, detailed?: boolean): number;
+/**
+ * A modal body that shows a prompt's supporting detail above its control.
+ *
+ * `detail` is markdown the caller supplied — a plan under review, or facts a
+ * question rests on — and can be taller than the panel. The detail renders in a
+ * viewport that yields every row its control does not use; the control's
+ * rendered height, not a fixed split, sizes the viewport, so a two-option
+ * review gives the plan nearly the whole panel and a long picker leaves the
+ * plan less.
+ *
+ * Scrolling keys depend on whether the detail overflows. While it does, Up and
+ * Down scroll it by one row, PageUp and PageDown by one viewport, and the wheel
+ * by its reported lines; a control that supplies `step` is then moved with Left
+ * and Right (or Tab and Shift+Tab), which keeps those keys off the scroller.
+ * While the detail fits, every key reaches the control unchanged, so a plain
+ * picker keeps its own Up, Down, Enter, and Escape bindings.
+ */
+export declare class DetailBody implements Component {
+    private readonly control;
+    private readonly theme;
+    private readonly rows;
+    private readonly step?;
+    private readonly markdown;
+    private scrollTop;
+    /** Rows the last render gave the detail; also the PageUp/PageDown step. */
+    private viewport;
+    /** Detail rows the last render measured, for clamping a scroll. */
+    private content;
+    /**
+     * @param detail - the markdown shown above the control.
+     * @param control - the focused control that answers the prompt.
+     * @param theme - the surface theme.
+     * @param rows - the panel body's row budget, chrome excluded.
+     * @param step - moves the control's selection by one item while the detail
+     * overflows; absent when the control has no selection to move.
+     */
+    constructor(detail: string, control: Component, theme: TuiTheme, rows: number, step?: ((delta: -1 | 1) => void) | undefined);
+    /**
+     * Scroll the overflowing detail, move the control's selection, or hand the
+     * key to the control.
+     * @param data - raw key bytes.
+     */
+    handleInput(data: string): void;
+    /**
+     * Scroll the overflowing detail with the wheel, or hand the mouse event to
+     * the control. While the detail fits it leaves the wheel to the caller, so a
+     * prompt that has nothing to scroll passes it to the transcript instead.
+     * @param event - the normalized mouse event.
+     * @returns the control's result, or `handled` for a consumed wheel event.
+     */
+    handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+    /** Drop both the detail's and the control's cached render state. */
+    invalidate(): void;
+    /**
+     * Render the detail viewport followed by the control.
+     * @param width - the viewport width in columns.
+     * @returns the body lines.
+     */
+    render(width: number): string[];
+    private scrollTo;
+}
+/**
+ * A prompt heading. Its header and trailing text stay on the first row — a
+ * header labeling the question, a trailing countdown at the right edge — while
+ * the question itself wraps across the heading rows.
+ */
+export interface PromptHeading {
+    /** Dim label above the question, such as the question's header or its batch position. */
+    readonly header?: string | undefined;
+    /** The question presented to the user, wrapped across the heading rows. */
+    readonly question: string;
+    /** Text pinned to the right of the first heading row, such as a timed window's countdown. */
+    readonly trailing?: string | undefined;
+}
+/** A prompt heading: a plain line, a structured heading, or a provider of either re-evaluated each repaint. */
+export type PromptTitle = string | PromptHeading | (() => string | PromptHeading);
+/**
+ * Rows a prompt heading occupies at one width.
+ *
+ * A prompt reserves its body budget from this before the first paint, so the
+ * body never overflows the rows the heading's wrapping left it.
+ * @param value - the headed value to measure.
+ * @param width - the available columns.
+ * @returns the number of rows the panel draws for the heading.
+ */
+export declare function promptHeadingRows(value: string | PromptHeading, width: number): number;
+/**
+ * A modal panel: an optional heading, a blank row when a heading is present,
+ * and the control that handles keys. The renderer focuses the component passed
+ * to `showOverlay`, and a bare container does not forward keys, so the panel is
+ * the focused component.
+ *
+ * Escape is intercepted here instead of by the control: the control binds it
+ * together with Ctrl+C to one cancel action, so a prompt that offers a skip
+ * could not otherwise tell the two apart. Ctrl+C keeps its own meaning and
+ * reaches the control's cancel binding.
+ *
+ * The panel reads as ordinary output rather than a dialog: no border, left
+ * aligned like a transcript row. Every row is padded to the width the caller
+ * passes, though, because the renderer composites an overlay over the row it
+ * covers and leaves the rest of that row as the transcript printed it; padding
+ * the full row is what keeps the transcript from showing through beside the
+ * body, which would read as one garbled line.
+ */
+export declare class PromptPanel implements Component, Focusable {
+    private readonly title;
+    private readonly theme;
+    private readonly body;
+    /** Set by the renderer when this panel owns the keyboard. */
+    focused: boolean;
+    /** Called when the user presses Escape to move past the prompt without answering. */
+    onSkip?: () => void;
+    /** Heading and separator rows the last render drew, so a mouse event keeps the control's own coordinates. */
+    private chromeRows;
+    /**
+     * @param title - the heading, a provider evaluated on every render for a
+     * heading that changes while the panel is open, such as a countdown, or
+     * undefined for a body that supplies its own first line.
+     * @param theme - the surface theme.
+     * @param body - the control that handles keys.
+     */
+    constructor(title: PromptTitle | undefined, theme: TuiTheme, body: Component);
+    /**
+     * Answer Escape as a skip and hand every other key to the wrapped control.
+     * @param data - raw key bytes.
+     */
+    handleInput(data: string): void;
+    /**
+     * Forward a mouse event past the panel's chrome to the wrapped control, so a
+     * scrolling body reaches its own viewport at the rows it rendered. Events on
+     * the heading or blank row belong to no control.
+     * @param event - the normalized mouse event, in panel coordinates.
+     * @returns the body's result, when it handled the event.
+     */
+    handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+    /** Drop the wrapped control's cached render state. */
+    invalidate(): void;
+    /**
+     * Render the optional heading and the body, filling every row the overlay
+     * covers.
+     * @param width - the viewport width in columns.
+     * @returns the panel lines, each exactly `width` columns wide.
+     */
+    render(width: number): string[];
+    /**
+     * Wrap the heading into at most {@link PROMPT_TITLE_MAX_ROWS} rows.
+     * @param width - the available columns.
+     * @returns the styled heading rows, or none when the panel has no heading.
+     */
+    private heading;
+    /**
+     * Pin one line of text to the right of a heading row.
+     * @param line - the heading row.
+     * @param trailing - the text to pin.
+     * @param width - the available columns.
+     * @returns the row with the trailing text at its right edge.
+     */
+    private withTrailing;
+    private row;
+}
+/**
+ * A single-select picker that answers only keyboard input.
+ *
+ * `SelectList` confirms a left click on a row and moves the highlight on the
+ * wheel; a stray click in the terminal would settle a prompt the user only meant
+ * to focus. This wrapper exposes no mouse handler, so the arrow keys move the
+ * highlight and Enter or Escape are the only ways to settle the list. It
+ * forwards the wrapped picker's own key handling, selection callbacks, and
+ * render state.
+ */
+export declare class KeyboardSelectList implements Component {
+    /** Called with the highlighted option when the user confirms. */
+    onSelect?: (item: SelectItem) => void;
+    /** Called when the user cancels. */
+    onCancel?: () => void;
+    /** Called whenever the highlighted option changes. */
+    onSelectionChange?: (item: SelectItem) => void;
+    private readonly list;
+    /**
+     * @param items - the options to show.
+     * @param maxVisible - most rows the picker shows before scrolling.
+     * @param theme - the picker theme.
+     * @param layout - the picker's column layout.
+     */
+    constructor(items: SelectItem[], maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
+    /**
+     * Forward keyboard input to the wrapped picker.
+     * @param data - raw key bytes.
+     */
+    handleInput(data: string): void;
+    /**
+     * Move the highlight onto one option.
+     * @param index - the option index; clamped to the list.
+     */
+    setSelectedIndex(index: number): void;
+    /**
+     * The highlighted option.
+     * @returns the highlighted option, or null when the list shows none.
+     */
+    getSelectedItem(): SelectItem | null;
+    /** Drop the wrapped picker's cached render state. */
+    invalidate(): void;
+    /**
+     * Render the wrapped picker's options.
+     * @param width - the viewport width in columns.
+     * @returns the picker lines.
+     */
+    render(width: number): string[];
+}
+/**
+ * A modal picker whose options are checked with Space and submitted with Enter.
+ *
+ * The single-select picker confirms on the same key that moves, so a checkable
+ * list cannot reuse it unchanged: this owns the check state and wraps the picker
+ * for navigation, scrolling, and rendering. Every option it passes down is its
+ * own copy whose label carries the marker, so a toggle rewrites that label in
+ * place — the picker renders the objects it was given, so the marker follows the
+ * check state without a second rendering path. Enter submits the checked options
+ * in list order and is ignored while none is checked, so a stray confirm cannot
+ * answer with an empty selection; Escape still cancels.
+ */
+export declare class MultiSelectList implements Component {
+    /** Called with the checked options in list order when the user confirms. */
+    onConfirm?: (items: SelectItem[]) => void;
+    /** Called when the user cancels the picker. */
+    onCancel?: () => void;
+    /** Called whenever the highlighted option changes. */
+    onSelectionChange?: (item: SelectItem) => void;
+    private readonly list;
+    private readonly items;
+    private readonly theme;
+    /**
+     * @param items - the options to check.
+     * @param maxVisible - most rows the picker shows before scrolling.
+     * @param theme - the picker theme shared with the single-select list.
+     * @param layout - the picker's column layout.
+     */
+    constructor(items: SelectItem[], maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
+    /**
+     * Toggle the highlighted option on Space, confirm the checked ones on Enter,
+     * and hand every other key to the wrapped picker.
+     * @param data - raw key bytes.
+     */
+    handleInput(data: string): void;
+    /**
+     * Move the highlight onto one option.
+     * @param index - the option index; clamped to the list.
+     */
+    setSelectedIndex(index: number): void;
+    /** Drop the wrapped picker's cached render state. */
+    invalidate(): void;
+    /**
+     * Render the options with their check markers and the key hint.
+     * @param width - the viewport width in columns.
+     * @returns the picker lines, the hint last.
+     */
+    render(width: number): string[];
+    /**
+     * The checked options.
+     * @returns the checked options in list order.
+     */
+    selectedItems(): SelectItem[];
+    private toggle;
+}
+/** Context occupancy the footer reports against the routed model's capacity. */
+export interface TuiContextStatus {
+    /** Estimated tokens of the next request's prompt. */
+    tokens: number;
+    /** The routed model's context window in tokens. */
+    window: number;
+    /** Whether the mounted engine compacts automatically at this pressure. */
+    automatic: boolean;
+}
+/** Delegated subagents the footer summarizes. */
+export interface TuiSubagentStatus {
+    /** Children this session's catalogs record, at any depth. */
+    total: number;
+    /** Children whose activation is still running. */
+    running: number;
+}
+/** Whole-log token figures the footer's bottom-right group reports. */
+export interface TuiSessionStats {
+    /** Decode throughput averaged over decode-timed steps; absent until one is timed. */
+    tokensPerSecond?: number | undefined;
+    /** Billed prompt tokens over the whole log: uncached input plus cache reads and writes. */
+    promptTokens: number;
+    /** Provider-reported output tokens over the whole log. */
+    outputTokens: number;
+    /** Prompt tokens the provider served from cache. */
+    cacheReadTokens: number;
+}
+/** One frame of the status bar. */
+export interface TuiStatus {
+    /** Workspace directory, abbreviated against the home directory. */
+    workspace: string;
+    /**
+     * Agent lifecycle state, `compacting` while a compaction transaction runs
+     * outside the turn lifecycle and the Agent itself stays idle, or `shell`
+     * while a local `!` command occupies the surface.
+     */
+    state: 'idle' | 'running' | 'compacting' | 'shell';
+    /** Display label for the routed model, provider-qualified when the deployment registers several. */
+    model: string;
+    /** Reasoning effort in force, when the route declares one. */
+    effort?: string | undefined;
+    /**
+     * Whether plan mode is in force, or selected to apply from the next step;
+     * absent when the deployment mounts no plan mode.
+     */
+    plan?: boolean | undefined;
+    /** Whether a clipboard image read is in flight; the identity line reports the wait. */
+    pasting?: boolean | undefined;
+    /** Context occupancy, absent until the meter reports both a pressure and a capacity. */
+    context?: TuiContextStatus | undefined;
+    /** Delegated children the session's catalogs record, absent while it has none. */
+    subagents?: TuiSubagentStatus | undefined;
+    /** Whole-log throughput and token totals; absent when the frame carries no measurement. */
+    stats?: TuiSessionStats | undefined;
+}
+/**
+ * Display label for the routed model: the provider qualifies it only when the
+ * deployment registers several, so the common single-provider footer stays short.
+ * @param provider - the routed provider.
+ * @param model - the routed model id.
+ * @param providerCount - providers the deployment registered.
+ * @returns the label the footer's right side shows.
+ */
+export declare function modelLabel(provider: string, model: string, providerCount: number): string;
+/**
+ * Display parts of the footer's bottom-right group, in display order: whole-log
+ * decode throughput, the billed token total, and the cache-hit share. A figure
+ * whose input has no data is omitted rather than shown as zero.
+ * @param stats - the whole-log token figures for one frame.
+ * @returns one text per available figure.
+ */
+export declare function sessionStatsParts(stats: TuiSessionStats): string[];
+/**
+ * The pinned footer under the composer: the workspace and Agent state against
+ * the routed model, then the context occupancy with the whole-log token figures
+ * at the bottom-right edge.
+ */
+export declare class StatusBar implements Component {
+    private readonly theme;
+    private status;
+    /**
+     * @param theme - the surface theme.
+     */
+    constructor(theme: TuiTheme);
+    /**
+     * Replace the rendered status.
+     * @param status - the current facts.
+     */
+    set(status: TuiStatus): void;
+    /** Drop cached render state. */
+    invalidate(): void;
+    /**
+     * Render the footer.
+     * @param width - the viewport width in columns.
+     * @returns the footer lines, each within `width`.
+     */
+    render(width: number): string[];
+    /**
+     * Render context occupancy and whole-log token figures for either terminal surface.
+     * @param width - the viewport width in columns.
+     * @returns the usage line within `width`.
+     */
+    renderUsage(width: number): string;
+    /** The usage line's left side: occupancy, then the delegated-work marker while any child is recorded. */
+    private usageLeft;
+    /**
+     * The delegated-work marker: `●` while at least one child runs, `○` once every
+     * recorded child has settled, with the count as running of total.
+     */
+    private subagentsPart;
+    /**
+     * Place a right side against a left side at the footer's edges.
+     *
+     * The right side yields first — truncated, then dropped — so the identity and
+     * state a user reads stay intact on a narrow terminal; only a left side wider
+     * than the terminal is truncated itself.
+     * @param left - the already styled left side.
+     * @param right - the already styled right side.
+     * @param width - the viewport width in columns.
+     * @returns one line within `width`.
+     */
+    private pairLine;
+    private headText;
+    /**
+     * The lifecycle slot: `compacting` while a compaction transaction occupies an
+     * otherwise idle Agent, because no turn status changes until it settles.
+     * @returns the styled lifecycle label.
+     */
+    private stateText;
+    private modelText;
+    /** The bottom-right group: whole-log throughput, token total, and cache-hit share. */
+    private statsRight;
+    private contextPart;
+}
+/**
+ * The composer with a placeholder.
+ *
+ * While the composer is empty, its content row shows the key hints, so the
+ * surface does not spend a footer line on keys the user already knows; the
+ * first typed character replaces them.
+ */
+export declare class PlaceholderEditor implements Component, Focusable {
+    private readonly editor;
+    private readonly theme;
+    private hint;
+    /**
+     * @param editor - the composer the user types into.
+     * @param theme - the surface theme.
+     */
+    constructor(editor: Editor, theme: TuiTheme);
+    /** Forward focus to the composer so it emits its cursor marker. */
+    get focused(): boolean;
+    set focused(value: boolean);
+    /**
+     * Replace the placeholder text.
+     * @param hint - the key hints line.
+     */
+    setHint(hint: string): void;
+    /** Forward input to the composer. */
+    handleInput(data: string): void;
+    /** Drop the composer's cached render state. */
+    invalidate(): void;
+    /**
+     * Render the composer, showing the hints in place of an empty content line.
+     * @param width - the viewport width in columns.
+     * @returns the composer lines, each within `width`.
+     */
+    render(width: number): string[];
+    /**
+     * The empty composer's content line: the hints with the cursor on their first
+     * character, so an untouched composer still shows where typing lands. A focused
+     * composer emits the hardware-cursor marker exactly as the editor does.
+     * @param width - the viewport width in columns.
+     * @returns the padded content line.
+     */
+    private placeholderLine;
+}
+//# sourceMappingURL=views.d.ts.map

package/lib/types/watch/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The viewing side of the local subagent stream: open one authenticated
+ * loopback request, parse its NDJSON frames, and report a decoded snapshot and
+ * ordered updates. This module never creates an Agent and never retries.
+ * @module @deepseek-ai/dsh-tui-app/watch/client
+ */
+import type { WatchAssistantFrame, WatchConnectionRecord, WatchExecutionState, WatchServerFrame, WatchSnapshotFrame } from './protocol.ts';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** Failure classes the viewer distinguishes. */
+export type WatchStreamFailureKind = 
+/** The service exists but refused this viewer: bad token, wrong version, or not viewable. */
+'refused'
+/** The service answered with malformed protocol data. */
+ | 'protocol'
+/** The TCP/HTTP connection or body failed. */
+ | 'network'
+/** The service reported an internal read failure. */
+ | 'service';
+/** Typed failure with a user-facing message. */
+export declare class WatchStreamError extends Error {
+    readonly kind: WatchStreamFailureKind;
+    readonly status?: number | undefined;
+    /**
+     * @param kind - the failure class.
+     * @param message - user-facing diagnostic.
+     * @param status - HTTP status when the failure came from a response.
+     */
+    constructor(kind: WatchStreamFailureKind, message: string, status?: number | undefined);
+}
+/** Opening snapshot and ordered updates delivered to one viewer. */
+export interface WatchStreamHandlers {
+    /** Apply the opening snapshot synchronously before any later frames are delivered. */
+    onSnapshot(snapshot: WatchSnapshotFrame): void;
+    /** One later committed event. */
+    onEvent(event: SessionEvent): void;
+    /** One later assistant frame. */
+    onAssistant(frame: WatchAssistantFrame): void;
+    /** Execution state changed. */
+    onStatus(status: WatchExecutionState): void;
+    /** The child finished one execution; the stream stays open for later runs. */
+    onExecutionEnd(stopReason: string): void;
+    /** The service is shutting down. */
+    onServiceClosed(): void;
+    /** The stream failed after the snapshot. */
+    onFailure(error: WatchStreamError): void;
+}
+/** One open watch stream. */
+export interface WatchStream {
+    /** The opening snapshot, already validated and decoded. */
+    readonly snapshot: WatchSnapshotFrame;
+    /** Close the local side without reporting a failure. */
+    close(): void;
+}
+/**
+ * Open one watch stream and wait for its snapshot.
+ * @param record - the published connection record.
+ * @param sessionId - the child session requested.
+ * @param handlers - callbacks for frames after the snapshot.
+ * @returns the snapshot and a close handle.
+ * @throws {WatchStreamError} when the request, response, or opening frame fails.
+ */
+export declare function openWatchStream(record: WatchConnectionRecord, sessionId: string, handlers: WatchStreamHandlers): Promise<WatchStream>;
+/**
+ * Parse and validate one NDJSON line.
+ * @param line - one complete JSON line without its terminator.
+ * @returns the validated frame.
+ * @throws {WatchStreamError} when the line is malformed or unknown.
+ */
+export declare function parseServerFrame(line: string): WatchServerFrame;
+//# sourceMappingURL=client.d.ts.map

package/lib/types/watch/history.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read-only history access for the watch viewer.
+ *
+ * History mode opens the persistence read handle only: it takes no write lock,
+ * restores no Agent, and issues no model request.
+ * @module @deepseek-ai/dsh-tui-app/watch/history
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session';
+/** One stored session cut the viewer folds. */
+export interface WatchHistory {
+    /** Stored session header. */
+    readonly header: SessionHeader;
+    /** Committed events in sequence order. */
+    readonly events: readonly SessionEvent[];
+}
+/**
+ * Read a stored child session without activating it.
+ * @param ctx - context carrying the optional persistence service.
+ * @param sessionId - the stored session to read.
+ * @returns the header and every committed event.
+ * @throws when persistence is unmounted, the session is absent, or the read fails.
+ */
+export declare function readWatchHistory(ctx: Context, sessionId: string): Promise<WatchHistory>;
+//# sourceMappingURL=history.d.ts.map