@robota-sdk/agent-transport 3.0.0-beta.72 → 3.0.0-beta.74

package/src/headless/__tests__/headless-provider-failure.integration.test.ts

@@ -0,0 +1,143 @@
+/**
+ * Provider-failure exit-code integration tests (CLI-064).
+ *
+ * Drives a real InteractiveSession with a provider whose chat() throws (the 401 class
+ * observed in product verification) and asserts the headless transport surfaces the
+ * failure: non-zero exit code and an error envelope/stderr message — never exit 0.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { InteractiveSession } from '@robota-sdk/agent-framework';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createHeadlessTransport } from '../headless-transport.js';
+
+import type { TInteractiveSessionOptions } from '@robota-sdk/agent-framework';
+
+type TStandardSessionOptions = Extract<
+  TInteractiveSessionOptions,
+  { cwd: string; provider: unknown }
+>;
+type TTestProvider = TStandardSessionOptions['provider'];
+type TResolvedConfig = NonNullable<TStandardSessionOptions['config']>;
+
+const AUTH_FAILURE_MESSAGE =
+  '401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}';
+
+function createConfig(): TResolvedConfig {
+  return {
+    defaultTrustLevel: 'moderate',
+    language: 'en',
+    provider: {
+      name: 'failing-test-provider',
+      model: 'failing-test-model',
+      apiKey: 'test-key',
+    },
+    permissions: { allow: [], deny: [] },
+    env: {},
+  };
+}
+
+function createAuthFailingProvider(): TTestProvider {
+  return {
+    name: 'failing-test-provider',
+    version: '1.0.0',
+    async chat() {
+      throw new Error(AUTH_FAILURE_MESSAGE);
+    },
+    async generateResponse() {
+      return { content: 'unused' };
+    },
+    supportsTools() {
+      return true;
+    },
+    validateConfig() {
+      return true;
+    },
+  };
+}
+
+function captureStream(stream: NodeJS.WriteStream): { writes: string[]; restore(): void } {
+  const writes: string[] = [];
+  const originalWrite = stream.write;
+  stream.write = ((chunk: string | Uint8Array, encodingOrCallback?: unknown) => {
+    writes.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+    if (typeof encodingOrCallback === 'function') {
+      encodingOrCallback();
+    }
+    return true;
+  }) as typeof stream.write;
+  return {
+    writes,
+    restore() {
+      stream.write = originalWrite;
+    },
+  };
+}
+
+describe('headless provider failure exit codes (CLI-064)', () => {
+  let cwd: string | undefined;
+
+  afterEach(() => {
+    if (cwd) rmSync(cwd, { recursive: true, force: true });
+    cwd = undefined;
+  });
+
+  it('TC-02: text format exits 1 and writes the auth failure to stderr', async () => {
+    cwd = mkdtempSync(join(tmpdir(), 'robota-headless-fail-'));
+    const session = new InteractiveSession({
+      cwd,
+      provider: createAuthFailingProvider(),
+      config: createConfig(),
+      permissionMode: 'bypassPermissions',
+      bare: true,
+    });
+    const stdout = captureStream(process.stdout);
+    const stderr = captureStream(process.stderr);
+
+    try {
+      const transport = createHeadlessTransport({ outputFormat: 'text', prompt: 'say hi' });
+      session.attachTransport(transport);
+      await transport.start();
+
+      expect(transport.getExitCode()).toBe(1);
+      expect(stderr.writes.join('')).toContain('authentication_error');
+    } finally {
+      stdout.restore();
+      stderr.restore();
+    }
+  });
+
+  it('TC-02: json format exits 1 with subtype error and error_code api_error', async () => {
+    cwd = mkdtempSync(join(tmpdir(), 'robota-headless-fail-'));
+    const session = new InteractiveSession({
+      cwd,
+      provider: createAuthFailingProvider(),
+      config: createConfig(),
+      permissionMode: 'bypassPermissions',
+      bare: true,
+    });
+    const stdout = captureStream(process.stdout);
+    const stderr = captureStream(process.stderr);
+
+    try {
+      const transport = createHeadlessTransport({ outputFormat: 'json', prompt: 'say hi' });
+      session.attachTransport(transport);
+      await transport.start();
+
+      expect(transport.getExitCode()).toBe(1);
+      const parsed: unknown = JSON.parse(stdout.writes.join('').trim());
+      expect(parsed).toMatchObject({
+        type: 'result',
+        subtype: 'error',
+        error_code: 'api_error',
+      });
+    } finally {
+      stdout.restore();
+      stderr.restore();
+    }
+  });
+});

package/src/headless/__tests__/headless-runner-initialization.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 import { createHeadlessRunner } from '../headless-runner.js';
 
 describe('createHeadlessRunner initialization', () => {

package/src/headless/__tests__/headless-runner.test.ts

@@ -1,7 +1,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
-import type { IExecutionResult } from '@robota-sdk/agent-framework';
-import type { TBackgroundJobGroupEvent } from '@robota-sdk/agent-framework';
+import type {
+  IExecutionResult,
+  IInteractiveSession,
+  TBackgroundJobGroupEvent,
+} from '@robota-sdk/agent-interface-transport';
 import type { TBackgroundTaskEvent } from '@robota-sdk/agent-framework';
 import { createHeadlessRunner } from '../headless-runner.js';
 
@@ -96,6 +98,25 @@ describe('createHeadlessRunner (text format)', () => {
     expect(stdoutWriteSpy).not.toHaveBeenCalled();
   });
 
+  it('TC-02 (CLI-064): text format writes the error message to stderr on error', async () => {
+    const stderrWrites: string[] = [];
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(((chunk: unknown) => {
+      stderrWrites.push(String(chunk));
+      return true;
+    }) as never);
+    try {
+      const session = createMockSession('error');
+      const runner = createHeadlessRunner({ session, outputFormat: 'text' });
+
+      const exitCode = await runner.run('test prompt');
+
+      expect(exitCode).toBe(1);
+      expect(stderrWrites.join('')).toContain('test error');
+    } finally {
+      stderrSpy.mockRestore();
+    }
+  });
+
   it('passes the prompt to session.submit', async () => {
     const session = createMockSession('complete', 'ok');
     const runner = createHeadlessRunner({ session, outputFormat: 'text' });

package/src/headless/__tests__/headless-transport.test.ts

@@ -1,7 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { createHeadlessTransport } from '../headless-transport.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
-import type { IExecutionResult } from '@robota-sdk/agent-framework';
+import type { IExecutionResult, IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 
 function createMockSession(): IInteractiveSession {
   return {

package/src/headless/headless-runner.ts

@@ -1,6 +1,6 @@
 import { executeSlashCommandIfPresent, subscribeStreamJsonEvents } from './headless-stream-json.js';
 
-import type { IInteractiveSession, IExecutionResult } from '@robota-sdk/agent-framework';
+import type { IExecutionResult, IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 
 export type TOutputFormat = 'text' | 'json' | 'stream-json';
 
@@ -78,8 +78,9 @@ function runTextFormat(session: IInteractiveSession, prompt: string): Promise<nu
       if (result.response) process.stdout.write(result.response + '\n');
       resolve(0);
     };
-    const onError = (_error: Error): void => {
+    const onError = (error: Error): void => {
       cleanup();
+      process.stderr.write(error.message + '\n');
       resolve(1);
     };
 

package/src/headless/headless-stream-json.ts

@@ -1,12 +1,12 @@
 import { randomUUID } from 'node:crypto';
 
+import type { TBackgroundTaskEvent } from '@robota-sdk/agent-framework';
 import type {
-  IInteractiveSession,
-  IExecutionResult,
   ICommandResult,
+  IExecutionResult,
+  IInteractiveSession,
   TBackgroundJobGroupEvent,
-  TBackgroundTaskEvent,
-} from '@robota-sdk/agent-framework';
+} from '@robota-sdk/agent-interface-transport';
 
 type TSlashCommandExecution =
   | { readonly kind: 'not-slash' }
@@ -65,7 +65,7 @@ interface IStreamJsonHandlers {
   onError: (error: Error) => void;
 }
 
-export function writeStreamJsonEvent(
+function writeStreamJsonEvent(
   session: IInteractiveSession,
   getSessionId: (s: IInteractiveSession) => string,
   event: TStreamJsonEvent,

package/src/headless/headless-transport.ts

@@ -8,8 +8,7 @@
 import { createHeadlessRunner } from './headless-runner.js';
 
 import type { TOutputFormat } from './headless-runner.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
-import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession, ITransportAdapter } from '@robota-sdk/agent-interface-transport';
 
 export interface IHeadlessTransportOptions {
   /** Output format: 'text', 'json', or 'stream-json'. */

