@robota-sdk/agent-transport-ws 3.0.0-beta.43

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Robota Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @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 { InteractiveSession, SystemCommandExecutor } 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,
+    commandExecutor,
+    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 }` | `commandExecutor.execute()`  |
+| `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 |
+| `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   |
+
+## Dependencies
+
+- `@robota-sdk/agent-sdk` — `InteractiveSession`, `SystemCommandExecutor`
+- No WebSocket library dependency (framework-agnostic)

package/dist/node/index.cjs

@@ -0,0 +1,114 @@
+"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
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ws-handler.ts
+function createWsHandler(options) {
+  const { session, commandExecutor, send } = options;
+  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 });
+  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);
+  const onMessage = (data) => {
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      send({ type: "protocol_error", message: "Invalid JSON" });
+      return;
+    }
+    switch (msg.type) {
+      case "submit":
+        if (!msg.prompt) {
+          send({ type: "protocol_error", message: "prompt is required" });
+          return;
+        }
+        session.submit(msg.prompt);
+        break;
+      case "command":
+        if (!msg.name) {
+          send({ type: "protocol_error", message: "name is required" });
+          return;
+        }
+        commandExecutor.execute(msg.name, session, 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
+          });
+        });
+        break;
+      case "abort":
+        session.abort();
+        break;
+      case "cancel-queue":
+        session.cancelQueue();
+        break;
+      case "get-messages":
+        send({ type: "messages", messages: session.getMessages() });
+        break;
+      case "get-context":
+        send({ type: "context", state: session.getContextState() });
+        break;
+      case "get-executing":
+        send({ type: "executing", executing: session.isExecuting() });
+        break;
+      case "get-pending":
+        send({ type: "pending", pending: session.getPendingPrompt() });
+        break;
+      default:
+        send({
+          type: "protocol_error",
+          message: `Unknown message type: ${msg.type}`
+        });
+    }
+  };
+  const cleanup = () => {
+    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);
+  };
+  return { onMessage, cleanup };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createWsHandler
+});

package/dist/node/index.d.cts

@@ -0,0 +1,110 @@
+import { InteractiveSession, SystemCommandExecutor, IToolState, IExecutionResult } from '@robota-sdk/agent-sdk';
+
+/**
+ * WebSocket transport adapter — exposes InteractiveSession over WebSocket.
+ *
+ * Framework-agnostic: works with any WebSocket implementation via
+ * send/onMessage callbacks. No dependency on ws, uWebSockets, etc.
+ *
+ * Protocol: JSON messages with { type, ...payload } structure.
+ * Server pushes InteractiveSession events to client in real-time.
+ */
+
+/** Inbound message from client → server. */
+type TClientMessage = {
+    type: 'submit';
+    prompt: string;
+} | {
+    type: 'command';
+    name: string;
+    args?: string;
+} | {
+    type: 'abort';
+} | {
+    type: 'cancel-queue';
+} | {
+    type: 'get-messages';
+} | {
+    type: 'get-context';
+} | {
+    type: 'get-executing';
+} | {
+    type: 'get-pending';
+};
+/** Outbound message from server → client. */
+type TServerMessage = {
+    type: 'text_delta';
+    delta: string;
+} | {
+    type: 'tool_start';
+    state: IToolState;
+} | {
+    type: 'tool_end';
+    state: IToolState;
+} | {
+    type: 'thinking';
+    isThinking: boolean;
+} | {
+    type: 'complete';
+    result: IExecutionResult;
+} | {
+    type: 'interrupted';
+    result: IExecutionResult;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'command_result';
+    name: string;
+    message: string;
+    success: boolean;
+    data?: Record<string, unknown>;
+} | {
+    type: 'messages';
+    messages: unknown[];
+} | {
+    type: 'context';
+    state: unknown;
+} | {
+    type: 'executing';
+    executing: boolean;
+} | {
+    type: 'pending';
+    pending: string | null;
+} | {
+    type: 'protocol_error';
+    message: string;
+};
+interface IWsHandlerOptions {
+    /** InteractiveSession to expose. */
+    session: InteractiveSession;
+    /** System command executor. */
+    commandExecutor: SystemCommandExecutor;
+    /** Send a JSON message to the client. */
+    send: (message: TServerMessage) => void;
+}
+/**
+ * Create a WebSocket message handler for an InteractiveSession.
+ *
+ * Returns:
+ * - `onMessage(data)`: call this when the WebSocket receives a message
+ * - `cleanup()`: call this when the WebSocket disconnects
+ *
+ * Usage:
+ * ```typescript
+ * const { onMessage, cleanup } = createWsHandler({
+ *   session: interactiveSession,
+ *   commandExecutor,
+ *   send: (msg) => ws.send(JSON.stringify(msg)),
+ * });
+ *
+ * ws.on('message', (data) => onMessage(String(data)));
+ * ws.on('close', cleanup);
+ * ```
+ */
+declare function createWsHandler(options: IWsHandlerOptions): {
+    onMessage: (data: string) => void;
+    cleanup: () => void;
+};
+
+export { type IWsHandlerOptions, type TClientMessage, type TServerMessage, createWsHandler };

package/dist/node/index.d.ts

@@ -0,0 +1,110 @@
+import { InteractiveSession, SystemCommandExecutor, IToolState, IExecutionResult } from '@robota-sdk/agent-sdk';
+
+/**
+ * WebSocket transport adapter — exposes InteractiveSession over WebSocket.
+ *
+ * Framework-agnostic: works with any WebSocket implementation via
+ * send/onMessage callbacks. No dependency on ws, uWebSockets, etc.
+ *
+ * Protocol: JSON messages with { type, ...payload } structure.
+ * Server pushes InteractiveSession events to client in real-time.
+ */
+
+/** Inbound message from client → server. */
+type TClientMessage = {
+    type: 'submit';
+    prompt: string;
+} | {
+    type: 'command';
+    name: string;
+    args?: string;
+} | {
+    type: 'abort';
+} | {
+    type: 'cancel-queue';
+} | {
+    type: 'get-messages';
+} | {
+    type: 'get-context';
+} | {
+    type: 'get-executing';
+} | {
+    type: 'get-pending';
+};
+/** Outbound message from server → client. */
+type TServerMessage = {
+    type: 'text_delta';
+    delta: string;
+} | {
+    type: 'tool_start';
+    state: IToolState;
+} | {
+    type: 'tool_end';
+    state: IToolState;
+} | {
+    type: 'thinking';
+    isThinking: boolean;
+} | {
+    type: 'complete';
+    result: IExecutionResult;
+} | {
+    type: 'interrupted';
+    result: IExecutionResult;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'command_result';
+    name: string;
+    message: string;
+    success: boolean;
+    data?: Record<string, unknown>;
+} | {
+    type: 'messages';
+    messages: unknown[];
+} | {
+    type: 'context';
+    state: unknown;
+} | {
+    type: 'executing';
+    executing: boolean;
+} | {
+    type: 'pending';
+    pending: string | null;
+} | {
+    type: 'protocol_error';
+    message: string;
+};
+interface IWsHandlerOptions {
+    /** InteractiveSession to expose. */
+    session: InteractiveSession;
+    /** System command executor. */
+    commandExecutor: SystemCommandExecutor;
+    /** Send a JSON message to the client. */
+    send: (message: TServerMessage) => void;
+}
+/**
+ * Create a WebSocket message handler for an InteractiveSession.
+ *
+ * Returns:
+ * - `onMessage(data)`: call this when the WebSocket receives a message
+ * - `cleanup()`: call this when the WebSocket disconnects
+ *
+ * Usage:
+ * ```typescript
+ * const { onMessage, cleanup } = createWsHandler({
+ *   session: interactiveSession,
+ *   commandExecutor,
+ *   send: (msg) => ws.send(JSON.stringify(msg)),
+ * });
+ *
+ * ws.on('message', (data) => onMessage(String(data)));
+ * ws.on('close', cleanup);
+ * ```
+ */
+declare function createWsHandler(options: IWsHandlerOptions): {
+    onMessage: (data: string) => void;
+    cleanup: () => void;
+};
+
+export { type IWsHandlerOptions, type TClientMessage, type TServerMessage, createWsHandler };

package/dist/node/index.js

@@ -0,0 +1,87 @@
+// src/ws-handler.ts
+function createWsHandler(options) {
+  const { session, commandExecutor, send } = options;
+  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 });
+  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);
+  const onMessage = (data) => {
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      send({ type: "protocol_error", message: "Invalid JSON" });
+      return;
+    }
+    switch (msg.type) {
+      case "submit":
+        if (!msg.prompt) {
+          send({ type: "protocol_error", message: "prompt is required" });
+          return;
+        }
+        session.submit(msg.prompt);
+        break;
+      case "command":
+        if (!msg.name) {
+          send({ type: "protocol_error", message: "name is required" });
+          return;
+        }
+        commandExecutor.execute(msg.name, session, 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
+          });
+        });
+        break;
+      case "abort":
+        session.abort();
+        break;
+      case "cancel-queue":
+        session.cancelQueue();
+        break;
+      case "get-messages":
+        send({ type: "messages", messages: session.getMessages() });
+        break;
+      case "get-context":
+        send({ type: "context", state: session.getContextState() });
+        break;
+      case "get-executing":
+        send({ type: "executing", executing: session.isExecuting() });
+        break;
+      case "get-pending":
+        send({ type: "pending", pending: session.getPendingPrompt() });
+        break;
+      default:
+        send({
+          type: "protocol_error",
+          message: `Unknown message type: ${msg.type}`
+        });
+    }
+  };
+  const cleanup = () => {
+    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);
+  };
+  return { onMessage, cleanup };
+}
+export {
+  createWsHandler
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@robota-sdk/agent-transport-ws",
+  "version": "3.0.0-beta.43",
+  "description": "WebSocket transport adapter for exposing InteractiveSession over real-time connections",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "node": {
+        "import": "./dist/node/index.js",
+        "require": "./dist/node/index.cjs"
+      },
+      "default": {
+        "import": "./dist/node/index.js",
+        "require": "./dist/node/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@robota-sdk/agent-sdk": "3.0.0-beta.43"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.6.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --out-dir dist/node --clean",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ --ext .ts",
+    "clean": "rimraf dist"
+  }
+}