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

package/src/hooks/useAppWorkspaceState.ts

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import {
+  countActiveBackgroundWorkspaceEntries,
+  getDefaultBackgroundWorkspaceEntries,
+} from '../execution-workspace-view-model.js';
+import { useBackgroundPanel } from './useBackgroundPanel.js';
+import { resolveBackgroundFocusKey } from '../flows/background-focus-flow.js';
+import { useKeybindingActions } from '../keybindings/keybindings-context.js';
+
+import type { IAppBackgroundViewModel } from '../app-view-model.js';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+export interface IAppWorkspaceState {
+  readonly background: IAppBackgroundViewModel;
+  readonly activeBackgroundTaskCount: number;
+  readonly activeAgentLabel: string | undefined;
+  readonly mainThreadEntryId: string | undefined;
+  readonly isSelectedEntryInteractive: boolean;
+  readonly isBackgroundListFocused: boolean;
+  readonly openSwitcher: () => void;
+  readonly toggleSwitcher: () => void;
+  readonly focusBackgroundList: () => void;
+}
+
+interface IOptions {
+  readonly snapshot: IExecutionWorkspaceSnapshot | null;
+  readonly selectedEntryId: string | undefined;
+  readonly select: (entryId: string) => void;
+  readonly read: (entryId: string) => Promise<IExecutionDetailPage>;
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly onSessionSwitch: (sessionId: string) => Promise<void>;
+  readonly addEntry: (entry: IHistoryEntry) => void;
+  readonly navigationEnabled: boolean;
+  readonly switcherVisible: boolean;
+  readonly setSwitcherVisible: (visible: boolean | ((current: boolean) => boolean)) => void;
+}
+
+interface ISwitcherActions {
+  readonly open: () => void;
+  readonly toggle: () => void;
+  readonly close: () => void;
+}
+
+function useBackgroundListKeys(
+  focusedIndex: number | null,
+  entryIds: readonly string[],
+  setFocusedIndex: (index: number | null) => void,
+  select: (entryId: string) => void,
+  enabled: boolean,
+): void {
+  useKeybindingActions(
+    'background-list',
+    (actions) => {
+      if (focusedIndex === null) return;
+      const action = resolveBackgroundFocusKey(focusedIndex, entryIds.length, {
+        upArrow: actions.includes('previous'),
+        downArrow: actions.includes('next'),
+        return: actions.includes('open'),
+        escape: actions.includes('close'),
+      });
+      if (action.type === 'move') setFocusedIndex(action.index);
+      if (action.type === 'open') {
+        const entryId = entryIds[action.index];
+        if (entryId) select(entryId);
+        setFocusedIndex(null);
+      }
+      if (action.type === 'exit') setFocusedIndex(null);
+    },
+    { isActive: focusedIndex !== null && enabled },
+  );
+}
+
+function useBackgroundFocus(
+  entryIds: readonly string[],
+  select: (entryId: string) => void,
+  enabled: boolean,
+): { focusedIndex: number | null; focusList: () => void } {
+  const [focusedIndex, setFocusedIndex] = useState<number | null>(null);
+  useEffect(() => {
+    setFocusedIndex((index) => {
+      if (index === null || entryIds.length === 0) return null;
+      return Math.min(index, entryIds.length - 1);
+    });
+  }, [entryIds.length]);
+  useBackgroundListKeys(focusedIndex, entryIds, setFocusedIndex, select, enabled);
+  const focusList = useCallback(() => {
+    if (entryIds.length > 0) setFocusedIndex(0);
+  }, [entryIds.length]);
+  return { focusedIndex, focusList };
+}
+
+function useSwitcherActions(setVisible: IOptions['setSwitcherVisible']): ISwitcherActions {
+  const open = useCallback(() => setVisible(true), [setVisible]);
+  const toggle = useCallback(() => setVisible((visible) => !visible), [setVisible]);
+  const close = useCallback(() => setVisible(false), [setVisible]);
+  return { open, toggle, close };
+}
+
+export function useAppWorkspaceState(options: IOptions): IAppWorkspaceState {
+  const entries = useMemo(
+    () => getDefaultBackgroundWorkspaceEntries(options.snapshot),
+    [options.snapshot],
+  );
+  const { focusedIndex, focusList } = useBackgroundFocus(
+    entries.map((entry) => entry.id),
+    options.select,
+    options.navigationEnabled,
+  );
+
+  const panel = useBackgroundPanel({
+    selectedEntryId: options.selectedEntryId,
+    snapshot: options.snapshot,
+    read: options.read,
+    sessionStore: options.sessionStore,
+    onSessionSwitch: options.onSessionSwitch,
+    addEntry: options.addEntry,
+  });
+  const switcher = useSwitcherActions(options.setSwitcherVisible);
+  const selected = panel.entry;
+  return {
+    background: {
+      entries,
+      focusedIndex,
+      selectedEntry: selected,
+      detail: panel.detail,
+      switcherVisible: options.switcherVisible,
+      snapshot: options.snapshot,
+      selectedEntryId: options.selectedEntryId,
+      select: options.select,
+      closeSwitcher: switcher.close,
+      attachToFork: panel.attachToFork,
+    },
+    activeBackgroundTaskCount: countActiveBackgroundWorkspaceEntries(options.snapshot),
+    activeAgentLabel: selected?.kind === 'main_thread' ? undefined : selected?.title,
+    mainThreadEntryId: options.snapshot?.entries.find((entry) => entry.kind === 'main_thread')?.id,
+    isSelectedEntryInteractive:
+      !selected || selected.kind === 'main_thread' || selected.controls.includes('send'),
+    isBackgroundListFocused: focusedIndex !== null,
+    openSwitcher: switcher.open,
+    toggleSwitcher: switcher.toggle,
+    focusBackgroundList: focusList,
+  };
+}

