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

package/src/flows/input-area-flow.ts

@@ -0,0 +1,188 @@
+import { isSlashCommand, tokeniseSlashCommand } from '@robota-sdk/agent-framework';
+
+import type { IHistoryEntry, TUniversalValue } from '@robota-sdk/agent-core';
+import type { ICommand } from '@robota-sdk/agent-interface-command';
+
+export interface IAutocompleteInputKey {
+  upArrow?: boolean;
+  downArrow?: boolean;
+  escape?: boolean;
+  tab?: boolean;
+  backspace?: boolean;
+  delete?: boolean;
+}
+
+export type TAutocompletePopupAction = 'previous' | 'next' | 'close' | 'complete';
+export type TPendingPromptInputAction = 'cancelQueue';
+export type TPromptHistoryInputAction = 'previous' | 'next';
+
+export type TCommandSelectionResult =
+  { type: 'insert'; value: string; selectedIndex?: number } | { type: 'submit'; value: string };
+
+export interface IPasteLabelChange {
+  value: string;
+  cursorHint: number;
+  label: string;
+  lineCount: number;
+}
+
+export interface IPromptHistoryNavigationState {
+  selectedIndex: number | null;
+  draft: string;
+}
+
+export interface IPromptHistoryNavigationResult {
+  value: string;
+  cursorHint: number;
+  state: IPromptHistoryNavigationState;
+}
+
+export function getAutocompletePopupAction(
+  key: IAutocompleteInputKey,
+): TAutocompletePopupAction | undefined {
+  if (key.upArrow === true) return 'previous';
+  if (key.downArrow === true) return 'next';
+  if (key.escape === true) return 'close';
+  if (key.tab === true) return 'complete';
+  return undefined;
+}
+
+export function getPendingPromptInputAction(
+  key: IAutocompleteInputKey,
+): TPendingPromptInputAction | undefined {
+  if (key.backspace === true || key.delete === true) {
+    return 'cancelQueue';
+  }
+  return undefined;
+}
+
+export function getPromptHistoryInputAction(
+  key: IAutocompleteInputKey,
+): TPromptHistoryInputAction | undefined {
+  if (key.upArrow === true) return 'previous';
+  if (key.downArrow === true) return 'next';
+  return undefined;
+}
+
+export function createPromptHistoryNavigationState(): IPromptHistoryNavigationState {
+  return { selectedIndex: null, draft: '' };
+}
+
+export function navigatePromptHistory(
+  value: string,
+  history: readonly string[],
+  state: IPromptHistoryNavigationState,
+  action: TPromptHistoryInputAction,
+): IPromptHistoryNavigationResult {
+  if (history.length === 0) {
+    return { value, cursorHint: value.length, state };
+  }
+
+  if (action === 'previous') {
+    const selectedIndex =
+      state.selectedIndex === null ? history.length - 1 : Math.max(0, state.selectedIndex - 1);
+    const nextValue = history[selectedIndex] ?? value;
+    return {
+      value: nextValue,
+      cursorHint: nextValue.length,
+      state: { selectedIndex, draft: state.selectedIndex === null ? value : state.draft },
+    };
+  }
+
+  if (state.selectedIndex === null) {
+    return { value, cursorHint: value.length, state };
+  }
+
+  if (state.selectedIndex < history.length - 1) {
+    const selectedIndex = state.selectedIndex + 1;
+    const nextValue = history[selectedIndex] ?? value;
+    return {
+      value: nextValue,
+      cursorHint: nextValue.length,
+      state: { ...state, selectedIndex },
+    };
+  }
+
+  return {
+    value: state.draft,
+    cursorHint: state.draft.length,
+    state: createPromptHistoryNavigationState(),
+  };
+}
+
+export function appendPromptHistory(history: readonly string[], value: string): string[] {
+  const prompt = value.trim();
+  if (prompt.length === 0) return [...history];
+  if (history[history.length - 1] === prompt) return [...history];
+  return [...history, prompt];
+}
+
+export function extractPromptHistory(entries: readonly IHistoryEntry[]): string[] {
+  let prompts: string[] = [];
+  for (const entry of entries) {
+    if (entry.category !== 'chat' || entry.type !== 'user') continue;
+    const data = entry.data as Record<string, TUniversalValue> | undefined;
+    if (typeof data?.content !== 'string') continue;
+    prompts = appendPromptHistory(prompts, data.content);
+  }
+  return prompts;
+}
+
+export function moveAutocompleteSelection(
+  selectedIndex: number,
+  commandCount: number,
+  direction: 'previous' | 'next',
+): number {
+  if (commandCount === 0) return 0;
+  if (direction === 'previous') {
+    return selectedIndex > 0 ? selectedIndex - 1 : commandCount - 1;
+  }
+  return selectedIndex < commandCount - 1 ? selectedIndex + 1 : 0;
+}
+
+export function resolveTabCompletion(value: string, command: ICommand): TCommandSelectionResult {
+  // Subcommand mode: '/parent filter' — space present after command name
+  if (isSlashCommand(value) && value.slice(1).includes(' ')) {
+    const { name } = tokeniseSlashCommand(value);
+    return { type: 'insert', value: `/${name} ${command.name} ` };
+  }
+  if (command.subcommands && command.subcommands.length > 0) {
+    return { type: 'insert', value: `/${command.name} `, selectedIndex: 0 };
+  }
+  return { type: 'insert', value: `/${command.name} ` };
+}
+
+export function resolveEnterCommandSelection(
+  value: string,
+  command: ICommand,
+): TCommandSelectionResult {
+  // Subcommand mode: '/parent filter' — space present after command name
+  if (isSlashCommand(value) && value.slice(1).includes(' ')) {
+    const { name } = tokeniseSlashCommand(value);
+    return { type: 'submit', value: `/${name} ${command.name}` };
+  }
+  if (command.subcommands && command.subcommands.length > 0 && command.runsBare !== true) {
+    return { type: 'insert', value: `/${command.name} `, selectedIndex: 0 };
+  }
+  return { type: 'submit', value: `/${command.name}` };
+}
+
+export function createPasteLabelChange(
+  value: string,
+  cursorPosition: number,
+  pasteId: number,
+  text: string,
+): IPasteLabelChange {
+  const lineCount = text.split('\n').length;
+  const label = `[Pasted text #${pasteId} +${lineCount} lines]`;
+  return {
+    value: value.slice(0, cursorPosition) + label + value.slice(cursorPosition),
+    cursorHint: cursorPosition + label.length,
+    label,
+    lineCount,
+  };
+}
+
+export function shouldSubmitInput(text: string): boolean {
+  return text.trim().length > 0;
+}

