@copilotkit/runtime 1.54.1 → 1.55.0-next.7

package/src/v2/runtime/endpoints/express-utils.ts

@@ -0,0 +1,182 @@
+import type {
+  Request as ExpressRequest,
+  Response as ExpressResponse,
+} from "express";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream";
+import { promisify } from "node:util";
+import { logger } from "@copilotkit/shared";
+
+const streamPipeline = promisify(pipeline);
+
+const METHODS_WITHOUT_BODY = new Set(["GET", "HEAD"]);
+
+export function createFetchRequestFromExpress(req: ExpressRequest): Request {
+  const method = req.method?.toUpperCase() ?? "GET";
+  const origin = buildOrigin(req);
+  const url = `${origin}${req.originalUrl ?? req.url ?? ""}`;
+
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      value.forEach((v) => headers.append(key, v));
+    } else {
+      headers.set(key, value);
+    }
+  }
+
+  const init: RequestInit & { duplex?: "half" } = {
+    method,
+    headers,
+  };
+
+  const hasParsedBody = req.body !== undefined && req.body !== null;
+  const streamConsumed = isStreamConsumed(req, hasParsedBody);
+
+  if (!METHODS_WITHOUT_BODY.has(method)) {
+    const canStreamBody = req.readable !== false && !streamConsumed;
+
+    if (canStreamBody) {
+      init.body = Readable.toWeb(req) as unknown as BodyInit;
+      init.duplex = "half";
+    } else if (hasParsedBody) {
+      const { body, contentType } = synthesizeBody(req.body);
+      if (contentType) {
+        headers.set("content-type", contentType);
+      }
+      headers.delete("content-length");
+      if (body !== undefined) {
+        init.body = body;
+      }
+      logger.info(
+        {
+          url,
+          method,
+          readable: req.readable,
+          readableEnded: req.readableEnded,
+          complete: req.complete,
+        },
+        "Express request stream already consumed; synthesized body from parsed content",
+      );
+    } else {
+      headers.delete("content-length");
+      logger.warn(
+        { url, method },
+        "Request stream already consumed but no body was available; sending empty body",
+      );
+    }
+  }
+
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  req.on("aborted", abort);
+  req.on("error", abort);
+  req.on("close", () => {
+    if (req.aborted) {
+      abort();
+    }
+  });
+  init.signal = controller.signal;
+
+  try {
+    return new Request(url, init);
+  } catch (error) {
+    if (error instanceof TypeError && /disturbed|locked/i.test(error.message)) {
+      // Fallback to synthesized/empty body when the stream was already consumed.
+      headers.delete("content-length");
+      delete init.duplex;
+
+      if (hasParsedBody) {
+        const { body, contentType } = synthesizeBody(req.body);
+        if (contentType) {
+          headers.set("content-type", contentType);
+        }
+        init.body = body;
+        logger.info(
+          { url, method },
+          "Request stream disturbed while constructing Request; reused parsed body",
+        );
+      } else {
+        init.body = undefined;
+        logger.warn(
+          { url, method },
+          "Request stream was disturbed; falling back to empty body",
+        );
+      }
+
+      return new Request(url, init);
+    }
+    throw error;
+  }
+}
+
+export async function sendFetchResponse(
+  res: ExpressResponse,
+  response: Response,
+): Promise<void> {
+  res.status(response.status);
+
+  response.headers.forEach((value, key) => {
+    if (key.toLowerCase() === "content-length" && response.body !== null) {
+      return;
+    }
+    res.setHeader(key, value);
+  });
+
+  if (!response.body) {
+    res.end();
+    return;
+  }
+
+  const nodeStream = Readable.fromWeb(response.body as any);
+  try {
+    await streamPipeline(nodeStream, res);
+  } catch (error) {
+    res.destroy(error as Error);
+    throw error;
+  }
+}
+
+function buildOrigin(req: ExpressRequest): string {
+  const protocol = req.protocol || (req.secure ? "https" : "http");
+  const host = req.get("host") ?? "localhost";
+  return `${protocol}://${host}`;
+}
+
+function isStreamConsumed(
+  req: ExpressRequest,
+  hasParsedBody: boolean,
+): boolean {
+  const state = (
+    req as unknown as {
+      _readableState?: { ended?: boolean; endEmitted?: boolean };
+    }
+  )._readableState;
+  return Boolean(
+    hasParsedBody ||
+    req.readableEnded ||
+    req.complete ||
+    state?.ended ||
+    state?.endEmitted,
+  );
+}
+
+function synthesizeBody(body: unknown): {
+  body?: BodyInit;
+  contentType?: string;
+} {
+  if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
+    return { body };
+  }
+
+  if (typeof body === "string") {
+    return { body };
+  }
+
+  if (typeof body === "object" && body !== undefined) {
+    return { body: JSON.stringify(body), contentType: "application/json" };
+  }
+
+  return {};
+}

