@orkestrel/terminal 0.0.1 → 0.0.2

package/dist/src/core/index.d.cts

@@ -1,8 +1,10 @@
+import { DriverInterface } from '@orkestrel/database';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { Guard } from '@orkestrel/contract';
 import { StylerInterface } from '@orkestrel/console';
+import { TableInterface } from '@orkestrel/database';
 
 /** The `Accept` header value that opens the broker's SSE stream. */
 export declare const ACCEPT_EVENT_STREAM = "text/event-stream";
@@ -10,6 +12,18 @@ export declare const ACCEPT_EVENT_STREAM = "text/event-stream";
 /** Matches an alphanumeric string (letters and digits only). The `alphanumeric` rule tests against this. */
 export declare const ALPHANUMERIC_PATTERN: RegExp;
 
+/** The rejection reason a bare {@link PromptInterface.answer} returns — `'unknown'` (no such parked prompt) or `'rejected'` (failed validation / type-check). */
+export declare type AnswerError = 'unknown' | 'rejected';
+
+/** The outcome of a bare {@link PromptInterface.answer} call — the accepted `value` on success, else the {@link AnswerError}. */
+export declare type AnswerResult = {
+    readonly success: true;
+    readonly value: unknown;
+} | {
+    readonly success: false;
+    readonly error: AnswerError;
+};
+
 /**
  * Append a rule-backed {@link Validator} to `validators` when the rule is enabled — a `false` /
  * `undefined` `check` is skipped, a function `check` is added verbatim (the custom override), and
@@ -143,12 +157,44 @@ export declare function createCheckboxState(options: CheckboxOptions): CheckboxS
 /** Build the initial {@link ConfirmState} from {@link ConfirmOptions} — defaulting the answer to `false`. */
 export declare function createConfirmState(options: ConfirmOptions): ConfirmState;
 
+/**
+ * Create a {@link TerminalStoreInterface} backed by one table of the `databases` layer — the
+ * driver-pluggable twin of {@link createMemoryTerminalStore}, storing each endpoint's config
+ * snapshot as one opaque JSON column.
+ *
+ * @param driver - The {@link DriverInterface} backing the table (default an in-memory driver)
+ * @returns A {@link TerminalStoreInterface}
+ *
+ * @example
+ * ```ts
+ * import { createDatabaseTerminalStore } from '@src/core'
+ *
+ * const store = createDatabaseTerminalStore() // in-memory by default
+ * ```
+ */
+export declare function createDatabaseTerminalStore(driver?: DriverInterface): TerminalStoreInterface;
+
 /** Build the initial {@link EditorState} from {@link EditorOptions} — resolving the validator + styler, seeding empty lines. */
 export declare function createEditorState(options: EditorOptions): EditorState;
 
 /** Build the initial {@link InputState} from {@link InputOptions} — resolving the validator + styler, seeding an empty value. */
 export declare function createInputState(options: InputOptions): InputState;
 
+/**
+ * Create the in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of endpoint
+ * config snapshots, the default store backing a {@link TerminalManagerInterface}'s `open` / `save`.
+ *
+ * @returns A {@link TerminalStoreInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMemoryTerminalStore } from '@src/core'
+ *
+ * const store = createMemoryTerminalStore()
+ * ```
+ */
+export declare function createMemoryTerminalStore(): TerminalStoreInterface;
+
 /** Build the initial {@link PasswordState} from {@link PasswordOptions} — resolving the validator + styler + mask. */
 export declare function createPasswordState(options: PasswordOptions): PasswordState;
 
@@ -210,6 +256,24 @@ export declare function createPromptClient(options: PromptClientOptions): Prompt
 /** Build the initial {@link SelectState} from {@link SelectOptions} — normalizing choices and pre-focusing the default. */
 export declare function createSelectState(options: SelectOptions): SelectState;
 