package/src/flows/permission-prompt-flow.ts

@@ -0,0 +1,108 @@
+import {
+  applySelectionInput,
+  getDirectionalSelectionInputAction,
+  type ISelectionFlowState,
+  type ISelectionInputKey,
+  type TSelectionInputAction,
+} from './selection-flow.js';
+
+export const PERMISSION_PROMPT_OPTIONS = [
+  'Allow [y]',
+  'Allow always (this session) [s]',
+  'Allow always (this project) [p]',
+  'Deny [n]',
+] as const;
+
+/**
+ * Issue #2351: the "always" options name the SCOPE they grant — the consent pattern the enforcer
+ * remembers (`Bash(git *)`, `Read(/w/src/**)`, `WebFetch(https://h/**)`), not the whole tool.
+ */
+export function permissionPromptOptionsFor(
+  scope: string,
+  canPersistProjectPermission = true,
+): readonly string[] {
+  return [
+    PERMISSION_PROMPT_OPTIONS[0],
+    `Allow ${scope} always (this session) [s]`,
+    canPersistProjectPermission
+      ? `Allow ${scope} always (this project) [p]`
+      : 'Project-wide approval unavailable',
+    PERMISSION_PROMPT_OPTIONS[3],
+  ];
+}
+
+export type TPermissionPromptDecision = true | 'allow-session' | 'allow-project' | false;
+export type TPermissionPromptInputAction =
+  TSelectionInputAction | { type: 'shortcut'; index: number };
+
+export type TPermissionPromptEffect =
+  { type: 'none' } | { type: 'resolve'; decision: TPermissionPromptDecision };
+
+export function getPermissionPromptInputAction(
+  input: string,
+  key: ISelectionInputKey,
+): TPermissionPromptInputAction | undefined {
+  const action = getDirectionalSelectionInputAction({ ...key, escape: false });
+  if (action !== undefined) {
+    return action;
+  }
+  if (input === 'y' || input === '1') {
+    return { type: 'shortcut', index: 0 };
+  }
+  if (input === 's' || input === 'a' || input === '2') {
+    return { type: 'shortcut', index: 1 };
+  }
+  if (input === 'p' || input === '3') {
+    return { type: 'shortcut', index: 2 };
+  }
+  if (input === 'n' || input === 'd' || input === '4') {
+    return { type: 'shortcut', index: 3 };
+  }
+  return undefined;
+}
+
+export function applyPermissionPromptInput(
+  state: ISelectionFlowState,
+  action: TPermissionPromptInputAction,
+  canPersistProjectPermission = true,
+): { state: ISelectionFlowState; effect: TPermissionPromptEffect } {
+  if (state.resolved) {
+    return { state, effect: { type: 'none' } };
+  }
+  if (typeof action !== 'string') {
+    if (action.index === 2 && !canPersistProjectPermission) {
+      return { state, effect: { type: 'none' } };
+    }
+    return resolvePermissionIndex(state, action.index);
+  }
+  const result = applySelectionInput(state, action, {
+    itemCount: PERMISSION_PROMPT_OPTIONS.length,
+  });
+  if (result.effect.type !== 'select') {
+    return { state: result.state, effect: { type: 'none' } };
+  }
+  if (result.effect.index === 2 && !canPersistProjectPermission) {
+    return { state: result.state, effect: { type: 'none' } };
+  }
+  return {
+    state: result.state,
+    effect: { type: 'resolve', decision: getPermissionDecision(result.effect.index) },
+  };
+}
+
+function getPermissionDecision(index: number): TPermissionPromptDecision {
+  if (index === 0) return true;
+  if (index === 1) return 'allow-session';
+  if (index === 2) return 'allow-project';
+  return false;
+}
+
+function resolvePermissionIndex(
+  state: ISelectionFlowState,
+  index: number,
+): { state: ISelectionFlowState; effect: TPermissionPromptEffect } {
+  return {
+    state: { ...state, selectedIndex: index, resolved: true },
+    effect: { type: 'resolve', decision: getPermissionDecision(index) },
+  };
+}

