@copilotkit/runtime 1.55.0-next.8 → 1.55.0

package/src/v2/runtime/{runtime.ts → core/runtime.ts}

@@ -4,22 +4,24 @@ import {
   RuntimeMode,
   RUNTIME_MODE_SSE,
   RUNTIME_MODE_INTELLIGENCE,
+} from "@copilotkit/shared";
+import {
   createLicenseChecker,
   type LicenseChecker,
-} from "@copilotkit/shared";
+} from "@copilotkit/license-verifier";
 import { AbstractAgent } from "@ag-ui/client";
 import type { MCPClientConfig } from "@ag-ui/mcp-apps-middleware";
 import { A2UIMiddlewareConfig } from "@ag-ui/a2ui-middleware";
-import pkg from "../../../package.json";
+import pkg from "../../../../package.json";
 import type {
   BeforeRequestMiddleware,
   AfterRequestMiddleware,
 } from "./middleware";
-import { TranscriptionService } from "./transcription-service/transcription-service";
-import { AgentRunner } from "./runner/agent-runner";
-import { InMemoryAgentRunner } from "./runner/in-memory";
-import { IntelligenceAgentRunner } from "./runner/intelligence";
-import { CopilotKitIntelligence } from "./intelligence-platform";
+import { TranscriptionService } from "../transcription-service/transcription-service";
+import { AgentRunner } from "../runner/agent-runner";
+import { InMemoryAgentRunner } from "../runner/in-memory";
+import { IntelligenceAgentRunner } from "../runner/intelligence";
+import { CopilotKitIntelligence } from "../intelligence-platform";
 
 export const VERSION = pkg.version;
 
@@ -38,11 +40,20 @@ export interface McpAppsConfig {
   servers: McpAppsServerConfig[];
 }
 
+export interface OpenGenerativeUIOptions extends BaseCopilotRuntimeMiddlewareOptions {}
+
+export type OpenGenerativeUIConfig = boolean | OpenGenerativeUIOptions;
+
 interface CopilotRuntimeMiddlewares {
-  /** Auto-apply A2UIMiddleware to agents at run time. */
+  /**
+   * Auto-apply A2UIMiddleware to agents at run time.
+   * Pass an object to enable and customise behaviour, or omit to disable.
+   */
   a2ui?: BaseCopilotRuntimeMiddlewareOptions & A2UIMiddlewareConfig;
   /** Auto-apply MCPAppsMiddleware to agents at run time. */
   mcpApps?: McpAppsConfig;
+  /** Auto-apply OpenGenerativeUIMiddleware to agents at run time. */
+  openGenerativeUI?: OpenGenerativeUIConfig;
 }
 
 interface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares {
@@ -80,6 +91,16 @@ export interface CopilotIntelligenceRuntimeOptions extends BaseCopilotRuntimeOpt
   identifyUser: IdentifyUserCallback;
   /** Auto-generate short names for newly created threads. */
   generateThreadNames?: boolean;
+  /** Max delay (ms) for WebSocket reconnect backoff. @default 10_000 */
+  maxReconnectMs?: number;
+  /** Max delay (ms) for channel rejoin backoff. @default 30_000 */
+  maxRejoinMs?: number;
+  /** Lock TTL in seconds. Clamped to a maximum of 3600 (1 hour). @default 20 */
+  lockTtlSeconds?: number;
+  /** Custom Redis key prefix for the thread lock. */
+  lockKeyPrefix?: string;
+  /** Interval in seconds at which the runtime renews the thread lock. Clamped to a maximum of 3000 (50 minutes). @default 15 */
+  lockHeartbeatIntervalSeconds?: number;
 }
 
 export type CopilotRuntimeOptions =
@@ -94,6 +115,7 @@ export interface CopilotRuntimeLike {
   runner: AgentRunner;
   a2ui: CopilotRuntimeOptions["a2ui"];
   mcpApps: CopilotRuntimeOptions["mcpApps"];
+  openGenerativeUI: CopilotRuntimeOptions["openGenerativeUI"];
   intelligence?: CopilotKitIntelligence;
   identifyUser?: IdentifyUserCallback;
   mode: RuntimeMode;
@@ -109,6 +131,9 @@ export interface CopilotIntelligenceRuntimeLike extends CopilotRuntimeLike {
   intelligence: CopilotKitIntelligence;
   identifyUser: IdentifyUserCallback;
   generateThreadNames: boolean;
+  lockTtlSeconds: number;
+  lockKeyPrefix?: string;
+  lockHeartbeatIntervalSeconds: number;
   mode: RUNTIME_MODE_INTELLIGENCE;
 }
 
@@ -120,6 +145,7 @@ abstract class BaseCopilotRuntime implements CopilotRuntimeLike {
   public runner: AgentRunner;
   public a2ui: CopilotRuntimeOptions["a2ui"];
   public mcpApps: CopilotRuntimeOptions["mcpApps"];
+  public openGenerativeUI: CopilotRuntimeOptions["openGenerativeUI"];
   public licenseChecker?: LicenseChecker;
 
   abstract readonly intelligence?: CopilotKitIntelligence;
@@ -133,16 +159,17 @@ abstract class BaseCopilotRuntime implements CopilotRuntimeLike {
       afterRequestMiddleware,
       a2ui,
       mcpApps,
+      openGenerativeUI,
     } = options;
 
     this.agents = agents;
     this.transcriptionService = transcriptionService;
     this.beforeRequestMiddleware = beforeRequestMiddleware;
     this.afterRequestMiddleware = afterRequestMiddleware;
-    this.a2ui = a2ui;
+    this.a2ui = a2ui || undefined;
     this.mcpApps = mcpApps;
+    this.openGenerativeUI = openGenerativeUI;
     this.runner = runner;
-    this.licenseChecker = createLicenseChecker(options.licenseToken);
   }
 }
 
