@copilotkit/runtime 1.56.1 → 1.56.2-canary.pin-to-send

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;
+      }
+    });
+  });
+}

package/src/v2/runtime/__tests__/runtime.test.ts

@@ -11,7 +11,9 @@ import { IntelligenceAgentRunner } from "../runner/intelligence";
 
 describe("runtime construction", () => {
   const agents = {};
-  const identifyUser = vi.fn().mockResolvedValue({ id: "user-1" });
+  const identifyUser = vi
+    .fn()
+    .mockResolvedValue({ id: "user-1", name: "User One" });
   const createMockIntelligence = (): CopilotKitIntelligence =>
     ({
       ɵgetRunnerWsUrl: vi.fn().mockReturnValue("ws://runner.example"),

package/src/v2/runtime/core/__tests__/debug-event-bus.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, vi } from "vitest";
+import { EventType } from "@ag-ui/client";
+import type { BaseEvent } from "@ag-ui/client";
+import type { DebugEventEnvelope } from "@copilotkit/shared";
+import { DebugEventBus } from "../debug-event-bus";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createBaseEvent(
+  overrides: Partial<BaseEvent> & { type: EventType } = {
+    type: EventType.RUN_STARTED,
+  },
+): BaseEvent {
+  return { type: overrides.type, ...overrides };
+}
+
+const defaultMetadata = {
+  agentId: "test-agent",
+  threadId: "thread-1",
+  runId: "run-1",
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("DebugEventBus", () => {
+  it("subscribe adds a listener and broadcast calls it with the correct envelope shape", () => {
+    const bus = new DebugEventBus();
+    const listener = vi.fn<[DebugEventEnvelope], void>();
+    const event = createBaseEvent({ type: EventType.RUN_STARTED });
+
+    bus.subscribe(listener);
+    bus.broadcast(event, defaultMetadata);
+
+    expect(listener).toHaveBeenCalledOnce();
+    const envelope = listener.mock.calls[0][0];
+    expect(envelope).toEqual(
+      expect.objectContaining({
+        agentId: "test-agent",
+        threadId: "thread-1",
+        runId: "run-1",
+        event,
+      }),
+    );
+    expect(typeof envelope.timestamp).toBe("number");
+  });
+
+  it("unsubscribe removes the listener so subsequent broadcasts don't reach it", () => {
+    const bus = new DebugEventBus();
+    const listener = vi.fn<[DebugEventEnvelope], void>();
+    const event = createBaseEvent();
+
+    const unsub = bus.subscribe(listener);
+    unsub();
+    bus.broadcast(event, defaultMetadata);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("multiple listeners all receive the same broadcast", () => {
+    const bus = new DebugEventBus();
+    const listenerA = vi.fn<[DebugEventEnvelope], void>();
+    const listenerB = vi.fn<[DebugEventEnvelope], void>();
+    const event = createBaseEvent();
+
+    bus.subscribe(listenerA);
+    bus.subscribe(listenerB);
+    bus.broadcast(event, defaultMetadata);
+
+    expect(listenerA).toHaveBeenCalledOnce();
+    expect(listenerB).toHaveBeenCalledOnce();
+    // Both receive the same envelope object
+    expect(listenerA.mock.calls[0][0]).toBe(listenerB.mock.calls[0][0]);
+  });
+
+  it("listener errors are swallowed and other listeners still receive the event", () => {
+    const bus = new DebugEventBus();
+    const failingListener = vi
+      .fn<[DebugEventEnvelope], void>()
+      .mockImplementation(() => {
+        throw new Error("boom");
+      });
+    const healthyListener = vi.fn<[DebugEventEnvelope], void>();
+    const event = createBaseEvent();
+
+    bus.subscribe(failingListener);
+    bus.subscribe(healthyListener);
+
+    // Should not throw
+    expect(() => bus.broadcast(event, defaultMetadata)).not.toThrow();
+    expect(failingListener).toHaveBeenCalledOnce();
+    expect(healthyListener).toHaveBeenCalledOnce();
+  });
+
+  it("broadcasting with no listeners does not throw", () => {
+    const bus = new DebugEventBus();
+    const event = createBaseEvent();
+
+    expect(() => bus.broadcast(event, defaultMetadata)).not.toThrow();
+  });
+
+  it("listenerCount reflects current count after subscribe and unsubscribe", () => {
+    const bus = new DebugEventBus();
+
+    expect(bus.listenerCount).toBe(0);
+
+    const unsub1 = bus.subscribe(vi.fn());
+    expect(bus.listenerCount).toBe(1);
+
+    const unsub2 = bus.subscribe(vi.fn());
+    expect(bus.listenerCount).toBe(2);
+
+    unsub1();
+    expect(bus.listenerCount).toBe(1);
+
+    unsub2();
+    expect(bus.listenerCount).toBe(0);
+  });
+
+  it("envelope has correct timestamp, agentId, threadId, runId, and the original event", () => {
+    const bus = new DebugEventBus();
+    const listener = vi.fn<[DebugEventEnvelope], void>();
+    const event = createBaseEvent({ type: EventType.STEP_STARTED });
+    const metadata = { agentId: "agent-x", threadId: "t-42", runId: "r-99" };
+
+    const before = Date.now();
+    bus.subscribe(listener);
+    bus.broadcast(event, metadata);
+    const after = Date.now();
+
+    const envelope = listener.mock.calls[0][0];
+    expect(envelope.agentId).toBe("agent-x");
+    expect(envelope.threadId).toBe("t-42");
+    expect(envelope.runId).toBe("r-99");
+    expect(envelope.event).toBe(event);
+    expect(envelope.timestamp).toBeGreaterThanOrEqual(before);
+    expect(envelope.timestamp).toBeLessThanOrEqual(after);
+  });
+
+  it("RUN_STARTED event type passthrough: envelope.event is the original object, not a copy", () => {
+    const bus = new DebugEventBus();
+    const listener = vi.fn<[DebugEventEnvelope], void>();
+    const event = createBaseEvent({ type: EventType.RUN_STARTED });
+
+    bus.subscribe(listener);
+    bus.broadcast(event, defaultMetadata);
+
+    const envelope = listener.mock.calls[0][0];
+    // Strict referential equality — the event is passed through, not cloned
+    expect(envelope.event).toBe(event);
+    expect(envelope.event.type).toBe(EventType.RUN_STARTED);
+  });
+});

package/src/v2/runtime/core/debug-event-bus.ts

@@ -0,0 +1,45 @@
+import { BaseEvent } from "@ag-ui/client";
+import { DebugEventEnvelope } from "@copilotkit/shared";
+
+export type DebugEventListener = (envelope: DebugEventEnvelope) => void;
+
+export class DebugEventBus {
+  private listeners = new Set<DebugEventListener>();
+
+  subscribe(listener: DebugEventListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  broadcast(
+    event: BaseEvent,
+    metadata: { agentId: string; threadId: string; runId: string },
+  ): void {
+    if (this.listeners.size === 0) return;
+
+    const envelope: DebugEventEnvelope = {
+      timestamp: Date.now(),
+      agentId: metadata.agentId,
+      threadId: metadata.threadId,
+      runId: metadata.runId,
+      event,
+    };
+
+    for (const listener of this.listeners) {
+      try {
+        listener(envelope);
+      } catch (err) {
+        console.warn(
+          "[DebugEventBus] Listener error suppressed:",
+          err instanceof Error ? err.message : err,
+        );
+      }
+    }
+  }
+
+  get listenerCount(): number {
+    return this.listeners.size;
+  }
+}

package/src/v2/runtime/core/fetch-handler.ts

@@ -46,6 +46,7 @@ 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 { handleDebugEvents } from "../handlers/handle-debug-events";
 import {
   handleListThreads,
   handleSubscribeToThreads,
@@ -339,6 +340,8 @@ function dispatchRoute(
         request,
         threadId: route.threadId,
       });
+    case "cpk-debug-events":
+      return Promise.resolve(handleDebugEvents({ runtime, request }));
   }
 }
 
@@ -414,6 +417,7 @@ function validateHttpMethod(
     case "info":
     case "threads/list":
     case "threads/messages":
+    case "cpk-debug-events":
       if (method === "GET") return null;
       return jsonResponse({ error: "Method not allowed" }, 405, {
         Allow: "GET",

package/src/v2/runtime/core/fetch-router.ts

@@ -74,6 +74,17 @@ function matchSegments(path: string): RouteInfo | null {
     return { method: "transcribe" };
   }
 
+  // /cpk-debug-events (1 segment)
+  // Reserved route name: the `cpk-` prefix makes collision with a
+  // user-named agent essentially impossible (the router only treats
+  // `agent/:agentId/...` patterns as agent lookups, so a bare
+  // `cpk-debug-events` segment would never fall through to one —
+  // the prefix is the real guard, not this branch's position).
+  // Handler returns 404 in production.
+  if (len >= 1 && segments[len - 1] === "cpk-debug-events") {
+    return { method: "cpk-debug-events" };
+  }
+
   // /agent/:agentId/run (3 segments)
   if (
     len >= 3 &&

package/src/v2/runtime/core/hooks.ts

@@ -43,7 +43,8 @@ export type RouteInfo =
   | { method: "threads/subscribe" }
   | { method: "threads/update"; threadId: string }
   | { method: "threads/archive"; threadId: string }
-  | { method: "threads/messages"; threadId: string };
+  | { method: "threads/messages"; threadId: string }
+  | { method: "cpk-debug-events" };
 
 /* ------------------------------------------------------------------------------------------------
  * Hook contexts

package/src/v2/runtime/core/runtime.ts

@@ -24,6 +24,7 @@ import type {
 } from "./middleware";
 import { createLogger, type CopilotRuntimeLogger } from "../../../lib/logger";
 import { TranscriptionService } from "../transcription-service/transcription-service";
+import { DebugEventBus } from "./debug-event-bus";
 import { AgentRunner } from "../runner/agent-runner";
 import { InMemoryAgentRunner } from "../runner/in-memory";
 import { IntelligenceAgentRunner } from "../runner/intelligence";
@@ -140,6 +141,7 @@ interface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares {
 
 export interface CopilotRuntimeUser {
   id: string;
+  name: string;
 }
 
 export type IdentifyUserCallback = (
@@ -189,6 +191,7 @@ export interface CopilotRuntimeLike {
   identifyUser?: IdentifyUserCallback;
   mode: RuntimeMode;
   licenseChecker?: LicenseChecker;
+  debugEventBus?: DebugEventBus;
   debug: ResolvedDebugConfig;
   debugLogger?: CopilotRuntimeLogger;
 }
@@ -218,6 +221,7 @@ abstract class BaseCopilotRuntime implements CopilotRuntimeLike {
   public mcpApps: CopilotRuntimeOptions["mcpApps"];
   public openGenerativeUI: CopilotRuntimeOptions["openGenerativeUI"];
   public licenseChecker?: LicenseChecker;
+  public readonly debugEventBus?: DebugEventBus;
   public debug: ResolvedDebugConfig;
   public debugLogger?: CopilotRuntimeLogger;
 
@@ -243,6 +247,10 @@ abstract class BaseCopilotRuntime implements CopilotRuntimeLike {
     this.mcpApps = mcpApps;
     this.openGenerativeUI = openGenerativeUI;
     this.runner = runner;
+
+    if (process.env.NODE_ENV !== "production") {
+      this.debugEventBus = new DebugEventBus();
+    }
     this.debug = resolveDebugConfig(options.debug);
     if (this.debug.enabled) {
       this.debugLogger = createLogger({
@@ -407,6 +415,10 @@ export class CopilotRuntime implements CopilotRuntimeLike {
     return this.delegate.licenseChecker;
   }
 
+  get debugEventBus() {
+    return this.delegate.debugEventBus;
+  }
+
   get debug(): ResolvedDebugConfig {
     return this.delegate.debug;
   }