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

package/src/ListPicker.tsx

@@ -0,0 +1,158 @@
+/**
+ * Generic list picker with arrow-key navigation and viewport scrolling.
+ * Renders items via a user-supplied renderItem function.
+ * Shows a limited number of items at a time; scrolls as the cursor moves.
+ */
+
+import { Box } from 'ink';
+import React, { useState, useRef, useCallback } from 'react';
+
+import {
+  applySelectionInput,
+  createSelectionFlowState,
+  normalizeSelectionState,
+  type ISelectionFlowState,
+  type TSelectionInputAction,
+} from './flows/selection-flow.js';
+import { useNumberedSelection } from './hooks/useNumberedSelection.js';
+import { KeyHintFooter, type IKeyHint } from './key-hint-footer.js';
+import { useKeybindingActions, useKeybindingHints } from './keybindings/keybindings-context.js';
+import { formatNumberedSelectionPrompt, numberedRowPrefix } from './numbered-list.js';
+import { Text } from './SafeText.js';
+import { useScreenReader } from './screen-reader-context.js';
+
+/** Default number of visible items */
+const DEFAULT_MAX_VISIBLE = 3;
+
+export interface IListPickerProps<T> {
+  /** Items to display in the list */
+  items: T[];
+  /** Render function for each item — receives the item and whether it is currently selected */
+  renderItem: (item: T, isSelected: boolean) => React.ReactElement;
+  /** Called when the user presses Enter on the highlighted item */
+  onSelect: (item: T) => void;
+  /** Called when the user presses Escape */
+  onCancel: () => void;
+  /** Maximum number of items visible at once (default: 10) */
+  maxVisible?: number;
+  /** Key-hint footer shown below the list (default: navigate/select/cancel; `[]` suppresses it) */
+  footerHints?: readonly IKeyHint[];
+  /** The item highlighted first (default: the first). Out-of-range values fall back to the first. */
+  initialIndex?: number;
+}
+
+/** Default affordance footer — Enter always selects and Esc always cancels. */
+export const LIST_PICKER_DEFAULT_FOOTER_HINTS: readonly IKeyHint[] = [
+  { keys: '↑↓', label: 'Navigate' },
+  { keys: 'Enter', label: 'Select' },
+  { keys: 'Esc', label: 'Cancel' },
+];
+
+export default function ListPicker<T>({
+  items,
+  renderItem,
+  onSelect,
+  onCancel,
+  maxVisible = DEFAULT_MAX_VISIBLE,
+  footerHints = LIST_PICKER_DEFAULT_FOOTER_HINTS,
+  initialIndex = 0,
+}: IListPickerProps<T>): React.ReactElement {
+  const [state, setState] = useState<ISelectionFlowState>(() => {
+    const index = initialIndex >= 0 && initialIndex < items.length ? initialIndex : 0;
+    const seeded = createSelectionFlowState(index);
+    // Keep the seeded row on screen when it sits past the first window.
+    return { ...seeded, scrollOffset: Math.max(0, index - maxVisible + 1) };
+  });
+  const stateRef = useRef(state);
+  const applyAction = useCallback(
+    (action: TSelectionInputAction): void => {
+      const result = applySelectionInput(stateRef.current, action, {
+        itemCount: items.length,
+        maxVisible,
+      });
+      stateRef.current = result.state;
+      setState(result.state);
+      if (result.effect.type === 'cancel') {
+        onCancel();
+      } else if (result.effect.type === 'select') {
+        const item = items[result.effect.index];
+        if (item !== undefined) {
+          onSelect(item);
+        }
+      }
+    },
+    [items, maxVisible, onCancel, onSelect],
+  );
+
+  // CLI-2004: the viewport is a sighted affordance — `↑ N more above` tells a reader nothing about
+  // where it is. The mode lists every item with its number and asks for one.
+  const screenReader = useScreenReader();
+  const numbered = useNumberedSelection({
+    enabled: screenReader && items.length > 0,
+    itemCount: items.length,
+    cancellable: true,
+    onSelect: (index) => {
+      const item = items[index];
+      if (item !== undefined) onSelect(item);
+    },
+    onCancel,
+  });
+
+  useKeybindingActions('list-picker', (actions) => actions.forEach(applyAction), {
+    isActive: !screenReader,
+  });
+  const effectiveFooterHints = useKeybindingHints('list-picker', [
+    [['previous', 'next'], 'Navigate'],
+    ['select', 'Select'],
+    ['cancel', 'Cancel'],
+  ]);
+
+  if (items.length === 0) {
+    return <Box />;
+  }
+
+  if (screenReader) {
+    const prompt = formatNumberedSelectionPrompt(items.length, true);
+    return (
+      <Box flexDirection="column">
+        {items.map((item, index) => (
+          <Box key={index}>
+            <Text>{numberedRowPrefix(index)}</Text>
+            {renderItem(item, false)}
+          </Box>
+        ))}
+        <Text>
+          {prompt}
+          {numbered.buffer.length > 0 ? ` ${numbered.buffer}` : ''}
+        </Text>
+        {numbered.invalid && <Text>{prompt}</Text>}
+      </Box>
+    );
+  }
+
+  const normalizedState = normalizeSelectionState(state, { itemCount: items.length, maxVisible });
+  if (normalizedState !== state) {
+    stateRef.current = normalizedState;
+  }
+  const { selectedIndex, scrollOffset } = normalizedState;
+  const visibleItems = items.slice(scrollOffset, scrollOffset + maxVisible);
+  const hasMore = scrollOffset + maxVisible < items.length;
+  const hasLess = scrollOffset > 0;
+
+  return (
+    <Box flexDirection="column">
+      {hasLess && <Text dimColor> ↑ {scrollOffset} more above</Text>}
+      {visibleItems.map((item, index) => (
+        <Box key={scrollOffset + index} marginBottom={1}>
+          {renderItem(item, scrollOffset + index === selectedIndex)}
+        </Box>
+      ))}
+      {hasMore && <Text dimColor> ↓ {items.length - scrollOffset - maxVisible} more below</Text>}
+      <KeyHintFooter
+        hints={
+          footerHints === LIST_PICKER_DEFAULT_FOOTER_HINTS ? effectiveFooterHints : footerHints
+        }
+      />
+    </Box>
+  );
+}

