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

package/src/hooks/useAppInputBindings.ts

@@ -0,0 +1,163 @@
+import { useApp, useInput } from 'ink';
+import { useEffect } from 'react';
+
+import { useKeybindingActions } from '../keybindings/keybindings-context.js';
+import { useScreenReader } from '../screen-reader-context.js';
+import { handleInterrupt } from '../shutdown-signal.js';
+import { useScreenReaderTurnSignals } from './useScreenReaderTurnSignals.js';
+
+import type { IPendingPermissionRequest } from '../types.js';
+import type { IActionRequest, TSessionEndReason } from '@robota-sdk/agent-core';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+import type { IToolState } from '@robota-sdk/agent-interface-session';
+
+interface IOptions {
+  readonly isThinking: boolean;
+  readonly isShuttingDown: boolean;
+  /** An observer stops nothing: neither the drivers' turn nor their loop. */
+  readonly readOnly: boolean;
+  /** Attached to a session a host runs: Ctrl-] detaches, like Ctrl-C and `/exit` there. */
+  readonly attached: boolean;
+  readonly permissionRequest: IPendingPermissionRequest | null;
+  readonly pendingUserAction: IActionRequest | null;
+  readonly pluginVisible: boolean;
+  readonly transportVisible: boolean;
+  readonly sessionPickerVisible: boolean;
+  readonly workspaceSwitcherVisible: boolean;
+  /** SCREEN-1993: the history-search overlay owns Esc and the switcher key while open. */
+  readonly historySearchOpen: boolean;
+  readonly selectedEntry: IExecutionWorkspaceEntry | undefined;
+  readonly backgroundListFocused: boolean;
+  readonly mainThreadEntryId: string | undefined;
+  readonly activeTools: readonly IToolState[];
+  readonly abort: () => void;
+  readonly stopWaitingLoop: () => Promise<void>;
+  readonly toggleWorkspaceSwitcher: () => void;
+  readonly selectWorkspaceEntry: (entryId: string) => void;
+  readonly shutdown: (reason?: TSessionEndReason) => Promise<void>;
+  readonly recoveryError: string | undefined;
+  readonly recoveryPending: boolean;
+  readonly coordinationBlocked: boolean;
+  /** SCREEN-2002: the theme picker owns its keys while it is open, like every sibling overlay. */
+  readonly themePickerVisible: boolean;
+  readonly retryRecovery: () => void;
+}
+
+function overlaysBlockKeys(options: IOptions): boolean {
+  return Boolean(
+    options.permissionRequest ||
+    options.pendingUserAction ||
+    options.pluginVisible ||
+    options.transportVisible ||
+    options.sessionPickerVisible ||
+    options.workspaceSwitcherVisible ||
+    options.historySearchOpen ||
+    options.themePickerVisible ||
+    options.coordinationBlocked,
+  );
+}
+
+function useEscapeBindings(options: IOptions): void {
+  const context = options.isThinking ? 'thinking' : 'background-detail';
+  useKeybindingActions(context, (actions) => {
+    if (overlaysBlockKeys(options)) return;
+    if (actions.includes('abort') && options.isThinking) {
+      if (!options.readOnly) options.abort();
+      return;
+    }
+    const selected = options.selectedEntry;
+    if (
+      actions.includes('return-to-main') &&
+      selected &&
+      selected.kind !== 'main_thread' &&
+      options.mainThreadEntryId
+    ) {
+      options.selectWorkspaceEntry(options.mainThreadEntryId);
+      return;
+    }
+    if (
+      actions.includes('return-to-main') &&
+      !options.backgroundListFocused &&
+      !options.readOnly
+    ) {
+      void options.stopWaitingLoop();
+    }
+  });
+}
+
+function useWorkspaceSwitcherBinding(options: IOptions): void {
+  useKeybindingActions('app', (actions) => {
+    if (!actions.includes('open-workspace-switcher')) return;
+    if (
+      options.permissionRequest ||
+      options.pendingUserAction ||
+      options.pluginVisible ||
+      options.sessionPickerVisible ||
+      options.historySearchOpen ||
+      options.themePickerVisible ||
+      options.coordinationBlocked ||
+      options.isShuttingDown
+    )
+      return;
+    options.toggleWorkspaceSwitcher();
+  });
+}
+
+function useRecoveryBinding(options: IOptions): void {
+  useKeybindingActions('recovery', (actions) => {
+    if (
+      options.recoveryError !== undefined &&
+      !options.recoveryPending &&
+      actions.includes('retry')
+    ) {
+      options.retryRecovery();
+    }
+  });
+}
+
+/** Ctrl-]: the raw byte, or `]` with ctrl where the terminal reports modifiers. */
+const DETACH_BYTE = '\x1d';
+
+function isDetachKey(input: string, ctrl: boolean): boolean {
+  return input === DETACH_BYTE || (ctrl && input === ']');
+}
+
+function useShutdownBindings(options: IOptions): void {
+  const { exit } = useApp();
+  const requestShutdown = (reason: TSessionEndReason): void => {
+    handleInterrupt({
+      isShuttingDown: options.isShuttingDown,
+      graceful: () => void options.shutdown(reason).finally(() => exit()),
+    });
+  };
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') requestShutdown('prompt_input_exit');
+    // Ctrl-] is the attach client's detach key. On a terminal running its own session there is
+    // nothing to detach from, and quitting that session is left to Ctrl-C and `/exit`.
+    else if (options.attached && isDetachKey(input, key.ctrl)) requestShutdown('prompt_input_exit');
+  });
+  useEffect(() => {
+    const onSignal = (): void => requestShutdown('other');
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    return () => {
+      process.off('SIGINT', onSignal);
+      process.off('SIGTERM', onSignal);
+    };
+  });
+}
+
+export function useAppInputBindings(options: IOptions): boolean {
+  useEscapeBindings(options);
+  useRecoveryBinding(options);
+  useWorkspaceSwitcherBinding(options);
+  useShutdownBindings(options);
+  const screenReader = useScreenReader();
+  useScreenReaderTurnSignals({
+    enabled: screenReader,
+    isThinking: options.isThinking,
+    activeTools: options.activeTools,
+    awaitingAnswer: options.permissionRequest !== null || options.pendingUserAction !== null,
+  });
+  return screenReader;
+}

