@copilotkit/runtime 1.56.2 → 1.56.4

package/dist/v2/runtime/telemetry/telemetry-client.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-client.mjs","names":["uuidv4","scarfClient"],"sources":["../../../../src/v2/runtime/telemetry/telemetry-client.ts"],"sourcesContent":["import { Analytics } from \"@segment/analytics-node\";\nimport { AnalyticsEvents } from \"./events\";\nimport { flattenObject } from \"./utils\";\nimport { v4 as uuidv4 } from \"uuid\";\nimport scarfClient from \"./scarf-client\";\n\nexport function isTelemetryDisabled(): boolean {\n  return (\n    (process.env as Record<string, string | undefined>)\n      .COPILOTKIT_TELEMETRY_DISABLED === \"true\" ||\n    (process.env as Record<string, string | undefined>)\n      .COPILOTKIT_TELEMETRY_DISABLED === \"1\" ||\n    (process.env as Record<string, string | undefined>).DO_NOT_TRACK ===\n      \"true\" ||\n    (process.env as Record<string, string | undefined>).DO_NOT_TRACK === \"1\"\n  );\n}\n\nexport class TelemetryClient {\n  segment: Analytics | undefined;\n  globalProperties: Record<string, any> = {};\n  private telemetryDisabled: boolean = false;\n  private sampleRate: number = 0.05;\n  private anonymousId = `anon_${uuidv4()}`;\n\n  constructor({\n    telemetryDisabled,\n    sampleRate,\n  }: {\n    telemetryDisabled?: boolean;\n    sampleRate?: number;\n  } = {}) {\n    this.telemetryDisabled = telemetryDisabled ?? isTelemetryDisabled();\n\n    if (this.telemetryDisabled) {\n      this.setSampleRate(sampleRate);\n      return;\n    }\n\n    this.setSampleRate(sampleRate);\n\n    const writeKey =\n      process.env.COPILOTKIT_SEGMENT_WRITE_KEY ||\n      \"n7XAZtQCGS2v1vvBy3LgBCv2h3Y8whja\";\n\n    this.segment = new Analytics({\n      writeKey,\n    });\n  }\n\n  private shouldSendEvent() {\n    if (this.telemetryDisabled) {\n      return false;\n    }\n    const randomNumber = Math.random();\n    return randomNumber < this.sampleRate;\n  }\n\n  async capture<K extends keyof AnalyticsEvents>(\n    event: K,\n    properties: AnalyticsEvents[K],\n  ) {\n    if (!this.shouldSendEvent()) {\n      return;\n    }\n\n    const flattenedProperties = flattenObject(properties);\n    const propertiesWithGlobal = {\n      ...this.globalProperties,\n      ...flattenedProperties,\n    };\n    const orderedPropertiesWithGlobal = Object.keys(propertiesWithGlobal)\n      .sort()\n      .reduce(\n        (obj, key) => {\n          obj[key] = propertiesWithGlobal[key];\n          return obj;\n        },\n        {} as Record<string, any>,\n      );\n\n    if (this.segment) {\n      this.segment.track({\n        anonymousId: this.anonymousId,\n        event,\n        properties: { ...orderedPropertiesWithGlobal },\n      });\n    }\n\n    await scarfClient.logEvent({\n      event,\n    });\n  }\n\n  setGlobalProperties(properties: Record<string, any>) {\n    const flattenedProperties = flattenObject(properties);\n    this.globalProperties = {\n      ...this.globalProperties,\n      ...flattenedProperties,\n    };\n  }\n\n  private setSampleRate(sampleRate: number | undefined) {\n    let _sampleRate: number;\n\n    _sampleRate = sampleRate ?? 0.05;\n\n    if (process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE) {\n      _sampleRate = parseFloat(process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE);\n    }\n\n    if (_sampleRate < 0 || _sampleRate > 1) {\n      throw new Error(\"Sample rate must be between 0 and 1\");\n    }\n\n    this.sampleRate = _sampleRate;\n    this.setGlobalProperties({\n      sampleRate: this.sampleRate,\n      sampleRateAdjustmentFactor: 1 - this.sampleRate,\n      sampleWeight: 1 / this.sampleRate,\n    });\n  }\n}\n\nconst telemetry = new TelemetryClient();\nexport default telemetry;\n"],"mappings":";;;;;;;AAMA,SAAgB,sBAA+B;AAC7C,QACG,QAAQ,IACN,kCAAkC,UACpC,QAAQ,IACN,kCAAkC,OACpC,QAAQ,IAA2C,iBAClD,UACD,QAAQ,IAA2C,iBAAiB;;AAIzE,IAAa,kBAAb,MAA6B;CAO3B,YAAY,EACV,mBACA,eAIE,EAAE,EAAE;0BAXgC,EAAE;2BACL;oBACR;qBACP,QAAQA,IAAQ;AASpC,OAAK,oBAAoB,qBAAqB,qBAAqB;AAEnE,MAAI,KAAK,mBAAmB;AAC1B,QAAK,cAAc,WAAW;AAC9B;;AAGF,OAAK,cAAc,WAAW;AAM9B,OAAK,UAAU,IAAI,UAAU,EAC3B,UAJA,QAAQ,IAAI,gCACZ,oCAID,CAAC;;CAGJ,AAAQ,kBAAkB;AACxB,MAAI,KAAK,kBACP,QAAO;AAGT,SADqB,KAAK,QAAQ,GACZ,KAAK;;CAG7B,MAAM,QACJ,OACA,YACA;AACA,MAAI,CAAC,KAAK,iBAAiB,CACzB;EAGF,MAAM,sBAAsB,cAAc,WAAW;EACrD,MAAM,uBAAuB;GAC3B,GAAG,KAAK;GACR,GAAG;GACJ;EACD,MAAM,8BAA8B,OAAO,KAAK,qBAAqB,CAClE,MAAM,CACN,QACE,KAAK,QAAQ;AACZ,OAAI,OAAO,qBAAqB;AAChC,UAAO;KAET,EAAE,CACH;AAEH,MAAI,KAAK,QACP,MAAK,QAAQ,MAAM;GACjB,aAAa,KAAK;GAClB;GACA,YAAY,EAAE,GAAG,6BAA6B;GAC/C,CAAC;AAGJ,QAAMC,qBAAY,SAAS,EACzB,OACD,CAAC;;CAGJ,oBAAoB,YAAiC;EACnD,MAAM,sBAAsB,cAAc,WAAW;AACrD,OAAK,mBAAmB;GACtB,GAAG,KAAK;GACR,GAAG;GACJ;;CAGH,AAAQ,cAAc,YAAgC;EACpD,IAAI;AAEJ,gBAAc,cAAc;AAE5B,MAAI,QAAQ,IAAI,iCACd,eAAc,WAAW,QAAQ,IAAI,iCAAiC;AAGxE,MAAI,cAAc,KAAK,cAAc,EACnC,OAAM,IAAI,MAAM,sCAAsC;AAGxD,OAAK,aAAa;AAClB,OAAK,oBAAoB;GACvB,YAAY,KAAK;GACjB,4BAA4B,IAAI,KAAK;GACrC,cAAc,IAAI,KAAK;GACxB,CAAC;;;AAIN,MAAM,YAAY,IAAI,iBAAiB"}
+{"version":3,"file":"telemetry-client.mjs","names":["scarfClient"],"sources":["../../../../src/v2/runtime/telemetry/telemetry-client.ts"],"sourcesContent":["import { AnalyticsEvents } from \"./events\";\nimport scarfClient from \"./scarf-client\";\n\nexport function isTelemetryDisabled(): boolean {\n  return (\n    (process.env as Record<string, string | undefined>)\n      .COPILOTKIT_TELEMETRY_DISABLED === \"true\" ||\n    (process.env as Record<string, string | undefined>)\n      .COPILOTKIT_TELEMETRY_DISABLED === \"1\" ||\n    (process.env as Record<string, string | undefined>).DO_NOT_TRACK ===\n      \"true\" ||\n    (process.env as Record<string, string | undefined>).DO_NOT_TRACK === \"1\"\n  );\n}\n\nexport class TelemetryClient {\n  private telemetryDisabled: boolean = false;\n  private sampleRate: number = 0.05;\n\n  constructor({\n    telemetryDisabled,\n    sampleRate,\n  }: {\n    telemetryDisabled?: boolean;\n    sampleRate?: number;\n  } = {}) {\n    this.telemetryDisabled = telemetryDisabled ?? isTelemetryDisabled();\n    this.setSampleRate(sampleRate);\n  }\n\n  private shouldSendEvent() {\n    if (this.telemetryDisabled) {\n      return false;\n    }\n    const randomNumber = Math.random();\n    return randomNumber < this.sampleRate;\n  }\n\n  async capture<K extends keyof AnalyticsEvents>(\n    event: K,\n    _properties: AnalyticsEvents[K],\n  ) {\n    if (!this.shouldSendEvent()) {\n      return;\n    }\n\n    await scarfClient.logEvent({\n      event,\n    });\n  }\n\n  private setSampleRate(sampleRate: number | undefined) {\n    let _sampleRate: number;\n\n    _sampleRate = sampleRate ?? 0.05;\n\n    if (process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE) {\n      _sampleRate = parseFloat(process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE);\n    }\n\n    if (_sampleRate < 0 || _sampleRate > 1) {\n      throw new Error(\"Sample rate must be between 0 and 1\");\n    }\n\n    this.sampleRate = _sampleRate;\n  }\n}\n\nconst telemetry = new TelemetryClient();\nexport default telemetry;\n"],"mappings":";;;;AAGA,SAAgB,sBAA+B;AAC7C,QACG,QAAQ,IACN,kCAAkC,UACpC,QAAQ,IACN,kCAAkC,OACpC,QAAQ,IAA2C,iBAClD,UACD,QAAQ,IAA2C,iBAAiB;;AAIzE,IAAa,kBAAb,MAA6B;CAI3B,YAAY,EACV,mBACA,eAIE,EAAE,EAAE;2BAT6B;oBACR;AAS3B,OAAK,oBAAoB,qBAAqB,qBAAqB;AACnE,OAAK,cAAc,WAAW;;CAGhC,AAAQ,kBAAkB;AACxB,MAAI,KAAK,kBACP,QAAO;AAGT,SADqB,KAAK,QAAQ,GACZ,KAAK;;CAG7B,MAAM,QACJ,OACA,aACA;AACA,MAAI,CAAC,KAAK,iBAAiB,CACzB;AAGF,QAAMA,qBAAY,SAAS,EACzB,OACD,CAAC;;CAGJ,AAAQ,cAAc,YAAgC;EACpD,IAAI;AAEJ,gBAAc,cAAc;AAE5B,MAAI,QAAQ,IAAI,iCACd,eAAc,WAAW,QAAQ,IAAI,iCAAiC;AAGxE,MAAI,cAAc,KAAK,cAAc,EACnC,OAAM,IAAI,MAAM,sCAAsC;AAGxD,OAAK,aAAa;;;AAItB,MAAM,YAAY,IAAI,iBAAiB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/runtime",
-  "version": "1.56.2",
+  "version": "1.56.4",
   "private": false,
   "keywords": [
     "ai",
@@ -87,7 +87,7 @@
     "@ai-sdk/google-vertex": "^3.0.97",
     "@ai-sdk/mcp": "^1.0.21",
     "@ai-sdk/openai": "^3.0.36",
-    "@copilotkit/license-verifier": "0.0.1-a1",
+    "@copilotkit/license-verifier": "0.2.0",
     "@graphql-yoga/plugin-defer-stream": "^3.3.1",
     "@hono/node-server": "^1.13.5",
     "@modelcontextprotocol/sdk": "^1.18.2",
@@ -115,7 +115,7 @@
     "uuid": "^10.0.0",
     "ws": "^8.18.0",
     "zod": "^3.23.3",
-    "@copilotkit/shared": "1.56.2"
+    "@copilotkit/shared": "1.56.4"
   },
   "devDependencies": {
     "@copilotkit/aimock": "^1.10.0",

package/src/agents/langgraph/__tests__/event-source.test.ts

@@ -0,0 +1,256 @@
+import { RemoteLangGraphEventSource } from "../event-source";
+import { LangGraphEventTypes } from "../events";
+
+/**
+ * Access private methods for testing via a helper.
+ * These are pure functions that extract data from LangGraph events.
+ */
+function getSource() {
+  return new RemoteLangGraphEventSource();
+}
+
+// Helper to call private methods. Returns `any` — type safety is traded for
+// access to private implementation details that have no public test surface.
+function callPrivate(
+  source: RemoteLangGraphEventSource,
+  method: string,
+  ...args: any[]
+) {
+  return (source as any)[method](...args);
+}
+
+describe("shouldEmitToolCall", () => {
+  const source = getSource();
+
+  it("returns true when shouldEmitToolCalls is true (boolean)", () => {
+    expect(callPrivate(source, "shouldEmitToolCall", true, "anyTool")).toBe(
+      true,
+    );
+  });
+
+  it("returns false when shouldEmitToolCalls is false (boolean)", () => {
+    expect(callPrivate(source, "shouldEmitToolCall", false, "anyTool")).toBe(
+      false,
+    );
+  });
+
+  it("returns true when tool name matches string", () => {
+    expect(
+      callPrivate(source, "shouldEmitToolCall", "SearchTool", "SearchTool"),
+    ).toBe(true);
+  });
+
+  it("returns false when tool name does not match string", () => {
+    expect(
+      callPrivate(source, "shouldEmitToolCall", "SearchTool", "OtherTool"),
+    ).toBe(false);
+  });
+
+  it("returns true when tool name is in array", () => {
+    expect(
+      callPrivate(
+        source,
+        "shouldEmitToolCall",
+        ["SearchTool", "FetchTool"],
+        "FetchTool",
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false when tool name is not in array", () => {
+    expect(
+      callPrivate(
+        source,
+        "shouldEmitToolCall",
+        ["SearchTool", "FetchTool"],
+        "OtherTool",
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("getCurrentMessageId", () => {
+  const source = getSource();
+
+  it("extracts id from standard kwargs layout", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { kwargs: { id: "msg-std-123" } } },
+    };
+    expect(callPrivate(source, "getCurrentMessageId", event)).toBe(
+      "msg-std-123",
+    );
+  });
+
+  it("extracts id from LangGraph Platform layout (no kwargs)", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { id: "msg-plat-456" } },
+    };
+    expect(callPrivate(source, "getCurrentMessageId", event)).toBe(
+      "msg-plat-456",
+    );
+  });
+
+  it("prefers kwargs layout when both present", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { kwargs: { id: "kwargs-id" }, id: "direct-id" } },
+    };
+    expect(callPrivate(source, "getCurrentMessageId", event)).toBe("kwargs-id");
+  });
+
+  it("returns undefined when neither layout is present", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: {} },
+    };
+    expect(callPrivate(source, "getCurrentMessageId", event)).toBeUndefined();
+  });
+
+  it("handles missing data gracefully", () => {
+    const event = { event: LangGraphEventTypes.OnChatModelStream };
+    expect(callPrivate(source, "getCurrentMessageId", event)).toBeUndefined();
+  });
+});
+
+describe("getCurrentToolCallChunks", () => {
+  const source = getSource();
+
+  it("extracts chunks from standard kwargs layout", () => {
+    const chunks = [{ name: "tool1", args: "{}", id: "tc-1", index: 0 }];
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { kwargs: { tool_call_chunks: chunks } } },
+    };
+    expect(callPrivate(source, "getCurrentToolCallChunks", event)).toEqual(
+      chunks,
+    );
+  });
+
+  it("extracts chunks from LangGraph Platform layout", () => {
+    const chunks = [{ name: "tool2", args: "{}", id: "tc-2", index: 0 }];
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { tool_call_chunks: chunks } },
+    };
+    expect(callPrivate(source, "getCurrentToolCallChunks", event)).toEqual(
+      chunks,
+    );
+  });
+
+  it("returns undefined when no chunks present", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: {} },
+    };
+    expect(
+      callPrivate(source, "getCurrentToolCallChunks", event),
+    ).toBeUndefined();
+  });
+});
+
+describe("getResponseMetadata", () => {
+  const source = getSource();
+
+  it("extracts metadata from standard kwargs layout", () => {
+    const meta = { finish_reason: "stop" };
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { kwargs: { response_metadata: meta } } },
+    };
+    expect(callPrivate(source, "getResponseMetadata", event)).toEqual(meta);
+  });
+
+  it("extracts metadata from LangGraph Platform layout", () => {
+    const meta = { finish_reason: "tool_calls" };
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { response_metadata: meta } },
+    };
+    expect(callPrivate(source, "getResponseMetadata", event)).toEqual(meta);
+  });
+
+  it("returns undefined when no metadata present", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: {} },
+    };
+    expect(callPrivate(source, "getResponseMetadata", event)).toBeUndefined();
+  });
+});
+
+describe("getCurrentContent", () => {
+  const source = getSource();
+
+  it("extracts string content from kwargs layout", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { kwargs: { content: "hello world" } } },
+    };
+    expect(callPrivate(source, "getCurrentContent", event)).toBe("hello world");
+  });
+
+  it("extracts string content from Platform layout", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { content: "platform content" } },
+    };
+    expect(callPrivate(source, "getCurrentContent", event)).toBe(
+      "platform content",
+    );
+  });
+
+  it("extracts text from array content (Anthropic format)", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: {
+        chunk: {
+          kwargs: {
+            content: [{ text: "array text", type: "text", index: 0 }],
+          },
+        },
+      },
+    };
+    expect(callPrivate(source, "getCurrentContent", event)).toBe("array text");
+  });
+
+  it("returns null when no content and no tool call chunks", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { kwargs: {} } },
+    };
+    expect(callPrivate(source, "getCurrentContent", event)).toBeNull();
+  });
+
+  it("falls back to tool_call_chunks args when no content", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: {
+        chunk: {
+          kwargs: {
+            content: "",
+            tool_call_chunks: [{ args: '{"key":"val"}' }],
+          },
+        },
+      },
+    };
+    expect(callPrivate(source, "getCurrentContent", event)).toBe(
+      '{"key":"val"}',
+    );
+  });
+
+  it("handles missing data gracefully", () => {
+    const event = { event: LangGraphEventTypes.OnChatModelStream };
+    expect(callPrivate(source, "getCurrentContent", event)).toBeNull();
+  });
+
+  it("returns empty string when content is empty string", () => {
+    const event = {
+      event: LangGraphEventTypes.OnChatModelStream,
+      data: { chunk: { kwargs: { content: "" } } },
+    };
+    // Empty string is a valid string, so typeof === "string" returns it as-is
+    expect(callPrivate(source, "getCurrentContent", event)).toBe("");
+  });
+});

