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

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

package/src/hooks/useNumberedSelection.ts

@@ -0,0 +1,93 @@
+/**
+ * CLI-2004 — the typed-number input wiring shared by every numbered menu.
+ *
+ * The reducer lives in `flows/selection-flow.ts` (one owner of "what is selected"); this hook is the
+ * Ink adapter around it, so six components get the same behaviour without six copies of the same
+ * `useInput` block. Inactive when the mode is off, so the arrow-key handlers keep the terminal.
+ */
+
+import { useInput } from 'ink';
+import { useCallback, useRef, useState } from 'react';
+
+import {
+  applyNumericSelection,
+  createNumericSelectionState,
+  type INumericSelectionState,
+} from '../flows/selection-flow.js';
+
+export interface IUseNumberedSelectionInputs {
+  /** Screen-reader mode. Off ⇒ the hook reads nothing. */
+  enabled: boolean;
+  itemCount: number;
+  cancellable?: boolean;
+  /** A checklist: a number toggles a row, the menu stays open, and an empty Enter commits. */
+  multi?: boolean;
+  /** Keep a single-row selection open so the user can select another row later. */
+  repeatable?: boolean;
+  onSelect: (index: number) => void;
+  onCancel?: () => void;
+  /** Required with `multi` — what an empty Enter commits. */
+  onConfirm?: () => void;
+}
+
+export interface INumberedSelection {
+  buffer: string;
+  invalid: boolean;
+  clear: () => void;
+}
+
+/** Read a typed selection for a numbered list. */
+export function useNumberedSelection(inputs: IUseNumberedSelectionInputs): INumberedSelection {
+  const [state, setState] = useState<INumericSelectionState>(createNumericSelectionState);
+  const stateRef = useRef(state);
+  const { enabled, itemCount, cancellable, multi, repeatable, onSelect, onCancel, onConfirm } =
+    inputs;
+
+  const clear = useCallback((): void => {
+    const empty = createNumericSelectionState();
+    stateRef.current = empty;
+    setState(empty);
+  }, []);
+
+  const handle = useCallback(
+    (input: string, key: Parameters<typeof applyNumericSelection>[2]): boolean => {
+      const result = applyNumericSelection(stateRef.current, input, key, {
+        itemCount,
+        ...(cancellable === true ? { cancellable: true } : {}),
+        ...(multi === true ? { multi: true } : {}),
+        ...(repeatable === true ? { repeatable: true } : {}),
+      });
+      stateRef.current = result.state;
+      setState(result.state);
+      if (result.effect.type === 'select') onSelect(result.effect.index);
+      else if (result.effect.type === 'cancel') onCancel?.();
+      else if (result.effect.type === 'confirm') onConfirm?.();
+      return result.effect.type !== 'none';
+    },
+    [itemCount, cancellable, multi, repeatable, onSelect, onCancel, onConfirm],
+  );
+
+  useInput(
+    (input, key) => {
+      // Pasted or fast-typed input can arrive as one chunk ("2\r"): Ink then reports it as plain
+      // text with no return key. Replay it as the keystrokes it contains so the Enter is not lost,
+      // but only up to the first keystroke that acts: the menu's callbacks see the state of the
+      // current render, so acting twice within one chunk could decide on stale state.
+      if (key.return !== true && /[\r\n]/u.test(input)) {
+        const plainKey = { ...key, return: false };
+        for (const part of input.split(/(\r\n|\r|\n)/u)) {
+          if (part === '') continue;
+          const acted = /^(\r\n|\r|\n)$/u.test(part)
+            ? handle('', { ...plainKey, return: true })
+            : handle(part, plainKey);
+          if (acted) break;
+        }
+        return;
+      }
+      handle(input, key);
+    },
+    { isActive: enabled },
+  );
+
+  return { buffer: state.buffer, invalid: state.invalid, clear };
+}

package/src/hooks/usePluginCallbacks.ts

