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

package/src/__tests__/cjk-text-input.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Tests for CjkTextInput pure utility functions.
+ *
+ * These test the input filtering and insertion logic extracted from
+ * the React component, without requiring Ink/React rendering.
+ */
+
+import { describe, it, expect } from 'vitest';
+import korean from './__fixtures__/korean-text.json';
+import {
+  filterPrintable,
+  insertAtCursor,
+  displayOffset,
+  charIndexAtDisplayOffset,
+} from '../flows/cjk-text-input-flow.js';
+
+describe('filterPrintable', () => {
+  it('returns empty string for null input', () => {
+    expect(filterPrintable(null)).toBe('');
+  });
+
+  it('returns empty string for undefined input', () => {
+    expect(filterPrintable(undefined)).toBe('');
+  });
+
+  it('returns empty string for empty string', () => {
+    expect(filterPrintable('')).toBe('');
+  });
+
+  it('passes through normal ASCII text', () => {
+    expect(filterPrintable('hello')).toBe('hello');
+  });
+
+  it('passes through Korean characters', () => {
+    expect(filterPrintable(korean.greeting)).toBe(korean.greeting);
+  });
+
+  it('passes through emoji', () => {
+    expect(filterPrintable('🎉')).toBe('🎉');
+  });
+
+  it('filters out null byte', () => {
+    expect(filterPrintable('\x00')).toBe('');
+  });
+
+  it('filters out escape character', () => {
+    expect(filterPrintable('\x1b')).toBe('');
+  });
+
+  it('filters out DEL character', () => {
+    expect(filterPrintable('\x7f')).toBe('');
+  });
+
+  it('filters out mixed control characters, keeps printable', () => {
+    expect(filterPrintable('\x01hello\x02world\x7f')).toBe('helloworld');
+  });
+
+  it('returns empty when input is only control characters', () => {
+    expect(filterPrintable('\x00\x01\x02\x03\x1f\x7f')).toBe('');
+  });
+
+  it('handles tab character (0x09) — filtered as control', () => {
+    expect(filterPrintable('\t')).toBe('');
+  });
+
+  it('handles newline (0x0a) — filtered as control', () => {
+    expect(filterPrintable('\n')).toBe('');
+  });
+});
+
+describe('insertAtCursor', () => {
+  it('inserts at the beginning', () => {
+    const result = insertAtCursor('world', 0, 'hello ');
+    expect(result.value).toBe('hello world');
+    expect(result.cursor).toBe(6);
+  });
+
+  it('inserts at the end', () => {
+    const result = insertAtCursor('hello', 5, ' world');
+    expect(result.value).toBe('hello world');
+    expect(result.cursor).toBe(11);
+  });
+
+  it('inserts in the middle', () => {
+    const result = insertAtCursor('helo', 3, 'l');
+    expect(result.value).toBe('hello');
+    expect(result.cursor).toBe(4);
+  });
+
+  it('inserts into empty string', () => {
+    const result = insertAtCursor('', 0, 'abc');
+    expect(result.value).toBe('abc');
+    expect(result.cursor).toBe(3);
+  });
+
+  it('handles multi-character paste', () => {
+    const result = insertAtCursor('ac', 1, 'bb');
+    expect(result.value).toBe('abbc');
+    expect(result.cursor).toBe(3);
+  });
+
+  it('handles Korean character insertion', () => {
+    const result = insertAtCursor(
+      korean.greetingWithoutMiddle,
+      1,
+      korean.greetingMiddleTwoSyllables,
+    );
+    expect(result.value).toBe(korean.greeting);
+    expect(result.cursor).toBe(3);
+  });
+
+  it('handles emoji insertion', () => {
+    const result = insertAtCursor('hello world', 6, '🎉 ');
+    expect(result.value).toBe('hello 🎉 world');
+    expect(result.cursor).toBe(9);
+  });
+});
+
+describe('displayOffset', () => {
+  it('returns 0 for charIndex 0', () => {
+    expect(displayOffset([...'hello'], 0, 10)).toBe(0);
+  });
+
+  it('returns char count for ASCII within one line', () => {
+    expect(displayOffset([...'hello'], 3, 10)).toBe(3);
+  });
+
+  it('accumulates across wrap boundary', () => {
+    // "abcde" width 3: offset at index 4 = 4 (abc on line 0, de on line 1)
+    expect(displayOffset([...'abcde'], 4, 3)).toBe(4);
+  });
+
+  it('cursor before CJK char is at end of previous content', () => {
+    // "abcd" + one wide syllable, width 5: cursor before the syllable is at col 4 on line 0
+    // gap happens when the syllable renders, not at cursor position
+    expect(displayOffset([...`abcd${korean.hanSyllable}`], 4, 5)).toBe(4);
+    // cursor after the syllable: 4(gap included) + 2 = 7 → but via offset: gap is at render
+    expect(displayOffset([...`abcd${korean.hanSyllable}`], 5, 5)).toBe(7);
+  });
+
+  it('handles pure CJK', () => {
+    // two wide syllables, width 5: 2 + 2 → total 4, fits on one line
+    expect(displayOffset([...korean.hangulWord], 2, 5)).toBe(4);
+  });
+
+  it('handles CJK wrapping', () => {
+    // three wide syllables, width 5: cursor before the third is after the second (offset 4)
+    // the third syllable doesn't fit at col 4, but cursor is BEFORE the wrap
+    expect(displayOffset([...korean.hangulWordPlusTe], 2, 5)).toBe(4);
+    // cursor after the third syllable: gap(1) + 2 = offset 7
+    expect(displayOffset([...korean.hangulWordPlusTe], 3, 5)).toBe(7);
+  });
+});
+
+describe('charIndexAtDisplayOffset', () => {
+  it('returns 0 for offset 0', () => {
+    expect(charIndexAtDisplayOffset([...'hello'], 0, 10)).toBe(0);
+  });
+
+  it('finds correct index for ASCII', () => {
+    expect(charIndexAtDisplayOffset([...'hello'], 3, 10)).toBe(3);
+  });
+
+  it('returns text length when offset exceeds text', () => {
+    expect(charIndexAtDisplayOffset([...'hi'], 100, 10)).toBe(2);
+  });
+
+  it('round-trips with displayOffset for ASCII', () => {
+    const text = 'abcdefghij';
+    const chars = [...text];
+    const width = 4;
+    for (let i = 0; i <= chars.length; i++) {
+      const off = displayOffset(chars, i, width);
+      expect(charIndexAtDisplayOffset(chars, off, width)).toBe(i);
+    }
+  });
+
+  it('round-trips with displayOffset for CJK', () => {
+    const text = korean.hangulWordPlusTest;
+    const chars = [...text];
+    const width = 5;
+    for (let i = 0; i <= chars.length; i++) {
+      const off = displayOffset(chars, i, width);
+      expect(charIndexAtDisplayOffset(chars, off, width)).toBe(i);
+    }
+  });
+
+  it('up arrow simulation: offset - width gives previous line position', () => {
+    // "abcdef" width 3: line 0 = "abc", line 1 = "def"
+    // cursor at index 4 (line 1, col 1) → offset = 4
+    // offset - 3 = 1 → charIndex 1 (line 0, col 1)
+    const chars = [...'abcdef'];
+    const off = displayOffset(chars, 4, 3);
+    expect(charIndexAtDisplayOffset(chars, off - 3, 3)).toBe(1);
+  });
+});

