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

package/dist/node/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  WsTransport: () => WsTransport,
   createWsHandler: () => createWsHandler,
   createWsTransport: () => createWsTransport
 });
@@ -158,6 +159,7 @@ function subscribeSessionEvents(session, send) {
   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 });
+  const onExecutionWorkspace = (event) => send({ type: "execution_workspace_event", snapshot: event.snapshot });
   session.on("user_message", onUserMessage);
   session.on("text_delta", onTextDelta);
   session.on("tool_start", onToolStart);
@@ -168,6 +170,7 @@ function subscribeSessionEvents(session, send) {
   session.on("error", onError);
   session.on("background_task_event", onBackgroundTaskEvent);
   session.on("background_job_group_event", onBackgroundJobGroupEvent);
+  session.on("execution_workspace_event", onExecutionWorkspace);
   return () => {
     session.off("user_message", onUserMessage);
     session.off("text_delta", onTextDelta);
@@ -179,6 +182,7 @@ function subscribeSessionEvents(session, send) {
     session.off("error", onError);
     session.off("background_task_event", onBackgroundTaskEvent);
     session.off("background_job_group_event", onBackgroundJobGroupEvent);
+    session.off("execution_workspace_event", onExecutionWorkspace);
   };
 }
 function createWsMessageHandler(session, send) {
@@ -222,7 +226,7 @@ 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";
+  return msg.type === "get-messages" || msg.type === "get-context" || msg.type === "get-executing" || msg.type === "get-pending" || msg.type === "get-execution-workspace";
 }
 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";
@@ -264,6 +268,11 @@ function handleSessionQueryMessage(session, send, msg) {
     send({ type: "context", state: session.getContextState() });
   } else if (msg.type === "get-executing") {
     send({ type: "executing", executing: session.isExecuting() });
+  } else if (msg.type === "get-execution-workspace") {
+    send({
+      type: "execution_workspace_event",
+      snapshot: session.getExecutionWorkspaceSnapshot()
+    });
   } else {
     send({ type: "pending", pending: session.getPendingPrompt() });
   }
@@ -292,8 +301,94 @@ function createWsTransport(options) {
     }
   };
 }
+
+// src/ws-transport-configurable.ts
+var import_node_http = require("http");
+var import_ws = require("ws");
+var DEFAULT_PORT = 7070;
+var DEFAULT_MAX_RETRIES = 20;
+var WsTransport = class {
+  name = "ws";
+  defaultEnabled = true;
+  optionsSchema = {
+    port: { type: "number", description: "WebSocket server port", default: DEFAULT_PORT },
+    maxRetries: {
+      type: "number",
+      description: "Port retry attempts when port is occupied",
+      default: DEFAULT_MAX_RETRIES
+    }
+  };
+  session = null;
+  stopFn = null;
+  port;
+  maxRetries;
+  constructor(config = {}) {
+    this.port = config.port ?? DEFAULT_PORT;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+  }
+  attach(session) {
+    this.session = session;
+  }
+  async start() {
+    if (!this.session) throw new Error("WsTransport: attach() must be called before start()");
+    const handle = await this.bindWithRetry(this.session, this.port, this.maxRetries);
+    this.stopFn = handle.stop;
+  }
+  async stop() {
+    await this.stopFn?.();
+    this.stopFn = null;
+  }
+  validateOptions(options) {
+    const { port, maxRetries } = options;
+    if (port !== void 0 && (typeof port !== "number" || port < 1 || port > 65535)) return false;
+    if (maxRetries !== void 0 && (typeof maxRetries !== "number" || maxRetries < 0))
+      return false;
+    return true;
+  }
+  bindWithRetry(session, port, retriesLeft) {
+    return this.tryBind(session, port).catch((err) => {
+      if (err.code === "EADDRINUSE" && retriesLeft > 0)
+        return this.bindWithRetry(session, port + 1, retriesLeft - 1);
+      throw err;
+    });
+  }
+  tryBind(session, port) {
+    return new Promise((resolve, reject) => {
+      const httpServer = (0, import_node_http.createServer)((_, res) => {
+        res.writeHead(400).end("WebSocket endpoint");
+      });
+      httpServer.on("error", (err) => {
+        httpServer.close();
+        reject(err);
+      });
+      httpServer.listen(port, "127.0.0.1", () => {
+        const wss = new import_ws.WebSocketServer({ server: httpServer });
+        wss.on("connection", (ws) => {
+          const send = (message) => {
+            if (ws.readyState === import_ws.WebSocket.OPEN) ws.send(JSON.stringify(message));
+          };
+          const { onMessage, cleanup } = createWsHandler({ session, send });
+          ws.on("message", (data) => onMessage(String(data)));
+          ws.on("close", cleanup);
+          ws.on("error", cleanup);
+          send({ type: "messages", messages: session.getMessages() });
+          send({
+            type: "execution_workspace_event",
+            snapshot: session.getExecutionWorkspaceSnapshot()
+          });
+        });
+        resolve({
+          stop: () => new Promise((res) => {
+            wss.close(() => httpServer.close(() => res()));
+          })
+        });
+      });
+    });
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  WsTransport,
   createWsHandler,
   createWsTransport
 });

