@copilotkit/runtime 1.56.3 → 1.56.4

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

@@ -1,6 +1,6 @@
 import { Observable } from "rxjs";
 import { describe, it, expect, vi } from "vitest";
-import { AbstractAgent, HttpAgent } from "@ag-ui/client";
+import { AbstractAgent, BaseEvent, EventType, HttpAgent } from "@ag-ui/client";
 import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
 import { handleRunAgent } from "../handlers/handle-run";
 import { CopilotRuntime } from "../core/runtime";
@@ -285,7 +285,7 @@ describe("handleRunAgent", () => {
     expect(useSpy).not.toHaveBeenCalled();
   });
 
-  describe("IntelligenceAgentRunner join code path", () => {
+  describe("IntelligenceAgentRunner realtime credentials path", () => {
     /** Loose mock type for CopilotKitIntelligence — avoids `as any` while the class has private fields. */
     interface MockIntelligencePlatform {
       [key: string]: ((...args: any[]) => any) | undefined;
@@ -296,6 +296,8 @@ describe("handleRunAgent", () => {
       platform?: MockIntelligencePlatform,
       options?: {
         generateThreadNames?: boolean;
+        lockHeartbeatIntervalSeconds?: number;
+        lockTtlSeconds?: number;
         identifyUser?: (
           request: Request,
         ) =>
@@ -318,7 +320,13 @@ describe("handleRunAgent", () => {
         runner,
         mode: "intelligence",
         generateThreadNames: options?.generateThreadNames ?? false,
-        intelligence: platform,
+        lockHeartbeatIntervalSeconds:
+          options?.lockHeartbeatIntervalSeconds ?? 15,
+        lockTtlSeconds: options?.lockTtlSeconds ?? 20,
+        intelligence: {
+          ɵgetClientWsUrl: vi.fn(() => "wss://runtime.example/client"),
+          ...platform,
+        },
         identifyUser:
           options?.identifyUser ??
           vi.fn().mockResolvedValue({ id: "user-1", name: "User One" }),
@@ -331,6 +339,7 @@ describe("handleRunAgent", () => {
           clone: vi.fn(() => createClone()),
           setMessages: vi.fn(),
           setState: vi.fn(),
+          abortRun: vi.fn(),
           threadId: undefined,
           headers: {},
           runAgent: vi.fn().mockResolvedValue(undefined),
@@ -340,6 +349,7 @@ describe("handleRunAgent", () => {
         clone: vi.fn(() => createClone()),
         setMessages: vi.fn(),
         setState: vi.fn(),
+        abortRun: vi.fn(),
         threadId: undefined,
         headers: {},
         runAgent: vi.fn().mockResolvedValue(undefined),
@@ -355,9 +365,12 @@ describe("handleRunAgent", () => {
           created: false,
         }),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
-        ɵacquireThreadLock: vi
-          .fn()
-          .mockResolvedValue({ joinToken: "jt-123", joinCode: "jc-123" }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
+          joinToken: "jt-123",
+        }),
+        ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
       };
       const runtime = createIntelligenceRuntime(agent, platform);
 
@@ -370,7 +383,15 @@ describe("handleRunAgent", () => {
       expect(response.status).toBe(200);
       expect(response.headers.get("Content-Type")).toBe("application/json");
       const body = await response.json();
-      expect(body).toEqual({ joinToken: "jt-123" });
+      expect(body).toEqual({
+        threadId: "thread-1",
+        runId: "run-1",
+        joinToken: "jt-123",
+        realtime: {
+          clientUrl: "wss://runtime.example/client",
+          topic: "thread:thread-1",
+        },
+      });
       expect(platform.getOrCreateThread).toHaveBeenCalledWith({
         threadId: "thread-1",
         userId: "user-1",
@@ -380,6 +401,8 @@ describe("handleRunAgent", () => {
         threadId: "thread-1",
         runId: "run-1",
         userId: "user-1",
+        agentId: "my-agent",
+        ttlSeconds: 20,
       });
       expect(platform.getThreadMessages).toHaveBeenCalledWith({
         threadId: "thread-1",
@@ -394,9 +417,12 @@ describe("handleRunAgent", () => {
           created: false,
         }),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
-        ɵacquireThreadLock: vi
-          .fn()
-          .mockResolvedValue({ joinToken: "jt-123", joinCode: "jc-123" }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
+          joinToken: "jt-123",
+        }),
+        ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
       };
       const identifyUser = vi
         .fn()
@@ -424,10 +450,12 @@ describe("handleRunAgent", () => {
         threadId: "thread-1",
         runId: "run-1",
         userId: "resolved-user",
+        agentId: "my-agent",
+        ttlSeconds: 20,
       });
     });
 
-    it("passes joinCode to runner.run() when provided", async () => {
+    it("starts the runner with canonical threadId and runId from the lock response", async () => {
       const agent = createAgentForIntelligence();
       const platform = {
         getOrCreateThread: vi.fn().mockResolvedValue({
@@ -435,9 +463,11 @@ describe("handleRunAgent", () => {
           created: false,
         }),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
-        ɵacquireThreadLock: vi
-          .fn()
-          .mockResolvedValue({ joinToken: "jt-456", joinCode: "jc-456" }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "canonical-thread",
+          runId: "canonical-run",
+          joinToken: "jt-456",
+        }),
       };
       const runtime = createIntelligenceRuntime(agent, platform);
 
@@ -448,11 +478,17 @@ describe("handleRunAgent", () => {
       });
 
       expect(runtime.runner.run).toHaveBeenCalledWith(
-        expect.objectContaining({ joinCode: "jc-456" }),
+        expect.objectContaining({
+          threadId: "canonical-thread",
+          input: expect.objectContaining({
+            threadId: "canonical-thread",
+            runId: "canonical-run",
+          }),
+        }),
       );
     });
 
-    it("returns 502 when joinToken is missing", async () => {
+    it("cleans up the lock and returns 502 when joinToken is missing", async () => {
       const agent = createAgentForIntelligence();
       const platform = {
         getOrCreateThread: vi.fn().mockResolvedValue({
@@ -460,7 +496,11 @@ describe("handleRunAgent", () => {
           created: false,
         }),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
-        ɵacquireThreadLock: vi.fn().mockResolvedValue({ joinCode: "jc-789" }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
+        }),
+        ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
       };
       const runtime = createIntelligenceRuntime(agent, platform);
 
@@ -472,7 +512,40 @@ describe("handleRunAgent", () => {
 
       expect(response.status).toBe(502);
       const body = await response.json();
-      expect(body.error).toBe("Join token not available");
+      expect(body.error).toBe("Run connection credentials not available");
+      expect(platform.ɵcleanupThreadLock).toHaveBeenCalledWith({
+        threadId: "thread-1",
+        runId: "run-1",
+      });
+      expect(runtime.runner.run).not.toHaveBeenCalled();
+    });
+
+    it("uses the requested lock owner when malformed credentials omit canonical IDs", async () => {
+      const agent = createAgentForIntelligence();
+      const platform = {
+        getOrCreateThread: vi.fn().mockResolvedValue({
+          thread: { id: "thread-1", name: null },
+          created: false,
+        }),
+        getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          joinToken: "jt-123",
+        }),
+        ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
+      };
+      const runtime = createIntelligenceRuntime(agent, platform);
+
+      const response = await handleRunAgent({
+        runtime,
+        request: createRunRequest(),
+        agentId: "my-agent",
+      });
+
+      expect(response.status).toBe(502);
+      expect(platform.ɵcleanupThreadLock).toHaveBeenCalledWith({
+        threadId: "thread-1",
+        runId: "run-1",
+      });
       expect(runtime.runner.run).not.toHaveBeenCalled();
     });
 
@@ -501,6 +574,206 @@ describe("handleRunAgent", () => {
       expect(body.error).toBe("Thread lock denied");
     });
 
+    it("cleans up the canonical lock and returns 502 when runner start fails immediately", async () => {
+      const agent = createAgentForIntelligence();
+      const platform = {
+        getOrCreateThread: vi.fn().mockResolvedValue({
+          thread: { id: "thread-1", name: null },
+          created: false,
+        }),
+        getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "canonical-thread",
+          runId: "canonical-run",
+          joinToken: "jt-123",
+        }),
+        ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
+      };
+      const runtime = createIntelligenceRuntime(agent, platform);
+      runtime.runner.run = vi.fn(
+        () =>
+          new Observable<BaseEvent>((subscriber) => {
+            subscriber.next({
+              type: EventType.RUN_ERROR,
+              message: "join failed",
+            } as BaseEvent);
+            subscriber.complete();
+          }),
+      );
+
+      const response = await handleRunAgent({
+        runtime,
+        request: createRunRequest(),
+        agentId: "my-agent",
+      });
+
+      expect(response.status).toBe(502);
+      const body = await response.json();
+      expect(body).toEqual({
+        error: "Failed to start runner",
+        message: "join failed",
+      });
+      expect(platform.ɵcleanupThreadLock).toHaveBeenCalledWith({
+        threadId: "canonical-thread",
+        runId: "canonical-run",
+      });
+      expect(platform.ɵcleanupThreadLock).toHaveBeenCalledTimes(1);
+    });
+
+    it("delays the run success response until the runner startup boundary resolves", async () => {
+      const agent = createAgentForIntelligence();
+      let resolveStartup: (() => void) | undefined;
+      const startup = new Promise<void>((resolve) => {
+        resolveStartup = resolve;
+      });
+      const platform = {
+        getOrCreateThread: vi.fn().mockResolvedValue({
+          thread: { id: "thread-1", name: null },
+          created: false,
+        }),
+        getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "canonical-thread",
+          runId: "canonical-run",
+          joinToken: "jt-123",
+        }),
+        ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
+      };
+      const runtime = createIntelligenceRuntime(agent, platform);
+      runtime.runner.runWithStartupBoundary = vi.fn(() => ({
+        events: new Observable<BaseEvent>(() => {}),
+        startup,
+      }));
+      let settled = false;
+
+      const responsePromise = handleRunAgent({
+        runtime,
+        request: createRunRequest(),
+        agentId: "my-agent",
+      }).then((response) => {
+        settled = true;
+        return response;
+      });
+
+      await Promise.resolve();
+
+      expect(settled).toBe(false);
+
+      resolveStartup?.();
+      const response = await responsePromise;
+
+      expect(response.status).toBe(200);
+      expect(runtime.runner.runWithStartupBoundary).toHaveBeenCalledWith(
+        expect.objectContaining({
+          threadId: "canonical-thread",
+          input: expect.objectContaining({
+            threadId: "canonical-thread",
+            runId: "canonical-run",
+          }),
+        }),
+      );
+    });
+
+    it("cleans up the lock and returns 502 when the runner startup boundary rejects", async () => {
+      const agent = createAgentForIntelligence();
+      const platform = {
+        getOrCreateThread: vi.fn().mockResolvedValue({
+          thread: { id: "thread-1", name: null },
+          created: false,
+        }),
+        getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "canonical-thread",
+          runId: "canonical-run",
+          joinToken: "jt-123",
+        }),
+        ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
+      };
+      const runtime = createIntelligenceRuntime(agent, platform);
+      runtime.runner.runWithStartupBoundary = vi.fn(() => ({
+        events: new Observable<BaseEvent>(() => {}),
+        startup: Promise.reject(new Error("Failed to join channel: denied")),
+      }));
+
+      const response = await handleRunAgent({
+        runtime,
+        request: createRunRequest(),
+        agentId: "my-agent",
+      });
+
+      expect(response.status).toBe(502);
+      const body = await response.json();
+      expect(body).toEqual({
+        error: "Failed to start runner",
+        message: "Failed to join channel: denied",
+      });
+      expect(platform.ɵcleanupThreadLock).toHaveBeenCalledWith({
+        threadId: "canonical-thread",
+        runId: "canonical-run",
+      });
+      expect(platform.ɵcleanupThreadLock).toHaveBeenCalledTimes(1);
+    });
+
+    it("aborts the agent when lock renewal fails", async () => {
+      vi.useFakeTimers();
+      const runningAgent = {
+        clone: vi.fn(),
+        setMessages: vi.fn(),
+        setState: vi.fn(),
+        abortRun: vi.fn(),
+        threadId: undefined,
+        headers: {},
+        runAgent: vi.fn().mockResolvedValue(undefined),
+      } as unknown as AbstractAgent;
+      const baseAgent = {
+        clone: vi.fn(() => runningAgent),
+        setMessages: vi.fn(),
+        setState: vi.fn(),
+        abortRun: vi.fn(),
+        threadId: undefined,
+        headers: {},
+        runAgent: vi.fn().mockResolvedValue(undefined),
+      } as unknown as AbstractAgent;
+      const platform = {
+        getOrCreateThread: vi.fn().mockResolvedValue({
+          thread: { id: "thread-1", name: null },
+          created: false,
+        }),
+        getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "canonical-thread",
+          runId: "canonical-run",
+          joinToken: "jt-123",
+        }),
+        ɵrenewThreadLock: vi.fn().mockRejectedValue(new Error("lost lock")),
+      };
+      const runtime = createIntelligenceRuntime(baseAgent, platform, {
+        lockHeartbeatIntervalSeconds: 1,
+        lockTtlSeconds: 5,
+      });
+      runtime.runner.run = vi.fn(() => new Observable<BaseEvent>(() => {}));
+
+      try {
+        const response = await handleRunAgent({
+          runtime,
+          request: createRunRequest(),
+          agentId: "my-agent",
+        });
+        expect(response.status).toBe(200);
+
+        await vi.advanceTimersByTimeAsync(1_000);
+
+        expect(platform.ɵrenewThreadLock).toHaveBeenCalledWith({
+          threadId: "canonical-thread",
+          runId: "canonical-run",
+          ttlSeconds: 5,
+        });
+        expect(runningAgent.abortRun).toHaveBeenCalledTimes(1);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
     it("passes only unseen input messages to the runner for durable persistence", async () => {
       const agent = createAgentForIntelligence();
       const platform = {
@@ -517,9 +790,11 @@ describe("handleRunAgent", () => {
             },
           ],
         }),
-        ɵacquireThreadLock: vi
-          .fn()
-          .mockResolvedValue({ joinToken: "jt-123", joinCode: "jc-123" }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
+          joinToken: "jt-123",
+        }),
       };
       const runtime = createIntelligenceRuntime(agent, platform);
       const response = await handleRunAgent({
@@ -577,9 +852,12 @@ describe("handleRunAgent", () => {
         getThreadMessages: vi
           .fn()
           .mockRejectedValue(new Error("history unavailable")),
-        ɵacquireThreadLock: vi
-          .fn()
-          .mockResolvedValue({ joinToken: "jt-123", joinCode: "jc-123" }),
+        ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
+          joinToken: "jt-123",
+        }),
+        ɵcleanupThreadLock: vi.fn().mockResolvedValue(undefined),
       };
       const runtime = createIntelligenceRuntime(agent, platform);
 
@@ -592,6 +870,10 @@ describe("handleRunAgent", () => {
       expect(response.status).toBe(502);
       const body = await response.json();
       expect(body.error).toBe("Thread history lookup failed");
+      expect(platform.ɵcleanupThreadLock).toHaveBeenCalledWith({
+        threadId: "thread-1",
+        runId: "run-1",
+      });
       expect(runtime.runner.run).not.toHaveBeenCalled();
     });
 
@@ -604,8 +886,9 @@ describe("handleRunAgent", () => {
         }),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
         ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
           joinToken: "jt-created",
-          joinCode: "jc-created",
         }),
       };
       const runtime = createIntelligenceRuntime(agent, platform);
@@ -626,6 +909,8 @@ describe("handleRunAgent", () => {
         threadId: "thread-1",
         runId: "run-1",
         userId: "user-1",
+        agentId: "my-agent",
+        ttlSeconds: 20,
       });
     });
 
@@ -675,8 +960,9 @@ describe("handleRunAgent", () => {
         }),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
         ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
           joinToken: "jt-created",
-          joinCode: "jc-created",
         }),
       };
       const runtime = createIntelligenceRuntime(baseAgent, platform, {
@@ -730,8 +1016,9 @@ describe("handleRunAgent", () => {
         updateThread: vi.fn(),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
         ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
           joinToken: "jt-created",
-          joinCode: "jc-created",
         }),
       };
       const runtime = createIntelligenceRuntime(agent, platform, {
@@ -759,8 +1046,9 @@ describe("handleRunAgent", () => {
         updateThread: vi.fn(),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
         ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
           joinToken: "jt-created",
-          joinCode: "jc-created",
         }),
       };
       const runtime = createIntelligenceRuntime(agent, platform, {
@@ -815,8 +1103,9 @@ describe("handleRunAgent", () => {
         updateThread: vi.fn(),
         getThreadMessages: vi.fn().mockResolvedValue({ messages: [] }),
         ɵacquireThreadLock: vi.fn().mockResolvedValue({
+          threadId: "thread-1",
+          runId: "run-1",
           joinToken: "jt-created",
-          joinCode: "jc-created",
         }),
       };
       const runtime = createIntelligenceRuntime(baseAgent, platform, {
@@ -938,4 +1227,66 @@ describe("handleRunAgent", () => {
       }
     });
   });
+
+  describe("telemetry", () => {
+    it("captures oss.runtime.copilot_request_created on every invocation", async () => {
+      // Dynamic import so we spy on the module singleton the handler uses.
+      const { telemetry } = await import("../telemetry");
+      const captureSpy = vi
+        .spyOn(telemetry, "capture")
+        .mockResolvedValue(undefined);
+
+      try {
+        const runtime = createMockRuntime({});
+        await handleRunAgent({
+          runtime,
+          request: createMockRequest(),
+          agentId: "nonexistent-agent",
+        });
+
+        expect(captureSpy).toHaveBeenCalledWith(
+          "oss.runtime.copilot_request_created",
+          expect.objectContaining({
+            requestType: "run",
+            "cloud.api_key_provided": false,
+          }),
+        );
+      } finally {
+        captureSpy.mockRestore();
+      }
+    });
+
+    it("includes cloud.public_api_key when x-copilotcloud-public-api-key header is set", async () => {
+      const { telemetry } = await import("../telemetry");
+      const captureSpy = vi
+        .spyOn(telemetry, "capture")
+        .mockResolvedValue(undefined);
+
+      try {
+        const runtime = createMockRuntime({});
+        const request = new Request("https://example.com/agent/test/run", {
+          method: "POST",
+          headers: {
+            "x-copilotcloud-public-api-key": "ck_pub_run_test",
+          },
+        });
+
+        await handleRunAgent({
+          runtime,
+          request,
+          agentId: "nonexistent-agent",
+        });
+
+        expect(captureSpy).toHaveBeenCalledWith(
+          "oss.runtime.copilot_request_created",
+          expect.objectContaining({
+            "cloud.api_key_provided": true,
+            "cloud.public_api_key": "ck_pub_run_test",
+          }),
+        );
+      } finally {
+        captureSpy.mockRestore();
+      }
+    });
+  });
 });

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