@@ -165,19 +192,39 @@ export class CopilotIntelligenceRuntime
   readonly intelligence: CopilotKitIntelligence;
   readonly identifyUser: IdentifyUserCallback;
   readonly generateThreadNames: boolean;
+  readonly lockTtlSeconds: number;
+  readonly lockKeyPrefix?: string;
+  readonly lockHeartbeatIntervalSeconds: number;
   readonly mode = RUNTIME_MODE_INTELLIGENCE;
 
+  /** Maximum allowed lock TTL in seconds (1 hour). */
+  static readonly MAX_LOCK_TTL_SECONDS = 3_600;
+  /** Maximum allowed heartbeat interval in seconds (50 minutes). */
+  static readonly MAX_HEARTBEAT_INTERVAL_SECONDS = 3_000;
+
   constructor(options: CopilotIntelligenceRuntimeOptions) {
     super(
       options,
       new IntelligenceAgentRunner({
         url: options.intelligence.ɵgetRunnerWsUrl(),
         authToken: options.intelligence.ɵgetRunnerAuthToken(),
+        maxReconnectMs: options.maxReconnectMs,
+        maxRejoinMs: options.maxRejoinMs,
       }),
     );
     this.intelligence = options.intelligence;
     this.identifyUser = options.identifyUser;
     this.generateThreadNames = options.generateThreadNames ?? true;
+    this.licenseChecker = createLicenseChecker(options.licenseToken);
+    this.lockTtlSeconds = Math.min(
+      options.lockTtlSeconds ?? 20,
+      CopilotIntelligenceRuntime.MAX_LOCK_TTL_SECONDS,
+    );
+    this.lockKeyPrefix = options.lockKeyPrefix;
+    this.lockHeartbeatIntervalSeconds = Math.min(
+      options.lockHeartbeatIntervalSeconds ?? 15,
+      CopilotIntelligenceRuntime.MAX_HEARTBEAT_INTERVAL_SECONDS,
+    );
   }
 }
 
@@ -234,6 +281,10 @@ export class CopilotRuntime implements CopilotRuntimeLike {
     return this.delegate.mcpApps;
   }
 
+  get openGenerativeUI(): CopilotRuntimeOptions["openGenerativeUI"] {
+    return this.delegate.openGenerativeUI;
+  }
+
   get intelligence(): CopilotKitIntelligence | undefined {
     return this.delegate.intelligence;
   }
@@ -250,6 +301,24 @@ export class CopilotRuntime implements CopilotRuntimeLike {
       : undefined;
   }
 
+  get lockTtlSeconds(): number | undefined {
+    return isIntelligenceRuntime(this.delegate)
+      ? this.delegate.lockTtlSeconds
+      : undefined;
+  }
+
+  get lockKeyPrefix(): string | undefined {
+    return isIntelligenceRuntime(this.delegate)
+      ? this.delegate.lockKeyPrefix
+      : undefined;
+  }
+
+  get lockHeartbeatIntervalSeconds(): number | undefined {
+    return isIntelligenceRuntime(this.delegate)
+      ? this.delegate.lockHeartbeatIntervalSeconds
+      : undefined;
+  }
+
   get mode(): RuntimeMode {
     return this.delegate.mode;
   }

package/src/v2/runtime/endpoints/express-fetch-bridge.ts