+/**
+ * Create the multi-endpoint {@link TerminalManagerInterface} — a named registry of
+ * {@link PromptInterface} brokers so several parties can `ask` prompts of each other by name,
+ * with a transitive DEADLOCK check across every in-flight ask.
+ *
+ * @param options - See {@link TerminalManagerOptions}
+ * @returns A {@link TerminalManagerInterface}
+ *
+ * @example
+ * ```ts
+ * import { createTerminalManager } from '@src/core'
+ *
+ * const manager = createTerminalManager()
+ * manager.add('agent')
+ * ```
+ */
+export declare function createTerminalManager(options?: TerminalManagerOptions): TerminalManagerInterface;
+
 /** Ctrl+A (SOH, U+0001) — move to start of line. */
 export declare const CTRL_A: string;
 
@@ -225,6 +289,65 @@ export declare const CTRL_E: string;
 /** Ctrl+U (NAK, U+0015) — clear the current line. */
 export declare const CTRL_U: string;
 
+/**
+ * A {@link TerminalStoreInterface} backed by one table of the `databases` layer — an endpoint's
+ * durable CONFIG state IS a row, so persistence reduces to keyed point-access (`get` / `set` /
+ * `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
+ * {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}.
+ *
+ * @remarks
+ * The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
+ * JSON, SQLite, IndexedDB) is chosen by whoever builds it (the factories), so a JSON / SQLite /
+ * IndexedDB backend swaps in WITHOUT touching the manager — the same seam as
+ * {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}. The driver defaults to memory
+ * ({@link import('./factories.js').createDatabaseTerminalStore} passes `createMemoryDriver()`), so
+ * it ALSO works in memory out of the box; you opt into the durable plumbing by passing a JSON /
+ * SQLite / IndexedDB driver.
+ *
+ * The {@link TerminalSnapshot} is stored as ONE OPAQUE JSON COLUMN — the table is a row of
+ * `{ id; snapshot }` ({@link TerminalSnapshotRow}). The snapshot is already a COMPLETE,
+ * self-contained, pure-JSON CONFIG payload (no live broker state), so storing it whole is lossless
+ * AND keeps the row type flat (`snapshot` reads back as `unknown`).
+ *
+ * - **`set(snapshot)` upserts under the snapshot's OWN `id`** (no separate id param) — it writes
+ *   the row `{ id: snapshot.id, snapshot }`.
+ * - **`get(id)` resolves the stored snapshot for an id**, narrowing the opaque JSON column back to
+ *   a {@link TerminalSnapshot} ({@link import('./helpers.js').isTerminalSnapshot} — the AGENTS §14
+ *   boundary narrow for an untrusted storage read), or `undefined` if none is stored.
+ * - **`delete(id)` drops a snapshot by id**; an absent id is a no-op (no throw).
+ *
+ * There is NO idle-TTL / eviction — a persisted config lives until an explicit `delete`. The public
+ * surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method bijection with
+ * {@link TerminalStoreInterface}). Hydration stays a caller concern: `open` always restores an EMPTY
+ * broker — parked Promises are process-bound and never resurrected.
+ *
+ * @example
+ * ```ts
+ * import { createDatabaseTerminalStore, createMemoryDriver } from '@src/core'
+ *
+ * const store = createDatabaseTerminalStore(createMemoryDriver()) // a durable driver swaps in here
+ * await store.set({ id: 'shell', timeout: 5000 })        // persist the config (one JSON column)
+ * const snapshot = await store.get('shell')
+ * await store.delete('shell')                            // drop it
+ * ```
+ */
+export declare class DatabaseTerminalStore implements TerminalStoreInterface {
+    #private;
+    /**
+     * Wrap a table as a terminal store.
+     *
+     * @param table - The {@link TableInterface} holding the snapshots — its row is the
+     *   {@link TerminalSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
+     */
+    constructor(table: TableInterface<TerminalSnapshotRow>);
+    /** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `TerminalSnapshot`. */
+    get(id: string): Promise<TerminalSnapshot | undefined>;
+    /** Insert or replace under the snapshot's OWN `id` (no separate id param) — the row is `{ id, snapshot }`. */
+    set(snapshot: TerminalSnapshot): Promise<void>;
+    /** Drop a snapshot by id; an absent id is a no-op (no throw). */
+    delete(id: string): Promise<void>;
+}
+
 /** The default mask glyph a {@link import('./types.js').PasswordState} renders each input character as — `*`. */
 export declare const DEFAULT_MASK = "*";
 
