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

package/src/v2/runtime/handlers/__tests__/handle-debug-events.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { handleDebugEvents } from "../handle-debug-events";
+import { DebugEventBus } from "../../core/debug-event-bus";
+import type { CopilotRuntimeLike } from "../../core/runtime";
+import type { BaseEvent } from "@ag-ui/client";
+
+/* ------------------------------------------------------------------------------------------------
+ * Helpers
+ * --------------------------------------------------------------------------------------------- */
+
+function createMockRuntime(
+  overrides: { debugEventBus?: DebugEventBus } = {},
+): Pick<CopilotRuntimeLike, "debugEventBus"> {
+  return {
+    debugEventBus: overrides.debugEventBus ?? new DebugEventBus(),
+  };
+}
+
+function createMockRequest(options: { signal?: AbortSignal } = {}): Request {
+  return new Request("http://localhost/cpk-debug-events", {
+    method: "GET",
+    signal: options.signal,
+  });
+}
+
+function createTestEvent(): BaseEvent {
+  return { type: "custom" } as BaseEvent;
+}
+
+async function readNextSSELine(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+): Promise<string> {
+  const decoder = new TextDecoder();
+  let accumulated = "";
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    accumulated += decoder.decode(value, { stream: true });
+    if (accumulated.includes("\n\n")) return accumulated;
+  }
+  return accumulated;
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Tests
+ * --------------------------------------------------------------------------------------------- */
+
+describe("handleDebugEvents", () => {
+  let savedNodeEnv: string | undefined;
+
+  beforeEach(() => {
+    savedNodeEnv = process.env.NODE_ENV;
+  });
+
+  afterEach(() => {
+    if (savedNodeEnv === undefined) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = savedNodeEnv;
+    }
+  });
+
+  it("returns 404 when NODE_ENV is production", async () => {
+    process.env.NODE_ENV = "production";
+
+    const runtime = createMockRuntime();
+    const request = createMockRequest();
+
+    const response = handleDebugEvents({
+      runtime: runtime as CopilotRuntimeLike,
+      request,
+    });
+
+    expect(response.status).toBe(404);
+    expect(await response.text()).toBe("Not Found");
+  });
+
+  it("returns 503 when debugEventBus is undefined", async () => {
+    process.env.NODE_ENV = "test";
+
+    const runtime = createMockRuntime({ debugEventBus: undefined });
+    // Remove the property so it's truly undefined
+    delete (runtime as Record<string, unknown>).debugEventBus;
+
+    const request = createMockRequest();
+
+    const response = handleDebugEvents({
+      runtime: runtime as CopilotRuntimeLike,
+      request,
+    });
+
+    expect(response.status).toBe(503);
+    expect(await response.text()).toBe("Debug event bus not available");
+  });
+
+  it("returns correct SSE response headers", () => {
+    process.env.NODE_ENV = "test";
+
+    const runtime = createMockRuntime();
+    const request = createMockRequest();
+
+    const response = handleDebugEvents({
+      runtime: runtime as CopilotRuntimeLike,
+      request,
+    });
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Content-Type")).toBe("text/event-stream");
+    expect(response.headers.get("Cache-Control")).toBe("no-cache");
+    expect(response.headers.get("Connection")).toBe("keep-alive");
+  });
+
+  it("streams events as SSE data lines when bus broadcasts", async () => {
+    process.env.NODE_ENV = "test";
+
+    const bus = new DebugEventBus();
+    const runtime = createMockRuntime({ debugEventBus: bus });
+    const request = createMockRequest();
+
+    const response = handleDebugEvents({
+      runtime: runtime as CopilotRuntimeLike,
+      request,
+    });
+
+    const reader = response.body!.getReader();
+
+    // Read and discard the initial ": connected" SSE comment
+    const comment = await readNextSSELine(reader);
+    expect(comment).toMatch(/^: connected/);
+
+    // Broadcast an event through the bus
+    bus.broadcast(createTestEvent(), {
+      agentId: "agent-1",
+      threadId: "thread-1",
+      runId: "run-1",
+    });
+
+    const line = await readNextSSELine(reader);
+
+    // The line should be "data: {json}\n\n"
+    expect(line).toMatch(/^data: \{.*\}\n\n$/);
+
+    const parsed = JSON.parse(line.replace("data: ", "").trim());
+    expect(parsed.agentId).toBe("agent-1");
+    expect(parsed.threadId).toBe("thread-1");
+    expect(parsed.runId).toBe("run-1");
+    expect(parsed.event).toEqual(createTestEvent());
+    expect(typeof parsed.timestamp).toBe("number");
+
+    reader.releaseLock();
+  });
+
+  it("unsubscribes from bus when request is aborted", async () => {
+    process.env.NODE_ENV = "test";
+
+    const bus = new DebugEventBus();
+    const runtime = createMockRuntime({ debugEventBus: bus });
+
+    const abortController = new AbortController();
+    const request = createMockRequest({ signal: abortController.signal });
+
+    handleDebugEvents({
+      runtime: runtime as CopilotRuntimeLike,
+      request,
+    });
+
+    // Before abort, the bus should have one listener
+    expect(bus.listenerCount).toBe(1);
+
+    // Abort the request
+    abortController.abort();
+
+    // After abort, the listener should be cleaned up
+    expect(bus.listenerCount).toBe(0);
+  });
+});

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

