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

package/src/__tests__/attention-bell-and-marks.test.ts

@@ -0,0 +1,144 @@
+/**
+ * CLI-2004 TC-08 / TC-09 — the two writers that reach the terminal outside Ink.
+ *
+ * Both are asserted against the exact BYTES, because that is the only channel a screen reader has:
+ * there is no `aria-live` in a terminal, so what a reader gets is what lands in the buffer.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BELL, createAttentionBell, LONG_TOOL_BELL_MS } from '../attention-bell.js';
+import { supportsTurnMarks } from '../terminal-capabilities.js';
+import { createTurnMarkWriter, turnMarkSequence } from '../terminal-marks.js';
+
+function collector(): { written: string[]; write: (text: string) => void } {
+  const written: string[] = [];
+  return { written, write: (text: string): void => void written.push(text) };
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe('TC-08: the attention bell', () => {
+  it('emits exactly one BEL on reply completion', () => {
+    const sink = collector();
+    createAttentionBell({ enabled: true, write: sink.write }).replyCompleted();
+    expect(sink.written).toEqual([BELL]);
+  });
+
+  it('emits exactly one BEL when a prompt mounts', () => {
+    const sink = collector();
+    createAttentionBell({ enabled: true, write: sink.write }).promptMounted();
+    expect(sink.written).toEqual([BELL]);
+  });
+
+  it('rings for a tool that outlived LONG_TOOL_BELL_MS', () => {
+    const sink = collector();
+    let now = 0;
+    const bell = createAttentionBell({ enabled: true, write: sink.write, now: () => now });
+    bell.toolStarted('Bash#0');
+    now = LONG_TOOL_BELL_MS + 1;
+    bell.toolCompleted('Bash#0');
+    expect(sink.written).toEqual([BELL]);
+  });
+
+  it('stays silent for a tool that finished under the threshold', () => {
+    const sink = collector();
+    let now = 0;
+    const bell = createAttentionBell({ enabled: true, write: sink.write, now: () => now });
+    bell.toolStarted('Bash#0');
+    now = LONG_TOOL_BELL_MS;
+    bell.toolCompleted('Bash#0');
+    expect(sink.written).toEqual([]);
+  });
+
+  it('stays silent for a completion whose start was never recorded', () => {
+    const sink = collector();
+    const bell = createAttentionBell({ enabled: true, write: sink.write });
+    bell.toolCompleted('Bash#0');
+    expect(sink.written).toEqual([]);
+  });
+
+  it('writes nothing at all when the mode is off', () => {
+    const sink = collector();
+    let now = 0;
+    const bell = createAttentionBell({ enabled: false, write: sink.write, now: () => now });
+    bell.replyCompleted();
+    bell.promptMounted();
+    bell.toolStarted('Bash#0');
+    now = LONG_TOOL_BELL_MS * 10;
+    bell.toolCompleted('Bash#0');
+    expect(sink.written).toEqual([]);
+  });
+});
+
+describe('TC-09: the OSC 133 turn marks', () => {
+  const A = '\x1b]133;A\x07';
+  const B = '\x1b]133;B\x07';
+  const C = '\x1b]133;C\x07';
+  const D = '\x1b]133;D\x07';
+
+  it('emits A, B, C, D in that order across one turn', () => {
+    const sink = collector();
+    const marks = createTurnMarkWriter({ enabled: true, supported: () => true, write: sink.write });
+    marks.emit('promptStart');
+    marks.emit('promptEnd');
+    marks.emit('turnStart');
+    marks.emit('turnEnd');
+    expect(sink.written).toEqual([A, B, C, D]);
+  });
+
+  it('spells each mark exactly', () => {
+    expect(turnMarkSequence('promptStart')).toBe(A);
+    expect(turnMarkSequence('promptEnd')).toBe(B);
+    expect(turnMarkSequence('turnStart')).toBe(C);
+    expect(turnMarkSequence('turnEnd')).toBe(D);
+  });
+
+  it('emits nothing when the mode is off', () => {
+    const sink = collector();
+    const marks = createTurnMarkWriter({
+      enabled: false,
+      supported: () => true,
+      write: sink.write,
+    });
+    marks.emit('promptStart');
+    marks.emit('turnEnd');
+    expect(sink.written).toEqual([]);
+  });
+
+  it('emits nothing when supportsTurnMarks() is false', () => {
+    const sink = collector();
+    const marks = createTurnMarkWriter({
+      enabled: true,
+      supported: () => false,
+      write: sink.write,
+    });
+    marks.emit('promptStart');
+    marks.emit('turnEnd');
+    expect(sink.written).toEqual([]);
+  });
+});
+
+describe('supportsTurnMarks — the documented negatives', () => {
+  it('is off in WezTerm, which owns OSC 133 itself', () => {
+    vi.stubEnv('PRODUCT_TURN_MARKS', '');
+    vi.stubEnv('TERM_PROGRAM', 'WezTerm');
+    expect(supportsTurnMarks()).toBe(false);
+  });
+
+  it('honours the explicit opt-in and the kill switch over everything else', () => {
+    vi.stubEnv('TERM_PROGRAM', 'WezTerm');
+    vi.stubEnv('PRODUCT_TURN_MARKS', '1');
+    expect(supportsTurnMarks({ override: true })).toBe(true);
+    vi.stubEnv('PRODUCT_TURN_MARKS', '0');
+    expect(supportsTurnMarks({ override: false })).toBe(false);
+  });
+
+  it('ignores an ambient Fixture Agent override without a host choice', () => {
+    vi.stubEnv('TERM_PROGRAM', 'WezTerm');
+    vi.stubEnv('PRODUCT_TURN_MARKS', '1');
+    expect(supportsTurnMarks()).toBe(false);
+  });
+});

package/src/__tests__/autocomplete-editing-keys.test.tsx

@@ -0,0 +1,127 @@
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, expect, it, vi } from 'vitest';
+
+import InputArea from '../InputArea.js';
+import { KeybindingsProvider } from '../keybindings/keybindings-context.js';
+import { parseKeybindingsDocument } from '../keybindings/keybinding-registry.js';
+
+import type { IKeybindingsSource } from '../keybindings/node-keybindings-source.js';
+import type { ITuiCommandQueryPort } from '../tui-app-channel-port.js';
+
+async function tick(ms = 25): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+const commandQueryPort: ITuiCommandQueryPort = {
+  getCommands: (filter) =>
+    [
+      { name: 'help', description: 'Show help', source: 'test' },
+      { name: 'permissions', description: 'Permissions', source: 'test' },
+    ].filter((command) => command.name.startsWith(filter ?? '')),
+  getSubcommands: (parent) =>
+    parent === 'permissions'
+      ? [{ name: 'retry', description: 'Retry a denial', source: 'test' }]
+      : [],
+};
+
+describe('InputArea editing keys while the slash autocomplete is open', () => {
+  it('deletes with backspace', async () => {
+    const { stdin, lastFrame } = render(
+      <InputArea onSubmit={vi.fn()} isDisabled={false} commandQueryPort={commandQueryPort} />,
+    );
+    await tick();
+    stdin.write('/per');
+    await tick();
+    expect(lastFrame()).toContain('permissions');
+
+    stdin.write('\x7f');
+    await tick();
+    expect(lastFrame()).toMatch(/> \/pe$/m);
+
+    stdin.write('\x7f\x7f\x7f');
+    await tick();
+    expect(lastFrame()).toContain('Type a message or /help');
+  });
+
+  it('deletes back out of a tab-completed command whose subcommands stay listed', async () => {
+    const { stdin, lastFrame } = render(
+      <InputArea onSubmit={vi.fn()} isDisabled={false} commandQueryPort={commandQueryPort} />,
+    );
+    await tick();
+    stdin.write('/per');
+    await tick();
+    stdin.write('\t');
+    await tick();
+    expect(lastFrame()).toContain('> /permissions');
+    expect(lastFrame()).toContain('retry');
+
+    stdin.write('\x7f\x7f');
+    await tick();
+    expect(lastFrame()).toMatch(/> \/permission$/m);
+    expect(lastFrame()).not.toContain('retry');
+  });
+
+  it('clears the line with ctrl+u', async () => {
+    const { stdin, lastFrame } = render(
+      <InputArea onSubmit={vi.fn()} isDisabled={false} commandQueryPort={commandQueryPort} />,
+    );
+    await tick();
+    stdin.write('/he');
+    await tick();
+    expect(lastFrame()).toContain('help');
+
+    stdin.write('\x15');
+    await tick();
+    expect(lastFrame()).toContain('Type a message or /help');
+  });
+
+  it('moves the cursor with the arrow keys so an insertion lands mid-word', async () => {
+    const { stdin, lastFrame } = render(
+      <InputArea onSubmit={vi.fn()} isDisabled={false} commandQueryPort={commandQueryPort} />,
+    );
+    await tick();
+    stdin.write('/pe');
+    await tick();
+    expect(lastFrame()).toContain('permissions');
+    stdin.write('\x1b[D');
+    await tick();
+    stdin.write('r');
+    await tick();
+    expect(lastFrame()).toMatch(/> \/pre$/m);
+  });
+
+  it("follows the user's chat-input bindings, not the defaults", async () => {
+    const parsed = parseKeybindingsDocument(
+      JSON.stringify({ version: 1, bindings: { 'chat-input': { 'delete-line': 'ctrl+k' } } }),
+      '/tmp/keybindings.json',
+    );
+    if (!parsed.ok) throw new Error(parsed.diagnostic.message);
+    const source: IKeybindingsSource = {
+      filePath: '/tmp/keybindings.json',
+      start: async () => undefined,
+      isStarted: () => true,
+      ensureFile: async () => '/tmp/keybindings.json',
+      getSnapshot: () => parsed.snapshot,
+      subscribe: () => () => undefined,
+      dispose: () => undefined,
+    };
+    const { stdin, lastFrame } = render(
+      <KeybindingsProvider source={source}>
+        <InputArea onSubmit={vi.fn()} isDisabled={false} commandQueryPort={commandQueryPort} />
+      </KeybindingsProvider>,
+    );
+    await tick();
+    stdin.write('/he');
+    await tick();
+    expect(lastFrame()).toContain('help');
+
+    stdin.write('\x15'); // ctrl+u is no longer bound
+    await tick();
+    expect(lastFrame()).toMatch(/> \/he$/m);
+
+    stdin.write('\x0b'); // ctrl+k
+    await tick();
+    expect(lastFrame()).toContain('Type a message or /help');
+  });
+});

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

@@ -0,0 +1,75 @@
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { render } from 'ink-testing-library';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+import BackgroundTaskPanel from '../BackgroundTaskPanel.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+
+function makeEntry(overrides: Partial<IExecutionWorkspaceEntry>): IExecutionWorkspaceEntry {
+  return {
+    id: 'task:sched_1',
+    sourceId: 'sched_1',
+    kind: 'background_task',
+    origin: { kind: 'slash_command', sessionId: 'session_1', commandName: 'schedule' },
+    taskKind: 'scheduled',
+    status: 'sleeping',
+    state: 'working',
+    title: 'wake',
+    unread: false,
+    attention: 'none',
+    visibility: 'default',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    controls: ['select', 'cancel'],
+    ...overrides,
+  };
+}
+
+/** SCREEN-1992 TC-04: the tick advances the countdown once a second, only while one exists. */
+describe('BackgroundTaskPanel countdown tick', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('advances the rendered countdown every second while a schedule sleeps', async () => {
+    const { lastFrame, rerender } = render(
+      <BackgroundTaskPanel entries={[makeEntry({ nextFireAt: '2026-01-01T00:01:00.000Z' })]} />,
+    );
+    expect(lastFrame()).toContain('in 1m 0s');
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(lastFrame()).toContain('in 59s');
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(lastFrame()).toContain('in 57s');
+
+    // No sleeping schedule ⇒ the tick stops: the frame no longer changes with time.
+    rerender(
+      <BackgroundTaskPanel entries={[makeEntry({ status: 'completed', state: 'completed' })]} />,
+    );
+    expect(vi.getTimerCount()).toBe(0);
+    expect(lastFrame()).not.toContain('in ');
+  });
+
+  it('never starts the tick in screen-reader mode, yet renders against the current clock', async () => {
+    // Mounted at app start with nothing scheduled, as the real panel is.
+    const { lastFrame, rerender } = render(
+      <ScreenReaderProvider enabled>
+        <BackgroundTaskPanel entries={[makeEntry({ status: 'completed', state: 'completed' })]} />
+      </ScreenReaderProvider>,
+    );
+    // Half an hour later a schedule for one minute out appears: the reader must hear `in 1m`,
+    // not the thirty minutes since mount.
+    vi.setSystemTime(new Date('2026-01-01T00:30:00.000Z'));
+    rerender(
+      <ScreenReaderProvider enabled>
+        <BackgroundTaskPanel entries={[makeEntry({ nextFireAt: '2026-01-01T00:31:00.000Z' })]} />
+      </ScreenReaderProvider>,
+    );
+    expect(lastFrame()).toContain('in 1m 0s');
+    expect(vi.getTimerCount()).toBe(0);
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(lastFrame()).toContain('in 1m 0s');
+  });
+});

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();
+  });
+});