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

package/README.md

@@ -1,94 +1,11 @@
 # @robota-sdk/agent-transport-ws
 
-Framework-agnostic WebSocket transport adapter for exposing `InteractiveSession` over real-time bidirectional connections. Works with any WebSocket implementation (Node.js `ws`, browser `WebSocket`, uWebSockets, etc.) via send/onMessage callbacks — no WebSocket library dependency.
-
-## Installation
-
-```bash
-pnpm add @robota-sdk/agent-transport-ws
-```
-
-## Usage
-
-```typescript
-import { createWsHandler } from '@robota-sdk/agent-transport-ws';
-import type { InteractiveSession } from '@robota-sdk/agent-sdk';
-import { WebSocketServer } from 'ws';
-
-const wss = new WebSocketServer({ port: 8080 });
-
-wss.on('connection', (ws) => {
-  const { onMessage, cleanup } = createWsHandler({
-    session: interactiveSession,
-    send: (msg) => ws.send(JSON.stringify(msg)),
-  });
-
-  ws.on('message', (data) => onMessage(String(data)));
-  ws.on('close', cleanup);
-});
-```
-
-## Message Protocol
-
-All messages are JSON-encoded objects with a `type` field.
-
-### Client to Server
-
-| type            | payload                           | maps to                      |
-| --------------- | --------------------------------- | ---------------------------- |
-| `submit`        | `{ prompt: string }`              | `session.submit(prompt)`     |
-| `command`       | `{ name: string, args?: string }` | `session.executeCommand()`   |
-| `abort`         | —                                 | `session.abort()`            |
-| `cancel-queue`  | —                                 | `session.cancelQueue()`      |
-| `get-messages`  | —                                 | `session.getMessages()`      |
-| `get-context`   | —                                 | `session.getContextState()`  |
-| `get-executing` | —                                 | `session.isExecuting()`      |
-| `get-pending`   | —                                 | `session.getPendingPrompt()` |
-
-### Server to Client (pushed events)
-
-| type                    | payload                             | source                                   |
-| ----------------------- | ----------------------------------- | ---------------------------------------- |
-| `text_delta`            | `{ delta: string }`                 | InteractiveSession event                 |
-| `tool_start`            | `{ state: IToolState }`             | InteractiveSession event                 |
-| `tool_end`              | `{ state: IToolState }`             | InteractiveSession event                 |
-| `background_task_event` | `{ event: TBackgroundTaskEvent }`   | InteractiveSession background task event |
-| `thinking`              | `{ isThinking: boolean }`           | InteractiveSession event                 |
-| `complete`              | `{ result: IExecutionResult }`      | InteractiveSession event                 |
-| `interrupted`           | `{ result: IExecutionResult }`      | InteractiveSession event                 |
-| `error`                 | `{ message: string }`               | InteractiveSession event                 |
-| `command_result`        | `{ name, message, success, data? }` | command response                         |
-| `messages`              | `{ messages: TUniversalMessage[] }` | get-messages response                    |
-| `context`               | `{ state: IContextWindowState }`    | get-context response                     |
-| `executing`             | `{ executing: boolean }`            | get-executing response                   |
-| `pending`               | `{ pending: string\|null }`         | get-pending response                     |
-| `protocol_error`        | `{ message: string }`               | invalid client message                   |
-
-## ITransportAdapter
-
-The WebSocket transport implements the `ITransportAdapter` interface from `@robota-sdk/agent-sdk`:
+WebSocket transport and wire protocol for the Robota SDK. Consumers that only need the WS message
+types (e.g. browser monitors) depend on this package without pulling React/Ink/Hono.
 
 ```typescript
-import { createWsTransport } from '@robota-sdk/agent-transport-ws';
-import type { ITransportAdapter } from '@robota-sdk/agent-sdk';
-
-const transport: ITransportAdapter = createWsTransport({
-  send: (msg) => ws.send(JSON.stringify(msg)),
-});
-
-transport.attach(interactiveSession);
-await transport.start();
-
-// Wire incoming messages
-ws.on('message', (data) => transport.onMessage(String(data)));
-ws.on('close', () => transport.stop());
+import { WsTransport, createWsHandler } from '@robota-sdk/agent-transport-ws';
+import type { TServerMessage, TClientMessage } from '@robota-sdk/agent-transport-ws';
 ```
 
-## Dependencies
-
-- `@robota-sdk/agent-sdk` — `InteractiveSession`
-- No WebSocket library dependency (framework-agnostic)
-
-## Background Work
-
-When the attached `InteractiveSession` emits background task updates, the WebSocket transport forwards them as protocol messages so clients can render subagent jobs, transcript references, and terminal states without polling session JSON.
+See [docs/SPEC.md](./docs/SPEC.md) for the full contract.

