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

package/src/tui/utils/tool-call-extractor.ts

@@ -0,0 +1,91 @@
+/**
+ * Extracts tool call summaries from session history messages.
+ * Pure function — no side effects, no framework dependencies.
+ */
+
+import { extractEditDiff } from './edit-diff.js';
+import type { IDiffLine } from './edit-diff.js';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+
+const TOOL_ARG_MAX_LENGTH = 80;
+const TAIL_KEEP = 30;
+const ELLIPSIS_LEN = 3;
+
+interface IHistoryMessage {
+  role: string;
+  toolCalls?: Array<{
+    function: { name: string; arguments: string };
+  }>;
+}
+
+/** A tool call summary with optional diff for Edit tools */
+export interface IToolCallSummary {
+  line: string;
+  diffLines?: IDiffLine[];
+  diffFile?: string;
+}
+
+/**
+ * Extract tool call display lines from history messages.
+ * Format: `ToolName(firstArgValue)` — first argument value truncated to 80 chars.
+ * Edit tools include diff information.
+ */
+export function extractToolCalls(history: IHistoryMessage[], startIndex: number): string[] {
+  return extractToolCallsWithDiff(history, startIndex).map((s) => s.line);
+}
+
+/**
+ * Extract tool call summaries with diff info from history messages.
+ */
+export function extractToolCallsWithDiff(
+  history: IHistoryMessage[],
+  startIndex: number,
+): IToolCallSummary[] {
+  const summaries: IToolCallSummary[] = [];
+  for (let i = startIndex; i < history.length; i++) {
+    const msg = history[i];
+    if (msg.role === 'assistant' && msg.toolCalls) {
+      for (const tc of msg.toolCalls) {
+        const value = parseFirstArgValue(tc.function.arguments);
+        const truncated =
+          value.length > TOOL_ARG_MAX_LENGTH
+            ? value.slice(0, TOOL_ARG_MAX_LENGTH - TAIL_KEEP - ELLIPSIS_LEN) +
+              '...' +
+              value.slice(-TAIL_KEEP)
+            : value;
+
+        const summary: IToolCallSummary = {
+          line: `${tc.function.name}(${truncated})`,
+        };
+
+        // Extract diff for Edit tool
+        if (tc.function.name === 'Edit') {
+          try {
+            const args = JSON.parse(tc.function.arguments) as Record<string, TUniversalValue>;
+            const diff = extractEditDiff('Edit', args);
+            if (diff) {
+              summary.diffLines = diff.lines;
+              summary.diffFile = diff.file;
+            }
+          } catch {
+            // ignore parse errors
+          }
+        }
+
+        summaries.push(summary);
+      }
+    }
+  }
+  return summaries;
+}
+
+/** Parse the first argument value from a JSON arguments string. */
+function parseFirstArgValue(argsJson: string): string {
+  try {
+    const parsed = JSON.parse(argsJson) as Record<string, TUniversalValue>;
+    const firstVal = Object.values(parsed)[0];
+    return typeof firstVal === 'string' ? firstVal : JSON.stringify(firstVal);
+  } catch {
+    return argsJson;
+  }
+}

package/src/tui/utils/tool-diff-summary.ts

@@ -0,0 +1,75 @@
+import type { IDiffLine } from './edit-diff.js';
+
+const MAX_DIFF_LINES = 12;
+const TRUNCATED_SHOW = 10;
+
+export interface IToolDiffSummaryInput {
+  file?: string;
+  lines: readonly IDiffLine[];
+}
+
+export interface IToolDiffSummary {
+  file?: string;
+  markdown: string;
+  truncated: boolean;
+  remainingLineCount: number;
+}
+
+export function buildToolDiffSummary(input: IToolDiffSummaryInput): IToolDiffSummary {
+  const visibleLines =
+    input.lines.length > MAX_DIFF_LINES ? selectVisibleDiffLines(input.lines) : input.lines;
+  const lineNumberWidth = Math.max(...visibleLines.map((line) => line.lineNumber), 0).toString()
+    .length;
+  const body = visibleLines.map((line) => formatDiffLine(line, lineNumberWidth));
+  const truncated = input.lines.length > MAX_DIFF_LINES;
+
+  return {
+    file: input.file,
+    markdown: ['```diff', ...body, '```'].join('\n'),
+    truncated,
+    remainingLineCount: truncated ? input.lines.length - visibleLines.length : 0,
+  };
+}
+
+function formatDiffLine(line: IDiffLine, lineNumberWidth: number): string {
+  if (line.type === 'hunk') return line.text;
+  const lineNumber = line.lineNumber.toString().padStart(lineNumberWidth, ' ');
+  if (line.type === 'remove') return `- ${lineNumber} | ${line.text}`;
+  if (line.type === 'add') return `+ ${lineNumber} | ${line.text}`;
+  return `  ${lineNumber} | ${line.text}`;
+}
+
+function selectVisibleDiffLines(lines: readonly IDiffLine[]): readonly IDiffLine[] {
+  const groups = groupByHunk(lines);
+  const visible: IDiffLine[] = [];
+
+  for (const group of groups) {
+    if (visible.length === 0 && group.length > TRUNCATED_SHOW) {
+      return group.slice(0, TRUNCATED_SHOW);
+    }
+    if (visible.length + group.length > TRUNCATED_SHOW) break;
+    visible.push(...group);
+  }
+
+  return visible.length > 0 ? visible : lines.slice(0, TRUNCATED_SHOW);
+}
+
+function groupByHunk(lines: readonly IDiffLine[]): IDiffLine[][] {
+  const groups: IDiffLine[][] = [];
+  let current: IDiffLine[] = [];
+
+  for (const line of lines) {
+    if (line.type === 'hunk' && current.length > 0) {
+      groups.push(current);
+      current = [line];
+      continue;
+    }
+    current.push(line);
+  }
+
+  if (current.length > 0) {
+    groups.push(current);
+  }
+
+  return groups;
+}

