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

package/src/ws/ws-background-messages.ts

@@ -0,0 +1,170 @@
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { TBackgroundControlAction, TClientMessage, TServerMessage } from './ws-protocol.js';
+
+export function handleBackgroundQueryMessage(
+  session: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<
+    TClientMessage,
+    | { type: 'get-background-tasks' | 'get-background-task' | 'read-background-task-log' }
+    | {
+        type:
+          | 'get-background-job-groups'
+          | 'get-background-job-group'
+          | 'wait-background-job-group';
+      }
+  >,
+): void {
+  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);
+}
+
+export function handleBackgroundControlMessage(
+  session: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<
+    TClientMessage,
+    { type: 'cancel-background-task' | 'close-background-task' | 'send-background-task' }
+  >,
+): void {
+  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: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<TClientMessage, { type: 'get-background-task' }>,
+): void {
+  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: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<TClientMessage, { type: 'read-background-task-log' }>,
+): void {
+  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: Error) => send({ type: 'protocol_error', message: error.message }),
+  );
+}
+
+function sendBackgroundJobGroupSnapshot(
+  session: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<TClientMessage, { type: 'get-background-job-group' }>,
+): void {
+  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: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<TClientMessage, { type: 'wait-background-job-group' }>,
+): void {
+  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: Error) => send({ type: 'protocol_error', message: error.message }),
+  );
+}
+
+function sendBackgroundTaskInput(
+  session: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<TClientMessage, { type: 'send-background-task' }>,
+): void {
+  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: (message: TServerMessage) => void,
+  action: TBackgroundControlAction,
+  taskId: string,
+  operation: Promise<void>,
+): void {
+  operation.then(
+    () => send({ type: 'background_task_control_result', action, taskId, success: true }),
+    (error: Error) =>
+      send({
+        type: 'background_task_control_result',
+        action,
+        taskId,
+        success: false,
+        message: error.message,
+      }),
+  );
+}

package/src/ws/ws-handler.ts

@@ -0,0 +1,279 @@
+/**
+ * WebSocket transport adapter — exposes IInteractiveSession 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 IInteractiveSession events to client in real-time.
+ */
+
+import type {
+  IInteractiveSession,
+  IExecutionResult,
+  IExecutionWorkspaceEvent,
+  TBackgroundJobGroupEvent,
+  TBackgroundTaskEvent,
+  IToolState,
+} from '@robota-sdk/agent-framework';
+import type { TClientMessage, TServerMessage } from './ws-protocol.js';
+import {
+  handleBackgroundControlMessage,
+  handleBackgroundQueryMessage,
+} from './ws-background-messages.js';
+
+export interface IWsHandlerOptions {
+  /** IInteractiveSession to expose. */
+  session: IInteractiveSession;
+  /** Send a JSON message to the client. */
+  send: (message: TServerMessage) => void;
+}
+
+/**
+ * Create a WebSocket message handler for an IInteractiveSession.
+ *
+ * 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,
+ *   send: (msg) => ws.send(JSON.stringify(msg)),
+ * });
+ *
+ * ws.on('message', (data) => onMessage(String(data)));
+ * ws.on('close', cleanup);
+ * ```
+ */
+export function createWsHandler(options: IWsHandlerOptions): {
+  onMessage: (data: string) => void;
+  cleanup: () => void;
+} {
+  const cleanup = subscribeSessionEvents(options.session, options.send);
+  const onMessage = createWsMessageHandler(options.session, options.send);
+
+  return { onMessage, cleanup };
+}
+
+function subscribeSessionEvents(
+  session: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+): () => void {
+  const onUserMessage = (content: string): void => send({ type: 'user_message', content });
+  const onTextDelta = (delta: string): void => send({ type: 'text_delta', delta });
+  const onToolStart = (state: IToolState): void => send({ type: 'tool_start', state });
+  const onToolEnd = (state: IToolState): void => send({ type: 'tool_end', state });
+  const onThinking = (isThinking: boolean): void => send({ type: 'thinking', isThinking });
+  const onComplete = (result: IExecutionResult): void => send({ type: 'complete', result });
+  const onInterrupted = (result: IExecutionResult): void => send({ type: 'interrupted', result });
+  const onError = (error: Error): void => send({ type: 'error', message: error.message });
+  const onBackgroundTaskEvent = (event: TBackgroundTaskEvent): void =>
+    send({ type: 'background_task_event', event });
+  const onBackgroundJobGroupEvent = (event: TBackgroundJobGroupEvent): void =>
+    send({ type: 'background_job_group_event', event });
+  const onExecutionWorkspace = (event: IExecutionWorkspaceEvent): void =>
+    send({ type: 'execution_workspace_event', snapshot: event.snapshot });
+
+  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);
+  session.on('execution_workspace_event', onExecutionWorkspace);
+
+  return (): void => {
+    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);
+    session.off('execution_workspace_event', onExecutionWorkspace);
+  };
+}
+
+function createWsMessageHandler(
+  session: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+): (data: string) => void {
+  return (data: string): void => {
+    const msg = parseClientMessage(data, send);
+    if (!msg) return;
+    handleClientMessage(session, send, msg);
+  };
+}
+
+function parseClientMessage(
+  data: string,
+  send: (message: TServerMessage) => void,
+): TClientMessage | null {
+  try {
+    return JSON.parse(data) as TClientMessage;
+  } catch {
+    send({ type: 'protocol_error', message: 'Invalid JSON' });
+    return null;
+  }
+}
+
+function handleClientMessage(
+  session: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: TClientMessage,
+): void {
+  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: TClientMessage): string {
+  return (msg as { type: string }).type;
+}
+
+function isSessionControlMessage(
+  msg: TClientMessage,
+): msg is Extract<TClientMessage, { type: 'submit' | 'command' | 'abort' | 'cancel-queue' }> {
+  return (
+    msg.type === 'submit' ||
+    msg.type === 'command' ||
+    msg.type === 'abort' ||
+    msg.type === 'cancel-queue'
+  );
+}
+
+function isSessionQueryMessage(msg: TClientMessage): msg is Extract<
+  TClientMessage,
+  {
+    type:
+      | 'get-messages'
+      | 'get-context'
+      | 'get-executing'
+      | 'get-pending'
+      | 'get-execution-workspace';
+  }
+> {
+  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: TClientMessage,
+): msg is Extract<
+  TClientMessage,
+  | { type: 'get-background-tasks' | 'get-background-task' | 'read-background-task-log' }
+  | { type: 'get-background-job-groups' | 'get-background-job-group' | 'wait-background-job-group' }
+> {
+  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: TClientMessage,
+): msg is Extract<
+  TClientMessage,
+  { type: 'cancel-background-task' | 'close-background-task' | 'send-background-task' }
+> {
+  return (
+    msg.type === 'cancel-background-task' ||
+    msg.type === 'close-background-task' ||
+    msg.type === 'send-background-task'
+  );
+}
+
+function handleSessionControlMessage(
+  session: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<TClientMessage, { type: 'submit' | 'command' | 'abort' | 'cancel-queue' }>,
+): void {
+  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: IInteractiveSession,
+  send: (message: TServerMessage) => void,
+  msg: Extract<
+    TClientMessage,
+    {
+      type:
+        | 'get-messages'
+        | 'get-context'
+        | 'get-executing'
+        | 'get-pending'
+        | 'get-execution-workspace';
+    }
+  >,
+): void {
+  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 if (msg.type === 'get-execution-workspace') {
+    send({
+      type: 'execution_workspace_event',
+      snapshot: session.getExecutionWorkspaceSnapshot(),
+    });
+  } else {
+    send({ type: 'pending', pending: session.getPendingPrompt() });
+  }
+}