@@ -0,0 +1,137 @@
+/**
+ * Express-aware Node ↔ Fetch bridge.
+ *
+ * When Express body-parsing middleware (e.g. `express.json()`) runs before the
+ * CopilotKit router, the Node request stream is already consumed and `req.body`
+ * holds the parsed content. The generic `createCopilotNodeHandler` (which uses
+ * `@remix-run/node-fetch-server`) would hang because it tries to read from the
+ * exhausted stream.
+ *
+ * This module detects the pre-parsed case and re-serialises `req.body` into the
+ * Fetch `Request`, falling back to the generic `createCopilotNodeHandler` when the
+ * stream is still available.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { sendResponse } from "@remix-run/node-fetch-server";
+import { createCopilotNodeHandler } from "./node-fetch-handler";
+import type { CopilotRuntimeFetchHandler } from "../core/fetch-handler";
+import { logger } from "@copilotkit/shared";
+
+const METHODS_WITHOUT_BODY = new Set(["GET", "HEAD", "OPTIONS"]);
+
+export type ExpressNodeHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => Promise<void>;
+
+/**
+ * Creates a Node HTTP handler from a fetch handler, with Express body-parser
+ * compatibility. Use this instead of `createNodeFetchHandler` in Express adapters.
+ *
+ * When the body stream hasn't been consumed, delegates to the generic
+ * `createCopilotNodeHandler`. Only intercepts when Express middleware has
+ * pre-parsed the body.
+ */
+export function createExpressNodeHandler(
+  handler: CopilotRuntimeFetchHandler,
+): ExpressNodeHandler {
+  const nodeHandler = createCopilotNodeHandler(handler);
+
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    const method = (req.method ?? "GET").toUpperCase();
+
+    // Fast path: if no body parser consumed the stream, use the generic handler.
+    if (METHODS_WITHOUT_BODY.has(method) || !hasPreParsedBody(req)) {
+      return nodeHandler(req, res);
+    }
+
+    // Slow path: body was consumed by Express middleware — rebuild the Request.
+    try {
+      const fetchReq = buildPreParsedRequest(req, res);
+      const fetchRes = await handler(fetchReq);
+      await sendResponse(res, fetchRes);
+    } catch (err: unknown) {
+      logger.error({ err }, "Error in Express fetch bridge (pre-parsed path)");
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.end("Internal Server Error");
+      }
+    }
+  };
+}
+
+/**
+ * Build a Fetch Request from a Node IncomingMessage whose body stream has
+ * already been consumed by an Express body parser.
+ */
+function buildPreParsedRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Request {
+  const expressReq = req as IncomingMessage & { body?: unknown };
+  const method = (req.method ?? "GET").toUpperCase();
+
+  const protocol = (req as any).protocol || "http";
+  const host = req.headers.host ?? "localhost";
+  const url = `${protocol}://${host}${(req as any).originalUrl ?? req.url ?? ""}`;
+
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) headers.append(key, v);
+    } else {
+      headers.set(key, value);
+    }
+  }
+
+  // Wire an AbortSignal so client disconnects propagate to the fetch handler
+  const controller = new AbortController();
+  res.on("close", () => {
+    if (!res.writableFinished) controller.abort();
+  });
+
+  const init: RequestInit & { duplex?: "half" } = {
+    method,
+    headers,
+    signal: controller.signal,
+  };
+
+  const { body, contentType } = synthesizeBody(expressReq.body);
+  if (contentType) {
+    headers.set("content-type", contentType);
+  }
+  headers.delete("content-length");
+  if (body !== undefined) {
+    init.body = body;
+  }
+
+  return new Request(url, init);
+}
+
+function hasPreParsedBody(req: IncomingMessage & { body?: unknown }): boolean {
+  if (req.body === undefined || req.body === null) return false;
+
+  // Check if the stream has already been consumed.
+  const state = (req as any)._readableState;
+  return Boolean(
+    req.readableEnded || req.complete || state?.ended || state?.endEmitted,
+  );
+}
+
+function synthesizeBody(body: unknown): {
+  body?: BodyInit;
+  contentType?: string;
+} {
+  if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
+    return { body };
+  }
+  if (typeof body === "string") {
+    return { body };
+  }
+  if (typeof body === "object" && body !== null) {
+    return { body: JSON.stringify(body), contentType: "application/json" };
+  }
+  return {};
+}

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

@@ -1,231 +1,54 @@
-import express from "express";
-import type {
-  Request as ExpressRequest,
-  Response as ExpressResponse,
-  NextFunction,
-  Router,
-} from "express";
-import cors from "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 {
-  createFetchRequestFromExpress,
-  sendFetchResponse,
-} from "./express-utils";
-import {
-  createJsonRequest,
-  expectString,
-  MethodCall,
-  parseMethodCall,
-} from "./single-route-helpers";
+import type { Router } from "express";
+import { createCopilotExpressHandler } from "./express";
+import type { CopilotRuntimeLike } from "../core/runtime";
+import type { CopilotRuntimeHooks } from "../core/hooks";
 
 interface CopilotSingleRouteExpressParams {
   runtime: CopilotRuntimeLike;
   basePath: string;
+  /**
+   * Lifecycle hooks for request processing.
+   */
+  hooks?: CopilotRuntimeHooks;
 }
 
