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

package/lib/types/shell.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Local `!` commands: one foreground shell execution whose streamed output is a
+ * transcript row. Nothing here reaches the model or the session log; the
+ * executor, sandbox policy, and output bounds belong to the mounted services.
+ * @module @deepseek-ai/dsh-tui-app/shell
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { ShellEntry, TerminalTranscript } from './transcript.ts';
+/**
+ * Wall-clock bound requested for one local command. The executor clamps it to
+ * its own `maxTimeoutMs`, so this is a request rather than a promise.
+ */
+export declare const SHELL_COMMAND_TIMEOUT_MS = 600000;
+/** What {@link ShellRunner.submit} learned. */
+export type ShellStart = {
+    readonly started: true;
+} | {
+    readonly started: false;
+    readonly reason: string;
+};
+/** Everything the runner needs from the application. */
+export interface ShellRunnerOptions {
+    /** Context carrying the shell executor, sandbox policy, and working directory. */
+    ctx: Context;
+    /** Transcript model the row is appended to. */
+    transcript: TerminalTranscript;
+    /** The live session whose sandbox policy applies. */
+    session: () => Session;
+    /** Directory the command starts in. */
+    cwd: () => string;
+    /** Repaint after a row changed. */
+    changed: () => void;
+}
+/**
+ * Run one `!` command at a time and stream it into a transcript row.
+ *
+ * The application refuses a second command while {@link running} is true, so
+ * this class owns no queue; it owns cancellation, streamed reads, and the
+ * settled facts the row shows.
+ */
+export declare class ShellRunner {
+    private readonly options;
+    private current;
+    /**
+     * @param options - context, transcript, session and directory accessors, and the repaint hook.
+     */
+    constructor(options: ShellRunnerOptions);
+    /** Whether a command currently occupies the surface. */
+    get running(): boolean;
+    /**
+     * Start one command.
+     *
+     * A refusal is returned rather than thrown so the caller can leave the
+     * composer untouched; the only refusals are composition faults, because the
+     * caller already owns the occupancy rules.
+     * @param command - the text after the leading `!`.
+     * @returns whether the row was appended, or why it was not.
+     */
+    submit(command: string): ShellStart;
+    /**
+     * Stop the running command, keeping the output it already produced.
+     * @returns whether a command was running.
+     */
+    cancel(): boolean;
+    /**
+     * Stop the running command and wait for it to close; used when the session
+     * switches or the application exits, where the row cannot outlive the view.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Poll one read into the row.
+     * @param state - the execution being folded.
+     * @param final - whether this is the last read before settlement.
+     */
+    private poll;
+    /**
+     * Prepare one execution and follow it to settlement.
+     * @param prepared - the spawning promise returned by the executor.
+     * @param state - the row this execution belongs to.
+     */
+    private start;
+    /**
+     * Write one settled outcome into the row and release the surface.
+     * @param state - the executed row.
+     * @param result - the executor's settled facts.
+     * @param timer - the poll timer started with this execution.
+     */
+    private settle;
+    /**
+     * Write a preparation failure into the row and release the surface.
+     * @param state - the row that never ran.
+     * @param error - the rejection that ended preparation.
+     */
+    private fail;
+}
+/**
+ * The right-aligned label of one shell row: whether it is local-only and which
+ * sandbox mode confined it.
+ * @param entry - the shell row.
+ * @returns the label text.
+ */
+export declare function shellLabel(entry: ShellEntry): string;
+/**
+ * The closing line of one shell row: its state and, once settled, how long it
+ * took and how it ended.
+ * @param entry - the shell row.
+ * @returns the status text.
+ */
+export declare function shellStatusLine(entry: ShellEntry): string;
+//# sourceMappingURL=shell.d.ts.map

