@radaros/transport 0.3.21 → 0.3.22

package/dist/index.d.cts

@@ -0,0 +1,333 @@
+import { Agent, A2AAgentCard, MCPToolProviderConfig, ToolDef, MCPToolProvider, Registry, Servable, Team, Workflow, Toolkit, EventBus, VoiceAgent } from '@radaros/core';
+
+interface A2AServerOptions {
+    agents: Record<string, Agent>;
+    basePath?: string;
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    version?: string;
+}
+
+/**
+ * Mount an A2A-compliant server on an Express app.
+ *
+ * - Serves `/.well-known/agent.json` with the Agent Card
+ * - Handles JSON-RPC 2.0 requests at the basePath for message/send, message/stream, tasks/get, tasks/cancel
+ */
+declare function createA2AServer(app: any, opts: A2AServerOptions): void;
+
+/**
+ * Generate an A2A Agent Card from a RadarOS Agent.
+ * The card is served at /.well-known/agent.json per the A2A spec.
+ */
+declare function generateAgentCard(agent: Agent, serverUrl: string, provider?: {
+    organization: string;
+    url?: string;
+}, version?: string): A2AAgentCard;
+/**
+ * Generate a combined Agent Card that lists multiple agents as skills.
+ */
+declare function generateMultiAgentCard(agents: Record<string, Agent>, serverUrl: string, provider?: {
+    organization: string;
+    url?: string;
+}, version?: string): A2AAgentCard;
+
+interface MCPServerEntry {
+    id: string;
+    config: MCPToolProviderConfig;
+    provider: MCPToolProvider;
+    status: "disconnected" | "connecting" | "connected" | "error";
+    error?: string;
+    toolCount: number;
+    connectedAt?: Date;
+}
+interface MCPServerSummary {
+    id: string;
+    name: string;
+    transport: string;
+    url?: string;
+    command?: string;
+    status: string;
+    toolCount: number;
+    error?: string;
+    connectedAt?: string;
+}
+/**
+ * Manages multiple MCP server connections at runtime.
+ * Servers can be added/removed/connected/disconnected dynamically,
+ * and their tools can be collected for injection into agents.
+ */
+declare class MCPManager {
+    private servers;
+    /** Add a server config. Auto-generates an id from the name if not provided. */
+    add(config: MCPToolProviderConfig, id?: string): MCPServerSummary;
+    /** Connect a server by id. Discovers tools on success. */
+    connect(id: string): Promise<MCPServerSummary>;
+    /** Disconnect a server by id. */
+    disconnect(id: string): Promise<MCPServerSummary>;
+    /** Remove a server entirely. Disconnects first if connected. */
+    remove(id: string): Promise<void>;
+    /** Get all tools from all connected servers, merged into one array. */
+    getAllTools(): Promise<ToolDef[]>;
+    /** Get tools from a specific server. */
+    getTools(id: string): Promise<ToolDef[]>;
+    /** List all registered servers. */
+    list(): MCPServerSummary[];
+    /** Get a single server summary. */
+    get(id: string): MCPServerSummary;
+    has(id: string): boolean;
+    /** Disconnect all servers. */
+    closeAll(): Promise<void>;
+    private getEntry;
+    private summarize;
+}
+
+interface AdminRouterOptions {
+    /** Shared MCPManager instance. If omitted, a new one is created. */
+    mcpManager?: MCPManager;
+    /**
+     * Express middleware for authentication/authorization.
+     * **IMPORTANT**: These endpoints can add MCP servers and execute tools.
+     * Always add auth middleware in production.
+     */
+    middleware?: any[];
+}
+/**
+ * Creates an Express sub-router with admin endpoints for managing
+ * MCP servers and the toolkit catalog at runtime.
+ *
+ * Mount under a prefix: `app.use("/admin", createAdminRouter())`
+ *
+ * Routes:
+ *   GET    /mcp              — list MCP servers
+ *   POST   /mcp              — add + connect an MCP server
+ *   GET    /mcp/:id          — single server details
+ *   POST   /mcp/:id/connect  — connect a server
+ *   POST   /mcp/:id/disconnect — disconnect
+ *   DELETE /mcp/:id          — remove a server
+ *   GET    /mcp/:id/tools    — tools from a specific server
+ *   GET    /mcp/tools        — all tools across connected servers
+ *
+ *   GET    /toolkits         — list toolkit catalog
+ *   GET    /toolkits/:id     — single toolkit meta
+ *   POST   /toolkits/:id     — instantiate a toolkit with config
+ */
+declare function createAdminRouter(opts?: AdminRouterOptions): {
+    router: any;
+    mcpManager: MCPManager;
+};
+
+interface FileUploadOptions {
+    maxFileSize?: number;
+    maxFiles?: number;
+    allowedMimeTypes?: string[];
+}
+declare function createFileUploadMiddleware(opts?: FileUploadOptions): any;
+declare function buildMultiModalInput(body: any, files?: any[]): string | any[];
+
+declare function errorHandler(options?: {
+    logger?: Pick<Console, "error">;
+}): (err: any, _req: any, res: any, _next: any) => void;
+declare function requestLogger(options?: {
+    logger?: Pick<Console, "log">;
+}): (req: any, _res: any, next: any) => void;
+
+interface SwaggerOptions {
+    /** Enable Swagger UI at /docs. Default: false */
+    enabled?: boolean;
+    /** API title shown in Swagger UI */
+    title?: string;
+    /** API description shown in Swagger UI */
+    description?: string;
+    /** API version string */
+    version?: string;
+    /** Route prefix used in path generation (e.g. "/api") */
+    routePrefix?: string;
+    /** Server URLs for the spec */
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    /** Path to serve Swagger UI. Default: "/docs" */
+    docsPath?: string;
+    /** Path to serve the raw OpenAPI JSON spec. Default: "/docs/spec.json" */
+    specPath?: string;
+}
+interface RouterOptions {
+    /**
+     * Use a Registry for live auto-discovery. The router creates dynamic routes
+     * that resolve agents/teams/workflows at request time — any instance created
+     * after the router is mounted is automatically available.
+     *
+     * When omitted, falls back to the global registry from `@radaros/core`.
+     * Pass `false` to disable registry-based routing entirely (use explicit maps only).
+     *
+     * @example
+     * createAgentRouter({ cors: true });
+     * new Agent({ name: "bot", model: openai("gpt-4o") }); // immediately routable
+     */
+    registry?: Registry | false;
+    /**
+     * Auto-discover agents, teams, and workflows from a mixed array.
+     * Each item is classified by its `.kind` and keyed by `.name`.
+     */
+    serve?: Servable[];
+    agents?: Record<string, Agent>;
+    teams?: Record<string, Team>;
+    workflows?: Record<string, Workflow<any>>;
+    middleware?: any[];
+    /** Swagger / OpenAPI configuration */
+    swagger?: SwaggerOptions;
+    /** File upload configuration for multi-modal inputs */
+    fileUpload?: boolean | FileUploadOptions;
+    /** CORS configuration. Pass true or '*' for permissive, a string for a single origin, or an array for multiple origins. */
+    cors?: string | string[] | boolean;
+    /** Rate limiting configuration. Pass true for defaults (100 req/min), or an object to customize. */
+    rateLimit?: {
+        windowMs?: number;
+        max?: number;
+    } | boolean;
+    /** Named tool library exposed via GET /tools. Tools from toolkits are auto-collected. */
+    toolLibrary?: Record<string, ToolDef>;
+    /** Toolkit instances whose tools are exposed via GET /tools. Merged with toolLibrary. */
+    toolkits?: Toolkit[];
+    /**
+     * Enable admin routes under `/admin` for managing MCP servers and the toolkit catalog.
+     * Pass `true` to use defaults, or provide an MCPManager instance to share state.
+     */
+    admin?: boolean | {
+        mcpManager?: MCPManager;
+    };
+}
+
+declare function createAgentRouter(opts: RouterOptions): any;
+
+interface OpenAPISpec {
+    openapi: string;
+    info: {
+        title: string;
+        description: string;
+        version: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, Record<string, unknown>>;
+    components: {
+        schemas: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+    };
+    security?: Array<Record<string, string[]>>;
+    tags: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+declare function generateOpenAPISpec(routerOpts: RouterOptions, swaggerOpts?: SwaggerOptions): OpenAPISpec;
+
+/**
+ * Minimal interface for a BrowserAgent — avoids a hard dependency on @radaros/browser.
+ * Any object that matches this shape (e.g. a real BrowserAgent) works.
+ */
+interface BrowserAgentLike {
+    name: string;
+    eventBus: EventBus;
+    run(task: string, opts?: {
+        startUrl?: string;
+        apiKey?: string;
+        sessionId?: string;
+    }): Promise<{
+        result: string;
+        success: boolean;
+        finalUrl: string;
+        durationMs: number;
+        videoPath?: string;
+        steps: Array<{
+            index: number;
+            action: unknown;
+            screenshot: Buffer;
+            pageUrl: string;
+            pageTitle: string;
+            dom?: string;
+        }>;
+    }>;
+}
+interface BrowserGatewayOptions {
+    /** Named BrowserAgent instances. Clients select one via agentName. */
+    agents: Record<string, BrowserAgentLike>;
+    /** Socket.IO server instance */
+    io: any;
+    /** Socket.IO namespace. Default: "/radaros-browser" */
+    namespace?: string;
+    /** Optional auth middleware applied to the namespace */
+    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
+    /**
+     * Stream screenshots to the client in real-time.
+     * Default: true. Disable for bandwidth-constrained clients.
+     */
+    streamScreenshots?: boolean;
+}
+/**
+ * Create a Socket.IO gateway that streams BrowserAgent execution in real-time.
+ *
+ * ## Client → Server events
+ * - `browser.start` — kick off a browser task
+ * - `browser.stop`  — cancel a running task
+ *
+ * ## Server → Client events
+ * - `browser.started`    — task accepted
+ * - `browser.screenshot` — live screenshot (base64 PNG)
+ * - `browser.action`     — action about to execute
+ * - `browser.step`       — full step with screenshot + DOM
+ * - `browser.done`       — task finished (result, success, duration, video)
+ * - `browser.error`      — error occurred
+ * - `browser.stopped`    — task was cancelled
+ */
+declare function createBrowserGateway(opts: BrowserGatewayOptions): void;
+
+interface GatewayOptions {
+    /**
+     * Use a Registry for live auto-discovery. The gateway resolves agents/teams
+     * at event time — any instance created after the gateway starts is automatically
+     * reachable.
+     *
+     * When omitted, falls back to the global registry from `@radaros/core`.
+     * Pass `false` to disable registry-based lookup (use explicit maps only).
+     *
+     * @example
+     * createAgentGateway({ io });
+     * new Agent({ name: "bot", model: openai("gpt-4o") }); // immediately reachable
+     */
+    registry?: Registry | false;
+    /**
+     * Auto-discover agents and teams from a mixed array.
+     * Each item is classified by its `.kind` and keyed by `.name`.
+     */
+    serve?: Servable[];
+    agents?: Record<string, Agent>;
+    teams?: Record<string, Team>;
+    io: any;
+    namespace?: string;
+    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
+    /** Max requests per minute per socket. Default: 60 */
+    maxRequestsPerMinute?: number;
+    /** Named tool library exposed via tools.list event. */
+    toolLibrary?: Record<string, ToolDef>;
+    /** Toolkit instances whose tools are exposed via tools.list. Merged with toolLibrary. */
+    toolkits?: Toolkit[];
+}
+
+declare function createAgentGateway(opts: GatewayOptions): void;
+
+interface VoiceGatewayOptions {
+    agents: Record<string, VoiceAgent>;
+    io: any;
+    namespace?: string;
+    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
+}
+declare function createVoiceGateway(opts: VoiceGatewayOptions): void;
+
+export { type A2AServerOptions, type AdminRouterOptions, type BrowserGatewayOptions, type FileUploadOptions, type GatewayOptions, MCPManager, type MCPServerEntry, type MCPServerSummary, type RouterOptions, type SwaggerOptions, type VoiceGatewayOptions, buildMultiModalInput, createA2AServer, createAdminRouter, createAgentGateway, createAgentRouter, createBrowserGateway, createFileUploadMiddleware, createVoiceGateway, errorHandler, generateAgentCard, generateMultiAgentCard, generateOpenAPISpec, requestLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radaros/transport",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "description": "HTTP and WebSocket transport layer for RadarOS agents",
   "license": "MIT",
   "repository": {
@@ -17,20 +17,23 @@
     "transport"
   ],
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
@@ -39,7 +42,7 @@
     "typescript": "^5.6.0"
   },
   "peerDependencies": {
-    "@radaros/core": "^0.3.21",
+    "@radaros/core": "^0.3.22",
     "@types/express": "^4.0.0 || ^5.0.0",
     "express": "^4.0.0 || ^5.0.0",
     "multer": ">=2.0.0",