@@ -411,6 +534,12 @@ export declare const INTEGER_PATTERN: RegExp;
  */
 export declare function isAbortError(error: unknown): boolean;
 
+/** Narrow an unknown wire payload to an answer POST body — a non-empty `id` string plus a `value` key (of any shape) present. */
+export declare function isAnswerPayload(value: unknown): value is {
+    readonly id: string;
+    readonly value: unknown;
+};
+
 /** Narrow an unknown value to a {@link CheckboxChoice} — the `recordOf` shape inlined so no non-exported member lingers (§5). */
 export declare function isCheckboxChoice(value: unknown): value is CheckboxChoice;
 
@@ -470,6 +599,9 @@ export declare const isPromptType: Guard<PromptType>;
  */
 export declare function isTerminalError(value: unknown): value is TerminalError;
 
+/** Narrow an unknown value to a {@link TerminalSnapshot} — a non-empty `id` plus an optional numeric `timeout`. */
+export declare const isTerminalSnapshot: Guard<TerminalSnapshot>;
+
 /**
  * The Control Sequence Introducer lead (`ESC[`) for the navigation keys — the prefix of the
  * arrow / home / end / delete sequences {@link SEQUENCE_NAMES} is keyed by. Named `KEY_CSI`
@@ -508,6 +640,45 @@ export declare interface KeyEvent {
     readonly shift: boolean;
 }
 
+/**
+ * The in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of
+ * {@link TerminalSnapshot}s keyed by endpoint id, the DEFAULT store
+ * {@link import('./factories.js').createMemoryTerminalStore} builds. The EXACT twin of
+ * {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore}.
+ *
+ * @remarks
+ * A plain `Map<string, TerminalSnapshot>` (AGENTS §21 — the snapshot is already pure, self-contained
+ * CONFIG-only JSON, so no encoding is needed for the memory tier). There is NO idle-TTL and NO
+ * eviction: a persisted config lives until an explicit `delete`. A durable backend (JSON / SQLite /
+ * IndexedDB) swaps in through the SAME interface without touching the manager — its
+ * driver-pluggable twin is {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore} (the
+ * snapshot as one opaque JSON column).
+ *
+ * - **`get` resolves the persisted snapshot for an id**, or `undefined` if none is stored.
+ * - **`set` inserts / replaces under the snapshot's OWN `id`** (no separate id param).
+ * - **`delete` drops a snapshot by id**; an absent id is a no-op (no throw).
+ *
+ * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method
+ * bijection with {@link TerminalStoreInterface}). Hydration is a caller concern: `open` always
+ * restores an EMPTY broker — parked Promises are process-bound and never resurrected.
+ *
+ * @example
+ * ```ts
+ * import { createMemoryTerminalStore } from '@src/core'
+ *
+ * const store = createMemoryTerminalStore()
+ * await store.set({ id: 'shell', timeout: 5000 })   // persist a config
+ * const snapshot = await store.get('shell')
+ * await store.delete('shell')                       // drop it
+ * ```
+ */
+export declare class MemoryTerminalStore implements TerminalStoreInterface {
+    #private;
+    get(id: string): Promise<TerminalSnapshot | undefined>;
+    set(snapshot: TerminalSnapshot): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
 /** Line feed (`\n`, U+000A) — Enter on some terminals / pasted input. */
 export declare const NEWLINE: string;
 
@@ -535,6 +706,23 @@ export declare interface Parked {
     readonly cancel: TimerCancel;
 }
 
+/**
+ * The request to {@link PromptInterface.park} a prompt directly — the general form the six
+ * `PromptFormInterface` methods each wrap via a private `gateFor(form, options)` dispatch.
+ *
+ * @remarks
+ * - `form` — which {@link PromptType} to park.
+ * - `options` — that form's options bag ({@link PromptFormOptions}).
+ * - `from` / `to` — set ONLY by a {@link TerminalManagerInterface} (the attribution edge); a
+ *   direct broker caller leaves both `undefined`.
+ */
+export declare interface ParkRequest {
+    readonly form: PromptType;
+    readonly options: PromptFormOptions;
+    readonly from?: string;
+    readonly to?: string;
+}
+
 /**
  * Decode one keypress's bytes into a {@link KeyEvent} — total, never throws. A `Uint8Array` is
  * read as UTF-8; the resulting string is matched against the known control bytes
@@ -631,6 +819,9 @@ export declare function passwordView(state: PasswordState): string;
  *   from the rules via {@link resolveValidation}.
  * - `status` — the current {@link PendingPromptStatus}.
  * - `time` — the creation timestamp (ms since epoch).
+ * - `from` / `to` — the OPTIONAL attribution edge a {@link TerminalManagerInterface} stamps on a
+ *   parked prompt (which endpoint asked, which endpoint must answer); absent for a bare broker
+ *   {@link PromptInterface} used directly (no manager attribution).
  */
 export declare interface PendingPrompt {
     readonly id: string;
@@ -639,6 +830,8 @@ export declare interface PendingPrompt {
     readonly options: Readonly<Record<string, unknown>>;
     readonly status: PendingPromptStatus;
     readonly time: number;
+    readonly from?: string;
+    readonly to?: string;
 }
 
 /**
@@ -693,7 +886,8 @@ export declare class Prompt implements PromptInterface {
     get count(): number;
     pending(): readonly PendingPrompt[];
     pending(id: string): PendingPrompt | undefined;
-    answer(id: string, value: unknown): boolean;
+    answer(id: string, value: unknown): AnswerResult;
+    park(request: ParkRequest): Ticket;
     input(options: InputOptions): Promise<string>;
     password(options: PasswordOptions): Promise<string>;
     confirm(options: ConfirmOptions): Promise<boolean>;
@@ -749,8 +943,10 @@ export declare interface PromptChoice {
  *   never an `as`), dispatched to `terminal`, and its resolved value POSTed back to `url`.
  *   Dispatch is strictly SERIAL: the read loop drives the terminal for ONE prompt at a time and
  *   only reads/dispatches the next event after the current prompt fully settles (its answer
- *   POSTed). A prompt id redelivered by the broker AFTER its prior dispatch has settled is
- *   dispatched again — the client does not dedupe across completion.
+ *   POSTed). A prompt id redelivered (e.g. after a reconnect) WHILE its prior dispatch is still
+ *   in flight is skipped (a `#seen` set tracks in-flight ids); once that dispatch settles (or the
+ *   broker sends `expire` for the id) the id is dropped from `#seen`, so a later redelivery of the
+ *   SAME id after completion is dispatched again — the client does not dedupe across completion.
  * - **Server signals.** An `expire` event (the broker dropped a parked prompt) emits `expire`; a
  *   `shutdown` event calls {@link disconnect} (not {@link destroy}) — the client stops streaming
  *   without auto-reconnect but stays reusable; a later {@link connect} recovers it.
@@ -890,6 +1086,12 @@ export declare interface PromptFormInterface {
     editor(options: EditorOptions): Promise<string>;
 }
 
+/**
+ * The union of every prompt form's options bag — the `options` a {@link ParkRequest} carries,
+ * narrowed at the call site by the paired {@link PromptType}.
+ */
+export declare type PromptFormOptions = InputOptions | PasswordOptions | ConfirmOptions | SelectOptions | CheckboxOptions | EditorOptions;
+
 /** The styled prompt-message header (`? message`) — the leading line every active prompt view shares. */
 export declare function promptHeader(styler: StylerInterface, message: string): string;
 
@@ -902,10 +1104,11 @@ export declare function promptHeader(styler: StylerInterface, message: string):
  *
  * @remarks
  * - **Park-as-Promise.** Each `input` / `password` / … call mints an id, parks a
- *   {@link PendingPrompt}, emits `pending`, and returns an unresolved Promise.
+ *   {@link PendingPrompt}, emits `pending`, and returns an unresolved Promise. {@link park} is the
+ *   general entry point the six form methods wrap.
  * - **Answer validates.** {@link answer} validates `value` against the prompt's resolved
  *   validator AND type-checks it to the prompt form before accepting; a bad answer is rejected
- *   (returns `false`, the prompt stays `pending`).
+ *   (an {@link AnswerResult} failure, the prompt stays `pending`).
  * - **Timeout → expire → reject.** An unanswered prompt expires after `timeout` ms — `expire`
  *   fires and the parked Promise rejects (a {@link import('./errors.js').TerminalError}). The
  *   timer is injectable for deterministic tests.
@@ -914,9 +1117,10 @@ export declare function promptHeader(styler: StylerInterface, message: string):
 export declare interface PromptInterface extends PromptFormInterface {
     readonly emitter: EmitterInterface<PromptEventMap>;
     readonly count: number;
+    park(request: ParkRequest): Ticket;
     pending(): readonly PendingPrompt[];
     pending(id: string): PendingPrompt | undefined;
-    answer(id: string, value: unknown): boolean;
+    answer(id: string, value: unknown): AnswerResult;
     destroy(): void;
 }
 
@@ -930,12 +1134,17 @@ export declare interface PromptInterface extends PromptFormInterface {
  *   {@link import('./constants.js').DEFAULT_PROMPT_TIMEOUT_MS}).
  * - `timer` — the injected {@link TimerHandler} (default the host `setTimeout`); supply a
  *   deterministic timer to drive expiry in tests without real time.
+ * - `cap` — the maximum number of prompts this broker will hold PARKED at once (default
+ *   UNBOUNDED — no cap unless supplied). Once `count` reaches `cap`, a new park is rejected with
+ *   a {@link import('./errors.js').TerminalError} (`code: 'LIMIT'`) WITHOUT parking, minting an
+ *   id, emitting `pending`, or arming the expiry timer — the runaway-asker memory ceiling.
  */
 export declare interface PromptOptions {
     readonly on?: EmitterHooks<PromptEventMap>;
     readonly error?: EmitterErrorHandler;
     readonly timeout?: number;
     readonly timer?: TimerHandler;
+    readonly cap?: number;
 }
 
 /**
@@ -980,6 +1189,13 @@ export declare interface PromptStep<T, S> {
  */
 export declare type PromptType = 'input' | 'password' | 'confirm' | 'select' | 'checkbox' | 'editor';
 
+/**
+ * The union of a resolved prompt's value shapes — a `string` (`input` / `password` / `select` /
+ * `editor`), a `boolean` (`confirm`), or a `readonly string[]` (`checkbox`, the checked values in
+ * choice order). The type a {@link Ticket}'s `value` Promise resolves to.
+ */
+export declare type PromptValue = string | boolean | readonly string[];
+
 /**
  * Rebuild a wire-decoded `validate` payload into a {@link ValidationRules} bag — the inverse of
  * {@link serializeValidationRules}. Keeps only the primitive rule values (`boolean` / `number` /
@@ -1112,6 +1328,12 @@ export declare const SEQUENCE_NAMES: Readonly<Record<string, string>>;
 /** Strip functions from a `choices` option — each choice keeps its plain fields; a bare string passes through. */
 export declare function serializeChoices(choices: unknown): readonly unknown[];
 
+/** Serialize a parked prompt's expiry into a {@link WireEvent} — event `'expire'`, `data` the JSON-stringified `{ id }` payload. */
+export declare function serializeExpire(id: string): WireEvent;
+
+/** Serialize a parked {@link PendingPrompt} into a {@link WireEvent} — event `'pending'`, `data` the JSON-stringified prompt, `id` the prompt's own id (an SSE bridge sets its frame `id:` from this). */
+export declare function serializePending(prompt: PendingPrompt): WireEvent;
+
 /**
  * Produce the WIRE-SAFE form of a prompt's options — the {@link PendingPrompt.options} a broker
  * serializes over SSE. Drops everything that cannot cross the wire (a `styler`, and any
@@ -1135,6 +1357,9 @@ export declare function serializeChoices(choices: unknown): readonly unknown[];
  */
 export declare function serializePromptOptions(options: object): Readonly<Record<string, unknown>>;
 
+/** The {@link WireEvent} a broker/manager sends when it is going away — event `'shutdown'`, no payload. */
+export declare function serializeShutdown(): WireEvent;
+
 /**
  * Flatten a `validate` option to its wire-safe {@link ValidationRules} DATA — a function rule
  * becomes `true` (its built-in check survives; its body cannot cross the wire). A bare-function
@@ -1174,6 +1399,18 @@ export declare function submitHeader(styler: StylerInterface, message: string):
 /** Tab (`\t`, U+0009). */
 export declare const TAB: string;
 
+/** The rejection reason a {@link TerminalManagerInterface.answer} call returns — an {@link AnswerError}, plus `'terminal'` (no such endpoint). */
+export declare type TerminalAnswerError = AnswerError | 'terminal';
+
+/** The outcome of a {@link TerminalManagerInterface.answer} call — the accepted `value` on success, else the {@link TerminalAnswerError}. */
+export declare type TerminalAnswerResult = {
+    readonly success: true;
+    readonly value: unknown;
+} | {
+    readonly success: false;
+    readonly error: TerminalAnswerError;
+};
+
 /**
  * An error a {@link import('./Prompt.js').Prompt} broker rejects a parked prompt's Promise with.
  *
@@ -1201,8 +1438,181 @@ export declare class TerminalError extends Error {
  *   `destroy`ed while it was still pending); the prompt's Promise rejects with this.
  * - `CANCEL` — the user aborted an interactive prompt (ctrl-c) at the server `Terminal` (T-c)
  *   driver; the awaited prompt call rejects with this so a caller can branch on `error.code`.
+ * - `LIMIT` — a broker's optional `cap` on concurrently-parked prompts was already reached; the
+ *   new call is rejected WITHOUT parking (never counted, never emitted, no timer armed).
+ * - `DESTROYED` — a call reached an already-`destroy`ed {@link TerminalManagerInterface} (`add`
+ *   at entry, or `open` whose `store` read resolved after a `destroy` happened in the gap).
+ */
+export declare type TerminalErrorCode = 'EXPIRE' | 'CANCEL' | 'DRIVER' | 'DEADLOCK' | 'TARGET' | 'LIMIT' | 'DESTROYED';
+
+/**
+ * The multi-endpoint terminal MANAGER — a registry of named {@link PromptInterface} brokers (one
+ * per endpoint), so several parties can `ask` prompts of each other by NAME with a `from` → `to`
+ * attribution edge on every parked prompt, and a transitive DEADLOCK check across all in-flight
+ * asks.
+ *
+ * @remarks
+ * - **Registry.** `add(name, options?)` mints (or, if `name` is already mounted, returns the
+ *   EXISTING broker UNCHANGED — idempotent, never clobbers a live/parked endpoint). Every mounted
+ *   broker's `pending` / `answer` / `expire` events are re-emitted on the manager, attributed by
+ *   `name`.
+ * - **`ask`.** The target must already be mounted via {@link add} — `ask` never auto-adds it;
+ *   rejects `TARGET` for an unknown `to` (listing the known names). Rejects `DEADLOCK` when parking
+ *   `from → to` would close a cycle over the CURRENT in-flight edge set (walked transitively);
+ *   otherwise parks through the target's broker and resolves with the ORIGINAL ticket Promise (edge
+ *   cleanup is attached via `.then`, never altering the value/rejection the caller observes).
+ * - **Durable open / save.** `open(name)` restores an EMPTY broker from the `store` (parked
+ *   Promises are process-bound and never resurrected); `save(name)` persists the endpoint's
+ *   configured `timeout`.
+ * - **Removal.** `remove` drops one endpoint or a batch (§9.2, array overload FIRST), destroying
+ *   each broker (which expires every prompt still parked on it). `clear` drops all; `destroy` is
+ *   idempotent.
+ *
+ * @example
+ * ```ts
+ * const manager = new TerminalManager()
+ * manager.add('agent')
+ * const name = manager.ask('user', 'agent', 'input', { message: 'Your name' })
+ * manager.answer('agent', manager.pending('agent')[0].id, 'Ada')
+ * await name // 'Ada'
+ * ```
+ */
+export declare class TerminalManager implements TerminalManagerInterface {
+    #private;
+    constructor(options?: TerminalManagerOptions);
+    get emitter(): EmitterInterface<TerminalManagerEventMap>;
+    get count(): number;
+    terminal(name: string): PromptInterface | undefined;
+    terminals(): readonly string[];
+    add(name: string, options?: TerminalOptions): PromptInterface;
+    ask(from: string, to: string, form: 'input' | 'password' | 'editor', options: InputOptions | PasswordOptions | EditorOptions): Promise<string>;
+    ask(from: string, to: string, form: 'confirm', options: ConfirmOptions): Promise<boolean>;
+    ask(from: string, to: string, form: 'select', options: SelectOptions): Promise<string>;
+    ask(from: string, to: string, form: 'checkbox', options: CheckboxOptions): Promise<readonly string[]>;
+    pending(): readonly PendingPrompt[];
+    pending(to: string): readonly PendingPrompt[];
+    answer(to: string, id: string, value: unknown): TerminalAnswerResult;
+    open(name: string): Promise<PromptInterface | undefined>;
+    save(name: string): Promise<boolean>;
+    remove(names: readonly string[]): boolean;
+    remove(name: string): boolean;
+    clear(): void;
+    destroy(): void;
+}
+
+/**
+ * The manager's event map (AGENTS §13) — the name-attributed re-emission of every mounted
+ * broker's events, so a caller subscribes once for ALL endpoints instead of per-broker.
+ *
+ * @remarks
+ * - `pending` — an endpoint parked a prompt (carries the {@link PendingPrompt}, itself carrying
+ *   `from` / `to`).
+ * - `answer` — an endpoint's parked prompt was answered (`to` names the endpoint).
+ * - `expire` — an endpoint's parked prompt timed out (`to` names the endpoint).
+ */
+export declare type TerminalManagerEventMap = {
+    pending: [prompt: PendingPrompt];
+    answer: [to: string, id: string, value: unknown];
+    expire: [to: string, id: string];
+};
+
+/**
+ * The multi-endpoint terminal MANAGER (§9.1/§9.2) — a registry of named {@link PromptInterface}
+ * brokers (one per endpoint), so several parties (agents, tools, humans) can `ask` prompts of
+ * each other by NAME, attributed with a `from` → `to` edge on every parked {@link PendingPrompt}.
+ *
+ * @remarks
+ * - **Accessors (§9.1).** `terminal(name)` looks up one endpoint's broker; `terminals()` lists
+ *   every mounted endpoint name.
+ * - **`add`** mints (or returns the existing) broker for `name` — idempotent, never clobbers a
+ *   live endpoint.
+ * - **`ask`** is the attributed convenience: parks a prompt from `from` to `to` (auto-`add`ing
+ *   `to` if absent) and resolves with the typed value, precisely overloaded per {@link PromptType}.
+ * - **`pending()`** lists every endpoint's parked prompts; `pending(to)` scopes to one endpoint.
+ * - **`answer`** routes to the named endpoint's broker.
+ * - **`open`** restores (or returns the live) broker for `name` from the `store`.
+ * - **`save`** persists an endpoint's config snapshot to the `store` (`false` when there is no
+ *   store, or `name` is unknown).
+ * - **Batch `remove` (§9.2).** The array overload is declared FIRST — `remove(names)` removes each
+ *   listed endpoint (`true` when any of the named terminals was removed); `remove(name)` removes one.
+ * - **`clear`** removes every endpoint without destroying the manager; **`destroy`** tears down
+ *   every broker, then the manager's own emitter.
+ */
+export declare interface TerminalManagerInterface {
+    readonly emitter: EmitterInterface<TerminalManagerEventMap>;
+    readonly count: number;
+    terminal(name: string): PromptInterface | undefined;
+    terminals(): readonly string[];
+    add(name: string, options?: TerminalOptions): PromptInterface;
+    ask(from: string, to: string, form: 'input' | 'password' | 'editor', options: InputOptions | PasswordOptions | EditorOptions): Promise<string>;
+    ask(from: string, to: string, form: 'confirm', options: ConfirmOptions): Promise<boolean>;
+    ask(from: string, to: string, form: 'select', options: SelectOptions): Promise<string>;
+    ask(from: string, to: string, form: 'checkbox', options: CheckboxOptions): Promise<readonly string[]>;
+    pending(): readonly PendingPrompt[];
+    pending(to: string): readonly PendingPrompt[];
+    answer(to: string, id: string, value: unknown): TerminalAnswerResult;
+    open(name: string): Promise<PromptInterface | undefined>;
+    save(name: string): Promise<boolean>;
+    remove(names: readonly string[]): boolean;
+    remove(name: string): boolean;
+    clear(): void;
+    destroy(): void;
+}
+
+/**
+ * Options for {@link import('./factories.js').createTerminalManager} / the
+ * {@link TerminalManagerInterface}.
+ *
+ * @remarks
+ * - `store` — the optional {@link TerminalStoreInterface} backing `open` / `save`.
+ * - `timeout` / `timer` / `cap` — the manager-wide default for each endpoint's broker (overridable
+ *   per {@link TerminalManagerInterface.add} call via {@link TerminalOptions}, exactly like
+ *   `timeout` / `timer`).
+ * - `on` / `error` — the manager's {@link EmitterHooks} + {@link EmitterErrorHandler} (AGENTS §13).
  */
-export declare type TerminalErrorCode = 'EXPIRE' | 'CANCEL';
+export declare interface TerminalManagerOptions {
+    readonly store?: TerminalStoreInterface;
+    readonly timeout?: number;
+    readonly timer?: TimerHandler;
+    readonly cap?: number;
+    readonly on?: EmitterHooks<TerminalManagerEventMap>;
+    readonly error?: EmitterErrorHandler;
+}
+
+/** Options for {@link import('./factories.js').createTerminal} / a manager-owned {@link PromptInterface} broker — the per-endpoint `timeout` + injected `timer` + optional `cap` on concurrently-parked prompts. */
+export declare interface TerminalOptions {
+    readonly timeout?: number;
+    readonly timer?: TimerHandler;
+    readonly cap?: number;
+}
+
+/** One endpoint's persisted CONFIG snapshot — `id` is the endpoint name; `timeout` its configured default. Parked Promises are process-bound and are never resurrected — `open` always restores an EMPTY broker. */
+export declare interface TerminalSnapshot {
+    readonly id: string;
+    readonly timeout?: number;
+}
+
+/** One opaque persisted row — the shape a `TableInterface<TerminalSnapshotRow>`-backed store reads/writes; `snapshot` is narrowed with {@link import('./helpers.js').isTerminalSnapshot} on read. */
+export declare interface TerminalSnapshotRow {
+    readonly id: string;
+    readonly snapshot: unknown;
+}
+
+/**
+ * The point-access persistence seam (AGENTS §5 — Stores) for a {@link TerminalManagerInterface}'s
+ * endpoint configs. Every primitive is async; `delete` of an absent id is a no-op.
+ */
+export declare interface TerminalStoreInterface {
+    get(id: string): Promise<TerminalSnapshot | undefined>;
+    set(snapshot: TerminalSnapshot): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/** The handle {@link PromptInterface.park} returns — the parked prompt's `id` plus the Promise that resolves (or rejects) with its {@link PromptValue}. */
+export declare interface Ticket {
+    readonly id: string;
+    readonly value: Promise<PromptValue>;
+}
 
 /** Cancel a pending {@link TimerHandler} deadline — idempotent, safe to call after the timer fired. */
 export declare type TimerCancel = () => void;
@@ -1270,4 +1680,11 @@ export declare interface ValidationRules {
  */
 export declare type Validator = (input: string) => true | string;
 
+/** One SSE-shaped wire frame — the `event` name, its `data` payload (already JSON-stringified), and an optional `id`. The transport-neutral shape {@link import('./helpers.js').serializePending} / {@link import('./helpers.js').serializeExpire} / {@link import('./helpers.js').serializeShutdown} build, with no `http` dependency. */
+export declare interface WireEvent {
+    readonly event: string;
+    readonly data: string;
+    readonly id?: string;
+}
+
 export { }