package/lib/types/startup.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The terminal app's command-line provider: it parses the `dsh --profile tui`
+ * flag family (`--resume`, `--provider`, `--model`, `--watch`) and its `--help` text, then
+ * publishes the values as {@link TUI_STARTUP_SERVICE}. The TUI row injects that
+ * service, so a help or usage invocation — which publishes nothing — mounts no
+ * terminal UI.
+ * @module @deepseek-ai/dsh-tui-app/startup
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "tui-startup";
+/** Services required before the flags can be resolved. */
+export declare const inject: string[];
+/** Service provided by this plugin and injected by the TUI row. */
+export declare const TUI_STARTUP_SERVICE = "tuiStartup";
+/** What the TUI row reads from {@link TUI_STARTUP_SERVICE}. */
+export interface TuiStartupValues {
+    /** Stored session id to resume, absent when this invocation starts a new session. */
+    resume?: string | undefined;
+    /** Provider route this session starts on, absent when the deployment default applies. */
+    provider?: string | undefined;
+    /** Model id this session starts on, absent when the deployment default applies. */
+    model?: string | undefined;
+    /** Stored child session id to view read-only, absent for an interactive session. */
+    watch?: string | undefined;
+}
+/**
+ * Parse and publish the TUI invocation as an ordinary Cordis service. A partial
+ * route is a usage error, so on rejection (and on `--help`) nothing is provided
+ * and the TUI row stays pending.
+ * @param ctx - plugin context carrying the command line.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=startup.d.ts.map

package/lib/types/subagents.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The pinned `/subagents` panel: one line per delegated child, read from the
+ * live session catalogs on every render and scrolled inside a fixed row budget.
+ * The panel never writes a transcript row, so the main Agent can keep streaming
+ * without moving it.
+ * @module @deepseek-ai/dsh-tui-app/subagents
+ */
+import type { Component, TuiMouseEvent, TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TuiTheme } from './ansi.ts';
+import type { TuiSubagent } from './session.ts';
+/**
+ * A scrollable list of the session's delegated children.
+ *
+ * The row provider runs on every render, so a child that starts or settles
+ * while the panel is open appears without reopening the command. The panel
+ * owns only its scroll position; the transcript underneath keeps following the
+ * Agent's output.
+ */
+export declare class SubagentPanel implements Component {
+    private readonly read;
+    private readonly failure;
+    private readonly capacity;
+    private readonly theme;
+    private readonly repaint;
+    /** Called when the user dismisses the panel with Enter or Ctrl+C. */
+    onClose?: () => void;
+    /** First row of the list currently shown. */
+    private offset;
+    /**
+     * @param read - cached children, read on every render and key event.
+     * @param failure - why the last descendant read failed, if it did.
+     * @param capacity - body rows the panel may draw, summary and scroll hint included.
+     * @param theme - the surface theme.
+     * @param repaint - requests a render after the panel scrolls itself.
+     */
+    constructor(read: () => readonly TuiSubagent[], failure: () => string | undefined, capacity: number, theme: TuiTheme, repaint: () => void);
+    /**
+     * Close on Enter or Ctrl+C, scroll the list on the arrow and page keys, and
+     * leave every other key alone. Escape is the surrounding panel's skip.
+     * @param data - raw key bytes.
+     */
+    handleInput(data: string): void;
+    /**
+     * Scroll the overflowing list with the wheel; leave the wheel to the
+     * transcript while every row fits.
+     * @param event - the normalized mouse event.
+     * @returns `handled` for a consumed wheel event, otherwise undefined.
+     */
+    handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+    /** The panel keeps no cached render state. */
+    invalidate(): void;
+    /**
+     * Render the summary and the visible rows.
+     * @param width - the viewport width in columns.
+     * @returns the panel's rows, clipped to `width` by the surrounding panel.
+     */
+    render(width: number): string[];
+    /**
+     * Read the cached children, or none while the last read failure stands.
+     * @returns the children, or an empty list after a failure.
+     */
+    private rows;
+    /** Rows one page of the scroll spends. */
+    private viewport;
+    /**
+     * Move the list by `delta` rows and request a repaint when the offset changes.
+     * @param delta - signed row delta.
+     */
+    private move;
+    /** The header naming the running and total counts. */
+    private summary;
+    /** One child's row: state, label, mode, and the watch command. */
+    private row;
+}
+//# sourceMappingURL=subagents.d.ts.map

package/lib/types/tool-view.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Host tool-presentation bridge for the terminal surface: the Host consumer
+ * of `ToolDefinition.presentCall`/`presentResult` anticipated by the
+ * [decision](../../../../.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md).
+ * The bridge resolves the acting scope's Tool definition and hands the declared
+ * call or result view to the transcript unchanged; the terminal renderer
+ * switches on the card tag and degrades to the surface's ordinary tool row when
+ * a Tool declares no view.
+ * @module @deepseek-ai/dsh-tui-app/tool-view
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolCallView, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools';
+/** Resolves the presentation view a Tool declared for one call and its settled result. */
+export interface ToolPresentationResolver {
+    /**
+     * @param name - the Tool name as the model requested it.
+     * @param argsJson - the raw arguments JSON the model produced.
+     * @returns the pending call view, or undefined when the Tool declares none.
+     */
+    call(name: string, argsJson: string): ToolCallView | undefined;
+    /**
+     * @param name - the Tool name as the model requested it.
+     * @param argsJson - the raw arguments JSON the model produced.
+     * @param result - the settled result projection the durable event carries.
+     * @returns the completed result view, or undefined when the Tool declares none.
+     */
+    result(name: string, argsJson: string, result: ToolResult): ToolResultView | undefined;
+}
+/**
+ * Build the resolver over the live Tool registry.
+ * @param ctx - the application context carrying the optional `tools` service.
+ * @param agent - reads the Agent whose scope owns the call; the registry resolves the
+ *   definition the acting scope sees, so a scoped shadow renders as it executed.
+ *   Returning undefined reads the deployment's global tool view, which is what a
+ *   read-only viewer with no live Agent can present.
+ * @returns the resolver the transcript folds with.
+ */
+export declare function createToolPresentationResolver(ctx: Context, agent: () => object | undefined): ToolPresentationResolver;
+//# sourceMappingURL=tool-view.d.ts.map