package/src/ws/ws-protocol.ts

@@ -0,0 +1,76 @@
+import type {
+  InteractiveSession,
+  ICommandResult,
+  IBackgroundJobGroupState,
+  IBackgroundTaskInput,
+  IBackgroundTaskListFilter,
+  IBackgroundTaskLogCursor,
+  IBackgroundTaskLogPage,
+  IBackgroundTaskState,
+  IExecutionResult,
+  IExecutionWorkspaceSnapshot,
+  IToolState,
+  TBackgroundJobGroupEvent,
+  TBackgroundTaskEvent,
+} from '@robota-sdk/agent-framework';
+
+export type TBackgroundControlAction = 'cancel' | 'close' | 'send';
+
+/** Inbound message from client to server. */
+export 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' }
+  | { type: 'get-execution-workspace' }
+  | { type: 'get-background-tasks'; filter?: IBackgroundTaskListFilter }
+  | { type: 'get-background-task'; taskId: string }
+  | { type: 'get-background-job-groups' }
+  | { type: 'get-background-job-group'; groupId: string }
+  | { type: 'wait-background-job-group'; groupId: string }
+  | { type: 'cancel-background-task'; taskId: string; reason?: string }
+  | { type: 'close-background-task'; taskId: string }
+  | { type: 'send-background-task'; taskId: string; input: IBackgroundTaskInput }
+  | { type: 'read-background-task-log'; taskId: string; cursor?: IBackgroundTaskLogCursor };
+
+/** Outbound message from server to client. */
+export type TServerMessage =
+  | { type: 'text_delta'; delta: string }
+  | { type: 'user_message'; content: 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?: ICommandResult['data'];
+    }
+  | { type: 'messages'; messages: ReturnType<InteractiveSession['getMessages']> }
+  | { type: 'context'; state: ReturnType<InteractiveSession['getContextState']> }
+  | { type: 'executing'; executing: boolean }
+  | { type: 'pending'; pending: string | null }
+  | { type: 'execution_workspace_event'; snapshot: IExecutionWorkspaceSnapshot }
+  | { type: 'background_task_event'; event: TBackgroundTaskEvent }
+  | { type: 'background_job_group_event'; event: TBackgroundJobGroupEvent }
+  | { type: 'background_tasks'; tasks: IBackgroundTaskState[] }
+  | { type: 'background_task'; taskId: string; task: IBackgroundTaskState | null }
+  | { type: 'background_job_groups'; groups: IBackgroundJobGroupState[] }
+  | { type: 'background_job_group'; groupId: string; group: IBackgroundJobGroupState | null }
+  | { type: 'background_task_log'; taskId: string; page: IBackgroundTaskLogPage }
+  | {
+      type: 'background_task_control_result';
+      action: TBackgroundControlAction;
+      taskId: string;
+      success: boolean;
+      message?: string;
+    }
+  | { type: 'protocol_error'; message: string };