package/src/MenuSelect.tsx

@@ -0,0 +1,159 @@
+import { Box } from 'ink';
+import React, { useState, useCallback, useRef } from 'react';
+
+import {
+  applySelectionInput,
+  createSelectionFlowState,
+  normalizeSelectionState,
+  type ISelectionFlowState,
+  type TSelectionInputAction,
+} from './flows/selection-flow.js';
+import { useNumberedSelection } from './hooks/useNumberedSelection.js';
+import {
+  KeyHintFooter,
+  SELECTION_INDICATOR,
+  SELECTION_INDICATOR_NONE,
+  type IKeyHint,
+} from './key-hint-footer.js';
+import { useKeybindingActions, useKeybindingHints } from './keybindings/keybindings-context.js';
+import { NumberedList } from './numbered-list.js';
+import { Text } from './SafeText.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { usePalette } from './theme/index.js';
+
+/** Footer for the interactive menu state. */
+export const MENU_SELECT_FOOTER_HINTS: readonly IKeyHint[] = [
+  { keys: '↑↓', label: 'Navigate' },
+  { keys: 'Enter', label: 'Select' },
+  { keys: 'Esc', label: 'Back' },
+];
+
+/** Footer for the error state — Esc (cancel) is the only active key. */
+export const MENU_SELECT_ERROR_FOOTER_HINTS: readonly IKeyHint[] = [{ keys: 'Esc', label: 'Back' }];
+
+export interface IMenuSelectItem {
+  label: string;
+  value: string;
+  hint?: string;
+}
+
+interface IProps {
+  title: string;
+  items: IMenuSelectItem[];
+  onSelect: (value: string) => void;
+  onBack: () => void;
+  loading?: boolean;
+  error?: string;
+}
+
+export default function MenuSelect({
+  title,
+  items,
+  onSelect,
+  onBack,
+  loading,
+  error,
+}: IProps): React.ReactElement {
+  const palette = usePalette();
+  const [state, setState] = useState<ISelectionFlowState>(() => createSelectionFlowState());
+  const stateRef = useRef(state);
+  const isEnabled = !loading && !error;
+  const screenReader = useScreenReader();
+  const numbered = useNumberedSelection({
+    enabled: screenReader && isEnabled,
+    itemCount: items.length,
+    cancellable: true,
+    onSelect: (index) => {
+      const item = items[index];
+      if (item !== undefined) onSelect(item.value);
+    },
+    onCancel: onBack,
+  });
+  const applyAction = useCallback(
+    (action: TSelectionInputAction): void => {
+      const result = applySelectionInput(stateRef.current, action, {
+        itemCount: items.length,
+        enabled: isEnabled,
+      });
+      stateRef.current = result.state;
+      setState(result.state);
+      if (result.effect.type === 'cancel') {
+        onBack();
+      } else if (result.effect.type === 'select') {
+        const item = items[result.effect.index];
+        if (item !== undefined) {
+          onSelect(item.value);
+        }
+      }
+    },
+    [isEnabled, items, onBack, onSelect],
+  );
+
+  useKeybindingActions(
+    'menu-select',
+    (actions) => actions.forEach((action) => applyAction(action === 'back' ? 'cancel' : action)),
+    { isActive: !screenReader },
+  );
+  const menuHints = useKeybindingHints('menu-select', [
+    [['previous', 'next'], 'Navigate'],
+    ['select', 'Select'],
+    ['back', 'Back'],
+  ]);
+  const errorHints = useKeybindingHints('menu-select', [['back', 'Back']]);
+
+  const normalizedState = normalizeSelectionState(state, { itemCount: items.length });
+  if (normalizedState !== state) {
+    stateRef.current = normalizedState;
+  }
+  const selected = normalizedState.selectedIndex;
+
+  if (screenReader) {
+    return (
+      <NumberedList
+        title={title}
+        options={loading ? [] : error ? [] : items.map((item) => item.label)}
+        description={loading ? 'Loading...' : error}
+        cancellable
+        buffer={numbered.buffer}
+        invalid={numbered.invalid}
+      />
+    );
+  }
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={palette.border.attention}
+      paddingX={1}
+    >
+      <Text color={palette.text.warning} bold>
+        {title}
+      </Text>
+      {loading && (
+        <Box marginTop={1}>
+          <Text dimColor>Loading...</Text>
+        </Box>
+      )}
+      {error && (
+        <Box marginTop={1}>
+          <Text color={palette.text.error}>{error}</Text>
+        </Box>
+      )}
+      {!loading && !error && (
+        <Box flexDirection="column" marginTop={1}>
+          {items.map((item, i) => (
+            <Box key={item.value}>
+              <Text color={i === selected ? palette.text.accent : undefined} bold={i === selected}>
+                {i === selected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+                {item.label}
+              </Text>
+              {item.hint && <Text dimColor> {item.hint}</Text>}
+            </Box>
+          ))}
+        </Box>
+      )}
+      <KeyHintFooter hints={loading ? [] : error ? errorHints : menuHints} />
+    </Box>
+  );
+}

