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

package/src/theme/theme-styles.ts

@@ -0,0 +1,177 @@
+/**
+ * SCREEN-2002 — one theme, every encoding.
+ *
+ * Ink reads `colors` directly. `marked-terminal` wants chalk STYLE FUNCTIONS and `cli-highlight` wants
+ * a token→function map, so both are built here from the same values. Ink's own `colorize` is this
+ * mapping (`chalk[name]` / `chalk.hex` / `chalk.ansi256` / `chalk.rgb`), which is why deriving them is
+ * not the "name→SGR layer" SCREEN-006 refused to invent — chalk is already the layer, and a direct
+ * dependency.
+ *
+ * The STRUCTURE of a markdown or syntax token is fixed here, not themed: a heading is bold, a first
+ * heading underlined and bold, a blockquote italic, a deletion dim and struck through, an href
+ * underlined, and a syntax `type` dim — exactly what the two dependencies do today. A theme changes
+ * the colour and nothing else, which is what keeps the `dark` theme's rendering the one users know.
+ */
+import chalk, { Chalk, backgroundColorNames, foregroundColorNames } from 'chalk';
+
+import { THEME_SYNTAX_KEYS } from './theme-contracts.js';
+
+import type { IThemeMarkdown, IThemeSyntax, ITuiTheme, TThemeColor } from './theme-contracts.js';
+import type { ChalkInstance } from 'chalk';
+
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/iu;
+const ANSI256 = /^ansi256\((\d{1,3})\)$/iu;
+const RGB = /^rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)$/iu;
+const ANSI256_MAX = 255;
+
+/** The grammar, written once: the validator, the refusal below and the file parser all quote it. */
+export const THEME_COLOR_GRAMMAR = '<chalk name> | #rgb | #rrggbb | ansi256(n) | rgb(r,g,b)';
+
+/**
+ * chalk's own name tables, which it exports; its styles are prototype getters, so a table has to be
+ * built from the names rather than from `Object.keys(chalk)`. This is the same set Ink's `colorize`
+ * accepts, which is why the grammar needs no list of its own.
+ *
+ * A `Map`, not an object literal: an object built by `Object.fromEntries` inherits `Object.prototype`,
+ * so a lookup of `constructor`, `toString`, `valueOf` or `__proto__` answers TRUTHY and the
+ * `undefined` guard below never fires — a value that is not a colour name would be handed back as
+ * though it were a style. That value becomes reachable the moment a parsed user theme (work unit 3)
+ * reaches this builder.
+ */
+const CHALK_STYLES = new Map<string, ChalkInstance>(
+  [...foregroundColorNames, ...backgroundColorNames].map((name) => [name, chalk[name]]),
+);
+const FOREGROUND_NAMES = new Set<string>(foregroundColorNames);
+
+/** A FOREGROUND chalk name Ink would accept — a `bg…` name is not a token value. */
+function isChalkColorName(value: string): boolean {
+  return FOREGROUND_NAMES.has(value);
+}
+
+/** Whether a string is a colour in Ink's grammar. The one place the grammar is decided. */
+export function isThemeColor(value: string): boolean {
+  if (HEX.test(value)) return true;
+  const ansi = ANSI256.exec(value);
+  if (ansi) return Number(ansi[1]) <= ANSI256_MAX;
+  const rgb = RGB.exec(value);
+  if (rgb) return rgb.slice(1).every((part) => Number(part) <= ANSI256_MAX);
+  return isChalkColorName(value);
+}
+
+/**
+ * A value that reached the builder without being a colour is a DEFECT IN THIS PACKAGE, not in a
+ * user's file: `parseThemeDocument` refuses a theme file whole, and every built-in value is checked
+ * by TC-01. Before work unit 3 this case had two different silent answers — `foreground` handed
+ * back its base, `background`'s helper handed back `chalk.reset` — so the same bad value rendered
+ * as unstyled text in one place and as a reset in another, and neither said anything. Throwing is
+ * the one behaviour that cannot render a theme nobody can see is wrong.
+ */
+function refuseThemeColor(value: string): never {
+  throw new Error(
+    `Theme colour ${JSON.stringify(value)} is not in Ink's colour grammar (${THEME_COLOR_GRAMMAR}).`,
+  );
+}
+
+/**
+ * A foreground style for one theme value, optionally continuing a chain. The base matters: chalk
+ * emits its SGR in chain order, so `chalk.dim` + a colour is not the same bytes as a colour + `.dim`,
+ * and reproducing a dependency's own default means reproducing its order.
+ */
+export function foreground(color: TThemeColor, base: ChalkInstance = chalk): ChalkInstance {
+  if (HEX.test(color)) return base.hex(color);
+  const ansi = ANSI256.exec(color);
+  if (ansi) return base.ansi256(Number(ansi[1]));
+  const rgb = RGB.exec(color);
+  if (rgb) return base.rgb(Number(rgb[1]), Number(rgb[2]), Number(rgb[3]));
+  // Gated on the FOREGROUND names, not on the shared table: the table also holds the `bg…` entries
+  // that `background()` needs, so asking it alone would answer `foreground('bgRed')` with a
+  // background style — a name `isThemeColor` already refuses as a token value.
+  const named = isChalkColorName(color) ? CHALK_STYLES.get(color) : undefined;
+  if (named === undefined) refuseThemeColor(color);
+  // A named colour continues the chain through chalk's own getter on the base instance.
+  const chained = Reflect.get(base, color) as ChalkInstance | undefined;
+  return chained ?? named;
+}
+
+/** A background style for one theme value. */
+export function background(color: TThemeColor, base: ChalkInstance = chalk): ChalkInstance {
+  if (HEX.test(color)) return base.bgHex(color);
+  const ansi = ANSI256.exec(color);
+  if (ansi) return base.bgAnsi256(Number(ansi[1]));
+  const rgb = RGB.exec(color);
+  if (rgb) return base.bgRgb(Number(rgb[1]), Number(rgb[2]), Number(rgb[3]));
+  const capitalised = `bg${color.charAt(0).toUpperCase()}${color.slice(1)}`;
+  const chained = Reflect.get(base, capitalised) as ChalkInstance | undefined;
+  return chained ?? refuseThemeColor(color);
+}
+
+/**
+ * The diff rows are written by this package, not by a dependency, and their caller decides colour
+ * with its own `color` flag — so a caller that asked for colour gets it even where chalk's own
+ * detection says level 0. That is the behaviour the renderer had when it wrote the escapes by hand,
+ * and the reason `renderMarkdown(md, { color: true })` still emits them off a TTY.
+ *
+ * What is forced is colour, NOT depth. Overriding a DETECTED level would downsample the rest of the
+ * frame while these rows alone emit truecolor — visible on a 256-colour terminal with a hex-valued
+ * theme, where `#56b4e9` is `ESC[38;5;117m` at level 2 and `ESC[38;2;86;180;233m` at level 3. So the
+ * ambient level is kept whenever there is one, and only the OFF case is overridden.
+ */
+const TRUECOLOR = 3;
+const FORCED_CHALK = new Chalk({ level: TRUECOLOR });
+
+function diffRowBase(): ChalkInstance {
+  return chalk.level === 0 ? FORCED_CHALK : chalk;
+}
+
+/** The `marked-terminal` constructor options: theme colour + the structure that is not themed. */
+export function markdownRendererOptions(markdown: IThemeMarkdown): Record<string, ChalkInstance> {
+  return {
+    // Each chain reproduces marked-terminal's own default order, so the `dark` theme is byte-identical.
+    heading: foreground(markdown.heading).bold,
+    firstHeading: foreground(markdown.firstHeading).underline.bold,
+    code: foreground(markdown.code),
+    codespan: foreground(markdown.codespan),
+    link: foreground(markdown.link),
+    href: foreground(markdown.href).underline,
+    blockquote: foreground(markdown.blockquote).italic,
+    del: foreground(markdown.del, chalk.dim).strikethrough,
+    html: foreground(markdown.html),
+  };
+}
+
+/** The `cli-highlight` theme: every one of its seventeen coloured keys, so none falls back. */
+export function syntaxHighlightTheme(syntax: IThemeSyntax): Record<string, ChalkInstance> {
+  const theme: Record<string, ChalkInstance> = {};
+  for (const key of THEME_SYNTAX_KEYS) {
+    // `type` is `<colour>.dim` in cli-highlight's own theme: the modifier is structure, the colour is
+    // the theme's, and the order is the dependency's, so the `dark` theme is byte-identical.
+    theme[key] = key === 'type' ? foreground(syntax[key]).dim : foreground(syntax[key]);
+  }
+  return theme;
+}
+
+/** The styles the diff renderer writes around a row: background and foreground composed per row. */
+export interface IDiffRowStyles {
+  readonly added: (row: string) => string;
+  readonly removed: (row: string) => string;
+  readonly hunk: (row: string) => string;
+  /** Structure only: dim over the inherited foreground, never a theme colour. */
+  readonly meta: (row: string) => string;
+}
+
+export function diffRowStyles(theme: ITuiTheme): IDiffRowStyles {
+  const { markdown } = theme;
+  const base = diffRowBase();
+  const addedBackground = background(markdown.diffAddedBackground, base);
+  const addedForeground = foreground(markdown.diffAdded, base);
+  const removedBackground = background(markdown.diffRemovedBackground, base);
+  const removedForeground = foreground(markdown.diffRemoved, base);
+  return {
+    added: (row) => addedBackground(addedForeground(row)),
+    removed: (row) => removedBackground(removedForeground(row)),
+    hunk: foreground(markdown.diffHunk, base),
+    // Dim over the INHERITED foreground, as this renderer always wrote it — colouring it would be a
+    // rendering change dressed as a theme.
+    meta: (row) => base.dim(row),
+  };
+}

