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

package/lib/types/clipboard.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Native clipboard text writes and raster image reads.
+ *
+ * A terminal delivers pasted text through bracketed paste, but no terminal
+ * protocol carries image bytes to a full-screen application, so the app asks
+ * the platform's own clipboard reader and stages the result in a temporary
+ * file. Each reader is a documented external program: `osascript` running the
+ * JavaScript automation runtime reads `NSPasteboard` directly on macOS,
+ * `System.Windows.Forms.Clipboard` through PowerShell on Windows and WSL,
+ * `wl-paste` on Wayland, and `xclip` on X11. The declared media type is the
+ * reader's, verified against the decoded bytes by the attachment service, so a
+ * mislabeled payload is refused rather than stored.
+ * @module @deepseek-ai/dsh-tui-app/clipboard
+ */
+import type { ImageMediaType } from '@deepseek-ai/dsh-attachment';
+/** One raster image read from the system clipboard, before attachment admission. */
+export interface ClipboardImage {
+    /** Encoded image bytes exactly as the platform reader produced them. */
+    data: Uint8Array;
+    /** Media type the reader declared; admission verifies it against the bytes. */
+    mediaType: ImageMediaType;
+}
+/**
+ * Run one clipboard reader.
+ * @param command - the reader program.
+ * @param args - its arguments.
+ * @param timeoutMs - how long the program may run.
+ * @param input - optional UTF-8 text supplied on stdin.
+ * @returns the program's stdout, or undefined when it is absent, fails, or times out.
+ */
+export type ClipboardCommandRunner = (command: string, args: readonly string[], timeoutMs: number, input?: string) => Promise<Buffer | undefined>;
+/** Process facts and readers a clipboard read may substitute. */
+export interface ClipboardReadOptions {
+    /** Platform to read from. */
+    platform?: NodeJS.Platform;
+    /** Environment consulted for the display session. */
+    env?: NodeJS.ProcessEnv;
+    /** Command runner. */
+    run?: ClipboardCommandRunner;
+    /** Create the path a staging reader writes. */
+    stagePath?: () => string;
+    /** Read and delete one staged file; undefined when the reader wrote no bytes. */
+    readStaged?: (path: string) => Promise<Uint8Array | undefined>;
+}
+/** This process's readers, used for every field a caller substitutes nothing for. */
+export declare const systemClipboard: Required<ClipboardReadOptions>;
+/**
+ * Read one image from the system clipboard.
+ * @param options - substituted process facts and readers; omitted fields read this process's clipboard.
+ * @returns the clipboard image, or undefined when the clipboard holds no accepted image or no reader is available.
+ */
+export declare function readClipboardImage(options?: ClipboardReadOptions): Promise<ClipboardImage | undefined>;
+/**
+ * Copy a selection using the local macOS pasteboard, or the terminal elsewhere.
+ * @param text - exact selected text, supplied to pbcopy through stdin.
+ * @param write - terminal output for the OSC 52 path.
+ * @param options - process facts and command runner; defaults to this process.
+ * @returns native command success, or true after an unacknowledged OSC 52 write.
+ */
+export declare function copyClipboardText(text: string, write: (data: string) => void, options?: Pick<ClipboardReadOptions, 'platform' | 'env' | 'run'>): Promise<boolean>;
+//# sourceMappingURL=clipboard.d.ts.map