package/src/http/__tests__/http-transport.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import { createHttpTransport } from '../http-transport.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 
 function createMockSession(): IInteractiveSession {
   return {

package/src/http/__tests__/routes.test.ts

@@ -5,7 +5,7 @@
 
 import { describe, it, expect, vi } from 'vitest';
 import { createAgentRoutes } from '../routes.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 
 function createMockSession(overrides?: Record<string, unknown>) {
   return {

package/src/http/http-transport.ts

@@ -7,8 +7,7 @@
 
 import { createAgentRoutes } from './routes.js';
 
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
-import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession, ITransportAdapter } from '@robota-sdk/agent-interface-transport';
 import type { Hono } from 'hono';
 
 export interface IHttpTransportOptions {

package/src/http/routes.ts

@@ -8,7 +8,7 @@
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 import type { Context } from 'hono';
 
 /** Callback that resolves an IInteractiveSession from the request context. */

package/src/mcp/__tests__/mcp-server.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, it, expect, vi } from 'vitest';
 import { createAgentMcpServer } from '../mcp-server.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 
 function createMockSession(commands?: Array<{ name: string; description: string }>) {
   return {

package/src/mcp/__tests__/mcp-transport.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import { createMcpTransport } from '../mcp-transport.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 
 function createMockSession(): IInteractiveSession {
   return {

package/src/mcp/mcp-server.ts

@@ -9,7 +9,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 
-import type { IInteractiveSession, IExecutionResult } from '@robota-sdk/agent-framework';
+import type { IExecutionResult, IInteractiveSession } from '@robota-sdk/agent-interface-transport';
 
 export interface IAgentMcpOptions {
   /** Name for the MCP server. */

package/src/mcp/mcp-transport.ts

@@ -8,8 +8,7 @@
 import { createAgentMcpServer } from './mcp-server.js';
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
-import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession, ITransportAdapter } from '@robota-sdk/agent-interface-transport';
 
 export interface IMcpTransportOptions {
   /** Name for the MCP server. */

package/src/testing/__tests__/scripted-provider.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Scripted provider fixture tests (CLI-074 TC-01).
+ *
+ * The fixture must replay declared turns in order, record every request's
+ * message array for assertions, and fail fast on script exhaustion — never
+ * silently improvise a response.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { createScriptedProvider } from '../scripted-provider.js';
+
+describe('createScriptedProvider (CLI-074)', () => {
+  it('TC-01: replays text turns in order and records requests', async () => {
+    const { provider, requests } = createScriptedProvider([
+      { text: 'first answer' },
+      { text: 'second answer' },
+    ]);
+
+    const first = await provider.chat([
+      { id: 'u1', role: 'user', content: 'hi', state: 'complete', timestamp: new Date() },
+    ]);
+    const second = await provider.chat([
+      { id: 'u2', role: 'user', content: 'again', state: 'complete', timestamp: new Date() },
+    ]);
+
+    expect(first.role).toBe('assistant');
+    expect(first.content).toBe('first answer');
+    expect(second.content).toBe('second answer');
+    expect(requests).toHaveLength(2);
+    expect(requests[0]?.map((message) => message.content)).toContain('hi');
+    expect(requests[1]?.map((message) => message.content)).toContain('again');
+  });
+
+  it('TC-01: replays tool_use turns as assistant toolCalls', async () => {
+    const { provider } = createScriptedProvider([
+      { toolCalls: [{ name: 'Read', args: { file_path: '/tmp/a.txt' } }] },
+      { text: 'done reading' },
+    ]);
+
+    const turn = await provider.chat([
+      { id: 'u1', role: 'user', content: 'read it', state: 'complete', timestamp: new Date() },
+    ]);
+
+    expect(turn.role).toBe('assistant');
+    if (turn.role !== 'assistant') throw new Error('unreachable');
+    expect(turn.content).toBeNull();
+    expect(turn.toolCalls).toHaveLength(1);
+    expect(turn.toolCalls?.[0]?.function.name).toBe('Read');
+    expect(JSON.parse(turn.toolCalls?.[0]?.function.arguments ?? '{}')).toEqual({
+      file_path: '/tmp/a.txt',
+    });
+  });
+
+  it('TC-01: throws on script exhaustion instead of improvising', async () => {
+    const { provider } = createScriptedProvider([{ text: 'only turn' }]);
+
+    await provider.chat([
+      { id: 'u1', role: 'user', content: 'one', state: 'complete', timestamp: new Date() },
+    ]);
+
+    await expect(
+      provider.chat([
+        { id: 'u2', role: 'user', content: 'two', state: 'complete', timestamp: new Date() },
+      ]),
+    ).rejects.toThrow(/script exhausted/i);
+  });
+
+  it('supportsTools is true and validateConfig passes (agent-loop prerequisites)', () => {
+    const { provider } = createScriptedProvider([{ text: 'x' }]);
+    expect(provider.supportsTools()).toBe(true);
+  });
+});

package/src/testing/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Test-only fixtures (CLI-074). Exported via the `./testing` subpath; never import
+ * from runtime code.
+ */
+
+export { createScriptedProvider } from './scripted-provider.js';
+export type { IScriptedProvider, TScriptedTurn } from './scripted-provider.js';

package/src/testing/scripted-provider.ts

@@ -0,0 +1,73 @@
+/**
+ * Deterministic scripted provider for E2E tests (CLI-074).
+ *
+ * Replays a declared sequence of assistant turns through the REAL agent loop —
+ * tool execution, permission gate, session persistence, and output transports all
+ * run unmocked. Test-only: exported via the `@robota-sdk/agent-transport/testing`
+ * subpath and never imported by runtime code.
+ */
+
+import type { IAIProvider, IRawProviderResponse, TUniversalMessage } from '@robota-sdk/agent-core';
+
+/** One scripted assistant turn: plain text or tool invocations. */
+export type TScriptedTurn =
+  | { text: string }
+  | { toolCalls: ReadonlyArray<{ name: string; args: Record<string, unknown> }> };
+
+export interface IScriptedProvider {
+  provider: IAIProvider;
+  /** Message arrays of every chat() call, in order, for request assertions. */
+  requests: TUniversalMessage[][];
+}
+
+export function createScriptedProvider(turns: readonly TScriptedTurn[]): IScriptedProvider {
+  const requests: TUniversalMessage[][] = [];
+  let cursor = 0;
+
+  const provider: IAIProvider = {
+    name: 'scripted-test-provider',
+    version: 'test',
+    async chat(messages: TUniversalMessage[]): Promise<TUniversalMessage> {
+      requests.push([...messages]);
+      const turn = turns[cursor];
+      if (turn === undefined) {
+        throw new Error(
+          `Scripted provider: script exhausted at call ${cursor + 1} (script declares ${turns.length} turn(s)) — extend the script instead of relying on improvised responses`,
+        );
+      }
+      cursor += 1;
+      if ('text' in turn) {
+        return {
+          id: `scripted-${cursor}`,
+          role: 'assistant',
+          content: turn.text,
+          state: 'complete',
+          timestamp: new Date(),
+        };
+      }
+      return {
+        id: `scripted-${cursor}`,
+        role: 'assistant',
+        content: null,
+        state: 'complete',
+        timestamp: new Date(),
+        toolCalls: turn.toolCalls.map((call, index) => ({
+          id: `scripted-call-${cursor}-${index}`,
+          type: 'function' as const,
+          function: { name: call.name, arguments: JSON.stringify(call.args) },
+        })),
+      };
+    },
+    async generateResponse(): Promise<IRawProviderResponse> {
+      return { content: 'scripted provider does not implement raw responses' };
+    },
+    supportsTools(): boolean {
+      return true;
+    },
+    validateConfig(): boolean {
+      return true;
+    },
+  };
+
+  return { provider, requests };
+}

package/src/transport-registry.ts

@@ -11,9 +11,9 @@ import { readSettings, writeSettings, type TSettingsData } from '@robota-sdk/age
 import { WsTransport } from './ws/index.js';
 
 import type { TUniversalValue } from '@robota-sdk/agent-core';
-import type { IInteractiveSession } from '@robota-sdk/agent-framework';
 import type {
   IConfigurableTransport,
+  IInteractiveSession,
   ITransportConfig,
   ITransportEntry,
 } from '@robota-sdk/agent-interface-transport';

package/src/tui/App.tsx

@@ -31,16 +31,19 @@ import type { ITuiCliAdapter } from './tui-cli-adapter.js';
 import type { TuiInteractionChannel } from './TuiInteractionChannel.js';
 import type { TPermissionMode } from '@robota-sdk/agent-core';
 import type {
+  IExecutionDetailPage,
   IInteractiveSession,
   IInteractiveSessionStore,
-  IExecutionDetailPage,
-} from '@robota-sdk/agent-framework';
-import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+  ITransportRegistryView,
+} from '@robota-sdk/agent-interface-transport';
 
 interface IProps {
   cwd: string;
-  channel: TuiInteractionChannel;
-  createChannel?: (resumeSessionId?: string) => TuiInteractionChannel;
+  /**
+   * Sole channel source (CLI-B12): App owns the channel lifecycle in React state.
+   * The initial channel and every session-switch replacement come from this factory.
+   */
+  createChannel: (resumeSessionId?: string) => TuiInteractionChannel;
   providerOverride?: string | undefined;
   providerType?: string | undefined;
   modelId?: string;
@@ -55,10 +58,15 @@ interface IProps {
 }
 
 export default function App(props: IProps): React.ReactElement {
+  // Lazy initializer: channel construction is side-effect-free (object wiring only);
+  // I/O starts in AppInner's effect via channel.start(). Runs once per mount.
   const [sessionState, setSessionState] = useState<{
     channel: TuiInteractionChannel;
     sessionId: string | undefined;
-  }>({ channel: props.channel, sessionId: props.resumeSessionId });
+  }>(() => ({
+    channel: props.createChannel(props.resumeSessionId),
+    sessionId: props.resumeSessionId,
+  }));
   const [showInitialSessionPicker, setShowInitialSessionPicker] = useState(
     props.showSessionPickerOnStart ?? false,
   );
@@ -73,10 +81,10 @@ export default function App(props: IProps): React.ReactElement {
         resumeSessionId={sessionState.sessionId}
         onSessionSwitch={(sessionId) => {
           setShowInitialSessionPicker(false);
-          const oldChannel = sessionState.channel;
-          const newChannel = props.createChannel ? props.createChannel(sessionId) : props.channel;
-          setSessionState({ channel: newChannel, sessionId });
-          void oldChannel.stop();
+          // Stop the old channel BEFORE the new one becomes active so it can
+          // never receive events addressed to the new session (CLI-B12).
+          void sessionState.channel.stop();
+          setSessionState({ channel: props.createChannel(sessionId), sessionId });
         }}
       />
     </TuiCliAdapterProvider>
@@ -84,7 +92,10 @@ export default function App(props: IProps): React.ReactElement {
 }
 
 function AppInner(
-  props: IProps & { onSessionSwitch: (sessionId: string) => void },
+  props: IProps & {
+    channel: TuiInteractionChannel;
+    onSessionSwitch: (sessionId: string) => void;
+  },
 ): React.ReactElement {
   const cwd = props.cwd;
   const { channel } = props;
@@ -436,22 +447,6 @@ function AppInner(
         />
       )}
       <ContextWarningBanner percentage={contextState.percentage} />
-      <SessionStatusBar
-        cwd={cwd}
-        permissionMode={permissionMode}
-        modelId={props.modelId}
-        providerType={props.providerType}
-        sessionId={sessionId}
-        isThinking={isThinking}
-        activeToolCount={activeTools.length}
-        activeBackgroundTaskCount={activeBackgroundTaskCount}
-        hasPendingPrompt={pendingPrompt !== null}
-        contextState={contextState}
-        sessionName={sessionName}
-        settings={statusLineSettings}
-        activeAgentLabel={activeAgentLabel}
-        gitRefreshToken={gitRefreshToken}
-      />
       <InputArea
         onSubmit={handleSubmitWithGitRefresh}
         onCancelQueue={handleCancelQueue}
@@ -472,8 +467,22 @@ function AppInner(
         sessionName={sessionName}
         history={history}
       />
-      {/* Blank line for Korean IME — normal flow ensures it persists across remounts. */}
-      <Text> </Text>
+      <SessionStatusBar
+        cwd={cwd}
+        permissionMode={permissionMode}
+        modelId={props.modelId}
+        providerType={props.providerType}
+        sessionId={sessionId}
+        isThinking={isThinking}
+        activeToolCount={activeTools.length}
+        activeBackgroundTaskCount={activeBackgroundTaskCount}
+        hasPendingPrompt={pendingPrompt !== null}
+        contextState={contextState}
+        sessionName={sessionName}
+        settings={statusLineSettings}
+        activeAgentLabel={activeAgentLabel}
+        gitRefreshToken={gitRefreshToken}
+      />
     </Box>
   );
 }

package/src/tui/BackgroundTaskPanel.tsx

@@ -3,7 +3,7 @@ import React from 'react';
 
 import { formatBackgroundTaskRow } from './background-task-row-format.js';
 
-import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-framework';
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-transport';
 
 interface IProps {
   entries: IExecutionWorkspaceEntry[];

package/src/tui/CjkTextInput.tsx

@@ -79,14 +79,10 @@ export default function CjkTextInput({
     forceRender,
   });
 
-  // Do NOT call setCursorPosition() — passing y:0 moves the real terminal cursor
-  // to the top of the entire ink output (logo area), which causes Terminal.app to
-  // SIGSEGV when Korean IME queries attributedSubstringFromRange: at that position.
-  // Without setCursorPosition, the IME candidate window appears at bottom-left
-  // (same behavior as Claude Code, issue #19207), but Terminal.app does not crash.
-  //
-  // A correct fix would require knowing the total rendered height to pass the right
-  // y coordinate, which ink does not expose to components.
+  // Real terminal cursor positioning is intentionally omitted.
+  // setCursorPosition(x, 0) crashes Terminal.app via Korean IME SIGSEGV.
+  // Correct fix requires the input row's y offset from the bottom of the render,
+  // which Ink does not expose. Tracked as a known limitation.
 
   return (
     <Text>

package/src/tui/ExecutionWorkspaceDetailPane.tsx

@@ -10,7 +10,7 @@ import type {
   IExecutionDetailPage,
   IExecutionWorkspaceEntry,
   TExecutionDetailRecordKind,
-} from '@robota-sdk/agent-framework';
+} from '@robota-sdk/agent-interface-transport';
 
 const MAX_VISIBLE_DETAIL_RECORDS = 12;