package/src/tool-summary-status.ts

@@ -0,0 +1,59 @@
+/**
+ * Persisted tool-summary → status-SSOT mapping (SCREEN-006).
+ *
+ * MessageList used to hand-roll its own glyph/color mapping for tool summaries, which drifted
+ * from `status-glyph.ts` (denied rendered plain yellow vs the SSOT's yellowBright). These
+ * helpers route the persisted summary items through `toolStateStatusKind` + `STATUS_SYMBOL`
+ * so tool status renders one way everywhere.
+ */
+
+import { humanizeToolArgument, humanizeToolName } from './humanize-tool-name.js';
+import { STATUS_SYMBOL, toolStateStatusKind } from './status-glyph.js';
+
+import type { TUiStatusKind } from './status-glyph.js';
+import type { IToolCallSummary } from './utils/tool-call-extractor.js';
+import type { IToolState } from '@robota-sdk/agent-interface-session';
+
+/** A tool item as persisted in a `tool-summary` history entry (loosely-typed session data). */
+export type TToolSummaryItem = {
+  toolName: string;
+  firstArg?: string;
+  isRunning?: boolean;
+  result?: string;
+  diffLines?: IToolCallSummary['diffLines'];
+  diffFile?: string;
+  toolResultData?: string;
+};
+
+/**
+ * Map a persisted tool-summary item to the semantic status kind — via the `status-glyph.ts`
+ * SSOT. A command-output error (non-zero exit surfaced by `formatCommandOutputSummary`)
+ * overrides the recorded result; the caller passes that flag so this module stays free of
+ * the command-output dependency.
+ */
+export function toolSummaryStatusKind(
+  tool: TToolSummaryItem,
+  hasCommandOutputError: boolean,
+): TUiStatusKind {
+  if (hasCommandOutputError) return 'error';
+  const result: IToolState['result'] =
+    tool.result === 'success' || tool.result === 'error' || tool.result === 'denied'
+      ? tool.result
+      : undefined;
+  return toolStateStatusKind({
+    toolName: tool.toolName,
+    firstArg: tool.firstArg ?? '',
+    isRunning: tool.isRunning ?? false,
+    result,
+  });
+}
+
+/** One-line summary label: SSOT glyph + humanized tool name + first argument. */
+export function getToolSummaryLabel(
+  tool: TToolSummaryItem,
+  kind: TUiStatusKind,
+  prefix?: string,
+): string {
+  const argument = humanizeToolArgument(tool.firstArg);
+  return `${STATUS_SYMBOL[kind]} ${humanizeToolName(tool.toolName, prefix)}${argument ? `(${argument})` : ''}`;
+}

