@robota-sdk/agent-transport 3.0.0-beta.64

package/src/tui/CjkTextInput.tsx

@@ -0,0 +1,204 @@
+/**
+ * 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 React, { useRef, useState } from 'react';
+import { Text, useInput, usePaste } from 'ink';
+import chalk from 'chalk';
+import {
+  applyCjkTextInput,
+  applyCjkTextPaste,
+  createCjkTextInputFlowState,
+  syncCjkTextInputFlowState,
+  type ICjkTextInputFlowState,
+} from './flows/cjk-text-input-flow.js';
+
+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;
+}
+
+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;
+  forceRender: React.Dispatch<React.SetStateAction<number>>;
+}
+
+export default function CjkTextInput({
+  value,
+  onChange,
+  onSubmit,
+  onPaste,
+  placeholder = '',
+  focus = true,
+  showCursor = true,
+  availableWidth,
+  cursorHint = null,
+  enableVerticalNavigation = true,
+}: IProps): React.ReactElement {
+  const stateRef = useRef<ICjkTextInputFlowState>(createCjkTextInputFlowState(value));
+  const [, forceRender] = useState(0);
+
+  // useCursor removed — see comment below about Terminal.app SIGSEGV
+
+  // 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,
+    forceRender,
+  });
+
+  // Do NOT call setCursorPosition() — passing y:0 moves the real terminal cursor
+  // to the top of the entire ink output (logo area), which causes Terminal.app to
+  // SIGSEGV when Korean IME queries attributedSubstringFromRange: at that position.
+  // Without setCursorPosition, the IME candidate window appears at bottom-left
+  // (same behavior as Claude Code, issue #19207), but Terminal.app does not crash.
+  //
+  // A correct fix would require knowing the total rendered height to pass the right
+  // y coordinate, which ink does not expose to components.
+
+  return (
+    <Text>
+      {renderWithCursor(
+        stateRef.current.value,
+        stateRef.current.cursor,
+        placeholder,
+        showCursor && focus,
+      )}
+    </Text>
+  );
+}
+
+function useCjkTextInputHandlers(options: IInputHandlerOptions): void {
+  usePaste(
+    (text) => {
+      applyCjkFlowSafely(options, () =>
+        applyCjkTextPaste(options.stateRef.current, text, createFlowOptions(options)),
+      );
+    },
+    { isActive: options.focus },
+  );
+
+  useInput(
+    (input, key) => {
+      applyCjkFlowSafely(options, () =>
+        applyCjkTextInput(options.stateRef.current, input, key, createFlowOptions(options)),
+      );
+    },
+    { isActive: options.focus },
+  );
+}
+
+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(
+      result.effect,
+      options.onChange,
+      options.onSubmit,
+      options.onPaste,
+      options.forceRender,
+    );
+  } catch {
+    // Korean IME in raw mode can produce unexpected byte sequences.
+  }
+}
+
+function applyCjkTextInputEffect(
+  effect: ReturnType<typeof applyCjkTextInput>['effect'],
+  onChange: (value: string) => void,
+  onSubmit: ((value: string) => void) | undefined,
+  onPaste: ((text: string, cursorPosition: number) => void) | undefined,
+  forceRender: React.Dispatch<React.SetStateAction<number>>,
+): void {
+  if (effect.type === 'change') {
+    onChange(effect.value);
+  } else if (effect.type === 'submit') {
+    onSubmit?.(effect.value);
+  } else if (effect.type === 'paste') {
+    onPaste?.(effect.text, effect.cursor);
+  } else if (effect.type === 'render') {
+    forceRender((n) => n + 1);
+  }
+}
+
+/** Render text with an inverse-style cursor at the correct position */
+function renderWithCursor(
+  value: string,
+  cursorOffset: number,
+  placeholder: string,
+  showCursor: boolean,
+): string {
+  if (!showCursor) {
+    return value.length > 0 ? value : placeholder ? chalk.gray(placeholder) : '';
+  }
+
+  if (value.length === 0) {
+    if (placeholder.length > 0) {
+      return chalk.inverse(placeholder[0]) + chalk.gray(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/tui/ConfirmPrompt.tsx

@@ -0,0 +1,69 @@
+/**
+ * Reusable confirmation prompt with arrow-key selection.
+ * Used by model change, permission prompts, and other yes/no confirmations.
+ */
+
+import React, { useState, useRef, useCallback } from 'react';
+import { Box, Text, useInput } from 'ink';
+import {
+  applyConfirmPromptInput,
+  getConfirmPromptInputAction,
+  type TConfirmPromptInputAction,
+} from './flows/confirm-prompt-flow.js';
+import { createSelectionFlowState, type ISelectionFlowState } from './flows/selection-flow.js';
+
+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 [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],
+  );
+
+  useInput((input, key) => {
+    const action = getConfirmPromptInputAction(input, key, options.length);
+    if (action !== undefined) {
+      applyAction(action);
+    }
+  });
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="yellow" paddingX={1}>
+      <Text color="yellow">{message}</Text>
+      <Box marginTop={1}>
+        {options.map((opt, i) => (
+          <Box key={opt} marginRight={2}>
+            <Text
+              color={i === state.selectedIndex ? 'cyan' : undefined}
+              bold={i === state.selectedIndex}
+            >
+              {i === state.selectedIndex ? '> ' : '  '}
+              {opt}
+            </Text>
+          </Box>
+        ))}
+      </Box>
+      <Text dimColor> arrow keys to select, Enter to confirm</Text>
+    </Box>
+  );
+}

package/src/tui/ExecutionWorkspaceDetailPane.tsx

@@ -0,0 +1,62 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceEntry,
+  TExecutionDetailRecordKind,
+} from '@robota-sdk/agent-framework';
+import {
+  formatExecutionDetailRecord,
+  formatExecutionWorkspaceEntryRow,
+} from './execution-workspace-view-model.js';
+
+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 row = formatExecutionWorkspaceEntryRow(entry, { selectedEntryId: entry.id });
+  const records = page?.records.slice(-MAX_VISIBLE_DETAIL_RECORDS) ?? [];
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text color="cyan" 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="red">{error}</Text> : null}
+      {!loading && !error && records.length === 0 ? <Text dimColor>No detail yet</Text> : null}
+      {!loading &&
+        !error &&
+        records.map((record) => (
+          <Text key={record.id} color={getDetailRecordColor(record.kind)}>
+            {formatExecutionDetailRecord(record)}
+          </Text>
+        ))}
+      {page?.nextCursor ? <Text dimColor>... more detail available</Text> : null}
+    </Box>
+  );
+}
+
+function getDetailRecordColor(kind: TExecutionDetailRecordKind): string | undefined {
+  if (kind === 'error') return 'red';
+  if (kind === 'result') return 'green';
+  if (kind === 'process_output') return 'white';
+  if (kind === 'group_summary') return 'cyan';
+  return undefined;
+}