@@ -0,0 +1,38 @@
+/**
+ * Hook: uses the host plugin adapter, or an explicit unsupported adapter when none is provided.
+ *
+ * A missing host capability must fail visibly. Returning successful no-ops would make the plugin
+ * screen claim mutations succeeded while changing nothing.
+ */
+
+import { useMemo } from 'react';
+
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+
+function unsupported(): Promise<never> {
+  return Promise.reject(new Error('Plugin management is unavailable in this host.'));
+}
+
+function createUnsupportedPluginAdapter(): ICommandPluginAdapter {
+  return {
+    listInstalled: unsupported,
+    listAvailablePlugins: unsupported,
+    install: unsupported,
+    uninstall: unsupported,
+    enable: unsupported,
+    disable: unsupported,
+    marketplaceAdd: unsupported,
+    marketplaceRemove: unsupported,
+    marketplaceUpdate: unsupported,
+    marketplaceList: unsupported,
+    reloadPlugins: unsupported,
+  };
+}
+
+export function resolvePluginCallbacks(adapter?: ICommandPluginAdapter): ICommandPluginAdapter {
+  return adapter ?? createUnsupportedPluginAdapter();
+}
+
+export function usePluginCallbacks(adapter?: ICommandPluginAdapter): ICommandPluginAdapter {
+  return useMemo(() => resolvePluginCallbacks(adapter), [adapter]);
+}

package/src/hooks/usePluginScreenData.ts

