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

package/src/__tests__/channel-factory-integration.test.ts

@@ -0,0 +1,150 @@
+/**
+ * CLI-B11 TC-02: real-store channel factory integration.
+ *
+ * The official CI equivalent of real-resume-verify-v3.mjs: build the channel
+ * exactly the way render.tsx does (toChannelOptions + TuiInteractionChannel)
+ * over a REAL project session store with a persisted conversation, and assert
+ * the restored model context is non-empty. No store/session mocks.
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createNodeHostSessionStore } from '@robota-sdk/agent-framework';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createScriptedProvider } from '@robota-sdk/agent-core/testing';
+import { toChannelOptions, type IRenderOptions } from '../render.js';
+import { TuiInteractionChannel } from '../TuiInteractionChannel.js';
+
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+const RESTORE_DEADLINE_MS = 10_000;
+const POLL_MS = 50;
+
+function fakeCliAdapter(settingsPath: string): ITuiCliAdapter {
+  return {
+    getUserSettingsPath: () => settingsPath,
+    readSettings: () => ({}),
+    reloadPluginCommandSource: vi.fn(),
+    applyActiveModelChange: vi.fn().mockReturnValue({ applied: true }),
+    getGitBranch: vi.fn().mockReturnValue(undefined),
+    getProviderDisplayName: vi.fn((type: string) => type),
+  };
+}
+
+function persistConversation(store: IInteractiveSessionStore, id: string, cwd: string): void {
+  // TRANS-007: the store decodes on load, so a message must satisfy the contract. These were cast
+  // stubs with only `role` and `content`; the store accepted them because it never looked.
+  const at = new Date('2026-06-13T00:00:00.000Z');
+  const messages: TUniversalMessage[] = [
+    {
+      id: 'm-0',
+      role: 'user',
+      content: 'Remember the number 42.',
+      timestamp: at,
+      state: 'complete',
+    },
+    { id: 'm-1', role: 'assistant', content: 'Noted: 42.', timestamp: at, state: 'complete' },
+    {
+      id: 'm-2',
+      role: 'user',
+      content: 'And the city is Busan.',
+      timestamp: at,
+      state: 'complete',
+    },
+    { id: 'm-3', role: 'assistant', content: 'Noted: Busan.', timestamp: at, state: 'complete' },
+  ];
+  store.save({
+    id,
+    cwd,
+    createdAt: '2026-06-13T00:00:00.000Z',
+    updatedAt: '2026-06-13T00:00:00.000Z',
+    messages,
+  });
+}
+
+describe('channel factory restores persisted context (CLI-B11 TC-02)', () => {
+  let cwd: string;
+  let channel: TuiInteractionChannel | undefined;
+
+  beforeEach(() => {
+    cwd = realpathSync(mkdtempSync(join(tmpdir(), 'agent-test-b11-int-')));
+  });
+
+  afterEach(async () => {
+    await channel?.stop();
+    channel = undefined;
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  it('createChannel(sessionId) over a real FileSessionStore yields usedTokens > 0', async () => {
+    const store = createNodeHostSessionStore(join(cwd, 'state', 'sessions'));
+    const sessionId = 'b11-restore-session';
+    persistConversation(store, sessionId, cwd);
+
+    // Exactly the render.tsx factory: toChannelOptions(options, resumeSessionId).
+    const scripted = createScriptedProvider([{ text: 'unused in this test' }]);
+    const options: IRenderOptions = {
+      cwd,
+      provider: scripted.provider,
+      sessionStore: store,
+      cliAdapter: fakeCliAdapter(join(cwd, 'settings.json')),
+    };
+    channel = new TuiInteractionChannel(toChannelOptions(options, sessionId));
+    await channel.start();
+
+    // Restoration is asynchronous (pendingRestoreMessages inject after init).
+    const deadline = Date.now() + RESTORE_DEADLINE_MS;
+    let usedTokens = 0;
+    while (Date.now() < deadline) {
+      try {
+        // allow-fallback: session init is asynchronous; poll until it is ready
+        usedTokens = channel.getSession().getContextState().usedTokens;
+        if (usedTokens > 0) break;
+      } catch {
+        // allow-fallback: session init is asynchronous; poll until it is ready
+      }
+      await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+
+    // The persisted messages were injected into the model context — the exact
+    // signal that was 0 in the 2026-05-31 bug. (getFullHistory() is the display
+    // log restored from record.history, which this record intentionally omits.)
+    expect(usedTokens).toBeGreaterThan(0);
+  });
+
+  it('a channel created WITHOUT resumeSessionId starts with an empty context (control)', async () => {
+    const store = createNodeHostSessionStore(join(cwd, 'state', 'sessions'));
+    persistConversation(store, 'b11-other-session', cwd);
+
+    const scripted = createScriptedProvider([{ text: 'unused' }]);
+    const options: IRenderOptions = {
+      cwd,
+      provider: scripted.provider,
+      sessionStore: store,
+      cliAdapter: fakeCliAdapter(join(cwd, 'settings.json')),
+    };
+    channel = new TuiInteractionChannel(toChannelOptions(options, undefined));
+    await channel.start();
+
+    const deadline = Date.now() + RESTORE_DEADLINE_MS;
+    let ready = false;
+    while (Date.now() < deadline && !ready) {
+      try {
+        // allow-fallback: session init is asynchronous; poll until it is ready
+        channel.getSession().getContextState();
+        ready = true;
+      } catch {
+        // allow-fallback: session init is asynchronous; poll until it is ready
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+      }
+    }
+
+    expect(ready).toBe(true);
+    expect(channel.getSession().getFullHistory()).toHaveLength(0);
+  });
+});

package/src/__tests__/checkpoint-store-per-channel.test.ts

@@ -0,0 +1,81 @@
+/**
+ * #3231: the TUI builds a new channel on every session switch, and it may do so before the old
+ * session's turn has ended. A checkpoint store holds one turn in progress, so a store shared across
+ * channels would let the old turn close the new session's turn. Each channel gets its own.
+ */
+
+import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createScriptedProvider } from '@robota-sdk/agent-core/testing';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createInProcessChannelFactory } from '../render.js';
+import { TerminalHandoffController } from '../terminal-handoff-controller.js';
+
+import type { IChannelServices, IRenderOptions } from '../render.js';
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { ITuiAppChannelPort } from '../tui-app-channel-port.js';
+import type { EditCheckpointStore } from '@robota-sdk/agent-framework';
+
+const sessionStores = vi.hoisted(() => [] as unknown[]);
+
+vi.mock('../tui-session-options.js', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../tui-session-options.js')>();
+  return {
+    buildTuiSessionOptions: (
+      ...args: Parameters<typeof original.buildTuiSessionOptions>
+    ): ReturnType<typeof original.buildTuiSessionOptions> => {
+      const built = original.buildTuiSessionOptions(...args);
+      sessionStores.push(built.editCheckpointStore);
+      return built;
+    },
+  };
+});
+
+function fakeCliAdapter(settingsPath: string): ITuiCliAdapter {
+  return {
+    getUserSettingsPath: () => settingsPath,
+    readSettings: () => ({}),
+    reloadPluginCommandSource: vi.fn(),
+    applyActiveModelChange: vi.fn().mockReturnValue({ applied: true }),
+    getGitBranch: vi.fn().mockReturnValue(undefined),
+    getProviderDisplayName: vi.fn((type: string) => type),
+  };
+}
+
+describe('#3231: the in-process channel factory', () => {
+  const channels: ITuiAppChannelPort[] = [];
+  let cwd: string | undefined;
+
+  afterEach(async () => {
+    for (const channel of channels.splice(0)) await channel.stop();
+    sessionStores.splice(0);
+    if (cwd !== undefined) rmSync(cwd, { recursive: true, force: true });
+    cwd = undefined;
+  });
+
+  it('gives each channel, including a switched-to one, its own checkpoint store', () => {
+    cwd = realpathSync(mkdtempSync(join(tmpdir(), 'agent-test-store-per-channel-')));
+    const createEditCheckpointStore = vi.fn(() => ({}) as EditCheckpointStore);
+    const options: IRenderOptions = {
+      cwd,
+      provider: createScriptedProvider([{ text: 'unused' }]).provider,
+      cliAdapter: fakeCliAdapter(join(cwd, 'settings.json')),
+      createEditCheckpointStore,
+    };
+    const services = {
+      terminalHandoff: new TerminalHandoffController(),
+    } as unknown as IChannelServices;
+    const createChannel = createInProcessChannelFactory(options, services);
+
+    channels.push(createChannel(), createChannel('switched-to-session'));
+
+    expect(createEditCheckpointStore).toHaveBeenCalledTimes(2);
+    expect(sessionStores).toHaveLength(2);
+    expect(sessionStores[0]).toBeDefined();
+    expect(sessionStores[1]).toBeDefined();
+    expect(sessionStores[0]).not.toBe(sessionStores[1]);
+  });
+});