package/src/hooks/useAppearanceSettings.ts

@@ -0,0 +1,30 @@
+import { readAppearanceSettings } from '@robota-sdk/agent-framework';
+import { useCallback, useState } from 'react';
+
+import { useTuiCliAdapter } from '../tui-cli-adapter-context.js';
+
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { IAppearanceSettings } from '@robota-sdk/agent-interface-command';
+
+function readFromAdapter(cliAdapter: ITuiCliAdapter): IAppearanceSettings {
+  return readAppearanceSettings(cliAdapter.readSettings(cliAdapter.getUserSettingsPath()));
+}
+
+/**
+ * SCREEN-2002 — the persisted appearance, plus a from-disk `refresh()`.
+ *
+ * Refresh-on-result, the shape `useStatusLineSettings` already uses: the HOST applies
+ * `appearance-settings-patch` through the settings adapter, so the renderer learns about a change by
+ * RE-READING the document when a command result arrives. The TUI never writes these keys itself,
+ * which is what keeps one writer for one file.
+ */
+export function useAppearanceSettings(): [IAppearanceSettings, () => void] {
+  const cliAdapter = useTuiCliAdapter();
+  const [appearance, setAppearance] = useState<IAppearanceSettings>(() =>
+    readFromAdapter(cliAdapter),
+  );
+  const refresh = useCallback((): void => {
+    setAppearance(readFromAdapter(cliAdapter));
+  }, [cliAdapter]);
+  return [appearance, refresh];
+}

package/src/hooks/useAutocomplete.ts

