@robota-sdk/agent-transport-ws 3.0.0-beta.62 → 3.0.0-beta.76

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/ws-background-messages.ts","../../src/ws-handler.ts","../../src/ws-transport.ts","../../src/ws-transport-configurable.ts"],"sourcesContent":["import type { TBackgroundControlAction, TClientMessage, TServerMessage } from './ws-protocol.js';\nimport type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';\n\nexport function handleBackgroundQueryMessage(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<\n    TClientMessage,\n    | { type: 'get-background-tasks' | 'get-background-task' | 'read-background-task-log' }\n    | {\n        type:\n          | 'get-background-job-groups'\n          | 'get-background-job-group'\n          | 'wait-background-job-group';\n      }\n  >,\n): void {\n  if (msg.type === 'get-background-tasks') {\n    send({ type: 'background_tasks', tasks: session.listBackgroundTasks(msg.filter) });\n    return;\n  }\n  if (msg.type === 'get-background-task') {\n    sendBackgroundTaskSnapshot(session, send, msg);\n    return;\n  }\n  if (msg.type === 'get-background-job-groups') {\n    send({ type: 'background_job_groups', groups: session.listBackgroundJobGroups() });\n    return;\n  }\n  if (msg.type === 'get-background-job-group') {\n    sendBackgroundJobGroupSnapshot(session, send, msg);\n    return;\n  }\n  if (msg.type === 'wait-background-job-group') {\n    sendBackgroundJobGroupWaitResult(session, send, msg);\n    return;\n  }\n  sendBackgroundTaskLogPage(session, send, msg);\n}\n\nexport function handleBackgroundControlMessage(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<\n    TClientMessage,\n    { type: 'cancel-background-task' | 'close-background-task' | 'send-background-task' }\n  >,\n): void {\n  if (!msg.taskId) {\n    send({ type: 'protocol_error', message: 'taskId is required' });\n    return;\n  }\n  if (msg.type === 'cancel-background-task') {\n    sendBackgroundTaskControlResult(\n      send,\n      'cancel',\n      msg.taskId,\n      session.cancelBackgroundTask(msg.taskId, msg.reason),\n    );\n    return;\n  }\n  if (msg.type === 'close-background-task') {\n    sendBackgroundTaskControlResult(\n      send,\n      'close',\n      msg.taskId,\n      session.closeBackgroundTask(msg.taskId),\n    );\n    return;\n  }\n  sendBackgroundTaskInput(session, send, msg);\n}\n\nfunction sendBackgroundTaskSnapshot(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<TClientMessage, { type: 'get-background-task' }>,\n): void {\n  if (!msg.taskId) {\n    send({ type: 'protocol_error', message: 'taskId is required' });\n    return;\n  }\n  send({\n    type: 'background_task',\n    taskId: msg.taskId,\n    task: session.getBackgroundTask(msg.taskId) ?? null,\n  });\n}\n\nfunction sendBackgroundTaskLogPage(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<TClientMessage, { type: 'read-background-task-log' }>,\n): void {\n  if (!msg.taskId) {\n    send({ type: 'protocol_error', message: 'taskId is required' });\n    return;\n  }\n  session.readBackgroundTaskLog(msg.taskId, msg.cursor).then(\n    (page) => send({ type: 'background_task_log', taskId: msg.taskId, page }),\n    (error: Error) => send({ type: 'protocol_error', message: error.message }),\n  );\n}\n\nfunction sendBackgroundJobGroupSnapshot(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<TClientMessage, { type: 'get-background-job-group' }>,\n): void {\n  if (!msg.groupId) {\n    send({ type: 'protocol_error', message: 'groupId is required' });\n    return;\n  }\n  send({\n    type: 'background_job_group',\n    groupId: msg.groupId,\n    group: session.getBackgroundJobGroup(msg.groupId) ?? null,\n  });\n}\n\nfunction sendBackgroundJobGroupWaitResult(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<TClientMessage, { type: 'wait-background-job-group' }>,\n): void {\n  if (!msg.groupId) {\n    send({ type: 'protocol_error', message: 'groupId is required' });\n    return;\n  }\n  session.waitBackgroundJobGroup(msg.groupId).then(\n    (group) => send({ type: 'background_job_group', groupId: msg.groupId, group }),\n    (error: Error) => send({ type: 'protocol_error', message: error.message }),\n  );\n}\n\nfunction sendBackgroundTaskInput(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<TClientMessage, { type: 'send-background-task' }>,\n): void {\n  if (!msg.input) {\n    send({ type: 'protocol_error', message: 'input is required' });\n    return;\n  }\n  sendBackgroundTaskControlResult(\n    send,\n    'send',\n    msg.taskId,\n    session.sendBackgroundTask(msg.taskId, msg.input),\n  );\n}\n\nfunction sendBackgroundTaskControlResult(\n  send: (message: TServerMessage) => void,\n  action: TBackgroundControlAction,\n  taskId: string,\n  operation: Promise<void>,\n): void {\n  operation.then(\n    () => send({ type: 'background_task_control_result', action, taskId, success: true }),\n    (error: Error) =>\n      send({\n        type: 'background_task_control_result',\n        action,\n        taskId,\n        success: false,\n        message: error.message,\n      }),\n  );\n}\n","/**\n * WebSocket transport adapter — exposes IInteractiveSession over WebSocket.\n *\n * Framework-agnostic: works with any WebSocket implementation via\n * send/onMessage callbacks. No dependency on ws, uWebSockets, etc.\n *\n * Protocol: JSON messages with { type, ...payload } structure.\n * Server pushes IInteractiveSession events to client in real-time.\n */\n\nimport {\n  handleBackgroundControlMessage,\n  handleBackgroundQueryMessage,\n} from './ws-background-messages.js';\n\nimport type { TClientMessage, TServerMessage } from './ws-protocol.js';\nimport type { TBackgroundTaskEvent } from '@robota-sdk/agent-framework';\nimport type {\n  IExecutionResult,\n  IExecutionWorkspaceEvent,\n  IInteractiveSession,\n  IToolState,\n  TBackgroundJobGroupEvent,\n} from '@robota-sdk/agent-interface-transport';\n\nexport interface IWsHandlerOptions {\n  /** IInteractiveSession to expose. */\n  session: IInteractiveSession;\n  /** Send a JSON message to the client. */\n  send: (message: TServerMessage) => void;\n}\n\n/**\n * Create a WebSocket message handler for an IInteractiveSession.\n *\n * Returns:\n * - `onMessage(data)`: call this when the WebSocket receives a message\n * - `cleanup()`: call this when the WebSocket disconnects\n *\n * Usage:\n * ```typescript\n * const { onMessage, cleanup } = createWsHandler({\n *   session: interactiveSession,\n *   send: (msg) => ws.send(JSON.stringify(msg)),\n * });\n *\n * ws.on('message', (data) => onMessage(String(data)));\n * ws.on('close', cleanup);\n * ```\n */\nexport function createWsHandler(options: IWsHandlerOptions): {\n  onMessage: (data: string) => void;\n  cleanup: () => void;\n} {\n  const cleanup = subscribeSessionEvents(options.session, options.send);\n  const onMessage = createWsMessageHandler(options.session, options.send);\n\n  return { onMessage, cleanup };\n}\n\nfunction subscribeSessionEvents(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n): () => void {\n  const onUserMessage = (content: string): void => send({ type: 'user_message', content });\n  const onTextDelta = (delta: string): void => send({ type: 'text_delta', delta });\n  const onToolStart = (state: IToolState): void => send({ type: 'tool_start', state });\n  const onToolEnd = (state: IToolState): void => send({ type: 'tool_end', state });\n  const onThinking = (isThinking: boolean): void => send({ type: 'thinking', isThinking });\n  const onComplete = (result: IExecutionResult): void => send({ type: 'complete', result });\n  const onInterrupted = (result: IExecutionResult): void => send({ type: 'interrupted', result });\n  const onError = (error: Error): void => send({ type: 'error', message: error.message });\n  const onBackgroundTaskEvent = (event: TBackgroundTaskEvent): void =>\n    send({ type: 'background_task_event', event });\n  const onBackgroundJobGroupEvent = (event: TBackgroundJobGroupEvent): void =>\n    send({ type: 'background_job_group_event', event });\n  const onExecutionWorkspace = (event: IExecutionWorkspaceEvent): void =>\n    send({ type: 'execution_workspace_event', snapshot: event.snapshot });\n\n  session.on('user_message', onUserMessage);\n  session.on('text_delta', onTextDelta);\n  session.on('tool_start', onToolStart);\n  session.on('tool_end', onToolEnd);\n  session.on('thinking', onThinking);\n  session.on('complete', onComplete);\n  session.on('interrupted', onInterrupted);\n  session.on('error', onError);\n  session.on('background_task_event', onBackgroundTaskEvent);\n  session.on('background_job_group_event', onBackgroundJobGroupEvent);\n  session.on('execution_workspace_event', onExecutionWorkspace);\n\n  return (): void => {\n    session.off('user_message', onUserMessage);\n    session.off('text_delta', onTextDelta);\n    session.off('tool_start', onToolStart);\n    session.off('tool_end', onToolEnd);\n    session.off('thinking', onThinking);\n    session.off('complete', onComplete);\n    session.off('interrupted', onInterrupted);\n    session.off('error', onError);\n    session.off('background_task_event', onBackgroundTaskEvent);\n    session.off('background_job_group_event', onBackgroundJobGroupEvent);\n    session.off('execution_workspace_event', onExecutionWorkspace);\n  };\n}\n\nfunction createWsMessageHandler(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n): (data: string) => void {\n  return (data: string): void => {\n    const msg = parseClientMessage(data, send);\n    if (!msg) return;\n    handleClientMessage(session, send, msg);\n  };\n}\n\nfunction parseClientMessage(\n  data: string,\n  send: (message: TServerMessage) => void,\n): TClientMessage | null {\n  try {\n    return JSON.parse(data) as TClientMessage;\n  } catch {\n    send({ type: 'protocol_error', message: 'Invalid JSON' });\n    return null;\n  }\n}\n\nfunction handleClientMessage(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: TClientMessage,\n): void {\n  if (isSessionControlMessage(msg)) {\n    handleSessionControlMessage(session, send, msg);\n    return;\n  }\n  if (isSessionQueryMessage(msg)) {\n    handleSessionQueryMessage(session, send, msg);\n    return;\n  }\n  if (isBackgroundQueryMessage(msg)) {\n    handleBackgroundQueryMessage(session, send, msg);\n    return;\n  }\n  if (isBackgroundControlMessage(msg)) {\n    handleBackgroundControlMessage(session, send, msg);\n    return;\n  }\n  send({ type: 'protocol_error', message: `Unknown message type: ${getMessageType(msg)}` });\n}\n\nfunction getMessageType(msg: TClientMessage): string {\n  return (msg as { type: string }).type;\n}\n\nfunction isSessionControlMessage(\n  msg: TClientMessage,\n): msg is Extract<TClientMessage, { type: 'submit' | 'command' | 'abort' | 'cancel-queue' }> {\n  return (\n    msg.type === 'submit' ||\n    msg.type === 'command' ||\n    msg.type === 'abort' ||\n    msg.type === 'cancel-queue'\n  );\n}\n\nfunction isSessionQueryMessage(msg: TClientMessage): msg is Extract<\n  TClientMessage,\n  {\n    type:\n      | 'get-messages'\n      | 'get-context'\n      | 'get-executing'\n      | 'get-pending'\n      | 'get-execution-workspace';\n  }\n> {\n  return (\n    msg.type === 'get-messages' ||\n    msg.type === 'get-context' ||\n    msg.type === 'get-executing' ||\n    msg.type === 'get-pending' ||\n    msg.type === 'get-execution-workspace'\n  );\n}\n\nfunction isBackgroundQueryMessage(\n  msg: TClientMessage,\n): msg is Extract<\n  TClientMessage,\n  | { type: 'get-background-tasks' | 'get-background-task' | 'read-background-task-log' }\n  | { type: 'get-background-job-groups' | 'get-background-job-group' | 'wait-background-job-group' }\n> {\n  return (\n    msg.type === 'get-background-tasks' ||\n    msg.type === 'get-background-task' ||\n    msg.type === 'read-background-task-log' ||\n    msg.type === 'get-background-job-groups' ||\n    msg.type === 'get-background-job-group' ||\n    msg.type === 'wait-background-job-group'\n  );\n}\n\nfunction isBackgroundControlMessage(\n  msg: TClientMessage,\n): msg is Extract<\n  TClientMessage,\n  { type: 'cancel-background-task' | 'close-background-task' | 'send-background-task' }\n> {\n  return (\n    msg.type === 'cancel-background-task' ||\n    msg.type === 'close-background-task' ||\n    msg.type === 'send-background-task'\n  );\n}\n\nfunction handleSessionControlMessage(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<TClientMessage, { type: 'submit' | 'command' | 'abort' | 'cancel-queue' }>,\n): void {\n  if (msg.type === 'submit') {\n    if (!msg.prompt) {\n      send({ type: 'protocol_error', message: 'prompt is required' });\n      return;\n    }\n    session.submit(msg.prompt);\n  } else if (msg.type === 'command') {\n    if (!msg.name) {\n      send({ type: 'protocol_error', message: 'name is required' });\n      return;\n    }\n    session.executeCommand(msg.name, msg.args ?? '').then((result) => {\n      send({\n        type: 'command_result',\n        name: msg.name,\n        message: result?.message ?? `Unknown command: ${msg.name}`,\n        success: result?.success ?? false,\n        data: result?.data,\n      });\n    });\n  } else if (msg.type === 'abort') {\n    session.abort();\n  } else {\n    session.cancelQueue();\n  }\n}\n\nfunction handleSessionQueryMessage(\n  session: IInteractiveSession,\n  send: (message: TServerMessage) => void,\n  msg: Extract<\n    TClientMessage,\n    {\n      type:\n        | 'get-messages'\n        | 'get-context'\n        | 'get-executing'\n        | 'get-pending'\n        | 'get-execution-workspace';\n    }\n  >,\n): void {\n  if (msg.type === 'get-messages') {\n    send({ type: 'messages', messages: session.getMessages() });\n  } else if (msg.type === 'get-context') {\n    send({ type: 'context', state: session.getContextState() });\n  } else if (msg.type === 'get-executing') {\n    send({ type: 'executing', executing: session.isExecuting() });\n  } else if (msg.type === 'get-execution-workspace') {\n    send({\n      type: 'execution_workspace_event',\n      snapshot: session.getExecutionWorkspaceSnapshot(),\n    });\n  } else {\n    send({ type: 'pending', pending: session.getPendingPrompt() });\n  }\n}\n","/**\n * ITransportAdapter implementation for WebSocket transport.\n *\n * Wraps createWsHandler into the unified ITransportAdapter interface.\n * After start(), the consumer must wire onMessage to their WebSocket.\n */\n\nimport { createWsHandler } from './ws-handler.js';\n\nimport type { TServerMessage } from './ws-protocol.js';\nimport type { IInteractiveSession, ITransportAdapter } from '@robota-sdk/agent-interface-transport';\n\nexport interface IWsTransportOptions {\n  /** Send a JSON message to the connected WebSocket client. */\n  send: (message: TServerMessage) => void;\n}\n\nexport function createWsTransport(\n  options: IWsTransportOptions,\n): ITransportAdapter<IInteractiveSession> & { onMessage: ((data: string) => void) | null } {\n  let session: IInteractiveSession | null = null;\n  let cleanup: (() => void) | null = null;\n\n  return {\n    name: 'ws',\n    onMessage: null,\n    attach(s: IInteractiveSession) {\n      session = s;\n    },\n    async start() {\n      if (!session) throw new Error('No session attached. Call attach() first.');\n      const handler = createWsHandler({ session, send: options.send });\n      cleanup = handler.cleanup;\n      this.onMessage = handler.onMessage;\n    },\n    async stop() {\n      cleanup?.();\n      cleanup = null;\n      this.onMessage = null;\n    },\n  };\n}\n","/**\n * Self-contained WS transport implementing IConfigurableTransport.\n * Owns the WebSocket server lifecycle (ws package), started/stopped via the transport registry.\n */\n\nimport { createServer, type Server } from 'node:http';\n\nimport { WebSocketServer, WebSocket } from 'ws';\n\nimport { createWsHandler } from './ws-handler.js';\n\nimport type { TServerMessage } from './ws-protocol.js';\nimport type { TUniversalValue } from '@robota-sdk/agent-core';\nimport type {\n  IConfigurableTransport,\n  IInteractiveSession,\n} from '@robota-sdk/agent-interface-transport';\n\nconst DEFAULT_PORT = 7070;\nconst DEFAULT_MAX_RETRIES = 20;\n\nexport interface IWsTransportConfig {\n  port?: number;\n  maxRetries?: number;\n}\n\nexport class WsTransport implements IConfigurableTransport<IInteractiveSession> {\n  readonly name = 'ws';\n  readonly defaultEnabled = true;\n  readonly optionsSchema = {\n    port: { type: 'number', description: 'WebSocket server port', default: DEFAULT_PORT },\n    maxRetries: {\n      type: 'number',\n      description: 'Port retry attempts when port is occupied',\n      default: DEFAULT_MAX_RETRIES,\n    },\n  };\n\n  private session: IInteractiveSession | null = null;\n  private stopFn: (() => Promise<void>) | null = null;\n  private readonly port: number;\n  private readonly maxRetries: number;\n\n  constructor(config: IWsTransportConfig = {}) {\n    this.port = config.port ?? DEFAULT_PORT;\n    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;\n  }\n\n  attach(session: IInteractiveSession): void {\n    this.session = session;\n  }\n\n  async start(): Promise<void> {\n    if (!this.session) throw new Error('WsTransport: attach() must be called before start()');\n    const handle = await this.bindWithRetry(this.session, this.port, this.maxRetries);\n    this.stopFn = handle.stop;\n  }\n\n  async stop(): Promise<void> {\n    await this.stopFn?.();\n    this.stopFn = null;\n  }\n\n  validateOptions(options: Record<string, TUniversalValue>): boolean {\n    const { port, maxRetries } = options;\n    if (port !== undefined && (typeof port !== 'number' || port < 1 || port > 65535)) return false;\n    if (maxRetries !== undefined && (typeof maxRetries !== 'number' || maxRetries < 0))\n      return false;\n    return true;\n  }\n\n  private bindWithRetry(\n    session: IInteractiveSession,\n    port: number,\n    retriesLeft: number,\n  ): Promise<{ stop: () => Promise<void> }> {\n    return this.tryBind(session, port).catch((err: NodeJS.ErrnoException) => {\n      if (err.code === 'EADDRINUSE' && retriesLeft > 0)\n        return this.bindWithRetry(session, port + 1, retriesLeft - 1);\n      throw err;\n    });\n  }\n\n  private tryBind(\n    session: IInteractiveSession,\n    port: number,\n  ): Promise<{ stop: () => Promise<void> }> {\n    return new Promise((resolve, reject) => {\n      const httpServer: Server = createServer((_, res) => {\n        res.writeHead(400).end('WebSocket endpoint');\n      });\n\n      httpServer.on('error', (err: NodeJS.ErrnoException) => {\n        httpServer.close();\n        reject(err);\n      });\n\n      httpServer.listen(port, '127.0.0.1', () => {\n        const wss = new WebSocketServer({ server: httpServer });\n\n        wss.on('connection', (ws: WebSocket) => {\n          const send = (message: TServerMessage): void => {\n            if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(message));\n          };\n\n          const { onMessage, cleanup } = createWsHandler({ session, send });\n\n          ws.on('message', (data) => onMessage(String(data)));\n          ws.on('close', cleanup);\n          ws.on('error', cleanup);\n\n          send({ type: 'messages', messages: session.getMessages() });\n          send({\n            type: 'execution_workspace_event',\n            snapshot: session.getExecutionWorkspaceSnapshot(),\n          });\n        });\n\n        resolve({\n          stop: () =>\n            new Promise<void>((res) => {\n              wss.close(() => httpServer.close(() => res()));\n            }),\n        });\n      });\n    });\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@robota-sdk/agent-transport-ws",
-  "version": "3.0.0-beta.62",
-  "description": "WebSocket transport adapter for exposing InteractiveSession over real-time connections",
+  "version": "3.0.0-beta.76",
+  "description": "WebSocket transport and protocol for the Robota SDK",
   "type": "module",
   "main": "dist/node/index.js",
   "types": "dist/node/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/node/index.d.ts",
