@copilotkit/runtime 1.56.2 → 1.56.4

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__/express-single-telemetry.integration.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Integration test: Express single-route adapter (deprecated convenience
+ * wrapper) + telemetry. This adapter delegates to createCopilotExpressHandler
+ * with mode: "single-route".
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { AbstractAgent } from "@ag-ui/client";
+import { Observable, of } from "rxjs";
+
+import { telemetry } from "../telemetry";
+import { createCopilotEndpointSingleRouteExpress } from "../endpoints/express-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;
+}
+
+function makeRuntime() {
+  const runner = {
+    run: () =>
+      new Observable((observer) => {
+        observer.next({});
+        observer.complete();
+        return () => undefined;
+      }),
+    connect: () => of({}),
+    stop: async () => true,
+  };
+  return new CopilotRuntime({
+    agents: { default: makeAgent() },
+    runner,
+  });
+}
+
+describe("Express 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 = makeRuntime();
+    createCopilotEndpointSingleRouteExpress({
+      runtime,
+      basePath: "/api/copilotkit",
+    });
+
+    await vi.waitFor(() => {
+      expect(captureSpy).toHaveBeenCalledWith(
+        "oss.runtime.instance_created",
+        expect.objectContaining({
+          agentsAmount: 1,
+          "cloud.api_key_provided": false,
+        }),
+      );
+    });
+  });
+});

package/src/v2/runtime/__tests__/express-telemetry.integration.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Integration test: Express adapter + telemetry.
+ */
+import express from "express";
+import request from "supertest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { AbstractAgent } from "@ag-ui/client";
+import { Observable, of } from "rxjs";
+
+import { telemetry } from "../telemetry";
+import { createCopilotExpressHandler } from "../endpoints/express";
+import { CopilotRuntime } from "../core/runtime";
+
+function makeAgent(): AbstractAgent {
+  const a: unknown = { execute: async () => ({ events: [] }) };
+  (a as { clone: () => unknown }).clone = () => makeAgent();
+  return a as AbstractAgent;
+}
+
+function makeRuntime() {
+  const runner = {
+    run: () =>
+      new Observable((observer) => {
+        observer.next({});
+        observer.complete();
+        return () => undefined;
+      }),
+    connect: () => of({}),
+    stop: async () => true,
+  };
+  return new CopilotRuntime({
+    agents: { default: makeAgent() },
+    runner,
+  });
+}
+
+describe("Express 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 (multi-route)", async () => {
+    const runtime = makeRuntime();
+    createCopilotExpressHandler({ runtime, basePath: "/" });
+
+    await vi.waitFor(() => {
+      expect(captureSpy).toHaveBeenCalledWith(
+        "oss.runtime.instance_created",
+        expect.objectContaining({
+          agentsAmount: 1,
+          "cloud.api_key_provided": false,
+        }),
+      );
+    });
+  });
+
+  it("fires copilot_request_created when a real HTTP request hits the handler", async () => {
+    const runtime = makeRuntime();
+    const app = express();
+    app.use(createCopilotExpressHandler({ runtime, basePath: "/" }));
+
+    await request(app)
+      .post("/agent/default/run")
+      .set("Content-Type", "application/json")
+      .send({ messages: [], state: {}, threadId: "t1" });
+
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.copilot_request_created",
+      expect.objectContaining({
+        requestType: "run",
+        "cloud.api_key_provided": false,
+      }),
+    );
+  });
+
+  it("includes cloud.public_api_key on request when header is present", async () => {
+    const runtime = makeRuntime();
+    const app = express();
+    app.use(createCopilotExpressHandler({ runtime, basePath: "/" }));
+
+    await request(app)
+      .post("/agent/default/run")
+      .set("Content-Type", "application/json")
+      .set("x-copilotcloud-public-api-key", "ck_pub_test_xyz")
+      .send({ messages: [], state: {}, threadId: "t1" });
+
+    expect(captureSpy).toHaveBeenCalledWith(
+      "oss.runtime.copilot_request_created",
+      expect.objectContaining({
+        "cloud.api_key_provided": true,
+        "cloud.public_api_key": "ck_pub_test_xyz",
+      }),
+    );
+  });
+});

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