@copilotkit/runtime 1.55.0-next.8 → 1.55.0

package/src/v2/runtime/__tests__/integration/helpers/create-test-runtime.ts

@@ -0,0 +1,15 @@
+import { CopilotRuntime } from "../../../core/runtime";
+import { createFakeAgent, createTestRunner } from "./test-agent";
+
+/**
+ * Creates a CopilotRuntime configured with a fake agent for testing.
+ * No API keys required.
+ */
+export function createTestRuntime(
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+) {
+  return new CopilotRuntime({
+    agents: { default: createFakeAgent(opts) as any },
+    runner: createTestRunner(),
+  });
+}

package/src/v2/runtime/__tests__/integration/helpers/sse-reader.ts

@@ -0,0 +1,45 @@
+/**
+ * Read an SSE response stream to a string.
+ * Stops when RUN_FINISHED is seen or after maxChunks reads.
+ */
+export async function readSSEStream(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  stream: ReadableStream<any>,
+  opts: { maxChunks?: number } = {},
+): Promise<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let output = "";
+  const maxChunks = opts.maxChunks ?? 30;
+
+  for (let i = 0; i < maxChunks; i++) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      // The stream may emit strings (direct fetch handler) or Uint8Array (real HTTP)
+      output +=
+        typeof value === "string"
+          ? value
+          : decoder.decode(value, { stream: true });
+      if (output.includes("RUN_FINISHED")) break;
+    }
+  }
+
+  await reader.cancel();
+  output += decoder.decode();
+  return output;
+}
+
+/**
+ * Extract event type names from an SSE payload string.
+ * Matches "type":"EVENT_NAME" patterns in the data lines.
+ */
+export function extractEventTypes(ssePayload: string): string[] {
+  const types: string[] = [];
+  for (const line of ssePayload.split("\n")) {
+    if (!line.startsWith("data:")) continue;
+    const match = line.match(/"type"\s*:\s*"([^"]+)"/);
+    if (match?.[1]) types.push(match[1]);
+  }
+  return types;
+}

package/src/v2/runtime/__tests__/integration/helpers/test-agent.ts

@@ -0,0 +1,58 @@
+import { InMemoryAgentRunner } from "../../../runner/in-memory";
+
+/**
+ * Creates a fake agent that emits a deterministic sequence of AG-UI events.
+ * Requires no API keys — purely in-memory.
+ */
+export function createFakeAgent(
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+) {
+  return {
+    clone: () => {
+      const instance = {
+        setMessages: () => undefined,
+        setState: () => undefined,
+        threadId: "thread",
+        headers: {},
+        runAgent: async (
+          input: { runId: string },
+          { onEvent }: { onEvent: (payload: { event: unknown }) => void },
+        ) => {
+          // Capture headers if requested
+          if (opts.capturedHeaders) {
+            opts.capturedHeaders.push({ ...instance.headers });
+          }
+
+          onEvent({
+            event: {
+              type: "RUN_STARTED",
+              runId: input.runId,
+              input: { runId: input.runId },
+            },
+          });
+          onEvent({
+            event: { type: "TEXT_MESSAGE_START", messageId: "m1" },
+          });
+          onEvent({
+            event: {
+              type: "TEXT_MESSAGE_CONTENT",
+              messageId: "m1",
+              delta: "Hello from test",
+            },
+          });
+          onEvent({
+            event: { type: "TEXT_MESSAGE_END", messageId: "m1" },
+          });
+          onEvent({
+            event: { type: "RUN_FINISHED", runId: input.runId },
+          });
+        },
+      };
+      return instance;
+    },
+  };
+}
+
+export function createTestRunner() {
+  return new InMemoryAgentRunner();
+}

package/src/v2/runtime/__tests__/integration/node-servers.integration.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Integration tests for all Node.js-compatible server runtimes.
+ *
+ * Runs the same multi-endpoint and single-endpoint test suites against:
+ *   - Express (multi + single)
+ *   - Hono via @hono/node-server (multi + single)
+ *   - Raw Node.js http (multi + single)
+ *   - Direct fetch handler — no HTTP server (multi + single)
+ */
+
+import { multiEndpointSuite } from "./suites/multi-endpoint.suite";
+import { singleEndpointSuite } from "./suites/single-endpoint.suite";
+
+// Server factories
+import { createExpressMultiServer } from "./servers/express-multi";
+import { createExpressSingleServer } from "./servers/express-single";
+import { createHonoMultiServer } from "./servers/hono-multi";
+import { createHonoSingleServer } from "./servers/hono-single";
+import { createNodeMultiServer } from "./servers/node-multi";
+import { createNodeSingleServer } from "./servers/node-single";
+import { createFetchDirectHandler } from "./servers/fetch-direct";
+
+// ─── Multi-Endpoint ──────────────────────────────────────────────────
+
+multiEndpointSuite("Express", createExpressMultiServer);
+multiEndpointSuite("Hono", createHonoMultiServer);
+multiEndpointSuite("Node", createNodeMultiServer);
+multiEndpointSuite("Fetch", (opts) =>
+  Promise.resolve(createFetchDirectHandler("multi-route", opts)),
+);
+
+// ─── Single-Endpoint ─────────────────────────────────────────────────
+
+singleEndpointSuite("Express", createExpressSingleServer);
+singleEndpointSuite("Hono", createHonoSingleServer);
+singleEndpointSuite("Node", createNodeSingleServer);
+singleEndpointSuite("Fetch", (opts) =>
+  Promise.resolve(createFetchDirectHandler("single-route", opts)),
+);

