@robota-sdk/agent-transport 3.0.0-beta.69 → 3.0.0-beta.70

package/src/tui/__tests__/TuiInteractionChannel.lifecycle.test.ts

@@ -0,0 +1,294 @@
+/**
+ * Integration tests for TuiInteractionChannel lifecycle:
+ * session event wiring, handleInput roundtrip, onChange propagation.
+ *
+ * No Ink rendering, no PTY — pure TypeScript.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('@robota-sdk/agent-framework', async () => {
+  const actual = await vi.importActual<typeof import('@robota-sdk/agent-framework')>(
+    '@robota-sdk/agent-framework',
+  );
+  return {
+    ...actual,
+    InteractiveSession: vi.fn().mockImplementation(() => {
+      const handlers = new Map<string, Array<(...args: unknown[]) => void>>();
+      return {
+        getFullHistory: vi.fn().mockReturnValue([]),
+        setName: vi.fn(),
+        getName: vi.fn().mockReturnValue(undefined),
+        getPermissionMode: vi.fn().mockReturnValue('default'),
+        isInitialized: false,
+        on: vi.fn().mockImplementation((event: string, handler: (...args: unknown[]) => void) => {
+          if (!handlers.has(event)) handlers.set(event, []);
+          handlers.get(event)!.push(handler);
+        }),
+        off: vi.fn(),
+        emit: (event: string, ...args: unknown[]) => {
+          (handlers.get(event) ?? []).forEach((h) => h(...args));
+        },
+        submit: vi.fn().mockResolvedValue(undefined),
+        executeCommand: vi.fn().mockResolvedValue(null),
+        getPendingPrompt: vi.fn().mockReturnValue(null),
+        abort: vi.fn(),
+        cancelQueue: vi.fn(),
+        getContextState: vi.fn().mockReturnValue({
+          usedPercentage: 0,
+          usedTokens: 0,
+          maxTokens: 100_000,
+        }),
+        getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue({ entries: [] }),
+        shutdown: vi.fn().mockResolvedValue(undefined),
+        sendAgentJob: vi.fn().mockResolvedValue(undefined),
+        readExecutionWorkspaceDetail: vi.fn().mockResolvedValue({}),
+      };
+    }),
+    CommandRegistry: vi.fn().mockImplementation(() => ({
+      addModule: vi.fn(),
+    })),
+  };
+});
+
+import { TuiInteractionChannel } from '../TuiInteractionChannel.js';
+
+import type { IAIProvider } from '@robota-sdk/agent-core';
+import type { IExecutionResult, IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+type MockSession = {
+  getFullHistory: ReturnType<typeof vi.fn>;
+  submit: ReturnType<typeof vi.fn>;
+  executeCommand: ReturnType<typeof vi.fn>;
+  on: ReturnType<typeof vi.fn>;
+  emit: (event: string, ...args: unknown[]) => void;
+};
+
+function getMockSession(channel: TuiInteractionChannel): MockSession {
+  return (channel as unknown as { interactiveSession: MockSession }).interactiveSession;
+}
+
+function emitSessionEvent(channel: TuiInteractionChannel, event: string, ...args: unknown[]): void {
+  getMockSession(channel).emit(event, ...args);
+}
+
+function makeMockTransportRegistry(): {
+  registry: ITransportRegistryView<IInteractiveSession>;
+  startAll: ReturnType<typeof vi.fn>;
+  stopAll: ReturnType<typeof vi.fn>;
+} {
+  const startAll = vi.fn().mockResolvedValue(undefined);
+  const stopAll = vi.fn().mockResolvedValue(undefined);
+  return {
+    registry: { startAll, stopAll } as unknown as ITransportRegistryView<IInteractiveSession>,
+    startAll,
+    stopAll,
+  };
+}
+
+function makeChannel(opts?: {
+  transportRegistry?: ITransportRegistryView<IInteractiveSession>;
+}): TuiInteractionChannel {
+  return new TuiInteractionChannel({
+    cwd: '/tmp/test',
+    provider: {} as IAIProvider,
+    ...opts,
+  });
+}
+
+const MOCK_RESULT = {
+  contextState: { usedPercentage: 10, usedTokens: 1_000, maxTokens: 100_000 },
+  response: 'Hello!',
+} as unknown as IExecutionResult;
+
+const MOCK_TOOL = {
+  toolName: 'bash',
+  isRunning: true,
+  input: '{}',
+  startTime: Date.now(),
+} as unknown as Parameters<
+  InstanceType<typeof TuiInteractionChannel>['stateManager']['onToolStart']
+>[0];
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+// ── Group A: channel.start() / channel.stop() lifecycle ───────────────────────
+
+describe('Group A — channel.start() / channel.stop() lifecycle', () => {
+  it('A1: text_delta after start() updates stateManager.streamingText', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    emitSessionEvent(channel, 'text_delta', 'Hello!');
+
+    expect(channel.stateManager.streamingText).toBe('Hello!');
+    await channel.stop();
+  });
+
+  it('A2: complete after start() clears streaming state and updates contextState', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    emitSessionEvent(channel, 'text_delta', 'streaming...');
+    emitSessionEvent(channel, 'complete', MOCK_RESULT);
+
+    expect(channel.stateManager.streamingText).toBe('');
+    expect(channel.stateManager.contextState.percentage).toBe(10);
+    expect(channel.stateManager.contextState.usedTokens).toBe(1_000);
+    await channel.stop();
+  });
+
+  it('A3: tool_start after start() adds entry to stateManager.activeTools', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    emitSessionEvent(channel, 'tool_start', MOCK_TOOL);
+
+    expect(channel.stateManager.activeTools).toHaveLength(1);
+    expect(channel.stateManager.activeTools[0]).toMatchObject({ toolName: 'bash' });
+    await channel.stop();
+  });
+
+  it('A4: error after start() clears stateManager.streamingText', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    emitSessionEvent(channel, 'text_delta', 'partial...');
+    emitSessionEvent(channel, 'error');
+
+    expect(channel.stateManager.streamingText).toBe('');
+    await channel.stop();
+  });
+
+  it('A5: calling start() twice does not duplicate subscriptions', async () => {
+    const channel = makeChannel();
+    await channel.start();
+    await channel.start(); // second call is a no-op (sessionStarted guard)
+
+    emitSessionEvent(channel, 'text_delta', 'hi');
+
+    expect(channel.stateManager.streamingText).toBe('hi'); // not 'hihi'
+    await channel.stop();
+  });
+
+  it('A6: stop() calls transportRegistry.stopAll exactly once', async () => {
+    const { registry, stopAll } = makeMockTransportRegistry();
+    const channel = makeChannel({ transportRegistry: registry });
+    await channel.start();
+    await channel.stop();
+
+    expect(stopAll).toHaveBeenCalledOnce();
+  });
+});
+
+// ── Group B: handleInput() AI-response roundtrip ──────────────────────────────
+
+describe('Group B — handleInput() roundtrip', () => {
+  it('B1: handleInput("hello") calls session.submit with "hello"', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    await channel.handleInput('hello');
+
+    const mockSession = getMockSession(channel);
+    expect(mockSession.submit).toHaveBeenCalledWith('hello');
+    await channel.stop();
+  });
+
+  it('B2: text_delta + complete syncs history to stateManager', async () => {
+    const channel = makeChannel();
+    const mockSession = getMockSession(channel);
+    const historyEntry = {
+      role: 'assistant',
+      content: [{ type: 'text', text: 'Hi!' }],
+      timestamp: Date.now(),
+    };
+    mockSession.getFullHistory.mockReturnValue([historyEntry]);
+    await channel.start();
+
+    await channel.handleInput('hello');
+    emitSessionEvent(channel, 'text_delta', 'Hi!');
+    expect(channel.stateManager.streamingText).toBe('Hi!');
+
+    emitSessionEvent(channel, 'complete', MOCK_RESULT);
+    expect(channel.stateManager.streamingText).toBe('');
+    expect(channel.stateManager.history).toHaveLength(1);
+
+    await channel.stop();
+  });
+
+  it('B3: handleInput("/help") calls executeCommand, not session.submit', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    await channel.handleInput('/help');
+
+    const mockSession = getMockSession(channel);
+    expect(mockSession.submit).not.toHaveBeenCalled();
+    expect(mockSession.executeCommand).toHaveBeenCalledWith('help', '');
+    await channel.stop();
+  });
+
+  it('B4: handleInput("hello") triggers channel.onChange at least once', async () => {
+    const channel = makeChannel();
+    const onChange = vi.fn();
+    channel.onChange = onChange;
+    await channel.start();
+    onChange.mockClear();
+
+    await channel.handleInput('hello');
+    emitSessionEvent(channel, 'text_delta', 'hey');
+
+    expect(onChange).toHaveBeenCalled();
+    await channel.stop();
+  });
+});
+
+// ── Group C: onChange propagation invariant ───────────────────────────────────
+
+describe('Group C — onChange propagation invariant', () => {
+  it('C1: session event after start() causes channel.onChange to fire', async () => {
+    const channel = makeChannel();
+    const onChange = vi.fn();
+    channel.onChange = onChange;
+    await channel.start();
+    onChange.mockClear();
+
+    // tool_start calls notify() directly (not debounced), so onChange fires immediately
+    emitSessionEvent(channel, 'tool_start', MOCK_TOOL);
+
+    expect(onChange).toHaveBeenCalled();
+    await channel.stop();
+  });
+
+  it('C2: channel.onChange does not fire for events before start()', () => {
+    const channel = makeChannel();
+    const onChange = vi.fn();
+    channel.onChange = onChange;
+    // Do NOT call channel.start() — handlers not registered yet
+    emitSessionEvent(channel, 'text_delta', 'hello'); // no-op: no handlers
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('C3: channel.onChange does not fire for events after stop()', async () => {
+    const channel = makeChannel();
+    const onChange = vi.fn();
+    channel.onChange = onChange;
+    await channel.start();
+    await channel.stop(); // sets this.onChange = null
+    onChange.mockClear();
+
+    emitSessionEvent(channel, 'text_delta', 'hello');
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

package/src/tui/__tests__/TuiInteractionChannel.requestAction.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Unit tests for TuiInteractionChannel.requestAction() promise protocol.
+ *
+ * Tests the queue-based action resolution mechanism in isolation —
+ * no Ink rendering, no InteractiveSession, no real provider required.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@robota-sdk/agent-framework', async () => {
+  const actual = await vi.importActual<typeof import('@robota-sdk/agent-framework')>(
+    '@robota-sdk/agent-framework',
+  );
+  return {
+    ...actual,
+    InteractiveSession: vi.fn().mockImplementation(() => ({
+      getFullHistory: vi.fn().mockReturnValue([]),
+      setName: vi.fn(),
+      getSessionId: vi.fn().mockReturnValue('test-id'),
+      isInitialized: false,
+      on: vi.fn(),
+      off: vi.fn(),
+    })),
+    CommandRegistry: vi.fn().mockImplementation(() => ({
+      addModule: vi.fn(),
+    })),
+  };
+});
+
+import { TuiInteractionChannel } from '../TuiInteractionChannel.js';
+
+import type { IAIProvider } from '@robota-sdk/agent-core';
+import type { IActionRequest } from '@robota-sdk/agent-framework';
+
+function makeChannel(): TuiInteractionChannel {
+  return new TuiInteractionChannel({
+    cwd: '/tmp',
+    provider: {} as IAIProvider,
+  });
+}
+
+const PICK_ACTION: IActionRequest = {
+  type: 'pick',
+  id: 'mode',
+  title: '/mode',
+  items: [
+    { label: 'plan', value: 'plan' },
+    { label: 'default', value: 'default' },
+  ],
+};
+
+const CONFIRM_ACTION: IActionRequest = {
+  type: 'confirm',
+  id: 'exit',
+  message: 'Exit the session?',
+};
+
+describe('TuiInteractionChannel.requestAction', () => {
+  let channel: TuiInteractionChannel;
+
+  beforeEach(() => {
+    channel = makeChannel();
+  });
+
+  it('sets pendingAction when requestAction is called', () => {
+    void channel.requestAction(PICK_ACTION);
+    expect(channel.pendingAction).toMatchObject({ type: 'pick', id: 'mode' });
+  });
+
+  it('resolves pick response when resolveAction is called', async () => {
+    const responsePromise = channel.requestAction(PICK_ACTION);
+    channel.resolveAction({ type: 'pick', item: { label: 'plan', value: 'plan' } });
+    const response = await responsePromise;
+    expect(response).toEqual({ type: 'pick', item: { label: 'plan', value: 'plan' } });
+  });
+
+  it('clears pendingAction after resolveAction', async () => {
+    const responsePromise = channel.requestAction(PICK_ACTION);
+    channel.resolveAction({ type: 'cancelled' });
+    await responsePromise;
+    expect(channel.pendingAction).toBeNull();
+  });
+
+  it('resolves confirm response when resolveAction is called', async () => {
+    const responsePromise = channel.requestAction(CONFIRM_ACTION);
+    channel.resolveAction({ type: 'confirm', confirmed: true });
+    const response = await responsePromise;
+    expect(response).toEqual({ type: 'confirm', confirmed: true });
+  });
+
+  it('resolves cancelled when resolveAction is called with cancelled', async () => {
+    const responsePromise = channel.requestAction(PICK_ACTION);
+    channel.resolveAction({ type: 'cancelled' });
+    const response = await responsePromise;
+    expect(response).toEqual({ type: 'cancelled' });
+  });
+
+  it('queues multiple actions and processes them sequentially', async () => {
+    const p1 = channel.requestAction(PICK_ACTION);
+    const p2 = channel.requestAction(CONFIRM_ACTION);
+
+    // First action is pending immediately
+    expect(channel.pendingAction).toMatchObject({ type: 'pick' });
+
+    // Resolve first
+    channel.resolveAction({ type: 'pick', item: { label: 'plan', value: 'plan' } });
+    await p1;
+
+    // Second action becomes pending after first resolves
+    expect(channel.pendingAction).toMatchObject({ type: 'confirm' });
+
+    // Resolve second
+    channel.resolveAction({ type: 'confirm', confirmed: false });
+    const r2 = await p2;
+    expect(r2).toEqual({ type: 'confirm', confirmed: false });
+    expect(channel.pendingAction).toBeNull();
+  });
+
+  it('calls onChange when pendingAction changes', () => {
+    const onChange = vi.fn();
+    channel.onChange = onChange;
+    void channel.requestAction(PICK_ACTION);
+    expect(onChange).toHaveBeenCalled();
+  });
+});

package/src/tui/__tests__/compact-event-bridge.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
 import { TuiStateManager } from '../tui-state-manager.js';
-import { applyCompactEventToManager } from '../hooks/useInteractiveSession.js';
+import { applyCompactEventToManager } from '../hooks/useTuiChannel.js';
 
 describe('compact event bridge', () => {
   it('syncs session history so automatic compaction notifications render', () => {

package/src/tui/__tests__/input-area-flow.test.ts

@@ -14,7 +14,6 @@ import {
   shouldSubmitInput,
 } from '../flows/input-area-flow.js';
 import type { ICommand } from '@robota-sdk/agent-framework';
-import type { ITuiPickerInteraction } from '../command-interaction.js';
 import {
   createAssistantMessage,
   createSystemMessage,
@@ -67,20 +66,14 @@ describe('input area flow', () => {
     expect(result).toEqual({ type: 'submit', value: '/help' });
   });
 
-  it('Given interaction declared and no args When enter selects command Then open-interaction is returned', () => {
-    const result = resolveEnterCommandSelection('/ex', command('exit'), {
-      onMissingArgs: 'confirm',
-    });
+  it('Given command with no args and no subcommands When enter selects Then submits', () => {
+    const result = resolveEnterCommandSelection('/ex', command('exit'));
 
-    expect(result).toEqual({ type: 'open-interaction', commandName: 'exit' });
+    expect(result).toEqual({ type: 'submit', value: '/exit' });
   });
 
-  it('Given interaction declared but subcommand selected (args present) When enter selects Then submits', () => {
-    const pickerInteraction: ITuiPickerInteraction = {
-      onMissingArgs: 'picker',
-      getItems: () => [],
-    };
-    const result = resolveEnterCommandSelection('/mode plan', command('plan'), pickerInteraction);
+  it('Given subcommand selected (args present) When enter selects Then submits', () => {
+    const result = resolveEnterCommandSelection('/mode plan', command('plan'));
 
     expect(result).toEqual({ type: 'submit', value: '/mode plan' });
   });

package/src/tui/flows/input-area-flow.ts

@@ -1,6 +1,5 @@
-import { parseSlashInput } from '../hooks/useAutocomplete.js';
+import { isSlashCommand, tokeniseSlashCommand } from '@robota-sdk/agent-framework';
 
-import type { ITuiCommandInteraction } from '../command-interaction.js';
 import type { IHistoryEntry, TUniversalValue } from '@robota-sdk/agent-core';
 import type { ICommand } from '@robota-sdk/agent-framework';
 
@@ -19,8 +18,7 @@ export type TPromptHistoryInputAction = 'previous' | 'next';
 
 export type TCommandSelectionResult =
   | { type: 'insert'; value: string; selectedIndex?: number }
-  | { type: 'submit'; value: string }
-  | { type: 'open-interaction'; commandName: string };
+  | { type: 'submit'; value: string };
 
 export interface IPasteLabelChange {
   value: string;
@@ -144,9 +142,10 @@ export function moveAutocompleteSelection(
 }
 
 export function resolveTabCompletion(value: string, command: ICommand): TCommandSelectionResult {
-  const parsed = parseSlashInput(value);
-  if (parsed.parentCommand) {
-    return { type: 'insert', value: `/${parsed.parentCommand} ${command.name} ` };
+  // Subcommand mode: '/parent filter' — space present after command name
+  if (isSlashCommand(value) && value.slice(1).includes(' ')) {
+    const { name } = tokeniseSlashCommand(value);
+    return { type: 'insert', value: `/${name} ${command.name} ` };
   }
   if (command.subcommands && command.subcommands.length > 0) {
     return { type: 'insert', value: `/${command.name} `, selectedIndex: 0 };
@@ -157,15 +156,11 @@ export function resolveTabCompletion(value: string, command: ICommand): TCommand
 export function resolveEnterCommandSelection(
   value: string,
   command: ICommand,
-  interaction?: ITuiCommandInteraction,
 ): TCommandSelectionResult {
-  const parsed = parseSlashInput(value);
-  if (parsed.parentCommand) {
-    return { type: 'submit', value: `/${parsed.parentCommand} ${command.name}` };
-  }
-  // parentCommand is empty → no args provided beyond the command name itself
-  if (interaction?.onMissingArgs) {
-    return { type: 'open-interaction', commandName: command.name };
+  // Subcommand mode: '/parent filter' — space present after command name
+  if (isSlashCommand(value) && value.slice(1).includes(' ')) {
+    const { name } = tokeniseSlashCommand(value);
+    return { type: 'submit', value: `/${name} ${command.name}` };
   }
   if (command.subcommands && command.subcommands.length > 0) {
     return { type: 'insert', value: `/${command.name} `, selectedIndex: 0 };

package/src/tui/hooks/use-interactive-session-init.ts

@@ -3,9 +3,44 @@ import { InteractiveSession, CommandRegistry } from '@robota-sdk/agent-framework
 import { TuiStateManager } from '../tui-state-manager.js';
 import { CommandEffectQueue, type ICommandEffectQueue } from './command-effect-queue.js';
 
-import type { IInteractiveSessionProps } from './useInteractiveSession.js';
+import type { IAIProvider, TPermissionMode } from '@robota-sdk/agent-core';
 import type { TToolArgs } from '@robota-sdk/agent-core';
-import type { TPermissionResultValue } from '@robota-sdk/agent-framework';
+import type {
+  IBackgroundTaskRunner,
+  ICommandHostAdapters,
+  ICommandModule,
+  IInteractiveSession,
+  IInteractiveSessionStore,
+  TSubagentRunnerFactory,
+  TShellExecFn,
+  TPermissionResultValue,
+} from '@robota-sdk/agent-framework';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+export interface IInteractiveSessionProps {
+  cwd: string;
+  provider: IAIProvider;
+  permissionMode?: TPermissionMode;
+  maxTurns?: number;
+  sessionStore?: IInteractiveSessionStore;
+  resumeSessionId?: string;
+  forkSession?: boolean;
+  sessionName?: string;
+  onAutoNamed?: (name: string) => void;
+  backgroundTaskRunners?: IBackgroundTaskRunner[];
+  subagentRunnerFactory?: TSubagentRunnerFactory;
+  commandModules?: readonly ICommandModule[];
+  commandHostAdapters?: ICommandHostAdapters;
+  shellExec?: TShellExecFn;
+  transportRegistry?: ITransportRegistryView<IInteractiveSession>;
+  language?: string;
+  reloadPluginCommandSource?: (registry: CommandRegistry) => void;
+  agentName?: string;
+  systemPrompt?: string;
+  appendSystemPrompt?: string;
+  allowedTools?: string[];
+  deniedTools?: string[];
+}
 
 export interface IInitState {
   interactiveSession: InteractiveSession;

package/src/tui/hooks/useSlashRouting.ts

@@ -1,6 +1,6 @@
 /**
  * Slash command routing logic for the TUI.
- * Extracted from useInteractiveSession for single-responsibility.
+ * Extracted for single-responsibility.
  */
 
 import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';