package/src/tui/ExecutionWorkspaceSwitcher.tsx

@@ -0,0 +1,185 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import type {
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-framework';
+import {
+  applySelectionInput,
+  createSelectionFlowState,
+  getVerticalSelectionInputAction,
+  normalizeSelectionState,
+  type ISelectionFlowState,
+  type TSelectionInputAction,
+} from './flows/selection-flow.js';
+import { formatExecutionWorkspaceEntryRow } from './execution-workspace-view-model.js';
+
+const MAX_VISIBLE_WORKSPACE_ENTRIES = 8;
+
+interface IProps {
+  snapshot: IExecutionWorkspaceSnapshot | null;
+  selectedEntryId?: string;
+  onSelect: (entryId: string) => void;
+  onClose: () => void;
+}
+
+export default function ExecutionWorkspaceSwitcher({
+  snapshot,
+  selectedEntryId,
+  onSelect,
+  onClose,
+}: IProps): React.ReactElement {
+  const entries = [...(snapshot?.entries ?? [])];
+  const { normalized, visibleEntries, applyAction } = useWorkspaceSwitcherSelection({
+    entries,
+    selectedEntryId,
+    onSelect,
+    onClose,
+  });
+
+  useInput((_input, key) => {
+    const action = getVerticalSelectionInputAction(key);
+    if (action !== undefined) applyAction(action);
+  });
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="cyan" paddingX={1}>
+      <Text color="cyan" bold>
+        Execution workspace
+      </Text>
+      <Box flexDirection="column" marginTop={1}>
+        {visibleEntries.length === 0 ? (
+          <Text dimColor>No workspace entries</Text>
+        ) : (
+          visibleEntries.map((entry, index) => (
+            <ExecutionWorkspaceSwitcherRow
+              key={entry.id}
+              entry={entry}
+              isFocused={normalized.scrollOffset + index === normalized.selectedIndex}
+              selectedEntryId={selectedEntryId}
+            />
+          ))
+        )}
+      </Box>
+      <Text dimColor>Ctrl+B Close ↑↓ Navigate Enter Switch Esc Close</Text>
+    </Box>
+  );
+}
+
+interface IUseWorkspaceSwitcherSelectionInput {
+  entries: IExecutionWorkspaceEntry[];
+  selectedEntryId?: string;
+  onSelect: (entryId: string) => void;
+  onClose: () => void;
+}
+
+function useWorkspaceSwitcherSelection({
+  entries,
+  selectedEntryId,
+  onSelect,
+  onClose,
+}: IUseWorkspaceSwitcherSelectionInput): {
+  normalized: ISelectionFlowState;
+  visibleEntries: IExecutionWorkspaceEntry[];
+  applyAction: (action: TSelectionInputAction) => void;
+} {
+  const [state, setState] = useState<ISelectionFlowState>(() => createSelectionFlowState());
+  const stateRef = useRef(state);
+
+  useEffect(() => {
+    const selectedIndex = Math.max(
+      0,
+      entries.findIndex((entry) => entry.id === selectedEntryId),
+    );
+    const nextState = createNormalizedSelection({ selectedIndex, itemCount: entries.length });
+    stateRef.current = nextState;
+    setState(nextState);
+  }, [entries.length, selectedEntryId]);
+
+  const normalized = createNormalizedSelection({
+    selectedIndex: state.selectedIndex,
+    scrollOffset: state.scrollOffset,
+    itemCount: entries.length,
+  });
+  if (normalized !== state) stateRef.current = normalized;
+  return {
+    normalized,
+    visibleEntries: entries.slice(
+      normalized.scrollOffset,
+      normalized.scrollOffset + MAX_VISIBLE_WORKSPACE_ENTRIES,
+    ),
+    applyAction: createApplyAction({ entries, stateRef, setState, onSelect, onClose }),
+  };
+}
+
+function createApplyAction({
+  entries,
+  stateRef,
+  setState,
+  onSelect,
+  onClose,
+}: {
+  entries: IExecutionWorkspaceEntry[];
+  stateRef: React.MutableRefObject<ISelectionFlowState>;
+  setState: React.Dispatch<React.SetStateAction<ISelectionFlowState>>;
+  onSelect: (entryId: string) => void;
+  onClose: () => void;
+}): (action: TSelectionInputAction) => void {
+  return (action): void => {
+    const result = applySelectionInput(stateRef.current, action, {
+      itemCount: entries.length,
+      maxVisible: MAX_VISIBLE_WORKSPACE_ENTRIES,
+    });
+    const nextState =
+      result.effect.type === 'select' || result.effect.type === 'cancel'
+        ? { ...result.state, resolved: false }
+        : result.state;
+    stateRef.current = nextState;
+    setState(nextState);
+    if (result.effect.type === 'cancel') {
+      onClose();
+    } else if (result.effect.type === 'select') {
+      const entry = entries[result.effect.index];
+      if (entry) onSelect(entry.id);
+    }
+  };
+}
+
+function createNormalizedSelection(input: {
+  selectedIndex: number;
+  scrollOffset?: number;
+  itemCount: number;
+}): ISelectionFlowState {
+  return normalizeSelectionState(
+    {
+      selectedIndex: input.selectedIndex,
+      scrollOffset: input.scrollOffset ?? 0,
+      resolved: false,
+    },
+    { itemCount: input.itemCount, maxVisible: MAX_VISIBLE_WORKSPACE_ENTRIES },
+  );
+}
+
+function ExecutionWorkspaceSwitcherRow({
+  entry,
+  isFocused,
+  selectedEntryId,
+}: {
+  entry: IExecutionWorkspaceEntry;
+  isFocused: boolean;
+  selectedEntryId?: string;
+}): React.ReactElement {
+  const row = formatExecutionWorkspaceEntryRow(entry, { selectedEntryId });
+  return (
+    <Text>
+      <Text color={isFocused ? 'cyan' : undefined} bold={isFocused}>
+        {isFocused ? '> ' : '  '}
+      </Text>
+      <Text color={row.color}>{row.radio}</Text>
+      <Text color={isFocused ? 'cyan' : undefined} bold={isFocused}>{` ${row.title}`}</Text>
+      <Text dimColor>{` · ${row.statusLabel}`}</Text>
+      {row.subtitle ? <Text dimColor>{` · ${row.subtitle}`}</Text> : null}
+      {row.preview ? <Text dimColor>{` · ${row.preview}`}</Text> : null}
+    </Text>
+  );
+}