package/dist/node/index.d.cts

@@ -1,4 +1,7 @@
-import { IToolState, IExecutionResult, ICommandResult, InteractiveSession, TBackgroundTaskEvent, TBackgroundJobGroupEvent, IBackgroundTaskState, IBackgroundJobGroupState, IBackgroundTaskLogPage, IBackgroundTaskListFilter, IBackgroundTaskInput, IBackgroundTaskLogCursor, ITransportAdapter } from '@robota-sdk/agent-sdk';
+import { IToolState, IExecutionResult, ICommandResult, InteractiveSession, IExecutionWorkspaceSnapshot, TBackgroundTaskEvent, TBackgroundJobGroupEvent, IBackgroundTaskState, IBackgroundJobGroupState, IBackgroundTaskLogPage, IBackgroundTaskListFilter, IBackgroundTaskInput, IBackgroundTaskLogCursor } from '@robota-sdk/agent-sdk';
+export { IExecutionWorkspaceEntry, IExecutionWorkspaceSnapshot, TExecutionAttention, TExecutionWorkspaceStatus } from '@robota-sdk/agent-sdk';
+import { ITransportAdapter, IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+import { ISession, TUniversalValue } from '@robota-sdk/agent-core';
 
 type TBackgroundControlAction = 'cancel' | 'close' | 'send';
 /** Inbound message from client to server. */
@@ -21,6 +24,8 @@ type TClientMessage = {
     type: 'get-executing';
 } | {
     type: 'get-pending';
+} | {
+    type: 'get-execution-workspace';
 } | {
     type: 'get-background-tasks';
     filter?: IBackgroundTaskListFilter;
@@ -94,6 +99,9 @@ type TServerMessage = {
 } | {
     type: 'pending';
     pending: string | null;
+} | {
+    type: 'execution_workspace_event';
+    snapshot: IExecutionWorkspaceSnapshot;
 } | {
     type: 'background_task_event';
     event: TBackgroundTaskEvent;
@@ -183,4 +191,41 @@ declare function createWsTransport(options: IWsTransportOptions): ITransportAdap
     onMessage: ((data: string) => void) | null;
 };
 
-export { type IWsHandlerOptions, type IWsTransportOptions, type TClientMessage, type TServerMessage, createWsHandler, createWsTransport };
+/**
+ * Self-contained WS transport implementing IConfigurableTransport.
+ * Owns the WebSocket server lifecycle (ws package), started/stopped via the transport registry.
+ */
+
+interface IWsTransportConfig {
+    port?: number;
+    maxRetries?: number;
+}
+declare class WsTransport implements IConfigurableTransport {
+    readonly name = "ws";
+    readonly defaultEnabled = true;
+    readonly optionsSchema: {
+        port: {
+            type: string;
+            description: string;
+            default: number;
+        };
+        maxRetries: {
+            type: string;
+            description: string;
+            default: number;
+        };
+    };
+    private session;
+    private stopFn;
+    private readonly port;
+    private readonly maxRetries;
+    constructor(config?: IWsTransportConfig);
+    attach(session: ISession): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    validateOptions(options: Record<string, TUniversalValue>): boolean;
+    private bindWithRetry;
+    private tryBind;
+}
+
+export { type IWsHandlerOptions, type IWsTransportConfig, type IWsTransportOptions, type TClientMessage, type TServerMessage, WsTransport, createWsHandler, createWsTransport };

package/dist/node/index.d.ts

@@ -1,4 +1,7 @@
-import { IToolState, IExecutionResult, ICommandResult, InteractiveSession, TBackgroundTaskEvent, TBackgroundJobGroupEvent, IBackgroundTaskState, IBackgroundJobGroupState, IBackgroundTaskLogPage, IBackgroundTaskListFilter, IBackgroundTaskInput, IBackgroundTaskLogCursor, ITransportAdapter } from '@robota-sdk/agent-sdk';
+import { IToolState, IExecutionResult, ICommandResult, InteractiveSession, IExecutionWorkspaceSnapshot, TBackgroundTaskEvent, TBackgroundJobGroupEvent, IBackgroundTaskState, IBackgroundJobGroupState, IBackgroundTaskLogPage, IBackgroundTaskListFilter, IBackgroundTaskInput, IBackgroundTaskLogCursor } from '@robota-sdk/agent-sdk';
+export { IExecutionWorkspaceEntry, IExecutionWorkspaceSnapshot, TExecutionAttention, TExecutionWorkspaceStatus } from '@robota-sdk/agent-sdk';
+import { ITransportAdapter, IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+import { ISession, TUniversalValue } from '@robota-sdk/agent-core';
 
 type TBackgroundControlAction = 'cancel' | 'close' | 'send';
 /** Inbound message from client to server. */
@@ -21,6 +24,8 @@ type TClientMessage = {
     type: 'get-executing';
 } | {
     type: 'get-pending';
+} | {
+    type: 'get-execution-workspace';
 } | {
     type: 'get-background-tasks';
     filter?: IBackgroundTaskListFilter;
@@ -94,6 +99,9 @@ type TServerMessage = {
 } | {
     type: 'pending';
     pending: string | null;
+} | {
+    type: 'execution_workspace_event';
+    snapshot: IExecutionWorkspaceSnapshot;
 } | {
     type: 'background_task_event';
     event: TBackgroundTaskEvent;
@@ -183,4 +191,41 @@ declare function createWsTransport(options: IWsTransportOptions): ITransportAdap
     onMessage: ((data: string) => void) | null;
 };
 
-export { type IWsHandlerOptions, type IWsTransportOptions, type TClientMessage, type TServerMessage, createWsHandler, createWsTransport };
+/**
+ * Self-contained WS transport implementing IConfigurableTransport.
+ * Owns the WebSocket server lifecycle (ws package), started/stopped via the transport registry.
+ */
+
+interface IWsTransportConfig {
+    port?: number;
+    maxRetries?: number;
+}
+declare class WsTransport implements IConfigurableTransport {
+    readonly name = "ws";
+    readonly defaultEnabled = true;
+    readonly optionsSchema: {
+        port: {
+            type: string;
+            description: string;
+            default: number;
+        };
+        maxRetries: {
+            type: string;
+            description: string;
+            default: number;
+        };
+    };
+    private session;
+    private stopFn;
+    private readonly port;
+    private readonly maxRetries;
+    constructor(config?: IWsTransportConfig);
+    attach(session: ISession): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    validateOptions(options: Record<string, TUniversalValue>): boolean;
+    private bindWithRetry;
+    private tryBind;
+}
+
+export { type IWsHandlerOptions, type IWsTransportConfig, type IWsTransportOptions, type TClientMessage, type TServerMessage, WsTransport, createWsHandler, createWsTransport };

package/dist/node/index.js

@@ -131,6 +131,7 @@ function subscribeSessionEvents(session, send) {
   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 });
+  const onExecutionWorkspace = (event) => send({ type: "execution_workspace_event", snapshot: event.snapshot });
   session.on("user_message", onUserMessage);
   session.on("text_delta", onTextDelta);
   session.on("tool_start", onToolStart);
@@ -141,6 +142,7 @@ function subscribeSessionEvents(session, send) {
   session.on("error", onError);
   session.on("background_task_event", onBackgroundTaskEvent);
   session.on("background_job_group_event", onBackgroundJobGroupEvent);
+  session.on("execution_workspace_event", onExecutionWorkspace);
   return () => {
     session.off("user_message", onUserMessage);
     session.off("text_delta", onTextDelta);
@@ -152,6 +154,7 @@ function subscribeSessionEvents(session, send) {
     session.off("error", onError);
     session.off("background_task_event", onBackgroundTaskEvent);
     session.off("background_job_group_event", onBackgroundJobGroupEvent);
+    session.off("execution_workspace_event", onExecutionWorkspace);
   };
 }
 function createWsMessageHandler(session, send) {
@@ -195,7 +198,7 @@ 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";
+  return msg.type === "get-messages" || msg.type === "get-context" || msg.type === "get-executing" || msg.type === "get-pending" || msg.type === "get-execution-workspace";
 }
 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";
@@ -237,6 +240,11 @@ function handleSessionQueryMessage(session, send, msg) {
     send({ type: "context", state: session.getContextState() });
   } else if (msg.type === "get-executing") {
     send({ type: "executing", executing: session.isExecuting() });
+  } else if (msg.type === "get-execution-workspace") {
+    send({
+      type: "execution_workspace_event",
+      snapshot: session.getExecutionWorkspaceSnapshot()
+    });
   } else {
     send({ type: "pending", pending: session.getPendingPrompt() });
   }
@@ -265,7 +273,93 @@ function createWsTransport(options) {
     }
   };
 }
+
+// src/ws-transport-configurable.ts
+import { createServer } from "http";
+import { WebSocketServer, WebSocket } from "ws";
+var DEFAULT_PORT = 7070;
+var DEFAULT_MAX_RETRIES = 20;
+var WsTransport = class {
+  name = "ws";
+  defaultEnabled = true;
+  optionsSchema = {
+    port: { type: "number", description: "WebSocket server port", default: DEFAULT_PORT },
+    maxRetries: {
+      type: "number",
+      description: "Port retry attempts when port is occupied",
+      default: DEFAULT_MAX_RETRIES
+    }
+  };
+  session = null;
+  stopFn = null;
+  port;
+  maxRetries;
+  constructor(config = {}) {
+    this.port = config.port ?? DEFAULT_PORT;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+  }
+  attach(session) {
+    this.session = session;
+  }
+  async start() {
+    if (!this.session) throw new Error("WsTransport: attach() must be called before start()");
+    const handle = await this.bindWithRetry(this.session, this.port, this.maxRetries);
+    this.stopFn = handle.stop;
+  }
+  async stop() {
+    await this.stopFn?.();
+    this.stopFn = null;
+  }
+  validateOptions(options) {
+    const { port, maxRetries } = options;
+    if (port !== void 0 && (typeof port !== "number" || port < 1 || port > 65535)) return false;
+    if (maxRetries !== void 0 && (typeof maxRetries !== "number" || maxRetries < 0))
+      return false;
+    return true;
+  }
+  bindWithRetry(session, port, retriesLeft) {
+    return this.tryBind(session, port).catch((err) => {
+      if (err.code === "EADDRINUSE" && retriesLeft > 0)
+        return this.bindWithRetry(session, port + 1, retriesLeft - 1);
+      throw err;
+    });
+  }
+  tryBind(session, port) {
+    return new Promise((resolve, reject) => {
+      const httpServer = createServer((_, res) => {
+        res.writeHead(400).end("WebSocket endpoint");
+      });
+      httpServer.on("error", (err) => {
+        httpServer.close();
+        reject(err);
+      });
+      httpServer.listen(port, "127.0.0.1", () => {
+        const wss = new WebSocketServer({ server: httpServer });
+        wss.on("connection", (ws) => {
+          const send = (message) => {
+            if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(message));
+          };
+          const { onMessage, cleanup } = createWsHandler({ session, send });
+          ws.on("message", (data) => onMessage(String(data)));
+          ws.on("close", cleanup);
+          ws.on("error", cleanup);
+          send({ type: "messages", messages: session.getMessages() });
+          send({
+            type: "execution_workspace_event",
+            snapshot: session.getExecutionWorkspaceSnapshot()
+          });
+        });
+        resolve({
+          stop: () => new Promise((res) => {
+            wss.close(() => httpServer.close(() => res()));
+          })
+        });
+      });
+    });
+  }
+};
 export {
+  WsTransport,
   createWsHandler,
   createWsTransport
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-transport-ws",
-  "version": "3.0.0-beta.62",
+  "version": "3.0.0-beta.63",
   "description": "WebSocket transport adapter for exposing InteractiveSession over real-time connections",
   "type": "module",
   "main": "dist/node/index.js",
@@ -30,9 +30,13 @@
     "dist"
   ],
   "dependencies": {
-    "@robota-sdk/agent-sdk": "3.0.0-beta.62"
+    "ws": "^8.18.3",
+    "@robota-sdk/agent-core": "3.0.0-beta.63",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.63",
+    "@robota-sdk/agent-sdk": "3.0.0-beta.63"
   },
   "devDependencies": {
+    "@types/ws": "^8.5.10",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",