@robota-sdk/agent-transport 3.0.0-beta.64

package/src/tui/hooks/useInteractiveSession.ts

@@ -0,0 +1,273 @@
+import { useState, useCallback, useEffect } from 'react';
+import { InteractiveSession, CommandRegistry } from '@robota-sdk/agent-framework';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+import type {
+  IBackgroundTaskRunner,
+  ICommandHostAdapters,
+  ICommandModule,
+  IInteractiveSession,
+  IInteractiveSessionStore,
+  TSubagentRunnerFactory,
+  IExecutionDetailPage,
+  IExecutionWorkspaceSnapshot,
+  TShellExecFn,
+} from '@robota-sdk/agent-framework';
+import type {
+  IAIProvider,
+  TPermissionMode,
+  IHistoryEntry,
+  TSessionEndReason,
+} from '@robota-sdk/agent-core';
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import type { IPermissionRequest } from '../types.js';
+import { TuiStateManager } from '../tui-state-manager.js';
+import { useSlashRouting } from './useSlashRouting.js';
+import { CommandEffectQueue, type ICommandEffectQueue } from './command-effect-queue.js';
+import { usePermissionQueue } from './usePermissionQueue.js';
+import { initializeSession, type IInitState } from './use-interactive-session-init.js';
+
+const SESSION_INIT_POLL_MS = 200;
+
+export interface IInteractiveSessionProps {
+  cwd: string;
+  provider: IAIProvider;
+  permissionMode?: TPermissionMode;
+  maxTurns?: number;
+  sessionStore?: IInteractiveSessionStore;
+  resumeSessionId?: string;
+  forkSession?: boolean;
+  sessionName?: string;
+  backgroundTaskRunners?: IBackgroundTaskRunner[];
+  subagentRunnerFactory?: TSubagentRunnerFactory;
+  commandModules?: readonly ICommandModule[];
+  commandHostAdapters?: ICommandHostAdapters;
+  shellExec?: TShellExecFn;
+  transportRegistry?: ITransportRegistryView<IInteractiveSession>;
+  language?: string;
+  reloadPluginCommandSource?: (registry: CommandRegistry) => void;
+  agentName?: string;
+}
+
+export interface IInteractiveSessionState {
+  interactiveSession: InteractiveSession;
+  registry: CommandRegistry;
+  commandEffectQueue: ICommandEffectQueue;
+  history: IHistoryEntry[];
+  addEntry: (entry: IHistoryEntry) => void;
+  streamingText: string;
+  activeTools: import('@robota-sdk/agent-framework').IToolState[];
+  isThinking: boolean;
+  isAborting: boolean;
+  isShuttingDown: boolean;
+  pendingPrompt: string | null;
+  executionWorkspaceSnapshot: IExecutionWorkspaceSnapshot | null;
+  selectedExecutionEntryId?: string;
+  permissionRequest: IPermissionRequest | null;
+  contextState: { percentage: number; usedTokens: number; maxTokens: number };
+  handleSubmit: (input: string) => Promise<void>;
+  handleAbort: () => void;
+  handleCancelQueue: () => void;
+  handleShutdown: (reason?: TSessionEndReason) => Promise<void>;
+  selectExecutionWorkspaceEntry: (entryId: string) => void;
+  readExecutionWorkspaceDetail: (entryId: string) => Promise<IExecutionDetailPage>;
+}
+
+interface IHistoryReadableSession {
+  getFullHistory(): IHistoryEntry[];
+}
+
+interface IHistorySyncManager {
+  syncHistory(entries: IHistoryEntry[]): void;
+}
+
+export function applyCompactEventToManager(
+  interactiveSession: IHistoryReadableSession,
+  manager: IHistorySyncManager,
+): void {
+  manager.syncHistory(interactiveSession.getFullHistory());
+}
+
+export function applySkillActivationEventToManager(
+  interactiveSession: IHistoryReadableSession,
+  manager: IHistorySyncManager,
+): void {
+  manager.syncHistory(interactiveSession.getFullHistory());
+}
+
+function syncExecutionWorkspaceFromSession(
+  interactiveSession: InteractiveSession,
+  manager: TuiStateManager,
+): void {
+  try {
+    manager.syncExecutionWorkspaceSnapshot(
+      interactiveSession.getExecutionWorkspaceSnapshot({
+        selectedEntryId: manager.selectedExecutionEntryId,
+      }),
+    );
+  } catch {
+    // allow-fallback: session may not be initialized yet; swallow until ready
+    /* Session not initialized yet */
+  }
+}
+
+export function useInteractiveSession(props: IInteractiveSessionProps): IInteractiveSessionState {
+  const [, forceRender] = useState(0);
+  const [isShuttingDown, setIsShuttingDown] = useState(false);
+  const { permissionHandler, permissionRequest } = usePermissionQueue();
+
+  // Initialize once — useState lazy initializer runs exactly once per mount, safe for Concurrent Mode
+  const [initState] = useState<IInitState>(() => initializeSession(props, permissionHandler));
+  const { interactiveSession, registry, manager, commandEffectQueue } = initState;
+
+  manager.onChange = () => forceRender((n) => n + 1);
+
+  // Sync restored history immediately (session resume restores history in constructor)
+  if (manager.history.length === 0) {
+    const restored = interactiveSession.getFullHistory();
+    if (restored.length > 0) {
+      manager.syncHistory(restored);
+    }
+  }
+
+  // Start transports (settings-driven: WS + web-monitor based on registry config).
+  useEffect(() => {
+    if (!props.transportRegistry) return;
+    const reg = props.transportRegistry;
+    reg.startAll(interactiveSession).catch(() => undefined);
+    return () => {
+      reg.stopAll().catch(() => undefined);
+    };
+  }, [interactiveSession, props.transportRegistry]);
+
+  // Connect InteractiveSession events to TuiStateManager
+  useEffect(() => {
+    const onCompact = (): void => applyCompactEventToManager(interactiveSession, manager);
+    const onSkillActivation = (): void =>
+      applySkillActivationEventToManager(interactiveSession, manager);
+    const onExecutionWorkspaceEvent = (
+      event: import('@robota-sdk/agent-framework').IExecutionWorkspaceEvent,
+    ): void => manager.syncExecutionWorkspaceSnapshot(event.snapshot);
+
+    interactiveSession.on('text_delta', manager.onTextDelta);
+    interactiveSession.on('tool_start', manager.onToolStart);
+    interactiveSession.on('tool_end', manager.onToolEnd);
+    interactiveSession.on('thinking', manager.onThinking);
+    interactiveSession.on('complete', manager.onComplete);
+    interactiveSession.on('interrupted', manager.onInterrupted);
+    interactiveSession.on('error', manager.onError);
+    interactiveSession.on('context_update', manager.onContextUpdate);
+    interactiveSession.on('compact', onCompact);
+    interactiveSession.on('skill_activation', onSkillActivation);
+    interactiveSession.on('execution_workspace_event', onExecutionWorkspaceEvent);
+
+    // Sync context state and restored history after async initialization
+    const initCheck = setInterval(() => {
+      try {
+        const ctx = interactiveSession.getContextState();
+        manager.setContextState({
+          percentage: ctx.usedPercentage,
+          usedTokens: ctx.usedTokens,
+          maxTokens: ctx.maxTokens,
+        });
+        const restored = interactiveSession.getFullHistory();
+        if (restored.length > 0) {
+          manager.syncHistory(restored);
+        }
+        syncExecutionWorkspaceFromSession(interactiveSession, manager);
+        clearInterval(initCheck);
+      } catch {
+        // allow-fallback: session initializes asynchronously; poll until ready
+        /* Not yet initialized */
+      }
+    }, SESSION_INIT_POLL_MS);
+
+    return () => {
+      clearInterval(initCheck);
+      interactiveSession.off('text_delta', manager.onTextDelta);
+      interactiveSession.off('tool_start', manager.onToolStart);
+      interactiveSession.off('tool_end', manager.onToolEnd);
+      interactiveSession.off('thinking', manager.onThinking);
+      interactiveSession.off('complete', manager.onComplete);
+      interactiveSession.off('interrupted', manager.onInterrupted);
+      interactiveSession.off('error', manager.onError);
+      interactiveSession.off('context_update', manager.onContextUpdate);
+      interactiveSession.off('compact', onCompact);
+      interactiveSession.off('skill_activation', onSkillActivation);
+      interactiveSession.off('execution_workspace_event', onExecutionWorkspaceEvent);
+    };
+  }, [interactiveSession, manager]);
+
+  // Sync messages on every thinking state change:
+  // - thinking=true: "You:" and "System: Invoking..." are already in messages
+  // - thinking=false: complete/interrupted messages are in messages
+  useEffect(() => {
+    manager.syncHistory(interactiveSession.getFullHistory());
+    syncExecutionWorkspaceFromSession(interactiveSession, manager);
+    if (!manager.isThinking) {
+      manager.setPendingPrompt(interactiveSession.getPendingPrompt());
+    }
+  }, [manager.isThinking, interactiveSession, manager]);
+
+  const handleSubmit = useSlashRouting(
+    interactiveSession,
+    registry,
+    manager,
+    commandEffectQueue,
+    props.reloadPluginCommandSource,
+  );
+
+  const handleAbort = useCallback(() => {
+    manager.setAborting(true);
+    interactiveSession.abort();
+  }, [interactiveSession, manager]);
+
+  const handleCancelQueue = useCallback(() => {
+    interactiveSession.cancelQueue();
+    manager.setPendingPrompt(null);
+  }, [interactiveSession, manager]);
+
+  const handleShutdown = useCallback(
+    async (reason: TSessionEndReason = 'prompt_input_exit'): Promise<void> => {
+      if (isShuttingDown) return;
+      setIsShuttingDown(true);
+      manager.addEntry(messageToHistoryEntry(createSystemMessage('Shutting down...')));
+      await interactiveSession.shutdown({ reason, message: 'CLI shutdown' });
+    },
+    [interactiveSession, manager, isShuttingDown],
+  );
+
+  const selectExecutionWorkspaceEntry = useCallback(
+    (entryId: string): void => manager.selectExecutionWorkspaceEntry(entryId),
+    [manager],
+  );
+
+  const readExecutionWorkspaceDetail = useCallback(
+    (entryId: string): Promise<IExecutionDetailPage> =>
+      interactiveSession.readExecutionWorkspaceDetail(entryId),
+    [interactiveSession],
+  );
+
+  return {
+    interactiveSession,
+    registry,
+    commandEffectQueue,
+    history: manager.history,
+    addEntry: (entry: IHistoryEntry) => manager.addEntry(entry),
+    streamingText: manager.streamingText,
+    activeTools: manager.activeTools,
+    isThinking: manager.isThinking,
+    isAborting: manager.isAborting,
+    isShuttingDown,
+    pendingPrompt: manager.pendingPrompt,
+    executionWorkspaceSnapshot: manager.executionWorkspaceSnapshot,
+    selectedExecutionEntryId: manager.selectedExecutionEntryId,
+    permissionRequest,
+    contextState: manager.contextState,
+    handleSubmit,
+    handleAbort,
+    handleCancelQueue,
+    handleShutdown,
+    selectExecutionWorkspaceEntry,
+    readExecutionWorkspaceDetail,
+  };
+}

