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

package/src/flows/text-prompt-flow.ts

@@ -0,0 +1,93 @@
+export interface ITextPromptFlowState {
+  value: string;
+  error?: string;
+  resolved: boolean;
+}
+
+export interface ITextPromptInputKey {
+  escape?: boolean;
+  return?: boolean;
+  backspace?: boolean;
+  delete?: boolean;
+  ctrl?: boolean;
+  meta?: boolean;
+}
+
+export type TTextPromptInputAction =
+  { type: 'cancel' } | { type: 'submit' } | { type: 'delete' } | { type: 'insert'; value: string };
+
+export type TTextPromptEffect =
+  { type: 'none' } | { type: 'cancel' } | { type: 'submit'; value: string };
+
+export interface ITextPromptFlowOptions {
+  allowEmpty: boolean;
+  validate?: (value: string) => string | undefined;
+}
+
+export function createTextPromptFlowState(): ITextPromptFlowState {
+  return { value: '', resolved: false };
+}
+
+export function getTextPromptInputAction(
+  input: string,
+  key: ITextPromptInputKey,
+): TTextPromptInputAction | undefined {
+  if (key.escape === true) {
+    return { type: 'cancel' };
+  }
+  if (key.return === true) {
+    return { type: 'submit' };
+  }
+  if (key.backspace === true || key.delete === true) {
+    return { type: 'delete' };
+  }
+  if (input && key.ctrl !== true && key.meta !== true) {
+    return { type: 'insert', value: input };
+  }
+  return undefined;
+}
+
+export function applyTextPromptInput(
+  state: ITextPromptFlowState,
+  action: TTextPromptInputAction,
+  options: ITextPromptFlowOptions,
+): { state: ITextPromptFlowState; effect: TTextPromptEffect } {
+  if (state.resolved) {
+    return { state, effect: { type: 'none' } };
+  }
+  if (action.type === 'cancel') {
+    return { state: { ...state, resolved: true }, effect: { type: 'cancel' } };
+  }
+  if (action.type === 'delete') {
+    return {
+      state: { ...state, value: state.value.slice(0, -1), error: undefined },
+      effect: { type: 'none' },
+    };
+  }
+  if (action.type === 'insert') {
+    return {
+      state: { ...state, value: state.value + action.value, error: undefined },
+      effect: { type: 'none' },
+    };
+  }
+  return submitTextPromptValue(state, options);
+}
+
+function submitTextPromptValue(
+  state: ITextPromptFlowState,
+  options: ITextPromptFlowOptions,
+): { state: ITextPromptFlowState; effect: TTextPromptEffect } {
+  const trimmed = state.value.trim();
+  if (!trimmed && !options.allowEmpty) {
+    const emptyError = options.validate?.(trimmed);
+    return {
+      state: emptyError ? { ...state, error: emptyError } : state,
+      effect: { type: 'none' },
+    };
+  }
+  const error = options.validate?.(trimmed);
+  if (error !== undefined) {
+    return { state: { ...state, error }, effect: { type: 'none' } };
+  }
+  return { state: { ...state, resolved: true }, effect: { type: 'submit', value: trimmed } };
+}

