@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/dist/node/index.d.cts

@@ -0,0 +1,1066 @@
+import "react";
+import { CommandRegistry, EditCheckpointStore, IAgentDefinition, IAutomaticMemoryConfig, IBackgroundTaskRunner, ICommandHostAdapters, ICommandModule, IContributionSource, ICreateSessionOptions, ILivePromptTracePort, IMemoryStore, INodeHostSettingsSource, IOrgPolicy, IOutputStylePrompt, IPerTurnRecallConfig, IProjectSettingsPath, IPromptHistoryOptions, IProviderErrorGuidance, IRemoteCommandPolicy, ISkillRootDescriptor, IToolCallHandoffPolicy, InteractiveSession, TSettingsSource, TShellExecFn, TSubagentRunnerFactory, TWorkspaceProjectAccess } from "@robota-sdk/agent-framework";
+import { IBranchEvent, ICommandInfo, IContextFileRefreshedEvent, IExecutionResult, IInteractiveSession, IInteractiveSessionEvents, IInteractiveSessionStore, IPlanApprovalEvent, IPromptHistorySource, ITerminalHandoff, IToolState, TInteractiveEventName, TPermissionResultValue } from "@robota-sdk/agent-interface-session";
+import { IAIProvider, IActionRequest, IContextWindowState, IHistoryEntry, IProviderDefinition, IToolWithEventService, TActionResponse, TModelEffortSelection, TPermissionMode, TSessionEndReason, TToolArgs, TUniversalValue } from "@robota-sdk/agent-core";
+import { IExecutionDetailPage, IExecutionWorkspaceSnapshot } from "@robota-sdk/agent-interface-execution";
+import { ICommand, IThemeAppearanceState, IThemeCataloguePort, TReducedMotionOverride } from "@robota-sdk/agent-interface-command";
+import { ITransportRegistryView } from "@robota-sdk/agent-interface-transport";
+import { ITuiCommandInteraction, ITuiConfirmInteraction, ITuiPickerInteraction, ITuiPickerItem, TAnyTuiCommandInteraction, TOnMissingArgsAction } from "@robota-sdk/agent-interface-tui";
+//#region src/screen-reader-pacing.d.ts
+/** Raw timing choices supplied by the embedding host, with names for visible diagnostics. */
+interface IScreenReaderPacingOverrides {
+  readonly startupQuiet?: {
+    readonly raw: string | undefined;
+    readonly label: string;
+  };
+  readonly prepark?: {
+    readonly raw: string | undefined;
+    readonly label: string;
+  };
+}
+//#endregion
+//#region src/terminal-capabilities-context.d.ts
+/** Host-selected overrides; absent values leave terminal detection in charge. */
+interface ITerminalCapabilityOverrides {
+  readonly imeCursorPositioning?: boolean | undefined;
+  readonly turnMarks?: boolean | undefined;
+}
+//#endregion
+//#region src/tui-session-events.d.ts
+interface ITuiSessionEventNotice {
+  id: string;
+  event: 'plan_event' | 'context_file_refreshed' | 'branch_event' | 'delivery-error' |
+  /** SCREEN-1992: TUI-originated — the interval recap on return, not a session event. */
+  'attention-recap';
+  message: string;
+}
+type TTuiNoticeInput = {
+  event: 'plan_event';
+  payload: IPlanApprovalEvent;
+} | {
+  event: 'context_file_refreshed';
+  payload: IContextFileRefreshedEvent;
+} | {
+  event: 'branch_event';
+  payload: IBranchEvent;
+};
+//#endregion
+//#region src/tui-state-manager.d.ts
+/**
+ * TUI view of the core context-window state. The token fields are derived from the agent-core
+ * SSOT (`IContextWindowState`) via `Pick` so they stay structurally tied to it; `percentage` is an
+ * explicit display-facing mirror of `IContextWindowState.usedPercentage`.
+ */
+type TContextState = Pick<IContextWindowState, 'usedTokens' | 'maxTokens'> & {
+  /** Mirror of `IContextWindowState.usedPercentage`, named for the TUI display layer. */
+  percentage: number;
+};
+declare class TuiStateManager {
+  history: IHistoryEntry[];
+  /**
+   * Notices this terminal added itself (command results, init errors). They are not in the session's
+   * history, so each remembers how many session entries preceded it and is re-inserted there on sync.
+   */
+  private localNotices;
+  streamingText: string;
+  activeTools: IToolState[];
+  isThinking: boolean;
+  isAborting: boolean;
+  pendingPrompt: string | null;
+  contextState: TContextState;
+  executionWorkspaceSnapshot: IExecutionWorkspaceSnapshot | null;
+  selectedExecutionEntryId: string | undefined;
+  /** ERR-001 G2: humanized message of the last failed turn; cleared when the next turn starts. */
+  lastErrorMessage: string | null;
+  /** ERR-001 G3: no stream/tool activity for STALL_HINT_MS while thinking. */
+  isStalled: boolean;
+  private readonly sessionNoticeStore;
+  /** Bounded render-only projection; never merged into canonical session history. */
+  readonly sessionEventNotices: ITuiSessionEventNotice[];
+  /** Called after any state change. React hook sets this to trigger re-render. */
+  onChange: (() => void) | null;
+  private streamBuf;
+  private debouncedStreamNotify;
+  private stallTimer;
+  /** (Re)start the dead-air timer — any provider activity proves the connection is alive. */
+  private armStallTimer;
+  private clearStallTimer;
+  private notify;
+  onTextDelta: (delta: string) => void;
+  onToolStart: (state: IToolState) => void;
+  onToolEnd: (state: IToolState) => void;
+  onThinking: (thinking: boolean) => void;
+  onComplete: (result: IExecutionResult) => void;
+  onInterrupted: () => void;
+  onError: (error?: Error) => void;
+  onContextUpdate: (state: IContextWindowState) => void;
+  /**
+   * Sync history from InteractiveSession — authoritative SSOT replace (SCREEN-010: no front-windowing).
+   * The session history grows monotonically during a session, so Ink `<Static>` (count-based) renders
+   * only the newly-appended tail; committed lines already in terminal scrollback are never re-printed.
+   */
+  syncHistory(entries: IHistoryEntry[]): void;
+  /** Add a notice this terminal owns; it survives the next session-history sync in place. */
+  addEntry(entry: IHistoryEntry): void;
+  /** Echo the user's prompt at once; the session's own user entry replaces it on the next sync. */
+  addUserEcho(entry: IHistoryEntry): void;
+  clearHistory(): void;
+  /** Update pending prompt state */
+  setPendingPrompt(prompt: string | null): void;
+  /** Set aborting flag */
+  setAborting(aborting: boolean): void;
+  /** Update context state */
+  setContextState(state: TContextState): void;
+  addSessionEventNotice(input: TTuiNoticeInput): void;
+  addAttentionRecap(line: string): void;
+  addSessionEventDeliveryError(error: Error, event: TInteractiveEventName): void;
+  syncExecutionWorkspaceSnapshot(snapshot: IExecutionWorkspaceSnapshot): void;
+  selectExecutionWorkspaceEntry(entryId: string): void;
+  /**
+   * RUNTIME-52: release every timer this manager owns and detach the render callback. Called by the
+   * channel's teardown (`stop()`); after dispose the manager must never fire `onChange` or trip the
+   * stall hint on a discarded session.
+   */
+  dispose(): void;
+}
+//#endregion
+//#region src/terminal-handoff-controller.d.ts
+/** How the App suspends/resumes its rendering, registered into the controller on mount. */
+interface ITuiSuspendHooks {
+  /** Render nothing (release Ink input/raw mode); resolves once that has committed. */
+  suspend(): Promise<void>;
+  /** Resume rendering and force a redraw. */
+  resume(): void;
+}
+/**
+ * SCREEN-1992: terminal modes the TUI negotiated (focus reporting) are released before a child owns
+ * the terminal and re-negotiated once it is reclaimed, so the child never receives `CSI I`/`CSI O`
+ * and a child that reset the mode does not leave the TUI blind afterwards.
+ */
+interface ITerminalModeHooks {
+  /** May be async: SCREEN-2670 drains the parked screen-reader output before the child gets the TTY. */
+  preSuspend(): void | Promise<void>;
+  postResume(): void;
+}
+/** Minimal slice of the Ink render instance the controller needs. */
+interface IInkClearable {
+  clear(): void;
+}
+declare class TerminalHandoffController implements ITerminalHandoff {
+  private hooks?;
+  private instance?;
+  private modeHooks?;
+  /**
+   * The App registers how to suspend/resume Ink. Returns an unregister function for cleanup on
+   * unmount. Only a mounted App provides these hooks, which gates `canHandoffTerminal`.
+   */
+  registerSuspendHooks(hooks: ITuiSuspendHooks): () => void;
+  /** render.tsx registers the terminal-mode bracket (SCREEN-1992) before `render()`. */
+  setTerminalModeHooks(hooks: ITerminalModeHooks | undefined): void;
+  /** render.tsx supplies the Ink instance (for `clear()`) after `render()` returns. */
+  setInkInstance(instance: IInkClearable): void;
+  get canHandoffTerminal(): boolean;
+  runWithTerminal<T>(fn: () => Promise<T>): Promise<T>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Permission result: true (allow once), false (deny), 'allow-session' (remember for session),
+ * or 'allow-project' (persist through the host-selected project settings writer).
+ */
+type TPermissionResult = TPermissionResultValue;
+interface IPendingPermissionRequest {
+  toolName: string;
+  toolArgs: TToolArgs;
+  canPersistProjectPermission?: boolean;
+  /** The peer session whose message this call serves, when a peer turn asked. */
+  requestedByPeer?: string;
+  resolve: (result: TPermissionResult) => void;
+}
+//#endregion
+//#region src/tui-app-channel-port.d.ts
+interface ITuiCommandQueryPort {
+  getCommands(filter?: string): ICommand[];
+  getSubcommands(commandName: string): ICommand[];
+}
+type TTuiSessionUiEventName = 'ui_intent' | 'session_renamed';
+interface ITuiSessionUiEventPort {
+  on<E extends TTuiSessionUiEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+  off<E extends TTuiSessionUiEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+}
+interface ITuiRuntimeStatusSnapshot {
+  permissionMode: TPermissionMode;
+  sessionId: string;
+  activePresetId?: string;
+  effort?: TModelEffortSelection;
+}
+interface ITuiChannelSnapshot {
+  history: readonly IHistoryEntry[];
+  streamingText: string;
+  activeTools: readonly IToolState[];
+  isThinking: boolean;
+  isAborting: boolean;
+  lastErrorMessage: string | null;
+  isStalled: boolean;
+  sessionEventNotices: readonly ITuiSessionEventNotice[];
+  isShuttingDown: boolean;
+  pendingPrompt: string | null;
+  pendingCount: number;
+  executionWorkspaceSnapshot: IExecutionWorkspaceSnapshot | null;
+  selectedExecutionEntryId?: string;
+  permissionRequest: IPendingPermissionRequest | null;
+  pendingUserAction: IActionRequest | null;
+  contextState: {
+    percentage: number;
+    usedTokens: number;
+    maxTokens: number;
+  };
+}
+/**
+ * Complete channel surface visible below the top-level App composition shell.
+ *
+ * Deliberately excludes the concrete-session, concrete-registry and mutable-state-manager
+ * compatibility escapes retained by TuiInteractionChannel for non-React consumers.
+ */
+interface ITuiAppChannelPort {
+  readonly terminalHandoffController: TerminalHandoffController | undefined;
+  readonly sessionName: string | undefined;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  subscribe(onChange: () => void): () => void;
+  getSnapshot(): ITuiChannelSnapshot;
+  getCommandQueryPort(): ITuiCommandQueryPort;
+  getSessionUiEventPort(): ITuiSessionUiEventPort;
+  getRuntimeStatusSnapshot(fallbackPermissionMode: TPermissionMode): ITuiRuntimeStatusSnapshot;
+  addEntry(entry: IHistoryEntry): void;
+  handleInput(input: string): Promise<void>;
+  abort(): void;
+  cancelQueue(): void;
+  stopWaitingSelfPacedLoop(): Promise<void>;
+  shutdown(options?: {
+    reason?: TSessionEndReason;
+    timeoutMs?: number;
+  }): Promise<void>;
+  selectExecutionWorkspaceEntry(entryId: string): void;
+  readExecutionWorkspaceDetail(entryId: string): Promise<IExecutionDetailPage>;
+  sendAgentJob(taskId: string, input: string): Promise<void>;
+  resolveUserAction(request: IActionRequest, response: TActionResponse): void;
+}
+//#endregion
+//#region src/attention/attention-tracker.d.ts
+type TAttentionChangeKind = 'lost' | 'returned';
+interface IAttentionChange {
+  readonly kind: TAttentionChangeKind;
+  /** ISO timestamp of the transition, from the injected clock. */
+  readonly at: string;
+}
+type TAttentionListener = (change: IAttentionChange) => void;
+/** What a consumer of attention sees: the level, and every transition. */
+interface IAttentionSource {
+  readonly attended: boolean;
+  /** Which source decides the level right now — recorded so a degraded run is never a silent default. */
+  readonly source: 'focus' | 'idle';
+  subscribe(listener: TAttentionListener): () => void;
+}
+//#endregion
+//#region src/tui-channel-options.d.ts
+/**
+ * The TUI channel's option surface.
+ *
+ * ARCH-013: this lived inside the 698-line channel class, beside the code that consumes it. The
+ * projection FROM it — `buildTuiSessionOptions` — already had its own module, so the surface and its
+ * one projection now sit together and neither is buried in an implementation file. That matters for
+ * this item specifically: a field added to the resolved preset has to be added here to reach the
+ * interactive surface at all, and a surface nobody can find is a surface people forget.
+ */
+interface ITuiInteractionChannelOptions {
+  livePromptTrace?: ILivePromptTracePort;
+  /**
+   * Provider definitions, forwarded to the session so `/provider switch` can construct the provider
+   * it switches TO.
+   *
+   * Not optional-by-accident: without it the session holds an empty list, and the hot-swap fails with
+   * "Unknown provider: <name>. Currently supported: " — an empty supported-list, which is both wrong
+   * and unactionable. The definitions live in the composition root; the session cannot discover them.
+   */
+  providerDefinitions?: readonly IProviderDefinition[];
+  cwd: string;
+  provider: IAIProvider;
+  providerErrorGuidance?: IProviderErrorGuidance;
+  promptFileReferenceTag?: string;
+  modelCommandToolPrefix?: string;
+  subagentHookEnvironmentNames?: ICreateSessionOptions['subagentHookEnvironmentNames'];
+  observerFailureWarningCode?: ICreateSessionOptions['observerFailureWarningCode'];
+  commandHookShell?: string;
+  /** Skip instruction files and plugin discovery (`--safe-mode`). */
+  bare?: boolean;
+  /** Run no hook the settings layers declare (`--safe-mode`). */
+  skipConfiguredHooks?: boolean;
+  /** Resolved organization policy forwarded to the interactive session. */
+  orgPolicy?: IOrgPolicy;
+  projectAccess?: TWorkspaceProjectAccess;
+  projectSettingsPaths?: readonly IProjectSettingsPath[];
+  baselinePermissionAllow?: readonly string[];
+  /** Host-selected task-context root; absent means no framework task-directory scan. */
+  taskContext?: {
+    readonly enabled?: boolean;
+    readonly dir?: string;
+  };
+  contributionSources?: ICreateSessionOptions['contributionSources'];
+  skillRoots?: ICreateSessionOptions['skillRoots'];
+  userSettingsSources?: readonly INodeHostSettingsSource[];
+  /** Explicit authority- and permission-backed edit checkpoint capability. */
+  editCheckpointStore?: EditCheckpointStore;
+  /**
+   * CLI-076: the resolved model id (the same value the status line displays). Forwarded to the session so an
+   * explicit `--model` override reaches the provider chat call instead of being silently replaced by the
+   * session's default model.
+   */
+  model?: string;
+  /** CLI-1988: resolved provider-neutral response style. */
+  outputStyle?: IOutputStylePrompt;
+  /** ARCH-013: resolved preset effort, threaded to the session's `effort` seam. */
+  effort?: ICreateSessionOptions['effort'];
+  temperature?: number;
+  maxOutputTokens?: number;
+  /** Preset prompt seed, distinct from the replacing `systemPrompt` option. */
+  presetSystemPrompt?: string;
+  responseFormat?: ICreateSessionOptions['responseFormat'];
+  permissionMode?: TPermissionMode;
+  maxTurns?: number;
+  sessionStore?: IInteractiveSessionStore;
+  disableSessionLoops?: boolean;
+  resolveDefaultLoopPrompt?: () => string;
+  resumeSessionId?: string;
+  forkSession?: boolean;
+  /** Issue #3081: this channel's session is the target of a `/cd` from this directory. */
+  workspaceMovedFrom?: string;
+  sessionName?: string;
+  onAutoNamed?: (name: string) => void;
+  backgroundTaskRunners?: IBackgroundTaskRunner[];
+  /** MCP-004: forwarded to `ICreateSessionOptions.toolCallHandoff`. */
+  toolCallHandoff?: IToolCallHandoffPolicy;
+  subagentRunnerFactory?: TSubagentRunnerFactory;
+  /** ARCH-005: composition-root-contributed subagent definitions (merged capability packs). */
+  agentDefinitions?: readonly IAgentDefinition[];
+  agentDefinitionRoots?: readonly string[];
+  pluginDirectories?: {
+    readonly user?: string;
+    readonly project?: string;
+  };
+  /**
+   * ARCH-006: tools contributed by the composition root (the capability packs `assembleProduct` merged)
+   * and, when the profile hands the packs the whole tool surface, the suppressed framework default tier
+   * (`defaultTools: []`). Forwarded to the session's tool-composition seam; absent ⇒ unchanged.
+   */
+  additionalTools?: IToolWithEventService[];
+  defaultTools?: readonly IToolWithEventService[];
+  commandModules?: readonly ICommandModule[];
+  commandHostAdapters?: ICommandHostAdapters;
+  shellExec?: TShellExecFn;
+  /** REMOTE-006: optional remote-command policy (allow-by-default; a transport-origin command runs as a local one). */
+  remoteCommandPolicy?: IRemoteCommandPolicy;
+  transportRegistry?: ITransportRegistryView;
+  /** Bind concrete transports to each newly constructed session before registry startup. */
+  bindTransports?: (session: IInteractiveSession) => void | Promise<void>;
+  language?: string;
+  reloadPluginCommandSource?: (registry: CommandRegistry) => void;
+  agentName?: string;
+  /** Active preset id selected at startup (PRESET-011 runtime state). Defaults to 'default'. */
+  activePresetId?: string;
+  /** Preset persona block composed as a `source: 'persona'` system-prompt section (priority 5). */
+  persona?: string;
+  systemPrompt?: string;
+  appendSystemPrompt?: string;
+  allowedTools?: readonly string[];
+  deniedTools?: readonly string[];
+  /** Preset execution capability: activate agent runtime + subagent/background dispatch. */
+  enableParallelSubagents?: boolean;
+  /** Preset execution capability: run a post-task self-verification step. */
+  selfVerification?: boolean;
+  /** TERM-002: process-shared terminal-handoff controller (the TUI implementation of ITerminalHandoff). */
+  terminalHandoff?: TerminalHandoffController;
+  /** SCREEN-1992: the terminal's attention level; absent ⇒ no interval recap. */
+  attention?: IAttentionSource;
+  /**
+   * SELFHOST-008 P6: optional durable-memory store injected by the surface (agent-cli). Forwarded into
+   * `buildRuntimeSession`; absent ⇒ memory OFF (today's behavior). Enablement/policy is surface-owned.
+   */
+  memoryStore?: IMemoryStore;
+  /** SELFHOST-008 P6: optional automatic post-turn capture policy (absent ⇒ capture OFF). */
+  automaticMemory?: IAutomaticMemoryConfig;
+  /** SELFHOST-008 P6: optional per-turn recall policy (absent ⇒ recall OFF, startup-only injection). */
+  recallMemory?: IPerTurnRecallConfig;
+  /** Observe TUI-owned session-event rendering failures without failing the committed operation. */
+  onSessionEventDeliveryError?: (error: Error, event: TInteractiveEventName) => void;
+  /**
+   * CLI-2004: the resolved screen-reader mode. A PRESENTATION field — it changes nothing about the
+   * session and is deliberately NOT projected into `buildTuiSessionOptions`; it is carried here so
+   * the render-options → channel-options projection is complete and the ARCH-110 drop hazard is
+   * asserted rather than assumed. Absent ⇒ OFF.
+   */
+  screenReader?: boolean;
+  /** SCREEN-1993: the session-side prompt-history writer and project key; absent ⇒ nothing recorded. */
+  promptHistory?: IPromptHistoryOptions | undefined;
+}
+//#endregion
+//#region src/TuiInteractionChannel.d.ts
+declare class TuiInteractionChannel implements ITuiAppChannelPort {
+  readonly stateManager: TuiStateManager;
+  private readonly interactiveSession;
+  private readonly registry;
+  private readonly opts;
+  private submitHandler;
+  private readonly userActions;
+  private readonly permissions;
+  private readonly eventProjector;
+  /** SCREEN-1992: joins the terminal's attention to this channel's recap; absent without a source. */
+  private readonly attention;
+  private readonly lifecycle;
+  availableCommands: ICommandInfo[];
+  sessionName: string | undefined;
+  private autoNameTriggered;
+  private initPoller;
+  /** TERM-002: the App registers its Ink suspend/resume hooks into this controller. */
+  get terminalHandoffController(): TerminalHandoffController | undefined;
+  /** Set by React hook to trigger re-render on state change */
+  onChange: (() => void) | null;
+  constructor(opts: ITuiInteractionChannelOptions);
+  private startRuntime;
+  private stopTransports;
+  get permissionRequest(): IPendingPermissionRequest | null;
+  /** CMD-004: the action currently awaiting a user answer, or null. */
+  get pendingUserAction(): IActionRequest | null;
+  get isShuttingDown(): boolean;
+  get isActiveForPeerStatus(): boolean;
+  private createSession;
+  private createRegistry;
+  onSubmit(handler: (text: string) => Promise<void>): void;
+  setAvailableCommands(commands: ICommandInfo[]): void;
+  setBusy(busy: boolean): void;
+  start(): Promise<void>;
+  /**
+   * Full, idempotent channel teardown (CLI-075). Unwires every session listener, drains both
+   * request queues, stops the init poller, disposes the render-state manager, stops transports, and
+   * — unless a graceful `shutdown()` already ran — shuts the underlying session down so a discarded
+   * or switched-away channel releases its background tasks, subagent processes, and timers.
+   */
+  stop(): Promise<void>;
+  getSession(): InteractiveSession;
+  getRegistry(): CommandRegistry;
+  subscribe(onChange: () => void): () => void;
+  getSnapshot(): ITuiChannelSnapshot;
+  getCommandQueryPort(): ITuiCommandQueryPort;
+  getSessionUiEventPort(): ITuiSessionUiEventPort;
+  getRuntimeStatusSnapshot(fallbackPermissionMode: TPermissionMode): ITuiRuntimeStatusSnapshot;
+  addEntry(entry: IHistoryEntry): void;
+  abort(): void;
+  cancelQueue(): void;
+  stopWaitingSelfPacedLoop(): Promise<void>;
+  shutdown(options?: {
+    reason?: TSessionEndReason;
+    timeoutMs?: number;
+  }): Promise<void>;
+  selectExecutionWorkspaceEntry(entryId: string): void;
+  readExecutionWorkspaceDetail(entryId: string): Promise<IExecutionDetailPage>;
+  sendAgentJob(taskId: string, input: string): Promise<void>;
+  setSessionName(name: string): void;
+  /**
+   * Queue an ask and resolve when the user answers. Reached via the `ask_request` event handler
+   * (which passes the framework prompt `id` for co-drive dismissal) and by any direct
+   * `IInteractionChannel.askUser` caller (no id).
+   */
+  askUser(request: IActionRequest, id?: string): Promise<TActionResponse>;
+  /** Called by App's PendingActionPrompt when the user answers (or cancels) the pending action. */
+  resolveUserAction(request: IActionRequest, response: TActionResponse): void;
+  /** Resolve every queued/in-flight ask as cancelled (abort, shutdown). */
+  private cancelAllUserActions;
+  handleInput(input: string): Promise<void>;
+  private handleSlashCommand;
+  private handlePermissionRequest;
+  /**
+   * REMOTE-007 co-drive: another surface answered the prompt with this framework `id`, so dismiss the
+   * still-showing local dialog. Resolving the local entry (cancelled) is a no-op on the framework side
+   * — that id is already settled — but it clears the TUI's queue + render state.
+   */
+  private dismissPromptById;
+  /**
+   * Resolve every queued/in-flight permission request as `false` (deny) — abort, cancelQueue,
+   * shutdown, stop. Symmetric to `cancelAllUserActions()`: tearing down must neither leave a tool's
+   * permission promise dangling (the tool would hang) nor silently grant it (CLI-075 RUNTIME-32).
+   */
+  private cancelAllPermissions;
+  private handleAutoNaming;
+  private syncRestoredHistory;
+  private startInitCheck;
+  /** Throws while the session is not ready; the init poller classifies the error. */
+  private runInitCheck;
+  /** SCREEN-1992: the recap lands in this channel's notice store; no source ⇒ no coordinator. */
+  private createAttention;
+  private onInitFailure;
+  private stopInitCheck;
+  private syncExecutionWorkspace;
+}
+//#endregion
+//#region src/keybindings/keybinding-catalogue.d.ts
+declare const KEYBINDING_ACTIONS: {
+  readonly app: readonly ["open-workspace-switcher"];
+  readonly thinking: readonly ["abort"];
+  readonly 'background-detail': readonly ["return-to-main"];
+  readonly recovery: readonly ["retry"];
+  readonly 'chat-input': readonly ["submit", "history-previous", "history-next", "history-search", "cursor-left", "cursor-right", "delete-backward", "delete-word", "delete-line"];
+  readonly 'text-input': readonly ["submit", "cursor-left", "cursor-right", "cursor-up", "cursor-down", "delete-backward", "delete-word", "delete-line"];
+  readonly 'autocomplete-menu': readonly ["previous", "next", "close", "accept", "execute"];
+  readonly 'queued-prompt': readonly ["cancel"];
+  readonly 'confirm-prompt': readonly ["previous", "next", "confirm", "choose-yes", "choose-no"];
+  readonly 'permission-prompt': readonly ["previous", "next", "confirm", "allow-once", "allow-session", "allow-project", "deny"];
+  readonly 'text-prompt': readonly ["submit", "cancel", "delete-backward"];
+  readonly 'list-picker': readonly ["previous", "next", "select", "cancel"];
+  readonly 'menu-select': readonly ["previous", "next", "select", "back"];
+  readonly 'multi-select': readonly ["previous", "next", "toggle", "confirm", "cancel"];
+  readonly 'workspace-switcher': readonly ["previous", "next", "select", "close", "attach"];
+  readonly 'background-list': readonly ["previous", "next", "open", "close"];
+  readonly 'transport-settings': readonly ["previous", "next", "toggle", "close"];
+  /** SCREEN-1993: the reverse prompt-history search overlay. */
+  readonly 'history-search': readonly ["previous", "next", "cycle-scope", "insert", "execute", "cancel"];
+  /**
+   * SCREEN-2002: the theme picker. Navigation PREVIEWS; only `select` applies. Printable keys are
+   * fine here because the picker takes no text.
+   */
+  readonly 'theme-picker': readonly ["previous", "next", "select", "toggle-syntax", "toggle-motion", "cancel"];
+};
+type TKeybindingContext = keyof typeof KEYBINDING_ACTIONS;
+type TKeybindingAction<TContext extends TKeybindingContext = TKeybindingContext> = (typeof KEYBINDING_ACTIONS)[TContext][number];
+//#endregion
+//#region src/keybindings/keybinding-registry.d.ts
+interface IKeybindingWarning {
+  readonly code: 'multiplexer-conflict' | 'modifier-delivery';
+  readonly path: string;
+  readonly message: string;
+}
+interface IKeybindingDiagnostic {
+  readonly file: string;
+  readonly path: string;
+  readonly message: string;
+}
+interface IKeybindingSnapshot {
+  readonly generation: number;
+  readonly sourcePath: string;
+  readonly bindings: Readonly<Record<TKeybindingContext, Readonly<Record<string, readonly string[]>>>>;
+  readonly warnings: readonly IKeybindingWarning[];
+  readonly diagnostic?: IKeybindingDiagnostic;
+}
+//#endregion
+//#region src/keybindings/node-keybindings-source.d.ts
+interface IKeybindingsFilePort {
+  ensureFile(): Promise<string>;
+}
+interface IKeybindingsSource extends IKeybindingsFilePort {
+  readonly filePath: string;
+  start(): Promise<void>;
+  isStarted(): boolean;
+  getSnapshot(): IKeybindingSnapshot;
+  subscribe(listener: (snapshot: IKeybindingSnapshot) => void): () => void;
+  dispose(): void;
+}
+interface INodeKeybindingsSourceOptions {
+  readonly filePath: string;
+  readonly schemaUrl: string;
+  readonly onDiagnostic?: (diagnostic: IKeybindingDiagnostic) => void;
+}
+declare function createNodeKeybindingsSource(options: INodeKeybindingsSourceOptions): IKeybindingsSource;
+//#endregion
+//#region src/screen-reader-announcement.d.ts
+/**
+ * CLI-2004 — the first line the process prints.
+ *
+ * Two mutually exclusive lines, and never more than one:
+ *  - the mode is ON  → `[Screen reader mode: on via flag|env|settings]`. It is the only
+ *    self-diagnostic in the design: when someone reports "I passed the flag and nothing changed",
+ *    this line says whether the mode is on and which input turned it on.
+ *  - the mode is OFF and the environment looks like a reader is present → one advisory line naming
+ *    the flag. That is the whole of this project's answer to the auto-detection question: opt-in
+ *    keeps determinism, and a false positive costs one line of text instead of reshaping a sighted
+ *    user's interface.
+ *
+ * Printed before Ink's first frame and never during a turn, so it cannot interleave with output a
+ * reader is consuming.
+ */
+/** Which input turned the mode on. Mirrors the CLI resolver's channel. */
+type TScreenReaderChannel = 'flag' | 'env' | 'settings';
+//#endregion
+//#region src/theme/theme-contracts.d.ts
+/**
+ * SCREEN-2002 — the TUI's one theme token model.
+ *
+ * Before this, five things decided a colour: `PALETTE` (Ink names), `ANSI` (raw SGR for the markdown
+ * pipeline), `marked-terminal`'s own chalk defaults, `cli-highlight`'s `DEFAULT_THEME`, and a handful
+ * of `chalk.<name>` calls. A theme that rewrote only the first two would leave a daltonized run with
+ * red/green code blocks, because `cli-highlight` falls back PER KEY to its own theme. So the model
+ * carries every group a renderer reads, and the style builder derives every encoding from it through
+ * chalk — which is exactly what Ink's own `colorize` does, so no mapping layer is invented.
+ *
+ * Values use INK'S colour grammar verbatim (`<chalk name> | #rrggbb | ansi256(n) | rgb(r,g,b)`), so a
+ * theme file, a built-in and a component all speak one language and the grammar doubles as the
+ * injection floor: no raw escape sequence can enter through a theme.
+ */
+/** A colour in Ink's grammar. Validated at the boundary, never parsed twice. */
+type TThemeColor = string;
+/** Foreground and border roles every Ink component reads. */
+interface IThemeColors {
+  readonly text: {
+    readonly accent: TThemeColor;
+    readonly emphasis: TThemeColor;
+    readonly success: TThemeColor;
+    readonly warning: TThemeColor;
+    readonly error: TThemeColor;
+    readonly session: TThemeColor;
+    readonly muted: TThemeColor;
+    readonly onAccent: TThemeColor;
+  };
+  readonly border: {
+    readonly attention: TThemeColor;
+    readonly focused: TThemeColor;
+    readonly active: TThemeColor;
+    readonly muted: TThemeColor;
+    readonly error: TThemeColor;
+  };
+  readonly status: {
+    readonly running: TThemeColor;
+    readonly success: TThemeColor;
+    readonly error: TThemeColor;
+    readonly denied: TThemeColor;
+    readonly waiting: TThemeColor;
+    readonly cancelled: TThemeColor;
+    readonly idle: TThemeColor;
+  };
+}
+/**
+ * Every key `marked-terminal` colours by default, including `html` — a key left out would keep that
+ * dependency's own gray under every theme.
+ *
+ * Deliberately absent, because they carry no colour today and giving them one would change rendering
+ * rather than theme it: `strong` (`chalk.bold`), `em` (`chalk.italic`), `listitem` and `hr`
+ * (`chalk.reset`), and a diff's `diff `/`index ` metadata rows, which this package writes itself as
+ * dim over the inherited foreground.
+ */
+interface IThemeMarkdown {
+  readonly heading: TThemeColor;
+  readonly firstHeading: TThemeColor;
+  readonly code: TThemeColor;
+  readonly codespan: TThemeColor;
+  readonly link: TThemeColor;
+  readonly href: TThemeColor;
+  readonly blockquote: TThemeColor;
+  readonly del: TThemeColor;
+  readonly html: TThemeColor;
+  readonly diffAdded: TThemeColor;
+  readonly diffRemoved: TThemeColor;
+  readonly diffAddedBackground: TThemeColor;
+  readonly diffRemovedBackground: TThemeColor;
+  readonly diffHunk: TThemeColor;
+}
+/**
+ * `cli-highlight`'s seventeen coloured keys, ALL REQUIRED. Its `colorizeNode` reads
+ * `theme[token] || DEFAULT_THEME[token] || plain`, so one missing key restores that dependency's
+ * red/green pair — the exact thing a daltonized theme exists to remove.
+ */
+interface IThemeSyntax {
+  readonly keyword: TThemeColor;
+  readonly built_in: TThemeColor;
+  readonly type: TThemeColor;
+  readonly literal: TThemeColor;
+  readonly number: TThemeColor;
+  readonly regexp: TThemeColor;
+  readonly string: TThemeColor;
+  readonly class: TThemeColor;
+  readonly function: TThemeColor;
+  readonly comment: TThemeColor;
+  readonly doctag: TThemeColor;
+  readonly meta: TThemeColor;
+  readonly tag: TThemeColor;
+  readonly name: TThemeColor;
+  readonly attr: TThemeColor;
+  readonly addition: TThemeColor;
+  readonly deletion: TThemeColor;
+}
+/** The colour ramp of the package's one animation. Cadence is not themed. */
+interface IThemeMotion {
+  readonly wave: readonly [TThemeColor, TThemeColor, TThemeColor, TThemeColor];
+}
+type TThemeAppearance = 'dark' | 'light';
+type TThemeSource = 'built-in' | 'user' | 'plugin';
+interface ITuiTheme {
+  /** `dark`, `light`, `dark-daltonized`, `light-daltonized`, `custom:<slug>`, `custom:<plugin>:<slug>`. */
+  readonly id: string;
+  readonly name: string;
+  readonly appearance: TThemeAppearance;
+  readonly source: TThemeSource;
+  readonly colors: IThemeColors;
+  readonly markdown: IThemeMarkdown;
+  readonly syntax: IThemeSyntax;
+  readonly motion: IThemeMotion;
+}
+//#endregion
+//#region src/theme/built-in-themes.d.ts
+/**
+ * The catalogue, as a function rather than the array itself. A caller outside `src/theme/` — the
+ * theme registry a picker reads — needs to ENUMERATE the built-ins, which is a different act from
+ * reaching into one of them for a colour; the floor refuses the second by refusing the DATA's names,
+ * so the first gets an accessor of its own instead of an exemption.
+ */
+declare function listBuiltInThemes(): readonly ITuiTheme[];
+//#endregion
+//#region src/theme/theme-registry.d.ts
+/**
+ * A theme file that was found and refused. It is carried BESIDE the themes rather than among them,
+ * because a surface must be able to show the file without ever resolving to it — an id that can be
+ * listed and cannot be applied is the shape of the bug this avoids.
+ */
+interface IThemeSkip {
+  /**
+   * The id the file WOULD have had, so a `/theme <id>` that fails has a visible reason — or, when
+   * the file's own NAME is what made an id impossible, the quoted name in its place. It is a label,
+   * not a key: two files can carry the same one.
+   */
+  readonly id: string;
+  readonly fileName: string;
+  /** The path-named diagnostic, verbatim from `parseThemeDocument`. */
+  readonly reason: string;
+}
+interface IThemeResolution {
+  readonly theme: ITuiTheme;
+  /** The id that was asked for and not found. Absent ⇒ the request was satisfied. */
+  readonly unknownId?: string;
+}
+interface IThemeRegistry {
+  list(): readonly ITuiTheme[];
+  get(id: string): ITuiTheme | undefined;
+  /** The theme for an id, falling back to the default and NAMING what it could not find. */
+  resolve(id: string | undefined): IThemeResolution;
+  /** The theme files that were found and refused, with the reason each was refused for. */
+  skipped(): readonly IThemeSkip[];
+}
+declare function createThemeRegistry(themes?: readonly ITuiTheme[], skipped?: readonly IThemeSkip[]): IThemeRegistry;
+interface IThemeCataloguePortOptions {
+  readonly registry: IThemeRegistry;
+  /**
+   * Re-read on every call, not captured once: `/theme` reports what is PERSISTED, and the host
+   * applies a patch by writing the settings document. A snapshot would answer with the appearance
+   * the process started with, so the command would report the change it just made as not having
+   * happened.
+   */
+  readonly readAppearance: () => IThemeAppearanceState['settings'];
+  /**
+   * The pin on reduced motion for this run, when something above the settings applied one — WHICH
+   * tier and WHAT it pinned, as one value. Two optional fields would let a caller supply the tier
+   * alone, and a default for the missing half is exactly the wrong answer this pair exists to stop:
+   * `--no-reduced-motion` is an override too and pins the opposite value.
+   */
+  readonly reducedMotionPin?: {
+    readonly tier: TReducedMotionOverride;
+    readonly reducedMotion: boolean;
+  } | undefined;
+}
+declare function createThemeCataloguePort(options: IThemeCataloguePortOptions): IThemeCataloguePort;
+//#endregion
+//#region src/tui-cli-adapter.d.ts
+/**
+ * CLI seam injected into the renderer.
+ *
+ * CMD-004 Phase 2 Stage C: READ-ONLY toward settings — the renderer re-reads the persisted
+ * settings document for display (statusline refresh-on-result) but never writes it. All settings
+ * mutations are host actions executed by the session layer via `ICommandHostAdapters`.
+ */
+interface ITuiCliAdapter {
+  getUserSettingsPath(): string;
+  readSettings(path: string): Record<string, TUniversalValue>;
+  reloadPluginCommandSource(registry: CommandRegistry): void;
+  applyActiveModelChange(cwd: string, modelId: string, options?: {
+    providerOverride?: string;
+  }): {
+    applied: boolean;
+  };
+  getGitBranch(cwd: string): string | undefined;
+  getProviderDisplayName(type: string): string;
+  /** Optional host-owned command shown when a completed fork can be reopened outside the TUI. */
+  formatResumeCommand?: (sessionId: string) => string;
+}
+//#endregion
+//#region src/render.d.ts
+interface IRenderOptions {
+  cwd: string;
+  livePromptTrace?: ILivePromptTracePort;
+  /** Product identity for terminal labels, title, and host-facing copy. */
+  productDisplayName?: string;
+  modelCommandToolPrefix?: string;
+  subagentHookEnvironmentNames?: ICreateSessionOptions['subagentHookEnvironmentNames'];
+  observerFailureWarningCode?: ICreateSessionOptions['observerFailureWarningCode'];
+  commandHookShell?: string;
+  /** Skip instruction files and plugin discovery (`--safe-mode`). */
+  bare?: boolean;
+  /** Run no hook the settings layers declare (`--safe-mode`). */
+  skipConfiguredHooks?: boolean;
+  promptFileReferenceTag?: string;
+  provider: IAIProvider;
+  providerErrorGuidance?: IProviderErrorGuidance;
+  projectAccess?: TWorkspaceProjectAccess;
+  projectSettingsPaths?: readonly IProjectSettingsPath[];
+  baselinePermissionAllow?: readonly string[];
+  /** Host-selected task-context root; absent means no framework task-directory scan. */
+  taskContext?: {
+    readonly enabled?: boolean;
+    readonly dir?: string;
+  };
+  contributionSources?: readonly IContributionSource[];
+  skillRoots?: readonly ISkillRootDescriptor[];
+  userSettingsSources?: readonly INodeHostSettingsSource[];
+  /**
+   * CLI-083 (issue #2287) — the org policy, forwarded to the session so `blockedCommands` is
+   * enforced on the plain `robota` path as well as under `--serve`.
+   *
+   * DECLARED, not merely spread through. The shell forwards this with
+   * `...(orgPolicy === null ? {} : { orgPolicy })`, and a spread bypasses TypeScript's
+   * excess-property check — so before this field existed the value compiled, arrived, and was
+   * dropped by `toChannelOptions` below, which copies field by field. The idiom that looked safest
+   * is what disabled the one check that would have caught the missing declaration.
+   */
+  orgPolicy?: IOrgPolicy | undefined;
+  /** Explicit authority- and permission-backed edit checkpoint capability. */
+  editCheckpointStore?: EditCheckpointStore;
+  providerOverride?: string | undefined;
+  /**
+   * #1844: forwarded to the session so `/provider switch` can construct the provider it switches TO.
+   *
+   * The session cannot discover these — they are assembled at the composition root from the provider
+   * packages. Without them the hot-swap throws with an empty supported-list, which is the failure
+   * this option exists to prevent rather than a nicety.
+   */
+  providerDefinitions?: readonly IProviderDefinition[];
+  providerType?: string | undefined;
+  modelId?: string;
+  /** CLI-1988: resolved provider-neutral response style. */
+  outputStyle?: IOutputStylePrompt;
+  /** ARCH-013: resolved preset effort, forwarded to the session's `effort` seam. */
+  effort?: ITuiInteractionChannelOptions['effort'];
+  temperature?: number;
+  maxOutputTokens?: number;
+  /** Preset prompt seed, distinct from the replacing `systemPrompt` option. */
+  presetSystemPrompt?: string;
+  /** CLI-sourced additive prompt text, composed before the TUI is rendered. */
+  appendSystemPrompt?: string;
+  responseFormat?: ITuiInteractionChannelOptions['responseFormat'];
+  language?: string;
+  permissionMode?: TPermissionMode;
+  maxTurns?: number;
+  allowedTools?: readonly string[];
+  deniedTools?: readonly string[];
+  version?: string;
+  sessionStore?: IInteractiveSessionStore;
+  disableSessionLoops?: boolean;
+  resolveDefaultLoopPrompt?: () => string;
+  resumeSessionId?: string;
+  showSessionPickerOnStart?: boolean;
+  /** FLOW-2006: text a deep link prefilled into the composer. Never submitted on its own. */
+  initialInput?: string;
+  /** Where that text came from; `external-link` renders the provenance notice. */
+  initialInputOrigin?: 'external-link';
+  forkSession?: boolean;
+  /** Issue #3081: the startup session is the target of a `/cd` from this directory. */
+  workspaceMovedFrom?: string;
+  sessionName?: string;
+  backgroundTaskRunners?: IBackgroundTaskRunner[];
+  /** MCP-004: the tool-call handoff policy the composition root computed for this runtime. */
+  toolCallHandoff?: IToolCallHandoffPolicy;
+  subagentRunnerFactory?: TSubagentRunnerFactory;
+  /**
+   * ARCH-005: subagent definitions contributed by the composition root (the capability packs
+   * `assembleProduct` merged). Forwarded to the session's `agentDefinitions` seam; absent ⇒ unchanged.
+   */
+  agentDefinitions?: readonly IAgentDefinition[];
+  agentDefinitionRoots?: readonly string[];
+  pluginDirectories?: {
+    readonly user?: string;
+    readonly project?: string;
+  };
+  /**
+   * ARCH-006: tools contributed by the composition root (the capability packs `assembleProduct` merged)
+   * and, when the profile hands the packs the whole tool surface, the suppressed framework default tier
+   * (`defaultTools: []`). Forwarded to the session's tool-composition seam; absent ⇒ unchanged.
+   */
+  additionalTools?: IToolWithEventService[];
+  defaultTools?: readonly IToolWithEventService[];
+  commandModules?: readonly ICommandModule[];
+  commandHostAdapters?: ICommandHostAdapters;
+  shellExec?: TShellExecFn;
+  /** REMOTE-006: optional remote-command policy (allow-by-default; local == remote). */
+  remoteCommandPolicy?: IRemoteCommandPolicy;
+  startupUpdateNotice?: Promise<string | undefined>;
+  transportRegistry?: ITransportRegistryView;
+  bindTransports?: ITuiInteractionChannelOptions['bindTransports'];
+  cliAdapter: ITuiCliAdapter;
+  reloadPluginCommandSource?: (registry: CommandRegistry) => void;
+  agentName?: string;
+  /** Active preset id selected at startup (PRESET-011 runtime state). Defaults to 'default'. */
+  activePresetId?: string;
+  /** Preset persona block composed as a `source: 'persona'` system-prompt section (priority 5). */
+  persona?: string;
+  /** Preset execution capability: activate agent runtime + subagent/background dispatch. */
+  enableParallelSubagents?: boolean;
+  /** Preset execution capability: run a post-task self-verification step. */
+  selfVerification?: boolean;
+  /**
+   * Called with each live channel (including session-switch re-creations). Lets the embedding
+   * product wire process-level concerns (ERR-001 G1: error routing into the live session).
+   */
+  onChannelReady?: (channel: TuiInteractionChannel) => void;
+  /**
+   * SELFHOST-008 P6: optional durable-memory store injected by the surface (agent-cli). Forwarded to the
+   * channel → `buildRuntimeSession`; absent ⇒ memory OFF (today's behavior). Enablement is surface-owned.
+   */
+  memoryStore?: IMemoryStore;
+  /** SELFHOST-008 P6: optional automatic post-turn capture policy (absent ⇒ capture OFF). */
+  automaticMemory?: IAutomaticMemoryConfig;
+  /** SELFHOST-008 P6: optional per-turn recall policy (absent ⇒ recall OFF, startup-only injection). */
+  recallMemory?: IPerTurnRecallConfig;
+  /**
+   * CLI-2004: the resolved screen-reader mode. DECLARED, not spread through — `toChannelOptions`
+   * below copies field by field, so an undeclared field compiles, arrives and is silently dropped
+   * (the ARCH-110 containment hazard the `orgPolicy` comment above records). Absent ⇒ mode OFF and
+   * today's byte stream is unchanged.
+   */
+  screenReader?: boolean | undefined;
+  /** Host-selected raw timing overrides; absent values use the renderer's defaults. */
+  screenReaderPacing?: IScreenReaderPacingOverrides;
+  /** Host-selected cursor and turn-mark overrides; absent values use terminal detection. */
+  terminalCapabilities?: ITerminalCapabilityOverrides;
+  /** CLI-2004: which input turned the mode on — printed in the confirmation line. */
+  screenReaderChannel?: TScreenReaderChannel | undefined;
+  /** CLI-2004: mode off, but the environment suggests a reader is running ⇒ one advisory line. */
+  screenReaderHint?: boolean | undefined;
+  /** BEHAVIOR-2003: one watched source shared with the optional `/keybindings` command. */
+  keybindingsSource?: IKeybindingsSource;
+  /**
+   * SCREEN-2002: the theme catalogue this run renders from, shared with the optional `/theme`
+   * command. DECLARED, not spread — see the `screenReader` note above. Absent ⇒ the built-ins.
+   */
+  themeRegistry?: IThemeRegistry;
+  /** SCREEN-2002: reduced motion as the product shell resolved it (settings ← env ← flag). */
+  reducedMotion?: boolean | undefined;
+  /** SCREEN-2002: which tier decided it, when that was not the settings. */
+  reducedMotionOverride?: TReducedMotionOverride | undefined;
+  /**
+   * SCREEN-1992: the focus-reporting override the product shell resolved from its own environment.
+   * `true` forces DECSET 1004 on, `false` is the kill switch, absent ⇒ on for an interactive TTY.
+   */
+  focusReporting?: boolean | undefined;
+  /**
+   * SCREEN-1993: prompt history, resolved by the product shell. `promptHistory` is the session-side
+   * writer (forwarded to the channel like `memoryStore`); `promptHistorySource` and
+   * `promptHistoryProject` feed the input area's Ctrl+R search. DECLARED, not spread through — the
+   * projection below copies field by field. Absent ⇒ nothing is written and `ctrl+r` is inert.
+   */
+  promptHistory?: IPromptHistoryOptions;
+  promptHistorySource?: IPromptHistorySource;
+  promptHistoryProject?: string;
+}
+declare function renderApp(options: IRenderOptions): Promise<void>;
+//#endregion
+//#region src/SupervisedSessionView.d.ts
+interface ISupervisedViewRow {
+  readonly id: string;
+  readonly liveness: 'alive' | 'dead' | 'unknown';
+  readonly control: 'available' | 'unavailable';
+  readonly activity: 'working' | 'needs-input' | 'idle' | 'unknown';
+  readonly nextLoopAt?: string;
+  readonly name?: string;
+  readonly cwd?: string;
+  readonly pr?: {
+    readonly url: string;
+    readonly host: string;
+    readonly number: number;
+    readonly kind: 'pull' | 'merge-request';
+  };
+  readonly problem?: 'invalid-registration';
+}
+interface ISupervisedSessionViewProps {
+  readonly loadRows: (signal: AbortSignal) => Promise<readonly ISupervisedViewRow[]>;
+  readonly onStop?: (id: string) => Promise<void>;
+  readonly onStart?: () => Promise<string>;
+  readonly onOpenPr?: (id: string, url: string) => Promise<void>;
+  readonly filteredByCwd?: boolean;
+  readonly filteredByName?: boolean;
+  readonly filteredByPr?: boolean;
+  readonly stateFilter?: TGroup;
+  readonly refreshMs?: number;
+}
+declare const GROUP_ORDER: readonly ["needs-input", "working", "idle", "unknown", "unverified", "dead"];
+type TGroup = typeof GROUP_ORDER[number];
+declare function renderSupervisedSessionView(options: ISupervisedSessionViewProps & {
+  readonly screenReader: boolean;
+  readonly screenReaderChannel?: TScreenReaderChannel;
+  readonly screenReaderHint?: boolean;
+}): Promise<void>;
+//#endregion
+//#region src/create-default-tui-cli-adapter.d.ts
+interface IDefaultTuiCliAdapterOptions {
+  providerDefinitions: readonly IProviderDefinition[];
+  reloadPluginCommandSource: (registry: CommandRegistry) => void;
+  userSettingsPath: string;
+  settingsSources: readonly TSettingsSource[];
+  formatResumeCommand?: (sessionId: string) => string;
+}
+declare function createDefaultTuiCliAdapter({ providerDefinitions, reloadPluginCommandSource, userSettingsPath, settingsSources, formatResumeCommand }: IDefaultTuiCliAdapterOptions): ITuiCliAdapter;
+//#endregion
+//#region src/theme/theme-document.d.ts
+interface IThemeDocumentInput {
+  /** The namespaced id the caller minted — `custom:<slug>` or `custom:<plugin>:<slug>`. */
+  readonly id: string;
+  /** The file's own name, for the `Skipped theme "<file>": …` line. */
+  readonly fileName: string;
+  readonly source: TThemeSource;
+  readonly text: string;
+}
+type TThemeDocumentResult = {
+  readonly ok: true;
+  readonly theme: ITuiTheme;
+} | {
+  readonly ok: false;
+  readonly error: string;
+};
+/**
+ * Untrusted text on its way into a line a terminal will print — the one escaping policy, exported
+ * so the surfaces that build their OWN diagnostics use it rather than re-deriving it.
+ *
+ * A diagnostic is the one part of a refused file that reaches the terminal, and it quotes what was
+ * wrong — so without this the injection floor the grammar provides is defeated by the message that
+ * reports a violation of it. Escaped rather than stripped, because an author has to SEE what their
+ * file contains (`"\u001b[31m"`) instead of a value that looks fine.
+ *
+ * `JSON.stringify` alone is NOT enough, and that is the whole reason this is a function: it escapes
+ * U+0000–U+001F and leaves U+007F and the C1 range literal — including U+009B and U+009D, the
+ * single-byte spellings of CSI and OSC. A terminal accepts both spellings (`sanitize-terminal-text.ts`
+ * says so and handles both), so quoting only the 7-bit one leaves the 8-bit one's parameters
+ * standing as a live sequence.
+ */
+declare function quoteThemeText(value: string): string;
+/**
+ * The same escaping WITHOUT the surrounding quotes, for a field a caller already quotes — so a
+ * refused file does not print as `Skipped theme ""My Theme.json"": …`.
+ */
+declare function escapeThemeText(value: string): string;
+/**
+ * Prose a surface did not write — a dependency's message, a path from the environment. Sanitized
+ * rather than quoted, because it is a sentence; `sanitizeTerminalText` removes both spellings of
+ * every sequence, and the tab/newline it keeps are flattened so one diagnostic stays one line.
+ */
+declare function sanitizeThemeProse(message: string): string;
+/**
+ * Parse one theme file. The `id`, the `source` and the `appearance` are NOT the document's to
+ * decide: the id is minted from where the file was found so nothing can shadow a built-in, the
+ * source is where it was read from, and the appearance follows the base a theme chose to extend.
+ */
+declare function parseThemeDocument(input: IThemeDocumentInput): TThemeDocumentResult;
+//#endregion
+export { type IDefaultTuiCliAdapterOptions, type IKeybindingDiagnostic, type IKeybindingSnapshot, type IKeybindingWarning, type IKeybindingsFilePort, type IKeybindingsSource, type INodeKeybindingsSourceOptions, type IRenderOptions, type IScreenReaderPacingOverrides, type ISupervisedSessionViewProps, type ISupervisedViewRow, type ITerminalCapabilityOverrides, type IThemeCataloguePortOptions, type IThemeDocumentInput, type IThemeRegistry, type IThemeResolution, type IThemeSkip, type ITuiCliAdapter, type ITuiCommandInteraction, type ITuiConfirmInteraction, type ITuiInteractionChannelOptions, type ITuiPickerInteraction, type ITuiPickerItem, type ITuiTheme, type TAnyTuiCommandInteraction, type TKeybindingAction, type TKeybindingContext, type TOnMissingArgsAction, type TScreenReaderChannel, type TThemeDocumentResult, type TThemeSource, TuiInteractionChannel, createDefaultTuiCliAdapter, createNodeKeybindingsSource, createThemeCataloguePort, createThemeRegistry, escapeThemeText, listBuiltInThemes, parseThemeDocument, quoteThemeText, renderApp, renderSupervisedSessionView, sanitizeThemeProse };
+//# sourceMappingURL=index.d.cts.map