package/lib/types/commands.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The composer's slash-command surface: the app's own commands, the registry's
+ * catalog, and dispatch through `ctx.commands`. A registry command runs against
+ * the Agent without creating a model message; the app renders its settled text.
+ * @module @deepseek-ai/dsh-tui-app/commands
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AutocompleteProvider, SelectItem } from '@earendil-works/pi-tui';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { CommandExecution } from '@deepseek-ai/dsh-commands';
+import type { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+/** One local command the composer handles without the registry. */
+export interface LocalCommand {
+    /** Command name without the leading slash. */
+    name: string;
+    /** Discovery description. */
+    description: string;
+    /** Whether the command takes trailing input. */
+    takesInput: boolean;
+}
+/** App-owned commands take precedence over registry commands and skill gestures. */
+export declare const LOCAL_COMMANDS: readonly LocalCommand[];
+/**
+ * Parse one slash line.
+ * @param line - the composer's submitted text.
+ * @returns the command name and the remainder, or undefined when the line is not a command.
+ */
+export declare function parseCommand(line: string): {
+    name: string;
+    input: string;
+} | undefined;
+/**
+ * Build the completion catalog: the app's commands followed by the registry's
+ * effective commands for this Agent.
+ * @param ctx - context carrying the command registry.
+ * @param agent - the Agent whose scoped commands apply.
+ * @returns selectable entries carrying the slash value.
+ */
+export declare function commandCatalog(ctx: Context, agent: Agent): SelectItem[];
+/**
+ * Complete leading slash names with commands taking precedence over user-invocable skills.
+ * @param ctx - context carrying the optional command and skill registries.
+ * @param agent - the Agent whose scoped catalogs apply.
+ * @param cwd - workspace used for skill discovery.
+ * @returns the editor provider; each request reads the current catalogs and
+ *   honors cancellation, and completion preserves the token the user typed.
+ */
+export declare function slashAutocomplete(ctx: Context, agent: Agent, cwd: string): AutocompleteProvider;
+/**
+ * Execute one registry command against the owning Agent.
+ * @param ctx - context carrying the command registry.
+ * @param agent - the Agent the command targets.
+ * @param line - the full command line, including the leading slash.
+ * @param signal - cancellation lifetime of the dispatch.
+ * @returns the settled execution, or undefined when the name is unknown.
+ */
+export declare function executeCommand(ctx: Context, agent: Agent, line: string, signal: AbortSignal): Promise<CommandExecution | undefined>;
+/** One selectable model route. */
+export interface ModelChoice {
+    /** Registered provider route. */
+    provider: string;
+    /** Provider-owned model id. */
+    model: string;
+    /** Label shown in the picker. */
+    label: string;
+    /** Supporting detail shown beside the label. */
+    description: string;
+}
+/**
+ * List the model routes the live LLM registry advertises.
+ * @param ctx - context carrying the LLM registry.
+ * @returns one choice per reachable provider model, in registry order; providers that fail discovery are omitted.
+ */
+export declare function listModelChoices(ctx: Context): Promise<ModelChoice[]>;
+/** One selectable reasoning effort, or the routed model's provider default. */
+export interface EffortChoice {
+    /** Opaque effort id the adapter accepts, or undefined to send no effort. */
+    effort: ReasoningEffortId | undefined;
+    /** Label shown in the picker. */
+    label: string;
+    /** Supporting detail shown beside the label. */
+    description: string;
+}
+/**
+ * List the reasoning efforts one routed model declares.
+ *
+ * A route whose adapter declares no efforts has no effort control at all. A
+ * route that declares efforts without a default also accepts the provider's own
+ * behavior, which the first choice clears back to; when the adapter does
+ * declare a default, selecting that effort is the same request, so no separate
+ * clear is offered.
+ * @param ctx - context carrying the LLM registry.
+ * @param route - the routed provider and model.
+ * @returns the selectable efforts in adapter order, or undefined when the route declares none.
+ * @throws when the route has no registered adapter or its metadata is invalid.
+ */
+export declare function listEffortChoices(ctx: Context, route: {
+    provider: string;
+    model: string;
+}): Promise<EffortChoice[] | undefined>;
+//# sourceMappingURL=commands.d.ts.map

package/lib/types/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The terminal application's deployment-varying settings.
+ * @module @deepseek-ai/dsh-tui-app/config
+ */
+import z from '@deepseek-ai/schemastery';
+/**
+ * Where the TUI draws:
+ *
+ * - `'alternate'` — the alternate screen buffer with the app's own scroll
+ *   window. The composer and status bar stay pinned and PageUp/PageDown scroll
+ *   the transcript; the terminal's own scrollback is untouched.
+ * - `'inline'` — the terminal's normal screen. The transcript grows past the
+ *   viewport and the terminal's native scrollback keeps the history, while the
+ *   composer stays at the bottom.
+ */
+export type TuiScreen = 'alternate' | 'inline';
+/**
+ * Which palette the surface renders with:
+ *
+ * - `'auto'` — follow the terminal background signal when the host exports one,
+ *   otherwise the dark palette.
+ * - `'dark'` / `'light'` — pin the palette, for a host that gives no signal or
+ *   one the user disagrees with.
+ */
+export type TuiColorScheme = 'auto' | 'dark' | 'light';
+/** The terminal application's settings. */
+export interface Config {
+    /** Screen strategy; see {@link TuiScreen}. */
+    screen: TuiScreen;
+    /** Palette selection; see {@link TuiColorScheme}. */
+    colorScheme: TuiColorScheme;
+}
+/** Validated settings for the `tui-app` row. */
+export declare const Config: z<Config>;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/diagnostics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Console capture for a surface that owns the terminal.
+ *
+ * A full-screen TUI writes its frame through the terminal object, so a
+ * `console` call reaches the same device outside the renderer. The text lands on
+ * whatever row the cursor occupies, and the differential renderer leaves it
+ * there until that row's own content changes. The capture replaces the console
+ * methods for the lifetime of the surface and hands each formatted write to a
+ * sink that puts it where the renderer controls it.
+ * @module @deepseek-ai/dsh-tui-app/diagnostics
+ */
+/**
+ * Replace the process console methods until the returned function restores them.
+ *
+ * The wrapper formats arguments the way the console would have printed them and
+ * never writes to the terminal itself. It is installed before the renderer
+ * starts and removed after the renderer has restored the screen, so its sink
+ * runs only while the surface owns the terminal.
+ * @param sink - receives each plain-text message; an empty message reports nothing.
+ * @returns the idempotent restore function.
+ */
+export declare function captureConsole(sink: (text: string) => void): () => void;
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/types/diff.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure file-diff model for the transcript: turns the `FileDiff` hunks a
+ * mutation Tool declared into the row list the terminal draws, recovering the
+ * context/added/removed role of each line from the hunk's two sides.
+ * @module @deepseek-ai/dsh-tui-app/diff
+ */
+import type { FileDiff } from '@deepseek-ai/dsh-tools';
+/** Role of one rendered diff row. */
+export type DiffRowKind = 'path' | 'gap' | 'context' | 'added' | 'removed';
+/** One rendered diff row: its role and its verbatim text. */
+export interface DiffRow {
+    kind: DiffRowKind;
+    text: string;
+}
+/** A file diff's complete body plus the heading figures. */
+export interface DiffCard {
+    /** Every body row, in file order, before any height fold. */
+    rows: DiffRow[];
+    /** Added lines across every hunk. */
+    added: number;
+    /** Removed lines across every hunk. */
+    removed: number;
+    /** Distinct paths the hunks touch. */
+    files: number;
+}
+/**
+ * Build the body rows and heading figures for a list of declared hunks.
+ *
+ * A single-file card omits the path row because its heading already names the
+ * file; a card spanning several files opens each file with its path, and a
+ * later hunk of the same file opens with a gap marker, since the two hunks are
+ * not adjacent lines.
+ * @param diffs - the hunks a mutation Tool declared, in tool order.
+ * @returns the rows, the +/- totals, and the distinct-file count.
+ */
+export declare function buildDiffCard(diffs: readonly FileDiff[]): DiffCard;
+//# sourceMappingURL=diff.d.ts.map

package/lib/types/images.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Composer image markers: the text token that stands for one held clipboard
+ * image, and the fold that turns a submitted line back into its model-visible
+ * text and its ordered images.
+ *
+ * The composer is a text editor, so an image it holds needs a text
+ * representation that survives editing: a marker the user can delete like any
+ * other character, and that a submission reads back to decide which images the
+ * prompt still cites.
+ * @module @deepseek-ai/dsh-tui-app/images
+ */
+/**
+ * The marker text the composer holds for the image numbered `index`.
+ * @param index - the image's marker number, counted from one within the draft.
+ * @returns the marker the composer inserts and a submission reads back.
+ */
+export declare function imageMarker(index: number): string;
+/** One submitted composer line split into its text and the images it cites. */
+export interface MarkedPrompt {
+    /** The submitted line without the markers of images it still cites. */
+    text: string;
+    /** Cited image numbers, in first-appearance order and without duplicates. */
+    indices: number[];
+}
+/**
+ * Read a submitted line's image markers.
+ *
+ * A marker whose image the composer no longer holds is literal user text and
+ * stays in the prompt; a marker the composer still holds is removed, because the
+ * image travels as its own content block exactly as it does on the other
+ * surfaces.
+ * @param line - the submitted composer text.
+ * @param pending - image numbers the composer currently holds.
+ * @returns the model-visible text and the cited images in content order.
+ */
+export declare function parseImageMarkers(line: string, pending: ReadonlySet<number>): MarkedPrompt;
+//# sourceMappingURL=images.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @deepseek-ai/dsh-tui-app — the interactive terminal application over
+ * `dsh-base`. The bundle patch mounts this row together with its command-line
+ * provider; this module requires the launcher's exit request and the provider's
+ * parsed invocation, then boots the pi-tui surface against one in-process Agent
+ * and leaves process lifetime to the app's own exit request.
+ *
+ * @module @deepseek-ai/dsh-tui-app
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.ts';
+export { Config };
+export type { TuiColorScheme, TuiScreen } from './config.ts';
+export { internals, TuiApp } from './app.ts';
+export type { TuiAppOptions } from './app.ts';
+export { TUI_STARTUP_SERVICE } from './startup.ts';
+export type { TuiStartupValues } from './startup.ts';
+/** Stable Cordis plugin name. */
+export declare const name = "tui-app";
+/** Services required before the terminal UI can be built, including remembered tool approvals. */
+export declare const inject: string[];
+/**
+ * Mount the interactive terminal application.
+ * @param ctx - plugin context carrying the session, agent, and launcher services.
+ * @param config - validated app settings.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/interactions.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Terminal answerers for the two interaction seams the Agent pauses on: tool
+ * approvals and structured user questions. Approvals are answered for the
+ * app's own Agent and its live subagent descendants; every other Agent's
+ * request is delegated, so a composition that also mounts another surface
+ * keeps its own answerers authoritative. Always allow records a per-tool grant
+ * on the app's own root Agent, covering every live descendant. Questions stay
+ * restricted to the app's own Agent because a delegated child cannot ask them.
+ * A timed question is claimed through the user-questions service so this
+ * surface owns the countdown; a window that closes without an answer settles
+ * the call as pending, leaving it answerable as a late reply. A question's
+ * options end in a free-text `Other…` row, Escape skips the question, and
+ * Ctrl+C cancels the whole ask.
+ * @module @deepseek-ai/dsh-tui-app/interactions
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SelectItem } from '@earendil-works/pi-tui';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { AskUserQuestionAnswerItem, AskUserQuestionItem } from '@deepseek-ai/dsh-user-questions';
+import type { PromptTitle } from './views.ts';
+/** A heading that is a fixed value, or a provider the surface re-evaluates as it repaints. */
+export type InteractionTitle = PromptTitle;
+/**
+ * How one modal prompt settled.
+ *
+ * `skip` is Escape's own outcome, distinct from `cancel` only because a question
+ * batch advances past a skipped question while a cancelled one is abandoned;
+ * every other caller treats the two alike.
+ */
+export type PromptOutcome<T> = {
+    readonly kind: 'answer';
+    readonly value: T;
+} | {
+    readonly kind: 'skip';
+} | {
+    readonly kind: 'cancel';
+};
+/** The terminal surfaces the answerers drive. */
+export interface InteractionHost {
+    /**
+     * Ask the user to choose one item.
+     * @param title - the question shown above the list; a provider is re-evaluated on every repaint.
+     * @param items - the selectable items.
+     * @param signal - cancellation lifetime; aborting cancels the prompt.
+     * @param detail - markdown shown above the list, scrollable with Up/Down, PageUp/PageDown, and the wheel.
+     * @returns how the prompt settled: the chosen item, Escape's skip, or Ctrl+C's cancel.
+     */
+    choose(title: InteractionTitle, items: readonly SelectItem[], signal?: AbortSignal, detail?: string): Promise<PromptOutcome<SelectItem>>;
+    /**
+     * Ask the user to check any number of items.
+     * @param title - the question shown above the list; a provider is re-evaluated on every repaint.
+     * @param items - the selectable items.
+     * @param signal - cancellation lifetime; aborting cancels the prompt.
+     * @param detail - markdown shown above the list, scrollable with Up/Down, PageUp/PageDown, and the wheel.
+     * @returns how the prompt settled: the checked items in list order, Escape's skip, or Ctrl+C's cancel.
+     */
+    chooseMany(title: InteractionTitle, items: readonly SelectItem[], signal?: AbortSignal, detail?: string): Promise<PromptOutcome<SelectItem[]>>;
+    /**
+     * Ask the user for one line of text.
+     * @param title - the question shown above the input; a provider is re-evaluated on every repaint.
+     * @param signal - cancellation lifetime; aborting cancels the prompt.
+     * @param detail - markdown shown above the input, scrollable with Up/Down, PageUp/PageDown, and the wheel.
+     * @returns how the prompt settled: the entered text, Escape's skip, or Ctrl+C's cancel.
+     */
+    ask(title: InteractionTitle, signal?: AbortSignal, detail?: string): Promise<PromptOutcome<string>>;
+}
+/**
+ * Answer approvals for the app's Agent and its live subagent descendants, one
+ * request at a time. Any other Agent's request is delegated so a composition
+ * that also mounts other surfaces keeps their answerers authoritative. A
+ * request withdrawn while the prompt settles is answered `cancelled` and
+ * records no grant.
+ * @param ctx - the plugin context whose waterfall carries approval requests.
+ * @param host - the terminal prompt surface.
+ * @param owned - the Agent this app answers for.
+ * @returns a disposer removing the listener.
+ */
+export declare function installApprovalAnswerer(ctx: Context, host: InteractionHost, owned: Agent): () => void;
+/** One question's place in the batch it arrived with. */
+export interface QuestionPosition {
+    /** Zero-based index of the question. */
+    readonly index: number;
+    /** Number of questions the batch carries. */
+    readonly total: number;
+}
+/** How one question is presented: its cancellation lifetime, timed window, and batch place. */
+export interface AnswerQuestionOptions {
+    /** Cancellation lifetime of the whole request; aborting cancels the ask. */
+    readonly signal?: AbortSignal | undefined;
+    /** Absolute epoch milliseconds a timed window ends at; the heading counts down to it. */
+    readonly deadline?: number | undefined;
+    /** The question's place in a multi-question batch; a lone question shows none. */
+    readonly position?: QuestionPosition | undefined;
+}
+/**
+ * Answer one structured question.
+ *
+ * A question with options opens a picker whose last row is `Other…`: choosing it
+ * collects a free-form answer, which replaces a single selection and
+ * accompanies a multi-selection. Escape skips the question with an empty
+ * selection so the batch advances; Ctrl+C cancels the whole request.
+ *
+ * A plan review is special: its non-approve choice is not an answer to send
+ * back. The terminal has no separate "talk it over" action, so choosing Keep
+ * planning means the user kept planning to speak instead — leaving the question
+ * unanswered hands the turn back so the agent stays in plan mode and waits for
+ * their adjustment rather than revising immediately. Every unanswered path
+ * there hands the turn back the same way, while `Other…` carries the user's own
+ * feedback to the waiting model.
+ * @param host - the terminal prompt surface.
+ * @param question - the question to present.
+ * @param options - cancellation lifetime, timed window, and batch place.
+ * @returns the answer item, or undefined when the user cancelled the prompt or
+ * chose to keep planning instead of answering.
+ */
+export declare function answerQuestion(host: InteractionHost, question: AskUserQuestionItem, options?: AnswerQuestionOptions): Promise<AskUserQuestionAnswerItem | undefined>;
+/**
+ * Answer structured user questions for one owned Agent. A dismissed prompt
+ * fails the asking Tool with the seam's aborted code instead of leaving the
+ * request unanswered; a plan review the user keeps planning fails it with the
+ * cancelled code, the one plan mode reads as "the user took the turn back".
+ *
+ * A timed request is claimed and counted down by this surface: an unanswered or
+ * dismissed window resolves the Tool's pending result rather than failing it,
+ * so the question stays answerable through `/questions`.
+ * @param ctx - the plugin context whose waterfall carries question requests.
+ * @param host - the terminal prompt surface.
+ * @param owned - the Agent this app answers for.
+ * @returns a disposer removing the listener.
+ */
+export declare function installQuestionAnswerer(ctx: Context, host: InteractionHost, owned: Agent): () => void;
+//# sourceMappingURL=interactions.d.ts.map

package/lib/types/measurement.d.ts

@@ -0,0 +1,18 @@
+/** Shared projection-to-footer measurements for interactive and watched sessions. */
+import type { ProjectionSnapshot } from '@deepseek-ai/dsh-session-projection';
+import type { TuiContextStatus, TuiSessionStats } from './views.ts';
+/** Footer facts derived from one projection snapshot. */
+export interface TuiMeasurement {
+    /** Context occupancy, absent until the meter reports both a pressure and a capacity. */
+    context: TuiContextStatus | undefined;
+    /** Whole-log throughput and token totals; zero counts render nothing. */
+    stats: TuiSessionStats;
+}
+/**
+ * Convert registered usage projections to terminal footer facts.
+ * @param values - projection values at one committed log position, if available.
+ * @param automatic - whether the owning engine compacts automatically.
+ * @returns available context occupancy and whole-log token figures.
+ */
+export declare function measureUsage(values: ProjectionSnapshot['values'] | undefined, automatic: boolean): TuiMeasurement;
+//# sourceMappingURL=measurement.d.ts.map

package/lib/types/session.d.ts

@@ -0,0 +1,151 @@
+/**
+ * One interactive session: create or resume the single Agent this TUI drives,
+ * submit prompts, switch the model route, and tear the Agent down. The registry
+ * handle is the app's ownership capability, so no other consumer can dispose
+ * this Agent.
+ * @module @deepseek-ai/dsh-tui-app/session
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, ModelSelection } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+/** One delegated child as the `/subagents` listing reports it. */
+export interface TuiSubagent {
+    /** Durable child session id, also the argument `dsh watch` takes. */
+    readonly id: SessionId;
+    /** Catalog mode recorded by the parent when the child was created. */
+    readonly mode: 'one-shot' | 'continuable' | 'external' | 'unknown';
+    /** Durable creation label; absent for an unlabeled one-shot or external child. */
+    readonly label?: string;
+    /** Edge distance from this session; direct children are 1. */
+    readonly depth: number;
+    /** Whether the child's current local activation is still running. */
+    readonly running: boolean;
+}
+/** Invocation facts and route overrides for a session this app opens. */
+export interface TuiSessionOptions {
+    /** Working directory recorded on the session and used as the tool workspace root. */
+    cwd: string;
+    /** Provider override from the command line, absent when the deployment default applies. */
+    provider?: string | undefined;
+    /** Model override from the command line, absent when the deployment default applies. */
+    model?: string | undefined;
+}
+/** One live interactive session and the Agent behind it. */
+export declare class TuiSession {
+    private readonly ctx;
+    private readonly handle;
+    /** Child session ids whose current local activation has not settled yet. */
+    private readonly runningSubagents;
+    /** Cached descendants, refreshed through the mounted subagent service. */
+    private readonly subagentRows;
+    /** Failure from the last descendant read; `/subagents` reports it. */
+    private subagentError;
+    /** In-flight descendant refresh shared by concurrent callers. */
+    private subagentRefresh;
+    /** A refresh was requested while one was already running. */
+    private subagentRefreshQueued;
+    /** Retires this session's subagent lifecycle subscriptions. */
+    private readonly subagentSubscriptions;
+    private constructor();
+    /**
+     * Create a fresh Agent and its session.
+     * @param ctx - context carrying the agent registry and default-model service.
+     * @param options - invocation facts and route overrides.
+     * @returns the live session.
+     */
+    static create(ctx: Context, options: TuiSessionOptions): Promise<TuiSession>;
+    /**
+     * Resume a stored session under a live Agent.
+     * @param ctx - context carrying the agent registry, session store, and persistence.
+     * @param sessionId - the stored session to resume.
+     * @param options - invocation facts and route overrides.
+     * @returns the live session.
+     */
+    static resume(ctx: Context, sessionId: string, options: TuiSessionOptions): Promise<TuiSession>;
+    /** The Agent this session owns. */
+    get agent(): Agent;
+    /** The Agent's live session log. */
+    get session(): Session;
+    /** The route in force for the next step. */
+    get route(): ModelSelection;
+    /**
+     * The stored events that seeded this session at resume, oldest first. The
+     * read stops at the Session's first live sequence, so events appended after
+     * resume stay with the live `session/event` stream instead of being folded
+     * twice.
+     * @returns the seed events in sequence order; empty when the deployment mounts no persistence backend.
+     * @throws when the backend refuses to open or read the stored session.
+     */
+    history(): Promise<readonly SessionEvent[]>;
+    /** Whether the Agent currently has work in flight. */
+    get running(): boolean;
+    /** Whether the Agent or any live subagent descendant has work in flight. */
+    get busy(): boolean;
+    /**
+     * Whether any local subagent activation of this session is still running.
+     * @returns true while at least one `subagent/start` lacks its `subagent/end`.
+     */
+    hasRunningSubagents(): boolean;
+    /**
+     * The delegated children last read through the subagent service, in catalog
+     * pre-order. The panel and the footer read this cache; {@link refreshSubagents}
+     * updates it without blocking a render.
+     * @returns the cached rows; empty until the first refresh settles.
+     */
+    subagents(): readonly TuiSubagent[];
+    /**
+     * The last descendant read's failure, for the panel to report instead of an
+     * empty list.
+     * @returns the failure message, or undefined after a successful read.
+     */
+    subagentsFailure(): string | undefined;
+    /**
+     * Read this session's delegated descendants through `ctx.subagents`, which
+     * owns catalog observation, cold-Session reads, and branch diagnostics.
+     * Concurrent callers share one refresh; a request that arrives mid-read runs
+     * again after it so the cache never settles on a stale catalog.
+     * @returns after the cache reflects the latest completed read.
+     */
+    refreshSubagents(): Promise<void>;
+    /**
+     * Take one pending refresh request.
+     * @returns whether another refresh was requested while the last read ran.
+     */
+    private consumeRefreshRequest;
+    /**
+     * Read the service's descendant rows and project them for the terminal.
+     * @returns the rows in catalog pre-order.
+     * @throws when the composition mounts no subagent service.
+     */
+    private readSubagents;
+    /**
+     * Queue one human prompt as its own turn.
+     * @param content - the prompt's content blocks in message order.
+     */
+    submit(content: readonly ContentBlock[]): void;
+    /**
+     * Submit steering that the running turn consumes at its next step, or that
+     * starts a turn when the Agent is idle.
+     * @param content - the steering content blocks in message order.
+     */
+    steer(content: readonly ContentBlock[]): void;
+    /**
+     * Abort the active turn, drop pending input, and interrupt every running
+     * subagent descendant under this Agent's ancestor authority; a user interrupt
+     * owns the cause. A composition without the subagent service stops only this
+     * Agent, and one child whose interrupt is rejected is logged without keeping
+     * its siblings running.
+     */
+    cancel(): void;
+    /**
+     * Switch the route used by later steps.
+     * @param route - the new provider and model.
+     */
+    selectModel(route: ModelSelection): void;
+    /** Drain this session's durable events to storage. */
+    flush(): Promise<void>;
+    /** Stop the Agent, unregister it, and unwind its scoped world. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=session.d.ts.map