indusagi-coding-agent 0.1.59 → 0.1.61

package/dist/types/console/input/complete.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Completion source — structured suggestions for the composer's prompt line.
+ *
+ * As the user types, the composer can offer two kinds of completion:
+ *
+ *   1. **Slash commands** — when the buffer begins with `/`, the leading token is
+ *      matched (prefix, case-insensitive) against the {@link SlashRegistry}, and
+ *      every command whose name or alias starts with the typed stem is offered.
+ *   2. **File paths** — when the active token begins with `@` (an attachment
+ *      reference) or looks like a path stem, the trailing path component is
+ *      completed against a directory listing.
+ *
+ * Both branches resolve to the same {@link Suggestion} shape so the surface's
+ * completion window renders and applies them uniformly. The whole module is
+ * pure: the slash branch reads the registry (plain data), and the path branch
+ * takes an injected {@link DirReader} rather than calling `fs` itself, so the
+ * suggestion logic is unit-tested with a synthetic filesystem and no I/O.
+ *
+ * The entry point is {@link completeAt}: given the buffer, the caret offset, and
+ * the registry + dir-reader sources, it returns a {@link CompletionResult} —
+ * the active token's span (so the surface knows what to replace), the suggestion
+ * list, and the completion `kind`. {@link applySuggestion} then splices a chosen
+ * suggestion back into the buffer, returning the new buffer and caret.
+ */
+import type { SlashRegistry } from "../contract";
+/** Which source produced a batch of suggestions. */
+export type CompletionKind = "slash" | "path" | "none";
+/**
+ * One structured completion candidate.
+ *
+ * `value` is the text the surface splices in when this suggestion is accepted
+ * (already including any leading sigil — `/` for a command, `@`/trailing slash
+ * for a path). `label` is what the completion window shows; `detail` is the
+ * one-line description (a command summary, or a `dir`/`file` hint). `isDir`
+ * marks a directory so the surface can keep the window open for further descent.
+ */
+export interface Suggestion {
+    /** The text spliced into the buffer when accepted. */
+    readonly value: string;
+    /** The primary text shown in the completion window. */
+    readonly label: string;
+    /** A one-line description shown beside the label. */
+    readonly detail: string;
+    /** Whether this path suggestion is a directory (false for slash commands). */
+    readonly isDir: boolean;
+}
+/**
+ * The half-open `[start, end)` span of the buffer the active token occupies.
+ *
+ * The surface replaces exactly this span when a suggestion is applied, so the
+ * sigil and any preceding text are preserved.
+ */
+export interface TokenSpan {
+    /** Inclusive start offset of the active token. */
+    readonly start: number;
+    /** Exclusive end offset of the active token. */
+    readonly end: number;
+}
+/**
+ * The full result of asking for completion at a caret position.
+ *
+ * `kind` reports which source answered (`none` when nothing applies), `span` is
+ * the token to replace, and `suggestions` is the ranked candidate list (empty
+ * when nothing matched).
+ */
+export interface CompletionResult {
+    /** Which source produced the suggestions. */
+    readonly kind: CompletionKind;
+    /** The buffer span the active token occupies. */
+    readonly span: TokenSpan;
+    /** The ranked candidate list (possibly empty). */
+    readonly suggestions: readonly Suggestion[];
+}
+/** A pure directory listing: each name is a leaf, flagged dir-or-file. */
+export interface DirEntry {
+    /** The leaf name (no path separators). */
+    readonly name: string;
+    /** Whether the entry is a directory. */
+    readonly isDir: boolean;
+}
+/**
+ * An injected directory reader so the path branch stays pure and testable.
+ *
+ * Given a directory path (relative to the working dir), it returns that
+ * directory's immediate entries, or an empty list when the path does not exist
+ * or cannot be read. The live console binds this to a real `fs.readdir`; tests
+ * bind it to a synthetic tree.
+ */
+export type DirReader = (dirPath: string) => readonly DirEntry[];
+/**
+ * Compute the completion offering at a caret position.
+ *
+ * Routes on the active token's stem: a `/` at buffer-start yields slash
+ * completion; a `@`/path-like stem yields path completion; anything else yields
+ * the inert {@link CompletionKind} `none`. Pure with respect to both sources —
+ * the registry is data and the dir-reader is injected — so the entire decision
+ * is unit-testable.
+ *
+ * @param buffer   the composer text
+ * @param caret    the caret offset within the buffer
+ * @param registry the slash-command registry to match against
+ * @param readDir  the directory reader the path branch lists through
+ */
+export declare function completeAt(buffer: string, caret: number, registry: SlashRegistry, readDir: DirReader): CompletionResult;
+/**
+ * Splice an accepted suggestion back into the buffer.
+ *
+ * Pure: replaces the active token's span with the suggestion's `value` and
+ * returns the rewritten buffer plus the caret placed at the end of the inserted
+ * value. The surface re-runs {@link completeAt} afterward so descending into a
+ * directory (whose value ends in `/`) immediately offers the next level.
+ *
+ * @param buffer     the composer text the completion was computed against
+ * @param span       the token span returned by {@link completeAt}
+ * @param suggestion the candidate the user accepted
+ */
+export declare function applySuggestion(buffer: string, span: TokenSpan, suggestion: Suggestion): {
+    buffer: string;
+    caret: number;
+};