package/src/hooks/useAppInteractionState.ts

@@ -0,0 +1,84 @@
+import { useAppInputBindings } from './useAppInputBindings.js';
+import { useAppOverlays } from './useAppOverlays.js';
+import { useAppSubmissionState } from './useAppSubmissionState.js';
+
+import type { IAppOverlays } from './useAppOverlays.js';
+import type { IAppScreenState } from './useAppScreenState.js';
+import type { IAppSubmissionState } from './useAppSubmissionState.js';
+import type { ITuiChannelState } from './useTuiChannel.js';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+interface IOptions {
+  readonly cwd: string;
+  readonly state: ITuiChannelState;
+  readonly shell: IAppScreenState;
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly onSessionSwitch: (sessionId: string) => Promise<void>;
+  readonly pluginAdapter: ICommandPluginAdapter | undefined;
+  readonly transportRegistry: ITransportRegistryView | undefined;
+  readonly recoveryError: string | undefined;
+  readonly recoveryPending: boolean;
+  readonly coordinationBlocked: boolean;
+  readonly retryRecovery: () => void;
+}
+
+export interface IAppInteractionState {
+  readonly submission: IAppSubmissionState;
+  readonly overlays: IAppOverlays;
+  readonly screenReader: boolean;
+}
+
+export function useAppInteractionState(options: IOptions): IAppInteractionState {
+  const { screens, workspace } = options.shell;
+  const submission = useAppSubmissionState({
+    selectedEntry: workspace.background.selectedEntry,
+    submit: screens.handleSubmit,
+    sendAgentJob: options.state.sendAgentJob,
+    isThinking: options.state.isThinking,
+  });
+  const screenReader = useAppInputBindings({
+    isThinking: options.state.isThinking,
+    isShuttingDown: options.state.isShuttingDown,
+    readOnly: options.state.readOnly,
+    attached: options.state.attached,
+    permissionRequest: options.state.permissionRequest,
+    pendingUserAction: options.state.pendingUserAction,
+    pluginVisible: screens.showPluginTUI,
+    transportVisible: screens.showTransportTUI,
+    sessionPickerVisible: screens.showSessionPicker,
+    workspaceSwitcherVisible: workspace.background.switcherVisible,
+    historySearchOpen: options.shell.historySearchOpen,
+    themePickerVisible: screens.showThemePicker,
+    selectedEntry: workspace.background.selectedEntry,
+    backgroundListFocused: workspace.isBackgroundListFocused,
+    mainThreadEntryId: workspace.mainThreadEntryId,
+    activeTools: options.state.activeTools,
+    abort: options.state.handleAbort,
+    stopWaitingLoop: options.state.handleStopWaitingLoop,
+    toggleWorkspaceSwitcher: workspace.toggleSwitcher,
+    selectWorkspaceEntry: options.state.selectExecutionWorkspaceEntry,
+    shutdown: options.state.handleShutdown,
+    recoveryError: options.recoveryError,
+    recoveryPending: options.recoveryPending,
+    coordinationBlocked: options.coordinationBlocked,
+    retryRecovery: options.retryRecovery,
+  });
+  const overlays = useAppOverlays({
+    cwd: options.cwd,
+    pluginAdapter: options.pluginAdapter,
+    pluginVisible: screens.showPluginTUI,
+    setPluginVisible: screens.setShowPluginTUI,
+    transportRegistry: options.transportRegistry,
+    transportVisible: screens.showTransportTUI,
+    setTransportVisible: screens.setShowTransportTUI,
+    sessionStore: options.sessionStore,
+    hostSessions: options.state.hostSessions,
+    sessionPickerVisible: screens.showSessionPicker,
+    setSessionPickerVisible: screens.setShowSessionPicker,
+    onSessionSwitch: options.onSessionSwitch,
+    addEntry: options.state.addEntry,
+  });
+  return { submission, overlays, screenReader };
+}

