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

package/src/__tests__/history-search-overlay.test.tsx

@@ -0,0 +1,329 @@
+/**
+ * SCREEN-1993 TC-04 — the reverse prompt-history search overlay inside the input area.
+ *
+ * The source is an async iterable the test releases block by block, so "the first block renders
+ * before the second is yielded" and "cancel aborts the loader" are observed, not assumed.
+ */
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import InputArea from '../InputArea.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+
+import type { IInputAreaHistorySearch } from '../hooks/useInputAreaHistorySearch.js';
+import type {
+  IPromptHistoryBlock,
+  IPromptHistoryEntry,
+  IPromptHistorySource,
+} from '@robota-sdk/agent-interface-session';
+
+const CTRL_R = '\x12';
+const CTRL_S = '\x13';
+const CTRL_E = '\x05';
+const ESCAPE = '\x1b';
+const ENTER = '\r';
+const ARROW_DOWN = '\x1b[B';
+
+async function tick(ms = 25): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** A loaded CI runner can take longer than one tick to land a block: wait for the frame, bounded. */
+async function until(condition: () => boolean, timeoutMs = 5_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!condition()) {
+    if (Date.now() > deadline) throw new Error('until: condition not met in time');
+    await tick(10);
+  }
+}
+
+function entry(text: string, sessionId = 'other', project = '/elsewhere'): IPromptHistoryEntry {
+  return { at: '2026-01-01T00:00:00.000Z', sessionId, project, text };
+}
+
+/** A source whose blocks are released by the test, recording opens and abort signals. */
+function gatedSource(blocks: readonly IPromptHistoryBlock[]): {
+  readonly source: IPromptHistorySource;
+  readonly release: () => void;
+  readonly reads: number;
+  readonly aborted: () => boolean;
+  readonly opens: () => number;
+} {
+  let opens = 0;
+  let resolveNext: (() => void) | undefined;
+  let signal: AbortSignal | undefined;
+  const source: IPromptHistorySource = {
+    async *read(options) {
+      opens += 1;
+      signal = options.signal;
+      for (const block of blocks) {
+        await new Promise<void>((resolve) => {
+          resolveNext = resolve;
+        });
+        if (options.signal.aborted) return;
+        yield block;
+      }
+    },
+  };
+  return {
+    source,
+    release: () => resolveNext?.(),
+    reads: blocks.length,
+    aborted: () => signal?.aborted === true,
+    opens: () => opens,
+  };
+}
+
+function renderWith(
+  source: IPromptHistorySource,
+  options: {
+    readonly screenReader?: boolean;
+    readonly onOpenChange?: (open: boolean) => void;
+  } = {},
+): ReturnType<typeof render> & { readonly onSubmit: ReturnType<typeof vi.fn> } {
+  const onSubmit = vi.fn();
+  const historySearch: IInputAreaHistorySearch = {
+    source,
+    sessionId: 's-current',
+    project: '/here',
+    onOpenChange: options.onOpenChange,
+  };
+  const rendered = render(
+    <ScreenReaderProvider enabled={options.screenReader === true}>
+      <InputArea onSubmit={onSubmit} isDisabled={false} historySearch={historySearch} />
+    </ScreenReaderProvider>,
+  );
+  return { ...rendered, onSubmit };
+}
+
+describe('SCREEN-1993 TC-04: the history-search overlay', () => {
+  it('opens on ctrl+r, starts one loader, and renders the first block before the second lands', async () => {
+    const gate = gatedSource([
+      { entries: [entry('deploy the canary to eu-west', 's-current', '/here')], skippedLines: 1 },
+      { entries: [entry('rotate the staging secrets')], skippedLines: 0 },
+    ]);
+    const opened: boolean[] = [];
+    const { stdin, lastFrame, unmount } = renderWith(gate.source, {
+      onOpenChange: (open) => opened.push(open),
+    });
+    await tick();
+    stdin.write('dra');
+    await tick();
+    stdin.write(CTRL_R);
+    await tick();
+    expect(gate.opens()).toBe(1);
+    expect(opened).toEqual([true]);
+    expect(lastFrame()).toContain('(reverse-i-search)');
+    expect(lastFrame()).toContain('scope: all');
+    expect(lastFrame()).toContain('loading…');
+
+    gate.release();
+    await until(() => (lastFrame() ?? '').includes('deploy the canary to eu-west'));
+    expect(lastFrame()).not.toContain('rotate the staging secrets');
+    expect(lastFrame()).toContain('1 unreadable line skipped');
+
+    gate.release();
+    await until(() => (lastFrame() ?? '').includes('rotate the staging secrets'));
+    await until(() => !(lastFrame() ?? '').includes('loading…'));
+    expect(gate.opens()).toBe(1);
+    unmount();
+  });
+
+  it('a source with a synchronous body still renders the first block before the second lands', async () => {
+    // `NodePromptHistoryFile.read` is an async generator whose body is `readSync` all the way down:
+    // between two blocks there is only a microtask. Without a macrotask yield in the loader, Ink's
+    // throttled write never runs between publishes and the user sees the whole file at once.
+    const source: IPromptHistorySource = {
+      async *read() {
+        yield { entries: [entry('newest block prompt')], skippedLines: 0 };
+        yield { entries: [entry('older block prompt')], skippedLines: 0 };
+      },
+    };
+    const { stdin, frames, lastFrame, unmount } = renderWith(source);
+    await tick();
+    stdin.write(CTRL_R);
+    await until(() => (lastFrame() ?? '').includes('older block prompt'));
+    const firstBlockFrame = frames.find(
+      (frame) => frame.includes('newest block prompt') && !frame.includes('older block prompt'),
+    );
+    expect(firstBlockFrame).toBeDefined();
+    unmount();
+  });
+
+  it('narrows as the query is typed with the match marked, and enter inserts without submitting', async () => {
+    const gate = gatedSource([
+      {
+        entries: [
+          entry('deploy the canary to eu-west'),
+          entry('tidy the changelog headings'),
+          entry('redeploy after the deploy hook fails'),
+        ],
+        skippedLines: 0,
+      },
+    ]);
+    const { stdin, lastFrame, onSubmit, unmount } = renderWith(gate.source);
+    await tick();
+    stdin.write(CTRL_R);
+    gate.release();
+    await until(() => (lastFrame() ?? '').includes('tidy the changelog headings'));
+    stdin.write('deploy');
+    await until(() => (lastFrame() ?? '').includes('query: deploy'));
+    const frame = lastFrame() ?? '';
+    expect(frame).toContain('query: deploy');
+    expect(frame).toContain('[deploy]');
+    expect(frame).not.toContain('tidy the changelog headings');
+    expect(frame).toContain('2 matches');
+
+    stdin.write(ARROW_DOWN);
+    await tick();
+    stdin.write(ENTER);
+    await until(() => !(lastFrame() ?? '').includes('(reverse-i-search)'));
+    expect(lastFrame()).toContain('redeploy after the deploy hook fails');
+    expect(onSubmit).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it('ctrl+e submits the highlighted match through the normal submit path', async () => {
+    const gate = gatedSource([{ entries: [entry('rotate the staging secrets')], skippedLines: 0 }]);
+    const { stdin, lastFrame, onSubmit, unmount } = renderWith(gate.source);
+    await tick();
+    stdin.write(CTRL_R);
+    gate.release();
+    await until(() => (lastFrame() ?? '').includes('rotate the staging secrets'));
+    stdin.write('rotate');
+    await until(() => (lastFrame() ?? '').includes('query: rotate'));
+    stdin.write(CTRL_E);
+    await until(() => onSubmit.mock.calls.length > 0);
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith('rotate the staging secrets');
+    expect(lastFrame()).not.toContain('(reverse-i-search)');
+    unmount();
+  });
+
+  it('escape mid-load aborts the loader and leaves the draft byte-identical', async () => {
+    const gate = gatedSource([
+      { entries: [entry('a')], skippedLines: 0 },
+      { entries: [entry('b')], skippedLines: 0 },
+    ]);
+    const opened: boolean[] = [];
+    const { stdin, lastFrame, onSubmit, unmount } = renderWith(gate.source, {
+      onOpenChange: (open) => opened.push(open),
+    });
+    await tick();
+    const draft = 'third draft: keep me byte-identical  ';
+    stdin.write(draft);
+    await tick();
+    stdin.write(CTRL_R);
+    gate.release();
+    await until(() => (lastFrame() ?? '').includes('(reverse-i-search)'));
+    stdin.write('zzz');
+    await until(() => (lastFrame() ?? '').includes('query: zzz'));
+    expect(lastFrame()).toContain('loading…');
+    stdin.write(ESCAPE);
+    await until(() => !(lastFrame() ?? '').includes('(reverse-i-search)'));
+    expect(gate.aborted()).toBe(true);
+    expect(opened).toEqual([true, false]);
+    expect(lastFrame()).not.toContain('(reverse-i-search)');
+    expect(lastFrame()).toContain(draft.trimEnd());
+    expect(onSubmit).not.toHaveBeenCalled();
+    // The draft is submitted unchanged: what the composer holds is what it held before ctrl+r.
+    stdin.write(ENTER);
+    await until(() => onSubmit.mock.calls.length === 1);
+    expect(onSubmit).toHaveBeenCalledWith(draft.trim());
+    unmount();
+  });
+
+  it('ctrl+s cycles the scope and the session scope is the live prompt list', async () => {
+    const gate = gatedSource([
+      {
+        entries: [entry('stored elsewhere'), entry('stored here', 'other', '/here')],
+        skippedLines: 0,
+      },
+    ]);
+    const { stdin, lastFrame, onSubmit, unmount } = renderWith(gate.source);
+    await tick();
+    const prompts = ['typed this session', 'another prompt', 'typed this session'];
+    for (const [index, prompt] of prompts.entries()) {
+      stdin.write(prompt);
+      await until(() => (lastFrame() ?? '').includes(prompt));
+      stdin.write(ENTER);
+      // The deferred submit has fired and cleared the composer before the next prompt is typed.
+      await until(() => onSubmit.mock.calls.length === index + 1);
+      await until(() => !(lastFrame() ?? '').includes(prompt));
+    }
+    stdin.write(CTRL_R);
+    gate.release();
+    await until(() => (lastFrame() ?? '').includes('stored elsewhere'));
+    stdin.write(CTRL_S);
+    await until(() => (lastFrame() ?? '').includes('scope: session'));
+    expect(lastFrame()).toContain('typed this session');
+    // Collapsed to the newest occurrence in the session scope too.
+    expect((lastFrame() ?? '').split('typed this session').length - 1).toBe(1);
+    expect(lastFrame()).not.toContain('stored elsewhere');
+    stdin.write(CTRL_S);
+    await until(() => (lastFrame() ?? '').includes('scope: project'));
+    expect(lastFrame()).toContain('stored here');
+    expect(lastFrame()).not.toContain('stored elsewhere');
+    stdin.write(CTRL_S);
+    await until(() => (lastFrame() ?? '').includes('scope: all'));
+    unmount();
+  });
+
+  it('keeps a multi-line prompt on one row with a visible newline glyph, ranges aligned', async () => {
+    const source: IPromptHistorySource = {
+      async *read() {
+        yield {
+          entries: [entry('first line\nsecond line'), entry('crlf line\r\nthen deploy')],
+          skippedLines: 0,
+        };
+      },
+    };
+    const { stdin, lastFrame, unmount } = renderWith(source);
+    await tick();
+    stdin.write(CTRL_R);
+    await until(() => (lastFrame() ?? '').includes('first line↵second line'));
+    expect(lastFrame()).toContain('crlf line ↵then deploy');
+    stdin.write('deploy');
+    // The two-unit CRLF became two units, so the match range still lands on the word.
+    await until(() => (lastFrame() ?? '').includes('crlf line ↵then [deploy]'));
+    unmount();
+  });
+
+  it('renders a read error instead of an empty list', async () => {
+    const source: IPromptHistorySource = {
+      // eslint-disable-next-line require-yield -- the failure is the whole behaviour under test.
+      async *read() {
+        throw new Error('EACCES: permission denied');
+      },
+    };
+    const { stdin, lastFrame, unmount } = renderWith(source);
+    await tick();
+    stdin.write(CTRL_R);
+    await until(() => (lastFrame() ?? '').includes('History could not be read'));
+    expect(lastFrame()).toContain('History could not be read: EACCES: permission denied');
+    unmount();
+  });
+
+  it('in screen-reader mode the rows are numbered and blocks are published only at load end', async () => {
+    const gate = gatedSource([
+      { entries: [entry('first block prompt')], skippedLines: 0 },
+      { entries: [entry('second block prompt')], skippedLines: 0 },
+    ]);
+    const { stdin, lastFrame, unmount } = renderWith(gate.source, { screenReader: true });
+    await tick();
+    stdin.write(CTRL_R);
+    gate.release();
+    await until(() => (lastFrame() ?? '').includes('(reverse-i-search)'));
+    await tick(50);
+    expect(lastFrame()).not.toContain('first block prompt');
+    gate.release();
+    await until(() => (lastFrame() ?? '').includes('2. second block prompt'));
+    expect(lastFrame()).toContain('1. first block prompt');
+    // Digits are query text, not a selection.
+    stdin.write('2');
+    await until(() => (lastFrame() ?? '').includes('query: 2'));
+    expect(lastFrame()).toContain('no match');
+    unmount();
+  });
+});

package/src/__tests__/humanize-tool-name.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+
+import { humanizeToolName } from '../humanize-tool-name.js';
+
+describe('humanizeToolName (SCREEN-012)', () => {
+  it('strips the neutral prefix to recover the command name', () => {
+    expect(humanizeToolName('command_agent')).toBe('agent');
+    expect(humanizeToolName('command_parallel')).toBe('parallel');
+  });
+
+  it('uses a host-selected prefix without changing other tool names', () => {
+    expect(humanizeToolName('robota_command_agent', 'robota_command_')).toBe('agent');
+    expect(humanizeToolName('acme_command_agent', 'acme_command_')).toBe('agent');
+    expect(humanizeToolName('acme_command_agent')).toBe('acme_command_agent');
+  });
+
+  it('drops a trailing 8-hex projection hash', () => {
+    expect(humanizeToolName('command_some_long_command_1a2b3c4d')).toBe('some_long_command');
+  });
+
+  it('leaves non-command tool names unchanged', () => {
+    expect(humanizeToolName('Shell')).toBe('Shell');
+    expect(humanizeToolName('Read')).toBe('Read');
+    expect(humanizeToolName('Bash')).toBe('Bash');
+  });
+
+  it('falls back to the original when stripping would leave nothing', () => {
+    expect(humanizeToolName('command_')).toBe('command_');
+  });
+});

package/src/__tests__/input-area-bottom-border.test.tsx

@@ -0,0 +1,45 @@
+/**
+ * SCREEN-003 TC-01 — the input box's bottom border is an always-present hand-drawn `<Text>` row,
+ * not a Yoga-synthesized Box border that can drop glyphs under rapid re-render. Deterministic guard:
+ * the last rendered line is a full-width run of `─`, identical to the top border, in BOTH the
+ * streaming (`isDisabled`) state (where the flicker appeared) and the idle state.
+ */
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, expect, it, vi } from 'vitest';
+
+import InputArea from '../InputArea.js';
+
+// Built from the code point rather than a literal ESC in the pattern (no-control-regex).
+const ANSI_SGR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+const stripAnsi = (s: string): string => s.replace(ANSI_SGR, '');
+
+function borderLines(frame: string): { first: string; last: string; all: string[] } {
+  const lines = stripAnsi(frame)
+    .split('\n')
+    .map((l) => l.replace(/\s+$/, ''));
+  const nonEmpty = lines.filter((l) => l.length > 0);
+  return { first: nonEmpty[0], last: nonEmpty[nonEmpty.length - 1], all: nonEmpty };
+}
+
+async function tick(ms = 25): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe('InputArea bottom border stability (SCREEN-003)', () => {
+  for (const isDisabled of [true, false]) {
+    it(`renders a full-width \`─\` bottom border row (isDisabled=${isDisabled})`, async () => {
+      const { lastFrame } = render(<InputArea onSubmit={vi.fn()} isDisabled={isDisabled} />);
+      await tick();
+
+      const { first, last } = borderLines(lastFrame() ?? '');
+
+      // Bottom border is present and is a pure run of the horizontal box glyph.
+      expect(last).toMatch(/^─+$/);
+      // Top border is the same hand-drawn full-width run — both share `innerWidth`.
+      expect(first).toMatch(/^─+$/);
+      expect(last).toBe(first);
+      expect(last.length).toBeGreaterThan(0);
+    });
+  }
+});

package/src/__tests__/input-area-flow.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createCostCommandEntry,
+  createLoopCommandEntry,
+  createMCPActivationCommandEntry,
+  createRemoteControlCommandEntry,
+} from '@robota-sdk/agent-command';
+import {
+  appendPromptHistory,
+  createPasteLabelChange,
+  createPromptHistoryNavigationState,
+  extractPromptHistory,
+  getAutocompletePopupAction,
+  getPromptHistoryInputAction,
+  getPendingPromptInputAction,
+  moveAutocompleteSelection,
+  navigatePromptHistory,
+  resolveEnterCommandSelection,
+  resolveTabCompletion,
+  shouldSubmitInput,
+} from '../flows/input-area-flow.js';
+import type { ICommand } from '@robota-sdk/agent-interface-command';
+import {
+  createAssistantMessage,
+  createSystemMessage,
+  createUserMessage,
+  messageToHistoryEntry,
+} from '@robota-sdk/agent-core';
+
+const command = (name: string, subcommands?: ICommand[]): ICommand => ({
+  name,
+  description: `${name} command`,
+  source: 'test',
+  subcommands,
+  execute: async () => {},
+});
+
+describe('input area flow', () => {
+  it('Given autocomplete key info When mapped Then popup actions are produced', () => {
+    expect(getAutocompletePopupAction({ upArrow: true })).toBe('previous');
+    expect(getAutocompletePopupAction({ downArrow: true })).toBe('next');
+    expect(getAutocompletePopupAction({ escape: true })).toBe('close');
+    expect(getAutocompletePopupAction({ tab: true })).toBe('complete');
+  });
+
+  it('Given pending prompt key info When mapped Then cancel queue action is produced', () => {
+    expect(getPendingPromptInputAction({ backspace: true })).toBe('cancelQueue');
+    expect(getPendingPromptInputAction({ delete: true })).toBe('cancelQueue');
+    expect(getPendingPromptInputAction({ downArrow: true })).toBeUndefined();
+  });
+
+  it('Given wrapping autocomplete When moving beyond bounds Then index wraps', () => {
+    expect(moveAutocompleteSelection(0, 3, 'previous')).toBe(2);
+    expect(moveAutocompleteSelection(2, 3, 'next')).toBe(0);
+  });
+
+  it('Given parent command input When tab completes subcommand Then child name is inserted', () => {
+    const result = resolveTabCompletion('/plugin i', command('install'));
+
+    expect(result).toEqual({ type: 'insert', value: '/plugin install ' });
+  });
+
+  it('Given command with subcommands When enter selects it Then command name is inserted', () => {
+    const result = resolveEnterCommandSelection('/pl', command('plugin', [command('list')]));
+
+    expect(result).toEqual({ type: 'insert', value: '/plugin ', selectedIndex: 0 });
+  });
+
+  it('Given leaf command When enter selects it Then submit value is emitted', () => {
+    const result = resolveEnterCommandSelection('/he', command('help'));
+
+    expect(result).toEqual({ type: 'submit', value: '/help' });
+  });
+
+  it('Given command with no args and no subcommands When enter selects Then submits', () => {
+    const result = resolveEnterCommandSelection('/ex', command('exit'));
+
+    expect(result).toEqual({ type: 'submit', value: '/exit' });
+  });
+
+  it('submits the default session cost summary when Enter selects /cost', () => {
+    const cost = createCostCommandEntry();
+
+    expect(resolveEnterCommandSelection('/co', cost)).toEqual({ type: 'submit', value: '/cost' });
+    expect(resolveEnterCommandSelection('/cost', cost)).toEqual({ type: 'submit', value: '/cost' });
+  });
+
+  it('runs a command whose bare form is complete even though it declares subcommands', () => {
+    const mcp = createMCPActivationCommandEntry();
+
+    expect(mcp.subcommands?.length).toBeGreaterThan(0);
+    expect(resolveEnterCommandSelection('/mc', mcp)).toEqual({ type: 'submit', value: '/mcp' });
+  });
+
+  it.each([
+    { entry: createRemoteControlCommandEntry(), safeAction: 'status' },
+    { entry: createLoopCommandEntry(), safeAction: 'list' },
+  ])('requires an explicit safe action after autocomplete selects /$entry.name', ({ entry, safeAction }) => {
+    const firstEnter = resolveEnterCommandSelection(`/${entry.name.slice(0, 3)}`, entry);
+    expect(firstEnter).toEqual({ type: 'insert', value: `/${entry.name} `, selectedIndex: 0 });
+
+    const suggestion = entry.subcommands?.[0];
+    expect(suggestion?.name).toBe(safeAction);
+    expect(resolveEnterCommandSelection(firstEnter.value, suggestion!)).toEqual({
+      type: 'submit',
+      value: `/${entry.name} ${safeAction}`,
+    });
+  });
+
+  it('Given subcommand selected (args present) When enter selects Then submits', () => {
+    const result = resolveEnterCommandSelection('/mode plan', command('plan'));
+
+    expect(result).toEqual({ type: 'submit', value: '/mode plan' });
+  });
+
+  it('Given multiline paste When label change is created Then label is inserted at cursor', () => {
+    const result = createPasteLabelChange('abef', 2, 7, 'c\nd\ne');
+
+    expect(result).toEqual({
+      value: 'ab[Pasted text #7 +3 lines]ef',
+      cursorHint: 27,
+      label: '[Pasted text #7 +3 lines]',
+      lineCount: 3,
+    });
+  });
+
+  it('Given blank prompt When checked Then submit is rejected', () => {
+    expect(shouldSubmitInput('   ')).toBe(false);
+    expect(shouldSubmitInput(' hello ')).toBe(true);
+  });
+
+  it('Given prompt history key info When mapped Then history actions are produced', () => {
+    expect(getPromptHistoryInputAction({ upArrow: true })).toBe('previous');
+    expect(getPromptHistoryInputAction({ downArrow: true })).toBe('next');
+    expect(getPromptHistoryInputAction({ escape: true })).toBeUndefined();
+  });
+
+  it('Given empty prompt history When navigating Then input is unchanged', () => {
+    const result = navigatePromptHistory(
+      'draft',
+      [],
+      createPromptHistoryNavigationState(),
+      'previous',
+    );
+
+    expect(result).toEqual({
+      value: 'draft',
+      cursorHint: 5,
+      state: createPromptHistoryNavigationState(),
+    });
+  });
+
+  it('Given draft and history When pressing up Then latest prompt is recalled and draft is saved', () => {
+    const result = navigatePromptHistory(
+      'draft text',
+      ['first', 'second'],
+      createPromptHistoryNavigationState(),
+      'previous',
+    );
+
+    expect(result).toEqual({
+      value: 'second',
+      cursorHint: 6,
+      state: { selectedIndex: 1, draft: 'draft text' },
+    });
+  });
+
+  it('Given history navigation When pressing down past latest Then draft is restored', () => {
+    const result = navigatePromptHistory(
+      'second',
+      ['first', 'second'],
+      { selectedIndex: 1, draft: 'draft text' },
+      'next',
+    );
+
+    expect(result).toEqual({
+      value: 'draft text',
+      cursorHint: 10,
+      state: createPromptHistoryNavigationState(),
+    });
+  });
+
+  it('Given prompt submit When appended Then blank and consecutive duplicates are ignored', () => {
+    expect(appendPromptHistory(['first'], 'second')).toEqual(['first', 'second']);
+    expect(appendPromptHistory(['first'], 'first')).toEqual(['first']);
+    expect(appendPromptHistory(['first'], '   ')).toEqual(['first']);
+  });
+
+  it('Given history entries When extracted Then only user chat content is included', () => {
+    const entries = [
+      messageToHistoryEntry(createUserMessage('first')),
+      messageToHistoryEntry(createAssistantMessage('answer')),
+      messageToHistoryEntry(createSystemMessage('system')),
+      messageToHistoryEntry(createUserMessage('second')),
+    ];
+
+    expect(extractPromptHistory(entries)).toEqual(['first', 'second']);
+  });
+});

