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

package/src/CjkTextInput.tsx

@@ -0,0 +1,336 @@
+/**
+ * CJK-aware TextInput component for Ink.
+ *
+ * Replaces ink-text-input with proper wide character support:
+ * - Uses string-width for display width calculation
+ * - Cursor position based on character index (not display columns)
+ * - Renders CJK characters correctly (2 columns each)
+ * - Uses refs for value/cursor to avoid React state batching issues
+ *   (IME sends multiple keystrokes synchronously, state updates are async)
+ *
+ * Drop-in replacement: same props as ink-text-input.
+ */
+
+import chalk from 'chalk';
+import { Box, usePaste } from 'ink';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+
+import {
+  applyCjkTextInput,
+  applyCjkTextPaste,
+  createCjkTextInputFlowState,
+  syncCjkTextInputFlowState,
+  type ICjkTextInputFlowState,
+} from './flows/cjk-text-input-flow.js';
+import {
+  cancelDeferredSubmit,
+  createDeferSubmitState,
+  scheduleDeferredSubmit,
+  type IDeferSubmitState,
+} from './flows/defer-submit.js';
+import { useRealCursorPosition } from './hooks/useRealCursorPosition.js';
+import { useKeybindingActions } from './keybindings/keybindings-context.js';
+import { RenderedText } from './SafeText.js';
+import { sanitizeTerminalText } from './sanitize-terminal-text.js';
+import { useScreenReaderPacing } from './screen-reader-pacing-context.js';
+import { supportsImeCursorPositioning } from './terminal-capabilities.js';
+import { useTerminalCapabilityOverrides } from './terminal-capabilities-context.js';
+import { foreground, usePalette } from './theme/index.js';
+
+import type { IKeyInput, TKeybindingContext } from './keybindings/keybinding-registry.js';
+import type { DOMElement } from 'ink';
+
+interface IProps {
+  value: string;
+  onChange: (value: string) => void;
+  onSubmit?: (value: string) => void;
+  onPaste?: (text: string, cursorPosition: number) => void;
+  placeholder?: string;
+  focus?: boolean;
+  showCursor?: boolean;
+  /** Available width in columns for visual line wrapping navigation */
+  availableWidth?: number;
+  /** Cursor position hint for external value changes. null = end (default). */
+  cursorHint?: number | null;
+  /** When false, parent flows own up/down arrow behavior. */
+  enableVerticalNavigation?: boolean;
+  /**
+   * CLI-2004: called with the text a word/line delete removed. A reader announces what is LEFT on
+   * the line, so the removed text is the one thing it cannot tell you.
+   */
+  onDeletedText?: (deleted: string) => void;
+  /** Semantic key context; autocomplete consumes its own actions without invoking text actions. */
+  keybindingContext?: 'chat-input' | 'text-input' | 'autocomplete-menu';
+}
+
+interface IInputHandlerOptions {
+  stateRef: React.MutableRefObject<ICjkTextInputFlowState>;
+  onChange: (value: string) => void;
+  onSubmit?: (value: string) => void;
+  onPaste?: (text: string, cursorPosition: number) => void;
+  availableWidth?: number;
+  focus: boolean;
+  enableVerticalNavigation: boolean;
+  onDeletedText?: (deleted: string) => void;
+  forceRender: React.Dispatch<React.SetStateAction<number>>;
+  /** CLI-061: deferred-submit state (timer + submit guard). The input pipeline stays live during the window. */
+  deferState: IDeferSubmitState;
+  keybindingContext: 'chat-input' | 'text-input' | 'autocomplete-menu';
+}
+
+export default function CjkTextInput({
+  value,
+  onChange,
+  onSubmit,
+  onPaste,
+  placeholder = '',
+  focus = true,
+  showCursor = true,
+  availableWidth,
+  cursorHint = null,
+  enableVerticalNavigation = true,
+  onDeletedText,
+  keybindingContext = 'text-input',
+}: IProps): React.ReactElement {
+  const stateRef = useRef<ICjkTextInputFlowState>(createCjkTextInputFlowState(value));
+  const [, forceRender] = useState(0);
+  // CLI-061: deferred-submit state so a trailing IME character (a stdin event arriving just after Enter) is
+  // included in the submitted value. The timer is cancelled on unmount so no submit fires after teardown.
+  const deferRef = useRef<IDeferSubmitState>(createDeferSubmitState());
+  useEffect(() => () => cancelDeferredSubmit(deferRef.current), []);
+
+  // Sync ref when value changes from parent (e.g., setValue(''), tab completion, paste)
+  stateRef.current = syncCjkTextInputFlowState(stateRef.current, value, cursorHint);
+
+  useCjkTextInputHandlers({
+    stateRef,
+    onChange,
+    onSubmit,
+    onPaste,
+    availableWidth,
+    focus,
+    enableVerticalNavigation,
+    ...(onDeletedText !== undefined ? { onDeletedText } : {}),
+    forceRender,
+    deferState: deferRef.current,
+    keybindingContext,
+  });
+
+  // CLI-062: real terminal cursor positioning so the OS IME composition window appears AT the
+  // input position. The historical Terminal.app SIGSEGV came from a hardcoded `y: 0` (logo area);
+  // the hook only positions with a y measured from the live yoga layout and refuses the ink
+  // fullscreen geometry (invariants I1–I5 — see flows/real-cursor-flow.ts and the hook itself).
+  // SCREEN-2002: the placeholder's muted colour comes from the resolved theme, not a chalk literal.
+  const palette = usePalette();
+  const mutedPlaceholder = useMemo(() => foreground(palette.text.muted), [palette.text.muted]);
+  const boxRef = useRef<DOMElement | null>(null);
+  const terminalCapabilities = useTerminalCapabilityOverrides();
+  const { realCursorActive } = useRealCursorPosition({
+    boxRef,
+    enabled:
+      focus &&
+      showCursor &&
+      supportsImeCursorPositioning({ override: terminalCapabilities.imeCursorPositioning }),
+    value: stateRef.current.value,
+    cursor: stateRef.current.cursor,
+    ...(availableWidth !== undefined ? { availableWidth } : {}),
+  });
+
+  return (
+    <Box ref={boxRef}>
+      <RenderedText>
+        {renderWithCursor(
+          stateRef.current.value,
+          stateRef.current.cursor,
+          placeholder,
+          // I4: the drawn inverse cursor is suppressed ONLY while real positioning is active;
+          // any guard failure falls back to exactly today's rendering.
+          showCursor && focus && !realCursorActive,
+          mutedPlaceholder,
+        )}
+      </RenderedText>
+    </Box>
+  );
+}
+
+/**
+ * SCREEN-2670: which keys arm the echo exemption. Text insertion and deletion only — a keystroke
+ * whose commit repaints the composer. Submit and execute run through this same handler
+ * (`translateCjkInput` returns `key.return` for them) and their commit appends the user's prompt
+ * line to the transcript, which is exactly the content the park exists to pace; cursor moves and
+ * tab commit no text of the composer's own.
+ */
+function mutatesComposerText(
+  action: string | undefined,
+  translated: { input: string; key: IKeyInput },
+): boolean {
+  if (action === 'delete-backward' || action === 'delete-word' || action === 'delete-line')
+    return true;
+  return (
+    translated.key.return !== true &&
+    translated.key.ctrl !== true &&
+    translated.key.tab !== true &&
+    translated.input.length > 0
+  );
+}
+
+function useCjkTextInputHandlers(options: IInputHandlerOptions): void {
+  const pacing = useScreenReaderPacing();
+  usePaste(
+    (text) => {
+      pacing.armEchoRelease();
+      applyCjkFlowSafely(options, () =>
+        applyCjkTextPaste(options.stateRef.current, text, createFlowOptions(options)),
+      );
+    },
+    { isActive: options.focus },
+  );
+
+  useKeybindingActions(
+    options.keybindingContext,
+    (actions, input, key, consumed, resolvedContext) => {
+      const translated = translateCjkInput(resolvedContext, actions, input, key, consumed);
+      if (translated === undefined) return;
+      if (mutatesComposerText(actions[0], translated)) pacing.armEchoRelease();
+      applyCjkFlowSafely(options, () =>
+        applyCjkTextInput(
+          options.stateRef.current,
+          translated.input,
+          translated.key,
+          createFlowOptions(options),
+        ),
+      );
+    },
+    {
+      isActive: options.focus,
+      // #3125: the menu owns only its own keys; editing keys keep the chat input's bindings.
+      ...(options.keybindingContext === 'autocomplete-menu'
+        ? { fallbackContext: 'chat-input' as const }
+        : {}),
+    },
+  );
+}
+
+function translateCjkInput(
+  context: TKeybindingContext,
+  actions: readonly string[],
+  input: string,
+  key: IKeyInput,
+  consumed: boolean,
+): { input: string; key: IKeyInput } | undefined {
+  const action = actions[0];
+  if (action === 'submit' || action === 'execute') return { input: '', key: { return: true } };
+  if (context === 'autocomplete-menu' && consumed) return undefined;
+  if (action === 'cursor-left') return { input: '', key: { leftArrow: true } };
+  if (action === 'cursor-right') return { input: '', key: { rightArrow: true } };
+  if (action === 'cursor-up') return { input: '', key: { upArrow: true } };
+  if (action === 'cursor-down') return { input: '', key: { downArrow: true } };
+  if (action === 'delete-backward') return { input: '', key: { backspace: true } };
+  if (action === 'delete-word') return { input: 'w', key: { ctrl: true } };
+  if (action === 'delete-line') return { input: 'u', key: { ctrl: true } };
+  if (consumed) return undefined;
+  const rawText =
+    key.ctrl !== true &&
+    key.meta !== true &&
+    !key.return &&
+    !key.escape &&
+    !key.tab &&
+    !key.upArrow &&
+    !key.downArrow &&
+    !key.leftArrow &&
+    !key.rightArrow &&
+    !key.backspace &&
+    !key.delete;
+  return rawText || (key.ctrl === true && input === 'c') || key.tab ? { input, key } : undefined;
+}
+
+function createFlowOptions(options: IInputHandlerOptions): {
+  availableWidth?: number;
+  canPaste: boolean;
+  enableVerticalNavigation: boolean;
+} {
+  return {
+    availableWidth: options.availableWidth,
+    canPaste: options.onPaste !== undefined,
+    enableVerticalNavigation: options.enableVerticalNavigation,
+  };
+}
+
+function applyCjkFlowSafely(
+  options: IInputHandlerOptions,
+  run: () => ReturnType<typeof applyCjkTextInput>,
+): void {
+  try {
+    const result = run();
+    options.stateRef.current = result.state;
+    applyCjkTextInputEffect(options, result.effect);
+  } catch {
+    // allow-fallback: Korean IME in raw mode can produce unexpected byte sequences
+  }
+}
+
+function applyCjkTextInputEffect(
+  options: IInputHandlerOptions,
+  effect: ReturnType<typeof applyCjkTextInput>['effect'],
+): void {
+  if (effect.type === 'change') {
+    if (effect.deleted !== undefined) options.onDeletedText?.(effect.deleted);
+    options.onChange(effect.value);
+  } else if (effect.type === 'submit') {
+    // CLI-061: DEFER the submit and re-read the LIVE `stateRef.current.value` at fire time — never the stale
+    // `effect.value` captured at Enter. The input pipeline (this same handler) stays live during the window, so
+    // a trailing IME character's stdin event is applied to `stateRef` before the deferred read. The guard only
+    // blocks a SECOND submit — it must not gate the input pipeline (that would drop the trailing char).
+    const onSubmit = options.onSubmit;
+    if (onSubmit) {
+      scheduleDeferredSubmit(options.deferState, () => options.stateRef.current.value, onSubmit);
+    }
+  } else if (effect.type === 'paste') {
+    options.onPaste?.(effect.text, effect.cursor);
+  } else if (effect.type === 'render') {
+    options.forceRender((n) => n + 1);
+  }
+}
+
+/**
+ * Render text with an inverse-style cursor at the correct position.
+ *
+ * #2222: the input is sanitized BEFORE the cursor is drawn, and the result renders through
+ * `RenderedText` — the SGR here (inverse cursor, muted placeholder) is this component's own styling,
+ * and `SafeText` would strip it along with everything else, which is exactly how the drawn cursor
+ * disappeared (CLI-062 byte-identical rendering).
+ */
+function renderWithCursor(
+  rawValue: string,
+  cursorOffset: number,
+  rawPlaceholder: string,
+  showCursor: boolean,
+  mutedPlaceholder: (text: string) => string,
+): string {
+  const value = sanitizeTerminalText(rawValue);
+  const placeholder = sanitizeTerminalText(rawPlaceholder);
+  if (!showCursor) {
+    return value.length > 0 ? value : placeholder ? mutedPlaceholder(placeholder) : '';
+  }
+
+  if (value.length === 0) {
+    if (placeholder.length > 0) {
+      return chalk.inverse(placeholder[0]) + mutedPlaceholder(placeholder.slice(1));
+    }
+    return chalk.inverse(' ');
+  }
+
+  const chars = [...value];
+  let rendered = '';
+
+  for (let i = 0; i < chars.length; i++) {
+    const char = chars[i] ?? '';
+    rendered += i === cursorOffset ? chalk.inverse(char) : char;
+  }
+
+  if (cursorOffset >= chars.length) {
+    rendered += chalk.inverse(' ');
+  }
+
+  return rendered;
+}