@@ -0,0 +1,101 @@
+/**
+ * Slash command autocomplete hook.
+ * Extracted from InputArea.tsx for single-responsibility.
+ */
+
+import React, { useState, useMemo, useEffect } from 'react';
+
+import type { ITuiCommandQueryPort } from '../tui-app-channel-port.js';
+import type { ICommand } from '@robota-sdk/agent-interface-command';
+
+/** Parse input to determine autocomplete state */
+function parseSlashInput(value: string): {
+  isSlash: boolean;
+  parentCommand: string;
+  filter: string;
+} {
+  if (!value.startsWith('/')) return { isSlash: false, parentCommand: '', filter: '' };
+  const afterSlash = value.slice(1);
+  const spaceIndex = afterSlash.indexOf(' ');
+  if (spaceIndex === -1) return { isSlash: true, parentCommand: '', filter: afterSlash };
+  const parent = afterSlash.slice(0, spaceIndex);
+  const rest = afterSlash.slice(spaceIndex + 1);
+  return { isSlash: true, parentCommand: parent, filter: rest };
+}
+
+/** Hook: manage autocomplete state */
+export function useAutocomplete(
+  value: string,
+  commandQueryPort: ITuiCommandQueryPort | undefined,
+): {
+  showPopup: boolean;
+  filteredCommands: ICommand[];
+  selectedIndex: number;
+  setSelectedIndex: React.Dispatch<React.SetStateAction<number>>;
+  isSubcommandMode: boolean;
+  setShowPopup: React.Dispatch<React.SetStateAction<boolean>>;
+} {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [dismissed, setDismissed] = useState(false);
+
+  // Reset dismissed when input changes
+  const prevValueRef = React.useRef(value);
+  if (prevValueRef.current !== value) {
+    prevValueRef.current = value;
+    if (dismissed) setDismissed(false);
+  }
+
+  const parsed = parseSlashInput(value);
+  const isSubcommandMode = parsed.isSlash && parsed.parentCommand.length > 0;
+
+  const previousParentCommandRef = React.useRef(parsed.parentCommand);
+  useEffect(() => {
+    if (previousParentCommandRef.current === parsed.parentCommand) return;
+    previousParentCommandRef.current = parsed.parentCommand;
+    setSelectedIndex(0);
+  }, [parsed.parentCommand]);
+
+  const filteredCommands = useMemo(() => {
+    if (!commandQueryPort || !parsed.isSlash || dismissed) return [];
+    if (isSubcommandMode) {
+      const subs = commandQueryPort.getSubcommands(parsed.parentCommand);
+      if (subs.length === 0) return [];
+      if (!parsed.filter) return subs;
+      const lower = parsed.filter.toLowerCase();
+      return subs.filter((c) => c.name.toLowerCase().startsWith(lower));
+    }
+    return commandQueryPort.getCommands(parsed.filter);
+  }, [
+    commandQueryPort,
+    parsed.isSlash,
+    parsed.parentCommand,
+    parsed.filter,
+    dismissed,
+    isSubcommandMode,
+  ]);
+
+  const showPopup = parsed.isSlash && filteredCommands.length > 0 && !dismissed;
+
+  // Clamp selectedIndex
+  if (selectedIndex >= filteredCommands.length && filteredCommands.length > 0) {
+    setSelectedIndex(filteredCommands.length - 1);
+  }
+
+  return {
+    showPopup,
+    filteredCommands,
+    selectedIndex,
+    setSelectedIndex,
+    isSubcommandMode,
+    setShowPopup: (val) => {
+      if (typeof val === 'function') {
+        setDismissed((prev) => {
+          const nextVal = (val as (prev: boolean) => boolean)(!prev);
+          return !nextVal;
+        });
+      } else {
+        setDismissed(!val);
+      }
+    },
+  };
+}

package/src/hooks/useBackgroundPanel.ts

@@ -0,0 +1,58 @@
+/**
+ * The background panel's two data concerns as one call: what the selected entry's detail page says,
+ * and what happens when the operator attaches to a forked one.
+ *
+ * Both belong to the same surface and both are read by the same component, so `App` asks for them
+ * once rather than wiring two hooks whose inputs it has to keep in step. Split out because CLI-2004
+ * had already brought `App.tsx` to its size budget by extracting the detail read, and CLI-1994 adds
+ * the attach handler beside it — growing the file was the alternative the size rule forbids.
+ */
+
+import { useMemo } from 'react';
+
+import { useExecutionDetailPage } from './useExecutionDetailPage.js';
+import { useForkAttach } from './useForkAttach.js';
+
+import type { IExecutionDetailState } from './useExecutionDetailPage.js';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+export interface IUseBackgroundPanelOptions {
+  /** Which entry the switcher has selected; resolved against the snapshot below. */
+  readonly selectedEntryId: string | undefined;
+  /** The panel's data, and the re-read trigger — the detail follows a running task's output. */
+  readonly snapshot: IExecutionWorkspaceSnapshot | null;
+  readonly read: (entryId: string) => Promise<IExecutionDetailPage>;
+  /** Absent ⇒ this surface cannot open another session's record, and attach says so. */
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly onSessionSwitch: (sessionId: string) => void;
+  readonly addEntry: (entry: IHistoryEntry) => void;
+}
+
+export interface IBackgroundPanel {
+  /** The selected entry itself, which the switcher and the detail view both render. */
+  readonly entry: IExecutionWorkspaceEntry | undefined;
+  readonly detail: IExecutionDetailState;
+  readonly attachToFork: (entry: IExecutionWorkspaceEntry) => void;
+}
+
+/** Wire the background panel's detail read and its attach handler together. */
+export function useBackgroundPanel(inputs: IUseBackgroundPanelOptions): IBackgroundPanel {
+  const { snapshot, selectedEntryId } = inputs;
+  const entry = useMemo(
+    () => snapshot?.entries.find((candidate) => candidate.id === selectedEntryId),
+    [snapshot, selectedEntryId],
+  );
+  const detail = useExecutionDetailPage({ entry, snapshot, read: inputs.read });
+  const attachToFork = useForkAttach({
+    sessionStore: inputs.sessionStore,
+    onSessionSwitch: inputs.onSessionSwitch,
+    addEntry: inputs.addEntry,
+  });
+  return { entry, detail, attachToFork };
+}