package/src/tui/hooks/usePermissionQueue.ts

@@ -0,0 +1,51 @@
+import { useState, useRef, useCallback } from 'react';
+import type { TToolArgs } from '@robota-sdk/agent-core';
+import type { TPermissionResultValue } from '@robota-sdk/agent-framework';
+import type { IPermissionRequest } from '../types.js';
+
+export function usePermissionQueue(): {
+  permissionHandler: (toolName: string, toolArgs: TToolArgs) => Promise<TPermissionResultValue>;
+  permissionRequest: IPermissionRequest | null;
+} {
+  const [permissionRequest, setPermissionRequest] = useState<IPermissionRequest | null>(null);
+  const permissionQueueRef = useRef<
+    Array<{
+      toolName: string;
+      toolArgs: TToolArgs;
+      resolve: (result: TPermissionResultValue) => void;
+    }>
+  >([]);
+  const processingRef = useRef(false);
+
+  const processNextPermission = useCallback(() => {
+    if (processingRef.current) return;
+    const next = permissionQueueRef.current[0];
+    if (!next) {
+      setPermissionRequest(null);
+      return;
+    }
+    processingRef.current = true;
+    setPermissionRequest({
+      toolName: next.toolName,
+      toolArgs: next.toolArgs,
+      resolve: (result: TPermissionResultValue) => {
+        permissionQueueRef.current.shift();
+        processingRef.current = false;
+        setPermissionRequest(null);
+        next.resolve(result);
+        setTimeout(() => processNextPermission(), 0);
+      },
+    });
+  }, []);
+
+  const permissionHandler = useCallback(
+    (toolName: string, toolArgs: TToolArgs): Promise<TPermissionResultValue> =>
+      new Promise<TPermissionResultValue>((resolve) => {
+        permissionQueueRef.current.push({ toolName, toolArgs, resolve });
+        processNextPermission();
+      }),
+    [processNextPermission],
+  );
+
+  return { permissionHandler, permissionRequest };
+}

