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

package/src/attention/focus-input-filter.ts

@@ -0,0 +1,131 @@
+import { Readable } from 'node:stream';
+
+/**
+ * SCREEN-1992: the stdin proxy handed to Ink's `render({ stdin })`.
+ *
+ * Ink tokenizes `ESC [ I` as a keypress and every `useInput` listener would receive `[I`, so the
+ * composer would type it. The proxy sits in front of the real stdin, strips the two focus sequences
+ * while mode 1004 is negotiated, reports focus and keystrokes, and forwards every other byte
+ * unchanged — including a split escape sequence and a bracketed paste, which are Ink's to parse.
+ */
+const ESC = 0x1b;
+const FOCUS_IN = '\x1b[I';
+const FOCUS_OUT = '\x1b[O';
+
+export interface IFocusInputFilterResult {
+  /** The bytes Ink receives, byte-identical to the input apart from the stripped focus sequences. */
+  readonly forwarded: Buffer;
+  readonly focusIn: number;
+  readonly focusOut: number;
+}
+
+/** Pure: split one chunk into focus events and the bytes that remain. */
+export function filterFocusSequences(chunk: Buffer, negotiated: boolean): IFocusInputFilterResult {
+  if (!negotiated || !chunk.includes(ESC)) return { forwarded: chunk, focusIn: 0, focusOut: 0 };
+  const text = chunk.toString('latin1');
+  let focusIn = 0;
+  let focusOut = 0;
+  let forwarded = '';
+  let index = 0;
+  while (index < text.length) {
+    if (text.startsWith(FOCUS_IN, index)) {
+      focusIn += 1;
+      index += FOCUS_IN.length;
+    } else if (text.startsWith(FOCUS_OUT, index)) {
+      focusOut += 1;
+      index += FOCUS_OUT.length;
+    } else {
+      forwarded += text[index];
+      index += 1;
+    }
+  }
+  return { forwarded: Buffer.from(forwarded, 'latin1'), focusIn, focusOut };
+}
+
+export interface IFocusReportingStdinHooks {
+  /** Whether mode 1004 is currently negotiated; read per chunk so a handoff can flip it. */
+  readonly negotiated: () => boolean;
+  readonly onFocusIn: () => void;
+  readonly onFocusOut: () => void;
+  /** Any byte that was not a focus sequence. */
+  readonly onKeystroke: () => void;
+}
+
+type TStdinDataListener = (chunk: Buffer | string) => void;
+
+/** What ink 7.1.1 reads from the stream it is given (`App.js` input handling, `ink.js` kitty probe). */
+type TInkStdinSurface = Pick<
+  Readable,
+  'read' | 'setEncoding' | 'unshift' | 'on' | 'addListener' | 'removeListener'
+> & {
+  readonly isTTY: boolean;
+  // `tty.ReadStream` types these as returning itself; Ink discards the return value.
+  setRawMode(mode: boolean): TInkStdinSurface;
+  ref(): TInkStdinSurface;
+  unref(): TInkStdinSurface;
+};
+
+/** The subset of the real stdin the proxy touches (what `process.stdin` provides). */
+export interface IFocusReportingStdinSource {
+  readonly isTTY?: boolean;
+  on(event: 'data', listener: TStdinDataListener): void;
+  off(event: 'data', listener: TStdinDataListener): void;
+  setRawMode?: (mode: boolean) => void;
+  ref?: () => void;
+  unref?: () => void;
+}
+
+export class FocusReportingStdin extends Readable {
+  private readonly onData = (data: Buffer | string): void => {
+    const chunk = typeof data === 'string' ? Buffer.from(data) : data;
+    const result = filterFocusSequences(chunk, this.hooks.negotiated());
+    for (let i = 0; i < result.focusOut; i += 1) this.hooks.onFocusOut();
+    for (let i = 0; i < result.focusIn; i += 1) this.hooks.onFocusIn();
+    if (result.forwarded.length === 0) return;
+    this.hooks.onKeystroke();
+    this.push(result.forwarded);
+  };
+
+  constructor(
+    private readonly source: IFocusReportingStdinSource,
+    private readonly hooks: IFocusReportingStdinHooks,
+  ) {
+    super({ read() {} });
+    source.on('data', this.onData);
+  }
+
+  get isTTY(): boolean {
+    return this.source.isTTY === true;
+  }
+
+  setRawMode(mode: boolean): this {
+    this.source.setRawMode?.(mode);
+    return this;
+  }
+
+  ref(): this {
+    this.source.ref?.();
+    return this;
+  }
+
+  unref(): this {
+    this.source.unref?.();
+    return this;
+  }
+
+  /**
+   * Ink declares `stdin?: NodeJS.ReadStream` (a `tty.ReadStream`, which cannot be constructed
+   * without an fd) but touches only the members named in `TInkStdinSurface` — verified against ink
+   * 7.1.1's App and Ink classes. Assigning `this` to that surface is a typed check that every one of
+   * them exists here; the final narrowing is from the surface Ink reads to the type it declares.
+   */
+  asInkStdin(): NodeJS.ReadStream {
+    const surface: TInkStdinSurface = this;
+    return surface as NodeJS.ReadStream;
+  }
+
+  /** Detach from the underlying stdin; the proxy emits nothing afterwards. */
+  detach(): void {
+    this.source.off('data', this.onData);
+  }
+}

