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

package/src/__tests__/background-task-panel.test.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { render } from 'ink-testing-library';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+import BackgroundTaskPanel from '../BackgroundTaskPanel.js';
+
+function makeEntry(overrides: Partial<IExecutionWorkspaceEntry>): IExecutionWorkspaceEntry {
+  return {
+    id: 'task:agent_1',
+    sourceId: 'agent_1',
+    kind: 'background_task',
+    origin: { kind: 'slash_command', sessionId: 'session_1', commandName: 'agent' },
+    taskKind: 'agent',
+    status: 'running',
+    state: 'working',
+    title: 'general-purpose',
+    subtitle: 'agent',
+    preview: 'Analyze backlog',
+    unread: false,
+    attention: 'none',
+    visibility: 'default',
+    updatedAt: '2026-05-09T00:00:00.000Z',
+    controls: ['select', 'cancel'],
+    ...overrides,
+  };
+}
+
+describe('BackgroundTaskPanel', () => {
+  it('renders SDK workspace entries with compact markers instead of raw task ids', () => {
+    const { lastFrame } = render(
+      <BackgroundTaskPanel
+        entries={[
+          makeEntry({ id: 'task:agent_1', status: 'running' }),
+          makeEntry({
+            id: 'task:agent_2',
+            status: 'completed',
+            state: 'completed',
+            preview: 'Done',
+          }),
+          makeEntry({
+            id: 'task:agent_3',
+            status: 'failed',
+            state: 'failed',
+            attention: 'failed',
+            preview: 'Timed out',
+          }),
+        ]}
+      />,
+    );
+
+    const frame = lastFrame()!;
+    expect(frame).toContain('Background work');
+    // SCREEN-1992: the state word sits beside the glyph, so a reader hears it and no-color sees it.
+    expect(frame).toContain('├ ⟳ working general-purpose agent');
+    expect(frame).toContain('├ ✓ completed general-purpose agent · completed');
+    expect(frame).toContain('└ ✗ failed general-purpose agent · failed');
+    expect(frame).not.toContain('agent_1');
+    expect(frame).not.toContain('agent_2');
+    expect(frame).not.toContain('agent_3');
+  });
+
+  it('advertises the keyboard drill-in when not focused (SCREEN-013/014)', () => {
+    const { lastFrame } = render(
+      <BackgroundTaskPanel entries={[makeEntry({ id: 'task:agent_1' })]} />,
+    );
+    const frame = lastFrame()!;
+    // Entry affordance: ↓ to select, Ctrl+B for the full switcher.
+    expect(frame).toContain('select');
+    expect(frame).toContain('Ctrl+B');
+  });
+
+  it('shows the move/open affordance when a row is focused (SCREEN-014)', () => {
+    const { lastFrame } = render(
+      <BackgroundTaskPanel
+        entries={[makeEntry({ id: 'task:agent_1' }), makeEntry({ id: 'task:agent_2' })]}
+        focusedIndex={0}
+      />,
+    );
+    const frame = lastFrame()!;
+    expect(frame).toContain('Enter open');
+    expect(frame).toContain('Esc back');
+  });
+
+  it('keeps a long-preview row on a single line (SCREEN-011)', () => {
+    const longPreview =
+      'Read each of the following backlog files and analyze the current status, implementation ' +
+      'difficulty, dependencies, and estimated effort for every item; output a structured summary';
+    const { lastFrame } = render(
+      <BackgroundTaskPanel entries={[makeEntry({ id: 'task:agent_1', preview: longPreview })]} />,
+    );
+    const frame = lastFrame()!;
+    // The row with the connector must be exactly one line — no wrapped continuation line.
+    const rowLines = frame.split('\n').filter((line) => line.includes('⟳'));
+    expect(rowLines).toHaveLength(1);
+    // The connector + glyph still lead the single row line.
+    expect(rowLines[0]).toMatch(/└ ⟳ working general-purpose agent/);
+  });
+});