package/src/ConfirmPrompt.tsx

@@ -0,0 +1,140 @@
+/**
+ * Reusable confirmation prompt with arrow-key selection.
+ * Used by model change, permission prompts, and other yes/no confirmations.
+ */
+
+import { Box, useInput } from 'ink';
+import React, { useState, useRef, useCallback } from 'react';
+
+import {
+  applyConfirmPromptInput,
+  applyTypedConfirmInput,
+  createTypedConfirmState,
+  type ITypedConfirmState,
+  type TConfirmPromptInputAction,
+} from './flows/confirm-prompt-flow.js';
+import { createSelectionFlowState, type ISelectionFlowState } from './flows/selection-flow.js';
+import {
+  KeyHintFooter,
+  SELECTION_INDICATOR,
+  SELECTION_INDICATOR_NONE,
+  type IKeyHint,
+} from './key-hint-footer.js';
+import { useKeybindingActions, useKeybindingHints } from './keybindings/keybindings-context.js';
+import { Text } from './SafeText.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { usePalette } from './theme/index.js';
+
+/** The typed-answer prompt. Authored here beside the reducer that accepts it. */
+export const CONFIRM_PROMPT_TYPED_LITERAL = 'Answer y or n and press Enter';
+
+/**
+ * Footer for the confirm prompt. Names the canonical keys for a horizontal row (←→; the reducer
+ * also accepts ↑↓ as aliases). Esc is deliberately suppressed by the flow (`escape: false` — the
+ * prompt must resolve explicitly), so per the affordance contract the footer omits it.
+ */
+export const CONFIRM_PROMPT_FOOTER_HINTS: readonly IKeyHint[] = [
+  { keys: '←→', label: 'Navigate' },
+  { keys: 'Enter', label: 'Confirm' },
+];
+
+interface IProps {
+  /** Message to display above the options */
+  message: string;
+  /** Options to select from (default: ['Yes', 'No']) */
+  options?: string[];
+  /** Callback with the selected index */
+  onSelect: (index: number) => void;
+}
+
+export default function ConfirmPrompt({
+  message,
+  options = ['Yes', 'No'],
+  onSelect,
+}: IProps): React.ReactElement {
+  const palette = usePalette();
+  const [state, setState] = useState<ISelectionFlowState>(() => createSelectionFlowState());
+  const stateRef = useRef(state);
+  const applyAction = useCallback(
+    (action: TConfirmPromptInputAction): void => {
+      const result = applyConfirmPromptInput(stateRef.current, action, options.length);
+      stateRef.current = result.state;
+      setState(result.state);
+      if (result.effect.type === 'select') {
+        onSelect(result.effect.index);
+      }
+    },
+    [onSelect, options.length],
+  );
+
+  const screenReader = useScreenReader();
+  const [typed, setTyped] = useState<ITypedConfirmState>(createTypedConfirmState);
+  const typedRef = useRef(typed);
+
+  useInput(
+    (input, key) => {
+      const result = applyTypedConfirmInput(typedRef.current, input, key);
+      typedRef.current = result.state;
+      setTyped(result.state);
+      if (result.effect.type === 'select') onSelect(result.effect.index);
+    },
+    { isActive: screenReader },
+  );
+
+  useKeybindingActions(
+    'confirm-prompt',
+    (actions) => {
+      for (const action of actions) {
+        if (action === 'choose-yes' && options.length === 2) {
+          applyAction({ type: 'shortcut', index: 0 });
+        } else if (action === 'choose-no' && options.length === 2) {
+          applyAction({ type: 'shortcut', index: 1 });
+        } else if (action === 'previous' || action === 'next' || action === 'confirm') {
+          applyAction(action === 'confirm' ? 'select' : action);
+        }
+      }
+    },
+    { isActive: !screenReader },
+  );
+  const footerHints = useKeybindingHints('confirm-prompt', [
+    [['previous', 'next'], 'Navigate'],
+    ['confirm', 'Confirm'],
+  ]);
+
+  if (screenReader) {
+    return (
+      <Box flexDirection="column">
+        <Text>{message}</Text>
+        <Text>
+          {CONFIRM_PROMPT_TYPED_LITERAL}
+          {typed.buffer.length > 0 ? ` ${typed.buffer}` : ''}
+        </Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={palette.border.attention}
+      paddingX={1}
+    >
+      <Text color={palette.text.warning}>{message}</Text>
+      <Box marginTop={1}>
+        {options.map((opt, i) => (
+          <Box key={opt} marginRight={2}>
+            <Text
+              color={i === state.selectedIndex ? palette.text.accent : undefined}
+              bold={i === state.selectedIndex}
+            >
+              {i === state.selectedIndex ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+              {opt}
+            </Text>
+          </Box>
+        ))}
+      </Box>
+      <KeyHintFooter hints={footerHints} />
+    </Box>
+  );
+}

package/src/ContextWarningBanner.tsx

@@ -0,0 +1,45 @@
+import { Box } from 'ink';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { usePalette } from './theme/index.js';
+
+interface IProps {
+  percentage: number;
+}
+
+const COMPACT_SUGGESTION_THRESHOLD = 70;
+const CRITICAL_THRESHOLD = 90;
+
+export function ContextWarningBanner({ percentage }: IProps): React.ReactElement | null {
+  const palette = usePalette();
+  const screenReader = useScreenReader();
+  if (percentage >= CRITICAL_THRESHOLD) {
+    return (
+      <Box
+        {...(screenReader
+          ? {}
+          : { borderStyle: 'single' as const, borderColor: palette.border.error })}
+        paddingX={1}
+      >
+        <Text color={palette.text.error} bold>
+          ⚠ Context at {Math.round(percentage)}% — window nearly full. Run /compact to summarize the
+          conversation.
+        </Text>
+      </Box>
+    );
+  }
+
+  if (percentage >= COMPACT_SUGGESTION_THRESHOLD) {
+    return (
+      <Box paddingX={1}>
+        <Text color={palette.text.warning}>
+          Context at {Math.round(percentage)}% — consider running /compact to free up space.
+        </Text>
+      </Box>
+    );
+  }
+
+  return null;
+}

package/src/ExecutionWorkspaceDetailPane.tsx

@@ -0,0 +1,85 @@
+import { Box } from 'ink';
+import React from 'react';
+
+import {
+  formatExecutionDetailRecord,
+  formatExecutionWorkspaceEntryRow,
+} from './execution-workspace-view-model.js';
+import { Text } from './SafeText.js';
+import { STATUS_SYMBOL, statusGlyphColor } from './status-glyph.js';
+import { usePalette } from './theme/index.js';
+
+import type { IThemeColors } from './theme/index.js';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceEntry,
+  TExecutionDetailRecordKind,
+} from '@robota-sdk/agent-interface-execution';
+
+const MAX_VISIBLE_DETAIL_RECORDS = 12;
+
+interface IProps {
+  entry: IExecutionWorkspaceEntry;
+  page: IExecutionDetailPage | null;
+  loading?: boolean;
+  error?: string;
+}
+
+export default function ExecutionWorkspaceDetailPane({
+  entry,
+  page,
+  loading,
+  error,
+}: IProps): React.ReactElement {
+  const palette = usePalette();
+  const row = formatExecutionWorkspaceEntryRow(entry, { selectedEntryId: entry.id });
+  const records = page?.records.slice(-MAX_VISIBLE_DETAIL_RECORDS) ?? [];
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text color={palette.text.accent} bold>
+        {`Viewing ${row.title}`}
+      </Text>
+      <Text dimColor>
+        {row.statusLabel}
+        {row.subtitle ? ` · ${row.subtitle}` : ''}
+        {row.preview ? ` · ${row.preview}` : ''}
+      </Text>
+      {loading ? <Text dimColor>Loading workspace detail...</Text> : null}
+      {error ? <Text color={palette.text.error}>{error}</Text> : null}
+      {!loading && !error && records.length === 0 ? <Text dimColor>No detail yet</Text> : null}
+      {!loading &&
+        !error &&
+        records.map((record) => {
+          const { symbol, color } = getDetailRecordGlyph(record.kind, palette);
+          return (
+            <Text key={record.id} color={color}>
+              {symbol ? `${symbol} ` : ''}
+              {formatExecutionDetailRecord(record)}
+            </Text>
+          );
+        })}
+      {page?.nextCursor ? <Text dimColor>... more detail available</Text> : null}
+    </Box>
+  );
+}
+
+/**
+ * Symbol + color per detail-record kind. A symbol always accompanies the color
+ * so status is legible without color (SCREEN-005 — no color-only encoding).
+ */
+function getDetailRecordGlyph(
+  kind: TExecutionDetailRecordKind,
+  palette: IThemeColors,
+): {
+  symbol: string;
+  color: string | undefined;
+} {
+  if (kind === 'error')
+    return { symbol: STATUS_SYMBOL.error, color: statusGlyphColor(palette, 'error') };
+  if (kind === 'result')
+    return { symbol: STATUS_SYMBOL.success, color: statusGlyphColor(palette, 'success') };
+  if (kind === 'group_summary') return { symbol: '▸', color: palette.text.accent };
+  if (kind === 'process_output') return { symbol: '·', color: palette.text.emphasis };
+  return { symbol: '', color: undefined };
+}