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

package/src/ws/ws-handler.ts

@@ -1,280 +0,0 @@
-/**
- * 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 {
-  handleBackgroundControlMessage,
-  handleBackgroundQueryMessage,
-} from './ws-background-messages.js';
-
-import type { TClientMessage, TServerMessage } from './ws-protocol.js';
-import type { TBackgroundTaskEvent } from '@robota-sdk/agent-framework';
-import type {
-  IExecutionResult,
-  IExecutionWorkspaceEvent,
-  IInteractiveSession,
-  IToolState,
-  TBackgroundJobGroupEvent,
-} from '@robota-sdk/agent-interface-transport';
-
-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

@@ -1,78 +0,0 @@
-import type {
-  InteractiveSession,
-  IBackgroundTaskInput,
-  IBackgroundTaskListFilter,
-  IBackgroundTaskLogCursor,
-  IBackgroundTaskLogPage,
-  IBackgroundTaskState,
-  TBackgroundTaskEvent,
-} from '@robota-sdk/agent-framework';
-import type {
-  IBackgroundJobGroupState,
-  ICommandResult,
-  IExecutionResult,
-  IExecutionWorkspaceSnapshot,
-  IToolState,
-  TBackgroundJobGroupEvent,
-} from '@robota-sdk/agent-interface-transport';
-
-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

@@ -1,128 +0,0 @@
-/**
- * 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 { createWsHandler } from './ws-handler.js';
-
-import type { TServerMessage } from './ws-protocol.js';
-import type { TUniversalValue } from '@robota-sdk/agent-core';
-import type {
-  IConfigurableTransport,
-  IInteractiveSession,
-} from '@robota-sdk/agent-interface-transport';
-
-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

@@ -1,42 +0,0 @@
-/**
- * ITransportAdapter implementation for WebSocket transport.
- *
- * Wraps createWsHandler into the unified ITransportAdapter interface.
- * After start(), the consumer must wire onMessage to their WebSocket.
- */
-
-import { createWsHandler } from './ws-handler.js';
-
-import type { TServerMessage } from './ws-protocol.js';
-import type { IInteractiveSession, ITransportAdapter } from '@robota-sdk/agent-interface-transport';
-
-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;
-    },
-  };
-}