package/src/hooks/useCountdownTick.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react';
+
+import { MS_PER_SECOND } from '../attention/time-units.js';
+
+/** SCREEN-1992: one second, the resolution a `in 59s` countdown is read at. */
+const COUNTDOWN_TICK_MS = MS_PER_SECOND;
+
+/**
+ * The clock a sleeping schedule's countdown is rendered against. Re-renders once a second only while
+ * `active` (an entry carries `nextFireAt`) and not in screen-reader mode — a reader would otherwise
+ * hear the row change every second. When not ticking the clock is still the CURRENT one on every
+ * render (never the mount-time seed): a reader gets a correct number, read once.
+ */
+export function useCountdownTick(active: boolean, screenReader: boolean): Date {
+  const ticking = active && !screenReader;
+  const [tickedAt, setTickedAt] = useState(() => new Date());
+  useEffect(() => {
+    if (!ticking) return undefined;
+    setTickedAt(new Date());
+    const timer = setInterval(() => setTickedAt(new Date()), COUNTDOWN_TICK_MS);
+    return () => clearInterval(timer);
+  }, [ticking]);
+  return ticking ? tickedAt : new Date();
+}

package/src/hooks/useExecutionDetailPage.ts

@@ -0,0 +1,69 @@
+/**
+ * Loads the inline detail page for the selected background-execution entry.
+ *
+ * Extracted from `App.tsx` (CLI-2004): three pieces of state and one async effect that exist only
+ * for the detail pane, sitting in the middle of the component's input handlers. One responsibility,
+ * one module — and the App keeps room for the concerns that actually belong to it.
+ */
+
+import { useEffect, useState } from 'react';
+
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+
+export interface IExecutionDetailState {
+  page: IExecutionDetailPage | null;
+  error: string | undefined;
+  loading: boolean;
+}
+
+export interface IUseExecutionDetailPageInputs {
+  /** The selected entry, or undefined / the main thread when no detail is shown. */
+  entry: IExecutionWorkspaceEntry | undefined;
+  /** Re-read trigger: the snapshot the entry came from. */
+  snapshot: IExecutionWorkspaceSnapshot | null;
+  read: (entryId: string) => Promise<IExecutionDetailPage>;
+}
+
+/** Load (and cancel-on-change) the detail page for the selected entry. */
+export function useExecutionDetailPage(
+  inputs: IUseExecutionDetailPageInputs,
+): IExecutionDetailState {
+  const [page, setPage] = useState<IExecutionDetailPage | null>(null);
+  const [error, setError] = useState<string | undefined>();
+  const [loading, setLoading] = useState(false);
+  const { entry, snapshot, read } = inputs;
+
+  useEffect(() => {
+    if (!entry || entry.kind === 'main_thread') {
+      setPage(null);
+      setError(undefined);
+      setLoading(false);
+      return;
+    }
+
+    let isCurrent = true;
+    setLoading(true);
+    setError(undefined);
+    read(entry.id)
+      .then((loaded) => {
+        if (!isCurrent) return;
+        setPage(loaded);
+        setLoading(false);
+      })
+      .catch((cause: Error) => {
+        if (!isCurrent) return;
+        setError(cause.message);
+        setLoading(false);
+      });
+
+    return () => {
+      isCurrent = false;
+    };
+  }, [snapshot, read, entry]);
+
+  return { page, error, loading };
+}

package/src/hooks/useForkAttach.ts

