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

package/dist/node/index.d.ts

@@ -0,0 +1,1224 @@
+import React from "react";
+import { CommandRegistry, EditCheckpointStore, IAgentDefinition, IAutomaticMemoryConfig, IBackgroundTaskRunner, ICommandHostAdapters, ICommandHostTerminalHandoff, ICommandHostWorkspace, ICommandModule, IContributionSource, ICreateSessionOptions, ILivePromptTracePort, IMemoryStore, INodeHostSettingsSource, IOrgPolicy, IOutputStylePrompt, IPerTurnRecallConfig, IProjectSettingsPath, IPromptHistoryOptions, IProviderErrorGuidance, IRemoteCommandPolicy, ISkillRootDescriptor, IToolCallHandoffPolicy, InteractiveSession, TInteractiveSessionOptions, TSettingsSource, TShellExecFn, TSubagentRunnerFactory, TWorkspaceProjectAccess } from "@robota-sdk/agent-framework";
+import { IAIProvider, IActionRequest, IContextWindowState, IHistoryEntry, IProviderDefinition, IToolWithEventService, TActionResponse, TModelEffortSelection, TPermissionMode, TProviderCredentialResolver, TSessionEndReason, TToolArgs, TUniversalValue } from "@robota-sdk/agent-core";
+import { IBranchEvent, ICommandInfo, IContextFileRefreshedEvent, IExecutionResult, IInteractiveSession, IInteractiveSessionEvents, IInteractiveSessionStore, IPlanApprovalEvent, IPromptHistorySource, ISessionListingEntry, ITerminalHandoff, IToolState, TInteractiveEventName, TPermissionRequester, TPermissionResultValue } from "@robota-sdk/agent-interface-session";
+import { TClientMessage, TServerMessage } from "@robota-sdk/agent-transport/client";
+import { IExecutionDetailPage, IExecutionWorkspaceSnapshot } from "@robota-sdk/agent-interface-execution";
+import { ICommand, ICommandResult, IThemeAppearanceState, IThemeCataloguePort, TAppearanceSettingsPatch, 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/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/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: Pick<IExecutionResult, "contextState">) => 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;
+  /**
+   * A host's history as a terminal attached to it last read it, then the echoes of prompts the host
+   * has not recorded yet. Unlike `syncHistory`, an empty history is an answer: the host's session
+   * has no entries.
+   */
+  syncHostHistory(entries: readonly IHistoryEntry[], echoes: readonly IHistoryEntry[]): void;
+  private withLocalNotices;
+  /** 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/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;
+  /** Issue #3288 §1: a background agent's own request, forwarded to the person. */
+  requester?: TPermissionRequester;
+  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;
+  /** The model the session reports, when its host says; absent ⇒ the one this terminal was started with. */
+  modelId?: string;
+}
+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;
+  };
+  /**
+   * The sessions the session picker offers, when the host keeps them (a terminal attached to a
+   * daemon). Absent ⇒ the picker lists this terminal's own session store. A host that keeps sessions
+   * live says which rows run now and how many clients are on each; the picker shows both.
+   */
+  hostSessions?: readonly ISessionListingEntry[];
+  /**
+   * Changes when the transcript starts over for another session while the App keeps this channel.
+   * The terminal prints the transcript once and counts what it printed, so a new transcript is
+   * printed from its start. Absent ⇒ the transcript never starts over under this channel.
+   */
+  transcriptGeneration?: number;
+  /**
+   * True while this terminal only observes the session: it sends nothing that changes it, and the
+   * App offers no key that would. Absent ⇒ the terminal drives the session.
+   */
+  readOnly?: boolean;
+  /**
+   * True when this terminal is attached to a session a host runs: leaving only detaches it, and
+   * Ctrl-] leaves too. Absent ⇒ the terminal runs its own session, where Ctrl-] means nothing.
+   */
+  attached?: boolean;
+}
+/**
+ * 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[];
+  environment?: Readonly<Record<string, string | undefined>>;
+  resolveProviderCredential?: import('@robota-sdk/agent-core').TProviderCredentialResolver;
+  /**
+   * Explicit authority- and permission-backed edit checkpoint capability for this channel's one
+   * session. Never shared with another channel's session: a store holds one turn in progress.
+   */
+  editCheckpointStore?: EditCheckpointStore;
+  /** The host's way to build each external-event grant's verifier; absent, no grant opens. */
+  externalEventVerifierFactory?: TInteractiveSessionOptions['externalEventVerifierFactory'];
+  /** The run's grant history, shared by every session this TUI binds (#3189). */
+  externalEventGrantHistory?: TInteractiveSessionOptions['externalEventGrantHistory'];
+  /**
+   * 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;
+  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[];
+  /** The sandbox the shell tools run under, so the session can let a confined command skip the prompt. */
+  sandboxClient?: ICreateSessionOptions['sandboxClient'];
+  toolExecutionPolicy?: ICreateSessionOptions['toolExecutionPolicy'];
+  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 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;
+  /** Esc on an idle prompt: the session decides which waiting loop, if any, stops. */
+  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 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/attached-session-connection.d.ts
+/**
+ * A terminal's end of the session protocol to a session it is attached to. The terminal only sends
+ * and listens; closing the connection belongs to whoever opened it.
+ */
+interface IAttachedSessionConnection {
+  send(message: TClientMessage): void;
+  subscribe(listener: (message: TServerMessage) => void): () => void;
+  onClose(listener: () => void): () => void;
+}
+/** Why an attached terminal stopped showing the session: the user left, or the connection closed. */
+type TAttachedSessionEnd = 'user' | 'closed';
+//#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/wire-tui-client-commands.d.ts
+/** What a client-run command may use: this terminal's handoff and working directory. */
+type TTuiClientCommandHost = ICommandHostTerminalHandoff & ICommandHostWorkspace;
+/**
+ * A command this terminal runs itself. Declared here rather than imported: the command package's
+ * `createTerminalClientCommands` produces objects of this shape, and this package does not depend on
+ * the command package.
+ */
+interface ITuiClientCommand {
+  readonly name: string;
+  execute(host: TTuiClientCommandHost, args: string): ICommandResult | Promise<ICommandResult>;
+}
+/** The client-run commands, and how this terminal writes what they change. */
+interface ITuiClientCommands {
+  readonly commands: readonly ITuiClientCommand[];
+  /** Writes the appearance keys of the user's settings; resolves when written. */
+  writeAppearanceSettings(patch: TAppearanceSettingsPatch): void | Promise<void>;
+}
+//#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[];
+  environment?: Readonly<Record<string, string | undefined>>;
+  resolveProviderCredential?: TProviderCredentialResolver;
+  /**
+   * CLI-083 (issue #2287) — the org policy, forwarded to the session so `blockedCommands` is
+   * enforced on the direct CLI 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;
+  /**
+   * Builds the authority- and permission-backed edit checkpoint store for one session; absent, no
+   * session keeps checkpoints. A factory, not a store: a session switch builds the next channel
+   * while the old session may still be finishing a turn, and a store holds one turn in progress.
+   */
+  createEditCheckpointStore?: () => EditCheckpointStore;
+  /** The host's way to build each external-event grant's verifier; absent, no grant opens. */
+  externalEventVerifierFactory?: TInteractiveSessionOptions['externalEventVerifierFactory'];
+  /**
+   * #3189: the run's grant history, handed to every session this TUI builds so a switch replays no
+   * spent token and resets no rate. DECLARED for the reason `orgPolicy` above is.
+   */
+  externalEventGrantHistory?: TInteractiveSessionOptions['externalEventGrantHistory'];
+  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[];
+  /** The sandbox the shell tools run under, so the session can let a confined command skip the prompt. */
+  sandboxClient?: ICreateSessionOptions['sandboxClient'];
+  toolExecutionPolicy?: ICreateSessionOptions['toolExecutionPolicy'];
+  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>;
+/**
+ * What the full TUI needs to attach to a session a host runs (a daemon) instead of building one.
+ * Only presentation options: everything else belongs to the host's session.
+ */
+interface IRenderAttachedAppOptions extends Pick<IRenderOptions, 'cwd' | 'productDisplayName' | 'version' | 'cliAdapter' | 'screenReader' | 'screenReaderChannel' | 'screenReaderHint' | 'screenReaderPacing' | 'terminalCapabilities' | 'keybindingsSource' | 'themeRegistry' | 'reducedMotion' | 'reducedMotionOverride' | 'focusReporting' | 'promptHistorySource' | 'promptHistoryProject'> {
+  /** The session protocol connection; closing it belongs to the caller. */
+  readonly connection: IAttachedSessionConnection;
+  /** Shown as the session's label until the session reports its own name. */
+  readonly sessionLabel: string;
+  /** This terminal's driver id, from the attach handshake. */
+  readonly driverId: string;
+  /** Commands this terminal runs itself (`/shell`, `/theme`, ...); the host never sees them. */
+  readonly clientCommands?: ITuiClientCommands;
+  /**
+   * How this terminal is on the session: `'drive'` (the default) sends prompts and answers questions;
+   * `'observe'` only watches, and the host refuses anything else from it.
+   */
+  readonly mode?: 'drive' | 'observe';
+  /** Print the screen-reader line; false when this process already printed it. Default true. */
+  readonly announce?: boolean;
+}
+/**
+ * Render the full TUI on a session the terminal is attached to over the session protocol. Leaving
+ * only detaches: the session keeps running. Resolves `'user'` when the user leaves (`/exit`,
+ * Ctrl-C) and `'closed'` when the connection closed.
+ */
+declare function renderAttachedApp(options: IRenderAttachedAppOptions): Promise<TAttachedSessionEnd>;
+//#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';
+  /** The verified registration generation; a row without one never offers an action. Never rendered. */
+  readonly generation?: string;
+}
+/** An attach the user confirmed in the view, bound to the process start the row showed. */
+interface ISupervisedAttachRequest {
+  readonly id: string;
+  readonly generation: string;
+  readonly mode: 'drive' | 'observe';
+  /** How the view was grouped, so it can reopen the same way after the attach. */
+  readonly groupByDirectory: boolean;
+}
+/** How the view ended: closed, or handed to the host to attach and then come back. */
+type TSupervisedViewExit = {
+  readonly kind: 'closed';
+} | ({
+  readonly kind: 'attach';
+} & ISupervisedAttachRequest);
+/**
+ * How a new session starts in a folder that is not trusted: trusted first (`trust` records the grant),
+ * or `restricted`, without the project's own configuration. A person chose it in the view.
+ */
+type TSupervisedStartTrustChoice = 'trust' | 'restricted';
+/** What the person is asked about: the folder a new session would start in, and what trust loads. */
+interface ISupervisedStartTrustQuestion {
+  readonly folder: string;
+  /** What trusting it would load, one line each. */
+  readonly loads: readonly string[];
+}
+interface ISupervisedSessionViewProps {
+  readonly loadRows: (signal: AbortSignal) => Promise<readonly ISupervisedViewRow[]>;
+  /** Called once the user confirmed; the view then closes so the host can attach this terminal. */
+  readonly onAttach?: (request: ISupervisedAttachRequest) => void;
+  /** Receives the generation the row displayed, so a session restarted under the same id is refused. */
+  readonly onStop?: (id: string, generation: string) => Promise<void>;
+  readonly onStart?: (choice?: TSupervisedStartTrustChoice) => Promise<string>;
+  /** The question to ask when the folder a new session starts in is not trusted yet; none otherwise. */
+  readonly startTrustQuestion?: () => Promise<ISupervisedStartTrustQuestion | undefined>;
+  /** Product-owned command shown when a long trust question is shortened. */
+  readonly trustStatusCommand?: string;
+  readonly onOpenPr?: (id: string, url: string, generation: string) => Promise<void>;
+  readonly filteredByCwd?: boolean;
+  readonly filteredByName?: boolean;
+  readonly filteredByPr?: boolean;
+  readonly stateFilter?: TGroup;
+  readonly refreshMs?: number;
+  /** The row to select first, when it is still listed — the one an attach left from. */
+  readonly initialSelectedId?: string;
+  readonly initialGroupByDirectory?: boolean;
+}
+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;
+  /** Print the screen-reader line; false when this process already printed it. */
+  readonly announce?: boolean;
+}): Promise<TSupervisedViewExit>;
+//#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 IAttachedSessionConnection, type IDefaultTuiCliAdapterOptions, type IKeybindingDiagnostic, type IKeybindingSnapshot, type IKeybindingWarning, type IKeybindingsFilePort, type IKeybindingsSource, type INodeKeybindingsSourceOptions, type IRenderAttachedAppOptions, type IRenderOptions, type IScreenReaderPacingOverrides, type ISupervisedAttachRequest, type ISupervisedSessionViewProps, type ISupervisedStartTrustQuestion, type ISupervisedViewRow, type ITerminalCapabilityOverrides, type IThemeCataloguePortOptions, type IThemeDocumentInput, type IThemeRegistry, type IThemeResolution, type IThemeSkip, type ITuiCliAdapter, type ITuiClientCommand, type ITuiClientCommands, type ITuiCommandInteraction, type ITuiConfirmInteraction, type ITuiInteractionChannelOptions, type ITuiPickerInteraction, type ITuiPickerItem, type ITuiTheme, type TAnyTuiCommandInteraction, type TAttachedSessionEnd, type TKeybindingAction, type TKeybindingContext, type TOnMissingArgsAction, type TScreenReaderChannel, type TSupervisedStartTrustChoice, type TSupervisedViewExit, type TThemeDocumentResult, type TThemeSource, type TTuiClientCommandHost, TuiInteractionChannel, createDefaultTuiCliAdapter, createNodeKeybindingsSource, createThemeCataloguePort, createThemeRegistry, escapeThemeText, listBuiltInThemes, parseThemeDocument, quoteThemeText, renderApp, renderAttachedApp, renderSupervisedSessionView, sanitizeThemeProse };
+//# sourceMappingURL=index.d.ts.map