package/src/graphql/resolvers/__tests__/resolve-message-id.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { resolveMessageId } from "../resolve-message-id";
+
+describe("resolveMessageId (#2118)", () => {
+  it("preserves a provided non-empty id verbatim", () => {
+    expect(resolveMessageId("msg-123")).toBe("msg-123");
+  });
+
+  it.each(["", null, undefined] as const)(
+    "falls back to a generated id when the event id is %p",
+    (input) => {
+      const id = resolveMessageId(input);
+      // randomId() always produces the "ck-<uuid>" shape; the important
+      // contract for #2118 is that the returned value is a non-empty string,
+      // never null/undefined.
+      expect(id).toMatch(/^ck-[0-9a-f-]{36}$/);
+    },
+  );
+
+  it("generates a fresh id on each fallback call", () => {
+    const a = resolveMessageId(undefined);
+    const b = resolveMessageId(undefined);
+    expect(a).not.toBe(b);
+  });
+});

package/src/graphql/resolvers/copilot.resolver.ts

@@ -58,6 +58,7 @@ import {
 } from "../types/converted";
 import telemetry from "../../lib/telemetry-client";
 import { randomId } from "@copilotkit/shared";
+import { resolveMessageId } from "./resolve-message-id";
 import { AgentsResponse } from "../types/agents-response.type";
 import { LangGraphEventTypes } from "../../agents/langgraph/events";
 import {
@@ -488,7 +489,7 @@ export class CopilotResolver {
                   typeof MessageStatusUnion
                 >();
 
-                const messageId = event.messageId;
+                const messageId = resolveMessageId(event.messageId);
                 // push the new message
                 pushMessage({
                   id: messageId,

package/src/graphql/resolvers/resolve-message-id.ts

@@ -0,0 +1,14 @@
+import { randomId } from "@copilotkit/shared";
+
+/**
+ * Resolve the id to use for a streamed TextMessageOutput.
+ *
+ * Upstream events occasionally arrive with `messageId` missing, null, or an
+ * empty string. We fall back to a freshly generated id in those cases so the
+ * resulting output never surfaces a null id to the GraphQL client (#2118).
+ */
+export function resolveMessageId(
+  eventMessageId: string | null | undefined,
+): string {
+  return eventMessageId || randomId();
+}

package/src/lib/runtime/__tests__/handle-service-adapter.test.ts

@@ -0,0 +1,108 @@
+import type { LanguageModel } from "ai";
+import { CopilotKitMisuseError } from "@copilotkit/shared";
+import { describe, expect, it } from "vitest";
+import { BuiltInAgent } from "../../../agent";
+import type { CopilotServiceAdapter } from "../../../service-adapters";
+import { CopilotRuntime } from "../copilot-runtime";
+
+function makeAdapter(
+  overrides?: Partial<CopilotServiceAdapter>,
+): CopilotServiceAdapter {
+  return {
+    name: "TestAdapter",
+    async process() {
+      throw new Error("process() is not expected to be called in these tests");
+    },
+    ...overrides,
+  };
+}
+
+async function getDefaultAgent(runtime: CopilotRuntime) {
+  const agents = await runtime.instance.agents;
+  return agents.default;
+}
+
+// `BuiltInAgent.config` is private; reading it is the only way to verify the
+// correct model was passed through without running the entire agent pipeline.
+// This narrow accessor is the Rule 2 exception, documented here once rather
+// than inline at each call site.
+function getBuiltInAgentModel(agent: BuiltInAgent): unknown {
+  return (agent as unknown as { config: { model: unknown } }).config.model;
+}
+
+describe("CopilotRuntime#handleServiceAdapter (#3217)", () => {
+  it("uses the adapter's pre-configured LanguageModel when getLanguageModel() returns one", async () => {
+    const fakeLanguageModel = {
+      specificationVersion: "v1",
+    } as unknown as LanguageModel;
+    const runtime = new CopilotRuntime();
+
+    runtime.handleServiceAdapter(
+      makeAdapter({
+        name: "OpenAIAdapter",
+        provider: "openai",
+        model: "gpt-4o",
+        getLanguageModel: () => fakeLanguageModel,
+      }),
+    );
+
+    const agent = await getDefaultAgent(runtime);
+    expect(agent).toBeInstanceOf(BuiltInAgent);
+    expect(getBuiltInAgentModel(agent as BuiltInAgent)).toBe(fakeLanguageModel);
+  });
+
+  it("builds a 'provider/model' string when only provider+model are exposed", async () => {
+    const runtime = new CopilotRuntime();
+
+    runtime.handleServiceAdapter(
+      makeAdapter({
+        name: "GroqAdapter",
+        provider: "groq",
+        model: "llama-3.3-70b-versatile",
+      }),
+    );
+
+    const agent = await getDefaultAgent(runtime);
+    expect(agent).toBeInstanceOf(BuiltInAgent);
+    expect(getBuiltInAgentModel(agent as BuiltInAgent)).toBe(
+      "groq/llama-3.3-70b-versatile",
+    );
+  });
+
+  it("throws CopilotKitMisuseError when no model source is available (LangChainAdapter regression)", async () => {
+    const runtime = new CopilotRuntime();
+
+    runtime.handleServiceAdapter(makeAdapter({ name: "LangChainAdapter" }));
+
+    await expect(runtime.instance.agents).rejects.toBeInstanceOf(
+      CopilotKitMisuseError,
+    );
+    await expect(runtime.instance.agents).rejects.toThrow(
+      /Service adapter "LangChainAdapter" does not provide model information/,
+    );
+  });
+
+  it("falls back to 'unknown' in the thrown error when the adapter has no name", async () => {
+    const runtime = new CopilotRuntime();
+
+    runtime.handleServiceAdapter(makeAdapter({ name: undefined }));
+
+    await expect(runtime.instance.agents).rejects.toThrow(
+      /Service adapter "unknown" does not provide model information/,
+    );
+  });
+
+  it("does not throw when provider is set without a model — but must not emit 'undefined/undefined'", async () => {
+    // Guards the specific #3217 regression: when only one half of the pair is
+    // present, we must NOT synthesize a bogus "provider/undefined" string.
+    const runtime = new CopilotRuntime();
+
+    runtime.handleServiceAdapter(
+      makeAdapter({ name: "PartialAdapter", provider: "openai" }),
+    );
+
+    await expect(runtime.instance.agents).rejects.toThrow(
+      CopilotKitMisuseError,
+    );
+  });
+});

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

@@ -0,0 +1,137 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { fetchWithRetry, parseRetryAfter, RETRY_CONFIG } from "../retry-utils";
+
+function responseWithRetryAfter(
+  headerValue: string | null,
+  status = 429,
+): Response {
+  const headers = new Headers();
+  if (headerValue !== null) headers.set("Retry-After", headerValue);
+  return new Response(null, { status, headers });
+}
+
+describe("parseRetryAfter", () => {
+  it("returns undefined when the Retry-After header is absent", () => {
+    expect(parseRetryAfter(responseWithRetryAfter(null))).toBeUndefined();
+  });
+
+  it("parses integer seconds into milliseconds", () => {
+    expect(parseRetryAfter(responseWithRetryAfter("5"))).toBe(5000);
+  });
+
+  it("treats zero seconds as zero delay", () => {
+    expect(parseRetryAfter(responseWithRetryAfter("0"))).toBe(0);
+  });
+
+  it("clamps a negative numeric value to zero", () => {
+    // `-1` fails the `seconds >= 0` guard and falls through to Date.parse,
+    // which interprets it as a year-in-the-past timestamp; the past-date
+    // branch then clamps to 0. The behavior is lenient rather than strict.
+    expect(parseRetryAfter(responseWithRetryAfter("-1"))).toBe(0);
+  });
+
+  it("parses an HTTP-date in the future as the delta to now", () => {
+    const now = Date.parse("2026-04-22T12:00:00Z");
+    vi.useFakeTimers();
+    vi.setSystemTime(now);
+    try {
+      const future = new Date(now + 30_000).toUTCString();
+      expect(parseRetryAfter(responseWithRetryAfter(future))).toBe(30_000);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("clamps an HTTP-date in the past to zero", () => {
+    const now = Date.parse("2026-04-22T12:00:00Z");
+    vi.useFakeTimers();
+    vi.setSystemTime(now);
+    try {
+      const past = new Date(now - 60_000).toUTCString();
+      expect(parseRetryAfter(responseWithRetryAfter(past))).toBe(0);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("returns undefined for unparseable values", () => {
+    expect(parseRetryAfter(responseWithRetryAfter("soon"))).toBeUndefined();
+  });
+});
+
+describe("fetchWithRetry Retry-After handling (#3637)", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("honors Retry-After within the allowed maximum on 429", async () => {
+    fetchMock
+      .mockResolvedValueOnce(responseWithRetryAfter("2"))
+      .mockResolvedValueOnce(new Response("ok", { status: 200 }));
+
+    const promise = fetchWithRetry("https://example.com", {});
+    await vi.advanceTimersByTimeAsync(1999);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(1);
+    const response = await promise;
+
+    expect(response.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws when Retry-After exceeds maxRetryAfterSeconds", async () => {
+    const excessive = RETRY_CONFIG.maxRetryAfterSeconds + 1;
+    fetchMock.mockResolvedValue(responseWithRetryAfter(String(excessive)));
+
+    // The oversized-Retry-After branch throws before sleeping, and the
+    // resulting Error doesn't match any retryable pattern, so the loop
+    // breaks out without consuming the remaining attempts.
+    await expect(fetchWithRetry("https://example.com", {})).rejects.toThrow(
+      new RegExp(
+        `Retry-After of ${excessive}s.*exceeds the maximum of ${RETRY_CONFIG.maxRetryAfterSeconds}s`,
+      ),
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to exponential backoff when Retry-After is missing on 429", async () => {
+    fetchMock
+      .mockResolvedValueOnce(new Response(null, { status: 429 }))
+      .mockResolvedValueOnce(new Response("ok", { status: 200 }));
+
+    const promise = fetchWithRetry("https://example.com", {});
+    // calculateDelay(0) === RETRY_CONFIG.baseDelayMs
+    await vi.advanceTimersByTimeAsync(RETRY_CONFIG.baseDelayMs - 1);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(1);
+    const response = await promise;
+
+    expect(response.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("ignores Retry-After on non-429 retryable responses (e.g. 503)", async () => {
+    const longRetryAfter = String(RETRY_CONFIG.maxRetryAfterSeconds + 600);
+    fetchMock
+      .mockResolvedValueOnce(responseWithRetryAfter(longRetryAfter, 503))
+      .mockResolvedValueOnce(new Response("ok", { status: 200 }));
+
+    const promise = fetchWithRetry("https://example.com", {});
+    // Exponential backoff applies, not the header value — otherwise this
+    // would wait 10 minutes and the test would time out.
+    await vi.advanceTimersByTimeAsync(RETRY_CONFIG.baseDelayMs);
+    const response = await promise;
+
+    expect(response.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});