@@ -0,0 +1,60 @@
+/**
+ * CLI-1994: the App's `attach` handler, as a hook rather than another closure inside `App.tsx`.
+ *
+ * `App.tsx` is a file the size floor has already frozen as debt, where the rule is "split instead of
+ * extending" — so the handler lives beside the other App hooks. The decision itself is neither here
+ * nor there: `attachToForkedSession` asks the framework, which owns when `attach` is offered and
+ * when it is honoured.
+ */
+
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import { useCallback } from 'react';
+
+import { attachToForkedSession } from '../flows/fork-attach-flow.js';
+import { useTuiCliAdapter } from '../tui-cli-adapter-context.js';
+
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+export interface IUseForkAttachOptions {
+  /** Absent when the surface persists nothing; attach then refuses, saying so. */
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  /** The surface's session-switch path — the same one the session picker takes. */
+  readonly onSessionSwitch: (sessionId: string) => void;
+  /** Where a refusal is written, so it reaches the operator instead of disappearing. */
+  readonly addEntry: (entry: IHistoryEntry) => void;
+}
+
+/**
+ * Attach to a forked conversation: point this terminal at the fork's own session record. A VIEW
+ * switch, never a merge — the parent's record is not read, written or joined either way.
+ */
+export function useForkAttach({
+  sessionStore,
+  onSessionSwitch,
+  addEntry,
+}: IUseForkAttachOptions): (entry: IExecutionWorkspaceEntry) => void {
+  const cliAdapter = useTuiCliAdapter();
+  return useCallback(
+    (entry: IExecutionWorkspaceEntry): void => {
+      const notify = (message: string): void =>
+        addEntry(messageToHistoryEntry(createSystemMessage(message)));
+      // A surface composed without a session store cannot open another session's record. Said
+      // plainly rather than reported as "the record is missing", which is a different fact.
+      if (sessionStore === undefined) {
+        notify('This surface has no session store, so it cannot attach to a forked session.');
+        return;
+      }
+      attachToForkedSession(entry, {
+        hasSessionRecord: (sessionId) => sessionStore.load(sessionId).status === 'valid',
+        switchSession: onSessionSwitch,
+        notify,
+        ...(cliAdapter.formatResumeCommand === undefined
+          ? {}
+          : { formatResumeCommand: cliAdapter.formatResumeCommand }),
+      });
+    },
+    [addEntry, cliAdapter, onSessionSwitch, sessionStore],
+  );
+}

package/src/hooks/useInputAreaHistorySearch.ts

@@ -0,0 +1,72 @@
+/**
+ * SCREEN-1993 — the input area's side of prompt-history search: the `chat-input.history-search`
+ * open binding, and what insert and execute do to the composer.
+ *
+ * Insert replaces the composer text with the match (cursor at the end); execute submits the match
+ * through the same path Enter takes, so it is recorded in the live prompt list like any prompt. While
+ * the overlay is open the composer is untouched, which is what makes cancel restore the draft exactly.
+ */
+import { useCallback, useEffect } from 'react';
+
+import {
+  useHistorySearch,
+  type IHistorySearchSurface,
+} from '../history-search/useHistorySearch.js';
+import { useKeybindingActions } from '../keybindings/keybindings-context.js';
+
+import type { IHistorySearchView } from '../history-search/useHistorySearch.js';
+
+/** What the input area receives from the app; absent ⇒ the feature is off and `ctrl+r` is inert. */
+export interface IInputAreaHistorySearch extends IHistorySearchSurface {
+  /** Lets the app block its own bindings (Esc abort, the switcher) while the overlay is open. */
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+}
+
+export interface IUseInputAreaHistorySearchOptions {
+  readonly historySearch: IInputAreaHistorySearch | undefined;
+  readonly sessionPrompts: readonly string[];
+  /** The composer can take keys: no popup, not disabled, nothing queued. */
+  readonly composerActive: boolean;
+  readonly setValue: (value: string) => void;
+  readonly setCursorHint: (hint: number | null) => void;
+  readonly submitPrompt: (prompt: string) => void;
+}
+
+export function useInputAreaHistorySearch(
+  options: IUseInputAreaHistorySearchOptions,
+): IHistorySearchView {
+  const { historySearch, setValue, setCursorHint, submitPrompt, composerActive } = options;
+  const onInsert = useCallback(
+    (text: string) => {
+      setValue(text);
+      setCursorHint(null);
+    },
+    [setCursorHint, setValue],
+  );
+  const onExecute = useCallback(
+    (text: string) => {
+      setValue('');
+      submitPrompt(text);
+    },
+    [setValue, submitPrompt],
+  );
+  const { view, openSearch, closeSearch } = useHistorySearch({
+    surface: historySearch,
+    sessionPrompts: options.sessionPrompts,
+    onInsert,
+    onExecute,
+    onOpenChange: historySearch?.onOpenChange,
+  });
+  useKeybindingActions(
+    'chat-input',
+    (actions) => {
+      if (actions.includes('history-search')) openSearch();
+    },
+    { isActive: composerActive && !view.open && historySearch !== undefined },
+  );
+  // Another overlay or a disabled composer takes the keys: the search cannot stay open under it.
+  useEffect(() => {
+    if (view.open && !composerActive) closeSearch();
+  }, [closeSearch, composerActive, view.open]);
+  return view;
+}

package/src/hooks/useInputAreaKeys.ts