package/src/tui/hooks/usePluginCallbacks.ts

@@ -0,0 +1,30 @@
+/**
+ * Hook: returns a no-op ICommandPluginAdapter for when no plugin adapter is provided.
+ *
+ * In normal usage, App receives commandHostAdapters.plugin from the CLI (agent-cli), which
+ * constructs the real adapter. This fallback exists only for test environments where no adapter
+ * is injected.
+ */
+
+import { useMemo } from 'react';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-framework';
+
+function createNoOpPluginAdapter(): ICommandPluginAdapter {
+  return {
+    listInstalled: async () => [],
+    listAvailablePlugins: async () => [],
+    install: async () => undefined,
+    uninstall: async () => undefined,
+    enable: async () => undefined,
+    disable: async () => undefined,
+    marketplaceAdd: async () => '',
+    marketplaceRemove: async () => undefined,
+    marketplaceUpdate: async () => undefined,
+    marketplaceList: async () => [],
+    reloadPlugins: async () => ({ loadedPluginCount: 0 }),
+  };
+}
+
+export function usePluginCallbacks(_cwd: string): ICommandPluginAdapter {
+  return useMemo(() => createNoOpPluginAdapter(), []);
+}

package/src/tui/hooks/usePluginScreenData.ts

@@ -0,0 +1,84 @@
+/**
+ * Hook: fetch data for PluginTUI screens.
+ * Extracted from PluginTUI.tsx for single-responsibility.
+ */
+
+import { useState, useEffect } from 'react';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-framework';
+import type { IMenuSelectItem } from '../MenuSelect.js';
+
+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/tui/hooks/useSideEffects.ts