package/src/tui-app-channel-port.ts

@@ -0,0 +1,83 @@
+import type { TerminalHandoffController } from './terminal-handoff-controller.js';
+import type { ITuiSessionEventNotice } from './tui-session-events.js';
+import type { IPendingPermissionRequest } from './types.js';
+import type {
+  IActionRequest,
+  IHistoryEntry,
+  TActionResponse,
+  TModelEffortSelection,
+  TSessionEndReason,
+  TPermissionMode,
+} from '@robota-sdk/agent-core';
+import type { ICommand } from '@robota-sdk/agent-interface-command';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type { IInteractiveSessionEvents, IToolState } from '@robota-sdk/agent-interface-session';
+
+export interface ITuiCommandQueryPort {
+  getCommands(filter?: string): ICommand[];
+  getSubcommands(commandName: string): ICommand[];
+}
+
+export type TTuiSessionUiEventName = 'ui_intent' | 'session_renamed';
+
+export interface ITuiSessionUiEventPort {
+  on<E extends TTuiSessionUiEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+  off<E extends TTuiSessionUiEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+}
+
+export interface ITuiRuntimeStatusSnapshot {
+  permissionMode: TPermissionMode;
+  sessionId: string;
+  activePresetId?: string;
+  effort?: TModelEffortSelection;
+}
+
+export 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.
+ */
+export 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;
+}