package/src/hooks/useAppLifecycleState.ts

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import { useTerminalTitle } from '../use-terminal-title.js';
+import { useTerminalHandoffSuspension } from './useTerminalHandoffSuspension.js';
+
+import type { ITuiAppChannelPort } from '../tui-app-channel-port.js';
+
+export interface IAppLifecycleState {
+  readonly sessionName: string | undefined;
+  readonly setSessionName: (name: string) => void;
+  readonly handoffSuspended: boolean;
+  readonly updateNotice: string | undefined;
+  readonly startError: string | undefined;
+  readonly startPending: boolean;
+  readonly retryStart: () => void;
+}
+
+function useChannelLifecycle(channel: ITuiAppChannelPort): {
+  startError: string | undefined;
+  startPending: boolean;
+  retryStart: () => void;
+} {
+  const [startError, setStartError] = useState<string | undefined>();
+  const [startPending, setStartPending] = useState(true);
+  const retryStart = useCallback((): void => {
+    setStartPending(true);
+    void channel
+      .start()
+      .then(() => setStartError(undefined))
+      .catch((cause) => {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        setStartError(`TUI start failed: ${message}`);
+      })
+      .finally(() => setStartPending(false));
+  }, [channel]);
+  useEffect(() => {
+    retryStart();
+  }, [channel, retryStart]);
+  return { startError, startPending, retryStart };
+}
+
+function useStartupUpdateNotice(source?: Promise<string | undefined>): string | undefined {
+  const [notice, setNotice] = useState<string | undefined>();
+  useEffect(() => {
+    let mounted = true;
+    source
+      ?.then((value) => {
+        if (mounted && value !== undefined) setNotice(value);
+      })
+      .catch(() => {
+        // Startup update checks are best-effort and must not disrupt the TUI.
+      });
+    return () => {
+      mounted = false;
+    };
+  }, [source]);
+  return notice;
+}
+
+export function useAppLifecycleState(
+  channel: ITuiAppChannelPort,
+  startupUpdateNotice?: Promise<string | undefined>,
+): IAppLifecycleState {
+  const channelLifecycle = useChannelLifecycle(channel);
+  const [sessionName, setSessionName] = useState<string | undefined>(channel.sessionName);
+  useEffect(() => {
+    if (channel.sessionName !== undefined && channel.sessionName !== sessionName) {
+      setSessionName(channel.sessionName);
+    }
+  }, [channel, channel.sessionName, sessionName]);
+  useTerminalTitle(sessionName);
+  const handoffSuspended = useTerminalHandoffSuspension(channel.terminalHandoffController);
+  const updateNotice = useStartupUpdateNotice(startupUpdateNotice);
+  return {
+    sessionName,
+    setSessionName,
+    handoffSuspended,
+    updateNotice,
+    ...channelLifecycle,
+  };
+}

package/src/hooks/useAppOverlays.ts