package/src/__tests__/input-area-focus-handoff.test.tsx

@@ -0,0 +1,77 @@
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { describe, expect, it, vi } from 'vitest';
+
+import InputArea from '../InputArea.js';
+
+// ESC [ B — the terminal down-arrow sequence Ink parses into `key.downArrow`.
+const DOWN_ARROW = '';
+
+async function tick(ms = 25): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe('InputArea ↓ fall-through into the background list (SCREEN-014)', () => {
+  it('requests background-list focus when ↓ is pressed on an empty input', async () => {
+    const onRequestFocusBackgroundList = vi.fn();
+    const { stdin } = render(
+      <InputArea
+        onSubmit={vi.fn()}
+        isDisabled={false}
+        onRequestFocusBackgroundList={onRequestFocusBackgroundList}
+      />,
+    );
+    await tick();
+    stdin.write(DOWN_ARROW);
+    await tick();
+    expect(onRequestFocusBackgroundList).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not request focus while the input is disabled', async () => {
+    const onRequestFocusBackgroundList = vi.fn();
+    const { stdin } = render(
+      <InputArea
+        onSubmit={vi.fn()}
+        isDisabled={true}
+        onRequestFocusBackgroundList={onRequestFocusBackgroundList}
+      />,
+    );
+    await tick();
+    stdin.write(DOWN_ARROW);
+    await tick();
+    expect(onRequestFocusBackgroundList).not.toHaveBeenCalled();
+  });
+
+  it('does not cancel a queued prompt while recovery disables the input', async () => {
+    const onCancelQueue = vi.fn();
+    const { stdin } = render(
+      <InputArea
+        onSubmit={vi.fn()}
+        isDisabled
+        pendingPrompt="queued prompt"
+        onCancelQueue={onCancelQueue}
+      />,
+    );
+    await tick();
+    stdin.write('\x7F');
+    await tick();
+    expect(onCancelQueue).not.toHaveBeenCalled();
+  });
+
+  it('keeps queued-prompt cancellation active during ordinary thinking disablement', async () => {
+    const onCancelQueue = vi.fn();
+    const { stdin } = render(
+      <InputArea
+        onSubmit={vi.fn()}
+        isDisabled
+        isQueueCancellationDisabled={false}
+        pendingPrompt="queued prompt"
+        onCancelQueue={onCancelQueue}
+      />,
+    );
+    await tick();
+    stdin.write('\x7F');
+    await tick();
+    expect(onCancelQueue).toHaveBeenCalledTimes(1);
+  });
+});