@copilotkit/runtime 1.56.2 → 1.56.4

package/src/v2/runtime/__tests__/handle-threads.test.ts

@@ -10,12 +10,13 @@ import {
 import { CopilotRuntime } from "../core/runtime";
 
 describe("thread handlers", () => {
-  const createIdentifyUser = () => vi.fn().mockResolvedValue({ id: "user-1" });
+  const createIdentifyUser = () =>
+    vi.fn().mockResolvedValue({ id: "user-1", name: "User One" });
 
   const createIntelligenceRuntime = (options?: {
     identifyUser?: (
       request: Request,
-    ) => { id: string } | Promise<{ id: string }>;
+    ) => { id: string; name: string } | Promise<{ id: string; name: string }>;
     intelligence?: Record<string, unknown>;
   }) =>
     ({
@@ -92,7 +93,25 @@ describe("thread handlers", () => {
     };
     const runtime = createIntelligenceRuntime({
       intelligence,
-      identifyUser: vi.fn().mockResolvedValue({ id: "" }),
+      identifyUser: vi.fn().mockResolvedValue({ id: "", name: "User" }),
+    });
+
+    const response = await handleListThreads({
+      runtime,
+      request: new Request("https://example.com/threads?agentId=agent-1"),
+    });
+
+    expect(response.status).toBe(400);
+    expect(intelligence.listThreads).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when identifyUser returns an invalid name for thread list", async () => {
+    const intelligence = {
+      listThreads: vi.fn(),
+    };
+    const runtime = createIntelligenceRuntime({
+      intelligence,
+      identifyUser: vi.fn().mockResolvedValue({ id: "user-1", name: "" }),
     });
 
     const response = await handleListThreads({
@@ -258,7 +277,50 @@ describe("thread handlers", () => {
     };
     const runtime = createIntelligenceRuntime({
       intelligence,
-      identifyUser: vi.fn().mockResolvedValue({ id: "" }),
+      identifyUser: vi.fn().mockResolvedValue({ id: "", name: "User" }),
+    });
+
+    const updateResponse = await handleUpdateThread({
+      runtime,
+      request: createMutationRequest("/threads/thread-1", "PATCH", {
+        agentId: "agent-1",
+      }),
+      threadId: "thread-1",
+    });
+    expect(updateResponse.status).toBe(400);
+
+    const archiveResponse = await handleArchiveThread({
+      runtime,
+      request: createMutationRequest("/threads/thread-1/archive", "POST", {
+        agentId: "agent-1",
+      }),
+      threadId: "thread-1",
+    });
+    expect(archiveResponse.status).toBe(400);
+
+    const deleteResponse = await handleDeleteThread({
+      runtime,
+      request: createMutationRequest("/threads/thread-1", "DELETE", {
+        agentId: "agent-1",
+      }),
+      threadId: "thread-1",
+    });
+    expect(deleteResponse.status).toBe(400);
+
+    expect(intelligence.updateThread).not.toHaveBeenCalled();
+    expect(intelligence.archiveThread).not.toHaveBeenCalled();
+    expect(intelligence.deleteThread).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when identifyUser returns an invalid name for thread mutations", async () => {
+    const intelligence = {
+      updateThread: vi.fn(),
+      archiveThread: vi.fn(),
+      deleteThread: vi.fn(),
+    };
+    const runtime = createIntelligenceRuntime({
+      intelligence,
+      identifyUser: vi.fn().mockResolvedValue({ id: "user-1", name: "" }),
     });
 
     const updateResponse = await handleUpdateThread({

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

@@ -0,0 +1,46 @@
+/**
+ * Integration test: Hono single-route adapter (deprecated path) + telemetry.
+ *
+ * `createCopilotEndpointSingleRoute` is the legacy direct single-route entry
+ * point, superseded by `createCopilotHonoHandler({ mode: "single-route" })`
+ * but still exported.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { AbstractAgent } from "@ag-ui/client";
+
+import { telemetry } from "../telemetry";
+import { createCopilotEndpointSingleRoute } from "../endpoints/hono-single";
+import { CopilotRuntime } from "../core/runtime";
+
+function makeAgent(): AbstractAgent {
+  const a: unknown = { execute: async () => ({ events: [] }) };
+  (a as { clone: () => unknown }).clone = () => makeAgent();
+  return a as AbstractAgent;
+}
+
+describe("Hono single-route adapter — telemetry firing (integration)", () => {
+  let captureSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    captureSpy = vi.spyOn(telemetry, "capture").mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    captureSpy.mockRestore();
+  });
+
+  it("fires instance_created on handler creation", async () => {
+    const runtime = new CopilotRuntime({ agents: { default: makeAgent() } });
+    createCopilotEndpointSingleRoute({ runtime, basePath: "/api/copilotkit" });
+
+    await vi.waitFor(() => {
+      expect(captureSpy).toHaveBeenCalledWith(
+        "oss.runtime.instance_created",
+        expect.objectContaining({
+          agentsAmount: 1,
+          "cloud.api_key_provided": false,
+        }),
+      );
+    });
+  });
+});

package/src/v2/runtime/__tests__/hono-telemetry.integration.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Integration test: Hono adapter + telemetry.
+ *
+ * Asserts both ends of the path-to-production chain that the v2 refactor
+ * previously broke (2ac4a40b5, 2026-03-29):
+ *   1. `oss.runtime.instance_created` fires once per handler factory.
+ *   2. `oss.runtime.copilot_request_created` fires when a real HTTP request
+ *      flows through the handler.
+ *
+ * If either regresses, this test fails.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { AbstractAgent } from "@ag-ui/client";
+
+import { telemetry } from "../telemetry";
+import { createCopilotHonoHandler } from "../endpoints/hono";
+import { CopilotRuntime } from "../core/runtime";
+
+function makeAgent(): AbstractAgent {
+  const a: unknown = {
+    execute: async () => ({ events: [] }),
+  };
+  (a as { clone: () => unknown }).clone = () => makeAgent();
+  return a as AbstractAgent;
+}
+
+describe("Hono adapter — telemetry firing (integration)", () => {
+  let captureSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    captureSpy = vi.spyOn(telemetry, "capture").mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    captureSpy.mockRestore();
+  });
+
+  it("fires instance_created on handler creation (multi-route)", async () => {
+    const runtime = new CopilotRuntime({ agents: { default: makeAgent() } });
+    createCopilotHonoHandler({ runtime, basePath: "/" });
+
+    await vi.waitFor(() => {
+      expect(captureSpy).toHaveBeenCalledWith(
+        "oss.runtime.instance_created",
+        expect.objectContaining({
+          agentsAmount: 1,
+          actionsAmount: 0,
+          endpointsAmount: 0,
+          "cloud.api_key_provided": false,
+        }),
+      );
+    });
+  });
+
+  it("fires copilot_request_created when a real HTTP request hits the handler", async () => {
+    const runtime = new CopilotRuntime({ agents: { default: makeAgent() } });
+    const endpoint = createCopilotHonoHandler({ runtime, basePath: "/" });
+
+    await endpoint.fetch(
+      new Request("https://example.com/agent/default/run", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ messages: [], state: {}, threadId: "t1" }),
+      }),
+    );
+
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.copilot_request_created",
+      expect.objectContaining({
+        requestType: "run",
+        "cloud.api_key_provided": false,
+      }),
+    );
+  });
+
+  it("includes cloud.public_api_key on request when header is present", async () => {
+    const runtime = new CopilotRuntime({ agents: { default: makeAgent() } });
+    const endpoint = createCopilotHonoHandler({ runtime, basePath: "/" });
+
+    await endpoint.fetch(
+      new Request("https://example.com/agent/default/run", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-copilotcloud-public-api-key": "ck_pub_test_123",
+        },
+        body: JSON.stringify({ messages: [], state: {}, threadId: "t1" }),
+      }),
+    );
+
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.copilot_request_created",
+      expect.objectContaining({
+        "cloud.api_key_provided": true,
+        "cloud.public_api_key": "ck_pub_test_123",
+      }),
+    );
+  });
+});

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

@@ -10,6 +10,10 @@
 
 import { multiEndpointSuite } from "./suites/multi-endpoint.suite";
 import { singleEndpointSuite } from "./suites/single-endpoint.suite";
+import {
+  debugEventsSuite,
+  debugEventsProductionGuardSuite,
+} from "./suites/debug-events.suite";
 
 // Server factories
 import { createExpressMultiServer } from "./servers/express-multi";
@@ -37,3 +41,18 @@ singleEndpointSuite("Node", createNodeSingleServer);
 singleEndpointSuite("Fetch", (opts) =>
   Promise.resolve(createFetchDirectHandler("single-route", opts)),
 );
+
+// ─── Debug Events ───────────────────────────────────────────────────
+
+debugEventsSuite("Express", createExpressMultiServer);
+debugEventsSuite("Hono", createHonoMultiServer);
+debugEventsSuite("Node", createNodeMultiServer);
+debugEventsSuite("Fetch", (opts) =>
+  Promise.resolve(createFetchDirectHandler("multi-route", opts)),
+);
+
+debugEventsProductionGuardSuite(
+  () => createFetchDirectHandler("multi-route"),
+  "http://localhost",
+  "/api/copilotkit",
+);

package/src/v2/runtime/__tests__/integration/suites/debug-events.suite.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import type { ServerHandle } from "../servers/types";
+import { readSSEStream } from "../helpers/sse-reader";
+
+/**
+ * Envelope shape returned in the debug SSE stream.
+ */
+interface DebugEnvelope {
+  timestamp: number;
+  agentId: string;
+  threadId: string;
+  runId: string;
+  event: { type: string; [key: string]: unknown };
+}
+
+/**
+ * Parse debug envelopes from SSE payload text.
+ * Each `data:` line contains a JSON DebugEventEnvelope.
+ */
+function parseDebugEnvelopes(ssePayload: string): DebugEnvelope[] {
+  const envelopes: DebugEnvelope[] = [];
+  for (const line of ssePayload.split("\n")) {
+    if (!line.startsWith("data:")) continue;
+    const json = line.slice("data:".length).trim();
+    if (!json) continue;
+    try {
+      envelopes.push(JSON.parse(json));
+    } catch {
+      // skip malformed lines
+    }
+  }
+  return envelopes;
+}
+
+/**
+ * Read from a long-lived debug SSE stream until we see a RUN_FINISHED envelope
+ * or a timeout elapses. Returns the raw text accumulated.
+ *
+ * IMPORTANT: The debug SSE stream is long-lived and never closes on its own.
+ * We MUST use a timeout to stop reading, and cancel the reader afterwards.
+ */
+async function readDebugStream(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  stream: ReadableStream<any>,
+  opts: { waitMs?: number } = {},
+): Promise<string> {
+  const waitMs = opts.waitMs ?? 4_000;
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let output = "";
+  let stopped = false;
+
+  const timer = setTimeout(() => {
+    stopped = true;
+    reader.cancel().catch(() => {});
+  }, waitMs);
+
+  try {
+    while (!stopped) {
+      const result = await reader.read().catch(() => ({
+        done: true as const,
+        value: undefined,
+      }));
+      if (result.done) break;
+      if (result.value) {
+        output +=
+          typeof result.value === "string"
+            ? result.value
+            : decoder.decode(result.value as Uint8Array, { stream: true });
+        if (output.includes("RUN_FINISHED")) {
+          stopped = true;
+          break;
+        }
+      }
+    }
+  } finally {
+    clearTimeout(timer);
+    // Do NOT await reader.cancel() — on tee'd streams (created by response.clone()
+    // inside the fetch handler), awaiting cancel hangs indefinitely because the
+    // other tee branch is never consumed.
+    reader.cancel().catch(() => {});
+    output += decoder.decode();
+  }
+
+  return output;
+}
+
+/**
+ * Shared debug-events integration test suite.
+ *
+ * @param name      Display name, e.g. "Express"
+ * @param factory   Creates & starts the server; returns a handle
+ */
+export function debugEventsSuite(
+  name: string,
+  factory: (opts?: {
+    capturedHeaders?: Record<string, string>[];
+  }) => Promise<ServerHandle & { handler?: (r: Request) => Promise<Response> }>,
+) {
+  describe(`[${name}] Debug Events`, () => {
+    let handle: ServerHandle & { handler?: (r: Request) => Promise<Response> };
+    let doFetch: (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ) => Promise<Response>;
+
+    beforeAll(async () => {
+      handle = await factory();
+      doFetch = handle.handler
+        ? (input, init) =>
+            handle.handler!(
+              new Request(
+                typeof input === "string" || input instanceof URL
+                  ? input
+                  : input,
+                init,
+              ),
+            )
+        : fetch;
+    });
+
+    afterAll(async () => {
+      await handle?.close();
+    });
+
+    const url = (path: string) => `${handle.baseUrl}${handle.basePath}${path}`;
+
+    // ─── SSE Format + Events + Envelope Structure ────────────────────
+    // Combined into a single test to avoid orphaned debug-stream subscribers
+    // across tests (the debug SSE endpoint is long-lived and its cleanup
+    // depends on the request signal being aborted).
+
+    it("streams debug event envelopes with correct structure during an agent run", async () => {
+      const controller = new AbortController();
+
+      // Start the debug stream. For real HTTP servers, fetch blocks until
+      // the first chunk arrives, so we also start the agent run concurrently.
+      const debugFetchPromise = doFetch(url("/cpk-debug-events"), {
+        signal: controller.signal,
+      });
+
+      // Give the subscription a tick to register
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Trigger an agent run. We start it AND begin consuming its stream
+      // concurrently with reading the debug stream.
+      const runRes = await doFetch(url("/agent/default/run"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          threadId: "t-debug-1",
+          runId: "r-debug-1",
+          messages: [],
+          state: {},
+          tools: [],
+          context: [],
+          forwardedProps: {},
+        }),
+      });
+
+      // Consume the run stream and the debug stream concurrently.
+      // Both are needed: the debug stream blocks until events arrive,
+      // and the run stream must be consumed to avoid backpressure.
+      const [debugRes, runPayload] = await Promise.all([
+        debugFetchPromise,
+        readSSEStream(runRes.body!),
+      ]);
+
+      // ── SSE response format ──
+      expect(debugRes.status).toBe(200);
+      expect(debugRes.headers.get("content-type")).toContain(
+        "text/event-stream",
+      );
+
+      // Run completed — events should be buffered in the debug stream.
+      expect(runPayload).toContain("RUN_FINISHED");
+
+      // Read the debug stream (events are already in the buffer)
+      const debugPayload = await readDebugStream(debugRes.body!, {
+        waitMs: 4_000,
+      });
+
+      const envelopes = parseDebugEnvelopes(debugPayload);
+
+      // ── Events flow through ──
+      expect(envelopes.length).toBeGreaterThan(0);
+
+      const eventTypes = envelopes.map((e) => e.event.type);
+      expect(eventTypes).toContain("RUN_STARTED");
+      expect(eventTypes).toContain("RUN_FINISHED");
+
+      // ── Envelope structure ──
+      for (const envelope of envelopes) {
+        expect(typeof envelope.timestamp).toBe("number");
+        expect(envelope.timestamp).toBeGreaterThan(0);
+        expect(envelope.agentId).toBe("default");
+        expect(typeof envelope.threadId).toBe("string");
+        expect(typeof envelope.runId).toBe("string");
+        expect(envelope.event).toBeDefined();
+        expect(typeof envelope.event.type).toBe("string");
+      }
+
+      // Full event sequence
+      expect(eventTypes).toContain("TEXT_MESSAGE_START");
+      expect(eventTypes).toContain("TEXT_MESSAGE_CONTENT");
+      expect(eventTypes).toContain("TEXT_MESSAGE_END");
+
+      // Clean up: abort the request so the debug subscriber is removed
+      controller.abort();
+    }, 15_000);
+
+    // Regression guard for agentId forwarding on /connect lives in a
+    // dedicated unit test (sse-connect-agent-id.test.ts) — driving /connect
+    // through the integration runtime doesn't emit events in a
+    // test-friendly way, so the unit test feeds a synthetic observable
+    // into handleSseConnect and asserts the envelope carries the route
+    // agentId rather than the literal string "connect".
+
+    // ─── HTTP Method Validation ──────────────────────────────────────
+
+    it("POST /cpk-debug-events returns 405", async () => {
+      const res = await doFetch(url("/cpk-debug-events"), { method: "POST" });
+      expect(res.status).toBe(405);
+    });
+  });
+}
+
+/**
+ * Production guard test -- only needs the fetch-direct handler since
+ * it doesn't require a real server. Tests that NODE_ENV=production
+ * returns 404 for the debug-events endpoint.
+ */
+export function debugEventsProductionGuardSuite(
+  createHandler: () => { handler: (r: Request) => Promise<Response> },
+  baseUrl: string,
+  basePath: string,
+) {
+  describe("[Fetch] Debug Events – production guard", () => {
+    it("returns 404 when NODE_ENV=production", async () => {
+      const originalEnv = process.env.NODE_ENV;
+      try {
+        process.env.NODE_ENV = "production";
+        const { handler } = createHandler();
+        const res = await handler(
+          new Request(`${baseUrl}${basePath}/cpk-debug-events`),
+        );
+        expect(res.status).toBe(404);
+      } finally {
+        process.env.NODE_ENV = originalEnv;
+      }
+    });
+  });
+}