package/src/tui-channel-lifecycle-coordinator.ts

@@ -0,0 +1,149 @@
+import type { TSessionEndReason } from '@robota-sdk/agent-core';
+
+export interface ITuiChannelShutdownRequest {
+  reason: TSessionEndReason;
+  message: string;
+}
+
+export interface ITuiChannelLifecycleOperations {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  beginShutdown(): void;
+  shutdownSession(request: ITuiChannelShutdownRequest): Promise<void>;
+}
+
+/** Marks a startup failure whose rollback also failed, so retrying cannot duplicate live resources. */
+export class TuiChannelStartRollbackError extends AggregateError {}
+
+/** Owns channel lifecycle transitions and bounds SDK shutdown without owning presentation state. */
+export class TuiChannelLifecycleCoordinator {
+  private started = false;
+  private startPromise: Promise<void> | undefined;
+  private teardownBegun = false;
+  private stopped = false;
+  private shuttingDown = false;
+  private shutdownPromise: Promise<void> | undefined;
+  private stopPromise: Promise<void> | undefined;
+
+  constructor(
+    private readonly operations: ITuiChannelLifecycleOperations,
+    private readonly defaultShutdownTimeoutMs: number,
+  ) {}
+
+  get isShuttingDown(): boolean {
+    return this.shuttingDown;
+  }
+
+  /** False before startup and immediately when teardown begins, even if teardown later fails. */
+  get isActiveForPeerStatus(): boolean {
+    return this.started && !this.teardownBegun && !this.shuttingDown;
+  }
+
+  async start(): Promise<void> {
+    if (this.teardownBegun) {
+      throw new Error('Cannot start a channel after teardown has begun.');
+    }
+    if (this.started) return;
+    const pendingStart = (this.startPromise ??= this.operations.start());
+    try {
+      await pendingStart;
+      this.started = true;
+    } catch (error) {
+      if (error instanceof TuiChannelStartRollbackError) this.teardownBegun = true;
+      throw error;
+    } finally {
+      if (this.startPromise === pendingStart) this.startPromise = undefined;
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.teardownBegun = true;
+    if (this.stopped) return;
+    this.stopPromise ??= this.performStop();
+    try {
+      await this.stopPromise;
+    } catch (error) {
+      // A failed teardown is retryable; claiming stopped here would strand owned resources.
+      this.stopPromise = undefined;
+      throw error;
+    }
+  }
+
+  private async performStop(): Promise<void> {
+    const pendingStart = this.startPromise;
+    let startError: Error | undefined;
+    if (pendingStart !== undefined) {
+      try {
+        await pendingStart;
+      } catch (cause) {
+        startError = cause instanceof Error ? cause : new Error(String(cause));
+      }
+    }
+    let stopError: Error | undefined;
+    try {
+      await this.operations.stop();
+    } catch (error) {
+      stopError = error instanceof Error ? error : new Error(String(error));
+    }
+    this.shutdownPromise ??= this.shutdownSessionBounded(
+      { reason: 'other', message: 'channel stopped' },
+      this.defaultShutdownTimeoutMs,
+    );
+    await this.shutdownPromise;
+    if (stopError !== undefined && startError !== undefined) {
+      throw new AggregateError(
+        [startError, stopError],
+        'TUI channel start and teardown both failed.',
+      );
+    }
+    if (stopError !== undefined) throw stopError;
+    this.started = false;
+    this.stopped = true;
+    if (startError !== undefined) throw startError;
+  }
+
+  async shutdown(options?: { reason?: TSessionEndReason; timeoutMs?: number }): Promise<void> {
+    this.teardownBegun = true;
+    if (!this.shuttingDown) {
+      this.shuttingDown = true;
+      this.operations.beginShutdown();
+    }
+    const pendingStop = this.stopPromise;
+    if (pendingStop !== undefined) {
+      await pendingStop.catch(() => undefined); // allow-fallback: the stop caller owns teardown failure
+      return;
+    }
+    this.shutdownPromise ??= this.performShutdown(options);
+    await this.shutdownPromise;
+  }
+
+  private async performShutdown(options?: {
+    reason?: TSessionEndReason;
+    timeoutMs?: number;
+  }): Promise<void> {
+    const pendingStart = this.startPromise;
+    if (pendingStart !== undefined) {
+      await pendingStart.catch(() => undefined); // allow-fallback: the start caller owns startup failure
+    }
+    await this.shutdownSessionBounded(
+      { reason: options?.reason ?? 'prompt_input_exit', message: 'CLI shutdown' },
+      options?.timeoutMs ?? this.defaultShutdownTimeoutMs,
+    );
+  }
+
+  private async shutdownSessionBounded(
+    request: ITuiChannelShutdownRequest,
+    timeoutMs: number,
+  ): Promise<void> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, timeoutMs);
+      timer.unref?.();
+    });
+    await Promise.race([
+      this.operations.shutdownSession(request).catch(() => undefined), // allow-fallback: shutdown is best-effort during process exit and remains timeout-bounded
+      timeout,
+    ]);
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/tui-channel-options.ts

