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

package/src/__tests__/wire-tui-client-commands.test.ts

@@ -0,0 +1,243 @@
+/**
+ * #3189 — the commands a terminal attached to a workspace daemon runs in its own process.
+ *
+ * The attached terminal gives them its own handoff and working directory, applies the appearance
+ * patch `/theme` asks for itself, and refuses any other host action by name instead of dropping it.
+ */
+import { createTerminalClientCommands } from '@robota-sdk/agent-command';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createTuiClientCommandHost,
+  findTuiClientCommand,
+  runTuiClientCommand,
+} from '../wire-tui-client-commands.js';
+
+import type {
+  ITuiClientCommand,
+  ITuiClientCommands,
+  TTuiClientCommandHost,
+} from '../wire-tui-client-commands.js';
+import type {
+  ICommandResult,
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+  TAppearanceSettingsPatch,
+  TCommandHostAction,
+} from '@robota-sdk/agent-interface-command';
+import type { ITerminalHandoff } from '@robota-sdk/agent-interface-session';
+
+/** Stands in for `/shell`: hands the terminal to a "child" that runs in the host's directory. */
+const shellLike: ITuiClientCommand = {
+  name: 'shell',
+  async execute(host, args) {
+    if (!host.canHandoffTerminal()) {
+      return { success: false, message: 'An interactive shell is unavailable here.' };
+    }
+    const cwd = host.getCwd();
+    const ran = await host.runWithTerminal(async () => `${args} in ${cwd}`);
+    return { success: true, message: ran };
+  },
+};
+
+function commandReturning(name: string, result: ICommandResult): ITuiClientCommand {
+  return { name, execute: () => result };
+}
+
+function hostFor(terminalHandoff?: ITerminalHandoff): TTuiClientCommandHost {
+  return createTuiClientCommandHost({ terminalHandoff, cwd: '/work/project' });
+}
+
+function writerSpy() {
+  return {
+    writeAppearanceSettings: vi.fn(async (_patch: TAppearanceSettingsPatch) => undefined),
+  };
+}
+
+const THEMES: IThemeCatalogueEntry[] = [
+  { id: 'dark', name: 'Dark', appearance: 'dark', source: 'built-in' },
+  { id: 'light', name: 'Light', appearance: 'light', source: 'built-in' },
+];
+const themeCatalogue: IThemeCataloguePort = {
+  listThemes: () => THEMES,
+  getTheme: (id) => THEMES.find((theme) => theme.id === id),
+  getAppearance: () => ({
+    settings: { theme: 'dark', syntaxHighlighting: true, reducedMotion: false },
+  }),
+};
+
+describe('createTuiClientCommandHost (#3189)', () => {
+  it('hands this terminal to the command and runs it in this terminal’s directory', async () => {
+    const handedOff = vi.fn();
+    const handoff: ITerminalHandoff = {
+      canHandoffTerminal: true,
+      runWithTerminal: <T>(fn: () => Promise<T>): Promise<T> => {
+        handedOff();
+        return fn();
+      },
+    };
+    const host = hostFor(handoff);
+
+    const outcome = await runTuiClientCommand(shellLike, 'ls', host, writerSpy());
+
+    expect(handedOff).toHaveBeenCalledTimes(1);
+    expect(outcome.result).toEqual({ success: true, message: 'ls in /work/project' });
+    expect(host.getCommandInvocationSource()).toBe('user');
+  });
+
+  it('without a handoff it cannot take the terminal, so the command takes its refusal path', async () => {
+    const host = hostFor(undefined);
+
+    expect(host.canHandoffTerminal()).toBe(false);
+    const outcome = await runTuiClientCommand(shellLike, 'ls', host, writerSpy());
+
+    expect(outcome.result).toEqual({
+      success: false,
+      message: 'An interactive shell is unavailable here.',
+    });
+    await expect(host.runWithTerminal(async () => 'never')).rejects.toThrow(/unavailable/u);
+  });
+});
+
+describe('runTuiClientCommand (#3189)', () => {
+  it('/theme with no arguments opens this terminal’s theme picker and writes nothing', async () => {
+    const theme = commandReturning('theme', {
+      success: true,
+      message: 'Opening the theme picker...',
+      uiIntents: [{ type: 'show-theme-picker' }],
+    });
+    const writers = writerSpy();
+
+    const outcome = await runTuiClientCommand(theme, '', hostFor(), writers);
+
+    expect(outcome.uiIntents).toEqual([{ type: 'show-theme-picker' }]);
+    expect(outcome.result).toEqual({ success: true, message: 'Opening the theme picker...' });
+    expect(writers.writeAppearanceSettings).not.toHaveBeenCalled();
+  });
+
+  it('/theme light, from the real client command set, is written before the command settles', async () => {
+    let finishWrite: () => void = () => undefined;
+    const written: TAppearanceSettingsPatch[] = [];
+    const commands: ITuiClientCommands = {
+      commands: createTerminalClientCommands({ themeCatalogue }),
+      writeAppearanceSettings: (patch) => {
+        written.push(patch);
+        return new Promise<void>((resolve) => {
+          finishWrite = resolve;
+        });
+      },
+    };
+    const theme = findTuiClientCommand(commands, 'theme');
+    if (!theme) throw new Error('the client command set has no /theme');
+
+    let settled = false;
+    const running = runTuiClientCommand(theme, 'light', hostFor(), commands).then((outcome) => {
+      settled = true;
+      return outcome;
+    });
+    await vi.waitFor(() => expect(written).toEqual([{ theme: 'light' }]));
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(settled).toBe(false);
+
+    finishWrite();
+    const outcome = await running;
+
+    expect(outcome.result.success).toBe(true);
+    expect(outcome.result.hostActions).toBeUndefined();
+    expect(outcome.result.data).toEqual({ appearance: { theme: 'light' } });
+    expect(outcome.uiIntents).toEqual([]);
+  });
+
+  it('an invalid appearance patch writes nothing and fails', async () => {
+    const command = commandReturning('theme', {
+      success: true,
+      message: 'Applied.',
+      hostActions: [
+        {
+          type: 'appearance-settings-patch',
+          patch: { reducedMotion: 'yes' } as unknown as TAppearanceSettingsPatch,
+        },
+      ],
+    });
+    const writers = writerSpy();
+
+    const outcome = await runTuiClientCommand(command, 'x', hostFor(), writers);
+
+    expect(outcome.result.success).toBe(false);
+    expect(outcome.result.message).toContain('invalid appearance settings patch');
+    expect(outcome.uiIntents).toEqual([]);
+    expect(writers.writeAppearanceSettings).not.toHaveBeenCalled();
+  });
+
+  it('a host action this terminal cannot perform is refused by name, and nothing beside it is written', async () => {
+    const hostActions: TCommandHostAction[] = [
+      { type: 'appearance-settings-patch', patch: { theme: 'light' } },
+      { type: 'session-exit' },
+    ];
+    const command = commandReturning('theme', {
+      success: true,
+      message: 'Applied.',
+      hostActions,
+      uiIntents: [{ type: 'show-theme-picker' }],
+    });
+    const writers = writerSpy();
+
+    const outcome = await runTuiClientCommand(command, '', hostFor(), writers);
+
+    expect(outcome).toEqual({
+      result: { success: false, message: "Cannot apply 'session-exit' on this terminal." },
+      uiIntents: [],
+    });
+    expect(writers.writeAppearanceSettings).not.toHaveBeenCalled();
+  });
+
+  it('a write that fails turns the result into that failure', async () => {
+    const command = commandReturning('theme', {
+      success: true,
+      message: 'Applied.',
+      hostActions: [{ type: 'appearance-settings-patch', patch: { theme: 'light' } }],
+    });
+
+    const outcome = await runTuiClientCommand(command, 'light', hostFor(), {
+      writeAppearanceSettings: () => Promise.reject(new Error('disk full')),
+    });
+
+    expect(outcome.result).toEqual({
+      success: false,
+      message: "Failed to apply 'appearance-settings-patch': disk full",
+    });
+  });
+
+  it('a failed result passes through unchanged and applies nothing', async () => {
+    const failed: ICommandResult = {
+      success: false,
+      message: 'Unknown theme "nope".',
+      hostActions: [{ type: 'appearance-settings-patch', patch: { theme: 'nope' } }],
+    };
+    const writers = writerSpy();
+
+    const outcome = await runTuiClientCommand(
+      commandReturning('theme', failed),
+      'nope',
+      hostFor(),
+      writers,
+    );
+
+    expect(outcome.result).toBe(failed);
+    expect(outcome.uiIntents).toEqual([]);
+    expect(writers.writeAppearanceSettings).not.toHaveBeenCalled();
+  });
+});
+
+describe('findTuiClientCommand (#3189)', () => {
+  it('finds a client command by name, and nothing without a set', () => {
+    const commands: ITuiClientCommands = {
+      commands: [shellLike],
+      writeAppearanceSettings: () => undefined,
+    };
+
+    expect(findTuiClientCommand(commands, 'shell')).toBe(shellLike);
+    expect(findTuiClientCommand(commands, 'model')).toBeUndefined();
+    expect(findTuiClientCommand(undefined, 'shell')).toBeUndefined();
+  });
+});