@@ -0,0 +1,90 @@
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import { listResumableSessionSummaries } from '@robota-sdk/agent-framework';
+import { useCallback, useEffect } from 'react';
+
+import { usePluginCallbacks } from './usePluginCallbacks.js';
+
+import type {
+  IAppPluginViewModel,
+  IAppSessionPickerViewModel,
+  IAppTransportViewModel,
+} from '../app-view-model.js';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+import type {
+  IInteractiveSessionStore,
+  ISessionListingEntry,
+} from '@robota-sdk/agent-interface-session';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+interface IOptions {
+  readonly cwd: string;
+  readonly pluginAdapter: ICommandPluginAdapter | undefined;
+  readonly pluginVisible: boolean;
+  readonly setPluginVisible: (visible: boolean) => void;
+  readonly transportRegistry: ITransportRegistryView | undefined;
+  readonly transportVisible: boolean;
+  readonly setTransportVisible: (visible: boolean) => void;
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  /** The host's sessions, when the channel's host keeps them; they replace the local store's. */
+  readonly hostSessions: readonly ISessionListingEntry[] | undefined;
+  readonly sessionPickerVisible: boolean;
+  readonly setSessionPickerVisible: (visible: boolean) => void;
+  readonly onSessionSwitch: (sessionId: string) => Promise<void>;
+  readonly addEntry: (entry: IHistoryEntry) => void;
+}
+
+const NO_SESSIONS_NOTICE = 'No saved sessions to resume in this workspace.';
+
+export interface IAppOverlays {
+  readonly plugin: IAppPluginViewModel;
+  readonly transport: IAppTransportViewModel;
+  readonly sessionPicker: IAppSessionPickerViewModel;
+}
+
+export function useAppOverlays(options: IOptions): IAppOverlays {
+  const pluginCallbacks = usePluginCallbacks(options.pluginAdapter);
+  const addPluginMessage = useCallback(
+    (content: string) => options.addEntry(messageToHistoryEntry(createSystemMessage(content))),
+    [options.addEntry],
+  );
+  const selectSession = useCallback(
+    (sessionId: string) => {
+      options.setSessionPickerVisible(false);
+      void options.onSessionSwitch(sessionId);
+    },
+    [options.onSessionSwitch, options.setSessionPickerVisible],
+  );
+  const cancelSessionPicker = useCallback(() => {
+    options.setSessionPickerVisible(false);
+    options.addEntry(messageToHistoryEntry(createSystemMessage('Session resume cancelled.')));
+  }, [options.addEntry, options.setSessionPickerVisible]);
+  const sessions =
+    options.hostSessions ?? listResumableSessionSummaries(options.sessionStore, options.cwd);
+  // A picker with nothing to pick would only hold the prompt: say so and give the prompt back.
+  const nothingToResume = options.sessionPickerVisible && sessions.length === 0;
+  useEffect(() => {
+    if (!nothingToResume) return;
+    options.setSessionPickerVisible(false);
+    options.addEntry(messageToHistoryEntry(createSystemMessage(NO_SESSIONS_NOTICE)));
+  }, [nothingToResume, options.addEntry, options.setSessionPickerVisible]);
+  return {
+    plugin: {
+      visible: options.pluginVisible,
+      callbacks: pluginCallbacks,
+      close: () => options.setPluginVisible(false),
+      addMessage: addPluginMessage,
+    },
+    transport: {
+      visible: options.transportVisible,
+      registry: options.transportRegistry,
+      close: () => options.setTransportVisible(false),
+    },
+    sessionPicker: {
+      visible: options.sessionPickerVisible && !nothingToResume,
+      sessions,
+      select: selectSession,
+      cancel: cancelSessionPicker,
+    },
+  };
+}

package/src/hooks/useAppScreenState.ts