package/dist/types/console/input/dir-reader.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Directory reader — the live `fs`-backed implementation of {@link DirReader}.
+ *
+ * The completion engine ({@link completeAt}) is pure: its path branch lists a
+ * directory through an injected {@link DirReader} rather than touching the disk
+ * itself, so the suggestion logic stays unit-testable against a synthetic tree.
+ * This module is the one place that binds that seam to a real filesystem.
+ *
+ * {@link createDirReader} returns a reader that resolves a (possibly relative)
+ * directory path against a base directory — the session working directory by
+ * default — and lists its immediate entries as {@link DirEntry} records. Every
+ * failure mode (a missing directory, a permission error, a path that names a
+ * file) collapses to an empty list, so the composer never throws while the user
+ * is mid-type. A symlink is classified by whether it ultimately resolves to a
+ * directory, falling back to its own dirent flag when the target cannot be
+ * stat-ed.
+ */
+import type { DirReader } from "./complete";
+/**
+ * Build a live {@link DirReader} rooted at `cwd`.
+ *
+ * The returned reader resolves each requested directory path against `cwd`
+ * (an absolute request is used as-is), lists it, and maps each child to a
+ * {@link DirEntry}. Any error returns `[]`.
+ *
+ * @param cwd the base directory relative requests resolve against
+ */
+export declare function createDirReader(cwd?: string): DirReader;

package/dist/types/console/input/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Console input — public barrel for the pure composer-input modules.
+ *
+ * Three decoupled, Ink-free, fully-tested modules the surface's `useInput`
+ * handler composes:
+ *
+ *   - **keymap** — classify a raw `(input, key)` event into a console
+ *     {@link ConsoleIntent}, and fold double-tap chords with {@link advanceChord}.
+ *   - **paste** — collapse a large clipboard burst behind a {@link PasteVault}
+ *     marker ({@link coalescePaste}) and re-expand at submit ({@link expandMarkers}).
+ *   - **complete** — produce structured slash/path {@link Suggestion}s
+ *     ({@link completeAt}) and splice an accepted one back ({@link applySuggestion}).
+ *
+ * The surface owns the live values (the chord latch, the paste vault, the
+ * highlighted-suggestion index) and the timers; every decision lives in these
+ * pure functions.
+ */
+export type { KeyChord, ConsoleVerb, ConsoleIntent, ChordOutcome, ChordLatch, ChordStep, } from "./keymap";
+export { NO_INTENT, readKey, NO_CHORD, advanceChord } from "./keymap";
+export type { PasteThresholds, PasteVault, PasteCapture, } from "./paste";
+export { PASTE_THRESHOLDS, PASTE_BURST_GAP_MS, EMPTY_PASTE_VAULT, pasteMarker, classifyPaste, coalescePaste, expandMarkers, hasMarkers, } from "./paste";
+export type { CompletionKind, Suggestion, TokenSpan, CompletionResult, DirEntry, DirReader, } from "./complete";
+export { completeAt, applySuggestion } from "./complete";
+export { createDirReader } from "./dir-reader";

