@copilotkit/runtime 1.56.3 → 1.56.4

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" },
     },

package/src/v2/runtime/handlers/shared/intelligence-utils.ts

@@ -1,7 +1,27 @@
 import { PlatformRequestError } from "../../intelligence-platform/client";
 
+/**
+ * Returns the HTTP status carried by platform request errors.
+ */
+export function getPlatformErrorStatus(error: unknown): number | undefined {
+  if (error instanceof PlatformRequestError) {
+    return error.status;
+  }
+
+  if (
+    error !== null &&
+    typeof error === "object" &&
+    "status" in error &&
+    typeof error.status === "number"
+  ) {
+    return error.status;
+  }
+
+  return undefined;
+}
+
 export function isPlatformNotFoundError(error: unknown): boolean {
-  return error instanceof PlatformRequestError && error.status === 404;
+  return getPlatformErrorStatus(error) === 404;
 }
 
 const MAX_ID_LENGTH = 128;

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

@@ -385,24 +385,34 @@ describe("CopilotKitIntelligence", () => {
   });
 
   describe("acquireThreadLock", () => {
-    it("sends POST to lock endpoint and returns thread connection credentials", async () => {
+    it("sends POST to lock endpoint and returns canonical run credentials", async () => {
       fetchMock.mockReturnValue(
-        jsonResponse({ joinToken: "jt-lock", joinCode: "jc-lock" }),
+        jsonResponse({
+          threadId: "t-1",
+          runId: "r-1",
+          joinToken: "jt-lock",
+        }),
       );
 
       const result = await client.ɵacquireThreadLock({
         threadId: "t-1",
         runId: "r-1",
         userId: "user-1",
+        agentId: "agent-1",
       });
 
-      expect(result).toEqual({ joinToken: "jt-lock", joinCode: "jc-lock" });
+      expect(result).toEqual({
+        threadId: "t-1",
+        runId: "r-1",
+        joinToken: "jt-lock",
+      });
       const [url, opts] = fetchMock.mock.calls[0];
       expect(url).toBe("https://api.example.com/api/threads/t-1/lock");
       expect(opts.method).toBe("POST");
       expect(JSON.parse(opts.body)).toEqual({
         runId: "r-1",
         userId: "user-1",
+        agentId: "agent-1",
       });
     });
 
@@ -413,9 +423,24 @@ describe("CopilotKitIntelligence", () => {
           threadId: "t-1",
           runId: "r-1",
           userId: "user-1",
+          agentId: "agent-1",
         }),
       ).rejects.toThrow(/409/);
     });
+
+    it("sends compare-delete cleanup to the lock endpoint", async () => {
+      fetchMock.mockReturnValue(emptyResponse());
+
+      await client.ɵcleanupThreadLock({
+        threadId: "t-1",
+        runId: "r-1",
+      });
+
+      const [url, opts] = fetchMock.mock.calls[0];
+      expect(url).toBe("https://api.example.com/api/threads/t-1/lock");
+      expect(opts.method).toBe("DELETE");
+      expect(JSON.parse(opts.body)).toEqual({ runId: "r-1" });
+    });
   });
 
   describe("getActiveJoinCode", () => {
@@ -544,8 +569,7 @@ describe("CopilotKitIntelligence", () => {
       const result = await client.ɵconnectThread({
         threadId: "t-1",
         userId: "user-1",
-        runId: "run-1",
-        lastSeenEventId: "event-1",
+        agentId: "agent-1",
       });
 
       expect(result).toBeNull();
@@ -554,51 +578,21 @@ describe("CopilotKitIntelligence", () => {
       expect(opts.method).toBe("POST");
       expect(JSON.parse(opts.body)).toEqual({
         userId: "user-1",
-        runId: "run-1",
-        lastSeenEventId: "event-1",
+        agentId: "agent-1",
       });
     });
 
-    it("returns a bootstrap connect plan", async () => {
+    it("returns credentials-only connect response", async () => {
       const payload = {
-        mode: "bootstrap",
-        latestEventId: "event-2",
-        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",
-      });
-
-      expect(result).toEqual(payload);
-    });
-
-    it("returns a live connect plan", async () => {
-      const payload = {
-        mode: "live",
-        joinToken: "jt-live",
-        joinFromEventId: "event-2",
-        events: [],
+        joinToken: "jt-connect",
       };
       fetchMock.mockReturnValue(jsonResponse(payload));
 
       const result = await client.ɵconnectThread({
         threadId: "t-1",
         userId: "user-1",
-        runId: "run-1",
-        lastSeenEventId: "event-2",
+        agentId: "agent-1",
       });
 
       expect(result).toEqual(payload);

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

@@ -1,5 +1,4 @@
 import { logger } from "@copilotkit/shared";
-import type { BaseEvent } from "@ag-ui/client";
 
 /**
  * Error thrown when an Intelligence platform HTTP request returns a non-2xx
@@ -150,10 +149,12 @@ export interface CreateThreadRequest {
 
 /** Credentials returned when locking or joining a thread's realtime channel. */
 export interface ThreadConnectionResponse {
+  /** Canonical platform thread identifier for the run or connection. */
+  threadId: string;
+  /** Canonical platform run identifier for an active run lock. */
+  runId?: string;
   /** Short-lived token for authenticating the Phoenix channel join. */
   joinToken: string;
-  /** Optional join code that can be shared with other clients to join the same channel. */
-  joinCode?: string;
   /** Lock metadata echoed back by the platform. */
   lock?: ThreadLockInfo;
 }
@@ -166,24 +167,13 @@ export interface SubscribeToThreadsResponse {
   joinToken: string;
 }
 
-export interface ConnectThreadBootstrapResponse {
-  mode: "bootstrap";
-  latestEventId: string | null;
-  events: BaseEvent[];
-}
+export type ConnectThreadResponse = ThreadConnectionResponse | null;
 
-export interface ConnectThreadLiveResponse {
-  mode: "live";
-  joinToken: string;
-  joinFromEventId: string | null;
-  events: BaseEvent[];
+export interface AcquireThreadLockResponse extends ThreadConnectionResponse {
+  /** Canonical platform run identifier for the acquired lock. */
+  runId: string;
 }
 
-export type ConnectThreadResponse =
-  | ConnectThreadBootstrapResponse
-  | ConnectThreadLiveResponse
-  | null;
-
 /** A single message within a thread's persisted history. */
 export interface ThreadMessage {
   /** Unique identifier for this message. */
@@ -212,6 +202,7 @@ export interface AcquireThreadLockRequest {
   threadId: string;
   runId: string;
   userId: string;
+  agentId: string;
   /** Custom Redis key prefix for the lock (default: "thread"). */
   lockKeyPrefix?: string;
   /** Lock TTL in seconds. When set, the lock auto-expires after this duration. */
@@ -227,6 +218,11 @@ export interface RenewThreadLockRequest {
   lockKeyPrefix?: string;
 }
 
+export interface CleanupThreadLockRequest {
+  threadId: string;
+  runId: string;
+}
+
 export interface RenewThreadLockResponse {
   ttlSeconds: number;
 }
@@ -606,13 +602,14 @@ export class CopilotKitIntelligence {
 
   async ɵacquireThreadLock(
     params: AcquireThreadLockRequest,
-  ): Promise<ThreadConnectionResponse> {
-    return this.#request<ThreadConnectionResponse>(
+  ): Promise<AcquireThreadLockResponse> {
+    return this.#request<AcquireThreadLockResponse>(
       "POST",
       `/api/threads/${encodeURIComponent(params.threadId)}/lock`,
       {
         runId: params.runId,
         userId: params.userId,
+        agentId: params.agentId,
         ...(params.lockKeyPrefix !== undefined
           ? { lockKeyPrefix: params.lockKeyPrefix }
           : {}),
@@ -623,6 +620,16 @@ export class CopilotKitIntelligence {
     );
   }
 
+  async ɵcleanupThreadLock(params: CleanupThreadLockRequest): Promise<void> {
+    return this.#request<void>(
+      "DELETE",
+      `/api/threads/${encodeURIComponent(params.threadId)}/lock`,
+      {
+        runId: params.runId,
+      },
+    );
+  }
+
   async ɵrenewThreadLock(
     params: RenewThreadLockRequest,
   ): Promise<RenewThreadLockResponse> {
@@ -653,18 +660,16 @@ export class CopilotKitIntelligence {
   async ɵconnectThread(params: {
     threadId: string;
     userId: string;
-    runId?: string;
-    lastSeenEventId?: string | null;
+    agentId: string;
   }): Promise<ConnectThreadResponse> {
-    const result = await this.#request<
-      ConnectThreadBootstrapResponse | ConnectThreadLiveResponse
-    >("POST", `/api/threads/${encodeURIComponent(params.threadId)}/connect`, {
-      userId: params.userId,
-      ...(params.runId !== undefined ? { runId: params.runId } : {}),
-      ...(params.lastSeenEventId !== undefined
-        ? { lastSeenEventId: params.lastSeenEventId }
-        : {}),
-    });
+    const result = await this.#request<ThreadConnectionResponse>(
+      "POST",
+      `/api/threads/${encodeURIComponent(params.threadId)}/connect`,
+      {
+        userId: params.userId,
+        agentId: params.agentId,
+      },
+    );
 
     // request() returns undefined for empty/204 responses
     return result ?? null;

package/src/v2/runtime/runner/__tests__/intelligence-runner.test.ts

@@ -619,10 +619,9 @@ describe("IntelligenceAgentRunner", () => {
     });
   });
 
-  describe("run with joinCode", () => {
-    it("uses joinCode for the channel topic when provided", async () => {
+  describe("run channel ownership", () => {
+    it("uses runId for the ingestion channel topic", async () => {
       const threadId = "t-jc";
-      const joinCode = "join-abc-123";
       const input = createRunInput({ threadId, runId: "r-jc" });
       const agent = new MockAgent([
         {
@@ -633,15 +632,16 @@ describe("IntelligenceAgentRunner", () => {
       ]);
 
       const eventsPromise = collectEvents(
-        runner.run({ threadId, agent, input, joinCode }),
+        runner.run({ threadId, agent, input }),
       );
       const ch = mockChannels[0];
-      expect(ch.topic).toBe(`ingestion:${joinCode}`);
+      expect(ch.topic).toBe("ingestion:r-jc");
+      expect(ch.params).toEqual({ thread_id: threadId, run_id: "r-jc" });
       ch.triggerJoin("ok");
       await eventsPromise;
     });
 
-    it("falls back to threadId when joinCode is not provided", async () => {
+    it("keeps pushed event payload ownership on canonical threadId and runId", async () => {
       const threadId = "t-no-jc";
       const input = createRunInput({ threadId, runId: "r-no-jc" });
       const agent = new MockAgent([
@@ -656,9 +656,17 @@ describe("IntelligenceAgentRunner", () => {
         runner.run({ threadId, agent, input }),
       );
       const ch = mockChannels[0];
-      expect(ch.topic).toBe(`ingestion:${threadId}`);
       ch.triggerJoin("ok");
       await eventsPromise;
+
+      expect(ch.pushLog[0].payload).toEqual(
+        expect.objectContaining({
+          threadId,
+          runId: "r-no-jc",
+          thread_id: threadId,
+          run_id: "r-no-jc",
+        }),
+      );
     });
   });
 

package/src/v2/runtime/runner/agent-runner.ts

@@ -10,7 +10,6 @@ export interface AgentRunnerRunRequest {
   threadId: string;
   agent: AbstractAgent;
   input: RunAgentInput;
-  joinCode?: string;
   persistedInputMessages?: Message[];
 }