@copilotkit/runtime 1.57.3 → 1.58.0-canary.thread-id-propagation

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

@@ -1,179 +0,0 @@
-import express from "express";
-import type {
-  Request as ExpressRequest,
-  Response as ExpressResponse,
-  NextFunction,
-  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";
-
-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;
-}
-
-/**
- * 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 normalizedBase = normalizeBasePath(basePath);
-
-  const handler = createCopilotRuntimeHandler({
-    runtime,
-    basePath: normalizedBase,
-    mode,
-    cors: false, // CORS is handled at the Express middleware layer
-    hooks,
-  });
-
-  const nodeHandler = createExpressNodeHandler(handler);
-
-  const expressHandler = async (
-    req: ExpressRequest,
-    res: ExpressResponse,
-    next: NextFunction,
-  ) => {
-    try {
-      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(
-      new RegExp(`^${escapeRegExp(normalizedBase)}(\\/.*)?$`),
-      expressHandler,
-    );
-  }
-
-  return router;
-}
-
-function escapeRegExp(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-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;
-}

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

@@ -1,60 +0,0 @@
-import { Hono } 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;
-  /**
-   * 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;
-  /**
-   * Lifecycle hooks for request processing.
-   */
-  hooks?: CopilotRuntimeHooks;
-}
-
-/** @deprecated Use `createCopilotHonoHandler` with `mode: "single-route"` instead. */
-export function createCopilotEndpointSingleRoute({
-  runtime,
-  basePath,
-  cors: corsConfig,
-  hooks,
-}: CopilotSingleEndpointParams) {
-  const routePath = normalizePath(basePath);
-
-  const handler = createCopilotRuntimeHandler({
-    runtime,
-    basePath: routePath,
-    mode: "single-route",
-    cors: corsConfig ? toFetchCorsConfig(corsConfig) : true,
-    hooks,
-  });
-
-  const app = new Hono();
-
-  return app.basePath(routePath).all("*", async (c) => handler(c.req.raw));
-}
-
-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;
-}

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

@@ -1,89 +0,0 @@
-import { Hono } from "hono";
-import type { CopilotRuntimeLike } from "../core/runtime";
-import { createCopilotRuntimeHandler } from "../core/fetch-handler";
-import type { CopilotCorsConfig } from "../core/fetch-cors";
-import type { CopilotRuntimeHooks } from "../core/hooks";
-
-/**
- * CORS configuration for CopilotKit endpoints.
- * When using credentials (e.g., HTTP-only cookies), you must specify an explicit origin.
- */
-export interface CopilotEndpointCorsConfig {
-  /**
-   * Allowed origin(s) for CORS. Can be:
-   * - A string: exact origin (e.g., "https://myapp.com")
-   * - An array: list of allowed origins
-   * - A function: dynamic origin resolution
-   *
-   * Note: When credentials is true, origin cannot be "*"
-   */
-  origin:
-    | string
-    | string[]
-    | ((origin: string, c: any) => string | undefined | null);
-  /**
-   * Whether to allow credentials (cookies, HTTP authentication).
-   * When true, origin must be explicitly specified (not "*").
-   */
-  credentials?: boolean;
-}
-
-interface CopilotEndpointParams {
-  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";
-
-  /**
-   * 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;
-  /**
-   * Lifecycle hooks for request processing.
-   */
-  hooks?: CopilotRuntimeHooks;
-}
-/** @deprecated Use `createCopilotHonoHandler` instead. */
-export const createCopilotEndpoint = createCopilotHonoHandler;
-
-export function createCopilotHonoHandler({
-  runtime,
-  basePath,
-  mode = "multi-route",
-  cors: corsConfig,
-  hooks,
-}: CopilotEndpointParams) {
-  const handler = createCopilotRuntimeHandler({
-    runtime,
-    basePath,
-    mode,
-    cors: corsConfig ? toFetchCorsConfig(corsConfig) : true,
-    hooks,
-  });
-
-  const app = new Hono();
-
-  return app.basePath(basePath).all("*", async (c) => handler(c.req.raw));
-}
-
-/**
- * Convert Hono-specific CORS config to the fetch handler's CopilotCorsConfig.
- */
-export function toFetchCorsConfig(
-  config: CopilotEndpointCorsConfig,
-): CopilotCorsConfig {
-  const origin = config.origin;
-  return {
-    origin:
-      typeof origin === "function"
-        ? (reqOrigin: string) => origin(reqOrigin, undefined) ?? null
-        : origin,
-    credentials: config.credentials,
-  };
-}

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

@@ -1,4 +0,0 @@
-export * from "./hono";
-export * from "./hono-single";
-export * from "./express";
-export * from "./express-single";

package/src/v2/runtime/endpoints/node-fetch-handler.ts