package/src/attention/interval-recap.ts

@@ -0,0 +1,148 @@
+import { MINUTES_PER_HOUR, MS_PER_MINUTE } from './time-units.js';
+
+import type { TExecutionNormalizedState } from '@robota-sdk/agent-interface-execution';
+
+/**
+ * SCREEN-1992: one line for what happened while the user was away.
+ *
+ * Counts only while unattended; `onReturned` renders the interval and resets it. Nothing here
+ * inspects the session — the coordinator feeds it the channel events it already receives.
+ */
+export const RECAP_MAX_WIDTH = 120;
+
+/** The framework's `TTurnSource` plus whatever a future source adds; only `agent-wakeup` is special here. */
+type TTurnSource = string;
+
+const TERMINAL_STATES: ReadonlySet<TExecutionNormalizedState> = new Set([
+  'completed',
+  'failed',
+  'stopped',
+]);
+
+export class IntervalRecap {
+  private lostAt: number | undefined;
+  private lastTurnSource: TTurnSource = 'user';
+  private turnsFinished = 0;
+  private wakeTurnsFinished = 0;
+  private needsInputCount = 0;
+  private errorCount = 0;
+  /** Every entry's latest state, attended or not — the baseline an interval starts from. */
+  private readonly currentStates = new Map<string, TExecutionNormalizedState>();
+  /** Entries that were not terminal when attention was lost and are terminal now. */
+  private readonly reachedTerminal = new Map<string, TExecutionNormalizedState>();
+  private baseline = new Map<string, TExecutionNormalizedState>();
+  private baselinePending = false;
+
+  get away(): boolean {
+    return this.lostAt !== undefined;
+  }
+
+  onLost(atIso: string): void {
+    this.lostAt = Date.parse(atIso);
+    this.reset();
+    this.baseline = new Map(this.currentStates);
+    // Lost before any snapshot arrived (a channel wired while the user is already away): the first
+    // snapshot is the baseline, so a resumed session's restored terminal tasks are not "news".
+    this.baselinePending = this.currentStates.size === 0;
+  }
+
+  /** The recap line for the interval just ended, or undefined when there is nothing to say. */
+  onReturned(atIso: string): string | undefined {
+    if (this.lostAt === undefined) return undefined;
+    const elapsedMs = Math.max(0, Date.parse(atIso) - this.lostAt);
+    this.lostAt = undefined;
+    const parts = this.parts();
+    this.reset();
+    if (parts.length === 0) return undefined;
+    return bound(`While away ${formatElapsed(elapsedMs)}: ${parts.join(' · ')}`);
+  }
+
+  turnSource(source: TTurnSource): void {
+    this.lastTurnSource = source;
+  }
+
+  turnCompleted(): void {
+    if (!this.away) return;
+    this.turnsFinished += 1;
+    if (this.lastTurnSource === 'agent-wakeup') this.wakeTurnsFinished += 1;
+  }
+
+  needsInput(): void {
+    if (this.away) this.needsInputCount += 1;
+  }
+
+  error(): void {
+    if (this.away) this.errorCount += 1;
+  }
+
+  /**
+   * A workspace entry's current state. Only an entry that REACHED a terminal state during the
+   * interval is counted: one already terminal when attention was lost is old news, and one that
+   * left the terminal state again (a resumed schedule) is dropped.
+   */
+  entryState(entryId: string, state: TExecutionNormalizedState): void {
+    this.currentStates.set(entryId, state);
+    if (!this.away) return;
+    if (this.baselinePending) {
+      this.baseline.set(entryId, state);
+      return;
+    }
+    const before = this.baseline.get(entryId);
+    const wasTerminal = before !== undefined && TERMINAL_STATES.has(before);
+    if (!TERMINAL_STATES.has(state) || wasTerminal) {
+      this.reachedTerminal.delete(entryId);
+      return;
+    }
+    this.reachedTerminal.set(entryId, state);
+  }
+
+  /** The end of one snapshot: a pending baseline is now complete. */
+  snapshotComplete(): void {
+    this.baselinePending = false;
+  }
+
+  private parts(): string[] {
+    const parts: string[] = [];
+    if (this.turnsFinished > 0) {
+      const wake = this.wakeTurnsFinished > 0 ? ` (${this.wakeTurnsFinished} wake)` : '';
+      parts.push(`${this.turnsFinished} ${plural(this.turnsFinished, 'turn')} finished${wake}`);
+    }
+    if (this.needsInputCount > 0) parts.push(`${this.needsInputCount} needs input`);
+    const byState = { completed: 0, failed: 0, stopped: 0 };
+    for (const state of this.reachedTerminal.values()) {
+      if (state in byState) byState[state as keyof typeof byState] += 1;
+    }
+    for (const state of ['completed', 'failed', 'stopped'] as const) {
+      if (byState[state] > 0) parts.push(`${byState[state]} ${state}`);
+    }
+    if (this.errorCount > 0) {
+      parts.push(`${this.errorCount} ${plural(this.errorCount, 'error')}`);
+    }
+    return parts;
+  }
+
+  private reset(): void {
+    this.turnsFinished = 0;
+    this.wakeTurnsFinished = 0;
+    this.needsInputCount = 0;
+    this.errorCount = 0;
+    this.reachedTerminal.clear();
+  }
+}
+
+function plural(count: number, noun: string): string {
+  return count === 1 ? noun : `${noun}s`;
+}
+
+function formatElapsed(elapsedMs: number): string {
+  const totalMinutes = Math.floor(elapsedMs / MS_PER_MINUTE);
+  if (totalMinutes < 1) return '<1m';
+  const hours = Math.floor(totalMinutes / MINUTES_PER_HOUR);
+  const minutes = totalMinutes % MINUTES_PER_HOUR;
+  if (hours === 0) return `${minutes}m`;
+  return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`;
+}
+
+function bound(line: string): string {
+  return line.length <= RECAP_MAX_WIDTH ? line : `${line.slice(0, RECAP_MAX_WIDTH - 1)}…`;
+}

package/src/attention/time-units.ts

@@ -0,0 +1,6 @@
+/** The units the attention modules convert between; named so no arithmetic carries a bare literal. */
+export const MS_PER_SECOND = 1000;
+export const SECONDS_PER_MINUTE = 60;
+export const MINUTES_PER_HOUR = 60;
+export const MS_PER_MINUTE = MS_PER_SECOND * SECONDS_PER_MINUTE;
+export const SECONDS_PER_HOUR = SECONDS_PER_MINUTE * MINUTES_PER_HOUR;

package/src/attention-bell.ts

@@ -0,0 +1,79 @@
+/**
+ * CLI-2004 — the audible attention signal.
+ *
+ * Three triggers, all of them "the session now needs you and you cannot see that it does": a reply
+ * finished, a prompt or dialog wants an answer, and a tool that ran long enough that you had stopped
+ * watching has finished.
+ *
+ * The long-tool threshold is a NAMED CONSTANT rather than a copied literal. It comes from a single
+ * reference, so it is the kind of number that has to be tunable and attributable — not folded into
+ * an inline `> 5000`.
+ *
+ * Written outside Ink for the same reason as `terminal-marks.ts`: BEL is terminal framing, not
+ * rendered content.
+ */
+
+/** A tool that took longer than this rings on completion. Single-reference; tunable by design. */
+export const LONG_TOOL_BELL_MS = 5000;
+
+/** The bell byte. */
+export const BELL = '\x07';
+
+export interface IAttentionBellOptions {
+  /** Screen-reader mode. Off ⇒ nothing is ever written. */
+  enabled: boolean;
+  /** Injected sink; defaults to the process's own stdout. */
+  write?: (text: string) => void;
+  /** Injected clock so the threshold is testable without real time. */
+  now?: () => number;
+  /** Override the long-tool threshold. */
+  longToolBellMs?: number;
+}
+
+export interface IAttentionBell {
+  /** The assistant finished a reply. */
+  replyCompleted(): void;
+  /** A prompt or dialog mounted and is waiting for an answer. */
+  promptMounted(): void;
+  /** Record a tool's start so its duration can be judged at completion. */
+  toolStarted(toolId: string): void;
+  /** A tool finished — rings only if its recorded start is older than the threshold. */
+  toolCompleted(toolId: string): void;
+}
+
+/**
+ * Build the bell. A tool whose start was never recorded never rings: the signal is "the thing you
+ * stopped waiting for is done", and without a start there is no duration to judge, so silence is the
+ * correct answer rather than a guessed one.
+ */
+export function createAttentionBell(options: IAttentionBellOptions): IAttentionBell {
+  const write =
+    options.write ??
+    ((text: string): void => {
+      process.stdout.write(text);
+    });
+  const now = options.now ?? ((): number => Date.now());
+  const threshold = options.longToolBellMs ?? LONG_TOOL_BELL_MS;
+  const startedAt = new Map<string, number>();
+
+  const ring = (): void => {
+    if (!options.enabled) return;
+    write(BELL);
+  };
+
+  return {
+    replyCompleted: ring,
+    promptMounted: ring,
+    toolStarted(toolId: string): void {
+      if (!options.enabled) return;
+      startedAt.set(toolId, now());
+    },
+    toolCompleted(toolId: string): void {
+      const started = startedAt.get(toolId);
+      startedAt.delete(toolId);
+      if (started === undefined) return;
+      if (now() - started <= threshold) return;
+      ring();
+    },
+  };
+}

package/src/attributed-user-echo.ts

@@ -0,0 +1,30 @@
+import { createUserMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+
+/** The part of a session this needs: who is driving the turn now, if it can say. */
+export interface IActiveDriverSource {
+  getActiveDriverId?: () => string | null;
+}
+
+/**
+ * PEER-007 (issue #1915): the transcript echo of a user message, attributed to the ACTIVE turn's
+ * driver so a peer's message is labelled as theirs the moment it appears rather than reading as the
+ * operator's own for the whole turn. The id is the framework's DERIVED one (`peer:<session-id>`),
+ * never peer-supplied text.
+ *
+ * The lookup is guarded because attribution is an ADDITION to the message, never a precondition for
+ * it: a session that cannot say who drove the turn must still get the message on screen. Unguarded,
+ * a throw here loses the message entirely and the transcript shows that nothing happened.
+ */
+export function attributedUserEcho(content: string, session: IActiveDriverSource): IHistoryEntry {
+  let driverId: string | null = null;
+  try {
+    driverId = session.getActiveDriverId?.() ?? null;
+  } catch {
+    driverId = null;
+  }
+  return messageToHistoryEntry(
+    createUserMessage(content, driverId ? { metadata: { driverId } } : {}),
+  );
+}

package/src/background-task-row-format.ts

@@ -0,0 +1,99 @@
+import { formatCountdown } from './attention/countdown.js';
+import { formatExecutionWorkspaceEntryRow } from './execution-workspace-view-model.js';
+import { STATUS_SYMBOL, workspaceStatusKind } from './status-glyph.js';
+
+import type { TUiStatusKind } from './status-glyph.js';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+
+/**
+ * The row's leading connector. CLI-2004 adds the plain form: `├`/`└` draw a tree a sighted reader
+ * follows at a glance and a screen reader announces as two more characters per row.
+ */
+export const BACKGROUND_TASK_CONNECTORS = { branch: '├', last: '└', plain: '-' } as const;
+
+export type TBackgroundTaskConnector =
+  (typeof BACKGROUND_TASK_CONNECTORS)[keyof typeof BACKGROUND_TASK_CONNECTORS];
+
+export interface IBackgroundTaskRow {
+  connector: TBackgroundTaskConnector;
+  /** Shared status glyph (⟳ running, ✓ done, ✗ failed, …) — see status-glyph.ts. */
+  marker: string;
+  /** SCREEN-1992: the five-word state beside the glyph — the word a reader hears, not a colour. */
+  state: string;
+  /** SCREEN-2002: the status KIND; the component resolves its colour from the live theme. */
+  statusKind: TUiStatusKind;
+  label: string;
+  segments: string[];
+  preview?: string;
+  /** SCREEN-1992: the entry's headline when it says more than the preview already does. */
+  headline?: string;
+  /** SCREEN-1992: `in 59s` while a schedule sleeps — rendered against `options.now`. */
+  countdown?: string;
+  accessibleText: string;
+}
+
+export interface IBackgroundTaskRowOptions {
+  isLast?: boolean;
+  /** Screen-reader mode ⇒ the plain connector. */
+  screenReader?: boolean;
+  /** The clock the countdown is rendered against; the panel's tick advances it. */
+  now?: Date;
+}
+
+/** The headline earns its place only when the row does not already say it (preview or subtitle). */
+function resolveHeadline(
+  entry: IExecutionWorkspaceEntry,
+  preview: string | undefined,
+  subtitle: string | undefined,
+): string | undefined {
+  const text = entry.headline?.text;
+  if (text === undefined || text.length === 0 || text === preview) return undefined;
+  if (subtitle !== undefined && subtitle.includes(text)) return undefined;
+  return entry.headline?.kind === 'question' ? `? ${text}` : text;
+}
+
+function resolveConnector(options: IBackgroundTaskRowOptions): TBackgroundTaskConnector {
+  if (options.screenReader === true) return BACKGROUND_TASK_CONNECTORS.plain;
+  return options.isLast === false
+    ? BACKGROUND_TASK_CONNECTORS.branch
+    : BACKGROUND_TASK_CONNECTORS.last;
+}
+
+export function formatBackgroundTaskRow(
+  entry: IExecutionWorkspaceEntry,
+  options: IBackgroundTaskRowOptions = {},
+): IBackgroundTaskRow {
+  const row = formatExecutionWorkspaceEntryRow(entry);
+  // Symbol from the same (status, attention) classification that drives row.statusKind,
+  // so the marker's glyph and colour always agree (SCREEN-007).
+  const marker = STATUS_SYMBOL[workspaceStatusKind(entry.status, entry.attention)];
+  const segments = [row.statusLabel, row.subtitle].filter(
+    (segment): segment is string => typeof segment === 'string' && segment.length > 0,
+  );
+  const connector = resolveConnector(options);
+  const headline = resolveHeadline(entry, row.preview, row.subtitle);
+  const countdown =
+    entry.nextFireAt === undefined
+      ? undefined
+      : formatCountdown(entry.nextFireAt, options.now ?? new Date());
+  return {
+    connector,
+    marker,
+    state: entry.state,
+    statusKind: row.statusKind,
+    label: row.title,
+    segments,
+    preview: row.preview,
+    headline,
+    countdown,
+    accessibleText: [
+      `${connector} ${marker} ${entry.state} ${row.title}`,
+      ...segments,
+      headline,
+      row.preview,
+      countdown,
+    ]
+      .filter((part): part is string => typeof part === 'string' && part.length > 0)
+      .join(' · '),
+  };
+}

package/src/command-interaction.ts

@@ -0,0 +1,8 @@
+export type {
+  TOnMissingArgsAction,
+  ITuiPickerItem,
+  ITuiCommandInteraction,
+  ITuiPickerInteraction,
+  ITuiConfirmInteraction,
+  TAnyTuiCommandInteraction,
+} from '@robota-sdk/agent-interface-tui';

package/src/command-output-summary.ts

@@ -0,0 +1,129 @@
+import { sanitizeTerminalText } from './sanitize-terminal-text.js';
+
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+
+const MAX_PREVIEW_LINES = 4;
+const SUCCESS_EXIT_CODE = 0;
+const COMMAND_TOOL_NAMES = new Set(['Shell', 'Bash', 'BackgroundProcess']);
+
+export interface ICommandOutputInput {
+  toolName: string;
+  firstArg?: string;
+  isRunning?: boolean;
+  result?: string;
+  toolResultData?: string;
+}
+
+export interface ICommandOutputSummary {
+  status: 'success' | 'error';
+  statusLabel: string;
+  previewLines: string[];
+  omittedLineCount: number;
+  transcriptHint?: string;
+}
+
+export function formatCommandOutputSummary(
+  tool: ICommandOutputInput,
+): ICommandOutputSummary | undefined {
+  if (!COMMAND_TOOL_NAMES.has(tool.toolName) || !tool.toolResultData) return undefined;
+
+  const parsed = parseToolResultData(tool.toolResultData);
+  const exitCode = getNumberValue(parsed, 'exitCode');
+  const successValue = getBooleanValue(parsed, 'success');
+  const output = buildOutputText(tool.toolResultData, parsed);
+  const lines = trimTrailingBlankLines(splitOutputLines(output));
+  // SEC-019: these lines ARE the command's stdout and stderr — the most directly attacker-chosen
+  // text in the whole surface. Sanitized where the summary is BUILT rather than where it is
+  // rendered, because this function exists to produce display text and a second render site would
+  // otherwise have to remember. `statusLabel` and `transcriptHint` are built from numbers and need
+  // nothing.
+  const previewLines = lines.slice(0, MAX_PREVIEW_LINES).map(sanitizeTerminalText);
+  const omittedLineCount = Math.max(0, lines.length - previewLines.length);
+  const isFailed =
+    tool.result === 'error' ||
+    successValue === false ||
+    (exitCode !== undefined && exitCode !== SUCCESS_EXIT_CODE);
+
+  return {
+    status: isFailed ? 'error' : 'success',
+    statusLabel: formatStatusLabel(isFailed, exitCode),
+    previewLines,
+    omittedLineCount,
+    transcriptHint:
+      omittedLineCount > 0
+        ? `... +${omittedLineCount} lines (full output in session transcript)`
+        : undefined,
+  };
+}
+
+function parseToolResultData(value: string): TUniversalValue {
+  try {
+    return JSON.parse(value) as TUniversalValue;
+  } catch {
+    return value;
+  }
+}
+
+function buildOutputText(raw: string, parsed: TUniversalValue): string {
+  if (!isUniversalObject(parsed)) return raw;
+
+  const output = getStringValue(parsed, 'output');
+  if (output !== undefined) return output;
+
+  const stdout = getStringValue(parsed, 'stdout');
+  const stderr = getStringValue(parsed, 'stderr');
+  const error = getStringValue(parsed, 'error');
+  const lines: string[] = [];
+  if (stdout) lines.push(stdout);
+  if (stderr) lines.push(prefixLines(stderr, '[stderr] '));
+  if (!stdout && !stderr && error) lines.push(error);
+  return lines.join('\n');
+}
+
+function formatStatusLabel(isFailed: boolean, exitCode: number | undefined): string {
+  if (exitCode !== undefined && exitCode !== SUCCESS_EXIT_CODE) return `exit ${exitCode}`;
+  return isFailed ? 'error' : 'ok';
+}
+
+function splitOutputLines(output: string): string[] {
+  if (!output) return [];
+  return output.replace(/\r\n/g, '\n').split('\n');
+}
+
+function trimTrailingBlankLines(lines: string[]): string[] {
+  let end = lines.length;
+  while (end > 0 && lines[end - 1]!.trim().length === 0) {
+    end -= 1;
+  }
+  return lines.slice(0, end);
+}
+
+function prefixLines(value: string, prefix: string): string {
+  return splitOutputLines(value)
+    .map((line) => `${prefix}${line}`)
+    .join('\n');
+}
+
+function isUniversalObject(value: TUniversalValue): value is Record<string, TUniversalValue> {
+  return (
+    typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)
+  );
+}
+
+function getStringValue(source: TUniversalValue, key: string): string | undefined {
+  if (!isUniversalObject(source)) return undefined;
+  const value = source[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function getNumberValue(source: TUniversalValue, key: string): number | undefined {
+  if (!isUniversalObject(source)) return undefined;
+  const value = source[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function getBooleanValue(source: TUniversalValue, key: string): boolean | undefined {
+  if (!isUniversalObject(source)) return undefined;
+  const value = source[key];
+  return typeof value === 'boolean' ? value : undefined;
+}

package/src/create-default-tui-cli-adapter.ts

@@ -0,0 +1,45 @@
+import { findProviderDefinition } from '@robota-sdk/agent-core';
+import {
+  applyActiveModelChange,
+  createNodeHostSettingsStore,
+  readSettings,
+  resolveGitBranchFromNodeHost,
+} from '@robota-sdk/agent-framework';
+
+import type { ITuiCliAdapter } from './tui-cli-adapter.js';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type { CommandRegistry } from '@robota-sdk/agent-framework';
+import type { TSettingsSource } from '@robota-sdk/agent-framework';
+
+export interface IDefaultTuiCliAdapterOptions {
+  providerDefinitions: readonly IProviderDefinition[];
+  reloadPluginCommandSource: (registry: CommandRegistry) => void;
+  userSettingsPath: string;
+  settingsSources: readonly TSettingsSource[];
+  formatResumeCommand?: (sessionId: string) => string;
+}
+
+export function createDefaultTuiCliAdapter({
+  providerDefinitions,
+  reloadPluginCommandSource,
+  userSettingsPath,
+  settingsSources,
+  formatResumeCommand,
+}: IDefaultTuiCliAdapterOptions): ITuiCliAdapter {
+  return {
+    getUserSettingsPath: () => userSettingsPath,
+    readSettings: (path) => readSettings(path),
+    reloadPluginCommandSource: (registry) => {
+      reloadPluginCommandSource(registry);
+    },
+    applyActiveModelChange: (_cwd, modelId, options) => {
+      const userStore = createNodeHostSettingsStore('user', userSettingsPath);
+      applyActiveModelChange(settingsSources, [userStore], modelId, options);
+      return { applied: true };
+    },
+    getGitBranch: (cwd) => resolveGitBranchFromNodeHost(cwd),
+    getProviderDisplayName: (type) =>
+      findProviderDefinition(providerDefinitions, type)?.displayName ?? type,
+    ...(formatResumeCommand === undefined ? {} : { formatResumeCommand }),
+  };
+}