@clawswarm/bridge 0.1.0-alpha

package/dist/router.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Org-scoped task router for the ClawSwarm bridge.
+ *
+ * Routes messages from ClawSwarm events to the appropriate
+ * WebSocket clients based on organization ID and client role.
+ *
+ * @module @clawswarm/bridge/router
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskRouter = void 0;
+// ─── TaskRouter ───────────────────────────────────────────────────────────────
+/**
+ * Routes ClawSwarm events to connected bridge clients.
+ *
+ * Provides a high-level API for broadcasting goal/task events
+ * to the right clients within an organization.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new BridgeServer({ port: 8787 });
+ * await bridge.start();
+ *
+ * const router = new TaskRouter(bridge);
+ *
+ * // Connect a ClawSwarm instance to the router
+ * swarm.on('task:completed', (task) => {
+ *   router.routeTaskEvent('task:completed', task.goalId, task, 'my-org-id');
+ * });
+ * ```
+ */
+class TaskRouter {
+    bridge;
+    rules = new Map();
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    // ─── Routing Methods ──────────────────────────────────────────────────────
+    /**
+     * Route a task-related event to all dashboard clients in the org.
+     *
+     * @param type - Event type
+     * @param goalId - Goal ID for context
+     * @param payload - Event payload
+     * @param orgId - Organization to route to
+     */
+    routeTaskEvent(type, goalId, payload, orgId) {
+        return this.bridge.broadcast(orgId, this._buildMessage(type, orgId, payload), ['dashboard', 'external']);
+    }
+    /**
+     * Route a goal-related event.
+     *
+     * @param type - Event type
+     * @param payload - Event payload (the Goal object)
+     * @param orgId - Organization to route to
+     */
+    routeGoalEvent(type, payload, orgId) {
+        return this.bridge.broadcast(orgId, this._buildMessage(type, orgId, payload), ['dashboard', 'external']);
+    }
+    /**
+     * Route an agent status update to dashboard clients.
+     */
+    routeAgentStatus(agentId, agentType, status, orgId, currentTaskId) {
+        return this.bridge.broadcast(orgId, this._buildMessage('agent:status', orgId, { agentId, agentType, status, currentTaskId }), ['dashboard']);
+    }
+    /**
+     * Broadcast a raw message to all clients in an org.
+     */
+    broadcast(orgId, message, roles) {
+        return this.bridge.broadcast(orgId, message, roles);
+    }
+    /**
+     * Add a routing rule for custom message handling.
+     * Rules are evaluated before default routing.
+     *
+     * @param id - Unique rule identifier
+     * @param rule - Route rule definition
+     */
+    addRule(id, rule) {
+        this.rules.set(id, rule);
+    }
+    /**
+     * Remove a routing rule.
+     */
+    removeRule(id) {
+        return this.rules.delete(id);
+    }
+    /**
+     * Route a message through all matching rules.
+     * Returns the number of clients that received the message.
+     */
+    route(orgId, message) {
+        let count = 0;
+        for (const rule of this.rules.values()) {
+            if (rule.messageType !== '*' && rule.messageType !== message.type)
+                continue;
+            if (rule.orgIds && !rule.orgIds.includes(orgId))
+                continue;
+            count += this.bridge.broadcast(orgId, message, rule.roles);
+        }
+        // Default: broadcast to all in org if no rules matched
+        if (count === 0) {
+            count = this.bridge.broadcast(orgId, message);
+        }
+        return count;
+    }
+    // ─── Private ──────────────────────────────────────────────────────────────
+    /**
+     * Build a typed bridge message.
+     * @internal
+     */
+    _buildMessage(type, orgId, payload) {
+        return {
+            type,
+            ts: new Date().toISOString(),
+            orgId,
+            payload,
+        };
+    }
+}
+exports.TaskRouter = TaskRouter;
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Bridge-specific types for the ClawSwarm WebSocket bridge server.
+ * @module @clawswarm/bridge/types
+ */
+/** Role of a connected client */
+export type ClientRole = 'agent' | 'dashboard' | 'external';
+/** A connected WebSocket client */
+export interface BridgeClient {
+    /** Unique connection ID */
+    id: string;
+    /** Organization this client belongs to */
+    orgId: string;
+    /** Client role */
+    role: ClientRole;
+    /** ISO timestamp of connection */
+    connectedAt: string;
+    /** Last ping/pong timestamp */
+    lastPingAt?: string;
+    /** Whether the client is authenticated */
+    authenticated: boolean;
+    /** Metadata from the handshake */
+    metadata: Record<string, string>;
+}
+/** All message types the bridge can handle */
+export type BridgeMessageType = 'auth' | 'ping' | 'pong' | 'goal:created' | 'goal:planning' | 'goal:completed' | 'goal:failed' | 'task:assigned' | 'task:started' | 'task:completed' | 'task:review' | 'task:rejected' | 'task:rework' | 'task:failed' | 'human:review_required' | 'agent:status' | 'error';
+/** Base shape of all bridge messages */
+export interface BridgeMessage<T = unknown> {
+    /** Message type */
+    type: BridgeMessageType;
+    /** ISO timestamp */
+    ts: string;
+    /** Organization ID (for routing) */
+    orgId?: string;
+    /** Message payload */
+    payload: T;
+    /** Optional correlation ID for request/response pairs */
+    correlationId?: string;
+}
+/** Auth message payload (client → server) */
+export interface AuthPayload {
+    token: string;
+    orgId: string;
+    role: ClientRole;
+    metadata?: Record<string, string>;
+}
+/** Error message payload */
+export interface ErrorPayload {
+    code: string;
+    message: string;
+    correlationId?: string;
+}
+/** Agent status update payload */
+export interface AgentStatusPayload {
+    agentId: string;
+    agentType: string;
+    status: 'idle' | 'busy' | 'error' | 'offline';
+    currentTaskId?: string;
+}
+/** A routing rule that maps message types to handler functions */
+export interface RoutingRule {
+    /** Message type to match */
+    messageType: BridgeMessageType | '*';
+    /** Org IDs to route to (empty = all orgs) */
+    orgIds?: string[];
+    /** Client roles to route to (empty = all roles) */
+    roles?: ClientRole[];
+}
+/** Configuration for the BridgeServer */
+export interface BridgeServerConfig {
+    /** Port to listen on (default: 8787) */
+    port?: number;
+    /** Host to bind to (default: '0.0.0.0') */
+    host?: string;
+    /** Maximum concurrent connections (default: 1000) */
+    maxConnections?: number;
+    /** Ping interval in ms (default: 30000) */
+    pingIntervalMs?: number;
+    /** Allowed auth tokens — empty array means no auth required */
+    authTokens?: string[];
+    /** Path prefix for WebSocket endpoint (default: '/') */
+    path?: string;
+}
+/** Events emitted by BridgeServer */
+export interface BridgeServerEvents {
+    'client:connected': (client: BridgeClient) => void;
+    'client:disconnected': (clientId: string, reason: string) => void;
+    'client:authenticated': (client: BridgeClient) => void;
+    'message:received': (client: BridgeClient, message: BridgeMessage) => void;
+    'message:sent': (clientId: string, message: BridgeMessage) => void;
+    'error': (error: Error) => void;
+    'listening': (port: number, host: string) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Bridge-specific types for the ClawSwarm WebSocket bridge server.
+ * @module @clawswarm/bridge/types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@clawswarm/bridge",
+  "version": "0.1.0-alpha",
+  "description": "WebSocket bridge server for ClawSwarm — real-time agent communication and org-scoped task routing",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./bridge": {
+      "types": "./dist/bridge.d.ts",
+      "import": "./dist/bridge.js",
+      "default": "./dist/bridge.js"
+    },
+    "./router": {
+      "types": "./dist/router.d.ts",
+      "import": "./dist/router.js",
+      "default": "./dist/router.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@clawswarm/core": "0.1.0-alpha",
+    "eventemitter3": "^5.0.0",
+    "ws": "^8.16.0",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.10",
+    "@types/uuid": "^9.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "websocket",
+    "bridge",
+    "multi-agent",
+    "orchestration"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trietphan/clawswarm.git",
+    "directory": "packages/bridge"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,330 @@
+/**
+ * WebSocket bridge server for ClawSwarm.
+ *
+ * Provides real-time bidirectional communication between agents,
+ * dashboard clients, and external consumers. Handles org-scoped
+ * message routing, authentication, and connection lifecycle.
+ *
+ * @module @clawswarm/bridge/bridge
+ */
+
+import { WebSocketServer, WebSocket } from 'ws';
+import { v4 as uuidv4 } from 'uuid';
+import EventEmitter from 'eventemitter3';
+import {
+  BridgeClient,
+  BridgeMessage,
+  BridgeServerConfig,
+  BridgeServerEvents,
+  AuthPayload,
+} from './types.js';
+
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_PORT = 8787;
+const DEFAULT_HOST = '0.0.0.0';
+const DEFAULT_MAX_CONNECTIONS = 1000;
+const DEFAULT_PING_INTERVAL_MS = 30_000;
+
+// ─── BridgeServer ─────────────────────────────────────────────────────────────
+
+/**
+ * The ClawSwarm bridge server.
+ *
+ * Manages WebSocket connections, authenticates clients, and routes
+ * messages between agents and dashboard consumers within org boundaries.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new BridgeServer({ port: 8787 });
+ *
+ * bridge.on('client:connected', (client) => {
+ *   console.log('Connected:', client.id, 'org:', client.orgId);
+ * });
+ *
+ * await bridge.start();
+ * console.log('Bridge listening on ws://localhost:8787');
+ * ```
+ */
+export class BridgeServer extends (EventEmitter as new () => EventEmitter<BridgeServerEvents>) {
+  private readonly config: Required<BridgeServerConfig>;
+  private wss: WebSocketServer | null = null;
+  private clients: Map<string, { client: BridgeClient; socket: WebSocket }> = new Map();
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config: BridgeServerConfig = {}) {
+    super();
+    this.config = {
+      port: config.port ?? DEFAULT_PORT,
+      host: config.host ?? DEFAULT_HOST,
+      maxConnections: config.maxConnections ?? DEFAULT_MAX_CONNECTIONS,
+      pingIntervalMs: config.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS,
+      authTokens: config.authTokens ?? [],
+      path: config.path ?? '/',
+    };
+  }
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  /**
+   * Start the WebSocket server.
+   * Returns a promise that resolves once the server is listening.
+   */
+  async start(): Promise<void> {
+    if (this.wss) throw new Error('BridgeServer is already running');
+
+    return new Promise((resolve, reject) => {
+      this.wss = new WebSocketServer({
+        port: this.config.port,
+        host: this.config.host,
+        path: this.config.path,
+      });
+
+      this.wss.on('connection', (socket, req) => this._onConnection(socket, req));
+      this.wss.on('error', (err) => {
+        this.emit('error', err);
+        reject(err);
+      });
+
+      this.wss.on('listening', () => {
+        this._startPingTimer();
+        this.emit('listening', this.config.port, this.config.host);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Stop the WebSocket server and disconnect all clients.
+   */
+  async stop(): Promise<void> {
+    if (!this.wss) return;
+
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+
+    // Close all client connections
+    for (const [id, { socket }] of this.clients) {
+      socket.close(1001, 'Server shutting down');
+      this.clients.delete(id);
+    }
+
+    return new Promise((resolve) => {
+      this.wss!.close(() => {
+        this.wss = null;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Send a message to a specific client by ID.
+   * Returns false if the client is not found or not connected.
+   */
+  send(clientId: string, message: BridgeMessage): boolean {
+    const entry = this.clients.get(clientId);
+    if (!entry || entry.socket.readyState !== WebSocket.OPEN) return false;
+
+    try {
+      entry.socket.send(JSON.stringify(message));
+      this.emit('message:sent', clientId, message);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Broadcast a message to all clients in an organization.
+   * Optionally filter by role.
+   *
+   * @param orgId - Organization to broadcast to ('*' for all orgs)
+   * @param message - Message to send
+   * @param roles - Optional role filter
+   * @returns Number of clients reached
+   */
+  broadcast(
+    orgId: string,
+    message: BridgeMessage,
+    roles?: BridgeClient['role'][]
+  ): number {
+    let count = 0;
+    for (const [, { client, socket }] of this.clients) {
+      if (socket.readyState !== WebSocket.OPEN) continue;
+      if (orgId !== '*' && client.orgId !== orgId) continue;
+      if (roles && !roles.includes(client.role)) continue;
+      if (!client.authenticated) continue;
+
+      socket.send(JSON.stringify(message));
+      count++;
+    }
+    return count;
+  }
+
+  /**
+   * Get all connected clients (optionally filtered by org).
+   */
+  getClients(orgId?: string): BridgeClient[] {
+    const all = Array.from(this.clients.values()).map(e => e.client);
+    return orgId ? all.filter(c => c.orgId === orgId) : all;
+  }
+
+  /**
+   * Get server stats.
+   */
+  stats(): { connections: number; orgs: number; uptime: boolean } {
+    const orgs = new Set(Array.from(this.clients.values()).map(e => e.client.orgId));
+    return {
+      connections: this.clients.size,
+      orgs: orgs.size,
+      uptime: this.wss !== null,
+    };
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  /**
+   * Handle a new WebSocket connection.
+   * @internal
+   */
+  private _onConnection(socket: WebSocket, _req: import('http').IncomingMessage): void {
+    if (this.clients.size >= this.config.maxConnections) {
+      socket.close(1013, 'Server at capacity');
+      return;
+    }
+
+    const clientId = uuidv4();
+    const client: BridgeClient = {
+      id: clientId,
+      orgId: 'unknown',
+      role: 'external',
+      connectedAt: new Date().toISOString(),
+      authenticated: this.config.authTokens.length === 0, // no auth if no tokens configured
+      metadata: {},
+    };
+
+    this.clients.set(clientId, { client, socket });
+    this.emit('client:connected', client);
+
+    socket.on('message', (data) => this._onMessage(clientId, data));
+    socket.on('close', (code, reason) => this._onClose(clientId, code, reason.toString()));
+    socket.on('error', (err) => this.emit('error', err));
+    socket.on('pong', () => {
+      const entry = this.clients.get(clientId);
+      if (entry) entry.client.lastPingAt = new Date().toISOString();
+    });
+  }
+
+  /**
+   * Handle an incoming message from a client.
+   * @internal
+   */
+  private _onMessage(clientId: string, data: import('ws').RawData): void {
+    const entry = this.clients.get(clientId);
+    if (!entry) return;
+
+    let message: BridgeMessage;
+    try {
+      message = JSON.parse(data.toString()) as BridgeMessage;
+    } catch {
+      this.send(clientId, this._errorMessage('PARSE_ERROR', 'Invalid JSON'));
+      return;
+    }
+
+    // Handle auth message
+    if (message.type === 'auth') {
+      this._handleAuth(clientId, message.payload as AuthPayload);
+      return;
+    }
+
+    // Reject unauthenticated messages
+    if (!entry.client.authenticated) {
+      this.send(clientId, this._errorMessage('UNAUTHORIZED', 'Authenticate first'));
+      return;
+    }
+
+    // Handle ping
+    if (message.type === 'ping') {
+      this.send(clientId, { type: 'pong', ts: new Date().toISOString(), payload: {} });
+      return;
+    }
+
+    this.emit('message:received', entry.client, message);
+  }
+
+  /**
+   * Handle an auth message from a client.
+   * @internal
+   */
+  private _handleAuth(clientId: string, payload: AuthPayload): void {
+    const entry = this.clients.get(clientId);
+    if (!entry) return;
+
+    const { token, orgId, role, metadata } = payload;
+
+    // Validate token if auth is configured
+    if (
+      this.config.authTokens.length > 0 &&
+      !this.config.authTokens.includes(token)
+    ) {
+      this.send(clientId, this._errorMessage('INVALID_TOKEN', 'Invalid auth token'));
+      entry.socket.close(1008, 'Unauthorized');
+      return;
+    }
+
+    entry.client.authenticated = true;
+    entry.client.orgId = orgId;
+    entry.client.role = role;
+    entry.client.metadata = metadata ?? {};
+
+    this.send(clientId, {
+      type: 'pong', // using pong as ack
+      ts: new Date().toISOString(),
+      payload: { authenticated: true, clientId },
+    });
+
+    this.emit('client:authenticated', entry.client);
+  }
+
+  /**
+   * Handle a client disconnection.
+   * @internal
+   */
+  private _onClose(clientId: string, code: number, reason: string): void {
+    this.clients.delete(clientId);
+    this.emit('client:disconnected', clientId, reason || String(code));
+  }
+
+  /**
+   * Build an error message.
+   * @internal
+   */
+  private _errorMessage(code: string, message: string): BridgeMessage {
+    return {
+      type: 'error',
+      ts: new Date().toISOString(),
+      payload: { code, message },
+    };
+  }
+
+  /**
+   * Start the ping timer for keep-alive.
+   * @internal
+   */
+  private _startPingTimer(): void {
+    this.pingTimer = setInterval(() => {
+      const now = new Date().toISOString();
+      for (const [id, { socket, client }] of this.clients) {
+        if (socket.readyState === WebSocket.OPEN) {
+          socket.ping();
+          client.lastPingAt = now;
+        } else {
+          // Clean up stale connections
+          this.clients.delete(id);
+        }
+      }
+    }, this.config.pingIntervalMs);
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @clawswarm/bridge — Public API
+ *
+ * @example
+ * ```typescript
+ * import { BridgeServer, TaskRouter } from '@clawswarm/bridge';
+ * ```
+ *
+ * @module @clawswarm/bridge
+ */
+
+export { BridgeServer } from './bridge.js';
+export { TaskRouter } from './router.js';
+
+export type {
+  BridgeClient,
+  ClientRole,
+  BridgeMessage,
+  BridgeMessageType,
+  BridgeServerConfig,
+  BridgeServerEvents,
+  AuthPayload,
+  ErrorPayload,
+  AgentStatusPayload,
+  RoutingRule,
+} from './types.js';