package/src/v2/runtime/endpoints/express.ts

@@ -0,0 +1,275 @@
+import express from "express";
+import type {
+  Request as ExpressRequest,
+  Response as ExpressResponse,
+  NextFunction,
+  Router,
+} from "express";
+import cors from "cors";
+
+import { CopilotRuntimeLike } from "../runtime";
+import { telemetry } from "../telemetry";
+import { handleRunAgent } from "../handlers/handle-run";
+import { handleConnectAgent } from "../handlers/handle-connect";
+import { handleStopAgent } from "../handlers/handle-stop";
+import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
+import { handleTranscribe } from "../handlers/handle-transcribe";
+import {
+  handleListThreads,
+  handleSubscribeToThreads,
+  handleUpdateThread,
+  handleArchiveThread,
+  handleDeleteThread,
+} from "../handlers/handle-threads";
+import { logger, getLicenseWarningHeader } from "@copilotkit/shared";
+import {
+  callBeforeRequestMiddleware,
+  callAfterRequestMiddleware,
+} from "../middleware";
+import {
+  createFetchRequestFromExpress,
+  sendFetchResponse,
+} from "./express-utils";
+
+interface CopilotExpressEndpointParams {
+  runtime: CopilotRuntimeLike;
+  basePath: string;
+}
+
+export function createCopilotEndpointExpress({
+  runtime,
+  basePath,
+}: CopilotExpressEndpointParams): Router {
+  const router = express.Router();
+  const normalizedBase = normalizeBasePath(basePath);
+
+  // Fire instance_created telemetry - resolve agents if needed
+  Promise.resolve(runtime.agents)
+    .then((agents) => {
+      telemetry.capture("oss.runtime.instance_created", {
+        actionsAmount: 0,
+        endpointTypes: [],
+        endpointsAmount: 0,
+        agentsAmount: Object.keys(agents).length,
+        "cloud.api_key_provided": false,
+      });
+    })
+    .catch(() => {
+      // Silently fail - telemetry should not break the application
+    });
+
+  router.use(
+    cors({
+      origin: "*",
+      methods: ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH", "OPTIONS"],
+      allowedHeaders: ["*"],
+    }),
+  );
+
+  router.post(
+    joinPath(normalizedBase, "/agent/:agentId/run"),
+    createRouteHandler(runtime, async ({ request, req }) => {
+      const agentId = req.params.agentId as string;
+      return handleRunAgent({ runtime, request, agentId });
+    }),
+  );
+
+  router.post(
+    joinPath(normalizedBase, "/agent/:agentId/connect"),
+    createRouteHandler(runtime, async ({ request, req }) => {
+      const agentId = req.params.agentId as string;
+      return handleConnectAgent({ runtime, request, agentId });
+    }),
+  );
+
+  router.post(
+    joinPath(normalizedBase, "/agent/:agentId/stop/:threadId"),
+    createRouteHandler(runtime, async ({ request, req }) => {
+      const agentId = req.params.agentId as string;
+      const threadId = req.params.threadId as string;
+      return handleStopAgent({ runtime, request, agentId, threadId });
+    }),
+  );
+
+  router.get(
+    joinPath(normalizedBase, "/info"),
+    createRouteHandler(runtime, async ({ request }) => {
+      return handleGetRuntimeInfo({ runtime, request });
+    }),
+  );
+
+  router.post(
+    joinPath(normalizedBase, "/transcribe"),
+    createRouteHandler(runtime, async ({ request }) => {
+      return handleTranscribe({ runtime, request });
+    }),
+  );
+
+  router.get(
+    joinPath(normalizedBase, "/threads"),
+    createRouteHandler(runtime, async ({ request }) => {
+      return handleListThreads({ runtime, request });
+    }),
+  );
+
+  router.post(
+    joinPath(normalizedBase, "/threads/subscribe"),
+    createRouteHandler(runtime, async ({ request }) => {
+      return handleSubscribeToThreads({ runtime, request });
+    }),
+  );
+
+  router.patch(
+    joinPath(normalizedBase, "/threads/:threadId"),
+    createRouteHandler(runtime, async ({ request, req }) => {
+      const threadId = req.params.threadId as string;
+      return handleUpdateThread({ runtime, request, threadId });
+    }),
+  );
+
+  router.post(
+    joinPath(normalizedBase, "/threads/:threadId/archive"),
+    createRouteHandler(runtime, async ({ request, req }) => {
+      const threadId = req.params.threadId as string;
+      return handleArchiveThread({ runtime, request, threadId });
+    }),
+  );
+
+  router.delete(
+    joinPath(normalizedBase, "/threads/:threadId"),
+    createRouteHandler(runtime, async ({ request, req }) => {
+      const threadId = req.params.threadId as string;
+      return handleDeleteThread({ runtime, request, threadId });
+    }),
+  );
+
+  router.use(joinPath(normalizedBase, "*"), (req, res) => {
+    res.status(404).json({ error: "Not found" });
+  });
+
+  return router;
+}
+
+type RouteHandlerContext = {
+  request: Request;
+  req: ExpressRequest;
+};
+
+type RouteHandlerFactory = (ctx: RouteHandlerContext) => Promise<Response>;
+
+function createRouteHandler(
+  runtime: CopilotRuntimeLike,
+  factory: RouteHandlerFactory,
+) {
+  return async (
+    req: ExpressRequest,
+    res: ExpressResponse,
+    next: NextFunction,
+  ) => {
+    const path = req.originalUrl ?? req.path;
+    let request = createFetchRequestFromExpress(req);
+
+    const warning = getLicenseWarningHeader(runtime.licenseChecker);
+    if (warning) res.setHeader(warning.key, warning.value);
+
+    try {
+      const maybeModifiedRequest = await callBeforeRequestMiddleware({
+        runtime,
+        request,
+        path,
+      });
+      if (maybeModifiedRequest) {
+        request = maybeModifiedRequest;
+      }
+    } catch (error) {
+      logger.error(
+        { err: error, url: request.url, path },
+        "Error running before request middleware",
+      );
+      if (error instanceof Response) {
+        try {
+          await sendFetchResponse(res, error);
+        } catch (streamError) {
+          next(streamError);
+        }
+        return;
+      }
+      next(error);
+      return;
+    }
+
+    try {
+      const response = await factory({ request, req });
+      const responseForMiddleware = response.clone();
+      await sendFetchResponse(res, response);
+      callAfterRequestMiddleware({
+        runtime,
+        response: responseForMiddleware,
+        path,
+      }).catch((error) => {
+        logger.error(
+          { err: error, url: req.originalUrl ?? req.url, path },
+          "Error running after request middleware",
+        );
+      });
+    } catch (error) {
+      if (error instanceof Response) {
+        const errorResponseForMiddleware = error.clone();
+        try {
+          await sendFetchResponse(res, error);
+        } catch (streamError) {
+          next(streamError);
+          return;
+        }
+        callAfterRequestMiddleware({
+          runtime,
+          response: errorResponseForMiddleware,
+          path,
+        }).catch((mwError) => {
+          logger.error(
+            { err: mwError, url: req.originalUrl ?? req.url, path },
+            "Error running after request middleware",
+          );
+        });
+        return;
+      }
+      logger.error(
+        { err: error, url: request.url, path },
+        "Error running request handler",
+      );
+      next(error);
+    }
+  };
+}
+
+function normalizeBasePath(path: string): string {
+  if (!path) {
+    throw new Error("basePath must be provided for Express endpoint");
+  }
+
+  if (!path.startsWith("/")) {
+    return `/${path}`;
+  }
+
+  if (path.length > 1 && path.endsWith("/")) {
+    return path.slice(0, -1);
+  }
+
+  return path;
+}
+
+function joinPath(basePath: string, suffix: string): string {
+  if (basePath === "/") {
+    return suffix.startsWith("/") ? suffix : `/${suffix}`;
+  }
+
+  if (!suffix) {
+    return basePath;
+  }
+
+  if (suffix === "*") {
+    return `${basePath}/*`;
+  }
+
+  return `${basePath}${suffix.startsWith("/") ? suffix : `/${suffix}`}`;
+}

