@copilotkit/runtime 1.54.1 → 1.55.0-next.8

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

@@ -0,0 +1,314 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { CopilotRuntimeLike } from "../runtime";
+import { telemetry } from "../telemetry";
+import { handleRunAgent } from "../handlers/handle-run";
+import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
+import { handleTranscribe } from "../handlers/handle-transcribe";
+import { logger, getLicenseWarningHeader } from "@copilotkit/shared";
+import {
+  callBeforeRequestMiddleware,
+  callAfterRequestMiddleware,
+} from "../middleware";
+import { handleConnectAgent } from "../handlers/handle-connect";
+import { handleStopAgent } from "../handlers/handle-stop";
+import {
+  handleListThreads,
+  handleSubscribeToThreads,
+  handleUpdateThread,
+  handleArchiveThread,
+  handleDeleteThread,
+} from "../handlers/handle-threads";
+
+/**
+ * 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;
+  /**
+   * 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;
+}
+
+// Define the context variables type
+type CopilotEndpointContext = {
+  Variables: {
+    modifiedRequest?: Request;
+  };
+};
+
+export function createCopilotEndpoint({
+  runtime,
+  basePath,
+  cors: corsConfig,
+}: CopilotEndpointParams) {
+  const app = new Hono<CopilotEndpointContext>();
+
+  // 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
+    });
+
+  return app
+    .basePath(basePath)
+    .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;
+      }
+
+      const warning = getLicenseWarningHeader(runtime.licenseChecker);
+      if (warning) c.header(warning.key, warning.value);
+
+      await next();
+    })
+    .use("*", async (c, next) => {
+      await next();
+
+      const response = c.res.clone();
+      const path = c.req.path;
+
+      // Non-blocking after middleware
+      callAfterRequestMiddleware({
+        runtime,
+        response,
+        path,
+      }).catch((error) => {
+        logger.error(
+          { err: error, url: c.req.url, path },
+          "Error running after request middleware",
+        );
+      });
+    })
+    .post("/agent/:agentId/run", async (c) => {
+      const agentId = c.req.param("agentId");
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleRunAgent({
+          runtime,
+          request,
+          agentId,
+        });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .post("/agent/:agentId/connect", async (c) => {
+      const agentId = c.req.param("agentId");
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleConnectAgent({
+          runtime,
+          request,
+          agentId,
+        });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+
+    .post("/agent/:agentId/stop/:threadId", async (c) => {
+      const agentId = c.req.param("agentId");
+      const threadId = c.req.param("threadId");
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleStopAgent({
+          runtime,
+          request,
+          agentId,
+          threadId,
+        });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .get("/info", async (c) => {
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleGetRuntimeInfo({
+          runtime,
+          request,
+        });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .post("/transcribe", async (c) => {
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleTranscribe({
+          runtime,
+          request,
+        });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .get("/threads", async (c) => {
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleListThreads({ runtime, request });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .post("/threads/subscribe", async (c) => {
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleSubscribeToThreads({ runtime, request });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .patch("/threads/:threadId", async (c) => {
+      const threadId = c.req.param("threadId");
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleUpdateThread({ runtime, request, threadId });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .post("/threads/:threadId/archive", async (c) => {
+      const threadId = c.req.param("threadId");
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleArchiveThread({ runtime, request, threadId });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .delete("/threads/:threadId", async (c) => {
+      const threadId = c.req.param("threadId");
+      const request = c.get("modifiedRequest") || c.req.raw;
+
+      try {
+        return await handleDeleteThread({ runtime, request, threadId });
+      } catch (error) {
+        logger.error(
+          { err: error, url: request.url, path: c.req.path },
+          "Error running request handler",
+        );
+        throw error;
+      }
+    })
+    .notFound((c) => {
+      return c.json({ error: "Not found" }, 404);
+    });
+
+  // return app;
+}

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

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

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

@@ -0,0 +1,125 @@
+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

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

package/src/v2/runtime/handler.ts

@@ -0,0 +1,3 @@
+export type CopilotKitRequestHandler = (params: {
+  request: Request;
+}) => Promise<Response>;

package/src/v2/runtime/handlers/get-runtime-info.ts

@@ -0,0 +1,79 @@
+import { CopilotRuntimeLike, isIntelligenceRuntime } from "../runtime";
+import {
+  AgentDescription,
+  RuntimeInfo,
+  type RuntimeLicenseStatus,
+} from "@copilotkit/shared";
+import { VERSION } from "../runtime";
+
+function resolveLicenseStatus(
+  runtime: CopilotRuntimeLike,
+): RuntimeLicenseStatus {
+  if (!runtime.licenseChecker) return "none";
+  const status = runtime.licenseChecker.getStatus();
+  if (status.warningSeverity === "none") return "valid";
+  if (status.error === "expired") return "expired";
+  if (status.warningSeverity === "warning") return "expiring";
+  if (status.error) return "invalid";
+  if (status.warningSeverity === "info") return "none";
+  return "unknown";
+}
+
+interface HandleGetRuntimeInfoParameters {
+  runtime: CopilotRuntimeLike;
+  request: Request;
+}
+
+export async function handleGetRuntimeInfo({
+  runtime,
+}: HandleGetRuntimeInfoParameters) {
+  try {
+    const agents = await runtime.agents;
+
+    const agentsDict = Object.entries(agents).reduce(
+      (acc, [name, agent]) => {
+        acc[name] = {
+          name,
+          description: agent.description,
+          className: agent.constructor.name,
+        };
+        return acc;
+      },
+      {} as Record<string, AgentDescription>,
+    );
+
+    const runtimeInfo: RuntimeInfo = {
+      version: VERSION,
+      agents: agentsDict,
+      audioFileTranscriptionEnabled: !!runtime.transcriptionService,
+      mode: runtime.mode,
+      ...(isIntelligenceRuntime(runtime)
+        ? {
+            intelligence: {
+              wsUrl: runtime.intelligence.ɵgetClientWsUrl(),
+            },
+          }
+        : {}),
+      a2uiEnabled: !!runtime.a2ui,
+      ...(isIntelligenceRuntime(runtime)
+        ? { licenseStatus: resolveLicenseStatus(runtime) }
+        : {}),
+    };
+
+    return new Response(JSON.stringify(runtimeInfo), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  } catch (error) {
+    return new Response(
+      JSON.stringify({
+        error: "Failed to retrieve runtime information",
+        message: error instanceof Error ? error.message : "Unknown error",
+      }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+}

package/src/v2/runtime/handlers/handle-connect.ts

@@ -0,0 +1,76 @@
+import { handleIntelligenceConnect } from "./intelligence/connect";
+import { handleSseConnect } from "./sse/connect";
+import { isIntelligenceRuntime } from "../runtime";
+import { telemetry } from "../telemetry";
+import {
+  parseConnectRequest,
+  RunAgentParameters as ConnectAgentParameters,
+  cloneAgentForRequest,
+} from "./shared/agent-utils";
+
+export async function handleConnectAgent({
+  runtime,
+  request,
+  agentId,
+}: ConnectAgentParameters) {
+  telemetry.capture("oss.runtime.copilot_request_created", {
+    "cloud.guardrails.enabled": false,
+    requestType: "connect",
+    "cloud.api_key_provided": !!request.headers.get(
+      "x-copilotcloud-public-api-key",
+    ),
+    ...(request.headers.get("x-copilotcloud-public-api-key")
+      ? {
+          "cloud.public_api_key": request.headers.get(
+            "x-copilotcloud-public-api-key",
+          )!,
+        }
+      : {}),
+  });
+
+  try {
+    const agent = await cloneAgentForRequest(runtime, agentId);
+    if (agent instanceof Response) {
+      return agent;
+    }
+
+    const connectRequest = await parseConnectRequest(request);
+    if (connectRequest instanceof Response) {
+      return connectRequest;
+    }
+
+    if (isIntelligenceRuntime(runtime)) {
+      return handleIntelligenceConnect({
+        runtime,
+        request,
+        threadId: connectRequest.input.threadId,
+        lastSeenEventId: connectRequest.lastSeenEventId,
+      });
+    }
+
+    return handleSseConnect({
+      runtime,
+      request,
+      threadId: connectRequest.input.threadId,
+    });
+  } catch (error) {
+    console.error("Error running agent:", error);
+    console.error(
+      "Error stack:",
+      error instanceof Error ? error.stack : "No stack trace",
+    );
+    console.error("Error details:", {
+      name: error instanceof Error ? error.name : "Unknown",
+      message: error instanceof Error ? error.message : String(error),
+      cause: error instanceof Error ? error.cause : undefined,
+    });
+
+    return Response.json(
+      {
+        error: "Failed to run agent",
+        message: error instanceof Error ? error.message : "Unknown error",
+      },
+      { status: 500 },
+    );
+  }
+}

package/src/v2/runtime/handlers/handle-run.ts

@@ -0,0 +1,89 @@
+import { isIntelligenceRuntime } from "../runtime";
+import { telemetry } from "../telemetry";
+import {
+  cloneAgentForRequest,
+  configureAgentForRequest,
+  parseRunRequest,
+  RunAgentParameters,
+} from "./shared/agent-utils";
+import { handleIntelligenceRun } from "./intelligence/run";
+import { handleSseRun } from "./sse/run";
+
+export async function handleRunAgent({
+  runtime,
+  request,
+  agentId,
+}: RunAgentParameters) {
+  telemetry.capture("oss.runtime.copilot_request_created", {
+    "cloud.guardrails.enabled": false,
+    requestType: "run",
+    "cloud.api_key_provided": !!request.headers.get(
+      "x-copilotcloud-public-api-key",
+    ),
+    ...(request.headers.get("x-copilotcloud-public-api-key")
+      ? {
+          "cloud.public_api_key": request.headers.get(
+            "x-copilotcloud-public-api-key",
+          )!,
+        }
+      : {}),
+  });
+
+  try {
+    const agent = await cloneAgentForRequest(runtime, agentId);
+    if (agent instanceof Response) {
+      return agent;
+    }
+
+    configureAgentForRequest({ runtime, request, agentId, agent });
+
+    if (
+      runtime.licenseChecker &&
+      !runtime.licenseChecker.checkFeature("agents")
+    ) {
+      console.warn(
+        '[CopilotKit Runtime] Warning: "agents" feature is not licensed. Visit copilotkit.ai/pricing',
+      );
+    }
+
+    const input = await parseRunRequest(request);
+    if (input instanceof Response) {
+      return input;
+    }
+
+    agent.setMessages(input.messages);
+    agent.setState(input.state);
+    agent.threadId = input.threadId;
+
+    if (isIntelligenceRuntime(runtime)) {
+      return handleIntelligenceRun({
+        runtime,
+        request,
+        agentId,
+        agent,
+        input,
+      });
+    }
+
+    return handleSseRun({ runtime, request, agent, input });
+  } catch (error) {
+    console.error("Error running agent:", error);
+    console.error(
+      "Error stack:",
+      error instanceof Error ? error.stack : "No stack trace",
+    );
+    console.error("Error details:", {
+      name: error instanceof Error ? error.name : "Unknown",
+      message: error instanceof Error ? error.message : String(error),
+      cause: error instanceof Error ? error.cause : undefined,
+    });
+
+    return Response.json(
+      {
+        error: "Failed to run agent",
+        message: error instanceof Error ? error.message : "Unknown error",
+      },
+      { status: 500 },
+    );
+  }
+}