package/src/__tests__/background-task-row-format.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+import {
+  BACKGROUND_TASK_CONNECTORS,
+  formatBackgroundTaskRow,
+} from '../background-task-row-format.js';
+
+function makeEntry(overrides: Partial<IExecutionWorkspaceEntry>): IExecutionWorkspaceEntry {
+  return {
+    id: 'task:agent_1',
+    sourceId: 'agent_1',
+    kind: 'background_task',
+    origin: { kind: 'slash_command', sessionId: 'session_1', commandName: 'agent' },
+    taskKind: 'agent',
+    status: 'running',
+    state: 'working',
+    title: 'Explore',
+    subtitle: 'general-purpose',
+    preview: 'Analyze backlog',
+    unread: false,
+    attention: 'none',
+    visibility: 'default',
+    updatedAt: '2026-05-09T00:00:00.000Z',
+    controls: ['select', 'cancel'],
+    ...overrides,
+  };
+}
+
+describe('formatBackgroundTaskRow', () => {
+  it('formats running SDK workspace entries without raw task ids', () => {
+    const row = formatBackgroundTaskRow(makeEntry({ id: 'task:agent_1' }), { isLast: true });
+
+    expect(row.connector).toBe('└');
+    expect(row.marker).toBe('⟳'); // running → shared status glyph (SCREEN-005)
+    // marker symbol AND colour come from the same glyph now (SCREEN-007): the running
+    // glyph is yellow, so the row colour is yellow (was cyan via the old view-model rule).
+    expect(row.statusKind).toBe('running');
+    expect(row.label).toBe('Explore agent');
+    expect(row.segments).toEqual(['running', 'agent · general-purpose']);
+    expect(row.preview).toBe('Analyze backlog');
+    expect(row.accessibleText).not.toContain('agent_1');
+  });
+
+  it('formats failed and completed rows from SDK-owned status and attention', () => {
+    const failed = formatBackgroundTaskRow(
+      makeEntry({
+        id: 'task:agent_2',
+        status: 'failed',
+        attention: 'failed',
+        preview: 'Timed out',
+      }),
+      { isLast: false },
+    );
+    const completed = formatBackgroundTaskRow(
+      makeEntry({ id: 'task:agent_3', status: 'completed', preview: 'Summary ready' }),
+    );
+
+    expect(failed.connector).toBe('├');
+    expect(failed.marker).toBe('✗'); // failed → error glyph (SCREEN-005)
+    expect(failed.statusKind).toBe('error');
+    expect(failed.preview).toBe('Timed out');
+    expect(completed.marker).toBe('✓'); // completed → success glyph (SCREEN-005)
+    expect(completed.statusKind).toBe('success');
+    expect(completed.preview).toBe('Summary ready');
+  });
+});
+
+/** CLI-2004: the tree connectors are drawing, and a reader announces them on every row. */
+describe('formatBackgroundTaskRow in screen-reader mode', () => {
+  it('uses the plain connector instead of the box-drawing branch/last glyphs', () => {
+    const branch = formatBackgroundTaskRow(makeEntry({}), { isLast: false, screenReader: true });
+    const last = formatBackgroundTaskRow(makeEntry({}), { isLast: true, screenReader: true });
+
+    expect(branch.connector).toBe(BACKGROUND_TASK_CONNECTORS.plain);
+    expect(last.connector).toBe(BACKGROUND_TASK_CONNECTORS.plain);
+    expect(branch.accessibleText.startsWith(BACKGROUND_TASK_CONNECTORS.plain)).toBe(true);
+  });
+
+  it('keeps the tree connectors outside the mode', () => {
+    expect(formatBackgroundTaskRow(makeEntry({}), { isLast: false }).connector).toBe(
+      BACKGROUND_TASK_CONNECTORS.branch,
+    );
+    expect(formatBackgroundTaskRow(makeEntry({}), { isLast: true }).connector).toBe(
+      BACKGROUND_TASK_CONNECTORS.last,
+    );
+  });
+});
+
+/** SCREEN-1992 TC-07: the state word beside the glyph, the headline and the countdown. */
+describe('formatBackgroundTaskRow state, headline and countdown', () => {
+  const now = new Date('2026-01-01T00:00:00.000Z');
+
+  it('places the state word beside the glyph and carries it in the accessible text', () => {
+    const row = formatBackgroundTaskRow(makeEntry({ status: 'cancelled', state: 'stopped' }), {
+      isLast: true,
+      now,
+    });
+    expect(row.state).toBe('stopped');
+    expect(row.accessibleText.startsWith('└ ⊗ stopped Explore agent')).toBe(true);
+  });
+
+  it('adds the headline only when it says more than the preview, marking a question', () => {
+    const same = formatBackgroundTaskRow(
+      makeEntry({ headline: { kind: 'activity', text: 'Analyze backlog' } }),
+      { now },
+    );
+    expect(same.headline).toBeUndefined();
+    const question = formatBackgroundTaskRow(
+      makeEntry({
+        status: 'waiting_permission',
+        state: 'needs-input',
+        attention: 'permission',
+        headline: { kind: 'question', text: 'Allow Bash?' },
+      }),
+      { now },
+    );
+    expect(question.headline).toBe('? Allow Bash?');
+    expect(question.accessibleText).toContain('needs-input');
+    expect(question.accessibleText).toContain('? Allow Bash?');
+  });
+
+  it('renders a countdown against the given clock for a sleeping schedule only', () => {
+    const sleeping = formatBackgroundTaskRow(
+      makeEntry({
+        taskKind: 'scheduled',
+        status: 'sleeping',
+        state: 'working',
+        nextFireAt: '2026-01-01T00:04:59.000Z',
+      }),
+      { now },
+    );
+    expect(sleeping.countdown).toBe('in 4m 59s');
+    expect(sleeping.accessibleText.endsWith('in 4m 59s')).toBe(true);
+    expect(formatBackgroundTaskRow(makeEntry({}), { now }).countdown).toBeUndefined();
+  });
+});
+
+describe('formatBackgroundTaskRow headline dedup against the subtitle (PR #2749 review)', () => {
+  it('drops a headline the subtitle already carries, such as a wake instruction', () => {
+    const row = formatBackgroundTaskRow(
+      makeEntry({
+        taskKind: 'scheduled',
+        status: 'sleeping',
+        subtitle: '↻ wake "say hello"',
+        preview: undefined,
+        headline: { kind: 'activity', text: 'say hello' },
+      }),
+      { now: new Date('2026-01-01T00:00:00.000Z') },
+    );
+    expect(row.headline).toBeUndefined();
+  });
+});

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(), 'robota-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, '.robota', '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, '.robota', '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__/cjk-defer-submit.test.tsx

@@ -0,0 +1,67 @@
+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';
+
+/**
+ * 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 (안녕하세 + Enter + 요 → 안녕하세요)', async () => {
+    const onSubmit = vi.fn();
+    const { stdin } = render(<Harness onSubmit={onSubmit} />);
+    await tick();
+
+    stdin.write('안녕하세'); // 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('요'); // 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('안녕하세요');
+  }, 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,78 @@
+/**
+ * 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 ROBOTA_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';
+
+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['ROBOTA_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="안녕하세요" onChange={noop} />);
+    await tick();
+    expect(lastFrame()).toBe('안녕하세요\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) + '안녕'} onChange={noop} availableWidth={58} />,
+    );
+    await tick();
+    expect(lastFrame()).toBe('a'.repeat(100) + '\n' + 'a'.repeat(50) + '안녕\u001b[7m \u001b[27m');
+    unmount();
+  });
+});