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

package/src/MultiSelectList.tsx

@@ -0,0 +1,294 @@
+/**
+ * Multi-select checklist (CMD-004): arrow-key navigation, Space toggles, Enter confirms once the
+ * selection count is within [minSelect, maxSelect], Esc cancels. Used by PendingActionPrompt for an
+ * IActionRequest whose `maxSelect` > 1.
+ *
+ * Note: unlike ListPicker, this renders all options without a scroll viewport — `IActionRequest`'s
+ * optional `maxVisible` hint is not yet honored here (multi-select lists are typically short). Adding a
+ * viewport is a follow-up if long multi-select lists appear.
+ */
+
+import { Box } from 'ink';
+import React, { useState } from 'react';
+
+import { useNumberedSelection } from './hooks/useNumberedSelection.js';
+import {
+  KeyHintFooter,
+  SELECTION_INDICATOR,
+  SELECTION_INDICATOR_NONE,
+  type IKeyHint,
+} from './key-hint-footer.js';
+import { useKeybindingActions, useKeybindingHints } from './keybindings/keybindings-context.js';
+import { NumberedSelectionPrompt, numberedRowPrefix } from './numbered-list.js';
+import { Text } from './SafeText.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { usePalette } from './theme/index.js';
+
+import type { IActionOption } from '@robota-sdk/agent-core';
+
+/**
+ * Footer hints for the multi-select checklist. The Enter hint carries a dynamic `(min N)` segment
+ * until the selection is confirmable.
+ */
+export function getMultiSelectFooterHints(input: {
+  canConfirm: boolean;
+  minSelect: number;
+}): readonly IKeyHint[] {
+  return [
+    { keys: '↑↓', label: 'Navigate' },
+    { keys: 'Space', label: 'Toggle' },
+    { keys: 'Enter', label: input.canConfirm ? 'Confirm' : `Confirm (min ${input.minSelect})` },
+    { keys: 'Esc', label: 'Cancel' },
+  ];
+}
+
+/**
+ * One checklist row. The mode swaps the position cue — a spoken number for the `> ` cursor and its
+ * colour — and nothing else: the checkbox is what says selected, in both.
+ */
+function ChecklistRow({
+  label,
+  index,
+  isCursor,
+  isChecked,
+  screenReader,
+}: {
+  label: string;
+  index: number;
+  isCursor: boolean;
+  isChecked: boolean;
+  screenReader: boolean;
+}): React.ReactElement {
+  const palette = usePalette();
+  const box = isChecked ? '[x] ' : '[ ] ';
+  if (screenReader) {
+    return (
+      <Text>
+        {numberedRowPrefix(index)}
+        {box}
+        {label}
+      </Text>
+    );
+  }
+  return (
+    <Text color={isCursor ? palette.text.accent : undefined}>
+      {isCursor ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+      {box}
+      {label}
+    </Text>
+  );
+}
+
+export interface IMultiSelectListProps {
+  title: string;
+  description?: string;
+  options: readonly IActionOption[];
+  minSelect: number;
+  maxSelect: number;
+  defaultValues?: readonly string[];
+  onConfirm: (values: string[]) => void;
+  onCancel: () => void;
+}
+
+/** The arrow-key driver: cursor motion, Space toggles, Enter confirms. Inactive in the mode. */
+function useChecklistArrowKeys(inputs: {
+  active: boolean;
+  itemCount: number;
+  setCursor: React.Dispatch<React.SetStateAction<number>>;
+  onToggleAtCursor: () => void;
+  onConfirm: () => void;
+  onCancel: () => void;
+}): void {
+  const { active, itemCount, setCursor } = inputs;
+  useKeybindingActions(
+    'multi-select',
+    (actions) => {
+      for (const action of actions) {
+        if (action === 'previous') {
+          setCursor((c) => (c <= 0 ? itemCount - 1 : c - 1));
+        } else if (action === 'next') {
+          setCursor((c) => (c >= itemCount - 1 ? 0 : c + 1));
+        } else if (action === 'toggle') {
+          inputs.onToggleAtCursor();
+        } else if (action === 'confirm') {
+          inputs.onConfirm();
+        } else if (action === 'cancel') {
+          inputs.onCancel();
+        }
+      }
+    },
+    { isActive: active },
+  );
+}
+
+/** How the checklist asks for an answer: a spoken range in the mode, the key hints otherwise. */
+function ChecklistAnswer(props: {
+  screenReader: boolean;
+  itemCount: number;
+  numbered: { buffer: string; invalid: boolean };
+  canConfirm: boolean;
+  minSelect: number;
+}): React.ReactElement {
+  const hints = useKeybindingHints('multi-select', [
+    [['previous', 'next'], 'Navigate'],
+    ['toggle', 'Toggle'],
+    ['confirm', props.canConfirm ? 'Confirm' : `Confirm (min ${props.minSelect})`],
+    ['cancel', 'Cancel'],
+  ]);
+  if (props.screenReader) {
+    return (
+      <NumberedSelectionPrompt
+        itemCount={props.itemCount}
+        cancellable
+        buffer={props.numbered.buffer}
+        invalid={props.numbered.invalid}
+      />
+    );
+  }
+  return <KeyHintFooter hints={hints} />;
+}
+
+/** The rendered checklist: the rows, and whichever answer affordance the mode calls for. */
+function ChecklistView(props: {
+  title: string;
+  description?: string;
+  options: readonly IActionOption[];
+  cursor: number;
+  selected: ReadonlySet<string>;
+  screenReader: boolean;
+  canConfirm: boolean;
+  minSelect: number;
+  numbered: { buffer: string; invalid: boolean };
+}): React.ReactElement {
+  const palette = usePalette();
+  const { title, description, options, cursor, selected, screenReader, numbered } = props;
+  return (
+    <Box
+      flexDirection="column"
+      {...(screenReader
+        ? {}
+        : { borderStyle: 'round' as const, borderColor: palette.border.attention })}
+      paddingX={1}
+    >
+      <Text color={palette.text.warning} bold>
+        {title}
+      </Text>
+      {description !== undefined && description.length > 0 && <Text dimColor>{description}</Text>}
+      {options.map((option, index) => (
+        <ChecklistRow
+          key={option.value}
+          label={option.label}
+          index={index}
+          isCursor={index === cursor}
+          isChecked={selected.has(option.value)}
+          screenReader={screenReader}
+        />
+      ))}
+      <ChecklistAnswer
+        screenReader={screenReader}
+        itemCount={options.length}
+        numbered={numbered}
+        canConfirm={props.canConfirm}
+        minSelect={props.minSelect}
+      />
+    </Box>
+  );
+}
+
+/** The checklist's own state: which row the cursor is on, what is ticked, and how it commits. */
+function useChecklistSelection(inputs: {
+  options: readonly IActionOption[];
+  minSelect: number;
+  maxSelect: number;
+  defaultValues?: readonly string[];
+  onConfirm: (values: string[]) => void;
+}): {
+  cursor: number;
+  setCursor: React.Dispatch<React.SetStateAction<number>>;
+  selected: ReadonlySet<string>;
+  toggleAt: (index: number) => void;
+  confirmIfAllowed: () => void;
+} {
+  const { options, minSelect, maxSelect, defaultValues, onConfirm } = inputs;
+  const [cursor, setCursor] = useState(0);
+  const [selected, setSelected] = useState<ReadonlySet<string>>(() => new Set(defaultValues ?? []));
+
+  const toggleAt = (index: number): void => {
+    const option = options[index];
+    if (option === undefined) return;
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(option.value)) {
+        next.delete(option.value);
+      } else if (next.size < maxSelect) {
+        next.add(option.value);
+      }
+      return next;
+    });
+  };
+  const confirmIfAllowed = (): void => {
+    if (selected.size >= minSelect) onConfirm([...selected]);
+  };
+
+  return { cursor, setCursor, selected, toggleAt, confirmIfAllowed };
+}
+
+export default function MultiSelectList({
+  title,
+  description,
+  options,
+  minSelect,
+  maxSelect,
+  defaultValues,
+  onConfirm,
+  onCancel,
+}: IMultiSelectListProps): React.ReactElement {
+  // CLI-2004: the checklist keeps its own reducer (Space toggles, Enter confirms) — what the mode
+  // changes is the ROW: a spoken number replaces the `> ` cursor, and typing that number toggles it.
+  const screenReader = useScreenReader();
+  const { cursor, setCursor, selected, toggleAt, confirmIfAllowed } = useChecklistSelection({
+    options,
+    minSelect,
+    maxSelect,
+    defaultValues,
+    onConfirm,
+  });
+
+  // CLI-2004: the checklist answers by number in the mode, through the SAME reducer every other
+  // numbered menu uses — `multi` is what keeps it open after a toggle and makes an empty Enter the
+  // commit. A local digit branch would have capped it at nine rows and skipped the shared prompt.
+  const numbered = useNumberedSelection({
+    enabled: screenReader,
+    itemCount: options.length,
+    cancellable: true,
+    multi: true,
+    onSelect: toggleAt,
+    onConfirm: confirmIfAllowed,
+    onCancel,
+  });
+
+  useChecklistArrowKeys({
+    active: !screenReader,
+    itemCount: options.length,
+    setCursor,
+    onToggleAtCursor: () => toggleAt(cursor),
+    onConfirm: confirmIfAllowed,
+    onCancel,
+  });
+
+  const canConfirm = selected.size >= minSelect;
+
+  return (
+    <ChecklistView
+      title={title}
+      {...(description !== undefined ? { description } : {})}
+      options={options}
+      cursor={cursor}
+      selected={selected}
+      screenReader={screenReader}
+      canConfirm={canConfirm}
+      minSelect={minSelect}
+      numbered={numbered}
+    />
+  );
+}

