@copilotkit/runtime 1.55.0-next.9 → 1.55.0

package/src/v2/runtime/core/fetch-handler.ts

@@ -0,0 +1,415 @@
+/**
+ * Framework-agnostic CopilotKit runtime handler.
+ *
+ * Returns a pure `(Request) => Promise<Response>` function that can be used
+ * directly with Bun, Deno, Cloudflare Workers, Next.js App Router, or any
+ * Fetch-native runtime — no framework dependency required.
+ *
+ * @example
+ * ```typescript
+ * import { CopilotRuntime, createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
+ *
+ * const handler = createCopilotRuntimeHandler({
+ *   runtime: new CopilotRuntime({ agents: { ... } }),
+ *   basePath: "/api/copilotkit",
+ *   cors: true,
+ * });
+ *
+ * // Bun
+ * Bun.serve({ fetch: handler });
+ *
+ * // Deno
+ * Deno.serve(handler);
+ *
+ * // Cloudflare Workers
+ * export default { fetch: handler };
+ * ```
+ */
+
+import type { CopilotRuntimeLike } from "./runtime";
+import type { CopilotRuntimeHooks, RouteInfo, HookContext } from "./hooks";
+import {
+  runOnRequest,
+  runOnBeforeHandler,
+  runOnResponse,
+  runOnError,
+} from "./hooks";
+import type { CopilotCorsConfig } from "./fetch-cors";
+import { handleCors, addCorsHeaders } from "./fetch-cors";
+import { matchRoute } from "./fetch-router";
+import {
+  callBeforeRequestMiddleware,
+  callAfterRequestMiddleware,
+} from "./middleware";
+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 {
+  parseMethodCall,
+  createJsonRequest,
+  expectString,
+  type MethodCall,
+} from "../endpoints/single-route-helpers";
+import { logger } from "@copilotkit/shared";
+
+/* ------------------------------------------------------------------------------------------------
+ * Public types
+ * --------------------------------------------------------------------------------------------- */
+
+export interface CopilotRuntimeHandlerOptions {
+  runtime: CopilotRuntimeLike;
+
+  /**
+   * Optional base path for routing.
+   *
+   * When provided: strict prefix stripping. The handler strips this prefix from the
+   * URL pathname and matches the remainder against known routes.
+   *
+   * When omitted: suffix matching. The handler matches known route patterns as
+   * suffixes of the URL pathname.
+   */
+  basePath?: string;
+
+  /**
+   * Endpoint mode:
+   * - "multi-route" (default): Routes like POST /agent/:agentId/run, GET /info, etc.
+   * - "single-route": Single POST endpoint with JSON envelope { method, params, body }
+   */
+  mode?: "multi-route" | "single-route";
+
+  /**
+   * Optional CORS configuration.
+   * When not provided, no CORS headers are added (let the framework handle it).
+   * Set to true for permissive defaults, or provide an object.
+   */
+  cors?: boolean | CopilotCorsConfig;
+
+  /**
+   * Lifecycle hooks for request processing.
+   */
+  hooks?: CopilotRuntimeHooks;
+}
+
+export type CopilotRuntimeFetchHandler = (
+  request: Request,
+) => Promise<Response>;
+
+/* ------------------------------------------------------------------------------------------------
+ * Handler factory
+ * --------------------------------------------------------------------------------------------- */
+
+export function createCopilotRuntimeHandler(
+  options: CopilotRuntimeHandlerOptions,
+): CopilotRuntimeFetchHandler {
+  const { runtime, basePath, mode = "multi-route", cors, hooks } = options;
+
+  const corsConfig = resolveCorsConfig(cors);
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url, "http://localhost");
+    const path = url.pathname;
+    const requestOrigin = request.headers.get("origin");
+
+    // Base hook context (route not yet known)
+    const baseCtx: HookContext = { request, path, runtime };
+
+    let route: RouteInfo | undefined;
+
+    try {
+      // 1. CORS preflight
+      if (corsConfig) {
+        const preflight = handleCors(request, corsConfig);
+        if (preflight) return preflight;
+      }
+
+      // 2. onRequest hook
+      request = await runOnRequest(hooks, { ...baseCtx, request });
+
+      // 3. Legacy beforeRequestMiddleware
+      try {
+        const maybeModified = await callBeforeRequestMiddleware({
+          runtime,
+          request,
+          path,
+        });
+        if (maybeModified) {
+          request = maybeModified;
+        }
+      } catch (mwError: unknown) {
+        logger.error(
+          { err: mwError, url: request.url, path },
+          "Error running before request middleware",
+        );
+        if (mwError instanceof Response) {
+          return maybeAddCors(mwError, corsConfig, requestOrigin);
+        }
+        throw mwError;
+      }
+
+      // 4. Route matching
+      let response: Response;
+
+      if (mode === "single-route") {
+        const resolved = await resolveSingleRoute(request, basePath, path);
+        route = resolved.route;
+        const { methodCall } = resolved;
+        // 5. onBeforeHandler hook
+        request = await runOnBeforeHandler(hooks, {
+          request,
+          path,
+          runtime,
+          route,
+        });
+        // 6. Wrap body for methods that need it, then dispatch
+        if (
+          route.method === "agent/run" ||
+          route.method === "agent/connect" ||
+          route.method === "transcribe"
+        ) {
+          request = createJsonRequest(request, methodCall.body);
+        }
+        response = await dispatchRoute(runtime, request, route);
+      } else {
+        // Multi-route: match URL pattern
+        const matched = matchRoute(path, basePath);
+        if (!matched) {
+          throw jsonResponse({ error: "Not found" }, 404);
+        }
+
+        // Validate HTTP method
+        const methodError = validateHttpMethod(request.method, matched);
+        if (methodError) {
+          route = matched;
+          throw methodError;
+        }
+
+        route = matched;
+
+        // 5. onBeforeHandler hook
+        request = await runOnBeforeHandler(hooks, {
+          request,
+          path,
+          runtime,
+          route,
+        });
+
+        // 6. Handler dispatch
+        response = await dispatchRoute(runtime, request, route);
+      }
+
+      // 7. onResponse hook
+      response = await runOnResponse(hooks, {
+        request,
+        response,
+        path,
+        runtime,
+        route,
+      });
+
+      // 8. CORS headers on response
+      response = maybeAddCors(response, corsConfig, requestOrigin);
+
+      // 9. Legacy afterRequestMiddleware (non-blocking)
+      // Clone the response so middleware can read the body without consuming
+      // the original stream that will be sent to the client.
+      callAfterRequestMiddleware({
+        runtime,
+        response: response.clone(),
+        path,
+      }).catch((error: unknown) => {
+        logger.error(
+          { err: error, url: request.url, path },
+          "Error running after request middleware",
+        );
+      });
+
+      return response;
+    } catch (error) {
+      // Short-circuit with thrown Response
+      if (error instanceof Response) {
+        const finalResponse = await runOnResponse(hooks, {
+          request,
+          response: error,
+          path,
+          runtime,
+          route: route ?? { method: "info" },
+        });
+        return maybeAddCors(finalResponse, corsConfig, requestOrigin);
+      }
+
+      // Run onError hook — wrapped so a throwing hook doesn't escape
+      try {
+        const errorResponse = await runOnError(hooks, {
+          request,
+          error,
+          path,
+          runtime,
+          route,
+        });
+
+        if (errorResponse) {
+          return maybeAddCors(errorResponse, corsConfig, requestOrigin);
+        }
+      } catch (hookError: unknown) {
+        logger.error(
+          { err: hookError, originalErr: error, url: request.url, path },
+          "onError hook threw",
+        );
+      }
+
+      logger.error(
+        { err: error, url: request.url, path },
+        "Unhandled error in CopilotKit runtime handler",
+      );
+
+      return maybeAddCors(
+        jsonResponse({ error: "internal_error" }, 500),
+        corsConfig,
+        requestOrigin,
+      );
+    }
+  };
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Route dispatch
+ * --------------------------------------------------------------------------------------------- */
+
+function dispatchRoute(
+  runtime: CopilotRuntimeLike,
+  request: Request,
+  route: RouteInfo,
+): Promise<Response> {
+  switch (route.method) {
+    case "agent/run":
+      return handleRunAgent({
+        runtime,
+        request,
+        agentId: route.agentId,
+      });
+    case "agent/connect":
+      return handleConnectAgent({
+        runtime,
+        request,
+        agentId: route.agentId,
+      });
+    case "agent/stop":
+      return handleStopAgent({
+        runtime,
+        request,
+        agentId: route.agentId,
+        threadId: route.threadId,
+      });
+    case "info":
+      return handleGetRuntimeInfo({ runtime, request });
+    case "transcribe":
+      return handleTranscribe({ runtime, request });
+  }
+}
+
+interface SingleRouteResolution {
+  route: RouteInfo;
+  methodCall: MethodCall;
+}
+
+async function resolveSingleRoute(
+  request: Request,
+  basePath: string | undefined,
+  pathname: string,
+): Promise<SingleRouteResolution> {
+  if (basePath) {
+    const normalizedBase =
+      basePath.length > 1 && basePath.endsWith("/")
+        ? basePath.slice(0, -1)
+        : basePath;
+    if (!pathname.startsWith(normalizedBase)) {
+      throw jsonResponse({ error: "Not found" }, 404);
+    }
+  }
+
+  if (request.method !== "POST") {
+    throw jsonResponse({ error: "Method not allowed" }, 405, { Allow: "POST" });
+  }
+
+  const methodCall = await parseMethodCall(request);
+
+  let route: RouteInfo;
+  switch (methodCall.method) {
+    case "agent/run":
+      route = {
+        method: "agent/run",
+        agentId: expectString(methodCall.params, "agentId"),
+      };
+      break;
+    case "agent/connect":
+      route = {
+        method: "agent/connect",
+        agentId: expectString(methodCall.params, "agentId"),
+      };
+      break;
+    case "agent/stop":
+      route = {
+        method: "agent/stop",
+        agentId: expectString(methodCall.params, "agentId"),
+        threadId: expectString(methodCall.params, "threadId"),
+      };
+      break;
+    case "info":
+      route = { method: "info" };
+      break;
+    case "transcribe":
+      route = { method: "transcribe" };
+      break;
+  }
+
+  return { route, methodCall };
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * HTTP method validation
+ * --------------------------------------------------------------------------------------------- */
+
+function validateHttpMethod(
+  httpMethod: string,
+  route: RouteInfo,
+): Response | null {
+  const method = httpMethod.toUpperCase();
+  if (route.method === "info" && method === "GET") return null;
+  if (route.method !== "info" && method === "POST") return null;
+  const allowed = route.method === "info" ? "GET" : "POST";
+  return jsonResponse({ error: "Method not allowed" }, 405, { Allow: allowed });
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Helpers
+ * --------------------------------------------------------------------------------------------- */
+
+function resolveCorsConfig(
+  cors: boolean | CopilotCorsConfig | undefined,
+): CopilotCorsConfig | null {
+  if (!cors) return null;
+  if (cors === true) return {};
+  return cors;
+}
+
+function maybeAddCors(
+  response: Response,
+  config: CopilotCorsConfig | null,
+  requestOrigin: string | null,
+): Response {
+  if (!config) return response;
+  return addCorsHeaders(response, config, requestOrigin);
+}
+
+function jsonResponse(
+  body: unknown,
+  status: number,
+  extraHeaders?: Record<string, string>,
+): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", ...extraHeaders },
+  });
+}