package/src/v2/runtime/__tests__/integration/servers/express-multi.ts

@@ -0,0 +1,35 @@
+import express from "express";
+import type { AddressInfo } from "node:net";
+import { createCopilotExpressHandler } from "../../../endpoints/express";
+import { createTestRuntime } from "../helpers/create-test-runtime";
+import type { ServerHandle } from "./types";
+
+const BASE_PATH = "/api/copilotkit";
+
+export async function createExpressMultiServer(
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+): Promise<ServerHandle> {
+  const runtime = createTestRuntime(opts);
+  const app = express();
+  app.use(
+    createCopilotExpressHandler({
+      runtime,
+      basePath: BASE_PATH,
+      cors: true,
+    }),
+  );
+
+  return new Promise((resolve) => {
+    const server = app.listen(0, () => {
+      const { port } = server.address() as AddressInfo;
+      resolve({
+        baseUrl: `http://localhost:${port}`,
+        basePath: BASE_PATH,
+        close: () =>
+          new Promise<void>((res, rej) =>
+            server.close((err) => (err ? rej(err) : res())),
+          ),
+      });
+    });
+  });
+}

package/src/v2/runtime/__tests__/integration/servers/express-single.ts

@@ -0,0 +1,36 @@
+import express from "express";
+import type { AddressInfo } from "node:net";
+import { createCopilotExpressHandler } from "../../../endpoints/express";
+import { createTestRuntime } from "../helpers/create-test-runtime";
+import type { ServerHandle } from "./types";
+
+const BASE_PATH = "/api/copilotkit";
+
+export async function createExpressSingleServer(
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+): Promise<ServerHandle> {
+  const runtime = createTestRuntime(opts);
+  const app = express();
+  app.use(
+    createCopilotExpressHandler({
+      runtime,
+      basePath: BASE_PATH,
+      mode: "single-route",
+      cors: true,
+    }),
+  );
+
+  return new Promise((resolve) => {
+    const server = app.listen(0, () => {
+      const { port } = server.address() as AddressInfo;
+      resolve({
+        baseUrl: `http://localhost:${port}`,
+        basePath: BASE_PATH,
+        close: () =>
+          new Promise<void>((res, rej) =>
+            server.close((err) => (err ? rej(err) : res())),
+          ),
+      });
+    });
+  });
+}

package/src/v2/runtime/__tests__/integration/servers/fetch-direct.ts

@@ -0,0 +1,39 @@
+import { createCopilotRuntimeHandler } from "../../../core/fetch-handler";
+import { createTestRuntime } from "../helpers/create-test-runtime";
+import type { ServerHandle } from "./types";
+
+const BASE_PATH = "/api/copilotkit";
+const SYNTHETIC_ORIGIN = "http://localhost";
+
+/**
+ * Creates a "server" that invokes the fetch handler directly — no HTTP server.
+ * This tests the core fetch handler in isolation.
+ *
+ * We monkey-patch `globalThis.fetch` for the duration of the test so that
+ * standard `fetch(url)` calls route through the handler. Instead, the returned
+ * ServerHandle has a `baseUrl` that test suites can use, and the suites use
+ * normal `fetch()` which goes over the network for real servers. For the direct
+ * handler, callers should use `fetchDirect` exported alongside the factory.
+ */
+export function createFetchDirectHandler(
+  mode: "multi-route" | "single-route",
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+): ServerHandle & { handler: (request: Request) => Promise<Response> } {
+  const runtime = createTestRuntime(opts);
+
+  const handler = createCopilotRuntimeHandler({
+    runtime,
+    basePath: BASE_PATH,
+    mode,
+    cors: true,
+  });
+
+  return {
+    baseUrl: SYNTHETIC_ORIGIN,
+    basePath: BASE_PATH,
+    handler,
+    close: async () => {
+      /* no-op — no server to close */
+    },
+  };
+}

package/src/v2/runtime/__tests__/integration/servers/hono-multi.ts

@@ -0,0 +1,30 @@
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import type { AddressInfo } from "node:net";
+import { createCopilotHonoHandler } from "../../../endpoints/hono";
+import { createTestRuntime } from "../helpers/create-test-runtime";
+import type { ServerHandle } from "./types";
+
+const BASE_PATH = "/api/copilotkit";
+
+export async function createHonoMultiServer(
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+): Promise<ServerHandle> {
+  const runtime = createTestRuntime(opts);
+  const app = new Hono();
+  app.route("/", createCopilotHonoHandler({ runtime, basePath: BASE_PATH }));
+
+  return new Promise((resolve) => {
+    const server = serve({ fetch: app.fetch, port: 0 }, () => {
+      const { port } = server.address() as AddressInfo;
+      resolve({
+        baseUrl: `http://localhost:${port}`,
+        basePath: BASE_PATH,
+        close: () =>
+          new Promise<void>((res, rej) =>
+            server.close((err) => (err ? rej(err) : res())),
+          ),
+      });
+    });
+  });
+}

