@radaros/transport 0.1.0

package/dist/index.js

@@ -0,0 +1,728 @@
+// src/express/router-factory.ts
+import { createRequire as createRequire3 } from "module";
+
+// src/express/swagger.ts
+import { createRequire } from "module";
+var _require = createRequire(import.meta.url);
+var SCHEMAS = {
+  RunRequest: {
+    type: "object",
+    required: ["input"],
+    properties: {
+      input: {
+        oneOf: [
+          { type: "string", description: "Text input" },
+          {
+            type: "array",
+            description: "Multi-modal content parts",
+            items: {
+              oneOf: [
+                {
+                  type: "object",
+                  properties: {
+                    type: { type: "string", enum: ["text"] },
+                    text: { type: "string" }
+                  },
+                  required: ["type", "text"]
+                },
+                {
+                  type: "object",
+                  properties: {
+                    type: { type: "string", enum: ["image"] },
+                    data: { type: "string", description: "Base64 data or URL" },
+                    mimeType: { type: "string", enum: ["image/png", "image/jpeg", "image/gif", "image/webp"] }
+                  },
+                  required: ["type", "data"]
+                },
+                {
+                  type: "object",
+                  properties: {
+                    type: { type: "string", enum: ["audio"] },
+                    data: { type: "string", description: "Base64 data or URL" },
+                    mimeType: { type: "string" }
+                  },
+                  required: ["type", "data"]
+                },
+                {
+                  type: "object",
+                  properties: {
+                    type: { type: "string", enum: ["file"] },
+                    data: { type: "string", description: "Base64 data or URL" },
+                    mimeType: { type: "string" },
+                    fileName: { type: "string" }
+                  },
+                  required: ["type", "data"]
+                }
+              ]
+            }
+          }
+        ]
+      },
+      sessionId: { type: "string", description: "Session ID for conversation continuity" },
+      userId: { type: "string", description: "User identifier" }
+    }
+  },
+  MultipartRunRequest: {
+    type: "object",
+    properties: {
+      input: { type: "string", description: "Text input" },
+      sessionId: { type: "string" },
+      userId: { type: "string" },
+      files: {
+        type: "array",
+        items: { type: "string", format: "binary" },
+        description: "Files to include as multi-modal input (images, audio, documents)"
+      }
+    },
+    required: ["input"]
+  },
+  RunOutput: {
+    type: "object",
+    properties: {
+      text: { type: "string", description: "Agent response text" },
+      toolCalls: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            toolCallId: { type: "string" },
+            toolName: { type: "string" },
+            result: {}
+          }
+        }
+      },
+      usage: {
+        type: "object",
+        properties: {
+          promptTokens: { type: "number" },
+          completionTokens: { type: "number" },
+          totalTokens: { type: "number" }
+        }
+      },
+      structured: { description: "Parsed structured output (if schema is configured)" },
+      durationMs: { type: "number" }
+    }
+  },
+  StreamChunk: {
+    type: "object",
+    description: "Server-Sent Event data",
+    properties: {
+      type: { type: "string", enum: ["text", "tool_call_start", "tool_call_delta", "tool_call_end", "finish"] },
+      text: { type: "string" }
+    }
+  },
+  Error: {
+    type: "object",
+    properties: {
+      error: { type: "string" }
+    }
+  },
+  WorkflowRunRequest: {
+    type: "object",
+    properties: {
+      sessionId: { type: "string" },
+      userId: { type: "string" }
+    }
+  }
+};
+function buildAgentDescription(agent) {
+  const parts = [];
+  parts.push(`**Model:** \`${agent.providerId}/${agent.modelId}\``);
+  if (typeof agent.instructions === "string") {
+    const instr = agent.instructions.length > 200 ? agent.instructions.slice(0, 200) + "\u2026" : agent.instructions;
+    parts.push(`**Instructions:** ${instr}`);
+  }
+  if (agent.tools?.length > 0) {
+    const toolNames = agent.tools.map((t) => `\`${t.name}\``).join(", ");
+    parts.push(`**Tools:** ${toolNames}`);
+  }
+  if (agent.hasStructuredOutput) {
+    parts.push("**Structured Output:** Enabled");
+  }
+  return parts.join("\n\n");
+}
+function generateOpenAPISpec(routerOpts, swaggerOpts = {}) {
+  const prefix = swaggerOpts.routePrefix ?? "";
+  const providers = /* @__PURE__ */ new Set();
+  if (routerOpts.agents) {
+    for (const agent of Object.values(routerOpts.agents)) {
+      providers.add(agent.providerId ?? "unknown");
+    }
+  }
+  const securitySchemes = {};
+  const securityRequirements = [];
+  if (providers.has("openai")) {
+    securitySchemes.OpenAIKey = {
+      type: "apiKey",
+      in: "header",
+      name: "x-openai-api-key",
+      description: "OpenAI API key (sk-...)"
+    };
+    securityRequirements.push({ OpenAIKey: [] });
+  }
+  if (providers.has("google")) {
+    securitySchemes.GoogleKey = {
+      type: "apiKey",
+      in: "header",
+      name: "x-google-api-key",
+      description: "Google AI API key (AIza...)"
+    };
+    securityRequirements.push({ GoogleKey: [] });
+  }
+  if (providers.has("anthropic")) {
+    securitySchemes.AnthropicKey = {
+      type: "apiKey",
+      in: "header",
+      name: "x-anthropic-api-key",
+      description: "Anthropic API key (sk-ant-...)"
+    };
+    securityRequirements.push({ AnthropicKey: [] });
+  }
+  securitySchemes.GenericKey = {
+    type: "apiKey",
+    in: "header",
+    name: "x-api-key",
+    description: "Generic API key (used if provider-specific key is not set)"
+  };
+  const spec = {
+    openapi: "3.0.3",
+    info: {
+      title: swaggerOpts.title ?? "RadarOS API",
+      description: swaggerOpts.description ?? "Auto-generated API documentation for RadarOS agents, teams, and workflows.",
+      version: swaggerOpts.version ?? "1.0.0"
+    },
+    paths: {},
+    components: {
+      schemas: SCHEMAS,
+      securitySchemes
+    },
+    security: securityRequirements,
+    tags: []
+  };
+  if (swaggerOpts.servers) {
+    spec.servers = swaggerOpts.servers;
+  }
+  if (routerOpts.agents && Object.keys(routerOpts.agents).length > 0) {
+    spec.tags.push({ name: "Agents", description: "Agent endpoints for running and streaming AI agents" });
+    for (const [name, agent] of Object.entries(routerOpts.agents)) {
+      const agentDesc = buildAgentDescription(agent);
+      spec.paths[`${prefix}/agents/${name}/run`] = {
+        post: {
+          tags: ["Agents"],
+          summary: `Run agent: ${name}`,
+          description: agentDesc,
+          operationId: `runAgent_${name}`,
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/RunRequest" }
+              },
+              "multipart/form-data": {
+                schema: { $ref: "#/components/schemas/MultipartRunRequest" }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              description: "Agent run result",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/RunOutput" }
+                }
+              }
+            },
+            "400": {
+              description: "Bad request",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/Error" }
+                }
+              }
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/Error" }
+                }
+              }
+            }
+          }
+        }
+      };
+      spec.paths[`${prefix}/agents/${name}/stream`] = {
+        post: {
+          tags: ["Agents"],
+          summary: `Stream agent: ${name}`,
+          description: `Stream responses from agent **${name}** via Server-Sent Events.
+
+${agentDesc}`,
+          operationId: `streamAgent_${name}`,
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/RunRequest" }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              description: "SSE stream of agent chunks",
+              content: {
+                "text/event-stream": {
+                  schema: { $ref: "#/components/schemas/StreamChunk" }
+                }
+              }
+            },
+            "400": {
+              description: "Bad request",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/Error" }
+                }
+              }
+            }
+          }
+        }
+      };
+    }
+  }
+  if (routerOpts.teams && Object.keys(routerOpts.teams).length > 0) {
+    spec.tags.push({ name: "Teams", description: "Team endpoints for multi-agent coordination" });
+    for (const name of Object.keys(routerOpts.teams)) {
+      spec.paths[`${prefix}/teams/${name}/run`] = {
+        post: {
+          tags: ["Teams"],
+          summary: `Run team: ${name}`,
+          operationId: `runTeam_${name}`,
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/RunRequest" }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              description: "Team run result",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/RunOutput" }
+                }
+              }
+            },
+            "400": { description: "Bad request", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } },
+            "500": { description: "Internal server error", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } }
+          }
+        }
+      };
+      spec.paths[`${prefix}/teams/${name}/stream`] = {
+        post: {
+          tags: ["Teams"],
+          summary: `Stream team: ${name}`,
+          operationId: `streamTeam_${name}`,
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { $ref: "#/components/schemas/RunRequest" } } }
+          },
+          responses: {
+            "200": { description: "SSE stream", content: { "text/event-stream": { schema: { $ref: "#/components/schemas/StreamChunk" } } } },
+            "400": { description: "Bad request", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } }
+          }
+        }
+      };
+    }
+  }
+  if (routerOpts.workflows && Object.keys(routerOpts.workflows).length > 0) {
+    spec.tags.push({ name: "Workflows", description: "Workflow endpoints for step-based pipelines" });
+    for (const name of Object.keys(routerOpts.workflows)) {
+      spec.paths[`${prefix}/workflows/${name}/run`] = {
+        post: {
+          tags: ["Workflows"],
+          summary: `Run workflow: ${name}`,
+          operationId: `runWorkflow_${name}`,
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/WorkflowRunRequest" }
+              }
+            }
+          },
+          responses: {
+            "200": { description: "Workflow result", content: { "application/json": { schema: { type: "object" } } } },
+            "500": { description: "Internal server error", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } }
+          }
+        }
+      };
+    }
+  }
+  return spec;
+}
+function serveSwaggerUI(spec) {
+  let swaggerUiExpress;
+  try {
+    swaggerUiExpress = _require("swagger-ui-express");
+  } catch {
+    throw new Error(
+      "swagger-ui-express is required for Swagger UI. Install it: npm install swagger-ui-express"
+    );
+  }
+  return {
+    setup: swaggerUiExpress.setup(spec, {
+      customCss: ".swagger-ui .topbar { display: none }",
+      customSiteTitle: spec.info.title
+    }),
+    serve: swaggerUiExpress.serve
+  };
+}
+
+// src/express/file-upload.ts
+import { createRequire as createRequire2 } from "module";
+var _require2 = createRequire2(import.meta.url);
+var MIME_TO_PART_TYPE = {
+  "image/png": "image",
+  "image/jpeg": "image",
+  "image/jpg": "image",
+  "image/gif": "image",
+  "image/webp": "image",
+  "audio/mpeg": "audio",
+  "audio/mp3": "audio",
+  "audio/wav": "audio",
+  "audio/ogg": "audio",
+  "audio/webm": "audio",
+  "audio/flac": "audio",
+  "audio/aac": "audio",
+  "audio/mp4": "audio"
+};
+function getPartType(mimeType) {
+  return MIME_TO_PART_TYPE[mimeType] ?? "file";
+}
+function createFileUploadMiddleware(opts = {}) {
+  let multer;
+  try {
+    multer = _require2("multer");
+  } catch {
+    throw new Error(
+      "multer is required for file uploads. Install it: npm install multer"
+    );
+  }
+  const storage = multer.memoryStorage();
+  const upload = multer({
+    storage,
+    limits: {
+      fileSize: opts.maxFileSize ?? 50 * 1024 * 1024,
+      files: opts.maxFiles ?? 10
+    },
+    fileFilter: opts.allowedMimeTypes ? (_req, file, cb) => {
+      if (opts.allowedMimeTypes.includes(file.mimetype)) {
+        cb(null, true);
+      } else {
+        cb(new Error(`File type ${file.mimetype} is not allowed`));
+      }
+    } : void 0
+  });
+  return upload.array("files", opts.maxFiles ?? 10);
+}
+function filesToContentParts(files) {
+  return files.map((file) => {
+    const base64 = file.buffer.toString("base64");
+    const partType = getPartType(file.mimetype);
+    return {
+      type: partType,
+      data: base64,
+      mimeType: file.mimetype,
+      ...partType === "file" ? { fileName: file.originalname } : {}
+    };
+  });
+}
+function buildMultiModalInput(body, files) {
+  const textInput = body?.input;
+  if (!files || files.length === 0) {
+    return textInput;
+  }
+  const parts = [];
+  if (textInput) {
+    parts.push({ type: "text", text: textInput });
+  }
+  parts.push(...filesToContentParts(files));
+  return parts;
+}
+
+// src/express/router-factory.ts
+var _require3 = createRequire3(import.meta.url);
+var API_KEY_HEADERS = {
+  "x-openai-api-key": "openai",
+  "x-google-api-key": "google",
+  "x-anthropic-api-key": "anthropic",
+  "x-api-key": "_generic"
+};
+function extractApiKey(req, agent) {
+  for (const [header, provider] of Object.entries(API_KEY_HEADERS)) {
+    const value = req.headers[header];
+    if (value && (provider === "_generic" || provider === agent.providerId)) {
+      return value;
+    }
+  }
+  return req.body?.apiKey ?? void 0;
+}
+function createAgentRouter(opts) {
+  let express;
+  try {
+    express = _require3("express");
+  } catch {
+    throw new Error(
+      "express is required for createAgentRouter. Install it: npm install express"
+    );
+  }
+  const router = express.Router();
+  if (opts.middleware) {
+    for (const mw of opts.middleware) {
+      router.use(mw);
+    }
+  }
+  let uploadMiddleware = null;
+  if (opts.fileUpload) {
+    const uploadOpts = typeof opts.fileUpload === "object" ? opts.fileUpload : {};
+    uploadMiddleware = createFileUploadMiddleware(uploadOpts);
+  }
+  function withUpload(handler) {
+    if (!uploadMiddleware) return handler;
+    return (req, res, next) => {
+      uploadMiddleware(req, res, (err) => {
+        if (err) {
+          return res.status(400).json({ error: err.message });
+        }
+        handler(req, res).catch(next);
+      });
+    };
+  }
+  if (opts.swagger?.enabled) {
+    const spec = generateOpenAPISpec(opts, opts.swagger);
+    const docsPath = opts.swagger.docsPath ?? "/docs";
+    const specPath = opts.swagger.specPath ?? "/docs/spec.json";
+    router.get(specPath, (_req, res) => {
+      res.json(spec);
+    });
+    try {
+      const { serve, setup } = serveSwaggerUI(spec);
+      router.use(docsPath, serve, setup);
+    } catch (e) {
+      console.warn(`[radaros:transport] Swagger UI disabled: ${e.message}`);
+    }
+  }
+  if (opts.agents) {
+    for (const [name, agent] of Object.entries(opts.agents)) {
+      router.post(
+        `/agents/${name}/run`,
+        withUpload(async (req, res) => {
+          try {
+            const input = buildMultiModalInput(req.body, req.files);
+            if (!input) {
+              return res.status(400).json({ error: "input is required" });
+            }
+            const { sessionId, userId } = req.body ?? {};
+            const apiKey = extractApiKey(req, agent);
+            const result = await agent.run(input, { sessionId, userId, apiKey });
+            res.json(result);
+          } catch (error) {
+            res.status(500).json({ error: error.message });
+          }
+        })
+      );
+      router.post(`/agents/${name}/stream`, async (req, res) => {
+        try {
+          const { input, sessionId, userId } = req.body ?? {};
+          if (!input) {
+            return res.status(400).json({ error: "input is required" });
+          }
+          const apiKey = extractApiKey(req, agent);
+          res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive"
+          });
+          const stream = agent.stream(input, { sessionId, userId, apiKey });
+          for await (const chunk of stream) {
+            res.write(`data: ${JSON.stringify(chunk)}
+
+`);
+          }
+          res.write("data: [DONE]\n\n");
+          res.end();
+        } catch (error) {
+          if (!res.headersSent) {
+            res.status(500).json({ error: error.message });
+          } else {
+            res.write(
+              `data: ${JSON.stringify({ type: "error", error: error.message })}
+
+`
+            );
+            res.end();
+          }
+        }
+      });
+    }
+  }
+  if (opts.teams) {
+    for (const [name, team] of Object.entries(opts.teams)) {
+      router.post(`/teams/${name}/run`, async (req, res) => {
+        try {
+          const { input, sessionId, userId } = req.body ?? {};
+          if (!input) {
+            return res.status(400).json({ error: "input is required" });
+          }
+          const apiKey = req.headers["x-api-key"] ?? req.body?.apiKey;
+          const result = await team.run(input, { sessionId, userId, apiKey });
+          res.json(result);
+        } catch (error) {
+          res.status(500).json({ error: error.message });
+        }
+      });
+      router.post(`/teams/${name}/stream`, async (req, res) => {
+        try {
+          const { input, sessionId, userId } = req.body ?? {};
+          if (!input) {
+            return res.status(400).json({ error: "input is required" });
+          }
+          const apiKey = req.headers["x-api-key"] ?? req.body?.apiKey;
+          res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive"
+          });
+          const stream = team.stream(input, { sessionId, userId, apiKey });
+          for await (const chunk of stream) {
+            res.write(`data: ${JSON.stringify(chunk)}
+
+`);
+          }
+          res.write("data: [DONE]\n\n");
+          res.end();
+        } catch (error) {
+          if (!res.headersSent) {
+            res.status(500).json({ error: error.message });
+          } else {
+            res.write(
+              `data: ${JSON.stringify({ type: "error", error: error.message })}
+
+`
+            );
+            res.end();
+          }
+        }
+      });
+    }
+  }
+  if (opts.workflows) {
+    for (const [name, workflow] of Object.entries(opts.workflows)) {
+      router.post(`/workflows/${name}/run`, async (req, res) => {
+        try {
+          const { sessionId, userId } = req.body ?? {};
+          const result = await workflow.run({ sessionId, userId });
+          res.json(result);
+        } catch (error) {
+          res.status(500).json({ error: error.message });
+        }
+      });
+    }
+  }
+  return router;
+}
+
+// src/express/middleware.ts
+function errorHandler() {
+  return (err, _req, res, _next) => {
+    console.error("[radaros:transport] Error:", err.message);
+    res.status(err.statusCode ?? 500).json({
+      error: err.message ?? "Internal server error"
+    });
+  };
+}
+function requestLogger() {
+  return (req, _res, next) => {
+    console.log(`[radaros:transport] ${req.method} ${req.path}`);
+    next();
+  };
+}
+
+// src/socketio/gateway.ts
+function createAgentGateway(opts) {
+  const ns = opts.io.of(opts.namespace ?? "/radaros");
+  if (opts.authMiddleware) {
+    ns.use(opts.authMiddleware);
+  }
+  ns.on("connection", (socket) => {
+    socket.on(
+      "agent.run",
+      async (data) => {
+        const agent = opts.agents?.[data.name];
+        if (!agent) {
+          socket.emit("agent.error", {
+            error: `Agent "${data.name}" not found`
+          });
+          return;
+        }
+        try {
+          const apiKey = data.apiKey ?? socket.handshake?.auth?.apiKey;
+          const sessionId = data.sessionId ?? socket.id;
+          let fullText = "";
+          for await (const chunk of agent.stream(data.input, {
+            sessionId,
+            apiKey
+          })) {
+            if (chunk.type === "text") {
+              fullText += chunk.text;
+              socket.emit("agent.chunk", { chunk: chunk.text });
+            } else if (chunk.type === "tool_call_start") {
+              socket.emit("agent.tool.call", {
+                toolName: chunk.toolCall.name,
+                args: null
+              });
+            } else if (chunk.type === "tool_call_end") {
+              socket.emit("agent.tool.done", { toolCallId: chunk.toolCallId });
+            }
+          }
+          socket.emit("agent.done", { output: { text: fullText } });
+        } catch (error) {
+          socket.emit("agent.error", { error: error.message });
+        }
+      }
+    );
+    socket.on(
+      "team.run",
+      async (data) => {
+        const team = opts.teams?.[data.name];
+        if (!team) {
+          socket.emit("agent.error", {
+            error: `Team "${data.name}" not found`
+          });
+          return;
+        }
+        try {
+          const apiKey = data.apiKey ?? socket.handshake?.auth?.apiKey;
+          const result = await team.run(data.input, {
+            sessionId: data.sessionId ?? socket.id,
+            apiKey
+          });
+          socket.emit("agent.done", { output: result });
+        } catch (error) {
+          socket.emit("agent.error", { error: error.message });
+        }
+      }
+    );
+  });
+}
+export {
+  buildMultiModalInput,
+  createAgentGateway,
+  createAgentRouter,
+  createFileUploadMiddleware,
+  errorHandler,
+  generateOpenAPISpec,
+  requestLogger
+};