package/src/PendingActionPrompt.tsx

@@ -0,0 +1,121 @@
+/**
+ * PendingActionPrompt (CMD-004) — the TUI renderer for the unified `IActionRequest`. It derives the
+ * presentation from the request's fields (not a kind switch):
+ * - no options                → free-text (TextPrompt, honoring `masked`/`placeholder`/`allowEmpty`)
+ * - options, `maxSelect` > 1   → multi-select checklist (MultiSelectList)
+ * - options, `maxSelect` <= 1  → single-select list (ListPicker); with `allowFreeText`, a synthetic
+ *                                "Type a custom answer…" entry switches to a text field
+ *
+ * It always resolves the caller's `onAnswer` with a `TActionResponse` (answer or cancelled).
+ */
+
+import { Box } from 'ink';
+import React, { useState } from 'react';
+
+import { SELECTION_INDICATOR, SELECTION_INDICATOR_NONE } from './key-hint-footer.js';
+import ListPicker from './ListPicker.js';
+import MultiSelectList from './MultiSelectList.js';
+import { Text } from './SafeText.js';
+import TextPrompt from './TextPrompt.js';
+import { usePalette } from './theme/index.js';
+
+import type { IActionOption, IActionRequest, TActionResponse } from '@robota-sdk/agent-core';
+
+interface IPendingActionPromptProps {
+  request: IActionRequest;
+  onAnswer: (response: TActionResponse) => void;
+}
+
+/**
+ * Synthetic "type a custom answer" entry for a single-select with free text. Routed by object identity
+ * (reference equality), not by a magic value — so it can never collide with a real option's `value`.
+ */
+const FREE_TEXT_OPTION: IActionOption = { value: '', label: 'Type a custom answer…' };
+
+export default function PendingActionPrompt({
+  request,
+  onAnswer,
+}: IPendingActionPromptProps): React.ReactElement {
+  const palette = usePalette();
+  const [freeTextMode, setFreeTextMode] = useState(false);
+
+  const options = request.options ?? [];
+  const hasOptions = options.length > 0;
+  const maxSelect = request.maxSelect ?? 1;
+  const cancel = (): void => onAnswer({ type: 'cancelled' });
+
+  // Pure free-text (no options) — or the user chose "type a custom answer" on a single-select.
+  if (!hasOptions || freeTextMode) {
+    return (
+      <TextPrompt
+        key={`text:${request.id}`}
+        title={request.title}
+        description={request.description}
+        placeholder={request.placeholder}
+        allowEmpty={request.allowEmpty}
+        masked={request.masked}
+        onSubmit={(value) => onAnswer({ type: 'answer', values: [], text: value })}
+        onCancel={freeTextMode ? () => setFreeTextMode(false) : cancel}
+      />
+    );
+  }
+
+  // Multi-select.
+  if (maxSelect > 1) {
+    return (
+      <MultiSelectList
+        title={request.title}
+        description={request.description}
+        options={options}
+        minSelect={request.minSelect ?? 1}
+        maxSelect={maxSelect}
+        defaultValues={request.default?.values}
+        onConfirm={(values) => onAnswer({ type: 'answer', values })}
+        onCancel={cancel}
+      />
+    );
+  }
+
+  // Single-select, optionally with a "type your own" entry (routed by identity, see FREE_TEXT_OPTION).
+  const pickerItems: IActionOption[] = request.allowFreeText
+    ? [...options, FREE_TEXT_OPTION]
+    : [...options];
+  // BEHAVIOR-2437: a request's declared default is where the highlight STARTS — for a write
+  // confirmation built with `defaultYes: false`, a bare Enter must answer No, not Yes.
+  const defaultValue = request.default?.values?.[0];
+  const initialIndex =
+    defaultValue === undefined
+      ? 0
+      : Math.max(
+          0,
+          pickerItems.findIndex((option) => option.value === defaultValue),
+        );
+
+  return (
+    <Box flexDirection="column">
+      <Text bold>{request.title}</Text>
+      {request.description !== undefined && request.description.length > 0 && (
+        <Text dimColor>{request.description}</Text>
+      )}
+      <ListPicker<IActionOption>
+        items={pickerItems}
+        initialIndex={initialIndex}
+        maxVisible={request.maxVisible}
+        renderItem={(option, isSelected) => (
+          <Text color={isSelected ? palette.text.accent : undefined}>
+            {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+            {option.label}
+          </Text>
+        )}
+        onSelect={(option) => {
+          if (option === FREE_TEXT_OPTION) {
+            setFreeTextMode(true);
+          } else {
+            onAnswer({ type: 'answer', values: [option.value] });
+          }
+        }}
+        onCancel={cancel}
+      />
+    </Box>
+  );
+}

package/src/PermissionPrompt.tsx

@@ -0,0 +1,186 @@
+import { consentScopeFor } from '@robota-sdk/agent-framework';
+import { Box } from 'ink';
+import React from 'react';
+
+import {
+  applyPermissionPromptInput,
+  permissionPromptOptionsFor,
+  type TPermissionPromptInputAction,
+} from './flows/permission-prompt-flow.js';
+import { createSelectionFlowState, type ISelectionFlowState } from './flows/selection-flow.js';
+import { useNumberedSelection } from './hooks/useNumberedSelection.js';
+import {
+  KeyHintFooter,
+  SELECTION_INDICATOR,
+  SELECTION_INDICATOR_NONE,
+  type IKeyHint,
+} from './key-hint-footer.js';
+import { useKeybindingActions, useKeybindingHints } from './keybindings/keybindings-context.js';
+import { NumberedList } from './numbered-list.js';
+import { Text } from './SafeText.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { SCREEN_READER_LABELS } from './screen-reader-labels.js';
+import { usePalette } from './theme/index.js';
+
+import type { IPendingPermissionRequest } from './types.js';
+import type { TToolArgs } from '@robota-sdk/agent-core';
+
+interface IProps {
+  request: IPendingPermissionRequest;
+}
+
+/**
+ * Footer for the permission prompt — identical to the confirm prompt's (same horizontal row, same
+ * reducer). Esc is deliberately suppressed by the flow (`escape: false` — a permission ask must
+ * resolve explicitly; Esc-dismissal would be an implicit deny), so the footer omits it.
+ */
+export const PERMISSION_PROMPT_FOOTER_HINTS: readonly IKeyHint[] = [
+  { keys: '←→', label: 'Navigate' },
+  { keys: 'Enter', label: 'Confirm' },
+];
+
+function formatArgs(args: TToolArgs): string {
+  const entries = Object.entries(args);
+  if (entries.length === 0) return '(no arguments)';
+  return entries
+    .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+    .join(', ');
+}
+
+export default function PermissionPrompt({ request }: IProps): React.ReactElement {
+  const palette = usePalette();
+  const canPersistProjectPermission = request.canPersistProjectPermission !== false;
+  const [state, setState] = React.useState<ISelectionFlowState>(() => createSelectionFlowState());
+  const stateRef = React.useRef(state);
+  const prevRequestRef = React.useRef(request);
+
+  if (prevRequestRef.current !== request) {
+    prevRequestRef.current = request;
+    const nextState = createSelectionFlowState();
+    stateRef.current = nextState;
+    setState(nextState);
+  }
+
+  const applyAction = React.useCallback(
+    (action: TPermissionPromptInputAction): void => {
+      const result = applyPermissionPromptInput(
+        stateRef.current,
+        action,
+        canPersistProjectPermission,
+      );
+      stateRef.current = result.state;
+      setState(result.state);
+      if (result.effect.type === 'resolve') {
+        request.resolve(result.effect.decision);
+      }
+    },
+    [request, canPersistProjectPermission],
+  );
+
+  const screenReader = useScreenReader();
+  const options = permissionPromptOptionsFor(
+    consentScopeFor(request.toolName, request.toolArgs),
+    canPersistProjectPermission,
+  );
+  const numbered = useNumberedSelection({
+    enabled: screenReader,
+    itemCount: options.length,
+    onSelect: (index) => {
+      const result = applyPermissionPromptInput(
+        stateRef.current,
+        {
+          type: 'shortcut',
+          index,
+        },
+        canPersistProjectPermission,
+      );
+      stateRef.current = result.state;
+      setState(result.state);
+      if (result.effect.type === 'resolve') request.resolve(result.effect.decision);
+    },
+  });
+
+  useKeybindingActions(
+    'permission-prompt',
+    (actions) => {
+      const shortcutIndex = {
+        'allow-once': 0,
+        'allow-session': 1,
+        'allow-project': 2,
+        deny: 3,
+      } as const;
+      for (const action of actions) {
+        if (action in shortcutIndex) {
+          applyAction({
+            type: 'shortcut',
+            index: shortcutIndex[action as keyof typeof shortcutIndex],
+          });
+        } else if (action === 'previous' || action === 'next' || action === 'confirm') {
+          applyAction(action === 'confirm' ? 'select' : action);
+        }
+      }
+    },
+    { isActive: !screenReader },
+  );
+  const footerHints = useKeybindingHints('permission-prompt', [
+    [['previous', 'next'], 'Navigate'],
+    ['confirm', 'Confirm'],
+  ]);
+
+  if (screenReader) {
+    return (
+      <NumberedList
+        title={SCREEN_READER_LABELS.permissionRequired}
+        description={`${request.toolName} — ${formatArgs(request.toolArgs)}${
+          request.requestedByPeer !== undefined
+            ? ` (requested by another session: ${request.requestedByPeer})`
+            : ''
+        }`}
+        options={options}
+        buffer={numbered.buffer}
+        invalid={numbered.invalid}
+      />
+    );
+  }
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={palette.border.attention}
+      paddingX={1}
+    >
+      <Text color={palette.text.warning} bold>
+        [Permission Required]
+      </Text>
+      <Text>
+        Tool:{' '}
+        <Text color={palette.text.accent} bold>
+          {request.toolName}
+        </Text>
+      </Text>
+      <Text dimColor> {formatArgs(request.toolArgs)}</Text>
+      {request.requestedByPeer !== undefined ? (
+        <Text color={palette.text.warning}>
+          Requested by another session: {request.requestedByPeer}
+        </Text>
+      ) : null}
+      {/* Issue #2351: the "always" options carry the consent scope, so they no longer fit one row
+          of the prompt box — a row wrapped `Allow [y]` across two lines. One option per line. */}
+      <Box marginTop={1} flexDirection="column">
+        {options.map((opt, i) => (
+          <Box key={opt}>
+            <Text
+              color={i === state.selectedIndex ? palette.text.accent : undefined}
+              bold={i === state.selectedIndex}
+            >
+              {i === state.selectedIndex ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+              {opt}
+            </Text>
+          </Box>
+        ))}
+      </Box>
+      <KeyHintFooter hints={footerHints} />
+    </Box>
+  );
+}