@@ -0,0 +1,81 @@
+import { useState } from 'react';
+
+import { useAppearanceSettings } from './useAppearanceSettings.js';
+import { useAppWorkspaceState } from './useAppWorkspaceState.js';
+import { useSideEffects } from './useSideEffects.js';
+import { useStatusLineSettings } from './useStatusLineSettings.js';
+
+import type { IUseSideEffectsResult } from './side-effects-types.js';
+import type { IAppWorkspaceState } from './useAppWorkspaceState.js';
+import type { ITuiChannelState } from './useTuiChannel.js';
+import type {
+  IAppearanceSettings,
+  IStatusLineCommandSettings,
+} from '@robota-sdk/agent-interface-command';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+
+interface IOptions {
+  readonly state: ITuiChannelState;
+  readonly setSessionName: (name: string) => void;
+  readonly sessionStore: IInteractiveSessionStore | undefined;
+  readonly onSessionSwitch: (sessionId: string) => Promise<void>;
+  readonly showSessionPickerOnStart: boolean | undefined;
+  readonly coordinationBlocked: boolean;
+}
+
+export interface IAppScreenState {
+  readonly screens: IUseSideEffectsResult;
+  readonly workspace: IAppWorkspaceState;
+  readonly statusSettings: IStatusLineCommandSettings;
+  /** SCREEN-2002: the persisted appearance, re-read after every slash-command result. */
+  readonly appearance: IAppearanceSettings;
+  /** SCREEN-1993: the input area's history-search overlay is open and owns the keys. */
+  readonly historySearchOpen: boolean;
+  readonly setHistorySearchOpen: (open: boolean) => void;
+}
+
+export function useAppScreenState(options: IOptions): IAppScreenState {
+  const [workspaceSwitcherVisible, setWorkspaceSwitcherVisible] = useState(false);
+  const [historySearchOpen, setHistorySearchOpen] = useState(false);
+  const [statusSettings, refreshStatusSettings] = useStatusLineSettings();
+  const [appearance, refreshAppearance] = useAppearanceSettings();
+  const screens = useSideEffects({
+    uiEventPort: options.state.uiEventPort,
+    baseHandleSubmit: options.state.handleSubmit,
+    setSessionName: options.setSessionName,
+    refreshStatusLineSettings: refreshStatusSettings,
+    refreshAppearanceSettings: refreshAppearance,
+    showSessionPickerOnStart: options.showSessionPickerOnStart,
+    openAgentSwitcher: () => setWorkspaceSwitcherVisible(true),
+  });
+  const navigationEnabled =
+    options.state.permissionRequest === null &&
+    options.state.pendingUserAction === null &&
+    !screens.showPluginTUI &&
+    !screens.showTransportTUI &&
+    !screens.showSessionPicker &&
+    !screens.showThemePicker &&
+    !workspaceSwitcherVisible &&
+    !historySearchOpen &&
+    !options.coordinationBlocked;
+  const workspace = useAppWorkspaceState({
+    snapshot: options.state.executionWorkspaceSnapshot,
+    selectedEntryId: options.state.selectedExecutionEntryId,
+    select: options.state.selectExecutionWorkspaceEntry,
+    read: options.state.readExecutionWorkspaceDetail,
+    sessionStore: options.sessionStore,
+    onSessionSwitch: options.onSessionSwitch,
+    addEntry: options.state.addEntry,
+    navigationEnabled,
+    switcherVisible: workspaceSwitcherVisible,
+    setSwitcherVisible: setWorkspaceSwitcherVisible,
+  });
+  return {
+    screens,
+    workspace,
+    statusSettings,
+    appearance,
+    historySearchOpen,
+    setHistorySearchOpen,
+  };
+}

package/src/hooks/useAppSubmissionState.ts

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+
+interface IOptions {
+  readonly selectedEntry: IExecutionWorkspaceEntry | undefined;
+  readonly submit: (input: string) => Promise<void>;
+  readonly sendAgentJob: (taskId: string, input: string) => Promise<void>;
+  readonly isThinking: boolean;
+}
+
+export interface IAppSubmissionState {
+  readonly submit: (input: string) => Promise<void>;
+  readonly gitRefreshToken: number;
+}
+
+export function useAppSubmissionState(options: IOptions): IAppSubmissionState {
+  const [gitRefreshToken, setGitRefreshToken] = useState(0);
+  const routedSubmit = useCallback(
+    async (input: string): Promise<void> => {
+      const entry = options.selectedEntry;
+      if (entry && entry.kind !== 'main_thread' && entry.controls.includes('send')) {
+        await options.sendAgentJob(entry.sourceId, input);
+        return;
+      }
+      await options.submit(input);
+    },
+    [options.selectedEntry, options.sendAgentJob, options.submit],
+  );
+  const submit = useCallback(
+    async (input: string): Promise<void> => {
+      setGitRefreshToken((token) => token + 1);
+      await routedSubmit(input);
+    },
+    [routedSubmit],
+  );
+  const wasThinkingRef = useRef(false);
+  useEffect(() => {
+    if (wasThinkingRef.current && !options.isThinking) {
+      setGitRefreshToken((token) => token + 1);
+    }
+    wasThinkingRef.current = options.isThinking;
+  }, [options.isThinking]);
+  return { submit, gitRefreshToken };
+}