package/src/v2/runtime/core/fetch-router.ts

@@ -0,0 +1,112 @@
+/**
+ * Lightweight URL router for framework-agnostic CopilotKit runtime handler.
+ *
+ * Two strategies:
+ * - With `basePath`: strict prefix strip → match remainder
+ * - Without `basePath`: suffix matching on known patterns
+ *
+ * Single-route mode: delegates to `parseMethodCall` for JSON envelope dispatch.
+ */
+
+import type { RouteInfo } from "./hooks";
+
+/**
+ * Match a request URL against known CopilotKit route patterns.
+ *
+ * @param pathname - The URL pathname to match
+ * @param basePath - Optional base path prefix to strip first
+ * @returns RouteInfo if matched, null otherwise
+ */
+export function matchRoute(
+  pathname: string,
+  basePath?: string,
+): RouteInfo | null {
+  let remainder: string;
+
+  if (basePath) {
+    // Normalize: ensure basePath doesn't end with /
+    const normalizedBase =
+      basePath.length > 1 && basePath.endsWith("/")
+        ? basePath.slice(0, -1)
+        : basePath;
+
+    // Special case: basePath === "/" matches everything
+    if (normalizedBase === "/") {
+      remainder = pathname;
+    } else {
+      if (!pathname.startsWith(normalizedBase)) return null;
+
+      // The character after basePath must be "/" or end of string
+      const afterBase = pathname.slice(normalizedBase.length);
+      if (afterBase.length > 0 && !afterBase.startsWith("/")) return null;
+
+      remainder = afterBase || "/";
+    }
+  } else {
+    // Suffix matching: find known patterns at the end of the pathname
+    remainder = pathname;
+  }
+
+  return matchSegments(remainder);
+}
+
+function safeDecodeURIComponent(value: string): string | null {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}
+
+function matchSegments(path: string): RouteInfo | null {
+  const segments = path.split("/").filter(Boolean);
+  const len = segments.length;
+
+  // Try suffix matching — scan from the end for known patterns
+
+  // /info (1 segment)
+  if (len >= 1 && segments[len - 1] === "info") {
+    return { method: "info" };
+  }
+
+  // /transcribe (1 segment)
+  if (len >= 1 && segments[len - 1] === "transcribe") {
+    return { method: "transcribe" };
+  }
+
+  // /agent/:agentId/run (3 segments)
+  if (
+    len >= 3 &&
+    segments[len - 3] === "agent" &&
+    segments[len - 1] === "run"
+  ) {
+    const agentId = safeDecodeURIComponent(segments[len - 2]!);
+    if (!agentId) return null;
+    return { method: "agent/run", agentId };
+  }
+
+  // /agent/:agentId/connect (3 segments)
+  if (
+    len >= 3 &&
+    segments[len - 3] === "agent" &&
+    segments[len - 1] === "connect"
+  ) {
+    const agentId = safeDecodeURIComponent(segments[len - 2]!);
+    if (!agentId) return null;
+    return { method: "agent/connect", agentId };
+  }
+
+  // /agent/:agentId/stop/:threadId (4 segments)
+  if (
+    len >= 4 &&
+    segments[len - 4] === "agent" &&
+    segments[len - 2] === "stop"
+  ) {
+    const agentId = safeDecodeURIComponent(segments[len - 3]!);
+    const threadId = safeDecodeURIComponent(segments[len - 1]!);
+    if (!agentId || !threadId) return null;
+    return { method: "agent/stop", agentId, threadId };
+  }
+
+  return null;
+}