+      "source": "./src/index.ts",
       "node": {
         "import": "./dist/node/index.js",
         "require": "./dist/node/index.cjs"
@@ -26,30 +27,37 @@
   "bugs": {
     "url": "https://github.com/woojubb/robota/issues"
   },
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "dependencies": {
-    "@robota-sdk/agent-sdk": "3.0.0-beta.62"
+    "ws": "^8.21.0",
+    "@robota-sdk/agent-core": "3.0.0-beta.76",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.76",
+    "@robota-sdk/agent-framework": "3.0.0-beta.76"
   },
   "devDependencies": {
-    "rimraf": "^5.0.5",
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3",
-    "vitest": "^1.6.1"
+    "@types/ws": "^8.18.1",
+    "rimraf": "^5.0.10",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6"
   },
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --out-dir dist/node --clean",
-    "build:js": "tsup src/index.ts --format esm,cjs --out-dir dist/node --clean",
-    "build:types": "tsup src/index.ts --format esm,cjs --dts-only --out-dir dist/node",
+    "build": "tsdown",
+    "build:js": "tsdown --no-dts",
+    "build:types": "tsdown --dts",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
     "test:coverage": "vitest run --coverage --passWithNoTests",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/ --ext .ts",
     "clean": "rimraf dist"
   }
 }

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

@@ -0,0 +1,409 @@
+/**
+ * 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 {
+  IBackgroundJobGroupState,
+  IExecutionWorkspaceEvent,
+  IExecutionWorkspaceSnapshot,
+  IInteractiveSession,
+  TBackgroundJobGroupEvent,
+  TExecutionWorkspaceUpdateCause,
+} from '@robota-sdk/agent-interface-transport';
+import type {
+  IBackgroundTaskLogPage,
+  IBackgroundTaskState,
+  TBackgroundTaskEvent,
+} 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/__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-interface-transport';
+
+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/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';