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

package/src/UpdateNotice.tsx

@@ -0,0 +1,18 @@
+import { Box } from 'ink';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+import { usePalette } from './theme/index.js';
+
+interface IProps {
+  message: string;
+}
+
+export default function UpdateNotice({ message }: IProps): React.ReactElement {
+  const palette = usePalette();
+  return (
+    <Box paddingX={1} marginBottom={1}>
+      <Text color={palette.text.warning}>{message}</Text>
+    </Box>
+  );
+}

package/src/UsageSummaryEntry.tsx

@@ -0,0 +1,49 @@
+import { formatTokenCount } from '@robota-sdk/agent-core';
+import { Box } from 'ink';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+import { usePalette } from './theme/index.js';
+
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type { IUsageSnapshot } from '@robota-sdk/agent-interface-analytics';
+
+const TOKEN_COMPACT_THRESHOLD = 1000;
+
+export default function UsageSummaryEntry({ entry }: { entry: IHistoryEntry }): React.ReactElement {
+  const palette = usePalette();
+  const usage = entry.data as IUsageSnapshot | undefined;
+  if (!usage) return <></>;
+  const prompt = usage.promptTokens !== undefined ? formatUsageTokenCount(usage.promptTokens) : '?';
+  const completion =
+    usage.completionTokens !== undefined ? formatUsageTokenCount(usage.completionTokens) : '?';
+  const total = formatUsageTokenCount(usage.totalTokens);
+  // Usage another unit spent (the advisor, a background task) is named, and has no context window
+  // of the main thread to report.
+  const source =
+    usage.source !== undefined && usage.source.scope !== 'main' ? usage.source : undefined;
+  const sourceLabel = source ? (source.label ?? source.id ?? source.scope) : undefined;
+  const context = source
+    ? ''
+    : ` · Context ${Math.round(usage.contextUsedPercentage)}% (${formatTokenCount(
+        usage.contextUsedTokens,
+      )}/${formatTokenCount(usage.contextMaxTokens)})`;
+  const costLabel = usage.costStatus === 'unknown' ? 'cost unknown' : `cost ${usage.costStatus}`;
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <Text color={palette.text.emphasis} bold>
+          {sourceLabel ? `Usage (${sourceLabel}):` : 'Usage:'}{' '}
+        </Text>
+        <Text dimColor>
+          {usage.kind} {total} tokens (in {prompt} / out {completion}){context} · {costLabel}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+function formatUsageTokenCount(tokens: number): string {
+  return tokens < TOKEN_COMPACT_THRESHOLD ? tokens.toLocaleString() : formatTokenCount(tokens);
+}

package/src/WaveText.tsx

@@ -0,0 +1,70 @@
+/**
+ * WaveText — renders text with a subtle wave color animation.
+ * Groups of 3-4 characters share the same color, creating a soft flowing effect.
+ * The ramp comes from the resolved theme's motion tokens (SCREEN-006, SCREEN-2002): a calm span
+ * wide enough to be perceptible (#555→#bbb) at an unhurried 400ms cadence.
+ */
+
+import React, { useState, useEffect } from 'react';
+
+import { Text } from './SafeText.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { useMotion, useMotionTokens, usePalette } from './theme/index.js';
+
+/** Cadence is not themed: a theme changes colour, not how often the terminal repaints. */
+const MOTION_INTERVAL_MS = 400;
+const MOTION_CHARS_PER_GROUP = 4;
+
+interface IProps {
+  text: string;
+}
+
+export default function WaveText({ text }: IProps): React.ReactElement {
+  // Animate only on an interactive color terminal (shared with the markdown color
+  // gate via terminal-capabilities). Non-TTY / NO_COLOR / FORCE_COLOR=0 → static,
+  // no interval, no motion (SCREEN-006/008).
+  //
+  // CLI-2004: screen-reader mode is a gate on the same interval, not a second mechanism. A colour
+  // ramp is silent to a reader, but the repaint it causes is not — every tick re-emits the line, and
+  // the reader announces it again. SCREEN-2002 added `reducedMotion` as a third input to that rule.
+  const screenReader = useScreenReader();
+  const palette = usePalette();
+  const motionTokens = useMotionTokens();
+  // SCREEN-2002: the colour gate, screen-reader mode and the reduced-motion setting are ONE rule
+  // with one owner. This is its only consumer — the package's only animation.
+  const animate = useMotion();
+  const [tick, setTick] = useState(0);
+
+  useEffect(() => {
+    if (!animate) return undefined;
+    const timer = setInterval(() => {
+      setTick((prev) => prev + 1);
+    }, MOTION_INTERVAL_MS);
+    return () => clearInterval(timer);
+  }, [animate]);
+
+  if (screenReader) {
+    // No colour prop at all: the mode drops the cue rather than substituting a value.
+    return <Text>{text}</Text>;
+  }
+
+  if (!animate) {
+    return <Text color={palette.text.muted}>{text}</Text>;
+  }
+
+  const chars = [...text];
+
+  return (
+    <Text>
+      {chars.map((char, i) => {
+        const group = Math.floor(i / MOTION_CHARS_PER_GROUP);
+        const colorIndex = (tick + group) % motionTokens.wave.length;
+        return (
+          <Text key={i} color={motionTokens.wave[colorIndex]}>
+            {char}
+          </Text>
+        );
+      })}
+    </Text>
+  );
+}

package/src/__tests__/ListPicker.test.tsx

@@ -0,0 +1,188 @@
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { Text } from 'ink';
+import { describe, it, expect } from 'vitest';
+import ListPicker from '../ListPicker.js';
+import {
+  formatKeyHints,
+  SELECTION_INDICATOR,
+  SELECTION_INDICATOR_NONE,
+} from '../key-hint-footer.js';
+
+describe('ListPicker', () => {
+  it('renders all items with first selected by default', () => {
+    const items = ['Alpha', 'Beta', 'Gamma'];
+    const { lastFrame } = render(
+      <ListPicker
+        items={items}
+        renderItem={(item, isSelected) => (
+          <Text>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {item}
+          </Text>
+        )}
+        onSelect={() => {}}
+        onCancel={() => {}}
+      />,
+    );
+    const frame = lastFrame()!;
+    expect(frame).toContain('> Alpha');
+    expect(frame).toContain('  Beta');
+    expect(frame).toContain('  Gamma');
+  });
+
+  it('renders empty state when no items', () => {
+    const { lastFrame } = render(
+      <ListPicker
+        items={[]}
+        renderItem={(item, isSelected) => (
+          <Text>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {String(item)}
+          </Text>
+        )}
+        onSelect={() => {}}
+        onCancel={() => {}}
+      />,
+    );
+    // Should render without crashing
+    expect(lastFrame()).toBeDefined();
+  });
+
+  it('calls onSelect with item on Enter', () => {
+    let selected = '';
+    const items = ['Alpha', 'Beta'];
+    const { stdin } = render(
+      <ListPicker
+        items={items}
+        renderItem={(item, isSelected) => (
+          <Text>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {item}
+          </Text>
+        )}
+        onSelect={(item) => {
+          selected = item;
+        }}
+        onCancel={() => {}}
+      />,
+    );
+    stdin.write('\r');
+    expect(selected).toBe('Alpha');
+  });
+
+  it('navigates down with arrow key and selects', () => {
+    let selected = '';
+    const items = ['Alpha', 'Beta', 'Gamma'];
+    const { stdin } = render(
+      <ListPicker
+        items={items}
+        renderItem={(item, isSelected) => (
+          <Text>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {item}
+          </Text>
+        )}
+        onSelect={(item) => {
+          selected = item;
+        }}
+        onCancel={() => {}}
+      />,
+    );
+    stdin.write('\x1B[B'); // Down arrow
+    stdin.write('\r');
+    expect(selected).toBe('Beta');
+  });
+
+  it('calls onCancel on Escape', async () => {
+    const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+    let cancelled = false;
+    const { stdin } = render(
+      <ListPicker
+        items={['Alpha']}
+        renderItem={(item, isSelected) => (
+          <Text>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {item}
+          </Text>
+        )}
+        onSelect={() => {}}
+        onCancel={() => {
+          cancelled = true;
+        }}
+      />,
+    );
+    stdin.write('\x1B');
+    await delay(50);
+    expect(cancelled).toBe(true);
+  });
+
+  it('does not go above first item', () => {
+    const items = ['Alpha', 'Beta'];
+    const { stdin, lastFrame } = render(
+      <ListPicker
+        items={items}
+        renderItem={(item, isSelected) => (
+          <Text>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {item}
+          </Text>
+        )}
+        onSelect={() => {}}
+        onCancel={() => {}}
+      />,
+    );
+    stdin.write('\x1B[A'); // Up arrow (already at 0)
+    const frame = lastFrame()!;
+    expect(frame).toContain('> Alpha');
+  });
+
+  it('does not go below last item', () => {
+    let selected = '';
+    const items = ['Alpha', 'Beta'];
+    const { stdin } = render(
+      <ListPicker
+        items={items}
+        renderItem={(item, isSelected) => (
+          <Text>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {item}
+          </Text>
+        )}
+        onSelect={(item) => {
+          selected = item;
+        }}
+        onCancel={() => {}}
+      />,
+    );
+    stdin.write('\x1B[B'); // Down
+    stdin.write('\x1B[B'); // Down (should stay at Beta)
+    stdin.write('\x1B[B'); // Down (should stay at Beta)
+    stdin.write('\r');
+    expect(selected).toBe('Beta');
+  });
+
+  // SCREEN-005: default footer renders through the key-hint SSOT grammar.
+  it('renders the default footer in the shared key-hint grammar', () => {
+    const { lastFrame } = render(
+      <ListPicker
+        items={['Alpha']}
+        renderItem={(item, isSelected) => (
+          <Text>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {item}
+          </Text>
+        )}
+        onSelect={() => {}}
+        onCancel={() => {}}
+      />,
+    );
+    expect(lastFrame()!).toContain(
+      formatKeyHints([
+        { keys: '↑↓', label: 'Navigate' },
+        { keys: 'Enter', label: 'Select' },
+        { keys: 'Esc', label: 'Cancel' },
+      ]),
+    );
+  });
+});

package/src/__tests__/MenuSelect.test.tsx

@@ -0,0 +1,127 @@
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, it, expect } from 'vitest';
+import MenuSelect from '../MenuSelect.js';
+import { formatKeyHints } from '../key-hint-footer.js';
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe('MenuSelect', () => {
+  const items = [
+    { label: 'Option A', value: 'a' },
+    { label: 'Option B', value: 'b', hint: 'some hint' },
+    { label: 'Option C', value: 'c' },
+  ];
+
+  it('renders title and all items', () => {
+    const { lastFrame } = render(
+      <MenuSelect title="Test Menu" items={items} onSelect={() => {}} onBack={() => {}} />,
+    );
+    const frame = lastFrame()!;
+    expect(frame).toContain('Test Menu');
+    expect(frame).toContain('Option A');
+    expect(frame).toContain('Option B');
+    expect(frame).toContain('Option C');
+  });
+
+  it('renders hint text when provided', () => {
+    const { lastFrame } = render(
+      <MenuSelect title="Test" items={items} onSelect={() => {}} onBack={() => {}} />,
+    );
+    expect(lastFrame()!).toContain('some hint');
+  });
+
+  it('highlights first item by default with > prefix', () => {
+    const { lastFrame } = render(
+      <MenuSelect title="Test" items={items} onSelect={() => {}} onBack={() => {}} />,
+    );
+    expect(lastFrame()!).toContain('>');
+  });
+
+  it('shows loading state', () => {
+    const { lastFrame } = render(
+      <MenuSelect title="Test" items={[]} onSelect={() => {}} onBack={() => {}} loading />,
+    );
+    expect(lastFrame()!).toContain('Loading');
+  });
+
+  it('shows error state', () => {
+    const { lastFrame } = render(
+      <MenuSelect title="Test" items={[]} onSelect={() => {}} onBack={() => {}} error="Failed" />,
+    );
+    expect(lastFrame()!).toContain('Failed');
+  });
+
+  it('calls onSelect with value on Enter', () => {
+    let selected = '';
+    const { stdin } = render(
+      <MenuSelect
+        title="Test"
+        items={items}
+        onSelect={(v) => {
+          selected = v;
+        }}
+        onBack={() => {}}
+      />,
+    );
+    stdin.write('\r');
+    expect(selected).toBe('a');
+  });
+
+  it('calls onBack on Escape', async () => {
+    let backed = false;
+    const { stdin } = render(
+      <MenuSelect
+        title="Test"
+        items={items}
+        onSelect={() => {}}
+        onBack={() => {
+          backed = true;
+        }}
+      />,
+    );
+    stdin.write('\x1B');
+    await delay(50);
+    expect(backed).toBe(true);
+  });
+
+  it('navigates down with arrow key', () => {
+    let selected = '';
+    const { stdin } = render(
+      <MenuSelect
+        title="Test"
+        items={items}
+        onSelect={(v) => {
+          selected = v;
+        }}
+        onBack={() => {}}
+      />,
+    );
+    stdin.write('\x1B[B'); // Down arrow
+    stdin.write('\r');
+    expect(selected).toBe('b');
+  });
+
+  // SCREEN-005: footer + error-state hint render through the key-hint SSOT grammar.
+  it('renders the footer in the shared key-hint grammar', () => {
+    const { lastFrame } = render(
+      <MenuSelect title="Test" items={items} onSelect={() => {}} onBack={() => {}} />,
+    );
+    expect(lastFrame()!).toContain(
+      formatKeyHints([
+        { keys: '↑↓', label: 'Navigate' },
+        { keys: 'Enter', label: 'Select' },
+        { keys: 'Esc', label: 'Back' },
+      ]),
+    );
+  });
+
+  it('renders the error-state hint via the shared key-hint grammar', () => {
+    const { lastFrame } = render(
+      <MenuSelect title="Test" items={[]} onSelect={() => {}} onBack={() => {}} error="Failed" />,
+    );
+    const frame = lastFrame()!;
+    expect(frame).toContain(formatKeyHints([{ keys: 'Esc', label: 'Back' }]));
+    expect(frame).not.toContain('Press Esc to go back');
+  });
+});