package/src/ws/ws-transport-configurable.ts

@@ -0,0 +1,123 @@
+/**
+ * Self-contained WS transport implementing IConfigurableTransport.
+ * Owns the WebSocket server lifecycle (ws package), started/stopped via the transport registry.
+ */
+
+import { createServer, type Server } from 'node:http';
+import { WebSocketServer, WebSocket } from 'ws';
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+import type { IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+import { createWsHandler } from './ws-handler.js';
+import type { TServerMessage } from './ws-protocol.js';
+
+const DEFAULT_PORT = 7070;
+const DEFAULT_MAX_RETRIES = 20;
+
+export interface IWsTransportConfig {
+  port?: number;
+  maxRetries?: number;
+}
+
+export class WsTransport implements IConfigurableTransport<IInteractiveSession> {
+  readonly name = 'ws';
+  readonly defaultEnabled = true;
+  readonly 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,
+    },
+  };
+
+  private session: IInteractiveSession | null = null;
+  private stopFn: (() => Promise<void>) | null = null;
+  private readonly port: number;
+  private readonly maxRetries: number;
+
+  constructor(config: IWsTransportConfig = {}) {
+    this.port = config.port ?? DEFAULT_PORT;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+  }
+
+  attach(session: IInteractiveSession): void {
+    this.session = session;
+  }
+
+  async start(): Promise<void> {
+    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(): Promise<void> {
+    await this.stopFn?.();
+    this.stopFn = null;
+  }
+
+  validateOptions(options: Record<string, TUniversalValue>): boolean {
+    const { port, maxRetries } = options;
+    if (port !== undefined && (typeof port !== 'number' || port < 1 || port > 65535)) return false;
+    if (maxRetries !== undefined && (typeof maxRetries !== 'number' || maxRetries < 0))
+      return false;
+    return true;
+  }
+
+  private bindWithRetry(
+    session: IInteractiveSession,
+    port: number,
+    retriesLeft: number,
+  ): Promise<{ stop: () => Promise<void> }> {
+    return this.tryBind(session, port).catch((err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE' && retriesLeft > 0)
+        return this.bindWithRetry(session, port + 1, retriesLeft - 1);
+      throw err;
+    });
+  }
+
+  private tryBind(
+    session: IInteractiveSession,
+    port: number,
+  ): Promise<{ stop: () => Promise<void> }> {
+    return new Promise((resolve, reject) => {
+      const httpServer: Server = createServer((_, res) => {
+        res.writeHead(400).end('WebSocket endpoint');
+      });
+
+      httpServer.on('error', (err: NodeJS.ErrnoException) => {
+        httpServer.close();
+        reject(err);
+      });
+
+      httpServer.listen(port, '127.0.0.1', () => {
+        const wss = new WebSocketServer({ server: httpServer });
+
+        wss.on('connection', (ws: WebSocket) => {
+          const send = (message: TServerMessage): void => {
+            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<void>((res) => {
+              wss.close(() => httpServer.close(() => res()));
+            }),
+        });
+      });
+    });
+  }
+}

package/src/ws/ws-transport.ts

@@ -0,0 +1,42 @@
+/**
+ * ITransportAdapter implementation for WebSocket transport.
+ *
+ * Wraps createWsHandler into the unified ITransportAdapter interface.
+ * After start(), the consumer must wire onMessage to their WebSocket.
+ */
+
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import { createWsHandler } from './ws-handler.js';
+import type { TServerMessage } from './ws-protocol.js';
+
+export interface IWsTransportOptions {
+  /** Send a JSON message to the connected WebSocket client. */
+  send: (message: TServerMessage) => void;
+}
+
+export function createWsTransport(
+  options: IWsTransportOptions,
+): ITransportAdapter<IInteractiveSession> & { onMessage: ((data: string) => void) | null } {
+  let session: IInteractiveSession | null = null;
+  let cleanup: (() => void) | null = null;
+
+  return {
+    name: 'ws',
+    onMessage: null,
+    attach(s: IInteractiveSession) {
+      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;
+    },
+  };
+}