package/src/v2/runtime/__tests__/integration/servers/hono-single.ts

@@ -0,0 +1,37 @@
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import type { AddressInfo } from "node:net";
+import { createCopilotHonoHandler } from "../../../endpoints/hono";
+import { createTestRuntime } from "../helpers/create-test-runtime";
+import type { ServerHandle } from "./types";
+
+const BASE_PATH = "/api/copilotkit";
+
+export async function createHonoSingleServer(
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+): Promise<ServerHandle> {
+  const runtime = createTestRuntime(opts);
+  const app = new Hono();
+  app.route(
+    "/",
+    createCopilotHonoHandler({
+      runtime,
+      basePath: BASE_PATH,
+      mode: "single-route",
+    }),
+  );
+
+  return new Promise((resolve) => {
+    const server = serve({ fetch: app.fetch, port: 0 }, () => {
+      const { port } = server.address() as AddressInfo;
+      resolve({
+        baseUrl: `http://localhost:${port}`,
+        basePath: BASE_PATH,
+        close: () =>
+          new Promise<void>((res, rej) =>
+            server.close((err) => (err ? rej(err) : res())),
+          ),
+      });
+    });
+  });
+}

package/src/v2/runtime/__tests__/integration/servers/node-multi.ts

@@ -0,0 +1,45 @@
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { createCopilotRuntimeHandler } from "../../../core/fetch-handler";
+import { createCopilotNodeHandler } from "../../../endpoints/node-fetch-handler";
+import { createTestRuntime } from "../helpers/create-test-runtime";
+import type { ServerHandle } from "./types";
+
+const BASE_PATH = "/api/copilotkit";
+
+export async function createNodeMultiServer(
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+): Promise<ServerHandle> {
+  const runtime = createTestRuntime(opts);
+
+  const handler = createCopilotRuntimeHandler({
+    runtime,
+    basePath: BASE_PATH,
+    cors: true,
+  });
+
+  const nodeHandler = createCopilotNodeHandler(handler);
+
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    if (url.pathname.startsWith(BASE_PATH)) {
+      return nodeHandler(req, res);
+    }
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+  });
+
+  return new Promise((resolve) => {
+    server.listen(0, () => {
+      const { port } = server.address() as AddressInfo;
+      resolve({
+        baseUrl: `http://localhost:${port}`,
+        basePath: BASE_PATH,
+        close: () =>
+          new Promise<void>((res, rej) =>
+            server.close((err) => (err ? rej(err) : res())),
+          ),
+      });
+    });
+  });
+}

package/src/v2/runtime/__tests__/integration/servers/node-single.ts

@@ -0,0 +1,46 @@
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { createCopilotRuntimeHandler } from "../../../core/fetch-handler";
+import { createCopilotNodeHandler } from "../../../endpoints/node-fetch-handler";
+import { createTestRuntime } from "../helpers/create-test-runtime";
+import type { ServerHandle } from "./types";
+
+const BASE_PATH = "/api/copilotkit";
+
+export async function createNodeSingleServer(
+  opts: { capturedHeaders?: Record<string, string>[] } = {},
+): Promise<ServerHandle> {
+  const runtime = createTestRuntime(opts);
+
+  const handler = createCopilotRuntimeHandler({
+    runtime,
+    basePath: BASE_PATH,
+    mode: "single-route",
+    cors: true,
+  });
+
+  const nodeHandler = createCopilotNodeHandler(handler);
+
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    if (url.pathname.startsWith(BASE_PATH)) {
+      return nodeHandler(req, res);
+    }
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+  });
+
+  return new Promise((resolve) => {
+    server.listen(0, () => {
+      const { port } = server.address() as AddressInfo;
+      resolve({
+        baseUrl: `http://localhost:${port}`,
+        basePath: BASE_PATH,
+        close: () =>
+          new Promise<void>((res, rej) =>
+            server.close((err) => (err ? rej(err) : res())),
+          ),
+      });
+    });
+  });
+}

package/src/v2/runtime/__tests__/integration/servers/types.ts

@@ -0,0 +1,18 @@
+export interface ServerHandle {
+  /** Base URL, e.g. "http://localhost:54321" */
+  baseUrl: string;
+  /** CopilotKit basePath, e.g. "/api/copilotkit" */
+  basePath: string;
+  /** Shut down the server */
+  close: () => Promise<void>;
+}
+
+export type ServerFactory = (opts?: {
+  capturedHeaders?: Record<string, string>[];
+}) => Promise<ServerHandle>;
+
+/**
+ * A request function compatible with both real HTTP and direct fetch handler invocation.
+ * For real servers this is just global `fetch`. For direct fetch handlers it calls the handler directly.
+ */
+export type RequestFn = typeof fetch;