package/dist/node/index.cjs

@@ -1,299 +1 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  createWsHandler: () => createWsHandler,
-  createWsTransport: () => createWsTransport
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/ws-background-messages.ts
-function handleBackgroundQueryMessage(session, send, msg) {
-  if (msg.type === "get-background-tasks") {
-    send({ type: "background_tasks", tasks: session.listBackgroundTasks(msg.filter) });
-    return;
-  }
-  if (msg.type === "get-background-task") {
-    sendBackgroundTaskSnapshot(session, send, msg);
-    return;
-  }
-  if (msg.type === "get-background-job-groups") {
-    send({ type: "background_job_groups", groups: session.listBackgroundJobGroups() });
-    return;
-  }
-  if (msg.type === "get-background-job-group") {
-    sendBackgroundJobGroupSnapshot(session, send, msg);
-    return;
-  }
-  if (msg.type === "wait-background-job-group") {
-    sendBackgroundJobGroupWaitResult(session, send, msg);
-    return;
-  }
-  sendBackgroundTaskLogPage(session, send, msg);
-}
-function handleBackgroundControlMessage(session, send, msg) {
-  if (!msg.taskId) {
-    send({ type: "protocol_error", message: "taskId is required" });
-    return;
-  }
-  if (msg.type === "cancel-background-task") {
-    sendBackgroundTaskControlResult(
-      send,
-      "cancel",
-      msg.taskId,
-      session.cancelBackgroundTask(msg.taskId, msg.reason)
-    );
-    return;
-  }
-  if (msg.type === "close-background-task") {
-    sendBackgroundTaskControlResult(
-      send,
-      "close",
-      msg.taskId,
-      session.closeBackgroundTask(msg.taskId)
-    );
-    return;
-  }
-  sendBackgroundTaskInput(session, send, msg);
-}
-function sendBackgroundTaskSnapshot(session, send, msg) {
-  if (!msg.taskId) {
-    send({ type: "protocol_error", message: "taskId is required" });
-    return;
-  }
-  send({
-    type: "background_task",
-    taskId: msg.taskId,
-    task: session.getBackgroundTask(msg.taskId) ?? null
-  });
-}
-function sendBackgroundTaskLogPage(session, send, msg) {
-  if (!msg.taskId) {
-    send({ type: "protocol_error", message: "taskId is required" });
-    return;
-  }
-  session.readBackgroundTaskLog(msg.taskId, msg.cursor).then(
-    (page) => send({ type: "background_task_log", taskId: msg.taskId, page }),
-    (error) => send({ type: "protocol_error", message: error.message })
-  );
-}
-function sendBackgroundJobGroupSnapshot(session, send, msg) {
-  if (!msg.groupId) {
-    send({ type: "protocol_error", message: "groupId is required" });
-    return;
-  }
-  send({
-    type: "background_job_group",
-    groupId: msg.groupId,
-    group: session.getBackgroundJobGroup(msg.groupId) ?? null
-  });
-}
-function sendBackgroundJobGroupWaitResult(session, send, msg) {
-  if (!msg.groupId) {
-    send({ type: "protocol_error", message: "groupId is required" });
-    return;
-  }
-  session.waitBackgroundJobGroup(msg.groupId).then(
-    (group) => send({ type: "background_job_group", groupId: msg.groupId, group }),
-    (error) => send({ type: "protocol_error", message: error.message })
-  );
-}
-function sendBackgroundTaskInput(session, send, msg) {
-  if (!msg.input) {
-    send({ type: "protocol_error", message: "input is required" });
-    return;
-  }
-  sendBackgroundTaskControlResult(
-    send,
-    "send",
-    msg.taskId,
-    session.sendBackgroundTask(msg.taskId, msg.input)
-  );
-}
-function sendBackgroundTaskControlResult(send, action, taskId, operation) {
-  operation.then(
-    () => send({ type: "background_task_control_result", action, taskId, success: true }),
-    (error) => send({
-      type: "background_task_control_result",
-      action,
-      taskId,
-      success: false,
-      message: error.message
-    })
-  );
-}
-
-// src/ws-handler.ts
-function createWsHandler(options) {
-  const cleanup = subscribeSessionEvents(options.session, options.send);
-  const onMessage = createWsMessageHandler(options.session, options.send);
-  return { onMessage, cleanup };
-}
-function subscribeSessionEvents(session, send) {
-  const onUserMessage = (content) => send({ type: "user_message", content });
-  const onTextDelta = (delta) => send({ type: "text_delta", delta });
-  const onToolStart = (state) => send({ type: "tool_start", state });
-  const onToolEnd = (state) => send({ type: "tool_end", state });
-  const onThinking = (isThinking) => send({ type: "thinking", isThinking });
-  const onComplete = (result) => send({ type: "complete", result });
-  const onInterrupted = (result) => send({ type: "interrupted", result });
-  const onError = (error) => send({ type: "error", message: error.message });
-  const onBackgroundTaskEvent = (event) => send({ type: "background_task_event", event });
-  const onBackgroundJobGroupEvent = (event) => send({ type: "background_job_group_event", event });
-  session.on("user_message", onUserMessage);
-  session.on("text_delta", onTextDelta);
-  session.on("tool_start", onToolStart);
-  session.on("tool_end", onToolEnd);
-  session.on("thinking", onThinking);
-  session.on("complete", onComplete);
-  session.on("interrupted", onInterrupted);
-  session.on("error", onError);
-  session.on("background_task_event", onBackgroundTaskEvent);
-  session.on("background_job_group_event", onBackgroundJobGroupEvent);
-  return () => {
-    session.off("user_message", onUserMessage);
-    session.off("text_delta", onTextDelta);
-    session.off("tool_start", onToolStart);
-    session.off("tool_end", onToolEnd);
-    session.off("thinking", onThinking);
-    session.off("complete", onComplete);
-    session.off("interrupted", onInterrupted);
-    session.off("error", onError);
-    session.off("background_task_event", onBackgroundTaskEvent);
-    session.off("background_job_group_event", onBackgroundJobGroupEvent);
-  };
-}
-function createWsMessageHandler(session, send) {
-  return (data) => {
-    const msg = parseClientMessage(data, send);
-    if (!msg) return;
-    handleClientMessage(session, send, msg);
-  };
-}
-function parseClientMessage(data, send) {
-  try {
-    return JSON.parse(data);
-  } catch {
-    send({ type: "protocol_error", message: "Invalid JSON" });
-    return null;
-  }
-}
-function handleClientMessage(session, send, msg) {
-  if (isSessionControlMessage(msg)) {
-    handleSessionControlMessage(session, send, msg);
-    return;
-  }
-  if (isSessionQueryMessage(msg)) {
-    handleSessionQueryMessage(session, send, msg);
-    return;
-  }
-  if (isBackgroundQueryMessage(msg)) {
-    handleBackgroundQueryMessage(session, send, msg);
-    return;
-  }
-  if (isBackgroundControlMessage(msg)) {
-    handleBackgroundControlMessage(session, send, msg);
-    return;
-  }
-  send({ type: "protocol_error", message: `Unknown message type: ${getMessageType(msg)}` });
-}
-function getMessageType(msg) {
-  return msg.type;
-}
-function isSessionControlMessage(msg) {
-  return msg.type === "submit" || msg.type === "command" || msg.type === "abort" || msg.type === "cancel-queue";
-}
-function isSessionQueryMessage(msg) {
-  return msg.type === "get-messages" || msg.type === "get-context" || msg.type === "get-executing" || msg.type === "get-pending";
-}
-function isBackgroundQueryMessage(msg) {
-  return msg.type === "get-background-tasks" || msg.type === "get-background-task" || msg.type === "read-background-task-log" || msg.type === "get-background-job-groups" || msg.type === "get-background-job-group" || msg.type === "wait-background-job-group";
-}
-function isBackgroundControlMessage(msg) {
-  return msg.type === "cancel-background-task" || msg.type === "close-background-task" || msg.type === "send-background-task";
-}
-function handleSessionControlMessage(session, send, msg) {
-  if (msg.type === "submit") {
-    if (!msg.prompt) {
-      send({ type: "protocol_error", message: "prompt is required" });
-      return;
-    }
-    session.submit(msg.prompt);
-  } else if (msg.type === "command") {
-    if (!msg.name) {
-      send({ type: "protocol_error", message: "name is required" });
-      return;
-    }
-    session.executeCommand(msg.name, msg.args ?? "").then((result) => {
-      send({
-        type: "command_result",
-        name: msg.name,
-        message: result?.message ?? `Unknown command: ${msg.name}`,
-        success: result?.success ?? false,
-        data: result?.data
-      });
-    });
-  } else if (msg.type === "abort") {
-    session.abort();
-  } else {
-    session.cancelQueue();
-  }
-}
-function handleSessionQueryMessage(session, send, msg) {
-  if (msg.type === "get-messages") {
-    send({ type: "messages", messages: session.getMessages() });
-  } else if (msg.type === "get-context") {
-    send({ type: "context", state: session.getContextState() });
-  } else if (msg.type === "get-executing") {
-    send({ type: "executing", executing: session.isExecuting() });
-  } else {
-    send({ type: "pending", pending: session.getPendingPrompt() });
-  }
-}
-
-// src/ws-transport.ts
-function createWsTransport(options) {
-  let session = null;
-  let cleanup = null;
-  return {
-    name: "ws",
-    onMessage: null,
-    attach(s) {
-      session = s;
-    },
-    async start() {
-      if (!session) throw new Error("No session attached. Call attach() first.");
-      const handler = createWsHandler({ session, send: options.send });
-      cleanup = handler.cleanup;
-      this.onMessage = handler.onMessage;
-    },
-    async stop() {
-      cleanup?.();
-      cleanup = null;
-      this.onMessage = null;
-    }
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createWsHandler,
-  createWsTransport
-});
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("node:http"),t=require("ws");function n(e,t,n){if(n.type===`get-background-tasks`){t({type:`background_tasks`,tasks:e.listBackgroundTasks(n.filter)});return}if(n.type===`get-background-task`){i(e,t,n);return}if(n.type===`get-background-job-groups`){t({type:`background_job_groups`,groups:e.listBackgroundJobGroups()});return}if(n.type===`get-background-job-group`){o(e,t,n);return}if(n.type===`wait-background-job-group`){s(e,t,n);return}a(e,t,n)}function r(e,t,n){if(!n.taskId){t({type:`protocol_error`,message:`taskId is required`});return}if(n.type===`cancel-background-task`){l(t,`cancel`,n.taskId,e.cancelBackgroundTask(n.taskId,n.reason));return}if(n.type===`close-background-task`){l(t,`close`,n.taskId,e.closeBackgroundTask(n.taskId));return}c(e,t,n)}function i(e,t,n){if(!n.taskId){t({type:`protocol_error`,message:`taskId is required`});return}t({type:`background_task`,taskId:n.taskId,task:e.getBackgroundTask(n.taskId)??null})}function a(e,t,n){if(!n.taskId){t({type:`protocol_error`,message:`taskId is required`});return}e.readBackgroundTaskLog(n.taskId,n.cursor).then(e=>t({type:`background_task_log`,taskId:n.taskId,page:e}),e=>t({type:`protocol_error`,message:e.message}))}function o(e,t,n){if(!n.groupId){t({type:`protocol_error`,message:`groupId is required`});return}t({type:`background_job_group`,groupId:n.groupId,group:e.getBackgroundJobGroup(n.groupId)??null})}function s(e,t,n){if(!n.groupId){t({type:`protocol_error`,message:`groupId is required`});return}e.waitBackgroundJobGroup(n.groupId).then(e=>t({type:`background_job_group`,groupId:n.groupId,group:e}),e=>t({type:`protocol_error`,message:e.message}))}function c(e,t,n){if(!n.input){t({type:`protocol_error`,message:`input is required`});return}l(t,`send`,n.taskId,e.sendBackgroundTask(n.taskId,n.input))}function l(e,t,n,r){r.then(()=>e({type:`background_task_control_result`,action:t,taskId:n,success:!0}),r=>e({type:`background_task_control_result`,action:t,taskId:n,success:!1,message:r.message}))}function u(e){let t=d(e.session,e.send);return{onMessage:f(e.session,e.send),cleanup:t}}function d(e,t){let n=e=>t({type:`user_message`,content:e}),r=e=>t({type:`text_delta`,delta:e}),i=e=>t({type:`tool_start`,state:e}),a=e=>t({type:`tool_end`,state:e}),o=e=>t({type:`thinking`,isThinking:e}),s=e=>t({type:`complete`,result:e}),c=e=>t({type:`interrupted`,result:e}),l=e=>t({type:`error`,message:e.message}),u=e=>t({type:`background_task_event`,event:e}),d=e=>t({type:`background_job_group_event`,event:e}),f=e=>t({type:`execution_workspace_event`,snapshot:e.snapshot});return e.on(`user_message`,n),e.on(`text_delta`,r),e.on(`tool_start`,i),e.on(`tool_end`,a),e.on(`thinking`,o),e.on(`complete`,s),e.on(`interrupted`,c),e.on(`error`,l),e.on(`background_task_event`,u),e.on(`background_job_group_event`,d),e.on(`execution_workspace_event`,f),()=>{e.off(`user_message`,n),e.off(`text_delta`,r),e.off(`tool_start`,i),e.off(`tool_end`,a),e.off(`thinking`,o),e.off(`complete`,s),e.off(`interrupted`,c),e.off(`error`,l),e.off(`background_task_event`,u),e.off(`background_job_group_event`,d),e.off(`execution_workspace_event`,f)}}function f(e,t){return n=>{let r=p(n,t);r&&m(e,t,r)}}function p(e,t){try{return JSON.parse(e)}catch{return t({type:`protocol_error`,message:`Invalid JSON`}),null}}function m(e,t,i){if(g(i)){b(e,t,i);return}if(_(i)){x(e,t,i);return}if(v(i)){n(e,t,i);return}if(y(i)){r(e,t,i);return}t({type:`protocol_error`,message:`Unknown message type: ${h(i)}`})}function h(e){return e.type}function g(e){return e.type===`submit`||e.type===`command`||e.type===`abort`||e.type===`cancel-queue`}function _(e){return e.type===`get-messages`||e.type===`get-context`||e.type===`get-executing`||e.type===`get-pending`||e.type===`get-execution-workspace`}function v(e){return e.type===`get-background-tasks`||e.type===`get-background-task`||e.type===`read-background-task-log`||e.type===`get-background-job-groups`||e.type===`get-background-job-group`||e.type===`wait-background-job-group`}function y(e){return e.type===`cancel-background-task`||e.type===`close-background-task`||e.type===`send-background-task`}function b(e,t,n){if(n.type===`submit`){if(!n.prompt){t({type:`protocol_error`,message:`prompt is required`});return}e.submit(n.prompt)}else if(n.type===`command`){if(!n.name){t({type:`protocol_error`,message:`name is required`});return}e.executeCommand(n.name,n.args??``).then(e=>{t({type:`command_result`,name:n.name,message:e?.message??`Unknown command: ${n.name}`,success:e?.success??!1,data:e?.data})})}else n.type===`abort`?e.abort():e.cancelQueue()}function x(e,t,n){n.type===`get-messages`?t({type:`messages`,messages:e.getMessages()}):n.type===`get-context`?t({type:`context`,state:e.getContextState()}):n.type===`get-executing`?t({type:`executing`,executing:e.isExecuting()}):n.type===`get-execution-workspace`?t({type:`execution_workspace_event`,snapshot:e.getExecutionWorkspaceSnapshot()}):t({type:`pending`,pending:e.getPendingPrompt()})}function S(e){let t=null,n=null;return{name:`ws`,onMessage:null,attach(e){t=e},async start(){if(!t)throw Error(`No session attached. Call attach() first.`);let r=u({session:t,send:e.send});n=r.cleanup,this.onMessage=r.onMessage},async stop(){n?.(),n=null,this.onMessage=null}}}const C=7070;var w=class{name=`ws`;defaultEnabled=!0;optionsSchema={port:{type:`number`,description:`WebSocket server port`,default:C},maxRetries:{type:`number`,description:`Port retry attempts when port is occupied`,default:20}};session=null;stopFn=null;port;maxRetries;constructor(e={}){this.port=e.port??C,this.maxRetries=e.maxRetries??20}attach(e){this.session=e}async start(){if(!this.session)throw Error(`WsTransport: attach() must be called before start()`);let e=await this.bindWithRetry(this.session,this.port,this.maxRetries);this.stopFn=e.stop}async stop(){await this.stopFn?.(),this.stopFn=null}validateOptions(e){let{port:t,maxRetries:n}=e;return!(t!==void 0&&(typeof t!=`number`||t<1||t>65535)||n!==void 0&&(typeof n!=`number`||n<0))}bindWithRetry(e,t,n){return this.tryBind(e,t).catch(r=>{if(r.code===`EADDRINUSE`&&n>0)return this.bindWithRetry(e,t+1,n-1);throw r})}tryBind(n,r){return new Promise((i,a)=>{let o=(0,e.createServer)((e,t)=>{t.writeHead(400).end(`WebSocket endpoint`)});o.on(`error`,e=>{o.close(),a(e)}),o.listen(r,`127.0.0.1`,()=>{let e=new t.WebSocketServer({server:o});e.on(`connection`,e=>{let r=n=>{e.readyState===t.WebSocket.OPEN&&e.send(JSON.stringify(n))},{onMessage:i,cleanup:a}=u({session:n,send:r});e.on(`message`,e=>i(String(e))),e.on(`close`,a),e.on(`error`,a),r({type:`messages`,messages:n.getMessages()}),r({type:`execution_workspace_event`,snapshot:n.getExecutionWorkspaceSnapshot()})}),i({stop:()=>new Promise(t=>{e.close(()=>o.close(()=>t()))})})})})}};exports.WsTransport=w,exports.createWsHandler=u,exports.createWsTransport=S;