package/dist/types/console/input/input.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Console input — pure-module unit tests (no Ink, no fs, no timers).
+ *
+ * Three concerns, exercised against plain data:
+ *   1. keymap — {@link readKey} classifies modifier combos / named keys / text,
+ *      and {@link advanceChord} latches double-tap escape/clear chords.
+ *   2. paste — {@link classifyPaste} thresholds, {@link coalescePaste} marker
+ *      minting into an immutable {@link PasteVault}, and {@link expandMarkers}
+ *      round-tripping the hidden body back at submit time.
+ *   3. complete — {@link completeAt} routes slash vs path vs none, ranks
+ *      matches, and {@link applySuggestion} splices a choice back into the buffer
+ *      — the path branch driven by a synthetic {@link DirReader}.
+ */
+export {};

package/dist/types/console/input/keymap.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Keymap — pure translation of raw terminal key events into console intents.
+ *
+ * The console's `useInput` handler is a thin shell: it forwards the `(input,
+ * key)` pair Ink hands it straight into {@link readKey}, which classifies the
+ * keystroke into one of the console's own {@link ConsoleIntent} verbs. All the
+ * branching — modifier combos, arrow navigation, the chorded escape/clear
+ * double-taps — lives here as a pure function over plain data, so it can be
+ * unit-tested without mounting Ink and so the component never grows a tangle of
+ * `if (key.ctrl && input === "u")` conditionals inline.
+ *
+ * The input shape is dictated by the framework hook: Ink's `useInput` invokes
+ * its handler with `(input: string, key: Key)` where {@link KeyChord} mirrors
+ * Ink's `Key` flag bag (arrows, return, escape, ctrl, shift, tab, backspace,
+ * delete, meta, …). We re-declare the bag *structurally* here — a plain record
+ * of booleans plus the literal text — so the keymap depends on a data shape,
+ * not on importing the hook itself. The live handler passes Ink's `key` value
+ * directly; it is assignable because the field names match.
+ *
+ * The output is the console's own intent vocabulary, NOT a mirror of any
+ * upstream action enum. An intent is a small tagged record: a `verb` plus the
+ * minimal payload the reducer/surface needs to act (the literal text for an
+ * insert, the signed delta for a caret move). The surface maps each intent to a
+ * {@link ConsoleEvent} dispatch or a host callback; the keymap itself performs
+ * no effects.
+ *
+ * Chording (double-tap escape → tree, double-tap clear → exit) is *stateful*
+ * across keystrokes, so it is kept out of the pure classifier: {@link readKey}
+ * is memoryless, and {@link advanceChord} folds a prior {@link ChordLatch} plus
+ * a fresh intent into the next latch, reporting whether a chord fired. The
+ * surface owns the latch value and the timeout that expires it.
+ */
+import type { ModalKind } from "../contract";
+/**
+ * The boolean flag bag the framework input hook reports alongside the typed
+ * text — re-declared structurally so this module owns no hook import.
+ *
+ * Every field is the framework's own naming for the corresponding physical key
+ * or modifier. The live `useInput` handler passes its `key` argument straight
+ * in; it satisfies this shape by field-name compatibility.
+ */
+export interface KeyChord {
+    readonly upArrow: boolean;
+    readonly downArrow: boolean;
+    readonly leftArrow: boolean;
+    readonly rightArrow: boolean;
+    readonly pageUp: boolean;
+    readonly pageDown: boolean;
+    readonly return: boolean;
+    readonly escape: boolean;
+    readonly ctrl: boolean;
+    readonly shift: boolean;
+    readonly tab: boolean;
+    readonly backspace: boolean;
+    readonly delete: boolean;
+    readonly meta: boolean;
+}
+/**
+ * The console's own keystroke-intent verbs.
+ *
+ * Deliberately *not* a mirror of any upstream keybinding enum: each verb names
+ * what the console does, grouped by concern.
+ *
+ *   Editing
+ *     - `text:type`        — printable text to splice at the caret.
+ *     - `text:newline`     — insert a hard line break (soft submit guard).
+ *     - `edit:erasePrev`   — delete the grapheme before the caret.
+ *     - `edit:eraseNext`   — delete the grapheme after the caret.
+ *     - `edit:clearLine`   — wipe the whole composer buffer.
+ *
+ *   Caret / navigation
+ *     - `nav:left` / `nav:right`   — step the caret one column.
+ *     - `nav:home` / `nav:end`     — jump to buffer start / end.
+ *     - `nav:up` / `nav:down`      — recall older / newer history (or move in a list).
+ *
+ *   Session control
+ *     - `flow:submit`      — commit the buffer as a turn.
+ *     - `flow:dismiss`     — escape: close an overlay / cancel completion.
+ *     - `flow:accept`      — tab: accept the highlighted completion.
+ *     - `flow:interrupt`   — abort an in-flight turn.
+ *     - `flow:suspend`     — background the process (job control).
+ *     - `flow:cycleModel`  — rotate to the next model.
+ *
+ *   Model / reasoning
+ *     - `model:cycleThinking` — advance the reasoning-effort ladder one step.
+ *
+ *   Queue
+ *     - `queue:dequeue`    — pull the most recently queued input back into the
+ *       composer so it can be edited or dropped.
+ *
+ *   Input sources
+ *     - `input:pasteImage` — stage an image off the OS clipboard and splice its
+ *       temp path into the buffer.
+ *     - `input:externalEditor` — hand the buffer to `$EDITOR` and read it back.
+ *
+ *   Overlays
+ *     - `overlay:open`     — raise a global overlay (settings / sessions /
+ *       model pickers) directly from a control chord, without typing a slash
+ *       command. The target overlay rides in {@link ConsoleIntent.overlay}.
+ *
+ *   View toggles
+ *     - `view:expandTools` — flip whether collapsed tool output (bash / file /
+ *       grep / edit cards) is rendered in full or summarised.
+ *     - `view:toggleReasoning` — show/hide the assistant's thinking blocks live.
+ *
+ *   Inert
+ *     - `none`             — the keystroke carries no console meaning.
+ */
+export type ConsoleVerb = "text:type" | "text:newline" | "edit:erasePrev" | "edit:eraseNext" | "edit:clearLine" | "nav:left" | "nav:right" | "nav:home" | "nav:end" | "nav:up" | "nav:down" | "flow:submit" | "flow:dismiss" | "flow:accept" | "flow:interrupt" | "flow:suspend" | "flow:cycleModel" | "model:cycleThinking" | "queue:dequeue" | "input:pasteImage" | "input:externalEditor" | "overlay:open" | "view:expandTools" | "view:toggleReasoning" | "none";
+/**
+ * A classified keystroke: a {@link ConsoleVerb} plus the small payload a verb
+ * may carry — the literal text for a `text:type` insert, or the target overlay
+ * for an `overlay:open`. Every other verb is self-contained, so both payload
+ * fields are optional and present only on their owning verb.
+ */
+export interface ConsoleIntent {
+    /** What the keystroke means to the console. */
+    readonly verb: ConsoleVerb;
+    /** The literal text to splice, present only for `text:type`. */
+    readonly text?: string;
+    /** The overlay to raise, present only for `overlay:open`. */
+    readonly overlay?: ModalKind;
+}
+/** The inert intent — a keystroke the console ignores. */
+export declare const NO_INTENT: ConsoleIntent;
+/**
+ * Classify one raw key event into a single {@link ConsoleIntent}.
+ *
+ * Pure and memoryless: identical inputs always yield identical intents, and no
+ * cross-keystroke state (chords, timeouts) is consulted — that is the surface's
+ * job via {@link advanceChord}. Resolution order is deliberate: control combos
+ * and named keys win over raw text, so a `Ctrl+U` never also types "u".
+ *
+ * @param input the literal text the hook reports (may be empty for a bare key)
+ * @param key   the framework flag bag describing the physical key + modifiers
+ */
+export declare function readKey(input: string, key: KeyChord): ConsoleIntent;
+/**
+ * Which verbs participate in a double-tap chord, and what the second tap fires.
+ *
+ * A first tap of `flow:dismiss` (escape) primes a chord; a second tap within
+ * the surface's window fires `dismiss×2` (open the transcript tree). A first tap
+ * of `edit:clearLine` (Ctrl+U on an already-empty buffer) primes a chord whose
+ * second tap fires `clear×2` (request exit). Any other intent breaks the latch.
+ */
+export type ChordOutcome = "dismiss×2" | "clear×2";
+/**
+ * The cross-keystroke latch the surface carries between key events.
+ *
+ * `armed` is the verb a prior keystroke primed (or `null` when no chord is in
+ * flight). The surface resets it to `null` when its timeout expires.
+ */
+export interface ChordLatch {
+    /** The verb a previous keystroke armed, or `null` when nothing is primed. */
+    readonly armed: string | null;
+}
+/** A fresh, unarmed latch. */
+export declare const NO_CHORD: ChordLatch;
+/**
+ * The result of folding a fresh intent into the prior chord latch.
+ *
+ * `next` is the latch to carry forward; `fired` is the chord outcome when this
+ * keystroke completed a double-tap, otherwise `null`.
+ */
+export interface ChordStep {
+    /** The latch to carry into the next keystroke. */
+    readonly next: ChordLatch;
+    /** The chord that fired on this keystroke, or `null` if none did. */
+    readonly fired: ChordOutcome | null;
+}
+/**
+ * Fold a fresh {@link ConsoleIntent} into the prior {@link ChordLatch}.
+ *
+ * Pure: given the same latch and intent it always yields the same step. If the
+ * incoming verb matches the armed verb and that verb is chord-eligible, the
+ * chord fires and the latch resets. If the incoming verb is chord-eligible but
+ * the latch was empty (or armed with a different verb), it arms. Any other
+ * intent clears the latch. The timeout that expires a stale latch is the
+ * surface's responsibility (it simply resets to {@link NO_CHORD}).
+ *
+ * @param latch  the latch carried from the previous keystroke
+ * @param intent the freshly classified intent for this keystroke
+ */
+export declare function advanceChord(latch: ChordLatch, intent: ConsoleIntent): ChordStep;

package/dist/types/console/input/paste.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Paste coalescing — collapse a large clipboard burst into one compact marker.
+ *
+ * A terminal in bracketed-paste mode delivers a multi-line paste to the input
+ * hook as a single fat `input` string (or, on terminals without bracketing, as
+ * a rapid burst of per-character events). Splicing thousands of characters into
+ * the visible composer makes the editor unusable. The console instead replaces
+ * a large paste with a short placeholder token — a {@link PasteMarker} — that
+ * stands in for the hidden body, then re-expands every marker back to its
+ * original text at submit time.
+ *
+ * This module is the pure machinery behind that:
+ *
+ *   1. {@link classifyPaste} — decide whether a chunk is "large" (worth hiding)
+ *      from its line/char extent, using {@link PASTE_THRESHOLDS}.
+ *   2. {@link PasteVault} — an immutable store mapping each marker token to the
+ *      text it stands for, minted in submission order.
+ *   3. {@link coalescePaste} — fold a large chunk into a vault, returning the
+ *      marker token to splice plus the grown vault.
+ *   4. {@link expandMarkers} — at submit time, rewrite every marker token in the
+ *      buffer back to the stored body.
+ *
+ * All four are pure functions over plain data — no Ink, no refs, no timers — so
+ * the whole paste pipeline is unit-tested in isolation. The component owns only
+ * the live vault value and the burst-coalescing timer; the decisions are here.
+ *
+ * The marker format is the console's own: `‹clip N · K lines›`, where `N` is the
+ * 1-based mint order and `K` is the hidden line count. It is chosen to be
+ * visually distinct in the composer, unambiguous to match, and trivial to strip.
+ */
+/**
+ * The size at or above which a pasted chunk is hidden behind a marker.
+ *
+ * A chunk qualifies if it spans at least {@link lines} newlines *or* at least
+ * {@link chars} characters — whichever trips first — so both a tall short paste
+ * and a wide single-line paste are caught.
+ */
+export interface PasteThresholds {
+    /** Minimum newline count to treat a chunk as a large paste. */
+    readonly lines: number;
+    /** Minimum character count to treat a chunk as a large paste. */
+    readonly chars: number;
+}
+/** The default cut-offs above which a paste is coalesced into a marker. */
+export declare const PASTE_THRESHOLDS: PasteThresholds;
+/**
+ * The maximum gap, in milliseconds, between per-character events still treated
+ * as one burst.
+ *
+ * On terminals that do not bracket pastes, the hook sees many tiny events in
+ * quick succession; the surface accumulates them while consecutive events land
+ * within this window, then classifies the assembled chunk once the gap exceeds
+ * it. Exposed as data so the coalescing timer and any test share one value.
+ */
+export declare const PASTE_BURST_GAP_MS = 24;
+/** The console's own placeholder format for a hidden paste body. */
+export declare function pasteMarker(ordinal: number, lineCount: number): string;
+/**
+ * Decide whether a pasted chunk is large enough to hide behind a marker.
+ *
+ * Pure: a chunk is "large" when its newline count reaches the line threshold or
+ * its length reaches the char threshold. Small chunks are spliced verbatim by
+ * the caller; large ones are routed through {@link coalescePaste}.
+ *
+ * @param chunk      the assembled paste text
+ * @param thresholds the cut-offs to test against (defaults to {@link PASTE_THRESHOLDS})
+ */
+export declare function classifyPaste(chunk: string, thresholds?: PasteThresholds): "inline" | "coalesce";
+/**
+ * The immutable marker → body store.
+ *
+ * `bodies` maps each minted marker token to the exact text it hides; `minted`
+ * is the running count that drives the next ordinal. The store is replaced (not
+ * mutated) on every coalesce, so the surface holds it as a plain value and React
+ * reconciliation stays correct.
+ */
+export interface PasteVault {
+    /** Marker token → the original pasted text it stands for. */
+    readonly bodies: ReadonlyMap<string, string>;
+    /** How many markers have been minted so far (the next ordinal is this + 1). */
+    readonly minted: number;
+}
+/** A fresh, empty vault. */
+export declare const EMPTY_PASTE_VAULT: PasteVault;
+/**
+ * The outcome of folding a large paste into a vault.
+ *
+ * `marker` is the placeholder token the caller splices into the composer at the
+ * caret; `vault` is the grown store to carry forward.
+ */
+export interface PasteCapture {
+    /** The placeholder token to insert in place of the hidden body. */
+    readonly marker: string;
+    /** The vault grown by this capture. */
+    readonly vault: PasteVault;
+}
+/**
+ * Mint a marker for a large paste and record its body in a fresh vault.
+ *
+ * Pure: derives the next ordinal from `vault.minted`, formats the marker with
+ * the hidden line count, and returns a new vault with the body recorded. The
+ * caller is expected to have already classified `body` as `coalesce`; passing a
+ * small body still works but is rarely useful.
+ *
+ * @param vault the store to grow (defaults to {@link EMPTY_PASTE_VAULT})
+ * @param body  the full pasted text to hide
+ */
+export declare function coalescePaste(body: string, vault?: PasteVault): PasteCapture;
+/**
+ * Rewrite every paste marker in a buffer back to the text it stands for.
+ *
+ * Pure: scans the buffer for marker tokens and replaces each with its vault
+ * body. A marker with no matching vault entry (e.g. the user deleted half a
+ * token, or pasted a look-alike) is left verbatim, so expansion never throws
+ * and never loses unrelated text. This is the inverse of {@link coalescePaste}
+ * and is run once at submit time.
+ *
+ * @param buffer the composer text possibly containing markers
+ * @param vault  the store minted during the current edit
+ */
+export declare function expandMarkers(buffer: string, vault: PasteVault): string;
+/**
+ * Report whether a buffer still contains any minted paste marker.
+ *
+ * A pure convenience the surface uses to skip the expansion pass entirely when
+ * nothing was coalesced.
+ *
+ * @param buffer the composer text to scan
+ * @param vault  the store of minted markers
+ */
+export declare function hasMarkers(buffer: string, vault: PasteVault): boolean;

package/dist/types/console/mount.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Console mount — render the interactive surface and resolve on exit.
+ *
+ * The single entry point a run mode calls to take over the terminal: it
+ * resolves the colour scheme, assembles the {@link ConsoleProps}, renders the
+ * {@link TerminalConsole} through Ink's `render`, and returns a promise that
+ * settles when the surface tears down (the user exits, or `requestExit` fires).
+ *
+ * This is the only console module that performs the actual Ink mount; everything
+ * it composes (the reducer, theme, slash registry, input modules, surface
+ * components) is pure or presentational. Keeping the mount here lets the rest of
+ * the subsystem stay testable without an Ink runtime.
+ */
+import type { OverlayServices, SessionConductor, SlashRegistry } from "./contract";
+/**
+ * Options for {@link mountConsole}.
+ *
+ * Everything is optional with a sensible default: the theme falls back to the
+ * default scheme, the slash registry to the built-in catalog, and the seeds to
+ * empty. The conductor is the only required input and is passed positionally.
+ */
+export interface MountConsoleOptions {
+    /** The colour scheme name to resolve (falls back to the default). */
+    readonly scheme?: string | null;
+    /** The slash registry to dispatch against (defaults to the built-in catalog). */
+    readonly slash?: SlashRegistry;
+    /** An optional first user turn to submit on mount. */
+    readonly initialInput?: string;
+    /** Optional local image paths to attach to the first turn. */
+    readonly initialImages?: readonly string[];
+    /** Whether to render verbose diagnostics in the banner. */
+    readonly verbose?: boolean;
+    /** The runtime handles the modal overlays drive; absent on headless paths. */
+    readonly services?: OverlayServices;
+}
+/**
+ * The handle a {@link mountConsole} call resolves with once the surface exits.
+ */
+export interface MountResult {
+    /** Whether the surface tore down cleanly. */
+    readonly clean: boolean;
+}
+/**
+ * Render the interactive console for a session and resolve when it exits.
+ *
+ * Assembles the props, mounts {@link TerminalConsole} via Ink's `render`, and
+ * wires an `onExit` callback (and Ink's `waitUntilExit`) so the returned promise
+ * settles when the surface is dismissed.
+ *
+ * @param conductor the session this console drives
+ * @param opts      optional theme / registry / seed overrides
+ */
+export declare function mountConsole(conductor: SessionConductor, opts?: MountConsoleOptions): Promise<MountResult>;

package/dist/types/console/overlays/auth.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Auth overlays — the sign-in / sign-out and plugin dialogs.
+ *
+ * This group owns the four modal kinds tied to credentials and host-supplied
+ * overlays: the provider sign-in launcher (`signIn`), the sign-out confirmation
+ * (`signOut`), the in-flight OAuth device/redirect flow (`oauth`), and a
+ * plugin-supplied select/confirm/input/custom overlay (`plugin`). It is mounted
+ * unconditionally by {@link import("./host").OverlayHost}, which routes by
+ * {@link ModalState.kind}; this component renders a dialog body only for one of
+ * its own kinds and is otherwise inert.
+ *
+ * Each kind drives an {@link OverlayServices} handle then returns to the
+ * composer: `signIn` enumerates the merged provider directory and hands a
+ * browser provider off to the `oauth` kind (api-key providers post a status and
+ * close); `signOut` lists the saved accounts across providers and removes the
+ * chosen one through the vault; `oauth` runs the framework login flow, threading
+ * its url/prompt/progress callbacks into a local overlay state the dialog reads;
+ * `plugin` presents the host-supplied surface name and closes. React/Ink are
+ * obtained the same way the surface component is (default React export from
+ * `indusagi/react-host`, `Box`/`Text` from `indusagi/react-host/ink`).
+ */
+import type { OverlayGroupProps } from "./pickers";
+/**
+ * The auth overlay group: sign-in, sign-out, OAuth, and plugin overlays.
+ *
+ * Renders a dialog body only when the active modal kind is one of this group's
+ * own; every other kind (and an absent {@link OverlayServices}) yields nothing.
+ *
+ * @param props the forwarded overlay props
+ */
+export declare function AuthOverlays(props: OverlayGroupProps): JSX.Element | null;

package/dist/types/console/overlays/host.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OverlayHost — the single mount point for every modal overlay.
+ *
+ * The console surface raises overlays by writing a {@link ModalState} into the
+ * reducer; this component is the one place that turns that state into a rendered
+ * dialog. Rather than a hand-written `switch` over {@link ModalKind}, it mounts
+ * three group components unconditionally and forwards each the same props — the
+ * active {@link ModalState}, the {@link OverlayServices} runtime, the theme
+ * adapter, the {@link ConsoleDispatch}, and a `closeModal` callback. Each group
+ * owns a disjoint slice of the kind space and renders a body only for its own
+ * kinds:
+ *
+ *   - {@link PickerOverlays}  — `models`, `scopedModels`, `theme`, `settings`.
+ *   - {@link SessionOverlays} — `sessions`, `tree`, `userTurns`.
+ *   - {@link AuthOverlays}    — `signIn`, `signOut`, `oauth`, `plugin`.
+ *
+ * When no overlay is raised (`kind === "none"`) the host renders nothing, so the
+ * composer keeps focus and the groups are never mounted needlessly.
+ */
+import type { ConsoleDispatch, InkThemeAdapter, ModalState, OverlayServices } from "../contract";
+/**
+ * The props the console surface threads into {@link OverlayHost}.
+ *
+ * The same five fields are forwarded verbatim to each overlay group; the host
+ * adds no routing logic of its own beyond the `none` short-circuit.
+ */
+export interface OverlayHostProps {
+    /** The active modal overlay (kind + opaque payload). */
+    readonly modal: ModalState;
+    /** The runtime handles overlays drive; absent on headless mount paths. */
+    readonly services?: OverlayServices;
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** Dispatch a reducer event to mutate console state. */
+    readonly dispatch: ConsoleDispatch;
+    /** Drop the active overlay back to the composer. */
+    readonly closeModal: () => void;
+}
+/**
+ * Render the active modal overlay, or nothing when none is raised.
+ *
+ * @param props the modal state, runtime services, theme, dispatch, and closer
+ */
+export declare function OverlayHost(props: OverlayHostProps): JSX.Element | null;

package/dist/types/console/overlays/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Overlays subsystem — public barrel.
+ *
+ * Re-exports the single overlay mount point ({@link OverlayHost}) plus the three
+ * group components it forwards to ({@link PickerOverlays}, {@link SessionOverlays},
+ * {@link AuthOverlays}) and the shared prop shapes. The console surface imports
+ * the overlay host from `src/console/overlays` rather than reaching into the
+ * individual modules; the dialog bodies are filled by a later pass.
+ */
+export { OverlayHost, type OverlayHostProps } from "./host";
+export { PickerOverlays, type OverlayGroupProps } from "./pickers";
+export { SessionOverlays } from "./sessions";
+export { AuthOverlays } from "./auth";