@copilotkit/runtime 1.55.0-next.8 → 1.55.0

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

@@ -1,24 +1,8 @@
 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";
+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.
@@ -47,268 +31,59 @@ export interface CopilotEndpointCorsConfig {
 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;
 
-// Define the context variables type
-type CopilotEndpointContext = {
-  Variables: {
-    modifiedRequest?: Request;
-  };
-};
-
-export function createCopilotEndpoint({
+export function createCopilotHonoHandler({
   runtime,
   basePath,
+  mode = "multi-route",
   cors: corsConfig,
+  hooks,
 }: 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;
+  const handler = createCopilotRuntimeHandler({
+    runtime,
+    basePath,
+    mode,
+    cors: corsConfig ? toFetchCorsConfig(corsConfig) : true,
+    hooks,
+  });
 
-      // 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;
+  const app = new Hono();
 
-      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.basePath(basePath).all("*", async (c) => handler(c.req.raw));
+}
 
-  // return app;
+/**
+ * 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/node-fetch-handler.ts

@@ -0,0 +1,48 @@
+/**
+ * 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

@@ -0,0 +1,28 @@
+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/handlers/get-runtime-info.ts

@@ -1,10 +1,10 @@
-import { CopilotRuntimeLike, isIntelligenceRuntime } from "../runtime";
+import { CopilotRuntimeLike, isIntelligenceRuntime } from "../core/runtime";
 import {
   AgentDescription,
   RuntimeInfo,
   type RuntimeLicenseStatus,
 } from "@copilotkit/shared";
-import { VERSION } from "../runtime";
+import { VERSION } from "../core/runtime";
 
 function resolveLicenseStatus(
   runtime: CopilotRuntimeLike,
@@ -55,6 +55,7 @@ export async function handleGetRuntimeInfo({
           }
         : {}),
       a2uiEnabled: !!runtime.a2ui,
+      openGenerativeUIEnabled: !!runtime.openGenerativeUI,
       ...(isIntelligenceRuntime(runtime)
         ? { licenseStatus: resolveLicenseStatus(runtime) }
         : {}),

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

@@ -1,6 +1,6 @@
 import { handleIntelligenceConnect } from "./intelligence/connect";
 import { handleSseConnect } from "./sse/connect";
-import { isIntelligenceRuntime } from "../runtime";
+import { isIntelligenceRuntime } from "../core/runtime";
 import { telemetry } from "../telemetry";
 import {
   parseConnectRequest,
@@ -65,12 +65,15 @@ export async function handleConnectAgent({
       cause: error instanceof Error ? error.cause : undefined,
     });
 
-    return Response.json(
-      {
+    return new Response(
+      JSON.stringify({
         error: "Failed to run agent",
         message: error instanceof Error ? error.message : "Unknown error",
+      }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
       },
-      { status: 500 },
     );
   }
 }

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

@@ -1,4 +1,4 @@
-import { isIntelligenceRuntime } from "../runtime";
+import { isIntelligenceRuntime } from "../core/runtime";
 import { telemetry } from "../telemetry";
 import {
   cloneAgentForRequest,
@@ -78,12 +78,15 @@ export async function handleRunAgent({
       cause: error instanceof Error ? error.cause : undefined,
     });
 
-    return Response.json(
-      {
+    return new Response(
+      JSON.stringify({
         error: "Failed to run agent",
         message: error instanceof Error ? error.message : "Unknown error",
+      }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
       },
-      { status: 500 },
     );
   }
 }

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

@@ -1,4 +1,4 @@
-import { CopilotRuntimeLike } from "../runtime";
+import type { CopilotRuntimeLike } from "../core/runtime";
 import { EventType } from "@ag-ui/client";
 
 interface StopAgentParameters {

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

@@ -1,4 +1,4 @@
-import { CopilotRuntimeLike } from "../runtime";
+import type { CopilotRuntimeLike } from "../core/runtime";
 import {
   TranscriptionErrorCode,
   TranscriptionErrors,

package/src/v2/runtime/handlers/intelligence/connect.ts

@@ -1,4 +1,4 @@
-import { CopilotIntelligenceRuntimeLike } from "../../runtime";
+import { CopilotIntelligenceRuntimeLike } from "../../core/runtime";
 import { isPlatformNotFoundError } from "../shared/intelligence-utils";
 import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user";
 import { isHandlerResponse } from "../shared/json-response";

package/src/v2/runtime/handlers/intelligence/run.ts

@@ -1,5 +1,5 @@
 import { AbstractAgent, Message, RunAgentInput } from "@ag-ui/client";
-import { CopilotIntelligenceRuntimeLike } from "../../runtime";
+import { CopilotIntelligenceRuntimeLike } from "../../core/runtime";
 import { generateThreadNameForNewThread } from "./thread-names";
 import { logger } from "@copilotkit/shared";
 import { telemetry } from "../../telemetry";
@@ -73,6 +73,10 @@ export async function handleIntelligenceRun({
       threadId: input.threadId,
       runId: input.runId,
       userId,
+      ...(runtime.lockKeyPrefix !== undefined
+        ? { lockKeyPrefix: runtime.lockKeyPrefix }
+        : {}),
+      ttlSeconds: runtime.lockTtlSeconds,
     });
     joinToken = lockResult.joinToken;
     joinCode = lockResult.joinCode;
@@ -121,6 +125,30 @@ export async function handleIntelligenceRun({
 
   telemetry.capture("oss.runtime.agent_execution_stream_started", {});
 
+  // Start heartbeat timer to renew the thread lock.
+  let heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+  heartbeatTimer = setInterval(() => {
+    runtime.intelligence
+      .ɵrenewThreadLock({
+        threadId: input.threadId,
+        runId: input.runId,
+        ttlSeconds: runtime.lockTtlSeconds,
+        ...(runtime.lockKeyPrefix !== undefined
+          ? { lockKeyPrefix: runtime.lockKeyPrefix }
+          : {}),
+      })
+      .catch((err) => {
+        logger.error("Failed to renew thread lock:", err);
+      });
+  }, runtime.lockHeartbeatIntervalSeconds * 1_000);
+
+  const clearHeartbeat = () => {
+    if (heartbeatTimer !== undefined) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = undefined;
+    }
+  };
+
   runtime.runner
     .run({
       threadId: input.threadId,
@@ -133,12 +161,14 @@ export async function handleIntelligenceRun({
     })
     .subscribe({
       error: (error) => {
+        clearHeartbeat();
         telemetry.capture("oss.runtime.agent_execution_stream_errored", {
           error: error instanceof Error ? error.message : String(error),
         });
         logger.error("Error running agent:", error);
       },
       complete: () => {
+        clearHeartbeat();
         telemetry.capture("oss.runtime.agent_execution_stream_ended", {});
       },
     });

package/src/v2/runtime/handlers/intelligence/thread-names.ts

@@ -1,7 +1,7 @@
 import { AbstractAgent, Message, RunAgentInput } from "@ag-ui/client";
 import { logger } from "@copilotkit/shared";
 import { randomUUID } from "node:crypto";
-import { CopilotIntelligenceRuntimeLike } from "../../runtime";
+import { CopilotIntelligenceRuntimeLike } from "../../core/runtime";
 import {
   cloneAgentForRequest,
   configureAgentForRequest,
@@ -130,7 +130,7 @@ async function runTitleGenerationAttempt(params: {
 
   agent.setMessages(messages);
   agent.setState({});
-  agent.threadId = `thread-name:${threadId}:${randomUUID()}`;
+  agent.threadId = randomUUID();
   const { newMessages } = await agent.runAgent({
     messages,
     state: {},

package/src/v2/runtime/handlers/intelligence/threads.ts

@@ -2,7 +2,7 @@ import {
   CopilotIntelligenceRuntimeLike,
   CopilotRuntimeLike,
   isIntelligenceRuntime,
-} from "../../runtime";
+} from "../../core/runtime";
 import { logger } from "@copilotkit/shared";
 import { errorResponse, isHandlerResponse } from "../shared/json-response";
 import { isValidIdentifier } from "../shared/intelligence-utils";

package/src/v2/runtime/handlers/shared/agent-utils.ts

@@ -5,7 +5,8 @@ import {
 } from "@ag-ui/client";
 import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
 import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
-import { CopilotRuntimeLike } from "../../runtime";
+import { CopilotRuntimeLike } from "../../core/runtime";
+import { OpenGenerativeUIMiddleware } from "../../open-generative-ui-middleware";
 import { extractForwardableHeaders } from "../header-utils";
 import { logger } from "@copilotkit/shared";
 
@@ -31,12 +32,15 @@ export async function cloneAgentForRequest(
   const agents = await runtime.agents;
 
   if (!agents[agentId]) {
-    return Response.json(
-      {
+    return new Response(
+      JSON.stringify({
         error: "Agent not found",
         message: `Agent '${agentId}' does not exist`,
+      }),
+      {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
       },
-      { status: 404 },
     );
   }
 
@@ -74,6 +78,15 @@ export function configureAgentForRequest(params: {
     }
   }
 
+  if (runtime.openGenerativeUI) {
+    const config = runtime.openGenerativeUI;
+    const targetAgents = typeof config === "object" ? config.agents : undefined;
+    const shouldApply = !targetAgents || targetAgents.includes(agentId);
+    if (shouldApply && typeof agent.use === "function") {
+      agent.use(new OpenGenerativeUIMiddleware());
+    }
+  }
+
   if (agent.headers) {
     agent.headers = {
       ...agent.headers,
@@ -90,12 +103,15 @@ export async function parseRunRequest(
     return RunAgentInputSchema.parse(requestBody);
   } catch (error) {
     logger.error("Invalid run request body:", error);
-    return Response.json(
-      {
+    return new Response(
+      JSON.stringify({
         error: "Invalid request body",
         details: error instanceof Error ? error.message : String(error),
+      }),
+      {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
       },
-      { status: 400 },
     );
   }
 }
@@ -125,12 +141,15 @@ export async function parseConnectRequest(request: Request): Promise<
     return { input, lastSeenEventId };
   } catch (error) {
     logger.error("Invalid connect request body:", error);
-    return Response.json(
-      {
+    return new Response(
+      JSON.stringify({
         error: "Invalid request body",
         details: error instanceof Error ? error.message : String(error),
+      }),
+      {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
       },
-      { status: 400 },
     );
   }
 }