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

package/src/__tests__/interaction-channel-charter.test.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+const TUI_CHANNEL_SOURCE = new URL('../TuiInteractionChannel.ts', import.meta.url);
+describe('ARCH-018 interaction-channel charter', () => {
+  it('does not retain nominal TUI conformance with a no-op write path', () => {
+    const source = readFileSync(TUI_CHANNEL_SOURCE, 'utf8');
+
+    expect(source).not.toContain('implements IInteractionChannel');
+    expect(source).not.toMatch(/write\(_event:\s*InteractionEvent\)/);
+  });
+});

package/src/__tests__/key-hint-consistency.test.tsx

@@ -0,0 +1,249 @@
+/**
+ * SCREEN-005 anti-drift consistency guard — the mechanical floor for the key-hint SSOT.
+ *
+ * Covers the FULL footer inventory: every component's declared hint set must (a) render exactly as
+ * `formatKeyHints(<declared hints>)` (round-trip through the SSOT — a fourth footer dialect cannot
+ * re-appear silently), and (b) obey the navigate → modify → primary → dismiss ordering. Also pins
+ * the Esc-suppression contract: the explicit-resolve prompts (Confirm/Permission) omit Esc from
+ * their footers because their flows suppress it.
+ */
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, expect, it } from 'vitest';
+import { Text } from 'ink';
+
+import ConfirmPrompt, { CONFIRM_PROMPT_FOOTER_HINTS } from '../ConfirmPrompt.js';
+import ExecutionWorkspaceSwitcher, {
+  EXECUTION_WORKSPACE_SWITCHER_FOOTER_HINTS,
+} from '../ExecutionWorkspaceSwitcher.js';
+import ListPicker, { LIST_PICKER_DEFAULT_FOOTER_HINTS } from '../ListPicker.js';
+import MenuSelect, {
+  MENU_SELECT_ERROR_FOOTER_HINTS,
+  MENU_SELECT_FOOTER_HINTS,
+} from '../MenuSelect.js';
+import MultiSelectList, { getMultiSelectFooterHints } from '../MultiSelectList.js';
+import PermissionPrompt, { PERMISSION_PROMPT_FOOTER_HINTS } from '../PermissionPrompt.js';
+import SlashAutocomplete, { SLASH_AUTOCOMPLETE_FOOTER_HINTS } from '../SlashAutocomplete.js';
+import TextPrompt, { TEXT_PROMPT_FOOTER_HINTS } from '../TextPrompt.js';
+import HistorySearchOverlay, { HISTORY_SEARCH_FOOTER_HINTS } from '../HistorySearchOverlay.js';
+import { formatKeyHints, type IKeyHint } from '../key-hint-footer.js';
+
+import type { ICommand } from '@robota-sdk/agent-interface-command';
+import type { IExecutionWorkspaceSnapshot } from '@robota-sdk/agent-interface-execution';
+
+/**
+ * Footer ordering contract: navigate → modify → primary → dismiss (docs/SPEC.md "Interaction
+ * affordance contract"). The rank vocabulary lives here in the test — the SSOT module stays
+ * mechanics-only.
+ */
+const KEY_RANK: Record<string, number> = {
+  '↑↓': 0, // navigate
+  '←→': 0, // navigate
+  Space: 1, // modify
+  Tab: 1, // modify
+  'Ctrl+S': 1, // modify (SCREEN-1993: the search scope)
+  Enter: 2, // primary
+  'Enter/Tab': 2, // primary (SCREEN-1993: insert the match)
+  'Ctrl+E': 2, // primary (SCREEN-1993: run the match)
+  Esc: 3, // dismiss
+  'Ctrl+B/Esc': 3, // dismiss
+};
+
+interface IFooterInventoryEntry {
+  name: string;
+  hints: readonly IKeyHint[];
+  renderFrame: () => string;
+}
+
+function makeSnapshot(): IExecutionWorkspaceSnapshot {
+  return {
+    sessionId: 's1',
+    selectedEntryId: 'main:s1',
+    updatedAt: '2026-07-24T00:00:00.000Z',
+    entries: [
+      {
+        id: 'main:s1',
+        sourceId: 's1',
+        kind: 'main_thread',
+        origin: { kind: 'user_prompt', sessionId: 's1' },
+        status: 'idle',
+        state: 'completed',
+        title: 'Main thread',
+        unread: false,
+        attention: 'none',
+        visibility: 'default',
+        updatedAt: '2026-07-24T00:00:00.000Z',
+        controls: ['select'],
+      },
+    ],
+  };
+}
+
+const noop = (): void => {};
+
+/** The FULL footer inventory — every footer call site in the package. */
+const FOOTER_INVENTORY: readonly IFooterInventoryEntry[] = [
+  {
+    name: 'ListPicker (default footer)',
+    hints: LIST_PICKER_DEFAULT_FOOTER_HINTS,
+    renderFrame: () =>
+      render(
+        <ListPicker
+          items={['a']}
+          renderItem={(item) => <Text>{item}</Text>}
+          onSelect={noop}
+          onCancel={noop}
+        />,
+      ).lastFrame()!,
+  },
+  {
+    name: 'SlashAutocomplete',
+    hints: SLASH_AUTOCOMPLETE_FOOTER_HINTS,
+    renderFrame: () =>
+      render(
+        <SlashAutocomplete
+          commands={[{ name: 'help', description: 'Show help' } as ICommand]}
+          selectedIndex={0}
+          visible={true}
+        />,
+      ).lastFrame()!,
+  },
+  {
+    name: 'TextPrompt',
+    hints: TEXT_PROMPT_FOOTER_HINTS,
+    renderFrame: () =>
+      render(<TextPrompt title="t" onSubmit={noop} onCancel={noop} />).lastFrame()!,
+  },
+  {
+    name: 'MenuSelect (normal)',
+    hints: MENU_SELECT_FOOTER_HINTS,
+    renderFrame: () =>
+      render(
+        <MenuSelect title="t" items={[{ label: 'A', value: 'a' }]} onSelect={noop} onBack={noop} />,
+      ).lastFrame()!,
+  },
+  {
+    name: 'MenuSelect (error-state hint)',
+    hints: MENU_SELECT_ERROR_FOOTER_HINTS,
+    renderFrame: () =>
+      render(
+        <MenuSelect title="t" items={[]} onSelect={noop} onBack={noop} error="Failed" />,
+      ).lastFrame()!,
+  },
+  {
+    name: 'MultiSelectList (min not yet satisfied)',
+    hints: getMultiSelectFooterHints({ canConfirm: false, minSelect: 2 }),
+    renderFrame: () =>
+      render(
+        <MultiSelectList
+          title="t"
+          options={[
+            { value: 'a', label: 'A' },
+            { value: 'b', label: 'B' },
+          ]}
+          minSelect={2}
+          maxSelect={2}
+          onConfirm={noop}
+          onCancel={noop}
+        />,
+      ).lastFrame()!,
+  },
+  {
+    name: 'MultiSelectList (confirmable)',
+    hints: getMultiSelectFooterHints({ canConfirm: true, minSelect: 0 }),
+    renderFrame: () =>
+      render(
+        <MultiSelectList
+          title="t"
+          options={[{ value: 'a', label: 'A' }]}
+          minSelect={0}
+          maxSelect={1}
+          onConfirm={noop}
+          onCancel={noop}
+        />,
+      ).lastFrame()!,
+  },
+  {
+    name: 'ConfirmPrompt',
+    hints: CONFIRM_PROMPT_FOOTER_HINTS,
+    renderFrame: () => render(<ConfirmPrompt message="m" onSelect={noop} />).lastFrame()!,
+  },
+  {
+    name: 'PermissionPrompt',
+    hints: PERMISSION_PROMPT_FOOTER_HINTS,
+    renderFrame: () =>
+      render(
+        <PermissionPrompt request={{ toolName: 'tool', toolArgs: {}, resolve: noop }} />,
+      ).lastFrame()!,
+  },
+  {
+    name: 'HistorySearchOverlay',
+    hints: HISTORY_SEARCH_FOOTER_HINTS,
+    renderFrame: () =>
+      render(
+        <HistorySearchOverlay
+          view={{
+            open: true,
+            query: '',
+            scope: 'all',
+            selectedIndex: 0,
+            matches: [],
+            loading: false,
+            skippedLines: 0,
+            error: undefined,
+          }}
+        />,
+      ).lastFrame()!,
+  },
+  {
+    name: 'ExecutionWorkspaceSwitcher',
+    hints: EXECUTION_WORKSPACE_SWITCHER_FOOTER_HINTS,
+    renderFrame: () =>
+      render(
+        <ExecutionWorkspaceSwitcher
+          snapshot={makeSnapshot()}
+          selectedEntryId="main:s1"
+          onSelect={noop}
+          onClose={noop}
+        />,
+      ).lastFrame()!,
+  },
+];
+
+describe('key-hint consistency (SCREEN-005 anti-drift guard)', () => {
+  it.each(FOOTER_INVENTORY.map((entry) => [entry.name, entry] as const))(
+    '%s: rendered footer round-trips through formatKeyHints',
+    (_name, entry) => {
+      expect(entry.renderFrame()).toContain(formatKeyHints(entry.hints));
+    },
+  );
+
+  it.each(FOOTER_INVENTORY.map((entry) => [entry.name, entry] as const))(
+    '%s: hint order is navigate → modify → primary → dismiss',
+    (_name, entry) => {
+      const ranks = entry.hints.map((hint) => {
+        const rank = KEY_RANK[hint.keys];
+        if (rank === undefined) {
+          throw new Error(
+            `Unknown key '${hint.keys}' — add it to KEY_RANK with its ordering category`,
+          );
+        }
+        return rank;
+      });
+      const sorted = [...ranks].sort((a, b) => a - b);
+      expect(ranks).toEqual(sorted);
+    },
+  );
+
+  it('explicit-resolve prompts (Confirm/Permission) omit Esc from their footers', () => {
+    for (const hints of [CONFIRM_PROMPT_FOOTER_HINTS, PERMISSION_PROMPT_FOOTER_HINTS]) {
+      expect(hints.some((hint) => hint.keys.includes('Esc'))).toBe(false);
+    }
+  });
+
+  it('Confirm and Permission prompt footers are identical (same row, same reducer)', () => {
+    expect(formatKeyHints(CONFIRM_PROMPT_FOOTER_HINTS)).toBe(
+      formatKeyHints(PERMISSION_PROMPT_FOOTER_HINTS),
+    );
+  });
+});

