@copilotkit/runtime 1.56.2 → 1.56.4-canary.1777529757

package/src/v2/runtime/__tests__/intelligence-run-telemetry.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Telemetry lifecycle tests for `packages/runtime/src/v2/runtime/handlers/intelligence/run.ts`.
+ *
+ * intelligence/run.ts fires three events across the agent run lifecycle:
+ *   - oss.runtime.agent_execution_stream_started  (line 126, after thread lock)
+ *   - oss.runtime.agent_execution_stream_errored  (inside runner subscribe's error handler)
+ *   - oss.runtime.agent_execution_stream_ended    (inside runner subscribe's complete handler)
+ *
+ * This test verifies each fires under the expected condition. It's paired
+ * with sse-response-telemetry.test.ts which covers the SSE path of the
+ * same event names — kept separate so a regression in one file fails only
+ * its own test.
+ */
+import type { AbstractAgent, BaseEvent } from "@ag-ui/client";
+import { Observable } from "rxjs";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+import { handleRunAgent } from "../handlers/handle-run";
+import { IntelligenceAgentRunner } from "../runner/intelligence";
+import { telemetry } from "../telemetry";
+import type { CopilotRuntime } from "../core/runtime";
+
+// --- Minimal helpers (mirroring handle-run.test.ts's intelligence block) ---
+
+interface MockIntelligencePlatform {
+  [key: string]: ((...args: any[]) => any) | undefined;
+}
+
+function makeAgent(): AbstractAgent {
+  const makeClone = () =>
+    ({
+      clone: vi.fn(() => makeClone()),
+      setMessages: vi.fn(),
+      setState: vi.fn(),
+      threadId: undefined,
+      headers: {},
+      runAgent: vi.fn().mockResolvedValue(undefined),
+    }) as unknown as AbstractAgent;
+  const agent: any = {
+    clone: vi.fn(() => makeClone()),
+    setMessages: vi.fn(),
+    setState: vi.fn(),
+    threadId: undefined,
+    headers: {},
+    runAgent: vi.fn().mockResolvedValue(undefined),
+  };
+  return agent as AbstractAgent;
+}
+
+function makeIntelligenceRuntime(
+  runObservable: Observable<BaseEvent>,
+  extraPlatform: MockIntelligencePlatform = {},
+): CopilotRuntime {
+  const runner = Object.create(IntelligenceAgentRunner.prototype);
+  runner.run = vi.fn(() => runObservable);
+
+  const platform: MockIntelligencePlatform = {
+    getOrCreateThread: vi.fn().mockResolvedValue({
+      thread: { id: "thread-1", name: null },
+      created: false,
+    }),
+    getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
+    ɵacquireThreadLock: vi.fn().mockResolvedValue({
+      threadId: "thread-1",
+      runId: "run-1",
+      joinToken: "jt-1",
+    }),
+    ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
+    ɵgetClientWsUrl: vi.fn(() => "wss://runtime.example/client"),
+    ɵrenewThreadLock: vi.fn().mockResolvedValue(undefined),
+    ...extraPlatform,
+  };
+
+  return {
+    agents: Promise.resolve({ "my-agent": makeAgent() }),
+    transcriptionService: undefined,
+    beforeRequestMiddleware: undefined,
+    afterRequestMiddleware: undefined,
+    runner,
+    mode: "intelligence",
+    generateThreadNames: false,
+    intelligence: platform,
+    identifyUser: vi.fn().mockResolvedValue({ id: "user-1", name: "User One" }),
+    lockTtlSeconds: 20,
+    lockHeartbeatIntervalSeconds: 15,
+  } as unknown as CopilotRuntime;
+}
+
+function makeRunRequest(): Request {
+  return new Request("https://example.com/agent/my-agent/run", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      threadId: "thread-1",
+      runId: "run-1",
+      state: {},
+      messages: [],
+      tools: [],
+      context: [],
+      forwardedProps: {},
+    }),
+  });
+}
+
+// --- Tests ---
+
+describe("intelligence/run.ts — telemetry lifecycle", () => {
+  let captureSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    captureSpy = vi.spyOn(telemetry, "capture").mockResolvedValue(undefined);
+    // Swallow the logger.error that fires on simulated agent errors.
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    captureSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  it("fires agent_execution_stream_started once thread lock is acquired", async () => {
+    // Observable that never completes — so only stream_started should fire.
+    const never = new Observable<BaseEvent>(() => {});
+    const runtime = makeIntelligenceRuntime(never);
+
+    await handleRunAgent({
+      runtime,
+      request: makeRunRequest(),
+      agentId: "my-agent",
+    });
+
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_started",
+      {},
+    );
+    // And NOT the other two
+    expect(captureSpy).not.toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_errored",
+      expect.anything(),
+    );
+    expect(captureSpy).not.toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_ended",
+      expect.anything(),
+    );
+  });
+
+  it("fires agent_execution_stream_ended when runner.run observable completes", async () => {
+    // Observable that completes immediately.
+    const completing = new Observable<BaseEvent>((subscriber) => {
+      subscriber.complete();
+    });
+    const runtime = makeIntelligenceRuntime(completing);
+
+    await handleRunAgent({
+      runtime,
+      request: makeRunRequest(),
+      agentId: "my-agent",
+    });
+
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_started",
+      {},
+    );
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_ended",
+      {},
+    );
+  });
+
+  it("fires agent_execution_stream_errored when runner.run observable errors", async () => {
+    const failing = new Observable<BaseEvent>((subscriber) => {
+      subscriber.error(new Error("agent exploded"));
+    });
+    const runtime = makeIntelligenceRuntime(failing);
+
+    await handleRunAgent({
+      runtime,
+      request: makeRunRequest(),
+      agentId: "my-agent",
+    });
+
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_started",
+      {},
+    );
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_errored",
+      expect.objectContaining({ error: "agent exploded" }),
+    );
+  });
+});

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/__tests__/sse-response-telemetry.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Telemetry lifecycle tests for `packages/runtime/src/v2/runtime/handlers/shared/sse-response.ts`.
+ *
+ * sse-response.ts fires three events across the SSE stream lifecycle:
+ *   - oss.runtime.agent_execution_stream_started  (line 73, right after observableFactory resolves)
+ *   - oss.runtime.agent_execution_stream_errored  (inside subscribe's error handler)
+ *   - oss.runtime.agent_execution_stream_ended    (inside subscribe's complete handler)
+ *
+ * Paired with intelligence-run-telemetry.test.ts which covers the
+ * intelligence/run path of the same event names — kept separate so a
+ * regression in one source file fails only its own test.
+ */
+import { BaseEvent } from "@ag-ui/client";
+import { Observable } from "rxjs";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+import { createSseEventResponse } from "../handlers/shared/sse-response";
+import { telemetry } from "../telemetry";
+
+function makeRequest(): Request {
+  return new Request("https://example.com/agent/test/run", { method: "POST" });
+}
+
+describe("sse-response.ts — telemetry lifecycle", () => {
+  let captureSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    captureSpy = vi.spyOn(telemetry, "capture").mockResolvedValue(undefined);
+    // Swallow the console.error from SSE logError on simulated failures.
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    captureSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  it("fires agent_execution_stream_started once the observable factory resolves", async () => {
+    // Observable that never completes — only started should fire.
+    const never = new Observable<BaseEvent>(() => {});
+    createSseEventResponse({
+      request: makeRequest(),
+      observableFactory: () => never,
+    });
+
+    await vi.waitFor(() => {
+      expect(captureSpy).toHaveBeenCalledWith(
+        "oss.runtime.agent_execution_stream_started",
+        {},
+      );
+    });
+
+    expect(captureSpy).not.toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_errored",
+      expect.anything(),
+    );
+    expect(captureSpy).not.toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_ended",
+      expect.anything(),
+    );
+  });
+
+  it("fires agent_execution_stream_ended when the observable completes", async () => {
+    const completing = new Observable<BaseEvent>((subscriber) => {
+      subscriber.complete();
+    });
+    createSseEventResponse({
+      request: makeRequest(),
+      observableFactory: () => completing,
+    });
+
+    await vi.waitFor(() => {
+      expect(captureSpy).toHaveBeenCalledWith(
+        "oss.runtime.agent_execution_stream_ended",
+        {},
+      );
+    });
+
+    // started should also have fired before ended
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_started",
+      {},
+    );
+  });
+
+  it("fires agent_execution_stream_errored with the error message when the observable errors", async () => {
+    const failing = new Observable<BaseEvent>((subscriber) => {
+      subscriber.error(new Error("stream blew up"));
+    });
+    createSseEventResponse({
+      request: makeRequest(),
+      observableFactory: () => failing,
+    });
+
+    await vi.waitFor(() => {
+      expect(captureSpy).toHaveBeenCalledWith(
+        "oss.runtime.agent_execution_stream_errored",
+        expect.objectContaining({ error: "stream blew up" }),
+      );
+    });
+
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.agent_execution_stream_started",
+      {},
+    );
+  });
+});

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