package/src/__tests__/PendingActionPrompt.test.tsx

@@ -0,0 +1,193 @@
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import PendingActionPrompt from '../PendingActionPrompt.js';
+import { formatKeyHints } from '../key-hint-footer.js';
+
+import type { IActionRequest } from '@robota-sdk/agent-core';
+
+const delay = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 20));
+const ESC = String.fromCharCode(27);
+const DOWN = `${ESC}[B`;
+const ENTER = '\r';
+
+describe('PendingActionPrompt (CMD-004 unified action renderer)', () => {
+  it('single-select: renders options and answers with the chosen value', async () => {
+    const onAnswer = vi.fn();
+    const request: IActionRequest = {
+      id: 'mode',
+      title: 'Select mode',
+      options: [
+        { value: 'plan', label: 'Plan' },
+        { value: 'default', label: 'Default' },
+      ],
+      maxSelect: 1,
+    };
+    const { stdin, lastFrame } = render(
+      <PendingActionPrompt request={request} onAnswer={onAnswer} />,
+    );
+    expect(lastFrame()).toContain('Select mode');
+    expect(lastFrame()).toContain('Plan');
+
+    stdin.write(DOWN);
+    await delay();
+    stdin.write(ENTER);
+    await delay();
+    expect(onAnswer).toHaveBeenCalledWith({ type: 'answer', values: ['default'] });
+  });
+
+  it('single-select: the highlight starts on the request default — a No-default confirmation answers No on Enter (BEHAVIOR-2437)', async () => {
+    const onAnswer = vi.fn();
+    const request: IActionRequest = {
+      id: 'git-commit',
+      title: 'Commit 1 staged file(s)?',
+      options: [
+        { value: 'yes', label: 'Yes' },
+        { value: 'no', label: 'No' },
+      ],
+      maxSelect: 1,
+      default: { values: ['no'] },
+    };
+    const { stdin, lastFrame } = render(
+      <PendingActionPrompt request={request} onAnswer={onAnswer} />,
+    );
+    expect(lastFrame()).toContain('> No');
+    expect(lastFrame()).not.toContain('> Yes');
+
+    stdin.write(ENTER);
+    await delay();
+    expect(onAnswer).toHaveBeenCalledWith({ type: 'answer', values: ['no'] });
+  });
+
+  it('multi-select (maxSelect>1): toggles with Space and confirms with Enter', async () => {
+    const onAnswer = vi.fn();
+    const request: IActionRequest = {
+      id: 'tags',
+      title: 'Pick tags',
+      options: [
+        { value: 'a', label: 'Alpha' },
+        { value: 'b', label: 'Beta' },
+        { value: 'c', label: 'Gamma' },
+      ],
+      minSelect: 1,
+      maxSelect: 3,
+    };
+    const { stdin, lastFrame } = render(
+      <PendingActionPrompt request={request} onAnswer={onAnswer} />,
+    );
+    expect(lastFrame()).toContain('[ ] Alpha');
+
+    stdin.write(' ');
+    await delay();
+    expect(lastFrame()).toContain('[x] Alpha');
+    stdin.write(DOWN);
+    await delay();
+    stdin.write(' ');
+    await delay();
+    stdin.write(ENTER);
+    await delay();
+    expect(onAnswer).toHaveBeenCalledWith({ type: 'answer', values: ['a', 'b'] });
+  });
+
+  it('free-text with masked: hides input and answers with typed text', async () => {
+    const onAnswer = vi.fn();
+    const request: IActionRequest = {
+      id: 'apiKey',
+      title: 'Enter API key',
+      allowFreeText: true,
+      masked: true,
+    };
+    const { stdin, lastFrame } = render(
+      <PendingActionPrompt request={request} onAnswer={onAnswer} />,
+    );
+    expect(lastFrame()).toContain('Enter API key');
+
+    stdin.write('sk-secret');
+    await delay();
+    expect(lastFrame()).not.toContain('sk-secret');
+    expect(lastFrame()).toContain('*'.repeat('sk-secret'.length));
+    stdin.write(ENTER);
+    await delay();
+    expect(onAnswer).toHaveBeenCalledWith({ type: 'answer', values: [], text: 'sk-secret' });
+  });
+
+  it('Esc cancels the request (resolves cancelled)', async () => {
+    const onAnswer = vi.fn();
+    const request: IActionRequest = {
+      id: 'exit',
+      title: 'Exit?',
+      options: [
+        { value: 'yes', label: 'Yes' },
+        { value: 'no', label: 'No' },
+      ],
+      maxSelect: 1,
+    };
+    const { stdin } = render(<PendingActionPrompt request={request} onAnswer={onAnswer} />);
+    stdin.write(ESC);
+    await delay();
+    expect(onAnswer).toHaveBeenCalledWith({ type: 'cancelled' });
+  });
+
+  it('single-select + allowFreeText: "type a custom answer" opens text; Esc returns to picker (not cancel)', async () => {
+    const onAnswer = vi.fn();
+    const request: IActionRequest = {
+      id: 'provider',
+      title: 'Select provider',
+      options: [{ value: 'openai', label: 'OpenAI' }],
+      maxSelect: 1,
+      allowFreeText: true,
+    };
+    const { stdin, lastFrame } = render(
+      <PendingActionPrompt request={request} onAnswer={onAnswer} />,
+    );
+    expect(lastFrame()).toContain('Type a custom answer');
+
+    stdin.write(DOWN); // move to the synthetic "type a custom answer" entry
+    await delay();
+    stdin.write(ENTER); // enter free-text mode
+    await delay();
+    stdin.write(ESC); // Esc here returns to the picker, does NOT cancel the request
+    await delay();
+    expect(onAnswer).not.toHaveBeenCalled();
+    expect(lastFrame()).toContain('OpenAI'); // back at the picker
+  });
+
+  // SCREEN-005: multi-select footer goes through the key-hint SSOT, keeping the dynamic (min N)
+  // segment on the Enter hint until the selection is confirmable.
+  it('multi-select footer shows the (min N) segment until satisfiable, in the shared grammar', async () => {
+    const onAnswer = vi.fn();
+    const request: IActionRequest = {
+      id: 'tags',
+      title: 'Pick tags',
+      options: [
+        { value: 'a', label: 'Alpha' },
+        { value: 'b', label: 'Beta' },
+      ],
+      minSelect: 1,
+      maxSelect: 2,
+    };
+    const { stdin, lastFrame } = render(
+      <PendingActionPrompt request={request} onAnswer={onAnswer} />,
+    );
+    expect(lastFrame()).toContain(
+      formatKeyHints([
+        { keys: '↑↓', label: 'Navigate' },
+        { keys: 'Space', label: 'Toggle' },
+        { keys: 'Enter', label: 'Confirm (min 1)' },
+        { keys: 'Esc', label: 'Cancel' },
+      ]),
+    );
+
+    stdin.write(' '); // toggle Alpha → selection satisfiable → min segment drops
+    await delay();
+    expect(lastFrame()).toContain(
+      formatKeyHints([
+        { keys: '↑↓', label: 'Navigate' },
+        { keys: 'Space', label: 'Toggle' },
+        { keys: 'Enter', label: 'Confirm' },
+        { keys: 'Esc', label: 'Cancel' },
+      ]),
+    );
+  });
+});