package/src/MessageList.tsx

@@ -0,0 +1,308 @@
+import { isToolMessage, isAssistantMessage } from '@robota-sdk/agent-core';
+import { Box } from 'ink';
+import React from 'react';
+
+import { formatCommandOutputSummary } from './command-output-summary.js';
+import { useRenderMarkdown } from './hooks/useRenderMarkdown.js';
+import { humanizeToolName } from './humanize-tool-name.js';
+import { useModelCommandToolPrefix } from './product-display-name-context.js';
+import { RoleLabel } from './RoleLabel.js';
+import { RenderedText, Text } from './SafeText.js';
+import { sanitizeTerminalText } from './sanitize-terminal-text.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { SCREEN_READER_LABELS, type TScreenReaderLabelKind } from './screen-reader-labels.js';
+import { statusGlyphColor } from './status-glyph.js';
+import { usePalette } from './theme/index.js';
+import { getToolSummaryLabel, toolSummaryStatusKind } from './tool-summary-status.js';
+import ToolCommandOutput from './ToolCommandOutput.js';
+import ToolDiffBlock from './ToolDiffBlock.js';
+import UsageSummaryEntry from './UsageSummaryEntry.js';
+
+import type { TToolSummaryItem } from './tool-summary-status.js';
+import type { IToolCallSummary } from './utils/tool-call-extractor.js';
+import type { IHistoryEntry, TUniversalMessage, TUniversalValue } from '@robota-sdk/agent-core';
+
+interface IProps {
+  history: IHistoryEntry[];
+}
+
+/**
+ * CLI-2004: one transcript label. In screen-reader mode it speaks the shared vocabulary and drops
+ * the colour — the searchable word IS the cue there — and outside it renders exactly as before.
+ */
+function EntryLabel({
+  kind,
+  text,
+  color,
+}: {
+  kind: TScreenReaderLabelKind;
+  text: string;
+  color: string;
+}): React.ReactElement {
+  if (useScreenReader()) return <Text>{SCREEN_READER_LABELS[kind]} </Text>;
+  return (
+    <Text color={color} bold>
+      {text}
+    </Text>
+  );
+}
+
+function ToolMessage({ message }: { message: TUniversalMessage }): React.ReactElement {
+  const palette = usePalette();
+  const modelCommandToolPrefix = useModelCommandToolPrefix();
+  if (!isToolMessage(message)) {
+    return <></>;
+  }
+  const toolName = message.name;
+  const content = message.content;
+
+  // Try to parse structured tool summaries (with diff info)
+  let summaries: IToolCallSummary[] | null = null;
+  try {
+    const parsed = JSON.parse(content) as IToolCallSummary[];
+    if (Array.isArray(parsed) && parsed.length > 0 && typeof parsed[0].line === 'string') {
+      summaries = parsed as IToolCallSummary[];
+    }
+  } catch {
+    // Not JSON — fall back to plain text lines
+  }
+
+  if (summaries) {
+    return (
+      <Box flexDirection="column" marginBottom={1}>
+        <Box>
+          <EntryLabel kind="tool" text="Tool: " color={palette.text.emphasis} />
+          {toolName && (
+            <Text color={palette.text.emphasis} dimColor>
+              [{humanizeToolName(toolName, modelCommandToolPrefix)}]
+            </Text>
+          )}
+        </Box>
+        <Text> </Text>
+        {summaries.map((s, i) => (
+          <Box key={i} flexDirection="column">
+            <Text color={palette.text.success}>
+              {'  '}
+              {'✓'} {sanitizeTerminalText(s.line)}
+            </Text>
+            {s.diffLines && s.diffLines.length > 0 && (
+              <ToolDiffBlock file={s.diffFile} lines={s.diffLines} />
+            )}
+          </Box>
+        ))}
+      </Box>
+    );
+  }
+
+  // Fallback: plain text lines
+  const lines = content.split('\n').filter((l) => l.trim());
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <EntryLabel kind="tool" text="Tool: " color={palette.text.emphasis} />
+        {toolName && (
+          <Text color={palette.text.emphasis} dimColor>
+            [{sanitizeTerminalText(toolName)}]
+          </Text>
+        )}
+      </Box>
+      <Text> </Text>
+      {lines.map((line, i) => (
+        <Text key={i} color={palette.text.success}>
+          {'  '}
+          {'✓'} {sanitizeTerminalText(line)}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+/** ERR-001 G2: a failed turn renders as a styled error block, not a plain system note. */
+function ErrorEntryBlock({ message }: { message: TUniversalMessage }): React.ReactElement {
+  const palette = usePalette();
+  // SEC-019: an error message is untrusted text — it carries provider responses, tool stderr and
+  // file contents — and it reaches `<Text>` without going through the markdown renderer, so it does
+  // not inherit that path's sanitization.
+  const content = sanitizeTerminalText((message.content ?? '').replace(/^Error:\s*/, ''));
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <EntryLabel kind="error" text="✖ Error: " color={palette.text.error} />
+      </Box>
+      <Box marginLeft={2} flexDirection="column">
+        <Text color={palette.text.error} wrap="wrap">
+          {content}
+        </Text>
+        <Text dimColor wrap="wrap">
+          The session is still alive — type your next prompt when ready.
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+const MessageItem = React.memo(function MessageItem({
+  message,
+}: {
+  message: TUniversalMessage;
+}): React.ReactElement {
+  // Every hook this component uses runs BEFORE the early returns: a message whose role or kind
+  // changes in place would otherwise render a different NUMBER of hooks and React would throw.
+  const renderMarkdown = useRenderMarkdown();
+
+  if (isToolMessage(message)) {
+    return <ToolMessage message={message} />;
+  }
+
+  if (message.role === 'system' && message.metadata?.kind === 'error') {
+    return <ErrorEntryBlock message={message} />;
+  }
+
+  const content = message.content ?? '';
+  const isInterrupted = message.state === 'interrupted';
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <RoleLabel
+          role={message.role}
+          {...(typeof message.metadata?.driverId === 'string'
+            ? { driverId: message.metadata.driverId }
+            : {})}
+        />
+      </Box>
+      <Text> </Text>
+      <Box marginLeft={2}>
+        {isAssistantMessage(message) ? (
+          // `renderMarkdown` sanitizes its input and then styles it; the SGR in its output is ours.
+          <RenderedText wrap="wrap">
+            {renderMarkdown(content + (isInterrupted ? '\n\n_(interrupted)_' : ''))}
+          </RenderedText>
+        ) : (
+          <Text wrap="wrap">{content}</Text>
+        )}
+      </Box>
+    </Box>
+  );
+});
+
+function ToolSummaryEntry({ entry }: { entry: IHistoryEntry }): React.ReactElement {
+  const palette = usePalette();
+  const modelCommandToolPrefix = useModelCommandToolPrefix();
+  const data = entry.data as
+    | {
+        summary?: string;
+        tools?: TToolSummaryItem[];
+      }
+    | undefined;
+  const tools = data?.tools;
+  const lines = data?.summary?.split('\n') ?? [];
+
+  if (tools && tools.length > 0) {
+    return (
+      <Box flexDirection="column" marginBottom={1}>
+        <Box>
+          <EntryLabel kind="tool" text="Tool: " color={palette.text.emphasis} />
+        </Box>
+        <Text> </Text>
+        {tools.map((tool, i) => {
+          const kind = toolSummaryStatusKind(
+            tool,
+            formatCommandOutputSummary(tool)?.status === 'error',
+          );
+          return (
+            <Box key={i} flexDirection="column">
+              <Text color={statusGlyphColor(palette, kind)}>
+                {'  '}
+                {getToolSummaryLabel(tool, kind, modelCommandToolPrefix)}
+              </Text>
+              <ToolCommandOutput tool={tool} />
+              {tool.diffLines && tool.diffLines.length > 0 && (
+                <ToolDiffBlock file={tool.diffFile} lines={tool.diffLines} />
+              )}
+            </Box>
+          );
+        })}
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <EntryLabel kind="tool" text="Tool: " color={palette.text.emphasis} />
+      </Box>
+      <Text> </Text>
+      {lines.map((line, i) => (
+        <Text key={i} color={palette.text.success}>
+          {'  '}
+          {sanitizeTerminalText(line)}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+function EventEntry({ entry }: { entry: IHistoryEntry }): React.ReactElement {
+  const palette = usePalette();
+  const eventData = entry.data as Record<string, TUniversalValue> | undefined;
+  // SEC-019: an event message is BUILT by a neutral package from untrusted parts — a skill name that
+  // may come from a plugin, a memory topic the model chose — and interpolated into a sentence. The
+  // formatter cannot sanitize for a terminal (the same string reaches the GUI, where escapes are not
+  // the threat and stripping them would be arbitrary), so this render site is the boundary.
+  const text =
+    typeof eventData?.message === 'string'
+      ? eventData.message
+      : typeof eventData?.content === 'string'
+        ? eventData.content
+        : undefined;
+  // An event without a message is a record kept for persistence or telemetry (a provider-call trace,
+  // a usage observation), not a notice; printing its type name only adds noise to the transcript.
+  if (text === undefined) return <></>;
+  const eventMessage = sanitizeTerminalText(text);
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <EntryLabel kind="warning" text="System: " color={palette.text.warning} />
+      </Box>
+      <Text> </Text>
+      <Box marginLeft={2}>
+        <Text wrap="wrap">{eventMessage}</Text>
+      </Box>
+    </Box>
+  );
+}
+
+export function EntryItem({ entry }: { entry: IHistoryEntry }): React.ReactElement {
+  if (entry.category === 'chat') {
+    const message = entry.data as TUniversalMessage;
+    return <MessageItem message={message} />;
+  }
+
+  if (entry.type === 'tool-summary') {
+    return <ToolSummaryEntry entry={entry} />;
+  }
+
+  if (entry.type === 'usage-summary') {
+    return <UsageSummaryEntry entry={entry} />;
+  }
+
+  // tool-start/tool-end are recorded in history for persistence but not rendered
+  // (StreamingIndicator shows them during streaming, tool-summary shows them after)
+  if (entry.type === 'tool-start' || entry.type === 'tool-end') {
+    return <></>;
+  }
+
+  return <EventEntry entry={entry} />;
+}
+
+export default function MessageList({ history }: IProps): React.ReactElement {
+  return (
+    <Box flexDirection="column">
+      {history.map((entry) => (
+        <EntryItem key={entry.id} entry={entry} />
+      ))}
+    </Box>
+  );
+}