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

package/src/tui/TransportTUI.tsx

@@ -0,0 +1,116 @@
+/**
+ * TransportTUI — interactive overlay for transport enable/disable settings.
+ *
+ * Arrow keys navigate the list, space toggles enabled/disabled, enter/esc closes.
+ */
+
+import React, { useState, useCallback } from 'react';
+import { Box, Text, useInput } from 'ink';
+import type {
+  ITransportEntry,
+  ITransportRegistryView,
+} from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+
+const TRANSPORT_NAME_WIDTH = 18;
+
+interface IEntryRowProps {
+  entry: ITransportEntry<IInteractiveSession>;
+  selected: boolean;
+}
+
+function TransportEntryRow({ entry, selected }: IEntryRowProps): React.ReactElement {
+  const enabled = entry.config.enabled;
+  const dot = enabled ? '●' : '○';
+  const badge = enabled ? '[enabled] ' : '[disabled]';
+  const portOpt = entry.config.options?.port;
+  const portHint = typeof portOpt === 'number' ? `port: ${portOpt}` : '';
+  return (
+    <Box>
+      <Text color={selected ? 'cyan' : undefined} bold={selected}>
+        {`${dot} ${entry.transport.name.padEnd(TRANSPORT_NAME_WIDTH)} ${badge}  ${portHint}`}
+      </Text>
+    </Box>
+  );
+}
+
+type TKey = { upArrow: boolean; downArrow: boolean; escape: boolean; return: boolean };
+
+function useTransportInput(
+  entries: ITransportEntry<IInteractiveSession>[],
+  cursor: number,
+  saving: boolean,
+  registry: ITransportRegistryView<IInteractiveSession>,
+  setCursor: (fn: (c: number) => number) => void,
+  setSaving: (v: boolean) => void,
+  onClose: () => void,
+  refresh: () => void,
+): void {
+  useInput(
+    useCallback(
+      (_input: string, key: TKey) => {
+        if (saving) return;
+        if (key.upArrow) {
+          setCursor((c) => Math.max(0, c - 1));
+          return;
+        }
+        if (key.downArrow) {
+          setCursor((c) => Math.min(entries.length - 1, c + 1));
+          return;
+        }
+        if (key.escape || key.return) {
+          onClose();
+          return;
+        }
+        if (_input === ' ') {
+          const entry = entries[cursor];
+          if (!entry) return;
+          setSaving(true);
+          registry
+            .setEnabled(entry.transport.name, !entry.config.enabled)
+            .then(() => {
+              refresh();
+              setSaving(false);
+            })
+            .catch(() => setSaving(false));
+        }
+      },
+      [saving, entries, cursor, registry, onClose, refresh, setCursor, setSaving],
+    ),
+  );
+}
+
+interface IProps {
+  registry: ITransportRegistryView<IInteractiveSession>;
+  onClose: () => void;
+}
+
+export default function TransportTUI({ registry, onClose }: IProps): React.ReactElement {
+  const [entries, setEntries] = useState(() => registry.getAll());
+  const [cursor, setCursor] = useState(0);
+  const [saving, setSaving] = useState(false);
+  const refresh = useCallback((): void => {
+    setEntries(registry.getAll());
+  }, [registry]);
+
+  useTransportInput(entries, cursor, saving, registry, setCursor, setSaving, onClose, refresh);
+
+  return (
+    <Box flexDirection="column" paddingX={2} paddingY={1}>
+      <Text bold>Settings › Transports</Text>
+      <Box marginTop={1} flexDirection="column">
+        {entries.map((entry, i) => (
+          <TransportEntryRow key={entry.transport.name} entry={entry} selected={i === cursor} />
+        ))}
+      </Box>
+      <Box marginTop={1}>
+        <Text dimColor>↑↓ select space toggle enter/esc close</Text>
+      </Box>
+      {saving && (
+        <Box marginTop={1}>
+          <Text color="yellow">Saving…</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}

package/src/tui/UpdateNotice.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+
+interface IProps {
+  message: string;
+}
+
+export default function UpdateNotice({ message }: IProps): React.ReactElement {
+  return (
+    <Box paddingX={1} marginBottom={1}>
+      <Text color="yellow">{message}</Text>
+    </Box>
+  );
+}

package/src/tui/UsageSummaryEntry.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import { formatTokenCount } from '@robota-sdk/agent-core';
+import type { IUsageSnapshot } from '@robota-sdk/agent-framework';
+
+const TOKEN_COMPACT_THRESHOLD = 1000;
+
+export default function UsageSummaryEntry({ entry }: { entry: IHistoryEntry }): React.ReactElement {
+  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);
+  const 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="white" bold>
+          Usage:{' '}
+        </Text>
+        <Text dimColor>
+          {usage.kind} {total} tokens (in {prompt} / out {completion}) · Context {context} ·{' '}
+          {costLabel}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+function formatUsageTokenCount(tokens: number): string {
+  return tokens < TOKEN_COMPACT_THRESHOLD ? tokens.toLocaleString() : formatTokenCount(tokens);
+}

package/src/tui/WaveText.tsx

@@ -0,0 +1,44 @@
+/**
+ * WaveText — renders text with a subtle wave color animation.
+ * Groups of 3-4 characters share the same color, creating a soft flowing effect.
+ * Colors stay in a narrow range (dim grays) to avoid harsh contrast.
+ */
+
+import React, { useState, useEffect } from 'react';
+import { Text } from 'ink';
+
+// Subtle gray tones — minimal contrast, soft wave
+const WAVE_COLORS = ['#666666', '#888888', '#aaaaaa', '#888888'] as const;
+const INTERVAL_MS = 400;
+const CHARS_PER_GROUP = 4;
+
+interface IProps {
+  text: string;
+}
+
+export default function WaveText({ text }: IProps): React.ReactElement {
+  const [tick, setTick] = useState(0);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setTick((prev) => prev + 1);
+    }, INTERVAL_MS);
+    return () => clearInterval(timer);
+  }, []);
+
+  const chars = [...text];
+
+  return (
+    <Text>
+      {chars.map((char, i) => {
+        const group = Math.floor(i / CHARS_PER_GROUP);
+        const colorIndex = (tick + group) % WAVE_COLORS.length;
+        return (
+          <Text key={i} color={WAVE_COLORS[colorIndex]}>
+            {char}
+          </Text>
+        );
+      })}
+    </Text>
+  );
+}