@@ -1,48 +0,0 @@
-/**
- * Generic Node ↔ Fetch bridge for CopilotKit runtime.
- *
- * Wraps a `CopilotRuntimeFetchHandler` as a Node HTTP handler using
- * `@remix-run/node-fetch-server` for reliable streaming and conversion.
- *
- * @example
- * ```typescript
- * import { createServer } from "node:http";
- * import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
- * import { createCopilotNodeHandler } from "@copilotkit/runtime/v2/node";
- *
- * const handler = createCopilotRuntimeHandler({ runtime, basePath: "/api/copilotkit", cors: true });
- * const nodeHandler = createCopilotNodeHandler(handler);
- * createServer(nodeHandler).listen(3000);
- * ```
- */
-
-import type { IncomingMessage, ServerResponse } from "node:http";
-import { createRequest, sendResponse } from "@remix-run/node-fetch-server";
-import type { CopilotRuntimeFetchHandler } from "../core/fetch-handler";
-import { logger } from "@copilotkit/shared";
-
-export type NodeFetchHandler = (
-  req: IncomingMessage,
-  res: ServerResponse,
-) => Promise<void>;
-
-export function createCopilotNodeHandler(
-  handler: CopilotRuntimeFetchHandler,
-): NodeFetchHandler {
-  return async (req: IncomingMessage, res: ServerResponse) => {
-    try {
-      const fetchReq = createRequest(req, res);
-      const fetchRes = await handler(fetchReq);
-      await sendResponse(res, fetchRes);
-    } catch (err: unknown) {
-      logger.error({ err }, "Error in Node fetch handler");
-      if (!res.headersSent) {
-        res.statusCode = 500;
-        res.end("Internal Server Error");
-      }
-    }
-  };
-}
-
-/** @deprecated Use `createCopilotNodeHandler` instead. */
-export const createNodeFetchHandler = createCopilotNodeHandler;

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

@@ -1,28 +0,0 @@
-import { createCopilotRuntimeHandler } from "../core/fetch-handler";
-import type { CopilotRuntimeHandlerOptions } from "../core/fetch-handler";
-import { createCopilotNodeHandler } from "./node-fetch-handler";
-import type { NodeFetchHandler } from "./node-fetch-handler";
-/**
- * Convenience wrapper for creating a Node.js HTTP request listener
- * from CopilotKit runtime handler options.
- *
- * @example
- * ```typescript
- * import { createServer } from "node:http";
- * import { CopilotRuntime } from "@copilotkit/runtime/v2";
- * import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
- *
- * const listener = createCopilotNodeListener({
- *   runtime: new CopilotRuntime({ agents: { ... } }),
- *   basePath: "/api/copilotkit",
- *   cors: true,
- * });
- * createServer(listener).listen(3000);
- * ```
- */
-export function createCopilotNodeListener(
-  options: CopilotRuntimeHandlerOptions,
-): NodeFetchHandler {
-  const handler = createCopilotRuntimeHandler(options);
-  return createCopilotNodeHandler(handler);
-}

package/src/v2/runtime/endpoints/single-route-helpers.ts

@@ -1,125 +0,0 @@
-const METHOD_NAMES = [
-  "agent/run",
-  "agent/connect",
-  "agent/stop",
-  "info",
-  "transcribe",
-] as const;
-
-export type EndpointMethod = (typeof METHOD_NAMES)[number];
-
-interface JsonEnvelope {
-  method?: string;
-  params?: Record<string, unknown>;
-  body?: unknown;
-}
-
-export interface MethodCall {
-  method: EndpointMethod;
-  params?: Record<string, unknown>;
-  body?: unknown;
-}
-
-export async function parseMethodCall(request: Request): Promise<MethodCall> {
-  const contentType = request.headers.get("content-type") || "";
-
-  if (!contentType.includes("application/json")) {
-    throw createResponseError(
-      "Single-route endpoint expects JSON payloads",
-      415,
-    );
-  }
-
-  let jsonEnvelope: JsonEnvelope;
-  try {
-    jsonEnvelope = (await request.clone().json()) as JsonEnvelope;
-  } catch (error) {
-    throw createResponseError("Invalid JSON payload", 400);
-  }
-
-  const method = validateMethod(jsonEnvelope.method);
-
-  return {
-    method,
-    params: jsonEnvelope.params,
-    body: jsonEnvelope.body,
-  };
-}
-
-export function expectString(
-  params: Record<string, unknown> | undefined,
-  key: string,
-): string {
-  const value = params?.[key];
-  if (typeof value === "string" && value.trim().length > 0) {
-    return value;
-  }
-
-  throw createResponseError(`Missing or invalid parameter '${key}'`, 400);
-}
-
-export function createJsonRequest(base: Request, body: unknown): Request {
-  if (body === undefined || body === null) {
-    throw createResponseError("Missing request body for JSON handler", 400);
-  }
-
-  const headers = new Headers(base.headers);
-  headers.set("content-type", "application/json");
-  headers.delete("content-length");
-
-  const serializedBody = serializeJsonBody(body);
-
-  return new Request(base.url, {
-    method: "POST",
-    headers,
-    body: serializedBody,
-    signal: base.signal,
-  });
-}
-
-export function createResponseError(message: string, status: number): Response {
-  return new Response(
-    JSON.stringify({
-      error: "invalid_request",
-      message,
-    }),
-    {
-      status,
-      headers: {
-        "Content-Type": "application/json",
-      },
-    },
-  );
-}
-
-function validateMethod(method: string | undefined): EndpointMethod {
-  if (!method) {
-    throw createResponseError("Missing method field", 400);
-  }
-
-  if ((METHOD_NAMES as readonly string[]).includes(method)) {
-    return method as EndpointMethod;
-  }
-
-  throw createResponseError(`Unsupported method '${method}'`, 400);
-}
-
-function serializeJsonBody(body: unknown): BodyInit {
-  if (typeof body === "string") {
-    return body;
-  }
-
-  if (
-    body instanceof Blob ||
-    body instanceof ArrayBuffer ||
-    body instanceof Uint8Array
-  ) {
-    return body;
-  }
-
-  if (body instanceof FormData || body instanceof URLSearchParams) {
-    return body;
-  }
-
-  return JSON.stringify(body);
-}

package/src/v2/runtime/express.ts

@@ -1,2 +0,0 @@
-export * from "./endpoints/express";
-export * from "./endpoints/express-single";