package/src/flows/real-cursor-flow.ts

@@ -0,0 +1,83 @@
+/**
+ * CLI-062 — pure flow for real-terminal-cursor positioning during CJK IME composition.
+ *
+ * Maps the input box's absolute frame-space origin plus the live (value, cursor) to the exact
+ * screen cell the hardware cursor must occupy, and guards WHEN positioning is allowed at all.
+ * Contract: .design/investigations/2026-07-25-cli-062-ime-cursor-design.md.
+ *
+ * The wrap math reuses `displayOffset` — the same wrap-aware column accounting the input's
+ * vertical navigation already trusts — so the computed cell always matches where ink actually
+ * rendered the character under the cursor.
+ */
+
+import { displayOffset } from './cjk-text-input-flow.js';
+
+export interface ICursorCellInput {
+  /** Absolute frame-space column of the input box's first cell. */
+  absX: number;
+  /** Absolute frame-space row of the input box's first line. */
+  absY: number;
+  /** Current input value. */
+  value: string;
+  /** Cursor as a character index into the value (clamped to the value length). */
+  cursor: number;
+  /** Wrap width in columns; unset/non-positive means the value renders unwrapped. */
+  availableWidth?: number;
+}
+
+export interface ICursorCell {
+  x: number;
+  y: number;
+}
+
+export interface IRealCursorGuardInput {
+  /** Whether the input box has been measured in the CURRENT yoga layout. */
+  hasMeasured: boolean;
+  /** Target cursor row (absolute frame space). */
+  y: number;
+  /** Height of the live frame (ink-root yoga height). */
+  frameHeight: number;
+  /** Terminal viewport rows. */
+  viewportRows: number;
+  /** Terminal capability + focus gate (supportsImeCursorPositioning() && focused && showCursor). */
+  capability: boolean;
+}
+
+/** Compute the hardware-cursor cell for the current composition point. */
+export function computeCursorCell(input: ICursorCellInput): ICursorCell {
+  const chars = [...input.value];
+  const cursor = Math.min(Math.max(input.cursor, 0), chars.length);
+  const width =
+    input.availableWidth !== undefined && input.availableWidth > 0
+      ? input.availableWidth
+      : undefined;
+  const offset = displayOffset(chars, cursor, width ?? Number.MAX_SAFE_INTEGER);
+  if (width === undefined) {
+    return { x: input.absX + offset, y: input.absY };
+  }
+  return { x: input.absX + (offset % width), y: input.absY + Math.floor(offset / width) };
+}
+
+/**
+ * Crash-avoidance guard — the SIGSEGV invariants from the CLI-062 contract:
+ *
+ * - I1: never a GUESSED row — position only with a y measured from the current yoga layout
+ *   (`hasMeasured`); the historical hardcoded `y: 0` pointed the cursor at the logo area, where
+ *   Terminal.app's Korean IME `attributedSubstringFromRange:` null-derefs (Apple-side bug).
+ * - I2: never into an overflowing frame — when `frameHeight >= viewportRows` ink's bottom-anchor
+ *   assumption breaks (upstream defect, present in ink 7.0.5 AND 7.1.1: the cursor lands one row
+ *   high in the fullscreen path, and an overflowing frame clamps `cursorUp` at the screen top —
+ *   the original crash geometry). Same for a y outside `[0, frameHeight)`.
+ * - I5 lives in `supportsImeCursorPositioning()` and arrives here folded into `capability`.
+ *
+ * I3 (all movement rides ink's synchronized frame writes) and I4 (guard fail → no call → today's
+ * rendering) are properties of the hook that consumes this guard (useRealCursorPosition).
+ */
+export function shouldPositionRealCursor(input: IRealCursorGuardInput): boolean {
+  if (!input.capability) return false;
+  if (!input.hasMeasured) return false; // I1
+  if (input.viewportRows <= 0 || input.frameHeight <= 0) return false;
+  if (input.frameHeight >= input.viewportRows) return false; // I2 (fullscreen / overflow)
+  if (input.y < 0 || input.y >= input.frameHeight) return false; // I2 (out of frame)
+  return true;
+}