package/src/__tests__/key-hint-footer.test.tsx

@@ -0,0 +1,69 @@
+/**
+ * SCREEN-005: key-hint footer SSOT unit tests — formatter grammar, separator constant, indicator
+ * constants, and the KeyHintFooter render contract (dim, leading pad, nothing when empty).
+ */
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, expect, it } from 'vitest';
+
+import {
+  formatKeyHints,
+  KeyHintFooter,
+  KEY_HINT_SEPARATOR,
+  SELECTION_INDICATOR,
+  SELECTION_INDICATOR_NONE,
+  type IKeyHint,
+} from '../key-hint-footer.js';
+
+describe('formatKeyHints', () => {
+  it('joins keys+label pairs with the separator constant', () => {
+    const hints: IKeyHint[] = [
+      { keys: '↑↓', label: 'Navigate' },
+      { keys: 'Enter', label: 'Select' },
+      { keys: 'Esc', label: 'Cancel' },
+    ];
+    expect(formatKeyHints(hints)).toBe(
+      `↑↓ Navigate${KEY_HINT_SEPARATOR}Enter Select${KEY_HINT_SEPARATOR}Esc Cancel`,
+    );
+  });
+
+  it('renders a single hint without a separator', () => {
+    expect(formatKeyHints([{ keys: 'Esc', label: 'Back' }])).toBe('Esc Back');
+  });
+
+  it('returns the empty string for an empty list', () => {
+    expect(formatKeyHints([])).toBe('');
+  });
+
+  it('keeps the keys-before-label pair order', () => {
+    expect(formatKeyHints([{ keys: 'Space', label: 'Toggle' }])).toBe('Space Toggle');
+  });
+});
+
+describe('constants', () => {
+  it('separator is the middle-dot idiom', () => {
+    expect(KEY_HINT_SEPARATOR).toBe(' · ');
+  });
+
+  it('selection indicator and its blank counterpart are the same width', () => {
+    expect(SELECTION_INDICATOR).toBe('> ');
+    expect(SELECTION_INDICATOR_NONE).toBe('  ');
+    expect(SELECTION_INDICATOR_NONE.length).toBe(SELECTION_INDICATOR.length);
+  });
+});
+
+describe('KeyHintFooter', () => {
+  it('renders the formatted hints with a leading pad', () => {
+    const hints: IKeyHint[] = [
+      { keys: 'Enter', label: 'Submit' },
+      { keys: 'Esc', label: 'Cancel' },
+    ];
+    const { lastFrame } = render(<KeyHintFooter hints={hints} />);
+    expect(lastFrame()).toBe(` ${formatKeyHints(hints)}`);
+  });
+
+  it('renders nothing for an empty hint list', () => {
+    const { lastFrame } = render(<KeyHintFooter hints={[]} />);
+    expect(lastFrame()).toBe('');
+  });
+});

package/src/__tests__/live-trace-reaches-session.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it, vi } from 'vitest';
+import { toChannelOptions } from '../render.js';
+import { buildTuiSessionOptions } from '../tui-session-options.js';
+import type { IRenderOptions } from '../render.js';
+
+describe('live trace port projection', () => {
+  it('passes the exact host port through the TUI to the runtime session', () => {
+    const livePromptTrace = { enqueue: vi.fn() };
+    const render = { cwd: '/w', provider: {} as never, cliAdapter: {} as never, livePromptTrace } as IRenderOptions;
+    const channel = toChannelOptions(render);
+    expect(channel.livePromptTrace).toBe(livePromptTrace);
+    expect(buildTuiSessionOptions(channel).livePromptTrace).toBe(livePromptTrace);
+  });
+});