package/src/history-search/__tests__/history-search-flow.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  collapseToNewest,
+  cycleScope,
+  filterPrompts,
+  inScope,
+  splitByRanges,
+} from '../history-search-flow.js';
+
+import type { IPromptHistoryEntry } from '@robota-sdk/agent-interface-session';
+
+function entry(text: string, sessionId = 's1', project = '/p1'): IPromptHistoryEntry {
+  return { at: '2026-01-01T00:00:00.000Z', sessionId, project, text };
+}
+
+describe('history-search-flow (SCREEN-1993 TC-03)', () => {
+  it('filters case-insensitively with every match range, and an empty query matches all', () => {
+    const entries = [
+      entry('Deploy the canary'),
+      entry('redeploy after the deploy hook'),
+      entry('tidy'),
+    ];
+    const matches = filterPrompts(entries, 'DEPLOY');
+    expect(matches.map((match) => match.entry.text)).toEqual([
+      'Deploy the canary',
+      'redeploy after the deploy hook',
+    ]);
+    expect(matches[0]?.ranges).toEqual([[0, 6]]);
+    expect(matches[1]?.ranges).toEqual([
+      [2, 8],
+      [19, 25],
+    ]);
+    expect(filterPrompts(entries, '').map((match) => match.ranges)).toEqual([[], [], []]);
+  });
+
+  it('collapses duplicates to the newest occurrence and keeps newest-first order', () => {
+    const collapsed = collapseToNewest([
+      entry('deploy staging'),
+      entry('rotate secrets'),
+      entry('deploy staging '),
+      entry('tidy'),
+      entry('rotate secrets'),
+    ]);
+    expect(collapsed.map((item) => item.text)).toEqual([
+      'deploy staging',
+      'rotate secrets',
+      'tidy',
+    ]);
+  });
+
+  it('cycles all → session → project → all and scopes by session id or project', () => {
+    expect(cycleScope('all')).toBe('session');
+    expect(cycleScope('session')).toBe('project');
+    expect(cycleScope('project')).toBe('all');
+    const context = { sessionId: 's1', project: '/p1' };
+    const here = entry('a', 's1', '/p1');
+    const otherSession = entry('b', 's2', '/p1');
+    const otherProject = entry('c', 's3', '/p2');
+    expect([here, otherSession, otherProject].map((item) => inScope(item, 'all', context))).toEqual(
+      [true, true, true],
+    );
+    expect(
+      [here, otherSession, otherProject].map((item) => inScope(item, 'session', context)),
+    ).toEqual([true, false, false]);
+    expect(
+      [here, otherSession, otherProject].map((item) => inScope(item, 'project', context)),
+    ).toEqual([true, true, false]);
+  });
+
+  it('splits text into plain and matched runs for colour-free highlighting', () => {
+    expect(
+      splitByRanges('redeploy after the deploy hook', [
+        [2, 8],
+        [19, 25],
+      ]),
+    ).toEqual([
+      { text: 're', matched: false },
+      { text: 'deploy', matched: true },
+      { text: ' after the ', matched: false },
+      { text: 'deploy', matched: true },
+      { text: ' hook', matched: false },
+    ]);
+    expect(splitByRanges('plain', [])).toEqual([{ text: 'plain', matched: false }]);
+  });
+});

package/src/history-search/history-search-flow.ts

@@ -0,0 +1,94 @@
+/**
+ * SCREEN-1993 — the pure half of reverse prompt-history search: filtering with match ranges,
+ * collapse-to-newest dedup, the scope cycle and the run split a match is rendered from.
+ */
+import type { IPromptHistoryEntry } from '@robota-sdk/agent-interface-session';
+
+export type THistorySearchScope = 'all' | 'session' | 'project';
+
+/** `all → session → project → all`: the widest first, narrowing on each press. */
+const HISTORY_SEARCH_SCOPES: readonly THistorySearchScope[] = ['all', 'session', 'project'];
+
+export function cycleScope(scope: THistorySearchScope): THistorySearchScope {
+  const index = HISTORY_SEARCH_SCOPES.indexOf(scope);
+  return HISTORY_SEARCH_SCOPES[(index + 1) % HISTORY_SEARCH_SCOPES.length] ?? 'all';
+}
+
+export interface IHistorySearchScopeContext {
+  readonly sessionId: string;
+  readonly project: string;
+}
+
+/** Whether an entry belongs to the scope for this session and project. */
+export function inScope(
+  entry: IPromptHistoryEntry,
+  scope: THistorySearchScope,
+  context: IHistorySearchScopeContext,
+): boolean {
+  switch (scope) {
+    case 'all':
+      return true;
+    case 'session':
+      return entry.sessionId === context.sessionId;
+    case 'project':
+      return entry.project === context.project;
+  }
+}
+
+/** Search-time dedup: the first (newest) occurrence of a trimmed text wins; order is preserved. */
+export function collapseToNewest(entries: readonly IPromptHistoryEntry[]): IPromptHistoryEntry[] {
+  const seen = new Set<string>();
+  const collapsed: IPromptHistoryEntry[] = [];
+  for (const entry of entries) {
+    const key = entry.text.trim();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    collapsed.push(entry);
+  }
+  return collapsed;
+}
+
+export interface IHistorySearchMatch {
+  readonly entry: IPromptHistoryEntry;
+  /** `[start, end)` of the query inside `entry.text`; empty when the query is empty. */
+  readonly ranges: readonly (readonly [number, number])[];
+}
+
+/** Case-insensitive substring filter; an empty query matches everything with no ranges. */
+export function filterPrompts(
+  entries: readonly IPromptHistoryEntry[],
+  query: string,
+): IHistorySearchMatch[] {
+  const needle = query.toLowerCase();
+  if (needle.length === 0) return entries.map((entry) => ({ entry, ranges: [] }));
+  const matches: IHistorySearchMatch[] = [];
+  for (const entry of entries) {
+    const haystack = entry.text.toLowerCase();
+    const ranges: (readonly [number, number])[] = [];
+    let from = 0;
+    for (;;) {
+      const index = haystack.indexOf(needle, from);
+      if (index === -1) break;
+      ranges.push([index, index + needle.length]);
+      from = index + needle.length;
+    }
+    if (ranges.length > 0) matches.push({ entry, ranges });
+  }
+  return matches;
+}
+
+/** Text split into plain and highlighted runs, for rendering a match without colour dependence. */
+export function splitByRanges(
+  text: string,
+  ranges: readonly (readonly [number, number])[],
+): { readonly text: string; readonly matched: boolean }[] {
+  const runs: { text: string; matched: boolean }[] = [];
+  let cursor = 0;
+  for (const [start, end] of ranges) {
+    if (start > cursor) runs.push({ text: text.slice(cursor, start), matched: false });
+    runs.push({ text: text.slice(start, end), matched: true });
+    cursor = end;
+  }
+  if (cursor < text.length) runs.push({ text: text.slice(cursor), matched: false });
+  return runs;
+}