package/src/flows/selection-flow.ts

@@ -0,0 +1,205 @@
+export interface ISelectionFlowState {
+  selectedIndex: number;
+  scrollOffset: number;
+  resolved: boolean;
+}
+
+export interface ISelectionInputKey {
+  escape?: boolean;
+  return?: boolean;
+  upArrow?: boolean;
+  downArrow?: boolean;
+  leftArrow?: boolean;
+  rightArrow?: boolean;
+}
+
+export type TSelectionInputAction = 'cancel' | 'select' | 'previous' | 'next';
+
+export type TSelectionEffect =
+  | { type: 'none' }
+  | { type: 'cancel' }
+  | { type: 'select'; index: number }
+  // CLI-2004: a checklist toggles many times and then commits; only the numbered branch emits it.
+  | { type: 'confirm' };
+
+export interface ISelectionFlowOptions {
+  itemCount: number;
+  maxVisible?: number;
+  wrap?: boolean;
+  enabled?: boolean;
+}
+
+/** `initialIndex` seeds the highlight (a request's declared default); the caller clamps it. */
+export function createSelectionFlowState(initialIndex = 0): ISelectionFlowState {
+  return { selectedIndex: initialIndex, scrollOffset: 0, resolved: false };
+}
+
+export function getVerticalSelectionInputAction(
+  key: ISelectionInputKey,
+): TSelectionInputAction | undefined {
+  if (key.escape === true) return 'cancel';
+  if (key.upArrow === true) return 'previous';
+  if (key.downArrow === true) return 'next';
+  if (key.return === true) return 'select';
+  return undefined;
+}
+
+export function getDirectionalSelectionInputAction(
+  key: ISelectionInputKey,
+): TSelectionInputAction | undefined {
+  if (key.escape === true) return 'cancel';
+  if (key.leftArrow === true || key.upArrow === true) return 'previous';
+  if (key.rightArrow === true || key.downArrow === true) return 'next';
+  if (key.return === true) return 'select';
+  return undefined;
+}
+
+/**
+ * CLI-2004 — the typed-number branch of a selection.
+ *
+ * Screen-reader mode replaces arrow-key navigation with a numbered list and a typed answer, but the
+ * SELECTION itself must stay owned by this module: two reducers deciding what "selected" means is
+ * how a menu ends up resolving differently depending on how you drove it. `applyNumericSelection`
+ * accumulates digits and resolves on Enter; everything downstream is the same `TSelectionEffect`.
+ */
+export interface INumericSelectionState {
+  /** Digits typed so far, before Enter. */
+  buffer: string;
+  /** The last Enter was outside `1..itemCount` (or empty) — the caller re-prints the prompt. */
+  invalid: boolean;
+  resolved: boolean;
+}
+
+export interface INumericSelectionOptions {
+  itemCount: number;
+  /** Escape resolves as a cancel only when the menu offers one. */
+  cancellable?: boolean;
+  /**
+   * A checklist: a number TOGGLES its row and the menu stays open, so Enter on an empty buffer is
+   * the commit rather than an invalid entry. A single-choice menu resolves on the first number.
+   */
+  multi?: boolean;
+  /** A persistent view: selecting one row does not resolve the input. */
+  repeatable?: boolean;
+}
+
+export function createNumericSelectionState(): INumericSelectionState {
+  return { buffer: '', invalid: false, resolved: false };
+}
+
+/**
+ * Apply one keystroke to a numbered selection. Digits accumulate; Backspace edits; Enter resolves or
+ * marks the entry invalid; Escape cancels when the menu is cancellable. A non-digit character is
+ * ignored rather than treated as an answer — the invalid signal is reserved for a completed entry.
+ */
+export function applyNumericSelection(
+  state: INumericSelectionState,
+  input: string,
+  key: ISelectionInputKey & { backspace?: boolean; delete?: boolean },
+  options: INumericSelectionOptions,
+): { state: INumericSelectionState; effect: TSelectionEffect } {
+  if (state.resolved) return { state, effect: { type: 'none' } };
+  if (key.escape === true && options.cancellable === true) {
+    return { state: { ...state, resolved: true }, effect: { type: 'cancel' } };
+  }
+  if (key.backspace === true || key.delete === true) {
+    return { state: { ...state, buffer: state.buffer.slice(0, -1) }, effect: { type: 'none' } };
+  }
+  if (key.return === true) {
+    // A checklist commits on an empty Enter; a single-choice menu has nothing to commit, so the
+    // same keystroke there is an entry that named no row.
+    if (options.multi === true && state.buffer === '') {
+      return { state: { ...state, invalid: false, resolved: true }, effect: { type: 'confirm' } };
+    }
+    const index = Number.parseInt(state.buffer, 10) - 1;
+    if (!Number.isInteger(index) || index < 0 || index >= options.itemCount) {
+      return { state: { ...state, buffer: '', invalid: true }, effect: { type: 'none' } };
+    }
+    return {
+      // A toggle leaves the menu open — only a single-choice selection resolves it.
+      state: { ...state, buffer: '', invalid: false, resolved: options.multi !== true && options.repeatable !== true },
+      effect: { type: 'select', index },
+    };
+  }
+  if (/^[0-9]+$/.test(input)) {
+    return {
+      state: { ...state, buffer: state.buffer + input, invalid: false },
+      effect: { type: 'none' },
+    };
+  }
+  return { state, effect: { type: 'none' } };
+}
+
+export function applySelectionInput(
+  state: ISelectionFlowState,
+  action: TSelectionInputAction,
+  options: ISelectionFlowOptions,
+): { state: ISelectionFlowState; effect: TSelectionEffect } {
+  if (state.resolved) {
+    return { state, effect: { type: 'none' } };
+  }
+  if (action === 'cancel') {
+    return { state: { ...state, resolved: true }, effect: { type: 'cancel' } };
+  }
+  if (options.enabled === false || options.itemCount === 0) {
+    return { state, effect: { type: 'none' } };
+  }
+  if (action === 'select') {
+    const index = clampIndex(state.selectedIndex, options.itemCount);
+    return {
+      state: { ...state, selectedIndex: index, resolved: true },
+      effect: { type: 'select', index },
+    };
+  }
+  const selectedIndex = moveSelection(state.selectedIndex, action, options);
+  const scrollOffset = resolveScrollOffset(selectedIndex, state.scrollOffset, options);
+  return { state: { ...state, selectedIndex, scrollOffset }, effect: { type: 'none' } };
+}
+
+export function normalizeSelectionState(
+  state: ISelectionFlowState,
+  options: ISelectionFlowOptions,
+): ISelectionFlowState {
+  if (options.itemCount === 0) {
+    return { ...state, selectedIndex: 0, scrollOffset: 0 };
+  }
+  const selectedIndex = clampIndex(state.selectedIndex, options.itemCount);
+  const scrollOffset = resolveScrollOffset(selectedIndex, state.scrollOffset, options);
+  if (selectedIndex === state.selectedIndex && scrollOffset === state.scrollOffset) {
+    return state;
+  }
+  return {
+    ...state,
+    selectedIndex,
+    scrollOffset,
+  };
+}
+
+function moveSelection(
+  selectedIndex: number,
+  action: TSelectionInputAction,
+  options: ISelectionFlowOptions,
+): number {
+  if (action === 'previous') {
+    if (options.wrap === true && selectedIndex === 0) return options.itemCount - 1;
+    return Math.max(0, selectedIndex - 1);
+  }
+  if (options.wrap === true && selectedIndex === options.itemCount - 1) return 0;
+  return Math.min(options.itemCount - 1, selectedIndex + 1);
+}
+
+function resolveScrollOffset(
+  selectedIndex: number,
+  scrollOffset: number,
+  options: ISelectionFlowOptions,
+): number {
+  const maxVisible = options.maxVisible ?? options.itemCount;
+  if (maxVisible <= 0) return 0;
+  if (selectedIndex < scrollOffset) return selectedIndex;
+  if (selectedIndex >= scrollOffset + maxVisible) return selectedIndex - maxVisible + 1;
+  return Math.max(0, scrollOffset);
+}
+
+function clampIndex(index: number, itemCount: number): number {
+  return Math.min(Math.max(index, 0), itemCount - 1);
+}