package/src/v2/runtime/endpoints/hono-single.ts

@@ -0,0 +1,212 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+import { CopilotRuntimeLike } from "../runtime";
+import { handleRunAgent } from "../handlers/handle-run";
+import { handleConnectAgent } from "../handlers/handle-connect";
+import { handleStopAgent } from "../handlers/handle-stop";
+import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
+import { handleTranscribe } from "../handlers/handle-transcribe";
+import { logger } from "@copilotkit/shared";
+import {
+  callBeforeRequestMiddleware,
+  callAfterRequestMiddleware,
+} from "../middleware";
+import {
+  createJsonRequest,
+  expectString,
+  MethodCall,
+  parseMethodCall,
+} from "./single-route-helpers";
+
+import { CopilotEndpointCorsConfig } from "./hono";
+
+interface CopilotSingleEndpointParams {
+  runtime: CopilotRuntimeLike;
+  /**
+   * Absolute path at which to mount the single-route endpoint (e.g. "/api/copilotkit").
+   */
+  basePath: string;
+  /**
+   * Optional CORS configuration. When not provided, defaults to allowing all origins without credentials.
+   * To support HTTP-only cookies, provide cors config with credentials: true and explicit origin.
+   */
+  cors?: CopilotEndpointCorsConfig;
+}
+
+type CopilotEndpointContext = {
+  Variables: {
+    modifiedRequest?: Request;
+  };
+};
+
+export function createCopilotEndpointSingleRoute({
+  runtime,
+  basePath,
+  cors: corsConfig,
+}: CopilotSingleEndpointParams) {
+  const app = new Hono<CopilotEndpointContext>();
+  const routePath = normalizePath(basePath);
+
+  return app
+    .basePath(routePath)
+    .use(
+      "*",
+      cors({
+        origin: corsConfig?.origin ?? "*",
+        allowMethods: [
+          "GET",
+          "HEAD",
+          "PUT",
+          "POST",
+          "DELETE",
+          "PATCH",
+          "OPTIONS",
+        ],
+        allowHeaders: ["*"],
+        credentials: corsConfig?.credentials ?? false,
+      }),
+    )
+    .use("*", async (c, next) => {
+      const request = c.req.raw;
+      const path = c.req.path;
+
+      try {
+        const maybeModifiedRequest = await callBeforeRequestMiddleware({
+          runtime,
+          request,
+          path,
+        });
+        if (maybeModifiedRequest) {
+          c.set("modifiedRequest", maybeModifiedRequest);
+        }
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path },
+          "Error running before request middleware",
+        );
+        if (error instanceof Response) {
+          return error;
+        }
+        throw error;
+      }
+
+      await next();
+    })
+    .use("*", async (c, next) => {
+      await next();
+
+      const response = c.res.clone();
+      const path = c.req.path;
+
+      callAfterRequestMiddleware({
+        runtime,
+        response,
+        path,
+      }).catch((error) => {
+        logger.error(
+          { err: error, url: c.req.url, path },
+          "Error running after request middleware",
+        );
+      });
+    })
+    .post("/", async (c) => {
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      let methodCall: MethodCall;
+      try {
+        methodCall = await parseMethodCall(request);
+      } catch (error) {
+        if (error instanceof Response) {
+          logger.warn({ url: request.url }, "Invalid single-route payload");
+          return error;
+        }
+        logger.warn(
+          { err: error, url: request.url },
+          "Invalid single-route payload",
+        );
+        return c.json(
+          {
+            error: "invalid_request",
+            message:
+              error instanceof Error
+                ? error.message
+                : "Invalid request payload",
+          },
+          400,
+        );
+      }
+
+      try {
+        switch (methodCall.method) {
+          case "agent/run": {
+            const agentId = expectString(methodCall.params, "agentId");
+            const handlerRequest = createJsonRequest(request, methodCall.body);
+            return await handleRunAgent({
+              runtime,
+              request: handlerRequest,
+              agentId,
+            });
+          }
+          case "agent/connect": {
+            const agentId = expectString(methodCall.params, "agentId");
+            const handlerRequest = createJsonRequest(request, methodCall.body);
+            return await handleConnectAgent({
+              runtime,
+              request: handlerRequest,
+              agentId,
+            });
+          }
+          case "agent/stop": {
+            const agentId = expectString(methodCall.params, "agentId");
+            const threadId = expectString(methodCall.params, "threadId");
+            return await handleStopAgent({
+              runtime,
+              request,
+              agentId,
+              threadId,
+            });
+          }
+          case "info": {
+            return await handleGetRuntimeInfo({ runtime, request });
+          }
+          case "transcribe": {
+            const handlerRequest = createJsonRequest(request, methodCall.body);
+            return await handleTranscribe({ runtime, request: handlerRequest });
+          }
+          default: {
+            const exhaustiveCheck: never = methodCall.method;
+            return exhaustiveCheck;
+          }
+        }
+      } catch (error) {
+        if (error instanceof Response) {
+          return error;
+        }
+        logger.error(
+          { err: error, url: request.url, method: methodCall.method },
+          "Error running single-route handler",
+        );
+        throw error;
+      }
+    })
+    .notFound((c) => {
+      return c.json({ error: "Not found" }, 404);
+    });
+}
+
+function normalizePath(path: string): string {
+  if (!path) {
+    throw new Error("basePath must be provided for single-route endpoint");
+  }
+
+  if (!path.startsWith("/")) {
+    return `/${path}`;
+  }
+
+  if (path.length > 1 && path.endsWith("/")) {
+    return path.slice(0, -1);
+  }
+
+  return path;
+}