package/src/history-search/useHistorySearch.ts

@@ -0,0 +1,336 @@
+/**
+ * SCREEN-1993 — the reverse prompt-history search overlay's state.
+ *
+ * One loader per open: opening starts one read of the injected source under one `AbortController`,
+ * and every close — insert, execute or cancel — aborts it. Blocks arrive newest-first and are appended
+ * as they land, so the first frame shows the newest prompts before the rest of the file is read. The
+ * `session` scope never touches the file: it is the live prompt list the composer already holds.
+ *
+ * The composer's draft is restored by construction, not by copying: the overlay never writes the
+ * input while it is open, so a cancel leaves text and cursor exactly as they were.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { useKeybindingActions } from '../keybindings/keybindings-context.js';
+import { useScreenReader } from '../screen-reader-context.js';
+import {
+  collapseToNewest,
+  cycleScope,
+  filterPrompts,
+  inScope,
+  type IHistorySearchMatch,
+  type IHistorySearchScopeContext,
+  type THistorySearchScope,
+} from './history-search-flow.js';
+
+import type { IKeyInput } from '../keybindings/keybinding-registry.js';
+import type {
+  IPromptHistoryEntry,
+  IPromptHistorySource,
+} from '@robota-sdk/agent-interface-session';
+
+/** What the surface injects to turn the overlay on; absent ⇒ `ctrl+r` does nothing. */
+export interface IHistorySearchSurface {
+  readonly source: IPromptHistorySource;
+  readonly sessionId: string;
+  readonly project: string;
+}
+
+export interface IUseHistorySearchOptions {
+  readonly surface: IHistorySearchSurface | undefined;
+  /** The composer's live prompt list, oldest-first — the `session` scope. */
+  readonly sessionPrompts: readonly string[];
+  readonly onInsert: (text: string) => void;
+  readonly onExecute: (text: string) => void;
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+}
+
+export interface IHistorySearchView {
+  readonly open: boolean;
+  readonly query: string;
+  readonly scope: THistorySearchScope;
+  readonly selectedIndex: number;
+  readonly matches: readonly IHistorySearchMatch[];
+  readonly loading: boolean;
+  readonly skippedLines: number;
+  readonly error: string | undefined;
+}
+
+interface ILoadedState {
+  readonly entries: readonly IPromptHistoryEntry[];
+  readonly skippedLines: number;
+}
+
+const EMPTY_LOADED: ILoadedState = { entries: [], skippedLines: 0 };
+
+function isPrintable(input: string, key: IKeyInput): boolean {
+  const special =
+    key.ctrl === true ||
+    key.meta === true ||
+    Boolean(key.return || key.escape || key.tab) ||
+    Boolean(key.upArrow || key.downArrow || key.leftArrow || key.rightArrow) ||
+    Boolean(key.backspace || key.delete);
+  return input.length > 0 && !special;
+}
+
+function liveEntries(
+  prompts: readonly string[],
+  context: IHistorySearchScopeContext,
+): IPromptHistoryEntry[] {
+  return [...prompts]
+    .reverse()
+    .map((text) => ({ at: '', sessionId: context.sessionId, project: context.project, text }));
+}
+
+interface ILoader {
+  readonly loaded: ILoadedState;
+  readonly loading: boolean;
+  readonly error: string | undefined;
+  readonly start: () => void;
+  readonly stop: () => void;
+  /** Screen-reader mode: the list is published only here — per keystroke or at load end. */
+  readonly publish: () => void;
+}
+
+interface ILoaderRun {
+  readonly source: IPromptHistorySource;
+  readonly signal: AbortSignal;
+  readonly pending: { current: ILoadedState };
+  readonly publishEachBlock: boolean;
+  readonly publish: () => void;
+  readonly setError: (message: string) => void;
+  readonly setLoading: (loading: boolean) => void;
+}
+
+/**
+ * A real source reads synchronously and yields blocks with only a microtask between them; Ink's
+ * throttled write never runs inside that, so without this the whole file lands in one frame.
+ */
+const yieldToTerminal = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
+
+async function runLoader(run: ILoaderRun): Promise<void> {
+  try {
+    for await (const block of run.source.read({ signal: run.signal })) {
+      if (run.signal.aborted) return;
+      run.pending.current = {
+        entries: [...run.pending.current.entries, ...block.entries],
+        skippedLines: run.pending.current.skippedLines + block.skippedLines,
+      };
+      if (run.publishEachBlock) {
+        run.publish();
+        await yieldToTerminal();
+      }
+    }
+    if (!run.signal.aborted) run.publish();
+  } catch (cause) {
+    if (!run.signal.aborted) run.setError(cause instanceof Error ? cause.message : String(cause));
+  } finally {
+    if (!run.signal.aborted) run.setLoading(false);
+  }
+}
+
+/** Reads the source once per open under one abort signal. */
+function useHistoryLoader(
+  surface: IHistorySearchSurface | undefined,
+  screenReader: boolean,
+): ILoader {
+  const [loaded, setLoaded] = useState<ILoadedState>(EMPTY_LOADED);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | undefined>(undefined);
+  const controller = useRef<AbortController | undefined>(undefined);
+  const pending = useRef<ILoadedState>(EMPTY_LOADED);
+  const publish = useCallback(() => setLoaded(pending.current), []);
+  const stop = useCallback(() => {
+    controller.current?.abort();
+    controller.current = undefined;
+    setLoading(false);
+  }, []);
+  const start = useCallback(() => {
+    stop();
+    pending.current = EMPTY_LOADED;
+    setLoaded(EMPTY_LOADED);
+    setError(undefined);
+    if (surface === undefined) return;
+    const own = new AbortController();
+    controller.current = own;
+    setLoading(true);
+    void runLoader({
+      source: surface.source,
+      signal: own.signal,
+      pending,
+      publishEachBlock: !screenReader,
+      publish,
+      setError,
+      setLoading,
+    });
+  }, [publish, screenReader, stop, surface]);
+  useEffect(() => stop, [stop]);
+  return { loaded, loading, error, start, stop, publish };
+}
+
+interface ISearchKeysDeps {
+  readonly open: boolean;
+  readonly matches: readonly IHistorySearchMatch[];
+  readonly selected: number;
+  readonly scope: THistorySearchScope;
+  readonly screenReader: boolean;
+  readonly loader: ILoader;
+  readonly close: () => void;
+  readonly setScope: (scope: THistorySearchScope) => void;
+  readonly setSelectedIndex: (index: number) => void;
+  readonly setQuery: (update: (current: string) => string) => void;
+  readonly onInsert: (text: string) => void;
+  readonly onExecute: (text: string) => void;
+}
+
+/** The overlay's keys: the bound actions, and otherwise plain typing into the query. */
+function useHistorySearchKeys(deps: ISearchKeysDeps): void {
+  const editQuery = (update: (current: string) => string): void => {
+    deps.setQuery(update);
+    deps.setSelectedIndex(0);
+    if (deps.screenReader) deps.loader.publish();
+  };
+  const take = (action: 'insert' | 'execute'): void => {
+    const text = deps.matches[deps.selected]?.entry.text;
+    if (text === undefined) return;
+    deps.close();
+    (action === 'insert' ? deps.onInsert : deps.onExecute)(text);
+  };
+  const move = (step: number): void => {
+    if (deps.matches.length === 0) return;
+    deps.setSelectedIndex((deps.selected + step + deps.matches.length) % deps.matches.length);
+  };
+  useKeybindingActions(
+    'history-search',
+    (actions, input, key, consumed) => {
+      const action = actions[0];
+      if (action === 'cancel') deps.close();
+      else if (action === 'insert' || action === 'execute') take(action);
+      else if (action === 'previous') move(-1);
+      else if (action === 'next') move(1);
+      else if (action === 'cycle-scope') {
+        deps.setScope(cycleScope(deps.scope));
+        deps.setSelectedIndex(0);
+      } else if (!consumed && (key.backspace || key.delete)) editQuery((q) => q.slice(0, -1));
+      else if (!consumed && isPrintable(input, key)) editQuery((q) => q + input);
+    },
+    { isActive: deps.open },
+  );
+}
+
+/** The candidate list for the scope: the live list for `session`, the collapsed file otherwise. */
+function useCandidates(
+  open: boolean,
+  surface: IHistorySearchSurface | undefined,
+  scope: THistorySearchScope,
+  sessionPrompts: readonly string[],
+  entries: readonly IPromptHistoryEntry[],
+): IPromptHistoryEntry[] {
+  // Keyed on the surface's values, not its identity: the app rebuilds the object every render.
+  const sessionId = surface?.sessionId;
+  const project = surface?.project;
+  return useMemo(() => {
+    if (!open || sessionId === undefined || project === undefined) return [];
+    const context = { sessionId, project };
+    const scoped =
+      scope === 'session'
+        ? liveEntries(sessionPrompts, context)
+        : entries.filter((entry) => inScope(entry, scope, context));
+    return collapseToNewest(scoped);
+  }, [entries, open, project, scope, sessionId, sessionPrompts]);
+}
+
+interface IQueryState {
+  readonly query: string;
+  readonly scope: THistorySearchScope;
+  readonly selectedIndex: number;
+}
+
+const FRESH_QUERY: IQueryState = { query: '', scope: 'all', selectedIndex: 0 };
+
+/** The query, scope and selection as one state, with the setters the key handler needs. */
+function useQueryState(): {
+  readonly state: IQueryState;
+  readonly reset: () => void;
+  readonly setters: Pick<ISearchKeysDeps, 'setScope' | 'setSelectedIndex' | 'setQuery'>;
+} {
+  const [state, setState] = useState<IQueryState>(FRESH_QUERY);
+  const reset = useCallback(() => setState(FRESH_QUERY), []);
+  const setters = useMemo(
+    () => ({
+      setScope: (scope: THistorySearchScope): void => setState((s) => ({ ...s, scope })),
+      setSelectedIndex: (selectedIndex: number): void => setState((s) => ({ ...s, selectedIndex })),
+      setQuery: (update: (current: string) => string): void =>
+        setState((s) => ({ ...s, query: update(s.query) })),
+    }),
+    [],
+  );
+  return { state, reset, setters };
+}
+
+/** Open and close: one loader start per open, one stop per close, the app told of both. */
+function useOverlayVisibility(
+  loader: ILoader,
+  canOpen: boolean,
+  reset: () => void,
+  onOpenChange: ((open: boolean) => void) | undefined,
+): { readonly open: boolean; readonly openSearch: () => void; readonly closeSearch: () => void } {
+  const [open, setOpen] = useState(false);
+  const openSearch = useCallback(() => {
+    if (!canOpen || open) return;
+    reset();
+    setOpen(true);
+    onOpenChange?.(true);
+    loader.start();
+  }, [canOpen, loader, onOpenChange, open, reset]);
+  const closeSearch = useCallback(() => {
+    loader.stop();
+    setOpen(false);
+    onOpenChange?.(false);
+  }, [loader, onOpenChange]);
+  return { open, openSearch, closeSearch };
+}
+
+export function useHistorySearch(options: IUseHistorySearchOptions): {
+  readonly view: IHistorySearchView;
+  readonly openSearch: () => void;
+  readonly closeSearch: () => void;
+} {
+  const screenReader = useScreenReader();
+  const loader = useHistoryLoader(options.surface, screenReader);
+  const { state, reset, setters } = useQueryState();
+  const { query, scope } = state;
+  const { surface, onInsert, onExecute } = options;
+  const { open, openSearch, closeSearch } = useOverlayVisibility(
+    loader,
+    surface !== undefined,
+    reset,
+    options.onOpenChange,
+  );
+
+  const candidates = useCandidates(
+    open,
+    surface,
+    scope,
+    options.sessionPrompts,
+    loader.loaded.entries,
+  );
+  const matches = useMemo(() => filterPrompts(candidates, query), [candidates, query]);
+  const selected = Math.min(state.selectedIndex, Math.max(0, matches.length - 1));
+  useHistorySearchKeys({
+    open,
+    matches,
+    selected,
+    scope,
+    screenReader,
+    loader,
+    close: closeSearch,
+    onInsert,
+    onExecute,
+    ...setters,
+  });
+
+  const { loading, error, loaded } = loader;
+  const view = { ...state, open, selectedIndex: selected, matches, loading, error };
+  return { view: { ...view, skippedLines: loaded.skippedLines }, openSearch, closeSearch };
+}