@@ -0,0 +1,172 @@
+import type { IAttentionSource } from './attention/attention-tracker.js';
+import type { TerminalHandoffController } from './terminal-handoff-controller.js';
+import type {
+  IAIProvider,
+  IProviderDefinition,
+  IToolWithEventService,
+  TPermissionMode,
+} from '@robota-sdk/agent-core';
+import type {
+  IAgentDefinition,
+  IAutomaticMemoryConfig,
+  IBackgroundTaskRunner,
+  ICommandHostAdapters,
+  IOutputStylePrompt,
+  IOrgPolicy,
+  IProviderErrorGuidance,
+  IProjectSettingsPath,
+  INodeHostSettingsSource,
+  ICommandModule,
+  ICreateSessionOptions,
+  ILivePromptTracePort,
+  EditCheckpointStore,
+  IMemoryStore,
+  IPromptHistoryOptions,
+  IPerTurnRecallConfig,
+  IRemoteCommandPolicy,
+  IToolCallHandoffPolicy,
+  TShellExecFn,
+  TSubagentRunnerFactory,
+  TWorkspaceProjectAccess,
+} from '@robota-sdk/agent-framework';
+import type { CommandRegistry } from '@robota-sdk/agent-framework';
+import type {
+  IInteractiveSession,
+  IInteractiveSessionStore,
+  TInteractiveEventName,
+} from '@robota-sdk/agent-interface-session';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+/**
+ * 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.
+ */
+export 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;
+}

package/src/tui-cli-adapter-context.tsx

@@ -0,0 +1,13 @@
+import { createContext, useContext } from 'react';
+
+import type { ITuiCliAdapter } from './tui-cli-adapter.js';
+
+const TuiCliAdapterContext = createContext<ITuiCliAdapter | null>(null);
+
+export const TuiCliAdapterProvider = TuiCliAdapterContext.Provider;
+
+export function useTuiCliAdapter(): ITuiCliAdapter {
+  const adapter = useContext(TuiCliAdapterContext);
+  if (!adapter) throw new Error('TuiCliAdapterContext not provided');
+  return adapter;
+}

package/src/tui-cli-adapter.ts

@@ -0,0 +1,24 @@
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+import type { CommandRegistry } from '@robota-sdk/agent-framework';
+
+/**
+ * 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`.
+ */
+export 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;
+}