package/src/tui/hooks/useTuiChannel.ts

@@ -0,0 +1,95 @@
+/**
+ * useTuiChannel — React hook that subscribes to TuiInteractionChannel state changes.
+ *
+ * Returns the same shape as the former IInteractiveSessionState so that App.tsx
+ * changes are minimal.
+ */
+
+import { useState, useEffect } from 'react';
+
+import type { TuiInteractionChannel } from '../TuiInteractionChannel.js';
+import type { ICommandEffectQueue } from './command-effect-queue.js';
+import type { IPermissionRequest } from '../types.js';
+import type { IHistoryEntry, TSessionEndReason } from '@robota-sdk/agent-core';
+import type { InteractiveSession, CommandRegistry } from '@robota-sdk/agent-framework';
+import type {
+  IToolState,
+  IExecutionWorkspaceSnapshot,
+  IExecutionDetailPage,
+} from '@robota-sdk/agent-framework';
+
+export interface IInteractiveSessionState {
+  interactiveSession: InteractiveSession;
+  registry: CommandRegistry;
+  commandEffectQueue: ICommandEffectQueue;
+  history: IHistoryEntry[];
+  addEntry: (entry: IHistoryEntry) => void;
+  streamingText: string;
+  activeTools: 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 useTuiChannel(channel: TuiInteractionChannel): IInteractiveSessionState {
+  const [, forceRender] = useState(0);
+
+  useEffect(() => {
+    channel.onChange = () => forceRender((n) => n + 1);
+    return () => {
+      channel.onChange = null;
+    };
+  }, [channel]);
+
+  const manager = channel.stateManager;
+
+  return {
+    interactiveSession: channel.getSession(),
+    registry: channel.getRegistry(),
+    commandEffectQueue: channel.getCommandEffectQueue(),
+    history: manager.history,
+    addEntry: (e) => manager.addEntry(e),
+    streamingText: manager.streamingText,
+    activeTools: manager.activeTools,
+    isThinking: manager.isThinking,
+    isAborting: manager.isAborting,
+    isShuttingDown: channel.isShuttingDown,
+    pendingPrompt: manager.pendingPrompt,
+    executionWorkspaceSnapshot: manager.executionWorkspaceSnapshot,
+    selectedExecutionEntryId: manager.selectedExecutionEntryId,
+    permissionRequest: channel.permissionRequest,
+    contextState: manager.contextState,
+    handleSubmit: (input) => channel.handleInput(input),
+    handleAbort: () => channel.abort(),
+    handleCancelQueue: () => channel.cancelQueue(),
+    handleShutdown: (reason) => channel.shutdown({ reason }),
+    selectExecutionWorkspaceEntry: (id) => channel.selectExecutionWorkspaceEntry(id),
+    readExecutionWorkspaceDetail: (id) => channel.readExecutionWorkspaceDetail(id),
+  };
+}

package/src/tui/index.ts

@@ -1,8 +1,9 @@
 export { TuiTransport } from './tui-transport.js';
+export { renderApp } from './render.js';
+export type { IRenderOptions } from './render.js';
 export type { ITuiCliAdapter } from './tui-cli-adapter.js';
 export type { IDefaultTuiCliAdapterOptions } from './create-default-tui-cli-adapter.js';
 export { createDefaultTuiCliAdapter } from './create-default-tui-cli-adapter.js';
-export type { IRenderOptions } from './render.js';
 export type {
   TOnMissingArgsAction,
   ITuiPickerItem,