@copilotkit/runtime 1.55.0-next.8 → 1.55.0

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

@@ -6,240 +6,154 @@ import type {
   Router,
 } from "express";
 import cors from "cors";
+import type { CorsOptions } from "cors";
+import type { CopilotRuntimeLike } from "../core/runtime";
+import { createCopilotRuntimeHandler } from "../core/fetch-handler";
+import { createExpressNodeHandler } from "./express-fetch-bridge";
+import type { CopilotRuntimeHooks } from "../core/hooks";
 
-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 {
+export interface CopilotExpressEndpointParams {
   runtime: CopilotRuntimeLike;
   basePath: string;
+
+  /**
+   * Endpoint mode.
+   * - `"multi-route"` (default): separate routes for each operation
+   * - `"single-route"`: single POST endpoint with JSON envelope dispatch
+   */
+  mode?: "multi-route" | "single-route";
+
+  /**
+   * CORS configuration for the Express router.
+   * - `true` (default): permissive CORS (`origin: "*"`, all methods, all headers).
+   * - `false`: no CORS middleware is applied — handle it yourself.
+   * - object: passed directly to the Express `cors()` middleware.
+   */
+  cors?: boolean | CorsOptions;
+
+  /**
+   * Lifecycle hooks for request processing.
+   */
+  hooks?: CopilotRuntimeHooks;
 }
 
-export function createCopilotEndpointExpress({
+/**
+ * Creates an Express router that serves the CopilotKit runtime.
+ *
+ * In **multi-route** mode (default) the router exposes:
+ * - `GET  {basePath}/info` — runtime info
+ * - `POST {basePath}/agent/:agentId/run` — start an agent run
+ * - `POST {basePath}/agent/:agentId/connect` — connect to an agent run
+ * - `POST {basePath}/agent/:agentId/stop/:threadId` — stop an agent run
+ * - `POST {basePath}/transcribe` — transcribe audio
+ *
+ * In **single-route** mode a single `POST {basePath}` endpoint accepts a JSON
+ * envelope `{ method, params, body }` and dispatches to the appropriate handler.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { CopilotRuntime } from "@copilotkit/runtime/v2";
+ * import { createCopilotExpressHandler } from "@copilotkit/runtime/v2/express";
+ *
+ * const runtime = new CopilotRuntime({
+ *   agents: { default: new BuiltInAgent({ model: "openai/gpt-4o-mini" }) },
+ * });
+ *
+ * const app = express();
+ * app.use(createCopilotExpressHandler({
+ *   runtime,
+ *   basePath: "/api/copilotkit",
+ *   cors: true,
+ * }));
+ * app.listen(4000);
+ * ```
+ *
+ * @example Single-route mode with lifecycle hooks
+ * ```typescript
+ * app.use(createCopilotExpressHandler({
+ *   runtime,
+ *   basePath: "/api/copilotkit",
+ *   mode: "single-route",
+ *   hooks: {
+ *     onRequest: ({ request }) => {
+ *       if (!request.headers.get("authorization")) {
+ *         throw new Response("Unauthorized", { status: 401 });
+ *       }
+ *     },
+ *   },
+ * }));
+ * ```
+ */
+/** @deprecated Use `createCopilotExpressHandler` instead. */
+export { createCopilotExpressHandler as createCopilotEndpointExpress };
+
+export function createCopilotExpressHandler({
   runtime,
   basePath,
+  mode = "multi-route",
+  cors: corsOption = true,
+  hooks,
 }: 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" });
+  const handler = createCopilotRuntimeHandler({
+    runtime,
+    basePath: normalizedBase,
+    mode,
+    cors: false, // CORS is handled at the Express middleware layer
+    hooks,
   });
 
-  return router;
-}
-
-type RouteHandlerContext = {
-  request: Request;
-  req: ExpressRequest;
-};
+  const nodeHandler = createExpressNodeHandler(handler);
 
-type RouteHandlerFactory = (ctx: RouteHandlerContext) => Promise<Response>;
-
-function createRouteHandler(
-  runtime: CopilotRuntimeLike,
-  factory: RouteHandlerFactory,
-) {
-  return async (
+  const expressHandler = 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);
+      await nodeHandler(req, res);
+    } catch (err) {
+      next(err);
     }
   };
+
+  const router = express.Router();
+
+  // CORS middleware
+  if (corsOption) {
+    const corsConfig: CorsOptions =
+      corsOption === true
+        ? {
+            origin: "*",
+            methods: [
+              "GET",
+              "HEAD",
+              "PUT",
+              "POST",
+              "DELETE",
+              "PATCH",
+              "OPTIONS",
+            ],
+            allowedHeaders: ["*"],
+          }
+        : corsOption;
+    router.use(cors(corsConfig));
+  }
+
+  // Route mounting
+  if (mode === "single-route") {
+    router.post(normalizedBase, expressHandler);
+    router.options(normalizedBase, expressHandler);
+  } else if (normalizedBase === "/") {
+    router.all("*", expressHandler);
+  } else {
+    router.all(`${normalizedBase}/*`, expressHandler);
+    router.all(normalizedBase, expressHandler);
+  }
+
+  return router;
 }
 
 function normalizeBasePath(path: string): string {
@@ -257,19 +171,3 @@ function normalizeBasePath(path: string): string {
 
   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

@@ -1,25 +1,8 @@
 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";
+import type { CopilotRuntimeLike } from "../core/runtime";
+import { createCopilotRuntimeHandler } from "../core/fetch-handler";
+import type { CopilotRuntimeHooks } from "../core/hooks";
+import { CopilotEndpointCorsConfig, toFetchCorsConfig } from "./hono";
 
 interface CopilotSingleEndpointParams {
   runtime: CopilotRuntimeLike;
@@ -32,167 +15,32 @@ interface CopilotSingleEndpointParams {
    * To support HTTP-only cookies, provide cors config with credentials: true and explicit origin.
    */
   cors?: CopilotEndpointCorsConfig;
+  /**
+   * Lifecycle hooks for request processing.
+   */
+  hooks?: CopilotRuntimeHooks;
 }
 
-type CopilotEndpointContext = {
-  Variables: {
-    modifiedRequest?: Request;
-  };
-};
-
+/** @deprecated Use `createCopilotHonoHandler` with `mode: "single-route"` instead. */
 export function createCopilotEndpointSingleRoute({
   runtime,
   basePath,
   cors: corsConfig,
+  hooks,
 }: 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;
+  const handler = createCopilotRuntimeHandler({
+    runtime,
+    basePath: routePath,
+    mode: "single-route",
+    cors: corsConfig ? toFetchCorsConfig(corsConfig) : true,
+    hooks,
+  });
 
-      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,
-        );
-      }
+  const app = new Hono();
 
-      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);
-    });
+  return app.basePath(routePath).all("*", async (c) => handler(c.req.raw));
 }
 
 function normalizePath(path: string): string {