package/src/__tests__/cjk-defer-submit.test.tsx

@@ -0,0 +1,68 @@
+import { render } from 'ink-testing-library';
+import React, { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import CjkTextInput from '../CjkTextInput.js';
+import { IME_SUBMIT_DEFER_MS } from '../flows/defer-submit.js';
+import korean from './__fixtures__/korean-text.json';
+
+/**
+ * CLI-061 — integration proof that the CjkTextInput defer-submit includes a trailing IME character whose stdin
+ * event arrives JUST AFTER Enter. This exercises the real handler + stateRef + defer wiring (not the pure
+ * reducer, which by construction only sees the value captured at Enter and would be accidental-green).
+ *
+ * Real timers + a real wait > IME_SUBMIT_DEFER_MS so the deferred submit actually fires (fake timers conflict
+ * with Ink's own render scheduling).
+ *
+ * That wait is DERIVED from the constant rather than written next to a comment quoting it. Before, this file
+ * waited a hard-coded 90ms and said `// > 50ms defer` in prose — so raising IME_SUBMIT_DEFER_MS past 90 would
+ * have left the test waiting less than the defer it exists to outlast, and the comment asserting otherwise.
+ * The constant was also, by that arrangement, exported and named by nothing but a comment.
+ */
+const tick = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
+const DEFER_WAIT_MARGIN_MS = 40;
+const waitDefer = (): Promise<void> =>
+  new Promise((r) => setTimeout(r, IME_SUBMIT_DEFER_MS + DEFER_WAIT_MARGIN_MS));
+
+function Harness({ onSubmit }: { onSubmit: (value: string) => void }): React.ReactElement {
+  const [value, setValue] = useState('');
+  return <CjkTextInput value={value} onChange={setValue} onSubmit={onSubmit} focus />;
+}
+
+describe('CLI-061 — CjkTextInput defer-submit (integration)', () => {
+  it('includes a trailing syllable that arrives after Enter (greeting without its last syllable + Enter + last syllable → full greeting)', async () => {
+    const onSubmit = vi.fn();
+    const { stdin } = render(<Harness onSubmit={onSubmit} />);
+    await tick();
+
+    stdin.write(korean.greetingWithoutLastSyllable); // composed so far
+    await tick();
+    stdin.write('\r'); // Enter — schedules the deferred submit, does NOT submit synchronously
+    await tick();
+    expect(onSubmit).not.toHaveBeenCalled(); // deferred, not immediate
+
+    stdin.write(korean.greetingLastSyllable); // the final syllable's stdin event lands after Enter; the pipeline is still live
+    await tick();
+
+    await waitDefer(); // the defer window elapses → the deferred submit fires, re-reading the LATEST value
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith(korean.greeting);
+  }, 10_000);
+
+  it('a second Enter within the window does not double-submit', async () => {
+    const onSubmit = vi.fn();
+    const { stdin } = render(<Harness onSubmit={onSubmit} />);
+    await tick();
+
+    stdin.write('hi');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    stdin.write('\r'); // second Enter within the defer window
+    await tick();
+
+    await waitDefer();
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith('hi');
+  }, 10_000);
+});

package/src/__tests__/cjk-fallback-render.test.tsx

@@ -0,0 +1,89 @@
+/**
+ * CLI-062 — fallback-path pinning guard.
+ *
+ * When real-cursor positioning is NOT active (capability off — the default in this test process:
+ * stdout is not a TTY and PRODUCT_IME_CURSOR is unset), CjkTextInput's rendering must stay
+ * byte-identical to the pre-CLI-062 behavior (invariant I4: guard fail → today's visuals, drawn
+ * inverse cursor included). The expected strings below are literal captures of the component's
+ * output BEFORE the CLI-062 change (chalk.level forced to 3 so the inverse-cursor bytes are pinned,
+ * not stripped). If this test breaks, the `<Box ref>` wrapper or the drawn-cursor gating changed
+ * the fallback rendering — that is a regression, not a snapshot to refresh.
+ */
+
+import chalk from 'chalk';
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import CjkTextInput from '../CjkTextInput.js';
+import korean from './__fixtures__/korean-text.json';
+
+const noop = (): void => {};
+const tick = (): Promise<void> => new Promise((r) => setTimeout(r, 30));
+
+const ORIGINAL_CHALK_LEVEL = chalk.level;
+
+describe('CLI-062 — fallback rendering is byte-identical to pre-change output', () => {
+  beforeAll(() => {
+    chalk.level = 3;
+  });
+  afterAll(() => {
+    chalk.level = ORIGINAL_CHALK_LEVEL;
+  });
+
+  it('sanity: capability is off in this test process (fallback path is the one being pinned)', () => {
+    expect(process.env['PRODUCT_IME_CURSOR']).toBeUndefined();
+    expect(Boolean(process.stdout.isTTY)).toBe(false);
+  });
+
+  it('ASCII value with drawn end-of-line cursor', async () => {
+    const { lastFrame, unmount } = render(<CjkTextInput value="hello" onChange={noop} />);
+    await tick();
+    expect(lastFrame()).toBe('hello\u001b[7m \u001b[27m');
+    unmount();
+  });
+
+  it('CJK value with drawn end-of-line cursor', async () => {
+    const { lastFrame, unmount } = render(<CjkTextInput value={korean.greeting} onChange={noop} />);
+    await tick();
+    expect(lastFrame()).toBe(`${korean.greeting}\u001b[7m \u001b[27m`);
+    unmount();
+  });
+
+  it('empty value renders placeholder with inverse first character', async () => {
+    const { lastFrame, unmount } = render(
+      <CjkTextInput value="" onChange={noop} placeholder="Type a message or /help" />,
+    );
+    await tick();
+    expect(lastFrame()).toBe('\u001b[7mT\u001b[27m\u001b[90mype a message or /help\u001b[39m');
+    unmount();
+  });
+
+  it('unfocused input renders plain text without a drawn cursor', async () => {
+    const { lastFrame, unmount } = render(
+      <CjkTextInput value="hello" onChange={noop} focus={false} />,
+    );
+    await tick();
+    expect(lastFrame()).toBe('hello');
+    unmount();
+  });
+
+  it('long value wraps identically (the <Box ref> wrapper must not change layout)', async () => {
+    const { lastFrame, unmount } = render(
+      <CjkTextInput
+        value={'a'.repeat(150) + korean.greetingFirstTwoSyllables}
+        onChange={noop}
+        availableWidth={58}
+      />,
+    );
+    await tick();
+    expect(lastFrame()).toBe(
+      'a'.repeat(100) +
+        '\n' +
+        'a'.repeat(50) +
+        korean.greetingFirstTwoSyllables +
+        '\u001b[7m \u001b[27m',
+    );
+    unmount();
+  });
+});

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

@@ -0,0 +1,187 @@
+import { describe, expect, it } from 'vitest';
+import korean from './__fixtures__/korean-text.json';
+import {
+  applyCjkTextInput,
+  applyCjkTextPaste,
+  createCjkTextInputFlowState,
+  syncCjkTextInputFlowState,
+} from '../flows/cjk-text-input-flow.js';
+
+describe('cjk text input flow', () => {
+  it('Given printable input When applied Then value changes at cursor', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('ab'),
+      'c',
+      {},
+      { canPaste: true },
+    );
+
+    expect(result.state).toMatchObject({ value: 'abc', cursor: 3 });
+    expect(result.effect).toEqual({ type: 'change', value: 'abc' });
+  });
+
+  it('Given cursor in middle When backspace is applied Then previous char is removed', () => {
+    const state = { ...createCjkTextInputFlowState('abc'), cursor: 2 };
+
+    const result = applyCjkTextInput(state, '', { backspace: true }, { canPaste: true });
+
+    expect(result.state).toMatchObject({ value: 'ac', cursor: 1 });
+    expect(result.effect).toEqual({ type: 'change', value: 'ac' });
+  });
+
+  it('Given return key When applied Then submit effect contains current value', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('hello'),
+      '',
+      { return: true },
+      { canPaste: true },
+    );
+
+    expect(result.effect).toEqual({ type: 'submit', value: 'hello' });
+  });
+
+  it('Given multiline fallback paste When applied Then paste effect is emitted', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState(''),
+      'a\nb',
+      {},
+      { canPaste: true },
+    );
+
+    expect(result.effect).toEqual({ type: 'paste', text: 'a\nb', cursor: 0 });
+  });
+
+  it('Given Ink usePaste single-line text When applied Then text is inserted at cursor', () => {
+    const state = { ...createCjkTextInputFlowState('ab'), cursor: 1 };
+
+    const result = applyCjkTextPaste(state, korean.hangulWord, { canPaste: true });
+
+    expect(result.state).toMatchObject({ value: `a${korean.hangulWord}b`, cursor: 3 });
+    expect(result.effect).toEqual({ type: 'change', value: `a${korean.hangulWord}b` });
+  });
+
+  it('Given Ink usePaste multiline text When applied Then normalized paste effect is emitted', () => {
+    const state = { ...createCjkTextInputFlowState('ab'), cursor: 1 };
+
+    const result = applyCjkTextPaste(state, 'x\r\ny\rz', { canPaste: true });
+
+    expect(result.state).toBe(state);
+    expect(result.effect).toEqual({ type: 'paste', text: 'x\ny\nz', cursor: 1 });
+  });
+
+  it('Given bracketed multiline paste When end marker arrives Then buffered paste is emitted', () => {
+    const started = applyCjkTextInput(
+      createCjkTextInputFlowState('x'),
+      '[200~hello',
+      {},
+      { canPaste: true },
+    ).state;
+    const result = applyCjkTextInput(started, '\nworld[201~', {}, { canPaste: true });
+
+    expect(result.effect).toEqual({ type: 'paste', text: 'hello\nworld', cursor: 1 });
+    expect(result.state.isPasting).toBe(false);
+  });
+
+  it('Given external value update When synced Then cursor hint is honored', () => {
+    const state = createCjkTextInputFlowState('abc');
+
+    const result = syncCjkTextInputFlowState(state, 'a[Pasted]bc', 9);
+
+    expect(result).toMatchObject({ value: 'a[Pasted]bc', cursor: 9 });
+  });
+
+  it('Given vertical navigation disabled When up arrow is applied Then cursor is unchanged', () => {
+    const state = { ...createCjkTextInputFlowState('abcdef'), cursor: 5 };
+
+    const result = applyCjkTextInput(
+      state,
+      '',
+      { upArrow: true },
+      {
+        canPaste: true,
+        enableVerticalNavigation: false,
+        availableWidth: 2,
+      },
+    );
+
+    expect(result.state).toBe(state);
+    expect(result.effect).toEqual({ type: 'none' });
+  });
+});
+
+/**
+ * CLI-2004 — `Ctrl+W` and `Ctrl+U` are NEW BINDINGS, and they are unconditional.
+ *
+ * Ink reports `Ctrl+W` as `input: 'w'` with `ctrl: true`, so before this change the keystroke fell
+ * through to the printable path and typed a literal `w` into the buffer. That is a defect on the
+ * default path, not only in screen-reader mode, so the fix is not gated on the mode — which makes it
+ * a change to today's behaviour, and these cases are where that change is pinned. What the mode adds
+ * is only the announcement, which is `InputArea`'s to render from `deleted` / `deletedScope`.
+ */
+describe('CLI-2004 — word and line deletion are default bindings, not mode-gated ones', () => {
+  it('Given Ctrl+W When applied Then the word before the cursor is deleted, not a "w" typed', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('hello world'),
+      'w',
+      { ctrl: true },
+      { canPaste: true },
+    );
+
+    expect(result.state).toMatchObject({ value: 'hello ', cursor: 6 });
+    expect(result.effect).toEqual({
+      type: 'change',
+      value: 'hello ',
+      deleted: 'world',
+      deletedScope: 'word',
+    });
+  });
+
+  it('Given Ctrl+W with trailing spaces Then the spaces go with the word, as every shell does', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('one two   '),
+      'w',
+      { ctrl: true },
+      { canPaste: true },
+    );
+
+    expect(result.state.value).toBe('one ');
+    expect(result.effect).toMatchObject({ deleted: 'two   ', deletedScope: 'word' });
+  });
+
+  it('Given Ctrl+U When applied Then everything before the cursor is deleted', () => {
+    const state = { ...createCjkTextInputFlowState('abc def'), cursor: 4 };
+
+    const result = applyCjkTextInput(state, 'u', { ctrl: true }, { canPaste: true });
+
+    expect(result.state).toMatchObject({ value: 'def', cursor: 0 });
+    expect(result.effect).toEqual({
+      type: 'change',
+      value: 'def',
+      deleted: 'abc ',
+      deletedScope: 'line',
+    });
+  });
+
+  it('Given a plain "w" with no ctrl Then it is still typed', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('ne'),
+      'w',
+      {},
+      { canPaste: true },
+    );
+
+    expect(result.state.value).toBe('new');
+    expect(result.effect).toEqual({ type: 'change', value: 'new' });
+  });
+
+  it('Given the cursor at the start Then either deletion is a no-op rather than an empty change', () => {
+    const state = createCjkTextInputFlowState('');
+
+    expect(applyCjkTextInput(state, 'w', { ctrl: true }, { canPaste: true }).effect).toEqual({
+      type: 'none',
+    });
+    expect(applyCjkTextInput(state, 'u', { ctrl: true }, { canPaste: true }).effect).toEqual({
+      type: 'none',
+    });
+  });
+});