@copilotkit/runtime 1.56.2 → 1.56.4-canary.1777529757

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

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

@@ -147,15 +147,21 @@ export function createCopilotExpressHandler({
     router.post(normalizedBase, expressHandler);
     router.options(normalizedBase, expressHandler);
   } else if (normalizedBase === "/") {
-    router.all("*", expressHandler);
+    router.all(/.*/, expressHandler);
   } else {
-    router.all(`${normalizedBase}/*`, expressHandler);
-    router.all(normalizedBase, expressHandler);
+    router.all(
+      new RegExp(`^${escapeRegExp(normalizedBase)}(\\/.*)?$`),
+      expressHandler,
+    );
   }
 
   return router;
 }
 
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function normalizeBasePath(path: string): string {
   if (!path) {
     throw new Error("basePath must be provided for Express endpoint");

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

@@ -43,14 +43,15 @@ export async function handleConnectAgent({
       return handleIntelligenceConnect({
         runtime,
         request,
+        agentId,
         threadId: connectRequest.input.threadId,
-        lastSeenEventId: connectRequest.lastSeenEventId,
       });
     }
 
     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,20 +1,33 @@
 import { CopilotIntelligenceRuntimeLike } from "../../core/runtime";
-import { isPlatformNotFoundError } from "../shared/intelligence-utils";
+import { getPlatformErrorStatus } from "../shared/intelligence-utils";
 import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user";
 import { isHandlerResponse } from "../shared/json-response";
 
+/**
+ * Builds browser-facing realtime connection metadata owned by the runtime.
+ */
+function buildRealtimeConnectionInfo(params: {
+  clientUrl: string;
+  threadId: string;
+}): { clientUrl: string; topic: string } {
+  return {
+    clientUrl: params.clientUrl,
+    topic: `thread:${params.threadId}`,
+  };
+}
+
 interface HandleIntelligenceConnectParams {
   runtime: CopilotIntelligenceRuntimeLike;
   request: Request;
+  agentId: string;
   threadId: string;
-  lastSeenEventId: string | null;
 }
 
 export async function handleIntelligenceConnect({
   runtime,
   request,
+  agentId,
   threadId,
-  lastSeenEventId,
 }: HandleIntelligenceConnectParams): Promise<Response> {
   if (!runtime.intelligence) {
     return Response.json(
@@ -35,7 +48,7 @@ export async function handleIntelligenceConnect({
     const result = await runtime.intelligence.ɵconnectThread({
       threadId,
       userId: user.id,
-      lastSeenEventId,
+      agentId,
     });
 
     if (result === null) {
@@ -44,14 +57,38 @@ export async function handleIntelligenceConnect({
       });
     }
 
-    return Response.json(result, {
-      headers: { "Cache-Control": "no-cache", Connection: "keep-alive" },
-    });
+    return Response.json(
+      {
+        threadId: result.threadId,
+        joinToken: result.joinToken,
+        realtime: buildRealtimeConnectionInfo({
+          clientUrl: runtime.intelligence.ɵgetClientWsUrl(),
+          threadId: result.threadId,
+        }),
+      },
+      {
+        headers: { "Cache-Control": "no-cache", Connection: "keep-alive" },
+      },
+    );
   } catch (error) {
-    if (isPlatformNotFoundError(error)) {
-      return new Response(null, {
-        status: 204,
-      });
+    const status = getPlatformErrorStatus(error);
+    if (
+      status === 400 ||
+      status === 401 ||
+      status === 403 ||
+      status === 404 ||
+      status === 409
+    ) {
+      return Response.json(
+        {
+          error: "Connect request rejected",
+          message:
+            error instanceof Error
+              ? error.message
+              : "Intelligence platform rejected the connect request",
+        },
+        { status },
+      );
     }
 
     console.error("Connect plan not available:", error);

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

@@ -1,10 +1,53 @@
-import { AbstractAgent, Message, RunAgentInput } from "@ag-ui/client";
+import {
+  AbstractAgent,
+  BaseEvent,
+  EventType,
+  Message,
+  RunAgentInput,
+} from "@ag-ui/client";
 import { CopilotIntelligenceRuntimeLike } from "../../core/runtime";
 import { generateThreadNameForNewThread } from "./thread-names";
 import { logger } from "@copilotkit/shared";
 import { telemetry } from "../../telemetry";
 import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user";
 import { isHandlerResponse } from "../shared/json-response";
+import { AgentRunnerRunRequest } from "../../runner/agent-runner";
+import { Observable } from "rxjs";
+
+/**
+ * Builds browser-facing realtime connection metadata owned by the runtime.
+ */
+function buildRealtimeConnectionInfo(params: {
+  clientUrl: string;
+  threadId: string;
+}): { clientUrl: string; topic: string } {
+  return {
+    clientUrl: params.clientUrl,
+    topic: `thread:${params.threadId}`,
+  };
+}
+
+interface RunnerStartupBoundary {
+  events: Observable<BaseEvent>;
+  startup: Promise<void>;
+}
+
+interface RunnerWithStartupBoundary {
+  runWithStartupBoundary(request: AgentRunnerRunRequest): RunnerStartupBoundary;
+}
+
+function hasRunnerStartupBoundary(
+  runner: CopilotIntelligenceRuntimeLike["runner"],
+): runner is CopilotIntelligenceRuntimeLike["runner"] &
+  RunnerWithStartupBoundary {
+  const candidate = runner as { runWithStartupBoundary?: unknown };
+
+  return (
+    typeof candidate.runWithStartupBoundary === "function" &&
+    (Object.prototype.hasOwnProperty.call(runner, "runWithStartupBoundary") ||
+      Object.prototype.hasOwnProperty.call(runner, "threads"))
+  );
+}
 
 interface HandleIntelligenceRunParams {
   runtime: CopilotIntelligenceRuntimeLike;
@@ -66,20 +109,23 @@ export async function handleIntelligenceRun({
     );
   }
 
-  let joinCode: string | undefined;
+  let canonicalThreadId = input.threadId;
+  let canonicalRunId = input.runId;
   let joinToken: string | undefined;
   try {
     const lockResult = await runtime.intelligence.ɵacquireThreadLock({
       threadId: input.threadId,
       runId: input.runId,
       userId,
+      agentId,
       ...(runtime.lockKeyPrefix !== undefined
         ? { lockKeyPrefix: runtime.lockKeyPrefix }
         : {}),
       ttlSeconds: runtime.lockTtlSeconds,
     });
+    canonicalThreadId = lockResult.threadId;
+    canonicalRunId = lockResult.runId;
     joinToken = lockResult.joinToken;
-    joinCode = lockResult.joinCode;
   } catch (error) {
     logger.error("Thread lock denied:", error);
     return Response.json(
@@ -90,21 +136,42 @@ export async function handleIntelligenceRun({
     );
   }
 
-  if (!joinToken) {
+  const cleanupLock = (reason: string): Promise<void> =>
+    runtime.intelligence
+      .ɵcleanupThreadLock({
+        threadId: canonicalThreadId || input.threadId,
+        runId: canonicalRunId || input.runId,
+      })
+      .catch((cleanupError) => {
+        logger.error(
+          { err: cleanupError, reason },
+          "Failed to cleanup thread lock",
+        );
+      });
+
+  if (!canonicalThreadId || !canonicalRunId || !joinToken) {
+    await cleanupLock("malformed-lock-response");
     return Response.json(
       {
-        error: "Join token not available",
-        message: "Intelligence platform did not return a join token",
+        error: "Run connection credentials not available",
+        message:
+          "Intelligence platform did not return canonical threadId, runId, and joinToken",
       },
       { status: 502 },
     );
   }
 
+  const canonicalInput: RunAgentInput = {
+    ...input,
+    threadId: canonicalThreadId,
+    runId: canonicalRunId,
+  };
+
   let persistedInputMessages: Message[] | undefined;
   if (Array.isArray(input.messages)) {
     try {
       const history = await runtime.intelligence.getThreadMessages({
-        threadId: input.threadId,
+        threadId: canonicalThreadId,
       });
       const historicMessageIds = new Set(
         history.messages.map((message) => message.id),
@@ -114,6 +181,7 @@ export async function handleIntelligenceRun({
       );
     } catch (error) {
       logger.error("Thread history lookup failed:", error);
+      await cleanupLock("thread-history-lookup-failed");
       return Response.json(
         {
           error: "Thread history lookup failed",
@@ -130,8 +198,8 @@ export async function handleIntelligenceRun({
   heartbeatTimer = setInterval(() => {
     runtime.intelligence
       .ɵrenewThreadLock({
-        threadId: input.threadId,
-        runId: input.runId,
+        threadId: canonicalThreadId,
+        runId: canonicalRunId,
         ttlSeconds: runtime.lockTtlSeconds,
         ...(runtime.lockKeyPrefix !== undefined
           ? { lockKeyPrefix: runtime.lockKeyPrefix }
@@ -139,6 +207,15 @@ export async function handleIntelligenceRun({
       })
       .catch((err) => {
         logger.error("Failed to renew thread lock:", err);
+        clearHeartbeat();
+        try {
+          agent.abortRun();
+        } catch (abortError) {
+          logger.error(
+            "Failed to abort agent after lock renewal failure:",
+            abortError,
+          );
+        }
       });
   }, runtime.lockHeartbeatIntervalSeconds * 1_000);
 
@@ -149,19 +226,48 @@ export async function handleIntelligenceRun({
     }
   };
 
-  runtime.runner
-    .run({
-      threadId: input.threadId,
-      agent,
-      input,
-      ...(persistedInputMessages !== undefined
-        ? { persistedInputMessages }
-        : {}),
-      ...(joinCode ? { joinCode } : {}),
-    })
-    .subscribe({
+  const runStarted = { current: false };
+  let immediateStartupErrorMessage: string | undefined;
+  let immediateStartupCleanup: Promise<void> | undefined;
+
+  const runRequest: AgentRunnerRunRequest = {
+    threadId: canonicalThreadId,
+    agent,
+    input: canonicalInput,
+    ...(persistedInputMessages !== undefined ? { persistedInputMessages } : {}),
+  };
+
+  try {
+    const runStart = hasRunnerStartupBoundary(runtime.runner)
+      ? runtime.runner.runWithStartupBoundary(runRequest)
+      : {
+          events: runtime.runner.run(runRequest),
+          startup: Promise.resolve(),
+        };
+
+    runStart.events.subscribe({
+      next: (event: BaseEvent) => {
+        if (event.type === EventType.RUN_STARTED) {
+          runStarted.current = true;
+        }
+        if (event.type === EventType.RUN_ERROR && !runStarted.current) {
+          clearHeartbeat();
+          immediateStartupErrorMessage =
+            "message" in event && typeof event.message === "string"
+              ? event.message
+              : "Runner failed before the run started";
+          immediateStartupCleanup = cleanupLock("runner-start-failed");
+        }
+      },
       error: (error) => {
         clearHeartbeat();
+        if (!runStarted.current) {
+          immediateStartupErrorMessage =
+            error instanceof Error ? error.message : String(error);
+          immediateStartupCleanup = cleanupLock("runner-start-error");
+        } else {
+          cleanupLock("runner-error");
+        }
         telemetry.capture("oss.runtime.agent_execution_stream_errored", {
           error: error instanceof Error ? error.message : String(error),
         });
@@ -173,8 +279,43 @@ export async function handleIntelligenceRun({
       },
     });
 
+    await runStart.startup;
+  } catch (error) {
+    clearHeartbeat();
+    await (immediateStartupCleanup ?? cleanupLock("runner-start-threw"));
+    logger.error("Error starting agent runner:", error);
+    return Response.json(
+      {
+        error: "Failed to start runner",
+        message: error instanceof Error ? error.message : String(error),
+      },
+      { status: 502 },
+    );
+  }
+
+  if (immediateStartupErrorMessage) {
+    await immediateStartupCleanup;
+    return Response.json(
+      {
+        error: "Failed to start runner",
+        message: immediateStartupErrorMessage,
+      },
+      { status: 502 },
+    );
+  }
+
+  // IntelligenceAgentRunner resolves this boundary after Phoenix channel join.
+  // Other runner implementations fall back to construction/subscription errors.
   return Response.json(
-    { joinToken },
+    {
+      threadId: canonicalThreadId,
+      runId: canonicalRunId,
+      joinToken,
+      realtime: buildRealtimeConnectionInfo({
+        clientUrl: runtime.intelligence.ɵgetClientWsUrl(),
+        threadId: canonicalThreadId,
+      }),
+    },
     {
       headers: { "Cache-Control": "no-cache" },
     },