@@ -44,6 +44,7 @@ export async function handleConnectAgent({
         runtime,
         request,
         threadId: connectRequest.input.threadId,
+        runId: connectRequest.input.runId,
         lastSeenEventId: connectRequest.lastSeenEventId,
       });
     }
@@ -51,6 +52,7 @@ export async function handleConnectAgent({
     return handleSseConnect({
       runtime,
       request,
+      agentId,
       threadId: connectRequest.input.threadId,
     });
   } catch (error) {

package/src/v2/runtime/handlers/handle-debug-events.ts

@@ -0,0 +1,52 @@
+import { CopilotRuntimeLike } from "../core/runtime";
+import { DebugEventEnvelope } from "@copilotkit/shared";
+
+interface HandleDebugEventsParams {
+  runtime: CopilotRuntimeLike;
+  request: Request;
+}
+
+export function handleDebugEvents({
+  runtime,
+  request,
+}: HandleDebugEventsParams): Response {
+  if (process.env.NODE_ENV === "production") {
+    return new Response("Not Found", { status: 404 });
+  }
+
+  if (!runtime.debugEventBus) {
+    return new Response("Debug event bus not available", { status: 503 });
+  }
+
+  const bus = runtime.debugEventBus;
+  const encoder = new TextEncoder();
+  const stream = new TransformStream();
+  const writer = stream.writable.getWriter();
+
+  // Send an SSE comment immediately to flush response headers to the client.
+  // Without this, some frameworks buffer the response until actual data is written,
+  // leaving the client stuck in "connecting" state.
+  writer.write(encoder.encode(": connected\n\n")).catch(() => {});
+
+  const unsubscribe = bus.subscribe((envelope: DebugEventEnvelope) => {
+    if (request.signal.aborted) return;
+    const line = `data: ${JSON.stringify(envelope)}\n\n`;
+    writer.write(encoder.encode(line)).catch(() => {
+      // Client disconnected, will be cleaned up by abort handler.
+    });
+  });
+
+  request.signal.addEventListener("abort", () => {
+    unsubscribe();
+    writer.close().catch(() => {});
+  });
+
+  return new Response(stream.readable, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    },
+  });
+}

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

@@ -77,6 +77,7 @@ export async function handleRunAgent({
       request,
       agent,
       input,
+      agentId,
       debug: runtime.debug,
       logger: runtime.debugLogger,
     });

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