package/src/__tests__/command-handoff-pty-e2e.test.ts

@@ -0,0 +1,107 @@
+/**
+ * TEST-007 / TERM-003 + TERM-004: `/shell` and `/editor` through a real terminal handoff, end-to-end
+ * in a PTY. Drives `fixtures/command-handoff-driver.tsx` (real executors + real
+ * `TerminalHandoffController`). Proves on a real TTY that the child (subshell / `$EDITOR`) receives
+ * the driver's keystrokes and the command returns cleanly — the behavior only a PTY can validate
+ * (the session command-pipeline path is covered by the framework functional tests with a fake
+ * handoff).
+ */
+import { mkdtempSync, readFileSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createPtyEnv } from './pty/isolated-home.js';
+import { spawnPtyFixture } from './pty/spawn-pty.js';
+
+import type { IPtyRunSession } from './pty/spawn-pty.js';
+
+const FIXTURE = fileURLToPath(new URL('./fixtures/command-handoff-driver.tsx', import.meta.url));
+const FAKE_EDITOR = fileURLToPath(new URL('./fixtures/fake-editor.sh', import.meta.url));
+const PACKAGE_DIR = fileURLToPath(new URL('../..', import.meta.url));
+const TEST_TIMEOUT_MS = 30_000;
+
+const tempDirs: string[] = [];
+const sessions: IPtyRunSession[] = [];
+
+afterEach(() => {
+  for (const session of sessions.splice(0)) session.dispose();
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+interface IResult {
+  success: boolean;
+  message: string;
+  exitCode?: number;
+}
+
+function readResult(outputPath: string): IResult {
+  return JSON.parse(readFileSync(outputPath, 'utf8')) as IResult;
+}
+
+describe('command handoff PTY E2E', () => {
+  it(
+    '/shell runs a one-shot command on the real terminal and returns its exit code',
+    async () => {
+      const dir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-test-shell-pty-')));
+      tempDirs.push(dir);
+      const outputPath = join(dir, 'result.json');
+      const session = spawnPtyFixture(FIXTURE, {
+        argv: ['shell', outputPath],
+        cwd: PACKAGE_DIR,
+        // HARNESS-025: isolated HOME — the subshell must not read the developer's `~` (a real
+        // shell rc there would otherwise change what the handoff child does).
+        env: createPtyEnv(),
+      });
+      sessions.push(session);
+
+      await session.waitFor('READY canHandoff=true', 10_000);
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await session.sendKeys('shell-input', 10);
+      session.write('\r');
+      await session.waitFor('CMD_DONE', 10_000);
+      session.write('r');
+      await session.waitFor('INPUT_AFTER_HANDOFF r', 10_000);
+      expect(await session.expectExit(5_000)).toBe(0);
+
+      expect(session.snapshot()).toContain('SHELL_GOT:[shell-input]');
+      const result = readResult(outputPath);
+      expect(result.success).toBe(true);
+      expect(result.exitCode).toBe(0);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  it(
+    '/editor opens $EDITOR on the real terminal and round-trips the composed text',
+    async () => {
+      const dir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-test-editor-pty-')));
+      tempDirs.push(dir);
+      const outputPath = join(dir, 'result.json');
+      const session = spawnPtyFixture(FIXTURE, {
+        argv: ['editor', outputPath],
+        cwd: PACKAGE_DIR,
+        // HARNESS-025: isolated HOME — only the EDITOR override comes from the test, so a real
+        // `~/.selected_editor` (or similar) on the host cannot influence the assertion.
+        env: createPtyEnv({ EDITOR: `sh ${FAKE_EDITOR}` }),
+      });
+      sessions.push(session);
+
+      await session.waitFor('READY canHandoff=true', 10_000);
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await session.sendKeys('composed-in-editor', 10);
+      session.write('\r');
+      await session.waitFor('CMD_DONE', 10_000);
+      session.write('r');
+      await session.waitFor('INPUT_AFTER_HANDOFF r', 10_000);
+      expect(await session.expectExit(5_000)).toBe(0);
+
+      const result = readResult(outputPath);
+      expect(result.success).toBe(true);
+      expect(result.message).toBe('composed-in-editor');
+    },
+    TEST_TIMEOUT_MS,
+  );
+});

package/src/__tests__/command-output-summary.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import { formatCommandOutputSummary } from '../command-output-summary.js';
+
+describe('formatCommandOutputSummary', () => {
+  it('renders short command output inline without transcript decoration', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'echo hello',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({ success: true, output: 'hello\n', exitCode: 0 }),
+    });
+
+    expect(summary).toMatchObject({
+      status: 'success',
+      statusLabel: 'ok',
+      previewLines: ['hello'],
+      omittedLineCount: 0,
+      transcriptHint: undefined,
+    });
+  });
+
+  it('renders long command output with a bounded preview and transcript hint', () => {
+    const output = Array.from({ length: 8 }, (_, index) => `line-${index + 1}`).join('\n');
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'pnpm test',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({ success: true, output, exitCode: 0 }),
+    });
+
+    expect(summary?.previewLines).toEqual(['line-1', 'line-2', 'line-3', 'line-4']);
+    expect(summary?.omittedLineCount).toBe(4);
+    expect(summary?.transcriptHint).toBe('... +4 lines (full output in session transcript)');
+  });
+
+  it('keeps stderr distinct when stdout and stderr are structured separately', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'node script.js',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({
+        success: true,
+        stdout: 'ok',
+        stderr: 'warn',
+        exitCode: 0,
+      }),
+    });
+
+    expect(summary?.previewLines).toEqual(['ok', '[stderr] warn']);
+  });
+
+  it('marks non-zero exit codes as failed even when the tool transport succeeded', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'exit 42',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({ success: true, output: '', exitCode: 42 }),
+    });
+
+    expect(summary?.status).toBe('error');
+    expect(summary?.statusLabel).toBe('exit 42');
+    expect(summary?.previewLines).toEqual([]);
+  });
+
+  it('renders no-output commands without dangling transcript hints', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'true',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({ success: true, output: '', exitCode: 0 }),
+    });
+
+    expect(summary?.status).toBe('success');
+    expect(summary?.previewLines).toEqual([]);
+    expect(summary?.omittedLineCount).toBe(0);
+    expect(summary?.transcriptHint).toBeUndefined();
+  });
+
+  it('ignores non-command tools', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Read',
+      firstArg: 'file.ts',
+      isRunning: false,
+      result: 'success',
+      toolResultData: 'large file content',
+    });
+
+    expect(summary).toBeUndefined();
+  });
+});