package/src/ws/__tests__/ws-handler.test.ts

@@ -0,0 +1,407 @@
+/**
+ * Tests for WebSocket transport handler.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createWsHandler } from '../ws-handler.js';
+import type { TServerMessage } from '../ws-protocol.js';
+import type {
+  IBackgroundTaskLogPage,
+  IBackgroundTaskState,
+  IExecutionWorkspaceEvent,
+  IExecutionWorkspaceSnapshot,
+  IInteractiveSession,
+  IBackgroundJobGroupState,
+  TBackgroundJobGroupEvent,
+  TBackgroundTaskEvent,
+  TExecutionWorkspaceUpdateCause,
+} from '@robota-sdk/agent-framework';
+
+const backgroundTask: IBackgroundTaskState = {
+  id: 'task_1',
+  kind: 'agent',
+  label: 'Explore',
+  agentType: 'Explore',
+  status: 'running',
+  mode: 'background',
+  parentSessionId: 'session_1',
+  depth: 0,
+  cwd: '/repo',
+  updatedAt: '2026-05-01T00:00:00.000Z',
+  unread: false,
+  promptPreview: 'inspect code',
+};
+
+const backgroundTaskLogPage: IBackgroundTaskLogPage = {
+  taskId: 'task_1',
+  cursor: { offset: 0 },
+  lines: ['line one'],
+};
+
+const executionWorkspaceSnapshot: IExecutionWorkspaceSnapshot = {
+  sessionId: 'session_1',
+  entries: [],
+  updatedAt: '2026-05-01T00:00:00.000Z',
+};
+
+const backgroundJobGroup: IBackgroundJobGroupState = {
+  id: 'group_1',
+  parentSessionId: 'session_1',
+  waitPolicy: 'wait_all',
+  taskIds: ['task_1'],
+  status: 'running',
+  createdAt: '2026-05-01T00:00:00.000Z',
+  updatedAt: '2026-05-01T00:00:00.000Z',
+  results: [],
+};
+
+function createMockSession() {
+  const listeners = new Map<string, Set<(...args: unknown[]) => void>>();
+  return {
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    getMessages: vi.fn().mockReturnValue([{ role: 'user', content: 'hi' }]),
+    getContextState: vi
+      .fn()
+      .mockReturnValue({ usedTokens: 500, maxTokens: 100000, usedPercentage: 0.5 }),
+    isExecuting: vi.fn().mockReturnValue(false),
+    getPendingPrompt: vi.fn().mockReturnValue(null),
+    listBackgroundTasks: vi.fn().mockReturnValue([backgroundTask]),
+    getBackgroundTask: vi.fn().mockReturnValue(backgroundTask),
+    listBackgroundJobGroups: vi.fn().mockReturnValue([backgroundJobGroup]),
+    getBackgroundJobGroup: vi.fn().mockReturnValue(backgroundJobGroup),
+    waitBackgroundJobGroup: vi.fn().mockResolvedValue({
+      ...backgroundJobGroup,
+      status: 'completed',
+      completedAt: '2026-05-01T00:00:01.000Z',
+      results: [{ taskId: 'task_1', label: 'Explore', status: 'completed', summary: 'done' }],
+    }),
+    cancelBackgroundTask: vi.fn().mockResolvedValue(undefined),
+    closeBackgroundTask: vi.fn().mockResolvedValue(undefined),
+    sendBackgroundTask: vi.fn().mockResolvedValue(undefined),
+    readBackgroundTaskLog: vi.fn().mockResolvedValue(backgroundTaskLogPage),
+    getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue(executionWorkspaceSnapshot),
+    executeCommand: vi.fn().mockResolvedValue({ message: 'done', success: true, data: {} }),
+    listCommands: vi.fn().mockReturnValue([]),
+    on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }),
+    off: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      listeners.get(event)?.delete(handler);
+    }),
+    _emit: (event: string, ...args: unknown[]) => {
+      listeners.get(event)?.forEach((h) => h(...args));
+    },
+  } as unknown as IInteractiveSession & { _emit: (event: string, ...args: unknown[]) => void };
+}
+
+describe('WebSocket Transport Handler', () => {
+  function setup() {
+    const session = createMockSession();
+    const sent: TServerMessage[] = [];
+    const { onMessage, cleanup } = createWsHandler({
+      session: session as unknown as IInteractiveSession,
+      send: (msg) => sent.push(msg),
+    });
+    return { session, sent, onMessage, cleanup };
+  }
+
+  it('submit calls session.submit()', () => {
+    const { onMessage, session } = setup();
+    onMessage(JSON.stringify({ type: 'submit', prompt: 'hello' }));
+    expect(
+      (session as unknown as { submit: ReturnType<typeof vi.fn> }).submit,
+    ).toHaveBeenCalledWith('hello');
+  });
+
+  it('abort calls session.abort()', () => {
+    const { onMessage, session } = setup();
+    onMessage(JSON.stringify({ type: 'abort' }));
+    expect((session as unknown as { abort: ReturnType<typeof vi.fn> }).abort).toHaveBeenCalled();
+  });
+
+  it('cancel-queue calls session.cancelQueue()', () => {
+    const { onMessage, session } = setup();
+    onMessage(JSON.stringify({ type: 'cancel-queue' }));
+    expect(
+      (session as unknown as { cancelQueue: ReturnType<typeof vi.fn> }).cancelQueue,
+    ).toHaveBeenCalled();
+  });
+
+  it('get-messages sends messages back', () => {
+    const { onMessage, sent } = setup();
+    onMessage(JSON.stringify({ type: 'get-messages' }));
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.type).toBe('messages');
+  });
+
+  it('get-context sends context state back', () => {
+    const { onMessage, sent } = setup();
+    onMessage(JSON.stringify({ type: 'get-context' }));
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.type).toBe('context');
+  });
+
+  it('get-executing sends executing status', () => {
+    const { onMessage, sent } = setup();
+    onMessage(JSON.stringify({ type: 'get-executing' }));
+    expect(sent[0]).toEqual({ type: 'executing', executing: false });
+  });
+
+  it('get-pending sends pending prompt', () => {
+    const { onMessage, sent } = setup();
+    onMessage(JSON.stringify({ type: 'get-pending' }));
+    expect(sent[0]).toEqual({ type: 'pending', pending: null });
+  });
+
+  it('get-background-tasks sends current background task list', () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(JSON.stringify({ type: 'get-background-tasks', filter: { kind: 'agent' } }));
+
+    expect(sent[0]).toEqual({ type: 'background_tasks', tasks: [backgroundTask] });
+    expect(
+      (session as unknown as { listBackgroundTasks: ReturnType<typeof vi.fn> }).listBackgroundTasks,
+    ).toHaveBeenCalledWith({ kind: 'agent' });
+  });
+
+  it('get-background-task sends one background task snapshot', () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(JSON.stringify({ type: 'get-background-task', taskId: 'task_1' }));
+
+    expect(sent[0]).toEqual({
+      type: 'background_task',
+      taskId: 'task_1',
+      task: backgroundTask,
+    });
+    expect(
+      (session as unknown as { getBackgroundTask: ReturnType<typeof vi.fn> }).getBackgroundTask,
+    ).toHaveBeenCalledWith('task_1');
+  });
+
+  it('get-background-job-groups sends group snapshots', () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(JSON.stringify({ type: 'get-background-job-groups' }));
+
+    expect(sent[0]).toEqual({ type: 'background_job_groups', groups: [backgroundJobGroup] });
+    expect(
+      (session as unknown as { listBackgroundJobGroups: ReturnType<typeof vi.fn> })
+        .listBackgroundJobGroups,
+    ).toHaveBeenCalled();
+  });
+
+  it('get-background-job-group sends one group snapshot', () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(JSON.stringify({ type: 'get-background-job-group', groupId: 'group_1' }));
+
+    expect(sent[0]).toEqual({
+      type: 'background_job_group',
+      groupId: 'group_1',
+      group: backgroundJobGroup,
+    });
+    expect(
+      (session as unknown as { getBackgroundJobGroup: ReturnType<typeof vi.fn> })
+        .getBackgroundJobGroup,
+    ).toHaveBeenCalledWith('group_1');
+  });
+
+  it('wait-background-job-group waits and sends the completed group', async () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(JSON.stringify({ type: 'wait-background-job-group', groupId: 'group_1' }));
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(
+      (session as unknown as { waitBackgroundJobGroup: ReturnType<typeof vi.fn> })
+        .waitBackgroundJobGroup,
+    ).toHaveBeenCalledWith('group_1');
+    expect(sent[0]).toMatchObject({
+      type: 'background_job_group',
+      groupId: 'group_1',
+      group: { id: 'group_1', status: 'completed' },
+    });
+  });
+
+  it('cancel-background-task maps to session control and emits control result', async () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(JSON.stringify({ type: 'cancel-background-task', taskId: 'task_1', reason: 'stop' }));
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(
+      (session as unknown as { cancelBackgroundTask: ReturnType<typeof vi.fn> })
+        .cancelBackgroundTask,
+    ).toHaveBeenCalledWith('task_1', 'stop');
+    expect(sent[0]).toEqual({
+      type: 'background_task_control_result',
+      action: 'cancel',
+      taskId: 'task_1',
+      success: true,
+    });
+  });
+
+  it('send-background-task maps prompt input to session control', async () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(
+      JSON.stringify({
+        type: 'send-background-task',
+        taskId: 'task_1',
+        input: { prompt: 'continue' },
+      }),
+    );
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(
+      (session as unknown as { sendBackgroundTask: ReturnType<typeof vi.fn> }).sendBackgroundTask,
+    ).toHaveBeenCalledWith('task_1', { prompt: 'continue' });
+    expect(sent[0]).toEqual({
+      type: 'background_task_control_result',
+      action: 'send',
+      taskId: 'task_1',
+      success: true,
+    });
+  });
+
+  it('read-background-task-log sends log page', async () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(
+      JSON.stringify({
+        type: 'read-background-task-log',
+        taskId: 'task_1',
+        cursor: { offset: 0 },
+      }),
+    );
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(
+      (session as unknown as { readBackgroundTaskLog: ReturnType<typeof vi.fn> })
+        .readBackgroundTaskLog,
+    ).toHaveBeenCalledWith('task_1', { offset: 0 });
+    expect(sent[0]).toEqual({
+      type: 'background_task_log',
+      taskId: 'task_1',
+      page: backgroundTaskLogPage,
+    });
+  });
+
+  it('command executes via session.executeCommand()', async () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(JSON.stringify({ type: 'command', name: 'clear' }));
+    await new Promise((r) => setTimeout(r, 10));
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.type).toBe('command_result');
+    expect(
+      (session as unknown as { executeCommand: ReturnType<typeof vi.fn> }).executeCommand,
+    ).toHaveBeenCalledWith('clear', '');
+  });
+
+  it('invalid JSON sends protocol_error', () => {
+    const { onMessage, sent } = setup();
+    onMessage('not json');
+    expect(sent[0]).toEqual({ type: 'protocol_error', message: 'Invalid JSON' });
+  });
+
+  it('unknown type sends protocol_error', () => {
+    const { onMessage, sent } = setup();
+    onMessage(JSON.stringify({ type: 'unknown_type' }));
+    expect(sent[0]!.type).toBe('protocol_error');
+  });
+
+  it('submit without prompt sends protocol_error', () => {
+    const { onMessage, sent } = setup();
+    onMessage(JSON.stringify({ type: 'submit' }));
+    expect(sent[0]).toEqual({ type: 'protocol_error', message: 'prompt is required' });
+  });
+
+  it('forwards InteractiveSession events to client', () => {
+    const { session, sent } = setup();
+    (session as unknown as { _emit: (e: string, ...args: unknown[]) => void })._emit(
+      'text_delta',
+      'hello',
+    );
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toEqual({ type: 'text_delta', delta: 'hello' });
+  });
+
+  it('forwards thinking event', () => {
+    const { session, sent } = setup();
+    (session as unknown as { _emit: (e: string, ...args: unknown[]) => void })._emit(
+      'thinking',
+      true,
+    );
+    expect(sent[0]).toEqual({ type: 'thinking', isThinking: true });
+  });
+
+  it('forwards background task events to the client', () => {
+    const { session, sent } = setup();
+    const event: TBackgroundTaskEvent = {
+      type: 'background_task_text_delta',
+      taskId: 'task_1',
+      delta: 'partial',
+    };
+    (session as unknown as { _emit: (e: string, ...args: unknown[]) => void })._emit(
+      'background_task_event',
+      event,
+    );
+
+    expect(sent[0]).toEqual({ type: 'background_task_event', event });
+  });
+
+  it('forwards background job group events to the client', () => {
+    const { session, sent } = setup();
+    const event: TBackgroundJobGroupEvent = {
+      type: 'background_job_group_completed',
+      group: { ...backgroundJobGroup, status: 'completed' },
+    };
+    (session as unknown as { _emit: (e: string, ...args: unknown[]) => void })._emit(
+      'background_job_group_event',
+      event,
+    );
+
+    expect(sent[0]).toEqual({ type: 'background_job_group_event', event });
+  });
+
+  it('forwards execution_workspace_event to the client', () => {
+    const { session, sent } = setup();
+    const event: IExecutionWorkspaceEvent = {
+      type: 'execution_workspace_updated',
+      cause: 'main_thread',
+      snapshot: executionWorkspaceSnapshot,
+    };
+    (session as unknown as { _emit: (e: string, ...args: unknown[]) => void })._emit(
+      'execution_workspace_event',
+      event,
+    );
+
+    expect(sent[0]).toEqual({
+      type: 'execution_workspace_event',
+      snapshot: executionWorkspaceSnapshot,
+    });
+  });
+
+  it('get-execution-workspace sends current snapshot', () => {
+    const { onMessage, sent, session } = setup();
+    onMessage(JSON.stringify({ type: 'get-execution-workspace' }));
+
+    expect(sent[0]).toEqual({
+      type: 'execution_workspace_event',
+      snapshot: executionWorkspaceSnapshot,
+    });
+    expect(
+      (
+        session as unknown as {
+          getExecutionWorkspaceSnapshot: ReturnType<typeof vi.fn>;
+        }
+      ).getExecutionWorkspaceSnapshot,
+    ).toHaveBeenCalled();
+  });
+
+  it('cleanup unsubscribes from all events', () => {
+    const { session, cleanup } = setup();
+    cleanup();
+    expect((session as unknown as { off: ReturnType<typeof vi.fn> }).off).toHaveBeenCalledTimes(11);
+  });
+});

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

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createWsTransport } from '../ws-transport.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+
+function createMockSession(): IInteractiveSession {
+  return {
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    getMessages: vi.fn().mockReturnValue([]),
+    getContextState: vi
+      .fn()
+      .mockReturnValue({ usedPercentage: 0, usedTokens: 0, maxTokens: 200000 }),
+    isExecuting: vi.fn().mockReturnValue(false),
+    getPendingPrompt: vi.fn().mockReturnValue(null),
+    executeCommand: vi.fn().mockResolvedValue({ message: 'ok', success: true }),
+    listCommands: vi.fn().mockReturnValue([]),
+    on: vi.fn(),
+    off: vi.fn(),
+  } as unknown as IInteractiveSession;
+}
+
+describe('createWsTransport', () => {
+  it('returns an adapter with name "ws"', () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    expect(transport.name).toBe('ws');
+  });
+
+  it('throws if start() is called without attach()', async () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    await expect(transport.start()).rejects.toThrow('No session attached');
+  });
+
+  it('onMessage is null before start()', () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    expect(transport.onMessage).toBeNull();
+  });
+
+  it('provides onMessage after attach + start', async () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    transport.attach(createMockSession() as never);
+    await transport.start();
+    expect(typeof transport.onMessage).toBe('function');
+  });
+
+  it('clears onMessage after stop()', async () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    transport.attach(createMockSession() as never);
+    await transport.start();
+    await transport.stop();
+    expect(transport.onMessage).toBeNull();
+  });
+});

package/src/ws/index.ts

@@ -0,0 +1,13 @@
+export { createWsHandler } from './ws-handler.js';
+export type { IWsHandlerOptions } from './ws-handler.js';
+export type { TClientMessage, TServerMessage } from './ws-protocol.js';
+export { createWsTransport } from './ws-transport.js';
+export type { IWsTransportOptions } from './ws-transport.js';
+export { WsTransport } from './ws-transport-configurable.js';
+export type { IWsTransportConfig } from './ws-transport-configurable.js';
+export type {
+  IExecutionWorkspaceSnapshot,
+  IExecutionWorkspaceEntry,
+  TExecutionWorkspaceStatus,
+  TExecutionAttention,
+} from '@robota-sdk/agent-framework';