@@ -1,4 +1,9 @@
+import { BaseEvent, EventType, RunStartedEvent } from "@ag-ui/client";
 import { CopilotIntelligenceRuntimeLike } from "../../core/runtime";
+import type {
+  ConnectThreadBootstrapResponse,
+  ConnectThreadLiveResponse,
+} from "../../intelligence-platform/client";
 import { isPlatformNotFoundError } from "../shared/intelligence-utils";
 import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user";
 import { isHandlerResponse } from "../shared/json-response";
@@ -7,13 +12,64 @@ interface HandleIntelligenceConnectParams {
   runtime: CopilotIntelligenceRuntimeLike;
   request: Request;
   threadId: string;
+  runId: string;
   lastSeenEventId: string | null;
 }
 
+function stampCanonicalConnectEvent(
+  event: BaseEvent,
+  threadId: string,
+  runId: string,
+): BaseEvent {
+  const {
+    thread_id: _threadId,
+    run_id: _runId,
+    ...eventRecord
+  } = event as BaseEvent & {
+    thread_id?: unknown;
+    run_id?: unknown;
+  };
+
+  if (event.type === EventType.RUN_STARTED) {
+    const runStarted = eventRecord as RunStartedEvent;
+
+    return {
+      ...runStarted,
+      threadId,
+      runId,
+      input: {
+        ...(runStarted.input ?? {}),
+        threadId,
+        runId,
+      },
+    } as RunStartedEvent;
+  }
+
+  return {
+    ...eventRecord,
+    threadId,
+    runId,
+  } as BaseEvent;
+}
+
+function stampCanonicalConnectPlan(
+  result: ConnectThreadBootstrapResponse | ConnectThreadLiveResponse,
+  threadId: string,
+  runId: string,
+) {
+  return {
+    ...result,
+    events: result.events.map((event) =>
+      stampCanonicalConnectEvent(event, threadId, runId),
+    ),
+  };
+}
+
 export async function handleIntelligenceConnect({
   runtime,
   request,
   threadId,
+  runId,
   lastSeenEventId,
 }: HandleIntelligenceConnectParams): Promise<Response> {
   if (!runtime.intelligence) {
@@ -35,6 +91,7 @@ export async function handleIntelligenceConnect({
     const result = await runtime.intelligence.ɵconnectThread({
       threadId,
       userId: user.id,
+      runId,
       lastSeenEventId,
     });
 
@@ -44,7 +101,7 @@ export async function handleIntelligenceConnect({
       });
     }
 
-    return Response.json(result, {
+    return Response.json(stampCanonicalConnectPlan(result, threadId, runId), {
       headers: { "Cache-Control": "no-cache", Connection: "keep-alive" },
     });
   } catch (error) {

package/src/v2/runtime/handlers/shared/resolve-intelligence-user.ts

@@ -16,8 +16,11 @@ export async function resolveIntelligenceUser(params: {
     if (!isValidIdentifier(user?.id)) {
       return errorResponse("identifyUser must return a valid user id", 400);
     }
+    if (typeof user?.name !== "string" || user.name.trim().length === 0) {
+      return errorResponse("identifyUser must return a valid user name", 400);
+    }
 
-    return { id: user.id };
+    return { id: user.id, name: user.name };
   } catch (error) {
     console.error("Error identifying intelligence user:", error);
     return errorResponse("Failed to identify user", 500);

package/src/v2/runtime/handlers/shared/sse-response.ts

@@ -7,12 +7,15 @@ import {
   type CopilotRuntimeLogger,
 } from "../../../../lib/logger";
 import { telemetry } from "../../telemetry";
+import { DebugEventBus } from "../../core/debug-event-bus";
 
 interface CreateSseEventResponseParams {
   request: Request;
   observableFactory: () =>
     | Promise<Observable<BaseEvent>>
     | Observable<BaseEvent>;
+  debugEventBus?: DebugEventBus;
+  agentId?: string;
   debug?: ResolvedDebugConfig;
   /** Pre-created logger instance to avoid creating a new pino logger per request. */
   logger?: CopilotRuntimeLogger;
@@ -21,6 +24,8 @@ interface CreateSseEventResponseParams {
 export function createSseEventResponse({
   request,
   observableFactory,
+  debugEventBus,
+  agentId,
   debug,
   logger,
 }: CreateSseEventResponseParams): Response {
@@ -28,6 +33,8 @@ export function createSseEventResponse({
   const writer = stream.writable.getWriter();
   const encoder = new EventEncoder();
   let streamClosed = false;
+  let debugThreadId = "";
+  let debugRunId = "";
 
   const debugLogger = debug?.enabled
     ? (logger ??
@@ -74,6 +81,37 @@ export function createSseEventResponse({
 
     subscription = observable.subscribe({
       next: async (event) => {
+        // Extract threadId/runId from RUN_STARTED
+        if (event.type === "RUN_STARTED") {
+          const e = event as { threadId?: string; runId?: string };
+          debugThreadId = e.threadId ?? "";
+          debugRunId = e.runId ?? "";
+        }
+
+        // Broadcast to debug listeners BEFORE the stream-closed gate below.
+        // Intentional: debug subscribers (e.g. the VS Code Inspector panel)
+        // should still receive trailing events after the SSE client for
+        // this request closed its connection — they're independent
+        // consumers observing the underlying runtime, not the request's
+        // response stream.
+        //
+        // Wrapped in try/catch so a buggy debug subscriber can't propagate
+        // an exception into this observer — if the throw reached the
+        // `next` callback it would get routed to `error` by RxJS, closing
+        // the SSE stream for an unrelated reason. Log via `logError` and
+        // move on.
+        if (debugEventBus) {
+          try {
+            debugEventBus.broadcast(event, {
+              agentId: agentId ?? "",
+              threadId: debugThreadId,
+              runId: debugRunId,
+            });
+          } catch (broadcastError) {
+            logError(broadcastError);
+          }
+        }
+
         if (!request.signal.aborted && !streamClosed) {
           try {
             eventCount++;
@@ -92,6 +130,14 @@ export function createSseEventResponse({
           } catch (error) {
             if (error instanceof Error && error.name === "AbortError") {
               streamClosed = true;
+            } else {
+              // Non-abort write failures (backpressure disconnects,
+              // transform-stream exceptions, …) were previously swallowed
+              // silently — `streamClosed` stayed `false` and the next
+              // event re-attempted a broken writer. Log and mark the
+              // stream closed so we stop trying.
+              logError(error);
+              streamClosed = true;
             }
           }
         }

package/src/v2/runtime/handlers/sse/__tests__/sse-connect-agent-id.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from "vitest";
+import { of } from "rxjs";
+import { EventType, type BaseEvent } from "@ag-ui/client";
+
+vi.mock("pino", () => ({
+  default: vi.fn(() => ({
+    child: vi.fn(() => ({ debug: vi.fn() })),
+    debug: vi.fn(),
+  })),
+}));
+vi.mock("pino-pretty", () => ({ default: vi.fn() }));
+vi.mock("../../../telemetry", () => ({
+  telemetry: { capture: vi.fn() },
+}));
+
+import { handleSseConnect } from "../connect";
+import { DebugEventBus } from "../../../core/debug-event-bus";
+
+/**
+ * Regression guard for the agentId forwarding fix. `handleSseConnect` used
+ * to hardcode `agentId: "connect"` in every debug envelope emitted on
+ * /agent/:agentId/connect; the fix threads the route-resolved agentId
+ * through to `createSseEventResponse`. Reverting that change would make
+ * this test fail — the /run-based integration coverage wouldn't catch it
+ * because /run is a different code path.
+ */
+describe("handleSseConnect → debug envelope agentId", () => {
+  it("forwards the real agentId into envelopes on /connect", async () => {
+    const bus = new DebugEventBus();
+    const received: Array<{ agentId: string }> = [];
+    bus.subscribe((envelope) => {
+      received.push({ agentId: envelope.agentId });
+    });
+
+    const event: BaseEvent = {
+      type: EventType.RUN_STARTED,
+      threadId: "t-1",
+      runId: "r-1",
+    } as BaseEvent;
+
+    const fakeRuntime = {
+      debugEventBus: bus,
+      runner: {
+        connect: () => of(event),
+      },
+    } as any;
+
+    const response = handleSseConnect({
+      runtime: fakeRuntime,
+      request: new Request("http://localhost/agent/weather-agent/connect", {
+        method: "POST",
+      }),
+      agentId: "weather-agent",
+      threadId: "t-1",
+    });
+
+    // Drain to let the observable subscription fire.
+    const reader = response.body!.getReader();
+    while (true) {
+      const { done } = await reader.read();
+      if (done) break;
+    }
+
+    expect(received.length).toBeGreaterThan(0);
+    for (const env of received) {
+      // A revert to the pre-fix hardcoded "connect" would fail this
+      // positive assertion — no need for a separate not-toBe guard.
+      expect(env.agentId).toBe("weather-agent");
+    }
+  });
+});

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

@@ -5,16 +5,22 @@ import { extractForwardableHeaders } from "../header-utils";
 interface HandleSseConnectParams {
   runtime: CopilotRuntimeLike;
   request: Request;
+  agentId: string;
   threadId: string;
 }
 
 export function handleSseConnect({
   runtime,
   request,
+  agentId,
   threadId,
 }: HandleSseConnectParams): Response {
   return createSseEventResponse({
     request,
+    debugEventBus: runtime.debugEventBus,
+    // Forward the real agentId so debug envelopes reflect the agent the
+    // route resolved to — not the literal string "connect".
+    agentId,
     observableFactory: () =>
       runtime.runner.connect({
         threadId,

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

@@ -9,6 +9,7 @@ interface HandleSseRunParams {
   request: Request;
   agent: AbstractAgent;
   input: RunAgentInput;
+  agentId: string;
   debug?: ResolvedDebugConfig;
   /** Pre-created logger instance to avoid creating a new pino logger per request. */
   logger?: CopilotRuntimeLogger;
@@ -19,11 +20,14 @@ export function handleSseRun({
   request,
   agent,
   input,
+  agentId,
   debug,
   logger,
 }: HandleSseRunParams): Response {
   return createSseEventResponse({
     request,
+    debugEventBus: runtime.debugEventBus,
+    agentId,
     debug,
     logger,
     observableFactory: () =>

package/src/v2/runtime/intelligence-platform/__tests__/client.test.ts

@@ -35,7 +35,6 @@ describe("CopilotKitIntelligence", () => {
       apiUrl: "https://api.example.com",
       wsUrl: "wss://ws.example.com/socket",
       apiKey: "test-key",
-      organizationId: "org-1",
     });
   });
 
@@ -44,7 +43,6 @@ describe("CopilotKitIntelligence", () => {
       apiUrl: "https://api.example.com/",
       wsUrl: "wss://ws.example.com/socket",
       apiKey: "k",
-      organizationId: "org-1",
     });
     fetchMock.mockReturnValue(jsonResponse({ threads: [], joinCode: "" }));
     await c.listThreads({ userId: "u", agentId: "a" });
@@ -58,7 +56,6 @@ describe("CopilotKitIntelligence", () => {
       apiUrl: "https://api.example.com",
       wsUrl: "wss://ws.example.com",
       apiKey: "k",
-      organizationId: "org-1",
     });
 
     expect(c.ɵgetRunnerWsUrl()).toBe("wss://ws.example.com/runner");
@@ -71,7 +68,6 @@ describe("CopilotKitIntelligence", () => {
     const headers = fetchMock.mock.calls[0][1].headers;
     expect(headers.Authorization).toBe("Bearer test-key");
     expect(headers["Content-Type"]).toBe("application/json");
-    expect(headers["X-Organization-Id"]).toBe("org-1");
   });
 
   it("throws on non-ok response", async () => {
@@ -175,7 +171,6 @@ describe("CopilotKitIntelligence", () => {
         apiUrl: "https://api.example.com",
         wsUrl: "wss://ws.example.com/socket",
         apiKey: "test-key",
-        organizationId: "org-1",
         onThreadUpdated,
       });
       const thread = { id: "t-1", name: "Renamed" };
@@ -225,7 +220,6 @@ describe("CopilotKitIntelligence", () => {
         apiUrl: "https://api.example.com",
         wsUrl: "wss://ws.example.com/socket",
         apiKey: "test-key",
-        organizationId: "org-1",
         onThreadCreated,
       });
       const thread = { id: "t-1", name: null };
@@ -312,7 +306,6 @@ describe("CopilotKitIntelligence", () => {
         apiUrl: "https://api.example.com",
         wsUrl: "wss://ws.example.com/socket",
         apiKey: "test-key",
-        organizationId: "org-1",
         onThreadUpdated,
       });
       const thread = { id: "t-1", name: "Archived", archived: true };
@@ -353,7 +346,6 @@ describe("CopilotKitIntelligence", () => {
         apiUrl: "https://api.example.com",
         wsUrl: "wss://ws.example.com/socket",
         apiKey: "test-key",
-        organizationId: "org-1",
         onThreadDeleted,
       });
       fetchMock.mockReturnValue(jsonResponse(undefined));
@@ -376,7 +368,6 @@ describe("CopilotKitIntelligence", () => {
         apiUrl: "https://api.example.com",
         wsUrl: "wss://ws.example.com/socket",
         apiKey: "test-key",
-        organizationId: "org-1",
         onThreadDeleted: () => {
           throw new Error("callback exploded");
         },
@@ -503,7 +494,6 @@ describe("CopilotKitIntelligence", () => {
         apiUrl: "https://api.example.com",
         wsUrl: "wss://ws.example.com/socket",
         apiKey: "test-key",
-        organizationId: "org-1",
         onThreadUpdated: configCb,
       });
       client.onThreadUpdated(runtimeCb);
@@ -554,6 +544,7 @@ describe("CopilotKitIntelligence", () => {
       const result = await client.ɵconnectThread({
         threadId: "t-1",
         userId: "user-1",
+        runId: "run-1",
         lastSeenEventId: "event-1",
       });
 
@@ -563,6 +554,7 @@ describe("CopilotKitIntelligence", () => {
       expect(opts.method).toBe("POST");
       expect(JSON.parse(opts.body)).toEqual({
         userId: "user-1",
+        runId: "run-1",
         lastSeenEventId: "event-1",
       });
     });
@@ -571,13 +563,22 @@ describe("CopilotKitIntelligence", () => {
       const payload = {
         mode: "bootstrap",
         latestEventId: "event-2",
-        events: [{ type: "MESSAGES_SNAPSHOT", messages: [] }],
+        events: [
+          {
+            type: "RUN_STARTED",
+            threadId: "t-1",
+            run_id: "backend-run-1",
+            input: { messages: [] },
+          },
+          { type: "RUN_FINISHED" },
+        ],
       };
       fetchMock.mockReturnValue(jsonResponse(payload));
 
       const result = await client.ɵconnectThread({
         threadId: "t-1",
         userId: "user-1",
+        runId: "run-1",
         lastSeenEventId: "event-1",
       });
 
@@ -596,6 +597,7 @@ describe("CopilotKitIntelligence", () => {
       const result = await client.ɵconnectThread({
         threadId: "t-1",
         userId: "user-1",
+        runId: "run-1",
         lastSeenEventId: "event-2",
       });