@@ -0,0 +1,85 @@
+/**
+ * Hook: fetch data for PluginTUI screens.
+ * Extracted from PluginTUI.tsx for single-responsibility.
+ */
+
+import { useState, useEffect } from 'react';
+
+import type { IMenuSelectItem } from '../MenuSelect.js';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+
+export function usePluginScreenData(
+  screen: string,
+  marketplace: string | undefined,
+  callbacks: ICommandPluginAdapter,
+  refreshCounter: number,
+  stackLength: number,
+): { items: IMenuSelectItem[]; loading: boolean; error: string | undefined } {
+  const [items, setItems] = useState<IMenuSelectItem[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | undefined>();
+
+  useEffect(() => {
+    setItems([]);
+    setError(undefined);
+
+    if (screen === 'marketplace-list') {
+      setLoading(true);
+      callbacks
+        .marketplaceList()
+        .then((sources) => {
+          const baseItems: IMenuSelectItem[] = [{ label: 'Add Marketplace', value: '__add__' }];
+          const sourceItems: IMenuSelectItem[] = sources.map((s) => ({
+            label: s.name,
+            value: s.name,
+            hint: s.type,
+          }));
+          setItems([...baseItems, ...sourceItems]);
+          setLoading(false);
+        })
+        .catch((err) => {
+          setError(err instanceof Error ? err.message : String(err));
+          setLoading(false);
+        });
+    } else if (screen === 'marketplace-browse') {
+      const mp = marketplace ?? '';
+      setLoading(true);
+      callbacks
+        .listAvailablePlugins(mp)
+        .then((plugins) => {
+          setItems(
+            plugins.map((p) => ({
+              label: p.name,
+              value: p.name,
+              hint: p.installed ? 'installed' : p.description,
+            })),
+          );
+          setLoading(false);
+        })
+        .catch((err) => {
+          setError(err instanceof Error ? err.message : String(err));
+          setLoading(false);
+        });
+    } else if (screen === 'installed-list') {
+      setLoading(true);
+      callbacks
+        .listInstalled()
+        .then((plugins) => {
+          setItems(
+            plugins.map((p) => ({
+              label: p.name,
+              value: p.name,
+              hint: p.description,
+            })),
+          );
+          setLoading(false);
+        })
+        .catch((err) => {
+          setError(err instanceof Error ? err.message : String(err));
+          setLoading(false);
+        });
+    }
+  }, [stackLength, screen, marketplace, callbacks, refreshCounter]);
+
+  return { items, loading, error };
+}

package/src/hooks/useRealCursorPosition.ts

@@ -0,0 +1,125 @@
+/**
+ * CLI-062 — position the REAL terminal cursor at the CJK composition point.
+ *
+ * Mechanism (contract: .design/investigations/2026-07-25-cli-062-ime-cursor-design.md, POC-PASS):
+ * the input box's absolute frame-space origin comes from walking the yoga `parentNode` chain from
+ * a `<Box ref>` (the `5195e326b` approach, minus its debug logging); the cell is handed to ink's
+ * `useCursor().setCursorPosition`, which converts it into a relative `cursorUp` from the frame
+ * bottom INSIDE the same atomic synchronized frame write (invariant I3: never out-of-band — all
+ * cursor movement rides ink's ≤30fps frame writes; this hook itself writes NOTHING to any stream,
+ * the PoC row-accounting lesson).
+ *
+ * Measurement happens post-commit (layout is valid there) and is stored in state so the NEXT
+ * commit's insertion effect propagates a fresh position with its frame; `useBoxMetrics` provides
+ * the layout-change subscription so sibling-driven moves re-measure too. A stale origin self-heals
+ * within one frame (ink recomputes layout before onRender and notifies layout listeners).
+ */
+
+import { useBoxMetrics, useCursor, useWindowSize } from 'ink';
+import { useEffect, useState } from 'react';
+
+import { computeCursorCell, shouldPositionRealCursor } from '../flows/real-cursor-flow.js';
+
+import type { DOMElement } from 'ink';
+import type { RefObject } from 'react';
+
+export interface IUseRealCursorPositionOptions {
+  /** Ref attached to the `<Box>` wrapping the input's text. */
+  boxRef: RefObject<DOMElement | null>;
+  /** Capability + focus gate: supportsImeCursorPositioning() && focus && showCursor. */
+  enabled: boolean;
+  /** Live input value (from the input's state ref — fresh at render time). */
+  value: string;
+  /** Live cursor character index. */
+  cursor: number;
+  /** Wrap width in columns (matches the input's own wrap math). */
+  availableWidth?: number;
+}
+
+export interface IUseRealCursorPositionResult {
+  /** True while the hardware cursor is being positioned — the drawn cursor must be suppressed. */
+  realCursorActive: boolean;
+}
+
+interface IMeasuredOrigin {
+  x: number;
+  y: number;
+  frameHeight: number;
+}
+
+/** Walk the yoga `parentNode` chain to the absolute frame-space origin, plus the root frame height. */
+function measureAbsoluteOrigin(element: DOMElement): IMeasuredOrigin | undefined {
+  if (element.yogaNode === undefined) return undefined;
+  let x = 0;
+  let y = 0;
+  let current: DOMElement | undefined = element;
+  let root: DOMElement = element;
+  while (current !== undefined) {
+    const layout = current.yogaNode?.getComputedLayout();
+    x += layout?.left ?? 0;
+    y += layout?.top ?? 0;
+    root = current;
+    current = current.parentNode;
+  }
+  const frameHeight = root.yogaNode?.getComputedLayout().height ?? 0;
+  return { x, y, frameHeight };
+}
+
+function sameOrigin(a: IMeasuredOrigin | undefined, b: IMeasuredOrigin | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.x === b.x && a.y === b.y && a.frameHeight === b.frameHeight;
+}
+
+export function useRealCursorPosition(
+  options: IUseRealCursorPositionOptions,
+): IUseRealCursorPositionResult {
+  const { setCursorPosition } = useCursor();
+  // Layout-change subscription: useBoxMetrics re-renders this component whenever the tracked
+  // box's metrics change on a root layout commit, and exposes hasMeasured for invariant I1.
+  const metrics = useBoxMetrics(options.boxRef);
+  const { rows: viewportRows } = useWindowSize();
+  const [origin, setOrigin] = useState<IMeasuredOrigin | undefined>(undefined);
+
+  // I1: never a guessed row — measure the absolute origin ONLY from a committed yoga layout
+  // (post-commit effect; ink ran calculateLayout before onRender, passive effects run after).
+  // No dependency array on purpose: any render may follow a layout change, and the setState
+  // bails out when the origin is unchanged, so this settles instead of looping.
+  useEffect(() => {
+    const element = options.boxRef.current;
+    const next = element === null ? undefined : measureAbsoluteOrigin(element);
+    setOrigin((previous) => (sameOrigin(previous, next) ? previous : next));
+  });
+
+  const cell =
+    origin !== undefined && options.enabled
+      ? computeCursorCell({
+          absX: origin.x,
+          absY: origin.y,
+          value: options.value,
+          cursor: options.cursor,
+          ...(options.availableWidth !== undefined
+            ? { availableWidth: options.availableWidth }
+            : {}),
+        })
+      : undefined;
+
+  const realCursorActive =
+    cell !== undefined &&
+    origin !== undefined &&
+    shouldPositionRealCursor({
+      hasMeasured: metrics.hasMeasured, // I1 — `origin` is already narrowed non-undefined above
+      y: cell.y,
+      frameHeight: origin.frameHeight, // I2 checked inside the guard
+      viewportRows,
+      capability: options.enabled, // I5 folded in via supportsImeCursorPositioning()
+    });
+
+  // Render-phase call is safe: useCursor only records the position in a ref; propagation happens
+  // in its insertion effect, inside ink's synchronized frame write (I3). I4: when the guard fails
+  // (blur, fullscreen frame, not measured yet) we pass `undefined` — ink hides the hardware cursor
+  // and the caller falls back to today's drawn-cursor rendering; on unmount, useCursor's cleanup
+  // propagates `undefined` by itself.
+  setCursorPosition(realCursorActive && cell !== undefined ? { x: cell.x, y: cell.y } : undefined);
+
+  return { realCursorActive };
+}

package/src/hooks/useRenderMarkdown.ts

@@ -0,0 +1,38 @@
+import { renderMarkdown } from '../render-markdown.js';
+import { useScreenReader } from '../screen-reader-context.js';
+import { useSyntaxHighlighting, useTheme } from '../theme/index.js';
+
+import type { IRenderMarkdownOptions } from '../render-markdown.js';
+
+/** What a call site still decides. The three appearance inputs are no longer among them. */
+export type TRenderMarkdownExtras = Omit<
+  IRenderMarkdownOptions,
+  'theme' | 'syntaxHighlighting' | 'screenReader'
+>;
+
+/**
+ * SCREEN-2002 — markdown rendered with this surface's resolved appearance.
+ *
+ * The three inputs every render site needs — the theme, the syntax-highlighting setting and
+ * screen-reader mode — are bound here instead of at each call. That is a deliberate removal of an
+ * obligation rather than a convenience.
+ *
+ * The obligation was forgotten once and guarded four times. `/theme syntax off` shipped persisting
+ * a setting no call site passed, so the command reported success and changed nothing; each guard
+ * written afterwards measured a PROXY for "every call site passes it" — the prop appears in the
+ * file, the file matched the regex, the identifier occurs N times — and each held for exactly one
+ * review round. A binding removes the thing being proxied: there is no per-call-site argument left
+ * to forget, and the floor collapses to a single-consumer ratchet (nothing outside this module
+ * imports `renderMarkdown`), which is a property rather than a proxy for one.
+ *
+ * Screen-reader mode is bound too, uniformly. `StreamingIndicator` previously omitted it, which was
+ * correct but only incidentally: it returns its collapsed line before reaching any markdown, so the
+ * flag never applied. Binding it removes that coincidence as something a reader has to reconstruct.
+ */
+export function useRenderMarkdown(): (md: string, extras?: TRenderMarkdownExtras) => string {
+  const theme = useTheme();
+  const syntaxHighlighting = useSyntaxHighlighting();
+  const screenReader = useScreenReader();
+  return (md, extras = {}) =>
+    renderMarkdown(md, { ...extras, theme, syntaxHighlighting, screenReader });
+}

package/src/hooks/useScreenReaderTurnSignals.ts

@@ -0,0 +1,113 @@
+/**
+ * CLI-2004 — the non-visual half of a turn: the bell and the OSC 133 boundary marks.
+ *
+ * Both are byte-stream events, not rendering, so they live in a hook rather than a component: the
+ * App says WHEN a turn starts, ends, or wants an answer, and this decides what reaches the terminal.
+ * When the mode is off both writers are inert, so the App has exactly one code path.
+ *
+ * One turn emits `A` (prompt start) → `B` (prompt end) → `C` (turn start) → `D` (turn end): the
+ * prompt is marked while the user is being asked for input, and the execution pair brackets the
+ * agent's work. That is the boundary a reader jumps between.
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+
+import { createAttentionBell } from '../attention-bell.js';
+import { useScreenReaderPacing } from '../screen-reader-pacing-context.js';
+import { supportsTurnMarks } from '../terminal-capabilities.js';
+import { useTerminalCapabilityOverrides } from '../terminal-capabilities-context.js';
+import { createTurnMarkWriter } from '../terminal-marks.js';
+
+import type { IAttentionBell } from '../attention-bell.js';
+import type { IToolState } from '@robota-sdk/agent-interface-session';
+
+export interface IUseScreenReaderTurnSignalsInputs {
+  enabled: boolean;
+  /** The agent is working (a turn is in flight). */
+  isThinking: boolean;
+  /** Tools currently reported as active by the session. */
+  activeTools: readonly IToolState[];
+  /** A permission ask or user-action dialog is mounted and waiting for an answer. */
+  awaitingAnswer: boolean;
+}
+
+/**
+ * Stable key for one tool run within a turn.
+ *
+ * `executionId` where the session supplies one; otherwise the position, which `onToolEnd` preserves
+ * (it replaces the entry at its index rather than removing it).
+ */
+function toolKey(tool: IToolState, index: number): string {
+  return tool.executionId ?? `${tool.toolName}#${index}`;
+}
+
+/** The keys of the tools currently RUNNING — not merely present in the array. */
+function runningKeys(activeTools: readonly IToolState[]): Set<string> {
+  const running = new Set<string>();
+  activeTools.forEach((tool, index) => {
+    if (tool.isRunning) running.add(toolKey(tool, index));
+  });
+  return running;
+}
+
+/** Wire the bell and the turn marks to the App's turn lifecycle. */
+export function useScreenReaderTurnSignals(inputs: IUseScreenReaderTurnSignalsInputs): void {
+  const { enabled, isThinking, activeTools, awaitingAnswer } = inputs;
+  const bell = useMemo<IAttentionBell>(() => createAttentionBell({ enabled }), [enabled]);
+  // SCREEN-2670: the marks are POSITIONAL — the terminal records the line they arrive on — so they
+  // travel through the owned write path, ordered with the commit they belong to. Outside a provider
+  // the port writes to the process's own stdout, which is exactly today's path.
+  const pacing = useScreenReaderPacing();
+  const terminalCapabilities = useTerminalCapabilityOverrides();
+  const marks = useMemo(
+    () =>
+      createTurnMarkWriter({
+        enabled,
+        supported: () => supportsTurnMarks({ override: terminalCapabilities.turnMarks }),
+        write: (text) => pacing.write(text),
+      }),
+    [enabled, pacing, terminalCapabilities.turnMarks],
+  );
+  const wasThinking = useRef(false);
+  const runningTools = useRef<ReadonlySet<string>>(new Set());
+
+  // Turn boundaries: B/C when work starts, D/A when it ends and the prompt comes back.
+  useEffect(() => {
+    if (isThinking && !wasThinking.current) {
+      marks.emit('promptEnd');
+      marks.emit('turnStart');
+    } else if (!isThinking && wasThinking.current) {
+      marks.emit('turnEnd');
+      marks.emit('promptStart');
+      bell.replyCompleted();
+    }
+    wasThinking.current = isThinking;
+  }, [isThinking, bell, marks]);
+
+  // The very first prompt of the session is marked once, before anything has been asked.
+  useEffect(() => {
+    marks.emit('promptStart');
+  }, [marks]);
+
+  // A prompt or dialog that wants an answer rings once on mount.
+  useEffect(() => {
+    if (awaitingAnswer) bell.promptMounted();
+  }, [awaitingAnswer, bell]);
+
+  // Long-running tools: record each start, ring on the completions that outlived the threshold.
+  //
+  // Completion is the `isRunning` true→false transition, NOT the entry leaving the array. The
+  // session's `onToolEnd` replaces the finished entry in place (same index, same name, so the same
+  // key) and only `onThinking(false)` empties the array — so a membership test would report every
+  // tool as completing at turn end, judging its duration against the whole turn.
+  useEffect(() => {
+    const running = runningKeys(activeTools);
+    for (const key of running) {
+      if (!runningTools.current.has(key)) bell.toolStarted(key);
+    }
+    for (const key of runningTools.current) {
+      if (!running.has(key)) bell.toolCompleted(key);
+    }
+    runningTools.current = running;
+  }, [activeTools, bell]);
+}