+/**
+ * Creates an Express router that serves the CopilotKit runtime as a single
+ * POST endpoint. Clients send a JSON envelope with `{ method, params, body }`
+ * to dispatch to the appropriate handler.
+ *
+ * This is a convenience wrapper around {@link createCopilotExpressHandler}
+ * with `mode: "single-route"` and `cors: true`.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { CopilotRuntime } from "@copilotkit/runtime/v2";
+ * import { createCopilotEndpointSingleRouteExpress } from "@copilotkit/runtime/v2/express";
+ *
+ * const runtime = new CopilotRuntime({
+ *   agents: { default: new BuiltInAgent({ model: "openai/gpt-4o-mini" }) },
+ * });
+ *
+ * const app = express();
+ * app.use(createCopilotEndpointSingleRouteExpress({
+ *   runtime,
+ *   basePath: "/api/copilotkit",
+ * }));
+ * app.listen(4000);
+ * ```
+ */
+/** @deprecated Use `createCopilotExpressHandler` with `mode: "single-route"` instead. */
 export function createCopilotEndpointSingleRouteExpress({
   runtime,
   basePath,
+  hooks,
 }: CopilotSingleRouteExpressParams): Router {
-  const router = express.Router();
-  const routePath = normalizeSingleRoutePath(basePath);
-
-  router.use(
-    cors({
-      origin: "*",
-      methods: ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH", "OPTIONS"],
-      allowedHeaders: ["*"],
-    }),
-  );
-
-  router.post(routePath, createSingleRouteHandler(runtime));
-
-  router.use((req, res) => {
-    res.status(404).json({ error: "Not found" });
+  return createCopilotExpressHandler({
+    runtime,
+    basePath,
+    mode: "single-route",
+    cors: true,
+    hooks,
   });
-
-  return router;
-}
-
-function createSingleRouteHandler(runtime: CopilotRuntimeLike) {
-  return async (
-    req: ExpressRequest,
-    res: ExpressResponse,
-    next: NextFunction,
-  ) => {
-    const path = req.originalUrl ?? req.path;
-    let request = createFetchRequestFromExpress(req);
-
-    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;
-    }
-
-    let methodCall: MethodCall;
-    try {
-      methodCall = await parseMethodCall(request);
-    } catch (error) {
-      if (error instanceof Response) {
-        logger.warn({ url: request.url }, "Invalid single-route payload");
-        try {
-          await sendFetchResponse(res, error);
-        } catch (streamError) {
-          next(streamError);
-        }
-        return;
-      }
-      logger.warn(
-        { err: error, url: request.url },
-        "Invalid single-route payload",
-      );
-      res.status(400).json({
-        error: "invalid_request",
-        message:
-          error instanceof Error ? error.message : "Invalid request payload",
-      });
-      return;
-    }
-
-    try {
-      let response: Response;
-      switch (methodCall.method) {
-        case "agent/run": {
-          const agentId = expectString(methodCall.params, "agentId");
-          const handlerRequest = createJsonRequest(request, methodCall.body);
-          response = await handleRunAgent({
-            runtime,
-            request: handlerRequest,
-            agentId,
-          });
-          break;
-        }
-        case "agent/connect": {
-          const agentId = expectString(methodCall.params, "agentId");
-          const handlerRequest = createJsonRequest(request, methodCall.body);
-          response = await handleConnectAgent({
-            runtime,
-            request: handlerRequest,
-            agentId,
-          });
-          break;
-        }
-        case "agent/stop": {
-          const agentId = expectString(methodCall.params, "agentId");
-          const threadId = expectString(methodCall.params, "threadId");
-          response = await handleStopAgent({
-            runtime,
-            request,
-            agentId,
-            threadId,
-          });
-          break;
-        }
-        case "info": {
-          response = await handleGetRuntimeInfo({ runtime, request });
-          break;
-        }
-        case "transcribe": {
-          const handlerRequest = createJsonRequest(request, methodCall.body);
-          response = await handleTranscribe({
-            runtime,
-            request: handlerRequest,
-          });
-          break;
-        }
-        default: {
-          const exhaustive: never = methodCall.method;
-          return exhaustive;
-        }
-      }
-
-      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 single-route handler",
-      );
-      next(error);
-    }
-  };
-}
-
-function normalizeSingleRoutePath(path: string): string {
-  if (!path) {
-    throw new Error(
-      "basePath must be provided for Express single-route endpoint",
-    );
-  }
-
-  if (!path.startsWith("/")) {
-    return `/${path}`;
-  }
-
-  if (path.length > 1 && path.endsWith("/")) {
-    return path.slice(0, -1);
-  }
-
-  return path;
 }