@@ -0,0 +1,114 @@
+/**
+ * The input area's three key bindings, in one place.
+ *
+ * Extracted from `InputArea.tsx` (CLI-2004) by responsibility: the component owns the input's state
+ * and its rendering; these three `useInput` registrations are the routing between the two, and each
+ * is gated on a different combination of the same flags — which is the shape that gets copied wrong
+ * when it is inline among the render code.
+ */
+
+import {
+  moveAutocompleteSelection,
+  navigatePromptHistory,
+  type IPromptHistoryNavigationState,
+} from '../flows/input-area-flow.js';
+import { useKeybindingActions } from '../keybindings/keybindings-context.js';
+
+import type { ICommand } from '@robota-sdk/agent-interface-command';
+
+export interface IUseInputAreaKeysInputs {
+  value: string;
+  isDisabled: boolean;
+  /** SCREEN-1993: the history-search overlay owns the keys while it is open. */
+  searchOpen: boolean;
+  isQueueCancellationDisabled: boolean;
+  pendingPrompt?: string | null;
+  showPopup: boolean;
+  setShowPopup: (shown: boolean) => void;
+  filteredCommands: ICommand[];
+  selectedIndex: number;
+  setSelectedIndex: (update: (previous: number) => number) => void;
+  tabCompleteCommand: (command: ICommand) => void;
+  promptHistory: string[];
+  historyState: IPromptHistoryNavigationState;
+  setValue: (value: string) => void;
+  setCursorHint: (hint: number | null) => void;
+  setHistoryState: (state: IPromptHistoryNavigationState) => void;
+  onRequestFocusBackgroundList?: (() => void) | undefined;
+  onCancelQueue?: (() => void) | undefined;
+}
+
+/** The autocomplete popup's own keys: move the selection, close it, or take the completion. */
+function useAutocompletePopupKeys(inputs: IUseInputAreaKeysInputs): void {
+  const { showPopup, isDisabled, filteredCommands, selectedIndex } = inputs;
+  useKeybindingActions(
+    'autocomplete-menu',
+    (actions) => {
+      if (!showPopup) return;
+      for (const action of actions) {
+        if (action === 'previous' || action === 'next') {
+          inputs.setSelectedIndex((previous) =>
+            moveAutocompleteSelection(previous, filteredCommands.length, action),
+          );
+        } else if (action === 'close') {
+          inputs.setShowPopup(false);
+        } else if (action === 'accept') {
+          const command = filteredCommands[selectedIndex];
+          if (command) inputs.tabCompleteCommand(command);
+        }
+      }
+    },
+    { isActive: showPopup && !isDisabled },
+  );
+}
+
+/** Register the autocomplete-popup, prompt-history and queued-prompt bindings. */
+export function useInputAreaKeys(inputs: IUseInputAreaKeysInputs): void {
+  const { showPopup, isDisabled, isQueueCancellationDisabled, pendingPrompt, searchOpen } = inputs;
+
+  useAutocompletePopupKeys(inputs);
+
+  useKeybindingActions(
+    'chat-input',
+    (actions) => {
+      const action = actions.find(
+        (candidate): candidate is 'history-previous' | 'history-next' =>
+          candidate === 'history-previous' || candidate === 'history-next',
+      );
+      if (action === undefined) return;
+      const direction = action === 'history-previous' ? 'previous' : 'next';
+      // SCREEN-014: ↓ on an empty input that is not browsing history falls through into the
+      // background-work list (where it is a no-op for the input today). The parent decides whether
+      // there is a list to focus.
+      if (
+        direction === 'next' &&
+        inputs.historyState.selectedIndex === null &&
+        inputs.value.length === 0
+      ) {
+        inputs.onRequestFocusBackgroundList?.();
+        return;
+      }
+      const result = navigatePromptHistory(
+        inputs.value,
+        inputs.promptHistory,
+        inputs.historyState,
+        direction,
+      );
+      inputs.setValue(result.value);
+      inputs.setCursorHint(result.cursorHint);
+      inputs.setHistoryState(result.state);
+    },
+    { isActive: !showPopup && !isDisabled && !pendingPrompt && !searchOpen },
+  );
+
+  // Backspace cancels queued prompt
+  useKeybindingActions(
+    'queued-prompt',
+    (actions) => {
+      if (actions.includes('cancel') && pendingPrompt) {
+        inputs.onCancelQueue?.();
+      }
+    },
+    { isActive: !!pendingPrompt && !isQueueCancellationDisabled },
+  );
+}