package/src/tui/InkTerminal.ts

@@ -0,0 +1,42 @@
+/**
+ * ITerminalOutput implementation for Ink TUI.
+ *
+ * Permission prompts are handled by setting React state via a callback,
+ * which triggers the PermissionPrompt component to render.
+ * All other output methods are no-ops since Ink manages rendering.
+ */
+
+import type { TToolArgs } from '@robota-sdk/agent-core';
+import type { ITerminalOutput, ISpinner } from '@robota-sdk/agent-core';
+
+export type TPermissionResolver = (toolName: string, toolArgs: TToolArgs) => Promise<boolean>;
+
+/**
+ * Create an ITerminalOutput adapter for the Ink UI.
+ *
+ * @param _onPermissionRequest - Called when a tool needs user approval.
+ *   The function should show a UI prompt and resolve with true (allow) or false (deny).
+ */
+export function createInkTerminal(_onPermissionRequest: TPermissionResolver): ITerminalOutput {
+  const noopSpinner: ISpinner = {
+    stop: () => {},
+    update: () => {},
+  };
+
+  return {
+    write: () => {},
+    writeLine: () => {},
+    writeMarkdown: () => {},
+    writeError: () => {},
+
+    prompt: (_question: string) => Promise.resolve(''),
+
+    select: async (options: string[], initialIndex = 0) => {
+      // Called by permission-prompt.ts via promptForApproval
+      // We intercept at checkPermission level instead, so this shouldn't be called
+      return initialIndex;
+    },
+
+    spinner: () => noopSpinner,
+  };
+}