package/src/hooks/__tests__/use-app-loop-escape.test.tsx

@@ -0,0 +1,74 @@
+import React from 'react';
+import { Text } from 'ink';
+import { cleanup, render } from 'ink-testing-library';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { useAppInputBindings } from '../useAppInputBindings.js';
+
+type TOptions = Parameters<typeof useAppInputBindings>[0];
+
+function Probe({ options }: { options: TOptions }): React.ReactElement {
+  useAppInputBindings(options);
+  return <Text>ready</Text>;
+}
+
+function options(overrides: Partial<TOptions> = {}): TOptions {
+  return {
+    isThinking: false,
+    isShuttingDown: false,
+    permissionRequest: null,
+    pendingUserAction: null,
+    pluginVisible: false,
+    transportVisible: false,
+    sessionPickerVisible: false,
+    workspaceSwitcherVisible: false,
+    historySearchOpen: false,
+    themePickerVisible: false,
+    selectedEntry: undefined,
+    backgroundListFocused: false,
+    mainThreadEntryId: undefined,
+    activeTools: [],
+    abort: vi.fn(),
+    stopWaitingLoop: vi.fn().mockResolvedValue(undefined),
+    toggleWorkspaceSwitcher: vi.fn(),
+    selectWorkspaceEntry: vi.fn(),
+    shutdown: vi.fn().mockResolvedValue(undefined),
+    recoveryError: undefined,
+    recoveryPending: false,
+    coordinationBlocked: false,
+    retryRecovery: vi.fn(),
+    ...overrides,
+  };
+}
+
+afterEach(cleanup);
+
+describe('Esc for a waiting self-paced loop', () => {
+  it('routes idle Esc to targeted loop stop, but active-turn Esc to abort', async () => {
+    const idle = options();
+    const idleView = render(<Probe options={idle} />);
+    idleView.stdin.write('\u001b');
+    await vi.waitFor(() => expect(idle.stopWaitingLoop).toHaveBeenCalledOnce());
+    expect(idle.abort).not.toHaveBeenCalled();
+    idleView.unmount();
+
+    const thinking = options({ isThinking: true });
+    const thinkingView = render(<Probe options={thinking} />);
+    thinkingView.stdin.write('\u001b');
+    await vi.waitFor(() => expect(thinking.abort).toHaveBeenCalledOnce());
+    expect(thinking.stopWaitingLoop).not.toHaveBeenCalled();
+  });
+
+  it('keeps list-focus and overlay Esc with their owning surfaces', async () => {
+    for (const blocked of [
+      options({ backgroundListFocused: true }),
+      options({ historySearchOpen: true }),
+    ]) {
+      const view = render(<Probe options={blocked} />);
+      view.stdin.write('\u001b');
+      await new Promise<void>((resolve) => setTimeout(resolve, 10));
+      expect(blocked.stopWaitingLoop).not.toHaveBeenCalled();
+      view.unmount();
+    }
+  });
+});

package/src/hooks/__tests__/use-plugin-callbacks.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { resolvePluginCallbacks } from '../usePluginCallbacks.js';
+
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+
+describe('resolvePluginCallbacks', () => {
+  it('preserves the host-provided plugin capability', () => {
+    const adapter = { listInstalled: vi.fn() } as unknown as ICommandPluginAdapter;
+    expect(resolvePluginCallbacks(adapter)).toBe(adapter);
+  });
+
+  it('rejects explicitly when the host has no plugin capability', async () => {
+    await expect(resolvePluginCallbacks().listInstalled()).rejects.toThrow(
+      'Plugin management is unavailable in this host.',
+    );
+  });
+});