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

package/src/tui/TuiInteractionChannel.ts

@@ -0,0 +1,461 @@
+/**
+ * TuiInteractionChannel — implements IInteractionChannel for the Ink TUI.
+ *
+ * Moves session lifecycle (InteractiveSession, CommandRegistry, TuiStateManager)
+ * out of React hooks and into a plain TypeScript class.
+ */
+
+import {
+  createSystemMessage,
+  createUserMessage,
+  messageToHistoryEntry,
+} from '@robota-sdk/agent-core';
+import { InteractiveSession, CommandRegistry } from '@robota-sdk/agent-framework';
+
+import { CommandEffectQueue, type ICommandEffectQueue } from './hooks/command-effect-queue.js';
+import { applySystemCommandResult } from './hooks/useSlashRouting.js';
+import { generateSessionName } from './session-naming.js';
+import { TuiStateManager } from './tui-state-manager.js';
+
+import type { IPermissionRequest } from './types.js';
+import type { IAIProvider, TPermissionMode, TSessionEndReason } from '@robota-sdk/agent-core';
+import type { TToolArgs } from '@robota-sdk/agent-core';
+import type { IInteractionChannel } from '@robota-sdk/agent-framework';
+import type {
+  InteractionEvent,
+  IActionRequest,
+  IActionResponse,
+  ICommandInfo,
+} from '@robota-sdk/agent-framework';
+import type {
+  IBackgroundTaskRunner,
+  ICommandHostAdapters,
+  ICommandModule,
+  IInteractiveSession,
+  IInteractiveSessionStore,
+  TSubagentRunnerFactory,
+  IExecutionWorkspaceEvent,
+  IExecutionDetailPage,
+  IExecutionResult,
+  TShellExecFn,
+} from '@robota-sdk/agent-framework';
+import type { TPermissionResultValue } from '@robota-sdk/agent-framework';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+const SESSION_INIT_POLL_MS = 200;
+
+export interface ITuiInteractionChannelOptions {
+  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 class TuiInteractionChannel implements IInteractionChannel {
+  readonly stateManager: TuiStateManager;
+
+  private readonly interactiveSession: InteractiveSession;
+  private readonly registry: CommandRegistry;
+  private readonly commandEffectQueue: ICommandEffectQueue;
+  private readonly opts: ITuiInteractionChannelOptions;
+
+  private submitHandler: ((text: string) => Promise<void>) | null = null;
+  private actionQueue: Array<{
+    action: IActionRequest;
+    resolve: (response: IActionResponse) => void;
+  }> = [];
+  private processingAction = false;
+
+  permissionRequest: IPermissionRequest | null = null;
+  pendingAction: IActionRequest | null = null;
+  availableCommands: ICommandInfo[] = [];
+  isShuttingDown = false;
+  sessionName: string | undefined;
+
+  private autoNameTriggered = false;
+  private sessionStarted = false;
+  private initCheckInterval: ReturnType<typeof setInterval> | null = null;
+  private permissionQueue: Array<{
+    toolName: string;
+    toolArgs: TToolArgs;
+    resolve: (result: TPermissionResultValue) => void;
+  }> = [];
+  private processingPermission = false;
+
+  /** Set by React hook to trigger re-render on state change */
+  onChange: (() => void) | null = null;
+
+  constructor(opts: ITuiInteractionChannelOptions) {
+    this.opts = opts;
+    this.sessionName = opts.sessionName;
+    this.stateManager = new TuiStateManager();
+    this.stateManager.onChange = () => this.onChange?.();
+
+    this.interactiveSession = this.createSession();
+    this.registry = this.createRegistry();
+    this.commandEffectQueue = new CommandEffectQueue();
+  }
+
+  private createSession(): InteractiveSession {
+    const opts = this.opts;
+    return new InteractiveSession({
+      cwd: opts.cwd,
+      provider: opts.provider,
+      permissionMode: opts.permissionMode,
+      maxTurns: opts.maxTurns,
+      permissionHandler: (toolName, toolArgs) => this.handlePermissionRequest(toolName, toolArgs),
+      sessionStore: opts.sessionStore,
+      resumeSessionId: opts.resumeSessionId,
+      forkSession: opts.forkSession,
+      sessionName: opts.sessionName,
+      backgroundTaskRunners: opts.backgroundTaskRunners,
+      subagentRunnerFactory: opts.subagentRunnerFactory,
+      commandModules: opts.commandModules,
+      commandHostAdapters: opts.commandHostAdapters,
+      shellExec: opts.shellExec,
+      language: opts.language,
+      agentName: opts.agentName,
+      systemPrompt: opts.systemPrompt,
+      appendSystemPrompt: opts.appendSystemPrompt,
+      allowedTools: opts.allowedTools,
+      deniedTools: opts.deniedTools,
+    });
+  }
+
+  private createRegistry(): CommandRegistry {
+    const registry = new CommandRegistry();
+    for (const module of this.opts.commandModules ?? []) {
+      registry.addModule(module);
+    }
+    this.opts.reloadPluginCommandSource?.(registry);
+    return registry;
+  }
+
+  // ── IInteractionChannel ──────────────────────────────────────
+
+  onSubmit(handler: (text: string) => Promise<void>): void {
+    this.submitHandler = handler;
+  }
+
+  write(_event: InteractionEvent): void {
+    // Intentionally unused in TUI direct-wiring mode.
+    // TuiInteractionChannel subscribes to session events directly via start() →
+    // wireSessionEvents(), not through the IInteractionChannel event protocol used
+    // by createInteractiveRuntime. The two paths are mutually exclusive.
+  }
+
+  async requestAction(action: IActionRequest): Promise<IActionResponse> {
+    return new Promise<IActionResponse>((resolve) => {
+      this.actionQueue.push({ action, resolve });
+      this.processNextAction();
+    });
+  }
+
+  setAvailableCommands(commands: ICommandInfo[]): void {
+    this.availableCommands = commands;
+    this.onChange?.();
+  }
+
+  setBusy(busy: boolean): void {
+    this.stateManager.onThinking(busy);
+  }
+
+  async start(): Promise<void> {
+    if (this.sessionStarted) return;
+    this.sessionStarted = true;
+    this.wireSessionEvents();
+    this.syncRestoredHistory();
+    this.startInitCheck();
+
+    if (this.opts.transportRegistry) {
+      await this.opts.transportRegistry.startAll(this.interactiveSession);
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.onChange = null;
+    this.sessionStarted = false;
+    this.stopInitCheck();
+    if (this.opts.transportRegistry) {
+      await this.opts.transportRegistry.stopAll();
+    }
+  }
+
+  // ── Additional methods for App.tsx ───────────────────────────
+
+  getSession(): InteractiveSession {
+    return this.interactiveSession;
+  }
+
+  getRegistry(): CommandRegistry {
+    return this.registry;
+  }
+
+  getCommandEffectQueue(): ICommandEffectQueue {
+    return this.commandEffectQueue;
+  }
+
+  abort(): void {
+    this.stateManager.setAborting(true);
+    this.interactiveSession.abort();
+  }
+
+  cancelQueue(): void {
+    this.interactiveSession.cancelQueue();
+    this.stateManager.setPendingPrompt(null);
+  }
+
+  async shutdown(options?: { reason?: TSessionEndReason }): Promise<void> {
+    if (this.isShuttingDown) return;
+    this.isShuttingDown = true;
+    this.stateManager.addEntry(messageToHistoryEntry(createSystemMessage('Shutting down...')));
+    this.onChange?.();
+    await this.interactiveSession.shutdown({
+      reason: options?.reason ?? 'prompt_input_exit',
+      message: 'CLI shutdown',
+    });
+  }
+
+  selectExecutionWorkspaceEntry(entryId: string): void {
+    this.stateManager.selectExecutionWorkspaceEntry(entryId);
+  }
+
+  async readExecutionWorkspaceDetail(entryId: string): Promise<IExecutionDetailPage> {
+    return this.interactiveSession.readExecutionWorkspaceDetail(entryId);
+  }
+
+  async sendAgentJob(jobId: string, input: string): Promise<void> {
+    await this.interactiveSession.sendAgentJob(jobId, input);
+  }
+
+  setSessionName(name: string): void {
+    this.sessionName = name;
+    this.interactiveSession.setName(name);
+    this.onChange?.();
+  }
+
+  resolveAction(response: IActionResponse): void {
+    const pending = this.actionQueue[0];
+    if (!pending) return;
+    this.actionQueue.shift();
+    this.processingAction = false;
+    this.pendingAction = null;
+    this.onChange?.();
+    pending.resolve(response);
+    this.processNextAction();
+  }
+
+  async handleInput(input: string): Promise<void> {
+    if (!input.startsWith('/')) {
+      await this.interactiveSession.submit(input);
+      this.stateManager.setPendingPrompt(this.interactiveSession.getPendingPrompt());
+      return;
+    }
+    await this.handleSlashCommand(input);
+  }
+
+  private async handleSlashCommand(input: string): Promise<void> {
+    const parts = input.slice(1).split(/\s+/);
+    const cmd = parts[0]?.toLowerCase() ?? '';
+    const args = parts.slice(1).join(' ');
+
+    const result = await this.interactiveSession.executeCommand(cmd, args);
+    if (result) {
+      if (result.effects?.some((effect) => effect.type === 'session-execution-started')) {
+        this.stateManager.setPendingPrompt(this.interactiveSession.getPendingPrompt());
+        return;
+      }
+      applySystemCommandResult(
+        result,
+        this.interactiveSession,
+        this.registry,
+        this.stateManager,
+        this.commandEffectQueue,
+        this.opts.reloadPluginCommandSource,
+      );
+      return;
+    }
+
+    this.stateManager.addEntry(
+      messageToHistoryEntry(createSystemMessage(`Unknown command "/${cmd}". Type /help for help.`)),
+    );
+  }
+
+  // ── Private helpers ──────────────────────────────────────────
+
+  private processNextAction(): void {
+    if (this.processingAction) return;
+    const next = this.actionQueue[0];
+    if (!next) {
+      this.pendingAction = null;
+      this.onChange?.();
+      return;
+    }
+    this.processingAction = true;
+    this.pendingAction = next.action;
+    this.onChange?.();
+  }
+
+  private handlePermissionRequest(
+    toolName: string,
+    toolArgs: TToolArgs,
+  ): Promise<TPermissionResultValue> {
+    return new Promise<TPermissionResultValue>((resolve) => {
+      this.permissionQueue.push({ toolName, toolArgs, resolve });
+      this.processNextPermission();
+    });
+  }
+
+  private processNextPermission(): void {
+    if (this.processingPermission) return;
+    const next = this.permissionQueue[0];
+    if (!next) {
+      this.permissionRequest = null;
+      this.onChange?.();
+      return;
+    }
+    this.processingPermission = true;
+    this.permissionRequest = {
+      toolName: next.toolName,
+      toolArgs: next.toolArgs,
+      resolve: (result) => {
+        this.permissionQueue.shift();
+        this.processingPermission = false;
+        this.permissionRequest = null;
+        next.resolve(result);
+        setTimeout(() => this.processNextPermission(), 0);
+      },
+    };
+    this.onChange?.();
+  }
+
+  private wireSessionEvents(): void {
+    const session = this.interactiveSession;
+    const manager = this.stateManager;
+
+    const onUserMessage = (content: string): void => {
+      this.handleAutoNaming(content);
+      manager.addEntry(messageToHistoryEntry(createUserMessage(content)));
+    };
+    const onComplete = (result: IExecutionResult): void => {
+      manager.onComplete(result);
+      manager.syncHistory(session.getFullHistory());
+    };
+    const onError = (): void => {
+      manager.onError();
+      manager.syncHistory(session.getFullHistory());
+    };
+    const onCompact = (): void => {
+      manager.syncHistory(session.getFullHistory());
+    };
+    const onSkillActivation = (): void => {
+      manager.syncHistory(session.getFullHistory());
+    };
+    const onExecutionWorkspaceEvent = (event: IExecutionWorkspaceEvent): void => {
+      manager.syncExecutionWorkspaceSnapshot(event.snapshot);
+    };
+
+    session.on('user_message', onUserMessage);
+    session.on('text_delta', manager.onTextDelta);
+    session.on('tool_start', manager.onToolStart);
+    session.on('tool_end', manager.onToolEnd);
+    session.on('thinking', manager.onThinking);
+    session.on('complete', onComplete);
+    session.on('interrupted', manager.onInterrupted);
+    session.on('error', onError);
+    session.on('context_update', manager.onContextUpdate);
+    session.on('compact', onCompact);
+    session.on('skill_activation', onSkillActivation);
+    session.on('execution_workspace_event', onExecutionWorkspaceEvent);
+  }
+
+  private handleAutoNaming(content: string): void {
+    if (this.autoNameTriggered) return;
+    if (this.opts.sessionName || this.interactiveSession.getName()) return;
+    this.autoNameTriggered = true;
+    generateSessionName(this.opts.provider, content)
+      .then((name) => {
+        this.interactiveSession.setName(name);
+        this.sessionName = name;
+        this.opts.onAutoNamed?.(name);
+        this.onChange?.();
+      })
+      .catch(() => {
+        this.autoNameTriggered = false;
+      });
+  }
+
+  private syncRestoredHistory(): void {
+    if (this.stateManager.history.length === 0) {
+      const restored = this.interactiveSession.getFullHistory();
+      if (restored.length > 0) {
+        this.stateManager.syncHistory(restored);
+      }
+    }
+  }
+
+  private startInitCheck(): void {
+    this.initCheckInterval = setInterval(() => {
+      this.runInitCheck();
+    }, SESSION_INIT_POLL_MS);
+  }
+
+  private runInitCheck(): void {
+    try {
+      const ctx = this.interactiveSession.getContextState();
+      this.stateManager.setContextState({
+        percentage: ctx.usedPercentage,
+        usedTokens: ctx.usedTokens,
+        maxTokens: ctx.maxTokens,
+      });
+      const restored = this.interactiveSession.getFullHistory();
+      if (restored.length > 0) {
+        this.stateManager.syncHistory(restored);
+      }
+      this.syncExecutionWorkspace();
+      this.stopInitCheck();
+    } catch {
+      // allow-fallback: session initializes asynchronously; poll until ready
+      /* Not yet initialized */
+    }
+  }
+
+  private stopInitCheck(): void {
+    if (this.initCheckInterval !== null) {
+      clearInterval(this.initCheckInterval);
+      this.initCheckInterval = null;
+    }
+  }
+
+  private syncExecutionWorkspace(): void {
+    try {
+      // allow-fallback: session may not be initialized yet; swallow until ready
+      this.stateManager.syncExecutionWorkspaceSnapshot(
+        this.interactiveSession.getExecutionWorkspaceSnapshot({
+          selectedEntryId: this.stateManager.selectedExecutionEntryId,
+        }),
+      );
+    } catch {
+      // allow-fallback: session may not be initialized yet; swallow until ready
+      /* Session not initialized yet */
+    }
+  }
+}

package/src/tui/__tests__/TuiInteractionChannel.display-contract.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Display-contract tests for TuiInteractionChannel.
+ *
+ * Verifies user-visible state: which entries appear in stateManager.history,
+ * with which roles, and in which order.
+ *
+ * These are deliberately separate from lifecycle.test.ts:
+ *   lifecycle  → event routing / onChange propagation (mechanism layer)
+ *   this file  → what the user sees on screen (display contract layer)
+ *
+ * Design principles:
+ *   - user_message assertions do NOT require getFullHistory injection
+ *   - every history assertion checks entry.type (= role) explicitly
+ *   - timing: user message visible BEFORE complete fires
+ */
+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 {
+  createAssistantMessage,
+  createSystemMessage,
+  createUserMessage,
+  messageToHistoryEntry,
+} from '@robota-sdk/agent-core';
+import { TuiInteractionChannel } from '../TuiInteractionChannel.js';
+
+import type { IAIProvider, IHistoryEntry } from '@robota-sdk/agent-core';
+import type { IExecutionResult } from '@robota-sdk/agent-framework';
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+type MockSession = {
+  getFullHistory: 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 makeChannel(): TuiInteractionChannel {
+  return new TuiInteractionChannel({
+    cwd: '/tmp/test',
+    provider: {} as IAIProvider,
+  });
+}
+
+function makeResult(overrides?: Partial<IExecutionResult>): IExecutionResult {
+  return {
+    contextState: { usedPercentage: 5, usedTokens: 500, maxTokens: 100_000 },
+    response: 'done',
+    ...overrides,
+  } as unknown as IExecutionResult;
+}
+
+const MOCK_TOOL_RUNNING = {
+  toolName: 'bash',
+  isRunning: true,
+  input: '{}',
+  startTime: Date.now(),
+};
+
+const MOCK_TOOL_DONE = {
+  toolName: 'bash',
+  isRunning: false,
+  input: '{}',
+  startTime: Date.now(),
+};
+
+function entryRole(entry: IHistoryEntry): string {
+  return entry.type;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+// ── Group D: display contract (what the user sees) ────────────────────────────
+
+describe('Group D — display contract: history entries and active tools', () => {
+  it('D1 (CLI-B05): user_message event immediately adds role=user entry before complete', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    // user message fires BEFORE complete — must be in history immediately
+    emitSessionEvent(channel, 'user_message', 'hello');
+
+    expect(channel.stateManager.history).toHaveLength(1);
+    expect(entryRole(channel.stateManager.history[0])).toBe('user');
+    expect((channel.stateManager.history[0].data as { content: string }).content).toBe('hello');
+
+    await channel.stop();
+  });
+
+  it('D2: complete syncs assistant entry into history', async () => {
+    const channel = makeChannel();
+    const mockSession = getMockSession(channel);
+    const assistantEntry = messageToHistoryEntry(createAssistantMessage('Hi!'));
+    mockSession.getFullHistory.mockReturnValue([assistantEntry]);
+    await channel.start();
+
+    emitSessionEvent(channel, 'complete', makeResult());
+
+    const roles = channel.stateManager.history.map(entryRole);
+    expect(roles).toContain('assistant');
+    await channel.stop();
+  });
+
+  it('D3 (CLI-B06): error event syncs error entry into history — no silent failure', async () => {
+    const channel = makeChannel();
+    const mockSession = getMockSession(channel);
+    const userEntry = messageToHistoryEntry(createUserMessage('hello'));
+    const errorEntry = messageToHistoryEntry(createSystemMessage('Error: network failure'));
+    mockSession.getFullHistory.mockReturnValue([userEntry, errorEntry]);
+    await channel.start();
+
+    emitSessionEvent(channel, 'user_message', 'hello');
+    emitSessionEvent(channel, 'error');
+
+    // error entry from getFullHistory must be visible
+    const roles = channel.stateManager.history.map(entryRole);
+    expect(roles).toContain('system');
+    await channel.stop();
+  });
+
+  it('D4 (CLI-B07): tool_end marks tool isRunning=false; complete clears all (no stale spinner after complete)', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    emitSessionEvent(channel, 'tool_start', MOCK_TOOL_RUNNING);
+    expect(channel.stateManager.activeTools).toHaveLength(1);
+
+    // After tool_end: tool stays in activeTools with isRunning:false (shows "ran" status during streaming)
+    emitSessionEvent(channel, 'tool_end', MOCK_TOOL_DONE);
+    expect(channel.stateManager.activeTools).toHaveLength(1);
+    expect(channel.stateManager.activeTools[0]!.isRunning).toBe(false);
+
+    // After complete: all tools cleared — StreamingIndicator must be gone
+    emitSessionEvent(channel, 'complete', makeResult());
+    expect(channel.stateManager.activeTools).toHaveLength(0);
+
+    await channel.stop();
+  });
+
+  it('D5 (CLI-B08): thinking(false) clears activeTools even without complete', async () => {
+    const channel = makeChannel();
+    await channel.start();
+
+    emitSessionEvent(channel, 'thinking', true);
+    emitSessionEvent(channel, 'tool_start', MOCK_TOOL_RUNNING);
+    expect(channel.stateManager.activeTools).toHaveLength(1);
+
+    // abort path: thinking(false) without complete
+    emitSessionEvent(channel, 'thinking', false);
+    expect(channel.stateManager.activeTools).toHaveLength(0);
+
+    await channel.stop();
+  });
+
+  it('D6: full turn — user entry appears first, assistant entry follows after complete', async () => {
+    const channel = makeChannel();
+    const mockSession = getMockSession(channel);
+    const userEntry = messageToHistoryEntry(createUserMessage('hello'));
+    const assistantEntry = messageToHistoryEntry(createAssistantMessage('world'));
+    // session history after complete includes both
+    mockSession.getFullHistory.mockReturnValue([userEntry, assistantEntry]);
+    await channel.start();
+
+    // 1. user message fires — visible immediately
+    emitSessionEvent(channel, 'user_message', 'hello');
+    expect(entryRole(channel.stateManager.history[0])).toBe('user');
+
+    // 2. streaming
+    emitSessionEvent(channel, 'text_delta', 'world');
+    expect(channel.stateManager.streamingText).toBe('world');
+
+    // 3. complete — syncHistory replaces with authoritative session history
+    emitSessionEvent(channel, 'complete', makeResult());
+    expect(channel.stateManager.streamingText).toBe('');
+
+    const roles = channel.stateManager.history.map(entryRole);
+    expect(roles[0]).toBe('user');
+    expect(roles[1]).toBe('assistant');
+
+    await channel.stop();
+  });
+});