@copilotkit/runtime 1.56.2 → 1.56.4-canary.1777529757

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/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");
         },
@@ -394,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",
       });
     });
 
@@ -422,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", () => {
@@ -503,7 +519,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,7 +569,7 @@ describe("CopilotKitIntelligence", () => {
       const result = await client.ɵconnectThread({
         threadId: "t-1",
         userId: "user-1",
-        lastSeenEventId: "event-1",
+        agentId: "agent-1",
       });
 
       expect(result).toBeNull();
@@ -563,40 +578,21 @@ describe("CopilotKitIntelligence", () => {
       expect(opts.method).toBe("POST");
       expect(JSON.parse(opts.body)).toEqual({
         userId: "user-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: "MESSAGES_SNAPSHOT", messages: [] }],
-      };
-      fetchMock.mockReturnValue(jsonResponse(payload));
-
-      const result = await client.ɵconnectThread({
         threadId: "t-1",
-        userId: "user-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",
-        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
@@ -42,7 +41,6 @@ export class PlatformRequestError extends Error {
  *   apiUrl: "https://api.copilotkit.ai",
  *   wsUrl: "wss://api.copilotkit.ai",
  *   apiKey: process.env.COPILOTKIT_API_KEY!,
- *   organizationId: process.env.COPILOTKIT_ORGANIZATION_ID!,
  * });
  *
  * const runtime = new CopilotRuntime({
@@ -66,8 +64,6 @@ export interface CopilotKitIntelligenceConfig {
   wsUrl: string;
   /** API key for authenticating with the intelligence platform */
   apiKey: string;
-  /** Organization identifier used for self-hosted Intelligence instances */
-  organizationId: string;
   /**
    * Initial listener invoked after a thread is created.
    * Prefer {@link CopilotKitIntelligence.onThreadCreated} for multiple listeners.
@@ -153,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;
 }
@@ -169,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. */
@@ -215,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. */
@@ -230,6 +218,11 @@ export interface RenewThreadLockRequest {
   lockKeyPrefix?: string;
 }
 
+export interface CleanupThreadLockRequest {
+  threadId: string;
+  runId: string;
+}
+
 export interface RenewThreadLockResponse {
   ttlSeconds: number;
 }
@@ -248,7 +241,6 @@ export class CopilotKitIntelligence {
   #runnerWsUrl: string;
   #clientWsUrl: string;
   #apiKey: string;
-  #organizationId: string;
   #threadCreatedListeners = new Set<(thread: ThreadSummary) => void>();
   #threadUpdatedListeners = new Set<(thread: ThreadSummary) => void>();
   #threadDeletedListeners = new Set<(params: ThreadDeletedPayload) => void>();
@@ -260,7 +252,6 @@ export class CopilotKitIntelligence {
     this.#runnerWsUrl = deriveRunnerWsUrl(intelligenceWsUrl);
     this.#clientWsUrl = deriveClientWsUrl(intelligenceWsUrl);
     this.#apiKey = config.apiKey;
-    this.#organizationId = config.organizationId;
 
     if (config.onThreadCreated) {
       this.onThreadCreated(config.onThreadCreated);
@@ -345,10 +336,6 @@ export class CopilotKitIntelligence {
     return this.#clientWsUrl;
   }
 
-  ɵgetOrganizationId(): string {
-    return this.#organizationId;
-  }
-
   ɵgetRunnerAuthToken(): string {
     return this.#apiKey;
   }
@@ -359,7 +346,6 @@ export class CopilotKitIntelligence {
     const headers: Record<string, string> = {
       Authorization: `Bearer ${this.#apiKey}`,
       "Content-Type": "application/json",
-      "X-Organization-Id": this.#organizationId,
     };
 
     const response = await fetch(url, {
@@ -400,7 +386,7 @@ export class CopilotKitIntelligence {
 
     for (const callback of listeners) {
       try {
-        void (callback as (p: typeof payload) => void)(payload);
+        (callback as (p: typeof payload) => void)(payload);
       } catch (error) {
         logger.error(
           { err: error, callbackName, payload },
@@ -616,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 }
           : {}),
@@ -633,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> {
@@ -663,16 +660,16 @@ export class CopilotKitIntelligence {
   async ɵconnectThread(params: {
     threadId: string;
     userId: 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.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;