package/src/app-view-model.ts

@@ -21,13 +21,15 @@ import type {
   IExecutionWorkspaceSnapshot,
 } from '@robota-sdk/agent-interface-execution';
 import type {
-  IResumableSessionSummary,
+  ISessionListingEntry,
   IToolState,
 } from '@robota-sdk/agent-interface-session';
 import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
 
 export interface IAppViewModel {
   readonly staticItems: TStaticItem[];
+  /** Printing starts over from the first item when this changes (see `transcriptGeneration`). */
+  readonly transcriptKey: number;
   readonly handoffSuspended: boolean;
   readonly updateNotice: string | undefined;
   readonly coordinationError: string | undefined;
@@ -89,7 +91,7 @@ export interface IAppTransportViewModel {
 
 export interface IAppSessionPickerViewModel {
   readonly visible: boolean;
-  readonly sessions: readonly IResumableSessionSummary[];
+  readonly sessions: readonly ISessionListingEntry[];
   readonly select: (sessionId: string) => void;
   readonly cancel: () => void;
 }
@@ -133,4 +135,6 @@ export interface IAppStatusViewModel {
   readonly activePresetId: string | undefined;
   readonly effort: TModelEffortSelection | undefined;
   readonly gitRefreshToken: number;
+  /** This terminal only observes the session; the status bar says so. */
+  readonly readOnly: boolean;
 }

package/src/attached-session-connection.ts

@@ -0,0 +1,14 @@
+import type { TClientMessage, TServerMessage } from '@robota-sdk/agent-transport/client';
+
+/**
+ * A terminal's end of the session protocol to a session it is attached to. The terminal only sends
+ * and listens; closing the connection belongs to whoever opened it.
+ */
+export interface IAttachedSessionConnection {
+  send(message: TClientMessage): void;
+  subscribe(listener: (message: TServerMessage) => void): () => void;
+  onClose(listener: () => void): () => void;
+}
+
+/** Why an attached terminal stopped showing the session: the user left, or the connection closed. */
+export type TAttachedSessionEnd = 'user' | 'closed';

package/src/hooks/__tests__/use-app-detach-key.test.tsx

@@ -0,0 +1,72 @@
+/**
+ * Ctrl-] detaches a terminal attached to a session a host runs, exactly like Ctrl-C and `/exit`
+ * there. A terminal running its own session has nothing to detach from, so the key does nothing.
+ */
+
+import React from 'react';
+import { Text } from 'ink';
+import { cleanup, render } from 'ink-testing-library';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { useAppInputBindings } from '../useAppInputBindings.js';
+
+type TOptions = Parameters<typeof useAppInputBindings>[0];
+
+const CTRL_RIGHT_BRACKET = '\x1d';
+
+function Probe({ options }: { options: TOptions }): React.ReactElement {
+  useAppInputBindings(options);
+  return <Text>ready</Text>;
+}
+
+function options(overrides: Partial<TOptions> = {}): TOptions {
+  return {
+    isThinking: false,
+    isShuttingDown: false,
+    readOnly: false,
+    attached: false,
+    permissionRequest: null,
+    pendingUserAction: null,
+    pluginVisible: false,
+    transportVisible: false,
+    sessionPickerVisible: false,
+    workspaceSwitcherVisible: false,
+    historySearchOpen: false,
+    themePickerVisible: false,
+    selectedEntry: undefined,
+    backgroundListFocused: false,
+    mainThreadEntryId: undefined,
+    activeTools: [],
+    abort: vi.fn(),
+    stopWaitingLoop: vi.fn().mockResolvedValue(undefined),
+    toggleWorkspaceSwitcher: vi.fn(),
+    selectWorkspaceEntry: vi.fn(),
+    shutdown: vi.fn().mockResolvedValue(undefined),
+    recoveryError: undefined,
+    recoveryPending: false,
+    coordinationBlocked: false,
+    retryRecovery: vi.fn(),
+    ...overrides,
+  };
+}
+
+afterEach(cleanup);
+
+describe('Ctrl-] detach', () => {
+  it('leaves an attached terminal the way Ctrl-C does, driving or observing', async () => {
+    for (const attached of [options({ attached: true }), options({ attached: true, readOnly: true })]) {
+      const view = render(<Probe options={attached} />);
+      view.stdin.write(CTRL_RIGHT_BRACKET);
+      await vi.waitFor(() => expect(attached.shutdown).toHaveBeenCalledWith('prompt_input_exit'));
+      view.unmount();
+    }
+  });
+
+  it('does nothing on a terminal running its own session', async () => {
+    const own = options();
+    const view = render(<Probe options={own} />);
+    view.stdin.write(CTRL_RIGHT_BRACKET);
+    await new Promise<void>((resolve) => setTimeout(resolve, 200));
+    expect(own.shutdown).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/__tests__/use-app-loop-escape.test.tsx

@@ -16,6 +16,8 @@ function options(overrides: Partial<TOptions> = {}): TOptions {
   return {
     isThinking: false,
     isShuttingDown: false,
+    readOnly: false,
+    attached: false,
     permissionRequest: null,
     pendingUserAction: null,
     pluginVisible: false,
@@ -71,4 +73,15 @@ describe('Esc for a waiting self-paced loop', () => {
       view.unmount();
     }
   });
+
+  it('stops nothing on an observing terminal: neither the turn nor the loop', async () => {
+    for (const observing of [options({ readOnly: true }), options({ readOnly: true, isThinking: true })]) {
+      const view = render(<Probe options={observing} />);
+      view.stdin.write('\u001b');
+      await new Promise<void>((resolve) => setTimeout(resolve, 200));
+      expect(observing.stopWaitingLoop).not.toHaveBeenCalled();
+      expect(observing.abort).not.toHaveBeenCalled();
+      view.unmount();
+    }
+  });
 });

package/src/hooks/useAppController.ts

@@ -113,7 +113,9 @@ function buildInput(composition: IComposition): IAppInputViewModel {
     submit: composition.interaction.submission.submit,
     cancelQueue: state.handleCancelQueue,
     disabled: interactionBlocked || (state.isThinking && state.pendingPrompt !== null),
-    queueCancellationDisabled: interactionBlocked,
+    // An observer keeps the composer for `/exit` and this terminal's own commands, which the channel
+    // runs; the queue it would cancel is the drivers'.
+    queueCancellationDisabled: interactionBlocked || state.readOnly,
     isAborting: state.isAborting,
     pendingPrompt: state.pendingPrompt,
     pendingCount: state.pendingCount,
@@ -131,7 +133,7 @@ function buildStatus(composition: IComposition): IAppStatusViewModel {
   return {
     cwd: props.cwd,
     permissionMode: runtime.permissionMode,
-    modelId: props.modelId,
+    modelId: runtime.modelId ?? props.modelId,
     providerType: props.providerType,
     sessionId: runtime.sessionId,
     isThinking: state.isThinking,
@@ -145,6 +147,7 @@ function buildStatus(composition: IComposition): IAppStatusViewModel {
     activePresetId: runtime.activePresetId,
     effort: runtime.effort,
     gitRefreshToken: composition.interaction.submission.gitRefreshToken,
+    readOnly: state.readOnly,
   };
 }
 
@@ -152,6 +155,7 @@ function buildViewModel(composition: IComposition): IAppViewModel {
   const { interaction, lifecycle, shell, state } = composition;
   return {
     staticItems: composition.staticItems,
+    transcriptKey: state.transcriptGeneration,
     handoffSuspended: lifecycle.handoffSuspended,
     updateNotice: lifecycle.updateNotice,
     coordinationError: composition.coordination.error,

package/src/hooks/useAppInputBindings.ts

@@ -14,6 +14,10 @@ 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;
@@ -58,7 +62,7 @@ function useEscapeBindings(options: IOptions): void {
   useKeybindingActions(context, (actions) => {
     if (overlaysBlockKeys(options)) return;
     if (actions.includes('abort') && options.isThinking) {
-      options.abort();
+      if (!options.readOnly) options.abort();
       return;
     }
     const selected = options.selectedEntry;
@@ -71,7 +75,11 @@ function useEscapeBindings(options: IOptions): void {
       options.selectWorkspaceEntry(options.mainThreadEntryId);
       return;
     }
-    if (actions.includes('return-to-main') && !options.backgroundListFocused) {
+    if (
+      actions.includes('return-to-main') &&
+      !options.backgroundListFocused &&
+      !options.readOnly
+    ) {
       void options.stopWaitingLoop();
     }
   });
@@ -107,6 +115,13 @@ function useRecoveryBinding(options: IOptions): void {
   });
 }
 
+/** 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 => {
@@ -117,6 +132,9 @@ function useShutdownBindings(options: IOptions): void {
   };
   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');

package/src/hooks/useAppInteractionState.ts

@@ -41,6 +41,8 @@ export function useAppInteractionState(options: IOptions): IAppInteractionState
   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,
@@ -72,6 +74,7 @@ export function useAppInteractionState(options: IOptions): IAppInteractionState
     transportVisible: screens.showTransportTUI,
     setTransportVisible: screens.setShowTransportTUI,
     sessionStore: options.sessionStore,
+    hostSessions: options.state.hostSessions,
     sessionPickerVisible: screens.showSessionPicker,
     setSessionPickerVisible: screens.setShowSessionPicker,
     onSessionSwitch: options.onSessionSwitch,

package/src/hooks/useAppOverlays.ts

@@ -1,6 +1,6 @@
 import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
 import { listResumableSessionSummaries } from '@robota-sdk/agent-framework';
-import { useCallback } from 'react';
+import { useCallback, useEffect } from 'react';
 
 import { usePluginCallbacks } from './usePluginCallbacks.js';
 
@@ -11,7 +11,10 @@ import type {
 } 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 } from '@robota-sdk/agent-interface-session';
+import type {
+  IInteractiveSessionStore,
+  ISessionListingEntry,
+} from '@robota-sdk/agent-interface-session';
 import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
 
 interface IOptions {
@@ -23,12 +26,16 @@ interface IOptions {
   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;
@@ -52,6 +59,15 @@ export function useAppOverlays(options: IOptions): IAppOverlays {
     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,
@@ -65,8 +81,8 @@ export function useAppOverlays(options: IOptions): IAppOverlays {
       close: () => options.setTransportVisible(false),
     },
     sessionPicker: {
-      visible: options.sessionPickerVisible,
-      sessions: listResumableSessionSummaries(options.sessionStore, options.cwd),
+      visible: options.sessionPickerVisible && !nothingToResume,
+      sessions,
       select: selectSession,
       cancel: cancelSessionPicker,
     },

package/src/hooks/useNumberedSelection.ts

@@ -40,7 +40,8 @@ export interface INumberedSelection {
 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 { enabled, itemCount, cancellable, multi, repeatable, onSelect, onCancel, onConfirm } =
+    inputs;
 
   const clear = useCallback((): void => {
     const empty = createNumericSelectionState();
@@ -49,7 +50,7 @@ export function useNumberedSelection(inputs: IUseNumberedSelectionInputs): INumb
   }, []);
 
   const handle = useCallback(
-    (input: string, key: Parameters<typeof applyNumericSelection>[2]): void => {
+    (input: string, key: Parameters<typeof applyNumericSelection>[2]): boolean => {
       const result = applyNumericSelection(stateRef.current, input, key, {
         itemCount,
         ...(cancellable === true ? { cancellable: true } : {}),
@@ -61,12 +62,28 @@ export function useNumberedSelection(inputs: IUseNumberedSelectionInputs): INumb
       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 },

package/src/hooks/useTuiChannel.ts

@@ -23,7 +23,7 @@ import type {
   IExecutionDetailPage,
   IExecutionWorkspaceSnapshot,
 } from '@robota-sdk/agent-interface-execution';
-import type { IToolState } from '@robota-sdk/agent-interface-session';
+import type { ISessionListingEntry, IToolState } from '@robota-sdk/agent-interface-session';
 
 export interface ITuiChannelState {
   uiEventPort: ITuiSessionUiEventPort;
@@ -49,6 +49,14 @@ export interface ITuiChannelState {
   /** CMD-004: the unified action awaiting a user answer, or null. */
   pendingUserAction: IActionRequest | null;
   contextState: { percentage: number; usedTokens: number; maxTokens: number };
+  /** The host's sessions for the picker, when the channel's host keeps them. */
+  hostSessions: readonly ISessionListingEntry[] | undefined;
+  /** Changes when the transcript starts over for another session under this channel. */
+  transcriptGeneration: number;
+  /** This terminal only observes the session. */
+  readOnly: boolean;
+  /** This terminal is attached to a session a host runs; leaving only detaches it. */
+  attached: boolean;
   handleSubmit: (input: string) => Promise<void>;
   handleAbort: () => void;
   handleCancelQueue: () => void;
@@ -115,6 +123,10 @@ export function useTuiChannel(channel: ITuiAppChannelPort): ITuiChannelState {
     permissionRequest: snapshot.permissionRequest,
     pendingUserAction: snapshot.pendingUserAction,
     contextState: snapshot.contextState,
+    hostSessions: snapshot.hostSessions,
+    transcriptGeneration: snapshot.transcriptGeneration ?? 0,
+    readOnly: snapshot.readOnly === true,
+    attached: snapshot.attached === true,
     handleSubmit: (input) => channel.handleInput(input),
     handleAbort: () => channel.abort(),
     handleCancelQueue: () => channel.cancelQueue(),

package/src/index.ts

@@ -1,9 +1,23 @@
-export { renderApp } from './render.js';
+export { renderApp, renderAttachedApp } from './render.js';
 export { renderSupervisedSessionView } from './SupervisedSessionView.js';
-export type { ISupervisedViewRow, ISupervisedSessionViewProps } from './SupervisedSessionView.js';
+export type {
+  IAttachedSessionConnection,
+  TAttachedSessionEnd,
+} from './attached-session-connection.js';
+export type {
+  ISupervisedAttachRequest,
+  ISupervisedViewRow,
+  ISupervisedSessionViewProps,
+  TSupervisedViewExit,
+} from './SupervisedSessionView.js';
 export { TuiInteractionChannel } from './TuiInteractionChannel.js';
 export type { ITuiInteractionChannelOptions } from './TuiInteractionChannel.js';
-export type { IRenderOptions } from './render.js';
+export type {
+  ITuiClientCommand,
+  ITuiClientCommands,
+  TTuiClientCommandHost,
+} from './wire-tui-client-commands.js';
+export type { IRenderAttachedAppOptions, IRenderOptions } from './render.js';
 export type { ITerminalCapabilityOverrides } from './terminal-capabilities-context.js';
 export type { TScreenReaderChannel } from './screen-reader-announcement.js';
 export type { IScreenReaderPacingOverrides } from './screen-reader-pacing.js';