@@ -0,0 +1,210 @@
+import { useState, useRef, useCallback } from 'react';
+import { useApp } from 'ink';
+import type { ICommandInteraction, ICommandResult } from '@robota-sdk/agent-framework';
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import type { TSessionEndReason } from '@robota-sdk/agent-core';
+import type { TInteractivePrompt } from './side-effects-types.js';
+import type { IUseSideEffectsOptions, IUseSideEffectsResult } from './side-effects-types.js';
+import { applyCommandEffects } from './command-effect-handler.js';
+import { useTuiCliAdapter } from '../tui-cli-adapter-context.js';
+import {
+  addModelChangeCancelledMessage,
+  applyConfirmedModelChange,
+} from './model-change-side-effect.js';
+
+const EXIT_DELAY_MS = 500;
+
+export function useSideEffects({
+  cwd,
+  providerOverride,
+  interactiveSession,
+  commandEffectQueue,
+  addEntry,
+  baseHandleSubmit,
+  setSessionName,
+  setStatusLineSettings,
+  showSessionPickerOnStart,
+  openAgentSwitcher,
+}: IUseSideEffectsOptions): IUseSideEffectsResult {
+  const { exit } = useApp();
+  const cliAdapter = useTuiCliAdapter();
+  const [pendingModelId, setPendingModelId] = useState<string | null>(null);
+  const pendingModelChangeRef = useRef<string | null>(null);
+  const [pendingInteractionPrompt, setPendingInteractionPrompt] =
+    useState<TInteractivePrompt | null>(null);
+  const commandInteractionRef = useRef<ICommandInteraction | null>(null);
+  const [showPluginTUI, setShowPluginTUI] = useState(false);
+  const [showSessionPicker, setShowSessionPicker] = useState(showSessionPickerOnStart ?? false);
+  const [showTransportTUI, setShowTransportTUI] = useState(false);
+
+  const requestShutdown = useCallback(
+    (reason: TSessionEndReason, message: string): void => {
+      addEntry(messageToHistoryEntry(createSystemMessage('Shutting down...')));
+      setTimeout(() => {
+        void interactiveSession.shutdown({ reason, message }).finally(() => exit());
+      }, EXIT_DELAY_MS);
+    },
+    [interactiveSession, addEntry, exit],
+  );
+
+  const applyEffects = useCallback(
+    (effects: Parameters<typeof applyCommandEffects>[0]): boolean =>
+      applyCommandEffects(effects, {
+        addEntry,
+        requestShutdown,
+        requestModelChange: (modelId) => {
+          pendingModelChangeRef.current = modelId;
+          setPendingModelId(modelId);
+        },
+        openPluginTUI: () => setShowPluginTUI(true),
+        openSessionPicker: () => setShowSessionPicker(true),
+        openTransportTUI: () => setShowTransportTUI(true),
+        openAgentSwitcher: () => openAgentSwitcher?.(),
+        renameSession: (name) => {
+          interactiveSession.setName(name);
+          setSessionName(name);
+        },
+        applyStatusLinePatch: (patch) => {
+          setStatusLineSettings(
+            cliAdapter.applyStatusLineSettings(cliAdapter.getUserSettingsPath(), patch),
+          );
+          return true;
+        },
+        cliAdapter,
+      }),
+    [
+      addEntry,
+      cliAdapter,
+      interactiveSession,
+      requestShutdown,
+      setSessionName,
+      setStatusLineSettings,
+    ],
+  );
+
+  const applyCommandResult = useCallback(
+    (result: ICommandResult): void => {
+      if (result.message.length > 0) {
+        addEntry(messageToHistoryEntry(createSystemMessage(result.message)));
+      }
+      if (result.interaction !== undefined) {
+        commandInteractionRef.current = result.interaction;
+        setPendingInteractionPrompt(result.interaction.prompt);
+        return;
+      }
+      commandInteractionRef.current = null;
+      setPendingInteractionPrompt(null);
+      if (result.effects !== undefined && result.effects.length > 0) {
+        applyEffects(result.effects);
+      }
+    },
+    [addEntry, applyEffects],
+  );
+
+  const applyQueuedCommandState = useCallback((): boolean => {
+    const queued = commandEffectQueue.drain();
+    if (queued === undefined) {
+      return false;
+    }
+    if (queued.type === 'interaction') {
+      const { interaction } = queued;
+      commandInteractionRef.current = interaction;
+      setPendingInteractionPrompt(interaction.prompt);
+      return true;
+    }
+    return applyEffects(queued.effects);
+  }, [applyEffects, commandEffectQueue]);
+
+  const handleSubmit = useCallback(
+    async (input: string): Promise<void> => {
+      await baseHandleSubmit(input);
+      applyQueuedCommandState();
+    },
+    [baseHandleSubmit, applyQueuedCommandState],
+  );
+
+  const handleModelConfirm = useCallback(
+    (index: number) => {
+      const modelId = pendingModelChangeRef.current;
+      setPendingModelId(null);
+      pendingModelChangeRef.current = null;
+      if (index === 0 && modelId) {
+        applyConfirmedModelChange({
+          cwd,
+          modelId,
+          providerOverride,
+          addEntry,
+          requestShutdown,
+          applyModelChange: (c, m, opts) => {
+            cliAdapter.applyActiveModelChange(c, m, opts);
+            return { applied: true };
+          },
+        });
+      } else {
+        addModelChangeCancelledMessage(addEntry);
+      }
+    },
+    [cwd, providerOverride, addEntry, cliAdapter, requestShutdown],
+  );
+
+  const handleInteractionSubmit = useCallback(
+    async (value: string): Promise<void> => {
+      const interaction = commandInteractionRef.current;
+      if (interaction === null) {
+        setPendingInteractionPrompt(null);
+        return;
+      }
+      try {
+        // allow-fallback: user-facing error display for plugin interaction submit
+        const result = await interaction.submit(value);
+        applyCommandResult(result);
+      } catch (err) {
+        // allow-fallback: user-facing error display for plugin interaction submit
+        commandInteractionRef.current = null;
+        setPendingInteractionPrompt(null);
+        addEntry(
+          messageToHistoryEntry(
+            createSystemMessage(`Failed: ${err instanceof Error ? err.message : String(err)}`),
+          ),
+        );
+      }
+    },
+    [addEntry, applyCommandResult],
+  );
+
+  const handleInteractionCancel = useCallback(() => {
+    const interaction = commandInteractionRef.current;
+    commandInteractionRef.current = null;
+    setPendingInteractionPrompt(null);
+    if (interaction?.cancel === undefined) {
+      addEntry(messageToHistoryEntry(createSystemMessage('Command interaction cancelled.')));
+      return;
+    }
+    Promise.resolve(interaction.cancel())
+      .then((result) => applyCommandResult(result))
+      .catch((err) => {
+        // allow-fallback: user-facing error display for interaction cancel
+        addEntry(
+          messageToHistoryEntry(
+            createSystemMessage(`Failed: ${err instanceof Error ? err.message : String(err)}`),
+          ),
+        );
+      });
+  }, [addEntry, applyCommandResult]);
+
+  return {
+    handleSubmit,
+    pendingModelId,
+    pendingInteractionPrompt,
+    showPluginTUI,
+    showSessionPicker,
+    showTransportTUI,
+    setPendingModelId,
+    setShowPluginTUI,
+    setShowSessionPicker,
+    setShowTransportTUI,
+    handleModelConfirm,
+    handleInteractionSubmit,
+    handleInteractionCancel,
+  };
+}