package/lib/types/transcript.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The transcript model: durable Session events and live Assistant stream frames
+ * folded into the ordered rows the terminal surface renders. The fold is pure
+ * with respect to I/O, so rendering tests drive it with recorded events instead
+ * of a terminal.
+ * @module @deepseek-ai/dsh-tui-app/transcript
+ */
+import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools';
+import type { ApprovalOutcome, ApprovalRequestId } from '@deepseek-ai/dsh-user-approval';
+import type { ToolPresentationResolver } from './tool-view.ts';
+/** A human prompt row. */
+export interface UserEntry {
+    kind: 'user';
+    /** Row identity, stable for the life of the row. */
+    id: number;
+    /** The prompt text, without the composer markers of its images. */
+    text: string;
+    /** One label per attached image, in content order; empty for a text-only prompt. */
+    images: readonly string[];
+}
+/** An assistant message row. */
+export interface AssistantEntry {
+    kind: 'assistant';
+    /** Row identity; negative while the message is still streaming. */
+    id: number;
+    /** The assembled visible text. */
+    text: string;
+    /** Whether the turn was cancelled while this message streamed. */
+    interrupted: boolean;
+}
+/** Provider reasoning retained before its assistant message or attempt outcome. */
+export interface ReasoningEntry {
+    kind: 'reasoning';
+    /** Row identity; negative while the reasoning is still streaming. */
+    id: number;
+    /** The reasoning text streamed so far. */
+    text: string;
+}
+/**
+ * One Tool call and its settled outcome. The fold replaces this row when the
+ * result settles rather than mutating it, so durable rows keep one identity.
+ */
+export interface ToolEntry {
+    kind: 'tool';
+    /** Row identity, stable for the life of the row. */
+    id: number;
+    /** Correlating call id. */
+    callId: string;
+    /** Registered Tool name. */
+    name: string;
+    /** Raw arguments JSON as the model produced it. */
+    args: string;
+    /** Whether the call is still running or has settled. */
+    status: 'running' | 'ok' | 'error';
+    /** Visible result text, or empty while running. */
+    result: string;
+    /** Failure identity when the Tool reported an error. */
+    error?: string;
+    /** The presentation view the Tool declared for its call, when it declared one. */
+    callView?: ToolCallView | undefined;
+    /** The presentation view the Tool declared for its settled result; absent keeps the call view. */
+    resultView?: ToolResultView | undefined;
+}
+/** An app-level account that belongs to no message: injected context, turn outcomes, discarded attempts. */
+export interface NoticeEntry {
+    kind: 'notice';
+    /** Row identity, stable for the life of the row. */
+    id: number;
+    /** Whether the row reads as a failure. */
+    level: 'info' | 'error';
+    /** One-line account of what happened. */
+    text: string;
+}
+/**
+ * One local `!` shell command and its streamed output. The row belongs to this
+ * process only: it never enters the session log, so a new or resumed session
+ * drops it, and nothing in it reaches a model request.
+ */
+export interface ShellEntry {
+    kind: 'shell';
+    /** Row identity, stable while the row updates in place. */
+    id: number;
+    /** The command text the user typed after `!`. */
+    command: string;
+    /** Whether the command still runs or how it settled. */
+    status: 'running' | 'ok' | 'error' | 'cancelled' | 'timedout';
+    /** Combined stdout and stderr streamed so far. */
+    output: string;
+    /** Sandbox mode the command ran under; absent when the executor does not confine. */
+    mode?: string | undefined;
+    /** Process exit code; absent while running and while a signal ended it. */
+    exitCode?: number | null | undefined;
+    /** Terminating signal, when a signal ended the command. */
+    signal?: string | undefined;
+    /** Wall-clock time from submission to settlement; absent while running. */
+    durationMs?: number | undefined;
+    /** Bound the executor applied, read by the timeout status line. */
+    timeoutMs?: number | undefined;
+    /** True when the executor dropped output the row cannot show. */
+    lossy?: boolean | undefined;
+    /** Spill file holding the complete output, when truncation produced one. */
+    spillPath?: string | undefined;
+    /** True when the sandbox denied a file operation the command attempted. */
+    sandboxDenied?: boolean | undefined;
+}
+/**
+ * One approval request and its settled outcome, folded from the durable audit
+ * pair. The decision replaces the pending row in place so the request keeps one
+ * identity on screen.
+ */
+export interface ApprovalEntry {
+    kind: 'approval';
+    /** Row identity, stable across the decision. */
+    id: number;
+    /** Request identity pairing the ask with its decision. */
+    requestId: ApprovalRequestId;
+    /** Tool the decision is about. */
+    toolName: string;
+    /** The asker's explanation, when it supplied one. */
+    reason?: string;
+    /** Settled outcome; absent while the request is still waiting. */
+    outcome?: ApprovalOutcome;
+    /** The allowed outcome is covered by a remembered grant for this tool. */
+    remembered?: true;
+}
+/** One rendered row of the transcript. */
+export type TranscriptEntry = UserEntry | AssistantEntry | ReasoningEntry | ToolEntry | NoticeEntry | ShellEntry | ApprovalEntry;
+/**
+ * Join the visible text of a content block list, ignoring non-text blocks.
+ * @param blocks - message or tool-result content.
+ * @returns the concatenated text blocks.
+ */
+export declare function textOfBlocks(blocks: readonly ContentBlock[]): string;
+/**
+ * The ordered transcript of one Agent session. Durable rows come from the
+ * session log; live rows come from `agent/assistant-stream` and are replaced by
+ * their durable settlement.
+ */
+export declare class TerminalTranscript {
+    private readonly views?;
+    private rows;
+    private readonly toolByCallId;
+    private readonly approvalById;
+    private nextId;
+    private liveText;
+    private liveReasoning;
+    private attempt;
+    private changeCount;
+    /**
+     * @param views - resolves the diff card a Tool declared for its call and result;
+     * absent keeps every Tool row in its raw name-and-summary form.
+     */
+    constructor(views?: ToolPresentationResolver | undefined);
+    /** Monotone change counter; a view compares it to decide whether to rebuild. */
+    get revision(): number;
+    /** Whether an Assistant attempt is currently streaming. */
+    get streaming(): boolean;
+    /**
+     * The rows to render, in order: durable rows followed by the live attempt.
+     * @returns the current transcript.
+     */
+    entries(): readonly TranscriptEntry[];
+    /** Drop every row, for a new or resumed session. */
+    reset(): void;
+    /**
+     * Fold one durable Session event into the transcript.
+     * @param event - the appended event.
+     * @returns whether the visible transcript changed.
+     */
+    applyEvent(event: SessionEvent): boolean;
+    /**
+     * Fold one live Assistant stream frame into the transcript.
+     * @param frame - the published frame.
+     * @returns whether the visible transcript changed.
+     */
+    applyFrame(frame: AssistantStreamFrame): boolean;
+    private applyChunk;
+    private applyUserMessage;
+    private applyAssistantMessage;
+    private applyAttempt;
+    private appendReasoning;
+    private applyToolCall;
+    private applyToolResult;
+    private applyApprovalAsked;
+    private applyApprovalDecided;
+    private applyTurnEnd;
+    /**
+     * Append an app-level notice row.
+     * @param level - whether the row reads as a failure.
+     * @param text - the one-line account.
+     * @returns always true, since a row was appended.
+     */
+    notice(level: NoticeEntry['level'], text: string): boolean;
+    /**
+     * Append one local shell row in its running state.
+     * @param command - the command text after `!`.
+     * @param mode - the sandbox mode the executor will apply, when it confines.
+     * @returns the row identity later updates address.
+     */
+    appendShell(command: string, mode: string | undefined): number;
+    /**
+     * Replace one shell row with its next state.
+     *
+     * The fold replaces the row object instead of mutating it: the view caches a
+     * row's rendered lines against that object, so a fresh object is what makes
+     * streamed output repaint.
+     * @param id - the row appended by {@link appendShell}.
+     * @param patch - fields to replace; omitted fields keep their current value.
+     */
+    updateShell(id: number, patch: Partial<Omit<ShellEntry, 'kind' | 'id'>>): void;
+    private changed;
+}
+//# sourceMappingURL=transcript.d.ts.map