package/src/tui/__tests__/InteractivePrompt.test.tsx

@@ -0,0 +1,82 @@
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, expect, it, vi } from 'vitest';
+import InteractivePrompt from '../InteractivePrompt.js';
+
+const delay = () => new Promise((resolve) => setTimeout(resolve, 20));
+
+describe('InteractivePrompt', () => {
+  it('renders a generic choice prompt and submits the selected value', async () => {
+    const onSubmit = vi.fn();
+    const { stdin, lastFrame } = render(
+      <InteractivePrompt
+        prompt={{
+          kind: 'choice',
+          title: 'Select item',
+          options: [
+            { value: 'first', label: 'First item' },
+            { value: 'second', label: 'Second item' },
+          ],
+        }}
+        onSubmit={onSubmit}
+        onCancel={() => {}}
+      />,
+    );
+
+    expect(lastFrame()!).toContain('Select item');
+    expect(lastFrame()!).toContain('First item');
+
+    stdin.write('\u001B[B');
+    await delay();
+    stdin.write('\r');
+    await delay();
+
+    expect(onSubmit).toHaveBeenCalledWith('second');
+  });
+
+  it('renders a generic text prompt and validates submitted values', async () => {
+    const onSubmit = vi.fn();
+    const { stdin, lastFrame } = render(
+      <InteractivePrompt
+        prompt={{
+          kind: 'text',
+          title: 'Secret',
+          masked: true,
+          validate: (value) => (value.length === 0 ? 'Required' : undefined),
+        }}
+        onSubmit={onSubmit}
+        onCancel={() => {}}
+      />,
+    );
+
+    stdin.write('\r');
+    await delay();
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(lastFrame()!).toContain('Required');
+
+    stdin.write('abc');
+    await delay();
+    stdin.write('\r');
+    await delay();
+    expect(onSubmit).toHaveBeenCalledWith('abc');
+  });
+
+  it('renders generic prompt descriptions without command-specific UI branches', () => {
+    const { lastFrame } = render(
+      <InteractivePrompt
+        prompt={{
+          kind: 'text',
+          title: 'OpenAI API key',
+          description:
+            'Setup help: API key: OpenAI API keys - https://platform.openai.com/api-keys',
+        }}
+        onSubmit={() => {}}
+        onCancel={() => {}}
+      />,
+    );
+
+    expect(lastFrame()!).toContain('OpenAI API key');
+    expect(lastFrame()!).toContain('OpenAI API keys');
+    expect(lastFrame()!).toContain('https://platform.openai.com/api-keys');
+  });
+});

package/src/tui/__tests__/ListPicker.test.tsx

@@ -0,0 +1,159 @@
+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';
+
+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 ? '> ' : '  '}
+            {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 ? '> ' : '  '}
+            {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 ? '> ' : '  '}
+            {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 ? '> ' : '  '}
+            {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 ? '> ' : '  '}
+            {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 ? '> ' : '  '}
+            {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 ? '> ' : '  '}
+            {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');
+  });
+});

package/src/tui/__tests__/MenuSelect.test.tsx

@@ -0,0 +1,103 @@
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, it, expect } from 'vitest';
+import MenuSelect from '../MenuSelect.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');
+  });
+});