@copilotkit/runtime 1.56.2 → 1.56.3

package/src/lib/runtime/agent-integrations/langgraph/__tests__/dispatch-event-filtering.test.ts

@@ -1,5 +1,7 @@
 import { EventType } from "@ag-ui/client";
 import { LangGraphAgent } from "../agent";
+import { CustomEventNames } from "../consts";
+import { vi } from "vitest";
 
 function createAgent() {
   const agent = new LangGraphAgent({
@@ -33,6 +35,25 @@ function makeTextEvent(
   };
 }
 
+function makeCustomEvent(name: string, value: any) {
+  return {
+    type: EventType.CUSTOM,
+    name,
+    value,
+  } as any;
+}
+
+/**
+ * Mock the parent class's langGraphDefaultMergeState for a single test,
+ * using vi.spyOn for automatic cleanup.
+ */
+function withMockedParentMerge(agent: LangGraphAgent, returnValue: any) {
+  const parentProto = Object.getPrototypeOf(Object.getPrototypeOf(agent));
+  return vi
+    .spyOn(parentProto, "langGraphDefaultMergeState")
+    .mockReturnValue(returnValue);
+}
+
 describe("dispatchEvent emit-messages filtering", () => {
   it("suppresses message events when copilotkit:emit-messages is false", () => {
     const { agent, events } = createAgent();
@@ -153,3 +174,172 @@ describe("dispatchEvent emit-tool-calls filtering", () => {
     expect(events).toHaveLength(1);
   });
 });
+
+// ---------- CopilotKit custom event dispatch ----------
+
+describe("dispatchEvent custom CopilotKit events", () => {
+  it("manually_emit_message produces TextMessage event sequence", () => {
+    const { agent, events } = createAgent();
+
+    const result = agent.dispatchEvent(
+      makeCustomEvent(CustomEventNames.CopilotKitManuallyEmitMessage, {
+        message_id: "msg-manual-1",
+        message: "Hello from agent",
+        role: "assistant",
+      }),
+    );
+
+    expect(result).toBe(true);
+    expect(events).toHaveLength(3);
+    expect(events[0].type).toBe(EventType.TEXT_MESSAGE_START);
+    expect(events[0].messageId).toBe("msg-manual-1");
+    expect(events[0].role).toBe("assistant");
+    expect(events[1].type).toBe(EventType.TEXT_MESSAGE_CONTENT);
+    expect(events[1].delta).toBe("Hello from agent");
+    expect(events[2].type).toBe(EventType.TEXT_MESSAGE_END);
+    expect(events[2].messageId).toBe("msg-manual-1");
+  });
+
+  it("manually_emit_tool_call produces ToolCall event sequence", () => {
+    const { agent, events } = createAgent();
+
+    const result = agent.dispatchEvent(
+      makeCustomEvent(CustomEventNames.CopilotKitManuallyEmitToolCall, {
+        id: "tc-manual-1",
+        name: "SearchTool",
+        args: { query: "test" },
+      }),
+    );
+
+    expect(result).toBe(true);
+    expect(events).toHaveLength(3);
+    expect(events[0].type).toBe(EventType.TOOL_CALL_START);
+    expect(events[0].toolCallId).toBe("tc-manual-1");
+    expect(events[0].toolCallName).toBe("SearchTool");
+    expect(events[1].type).toBe(EventType.TOOL_CALL_ARGS);
+    expect(events[1].toolCallId).toBe("tc-manual-1");
+    expect(events[1].delta).toEqual({ query: "test" });
+    expect(events[2].type).toBe(EventType.TOOL_CALL_END);
+    expect(events[2].toolCallId).toBe("tc-manual-1");
+  });
+
+  it("manually_emit_state produces StateSnapshot event", () => {
+    const { agent, events } = createAgent();
+
+    // Mock getStateSnapshot since it depends on thread state
+    (agent as any).getStateSnapshot = (state: any) => ({
+      values: state.values,
+    });
+
+    const result = agent.dispatchEvent(
+      makeCustomEvent(
+        CustomEventNames.CopilotKitManuallyEmitIntermediateState,
+        {
+          progress: 75,
+        },
+      ),
+    );
+
+    expect(result).toBe(true);
+    expect((agent as any).activeRun.manuallyEmittedState).toEqual({
+      progress: 75,
+    });
+    const snapshotEvents = events.filter(
+      (e) => e.type === EventType.STATE_SNAPSHOT,
+    );
+    expect(snapshotEvents.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("copilotkit_exit produces Exit custom event", () => {
+    const { agent, events } = createAgent();
+
+    const result = agent.dispatchEvent(
+      makeCustomEvent(CustomEventNames.CopilotKitExit, {}),
+    );
+
+    expect(result).toBe(true);
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe(EventType.CUSTOM);
+    // "Exit" is the hardcoded downstream name in agent.ts — not a constant,
+    // because it's the value the frontend listens for, not an internal enum.
+    expect(events[0].name).toBe("Exit");
+    expect(events[0].value).toBe(true);
+  });
+
+  it("events without rawEvent pass through to subscriber", () => {
+    const { agent, events } = createAgent();
+
+    const result = agent.dispatchEvent({
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: "msg-no-raw",
+      role: "assistant",
+    } as any);
+
+    expect(result).toBe(true);
+    expect(events).toHaveLength(1);
+    expect(events[0].messageId).toBe("msg-no-raw");
+  });
+});
+
+// ---------- langGraphDefaultMergeState ----------
+
+describe("langGraphDefaultMergeState", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("merges copilotkit actions from ag-ui tools", () => {
+    const { agent } = createAgent();
+    const tools = [{ name: "tool1" }, { name: "tool2" }];
+
+    withMockedParentMerge(agent, {
+      "ag-ui": { tools, context: [] },
+      tools: [],
+      messages: [],
+    });
+
+    const result = agent.langGraphDefaultMergeState({} as any, [], {} as any);
+    expect(result.copilotkit).toBeDefined();
+    expect(result.copilotkit.actions).toEqual(expect.arrayContaining(tools));
+  });
+
+  it("merges copilotkit context from ag-ui", () => {
+    const { agent } = createAgent();
+    const context = [{ description: "user info", value: "test" }];
+
+    withMockedParentMerge(agent, {
+      "ag-ui": { tools: [], context },
+      tools: [],
+      messages: [],
+    });
+
+    const result = agent.langGraphDefaultMergeState({} as any, [], {} as any);
+    expect(result.copilotkit.context).toEqual(context);
+  });
+
+  it("handles missing ag-ui key without crashing", () => {
+    const { agent } = createAgent();
+
+    withMockedParentMerge(agent, { messages: [] });
+
+    const result = agent.langGraphDefaultMergeState({} as any, [], {} as any);
+    expect(result.copilotkit).toBeDefined();
+    expect(result.copilotkit.actions).toEqual([]);
+    expect(result.copilotkit.context).toEqual([]);
+  });
+
+  it("deduplicates tools from returnedTools and ag-ui tools", () => {
+    const { agent } = createAgent();
+    const tool = { name: "SharedTool", id: "shared-1" };
+
+    withMockedParentMerge(agent, {
+      "ag-ui": { tools: [tool], context: [] },
+      tools: [tool],
+      messages: [],
+    });
+
+    const result = agent.langGraphDefaultMergeState({} as any, [], {} as any);
+    expect(result.copilotkit.actions).toHaveLength(1);
+    expect(result.copilotkit.actions[0].name).toBe("SharedTool");
+  });
+});

package/src/lib/runtime/copilot-runtime.ts

@@ -463,10 +463,26 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       }
 
       if (isAgentsListEmpty) {
-        const model =
-          serviceAdapter.getLanguageModel?.() ??
-          `${serviceAdapter.provider}/${serviceAdapter.model}`;
-        agentsList.default = new BuiltInAgent({ model });
+        const languageModel = serviceAdapter.getLanguageModel?.();
+        if (languageModel) {
+          // Adapter exposes a pre-configured LanguageModel (e.g. OpenAI/Anthropic adapters)
+          agentsList.default = new BuiltInAgent({ model: languageModel });
+        } else if (serviceAdapter.provider && serviceAdapter.model) {
+          // Adapter exposes provider/model strings
+          agentsList.default = new BuiltInAgent({
+            model: `${serviceAdapter.provider}/${serviceAdapter.model}`,
+          });
+        } else {
+          throw new CopilotKitMisuseError({
+            message:
+              `Service adapter "${serviceAdapter.name ?? "unknown"}" does not provide model information. ` +
+              `When using adapters like LangChainAdapter without an explicit agents list, ` +
+              `please provide a default agent in the runtime config. Example:\n` +
+              `  new CopilotRuntime({\n` +
+              `    agents: { default: new BuiltInAgent({ model: "openai/gpt-4o" }) }\n` +
+              `  })`,
+          });
+        }
       }
 
       const actions = this.params?.actions;

package/src/lib/runtime/retry-utils.ts

@@ -7,6 +7,8 @@ export const RETRY_CONFIG = {
   maxDelayMs: 5000,
   // HTTP status codes that should be retried
   retryableStatusCodes: [502, 503, 504, 408, 429],
+  // Maximum Retry-After value (in seconds) we're willing to honor
+  maxRetryAfterSeconds: 60,
   // Network error patterns that should be retried
   retryableErrorMessages: [
     "fetch failed",
@@ -44,6 +46,28 @@ export function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// Parse the Retry-After header value into milliseconds.
+// Returns undefined if the header is missing or unparseable.
+export function parseRetryAfter(response: Response): number | undefined {
+  const retryAfter = response.headers.get("Retry-After");
+  if (!retryAfter) return undefined;
+
+  // Try as seconds (integer)
+  const seconds = Number(retryAfter);
+  if (!Number.isNaN(seconds) && seconds >= 0) {
+    return seconds * 1000;
+  }
+
+  // Try as HTTP-date
+  const date = Date.parse(retryAfter);
+  if (!Number.isNaN(date)) {
+    const delayMs = date - Date.now();
+    return delayMs > 0 ? delayMs : 0;
+  }
+
+  return undefined;
+}
+
 // Calculate exponential backoff delay
 export function calculateDelay(attempt: number): number {
   const delay = RETRY_CONFIG.baseDelayMs * Math.pow(2, attempt);
@@ -67,7 +91,23 @@ export async function fetchWithRetry(
         isRetryableError(null, response) &&
         attempt < RETRY_CONFIG.maxRetries
       ) {
-        const delay = calculateDelay(attempt);
+        let delay = calculateDelay(attempt);
+
+        // Honor Retry-After header on 429 responses
+        if (response.status === 429) {
+          const retryAfterMs = parseRetryAfter(response);
+          if (retryAfterMs !== undefined) {
+            const maxMs = RETRY_CONFIG.maxRetryAfterSeconds * 1000;
+            if (retryAfterMs > maxMs) {
+              throw new Error(
+                `Server requested Retry-After of ${Math.ceil(retryAfterMs / 1000)}s ` +
+                  `which exceeds the maximum of ${RETRY_CONFIG.maxRetryAfterSeconds}s`,
+              );
+            }
+            delay = retryAfterMs;
+          }
+        }
+
         logger?.warn(
           `Request to ${url} failed with status ${response.status}. ` +
             `Retrying attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries + 1} in ${delay}ms.`,

package/src/v2/runtime/__tests__/fetch-router.test.ts

@@ -135,6 +135,11 @@ describe("fetch-router", () => {
       const result = matchRoute("/info", "/");
       expect(result).toEqual({ method: "info" });
     });
+
+    it("matches GET /cpk-debug-events", () => {
+      const result = matchRoute("/api/copilotkit/cpk-debug-events", basePath);
+      expect(result).toEqual({ method: "cpk-debug-events" });
+    });
   });
 
   describe("without basePath (suffix matching)", () => {
@@ -204,5 +209,22 @@ describe("fetch-router", () => {
       const result = matchRoute("/api/v2/copilotkit/agent/a1/run");
       expect(result).toEqual({ method: "agent/run", agentId: "a1" });
     });
+
+    it("matches /cpk-debug-events suffix", () => {
+      const result = matchRoute("/api/copilotkit/cpk-debug-events");
+      expect(result).toEqual({ method: "cpk-debug-events" });
+    });
+
+    it("matches bare /cpk-debug-events", () => {
+      const result = matchRoute("/cpk-debug-events");
+      expect(result).toEqual({ method: "cpk-debug-events" });
+    });
+  });
+
+  describe("cpk-debug-events route with basePath", () => {
+    it("matches /cpk-debug-events with /api basePath", () => {
+      const result = matchRoute("/api/cpk-debug-events", "/api");
+      expect(result).toEqual({ method: "cpk-debug-events" });
+    });
   });
 });

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

@@ -228,7 +228,9 @@ describe("handleConnectAgent", () => {
         afterRequestMiddleware: undefined,
         runner,
         mode: "intelligence",
-        identifyUser: vi.fn().mockResolvedValue({ id: "user-1" }),
+        identifyUser: vi
+          .fn()
+          .mockResolvedValue({ id: "user-1", name: "User One" }),
         intelligence: platform,
       } as unknown as CopilotRuntime;
     };
@@ -262,6 +264,7 @@ describe("handleConnectAgent", () => {
       expect(platform.ɵconnectThread).toHaveBeenCalledWith({
         threadId: "thread-1",
         userId: "user-1",
+        runId: "run-1",
         lastSeenEventId: null,
       });
     });
@@ -271,7 +274,15 @@ describe("handleConnectAgent", () => {
         ɵconnectThread: vi.fn().mockResolvedValue({
           mode: "bootstrap",
           latestEventId: "event-2",
-          events: [{ type: "MESSAGES_SNAPSHOT", messages: [] }],
+          events: [
+            {
+              type: "RUN_STARTED",
+              threadId: "thread-1",
+              run_id: "backend-run-1",
+              input: { messages: [] },
+            },
+            { type: "RUN_FINISHED" },
+          ],
         }),
       };
       const runtime = createIntelligenceRuntime(platform);
@@ -287,7 +298,23 @@ describe("handleConnectAgent", () => {
       expect(body).toEqual({
         mode: "bootstrap",
         latestEventId: "event-2",
-        events: [{ type: "MESSAGES_SNAPSHOT", messages: [] }],
+        events: [
+          {
+            type: "RUN_STARTED",
+            threadId: "thread-1",
+            runId: "run-1",
+            input: {
+              messages: [],
+              threadId: "thread-1",
+              runId: "run-1",
+            },
+          },
+          {
+            type: "RUN_FINISHED",
+            threadId: "thread-1",
+            runId: "run-1",
+          },
+        ],
       });
     });
 
@@ -310,6 +337,7 @@ describe("handleConnectAgent", () => {
       expect(platform.ɵconnectThread).toHaveBeenCalledWith({
         threadId: "thread-1",
         userId: "user-1",
+        runId: "run-1",
         lastSeenEventId: null,
       });
     });
@@ -349,6 +377,7 @@ describe("handleConnectAgent", () => {
       expect(platform.ɵconnectThread).toHaveBeenCalledWith({
         threadId: "thread-1",
         userId: "user-1",
+        runId: "run-1",
         lastSeenEventId: "event-9",
       });
     });
@@ -357,7 +386,9 @@ describe("handleConnectAgent", () => {
       const platform = {
         ɵconnectThread: vi.fn().mockResolvedValue(null),
       };
-      const identifyUser = vi.fn().mockResolvedValue({ id: "resolved-user" });
+      const identifyUser = vi
+        .fn()
+        .mockResolvedValue({ id: "resolved-user", name: "Resolved User" });
       const runtime = createIntelligenceRuntime(platform);
       runtime.identifyUser = identifyUser;
       const request = createConnectRequest(
@@ -377,6 +408,7 @@ describe("handleConnectAgent", () => {
       expect(platform.ɵconnectThread).toHaveBeenCalledWith({
         threadId: "thread-1",
         userId: "resolved-user",
+        runId: "run-1",
         lastSeenEventId: "event-9",
       });
     });
@@ -386,7 +418,28 @@ describe("handleConnectAgent", () => {
         ɵconnectThread: vi.fn(),
       };
       const runtime = createIntelligenceRuntime(platform);
-      runtime.identifyUser = vi.fn().mockResolvedValue({ id: "" });
+      runtime.identifyUser = vi
+        .fn()
+        .mockResolvedValue({ id: "", name: "User" });
+
+      const response = await handleConnectAgent({
+        runtime,
+        request: createConnectRequest(),
+        agentId: "my-agent",
+      });
+
+      expect(response.status).toBe(400);
+      expect(platform.ɵconnectThread).not.toHaveBeenCalled();
+    });
+
+    it("returns 400 when identifyUser returns an invalid name", async () => {
+      const platform = {
+        ɵconnectThread: vi.fn(),
+      };
+      const runtime = createIntelligenceRuntime(platform);
+      runtime.identifyUser = vi
+        .fn()
+        .mockResolvedValue({ id: "user-1", name: "" });
 
       const response = await handleConnectAgent({
         runtime,

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

@@ -298,7 +298,9 @@ describe("handleRunAgent", () => {
         generateThreadNames?: boolean;
         identifyUser?: (
           request: Request,
-        ) => { id: string } | Promise<{ id: string }>;
+        ) =>
+          | { id: string; name: string }
+          | Promise<{ id: string; name: string }>;
       },
     ) => {
       const runner = Object.create(IntelligenceAgentRunner.prototype);
@@ -318,7 +320,8 @@ describe("handleRunAgent", () => {
         generateThreadNames: options?.generateThreadNames ?? false,
         intelligence: platform,
         identifyUser:
-          options?.identifyUser ?? vi.fn().mockResolvedValue({ id: "user-1" }),
+          options?.identifyUser ??
+          vi.fn().mockResolvedValue({ id: "user-1", name: "User One" }),
       } as unknown as CopilotRuntime;
     };
 
@@ -395,7 +398,9 @@ describe("handleRunAgent", () => {
           .fn()
           .mockResolvedValue({ joinToken: "jt-123", joinCode: "jc-123" }),
       };
-      const identifyUser = vi.fn().mockResolvedValue({ id: "resolved-user" });
+      const identifyUser = vi
+        .fn()
+        .mockResolvedValue({ id: "resolved-user", name: "Resolved User" });
       const runtime = createIntelligenceRuntime(agent, platform, {
         identifyUser,
       });
@@ -870,7 +875,29 @@ describe("handleRunAgent", () => {
         ɵacquireThreadLock: vi.fn(),
       };
       const runtime = createIntelligenceRuntime(agent, platform, {
-        identifyUser: vi.fn().mockResolvedValue({ id: "" }),
+        identifyUser: vi.fn().mockResolvedValue({ id: "", name: "User" }),
+      });
+
+      const response = await handleRunAgent({
+        runtime,
+        request: createRunRequest(),
+        agentId: "my-agent",
+      });
+
+      expect(response.status).toBe(400);
+      expect(platform.getOrCreateThread).not.toHaveBeenCalled();
+      expect(platform.ɵacquireThreadLock).not.toHaveBeenCalled();
+    });
+
+    it("returns 400 when identifyUser returns an invalid name", async () => {
+      const agent = createAgentForIntelligence();
+      const platform = {
+        getOrCreateThread: vi.fn(),
+        getThreadMessages: vi.fn(),
+        ɵacquireThreadLock: vi.fn(),
+      };
+      const runtime = createIntelligenceRuntime(agent, platform, {
+        identifyUser: vi.fn().mockResolvedValue({ id: "user-1", name: "" }),
       });
 
       const response = await handleRunAgent({

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

@@ -10,12 +10,13 @@ import {
 import { CopilotRuntime } from "../core/runtime";
 
 describe("thread handlers", () => {
-  const createIdentifyUser = () => vi.fn().mockResolvedValue({ id: "user-1" });
+  const createIdentifyUser = () =>
+    vi.fn().mockResolvedValue({ id: "user-1", name: "User One" });
 
   const createIntelligenceRuntime = (options?: {
     identifyUser?: (
       request: Request,
-    ) => { id: string } | Promise<{ id: string }>;
+    ) => { id: string; name: string } | Promise<{ id: string; name: string }>;
     intelligence?: Record<string, unknown>;
   }) =>
     ({
@@ -92,7 +93,25 @@ describe("thread handlers", () => {
     };
     const runtime = createIntelligenceRuntime({
       intelligence,
-      identifyUser: vi.fn().mockResolvedValue({ id: "" }),
+      identifyUser: vi.fn().mockResolvedValue({ id: "", name: "User" }),
+    });
+
+    const response = await handleListThreads({
+      runtime,
+      request: new Request("https://example.com/threads?agentId=agent-1"),
+    });
+
+    expect(response.status).toBe(400);
+    expect(intelligence.listThreads).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when identifyUser returns an invalid name for thread list", async () => {
+    const intelligence = {
+      listThreads: vi.fn(),
+    };
+    const runtime = createIntelligenceRuntime({
+      intelligence,
+      identifyUser: vi.fn().mockResolvedValue({ id: "user-1", name: "" }),
     });
 
     const response = await handleListThreads({
@@ -258,7 +277,50 @@ describe("thread handlers", () => {
     };
     const runtime = createIntelligenceRuntime({
       intelligence,
-      identifyUser: vi.fn().mockResolvedValue({ id: "" }),
+      identifyUser: vi.fn().mockResolvedValue({ id: "", name: "User" }),
+    });
+
+    const updateResponse = await handleUpdateThread({
+      runtime,
+      request: createMutationRequest("/threads/thread-1", "PATCH", {
+        agentId: "agent-1",
+      }),
+      threadId: "thread-1",
+    });
+    expect(updateResponse.status).toBe(400);
+
+    const archiveResponse = await handleArchiveThread({
+      runtime,
+      request: createMutationRequest("/threads/thread-1/archive", "POST", {
+        agentId: "agent-1",
+      }),
+      threadId: "thread-1",
+    });
+    expect(archiveResponse.status).toBe(400);
+
+    const deleteResponse = await handleDeleteThread({
+      runtime,
+      request: createMutationRequest("/threads/thread-1", "DELETE", {
+        agentId: "agent-1",
+      }),
+      threadId: "thread-1",
+    });
+    expect(deleteResponse.status).toBe(400);
+
+    expect(intelligence.updateThread).not.toHaveBeenCalled();
+    expect(intelligence.archiveThread).not.toHaveBeenCalled();
+    expect(intelligence.deleteThread).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when identifyUser returns an invalid name for thread mutations", async () => {
+    const intelligence = {
+      updateThread: vi.fn(),
+      archiveThread: vi.fn(),
+      deleteThread: vi.fn(),
+    };
+    const runtime = createIntelligenceRuntime({
+      intelligence,
+      identifyUser: vi.fn().mockResolvedValue({ id: "user-1", name: "" }),
     });
 
     const updateResponse = await handleUpdateThread({

package/src/v2/runtime/__tests__/integration/node-servers.integration.test.ts

@@ -10,6 +10,10 @@
 
 import { multiEndpointSuite } from "./suites/multi-endpoint.suite";
 import { singleEndpointSuite } from "./suites/single-endpoint.suite";
+import {
+  debugEventsSuite,
+  debugEventsProductionGuardSuite,
+} from "./suites/debug-events.suite";
 
 // Server factories
 import { createExpressMultiServer } from "./servers/express-multi";
@@ -37,3 +41,18 @@ singleEndpointSuite("Node", createNodeSingleServer);
 singleEndpointSuite("Fetch", (opts) =>
   Promise.resolve(createFetchDirectHandler("single-route", opts)),
 );
+
+// ─── Debug Events ───────────────────────────────────────────────────
+
+debugEventsSuite("Express", createExpressMultiServer);
+debugEventsSuite("Hono", createHonoMultiServer);
+debugEventsSuite("Node", createNodeMultiServer);
+debugEventsSuite("Fetch", (opts) =>
+  Promise.resolve(createFetchDirectHandler("multi-route", opts)),
+);
+
+debugEventsProductionGuardSuite(
+  () => createFetchDirectHandler("multi-route"),
+  "http://localhost",
+  "/api/copilotkit",
+);