package/src/flows/session-init-poller.ts

@@ -0,0 +1,76 @@
+/**
+ * Bounded polling helper for asynchronous session initialization.
+ *
+ * Distinguishes benign "not yet initialized" errors (retried until a timeout)
+ * from real failures (surfaced immediately), so the TUI can show an error
+ * instead of spinning forever.
+ */
+
+export type TSessionInitFailure =
+  { kind: 'timeout'; lastError: Error | undefined } | { kind: 'error'; error: Error };
+
+export interface ISessionInitPollerOptions {
+  /** Throws while the session is not ready; returns normally when ready. */
+  check: () => void;
+  intervalMs: number;
+  timeoutMs: number;
+  /** Returns true when an error means "keep polling". Defaults to /not initialized/i. */
+  isBenignError?: (error: Error) => boolean;
+  onReady: () => void;
+  onFailure: (failure: TSessionInitFailure) => void;
+}
+
+export interface ISessionInitPoller {
+  start(): void;
+  stop(): void;
+}
+
+function defaultIsBenignError(error: Error): boolean {
+  return /not initialized/i.test(error.message);
+}
+
+export function createSessionInitPoller(options: ISessionInitPollerOptions): ISessionInitPoller {
+  const isBenign = options.isBenignError ?? defaultIsBenignError;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let elapsedMs = 0;
+  let lastBenignError: Error | undefined;
+
+  function stop(): void {
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+
+  function tick(): void {
+    elapsedMs += options.intervalMs;
+    try {
+      options.check();
+    } catch (raw) {
+      // allow-fallback: poller's purpose is to classify and route this error, never to swallow it
+      const error = raw instanceof Error ? raw : new Error(String(raw));
+      if (!isBenign(error)) {
+        stop();
+        options.onFailure({ kind: 'error', error });
+        return;
+      }
+      lastBenignError = error;
+      if (elapsedMs >= options.timeoutMs) {
+        stop();
+        options.onFailure({ kind: 'timeout', lastError: lastBenignError });
+      }
+      return;
+    }
+    stop();
+    options.onReady();
+  }
+
+  return {
+    start(): void {
+      if (timer !== null) return;
+      elapsedMs = 0;
+      timer = setInterval(tick, options.intervalMs);
+    },
+    stop,
+  };
+}