package/src/__tests__/command-result-handler.test.ts

@@ -0,0 +1,171 @@
+/**
+ * CMD-004 Phase 2: `applySystemCommandResult` is pure rendering. Host actions are applied (and
+ * consumed) by the session, UI intents arrive via the `ui_intent` session event, and state-change
+ * notifications arrive as broadcast session events (`session_renamed`, `history_cleared`). The
+ * only result-carried hint consumed here is `data.pluginRegistryReloaded` — the requester-local
+ * command-registry/autocomplete refresh.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { homedir } from 'node:os';
+import { mkdirSync, mkdtempSync, writeFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { afterEach, vi } from 'vitest';
+import {
+  CommandRegistry,
+  BundlePluginLoader,
+  PluginCommandSource,
+} from '@robota-sdk/agent-framework';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import { TuiStateManager } from '../tui-state-manager.js';
+import { applySystemCommandResult } from '../hooks/command-result-handler.js';
+
+const PLUGIN_SOURCE_NAME = 'plugin';
+
+function reloadPluginCommandSource(registry: CommandRegistry): void {
+  const pluginsDir = join(process.env.HOME ?? homedir(), 'state', 'plugins');
+  const loader = new BundlePluginLoader(pluginsDir);
+  try {
+    // allow-fallback: test helper — empty registry on load error is safe
+    const plugins = loader.loadPluginsSync();
+    if (plugins.length === 0) {
+      registry.replaceSource(PLUGIN_SOURCE_NAME);
+    } else {
+      registry.replaceSource(PLUGIN_SOURCE_NAME, new PluginCommandSource(plugins));
+    }
+  } catch {
+    // allow-fallback: test helper — empty registry on load error is safe
+    registry.replaceSource(PLUGIN_SOURCE_NAME);
+  }
+}
+
+describe('applySystemCommandResult', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  function createSession(): IInteractiveSession {
+    return Object.assign(createTestInteractiveSession(), {
+      getContextState: () => ({ usedPercentage: 0, usedTokens: 0, maxTokens: 0 }),
+    });
+  }
+
+  it('renders the message only — UI intents are delivered via the ui_intent session event', () => {
+    const manager = new TuiStateManager();
+
+    applySystemCommandResult(
+      {
+        success: true,
+        message: 'Opening plugin manager...',
+        uiIntents: [{ type: 'show-plugin-manager' }],
+      },
+      createSession(),
+      new CommandRegistry(),
+      manager,
+    );
+
+    // Pure rendering: the message lands in history; the legacy screen effect does nothing here.
+    expect(manager.history).toHaveLength(1);
+    expect(manager.history[0]?.data).toMatchObject({ content: 'Opening plugin manager...' });
+  });
+
+  it('renders a host-actioned result as message only (host applied it; TUI refreshes on result)', () => {
+    const manager = new TuiStateManager();
+
+    applySystemCommandResult(
+      {
+        success: true,
+        message: 'Status line disabled.',
+      },
+      createSession(),
+      new CommandRegistry(),
+      manager,
+    );
+
+    expect(manager.history).toHaveLength(1);
+    expect(manager.history[0]?.data).toMatchObject({ content: 'Status line disabled.' });
+  });
+
+  it('appends the /clear result message AFTER the broadcast-driven clear (event fired during executeCommand)', () => {
+    const manager = new TuiStateManager();
+    manager.addEntry({
+      id: 'old',
+      timestamp: new Date('2026-05-03T00:00:00.000Z'),
+      category: 'chat',
+      type: 'user',
+      data: { role: 'user', content: 'old message' },
+    });
+
+    // Stage E: the transcript clear itself rides the broadcast `history_cleared` session event
+    // (bound in TuiInteractionChannel and emitted while the command executes — before the result
+    // returns), so by the time this renderer runs the history is already empty.
+    manager.clearHistory();
+    applySystemCommandResult(
+      {
+        success: true,
+        message: 'Conversation cleared.',
+      },
+      createSession(),
+      new CommandRegistry(),
+      manager,
+    );
+
+    expect(manager.history).toHaveLength(1);
+    expect(manager.history[0]?.type).toBe('system');
+    expect(manager.history[0]?.data).toMatchObject({ content: 'Conversation cleared.' });
+  });
+
+  it('reloads plugin command source immediately when requested', () => {
+    const home = realpathSync(mkdtempSync(join(tmpdir(), 'agent-test-plugin-reload-')));
+    const pluginDir = join(
+      home,
+      'state',
+      'plugins',
+      'cache',
+      'community',
+      'fresh-plugin',
+      '1.0.0',
+    );
+    mkdirSync(join(pluginDir, '.claude-plugin'), { recursive: true });
+    mkdirSync(join(pluginDir, 'skills', 'fresh-skill'), { recursive: true });
+    writeFileSync(
+      join(pluginDir, '.claude-plugin', 'plugin.json'),
+      JSON.stringify({
+        name: 'fresh-plugin',
+        version: '1.0.0',
+        description: 'Fresh plugin',
+        features: { skills: true },
+      }),
+      'utf8',
+    );
+    writeFileSync(
+      join(pluginDir, 'skills', 'fresh-skill', 'SKILL.md'),
+      '---\ndescription: Fresh skill\n---\n# Fresh Skill\n',
+      'utf8',
+    );
+    vi.stubEnv('HOME', home);
+    const registry = new CommandRegistry();
+    registry.addSource({
+      name: 'plugin',
+      getCommands: () => [{ name: 'stale-skill', description: 'Stale', source: 'plugin' }],
+    });
+    const manager = new TuiStateManager();
+
+    applySystemCommandResult(
+      {
+        success: true,
+        message: 'Reloaded 1 plugin resource.',
+        data: { pluginRegistryReloaded: true },
+      },
+      createSession(),
+      registry,
+      manager,
+      reloadPluginCommandSource,
+    );
+
+    expect(registry.getCommands().map((command) => command.name)).toEqual(['fresh-skill']);
+  });
+});

package/src/__tests__/compact-event-bridge.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import { TuiStateManager } from '../tui-state-manager.js';
+import { applyCompactEventToManager } from '../hooks/useTuiChannel.js';
+
+describe('compact event bridge', () => {
+  it('syncs session history so automatic compaction notifications render', () => {
+    const manager = new TuiStateManager();
+    const notification = messageToHistoryEntry(
+      createSystemMessage('Auto compacted context: 84% -> 35%'),
+    );
+    const session = {
+      getFullHistory: () => [notification],
+    };
+
+    applyCompactEventToManager(session, manager);
+
+    expect(manager.history).toEqual([notification]);
+  });
+});