package/src/v2/runtime/core/hooks.ts

@@ -0,0 +1,151 @@
+/**
+ * Lifecycle hooks for CopilotKit runtime request processing.
+ *
+ * Hooks let you intercept requests at various stages of the pipeline:
+ * - `onRequest`: Before routing — auth, correlation IDs, header injection
+ * - `onBeforeHandler`: After routing — route-specific authorization
+ * - `onResponse`: After handler — add headers, log, set cookies
+ * - `onError`: On error — custom error responses
+ *
+ * @example
+ * ```typescript
+ * const handler = createCopilotRuntimeHandler({
+ *   runtime,
+ *   hooks: {
+ *     onRequest: async ({ request }) => {
+ *       const token = request.headers.get("authorization");
+ *       if (!token) throw new Response("Unauthorized", { status: 401 });
+ *     },
+ *     onResponse: async ({ response }) => {
+ *       const headers = new Headers(response.headers);
+ *       headers.set("x-copilot-version", "2.0");
+ *       return new Response(response.body, { ...response, headers });
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+import type { MaybePromise } from "@copilotkit/shared";
+import type { CopilotRuntimeLike } from "./runtime";
+
+/* ------------------------------------------------------------------------------------------------
+ * Route info
+ * --------------------------------------------------------------------------------------------- */
+
+export type RouteInfo =
+  | { method: "agent/run"; agentId: string }
+  | { method: "agent/connect"; agentId: string }
+  | { method: "agent/stop"; agentId: string; threadId: string }
+  | { method: "info" }
+  | { method: "transcribe" };
+
+/* ------------------------------------------------------------------------------------------------
+ * Hook contexts
+ * --------------------------------------------------------------------------------------------- */
+
+export interface HookContext {
+  /** The incoming Fetch Request (possibly modified by prior hooks). */
+  request: Request;
+  /** The resolved URL pathname. */
+  path: string;
+  /** The CopilotRuntimeLike instance. */
+  runtime: CopilotRuntimeLike;
+}
+
+export interface HandlerHookContext extends HookContext {
+  /** The resolved route information. */
+  route: RouteInfo;
+}
+
+export interface ResponseHookContext extends HookContext {
+  /** The Response produced by the handler. */
+  response: Response;
+  /** The resolved route information. */
+  route: RouteInfo;
+}
+
+export interface ErrorHookContext extends HookContext {
+  /** The error that occurred. */
+  error: unknown;
+  /** The route info, if routing had already succeeded. */
+  route?: RouteInfo;
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Hooks interface
+ * --------------------------------------------------------------------------------------------- */
+
+export interface CopilotRuntimeHooks {
+  /**
+   * Called at the start of every request, before routing.
+   * Use to validate auth, attach headers, initialize correlation IDs, etc.
+   *
+   * Return a modified Request to replace the original, or void to continue.
+   * Throw a Response to short-circuit with an early response.
+   */
+  onRequest?: (ctx: HookContext) => MaybePromise<Request | void>;
+
+  /**
+   * Called after routing is resolved but before the handler executes.
+   * Receives the resolved route info (method, agentId, threadId).
+   *
+   * Use to do route-specific authorization, attach headers for agent calls, etc.
+   * Return a modified Request or void.
+   * Throw a Response to short-circuit.
+   */
+  onBeforeHandler?: (ctx: HandlerHookContext) => MaybePromise<Request | void>;
+
+  /**
+   * Called after the handler produces a Response, before it's sent to the client.
+   * Use to set cookies, add debugging headers, log, etc.
+   *
+   * Return a modified Response to replace the original, or void.
+   */
+  onResponse?: (ctx: ResponseHookContext) => MaybePromise<Response | void>;
+
+  /**
+   * Called when an error occurs during request processing.
+   * Return a Response to override the default error response, or void to use the default.
+   */
+  onError?: (ctx: ErrorHookContext) => MaybePromise<Response | void>;
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Internal hook runners
+ * --------------------------------------------------------------------------------------------- */
+
+export async function runOnRequest(
+  hooks: CopilotRuntimeHooks | undefined,
+  ctx: HookContext,
+): Promise<Request> {
+  if (!hooks?.onRequest) return ctx.request;
+  const result = await hooks.onRequest(ctx);
+  return result instanceof Request ? result : ctx.request;
+}
+
+export async function runOnBeforeHandler(
+  hooks: CopilotRuntimeHooks | undefined,
+  ctx: HandlerHookContext,
+): Promise<Request> {
+  if (!hooks?.onBeforeHandler) return ctx.request;
+  const result = await hooks.onBeforeHandler(ctx);
+  return result instanceof Request ? result : ctx.request;
+}
+
+export async function runOnResponse(
+  hooks: CopilotRuntimeHooks | undefined,
+  ctx: ResponseHookContext,
+): Promise<Response> {
+  if (!hooks?.onResponse) return ctx.response;
+  const result = await hooks.onResponse(ctx);
+  return result instanceof Response ? result : ctx.response;
+}
+
+export async function runOnError(
+  hooks: CopilotRuntimeHooks | undefined,
+  ctx: ErrorHookContext,
+): Promise<Response | void> {
+  if (!hooks?.onError) return;
+  return hooks.onError(ctx);
+}