@@ -2,27 +2,15 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { TelemetryClient } from "../telemetry/telemetry-client";
 import scarfClient from "../telemetry/scarf-client";
 
-const { segmentTrackMock } = vi.hoisted(() => ({
-  segmentTrackMock: vi.fn(),
-}));
-
-vi.mock("@segment/analytics-node", () => ({
-  Analytics: vi.fn().mockImplementation(() => ({
-    track: segmentTrackMock,
-  })),
-}));
-
 describe("TelemetryClient", () => {
   let scarfSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
     scarfSpy = vi.spyOn(scarfClient, "logEvent").mockResolvedValue(undefined);
-    segmentTrackMock.mockClear();
   });
 
   afterEach(() => {
     scarfSpy.mockRestore();
-    segmentTrackMock.mockClear();
   });
 
   it("sends event to scarf when sampled in", async () => {
@@ -44,33 +32,6 @@ describe("TelemetryClient", () => {
     });
   });
 
-  it("sends event with properties to segment when sampled in", async () => {
-    vi.spyOn(Math, "random").mockReturnValue(0);
-    const client = new TelemetryClient({
-      telemetryDisabled: false,
-      sampleRate: 1,
-    });
-
-    await client.capture("oss.runtime.instance_created", {
-      actionsAmount: 5,
-      endpointTypes: ["rest"],
-      endpointsAmount: 2,
-      "cloud.api_key_provided": true,
-      "cloud.public_api_key": "pk_test_123",
-    });
-
-    expect(segmentTrackMock).toHaveBeenCalledTimes(1);
-    const call = segmentTrackMock.mock.calls[0][0];
-    expect(call.event).toBe("oss.runtime.instance_created");
-    expect(call.anonymousId).toMatch(/^anon_/);
-    expect(call.properties).toMatchObject({
-      actionsAmount: 5,
-      endpointsAmount: 2,
-      "cloud.api_key_provided": true,
-      "cloud.public_api_key": "pk_test_123",
-    });
-  });
-
   it("only sends event name to scarf, not properties", async () => {
     const client = new TelemetryClient({
       telemetryDisabled: false,
@@ -106,7 +67,6 @@ describe("TelemetryClient", () => {
     });
 
     expect(scarfSpy).not.toHaveBeenCalled();
-    expect(segmentTrackMock).not.toHaveBeenCalled();
   });
 
   it("does not send events when sampled out", async () => {
@@ -124,7 +84,6 @@ describe("TelemetryClient", () => {
     });
 
     expect(scarfSpy).not.toHaveBeenCalled();
-    expect(segmentTrackMock).not.toHaveBeenCalled();
   });
 
   it("respects sample rate boundary", async () => {
@@ -139,26 +98,6 @@ describe("TelemetryClient", () => {
     expect(scarfSpy).toHaveBeenCalled();
   });
 
-  it("includes global properties in segment track call", async () => {
-    vi.spyOn(Math, "random").mockReturnValue(0);
-    const client = new TelemetryClient({
-      telemetryDisabled: false,
-      sampleRate: 1,
-    });
-
-    client.setGlobalProperties({ "copilotkit.package.name": "test-pkg" });
-
-    await client.capture("oss.runtime.instance_created", {
-      actionsAmount: 1,
-      endpointTypes: [],
-      endpointsAmount: 0,
-      "cloud.api_key_provided": false,
-    });
-
-    const call = segmentTrackMock.mock.calls[0][0];
-    expect(call.properties["copilotkit.package.name"]).toBe("test-pkg");
-  });
-
   it("throws when sample rate is out of range", () => {
     expect(() => new TelemetryClient({ sampleRate: 1.5 })).toThrow(
       "Sample rate must be between 0 and 1",

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,
@@ -61,6 +62,7 @@ import {
   type MethodCall,
 } from "../endpoints/single-route-helpers";
 import { logger } from "@copilotkit/shared";
+import { fireInstanceCreatedTelemetry } from "../telemetry/instance-created";
 
 /* ------------------------------------------------------------------------------------------------
  * Public types
@@ -113,6 +115,8 @@ export function createCopilotRuntimeHandler(
 ): CopilotRuntimeFetchHandler {
   const { runtime, basePath, mode = "multi-route", cors, hooks } = options;
 
+  fireInstanceCreatedTelemetry({ runtime });
+
   const corsConfig = resolveCorsConfig(cors);
 
   return async (request: Request): Promise<Response> => {
@@ -339,6 +343,8 @@ function dispatchRoute(
         request,
         threadId: route.threadId,
       });
+    case "cpk-debug-events":
+      return Promise.resolve(handleDebugEvents({ runtime, request }));
   }
 }
 
@@ -414,6 +420,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