@copilotkit/runtime 1.55.0-next.8 → 1.55.0

package/src/v2/runtime/__tests__/router-edge-cases.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect } from "vitest";
+import { matchRoute } from "../core/fetch-router";
+
+/* ------------------------------------------------------------------------------------------------
+ * basePath = "/"
+ * --------------------------------------------------------------------------------------------- */
+
+describe("matchRoute — basePath is /", () => {
+  it("matches /info", () => {
+    const result = matchRoute("/info", "/");
+    expect(result).toEqual({ method: "info" });
+  });
+
+  it("matches /agent/:id/run", () => {
+    const result = matchRoute("/agent/myAgent/run", "/");
+    expect(result).toEqual({ method: "agent/run", agentId: "myAgent" });
+  });
+
+  it("matches /agent/:id/connect", () => {
+    const result = matchRoute("/agent/myAgent/connect", "/");
+    expect(result).toEqual({ method: "agent/connect", agentId: "myAgent" });
+  });
+
+  it("matches /agent/:id/stop/:threadId", () => {
+    const result = matchRoute("/agent/myAgent/stop/t1", "/");
+    expect(result).toEqual({
+      method: "agent/stop",
+      agentId: "myAgent",
+      threadId: "t1",
+    });
+  });
+
+  it("matches /transcribe", () => {
+    const result = matchRoute("/transcribe", "/");
+    expect(result).toEqual({ method: "transcribe" });
+  });
+
+  it("returns null for unknown path", () => {
+    const result = matchRoute("/unknown", "/");
+    expect(result).toBeNull();
+  });
+});
+
+/* ------------------------------------------------------------------------------------------------
+ * Trailing slash normalization
+ * --------------------------------------------------------------------------------------------- */
+
+describe("matchRoute — trailing slash normalization", () => {
+  it("basePath with trailing slash matches", () => {
+    const result = matchRoute("/api/copilotkit/info", "/api/copilotkit/");
+    expect(result).toEqual({ method: "info" });
+  });
+
+  it("basePath without trailing slash matches", () => {
+    const result = matchRoute("/api/copilotkit/info", "/api/copilotkit");
+    expect(result).toEqual({ method: "info" });
+  });
+});
+
+/* ------------------------------------------------------------------------------------------------
+ * URL decoding
+ * --------------------------------------------------------------------------------------------- */
+
+describe("matchRoute — URL decoding", () => {
+  it("decodes URL-encoded agentId", () => {
+    const result = matchRoute("/api/agent/my%20agent/run", "/api");
+    expect(result).toEqual({ method: "agent/run", agentId: "my agent" });
+  });
+
+  it("decodes URL-encoded threadId", () => {
+    const result = matchRoute("/api/agent/myAgent/stop/thread%2F123", "/api");
+    expect(result).toEqual({
+      method: "agent/stop",
+      agentId: "myAgent",
+      threadId: "thread/123",
+    });
+  });
+
+  it("handles agentId with special characters", () => {
+    const result = matchRoute("/api/agent/agent%40domain.com/run", "/api");
+    expect(result).toEqual({
+      method: "agent/run",
+      agentId: "agent@domain.com",
+    });
+  });
+
+  it("handles already-decoded agentId", () => {
+    const result = matchRoute("/api/agent/simple-agent/run", "/api");
+    expect(result).toEqual({ method: "agent/run", agentId: "simple-agent" });
+  });
+});
+
+/* ------------------------------------------------------------------------------------------------
+ * Suffix matching (no basePath)
+ * --------------------------------------------------------------------------------------------- */
+
+describe("matchRoute — suffix matching (no basePath)", () => {
+  it("matches info as last segment of any path", () => {
+    const result = matchRoute("/some/deeply/nested/prefix/info");
+    expect(result).toEqual({ method: "info" });
+  });
+
+  it("matches transcribe as last segment", () => {
+    const result = matchRoute("/prefix/transcribe");
+    expect(result).toEqual({ method: "transcribe" });
+  });
+
+  it("matches agent/:id/run as trailing pattern", () => {
+    const result = matchRoute("/prefix/agent/myAgent/run");
+    expect(result).toEqual({ method: "agent/run", agentId: "myAgent" });
+  });
+
+  it("matches agent/:id/connect as trailing pattern", () => {
+    const result = matchRoute("/prefix/agent/myAgent/connect");
+    expect(result).toEqual({ method: "agent/connect", agentId: "myAgent" });
+  });
+
+  it("matches agent/:id/stop/:threadId as trailing pattern", () => {
+    const result = matchRoute("/prefix/agent/myAgent/stop/t1");
+    expect(result).toEqual({
+      method: "agent/stop",
+      agentId: "myAgent",
+      threadId: "t1",
+    });
+  });
+
+  it("returns null for no matching suffix", () => {
+    const result = matchRoute("/some/random/path/here");
+    expect(result).toBeNull();
+  });
+
+  it("returns null for empty path", () => {
+    const result = matchRoute("/");
+    expect(result).toBeNull();
+  });
+});
+
+/* ------------------------------------------------------------------------------------------------
+ * basePath boundary matching
+ * --------------------------------------------------------------------------------------------- */
+
+describe("matchRoute — basePath boundary", () => {
+  it("does not match if basePath is a prefix but not at segment boundary", () => {
+    // /apicopilotkit/info should NOT match basePath /api
+    const result = matchRoute("/apicopilotkit/info", "/api");
+    expect(result).toBeNull();
+  });
+
+  it("matches when basePath is exact prefix at segment boundary", () => {
+    const result = matchRoute("/api/info", "/api");
+    expect(result).toEqual({ method: "info" });
+  });
+
+  it("basePath matches exactly with no trailing path", () => {
+    // /api with basePath /api → remainder is "/" → no match (no known route for /)
+    const result = matchRoute("/api", "/api");
+    expect(result).toBeNull();
+  });
+
+  it("returns null when path does not start with basePath", () => {
+    const result = matchRoute("/other/info", "/api");
+    expect(result).toBeNull();
+  });
+});
+
+/* ------------------------------------------------------------------------------------------------
+ * Edge cases: segments and special patterns
+ * --------------------------------------------------------------------------------------------- */
+
+describe("matchRoute — segment edge cases", () => {
+  it("handles double slashes by filtering empty segments", () => {
+    // /api//info → segments: ["api", "info"] after filter(Boolean)
+    const result = matchRoute("/api//info", "/api");
+    expect(result).toEqual({ method: "info" });
+  });
+
+  it("handles path with only basePath + slash", () => {
+    const result = matchRoute("/api/", "/api");
+    expect(result).toBeNull();
+  });
+
+  it("matches with deep basePath", () => {
+    const result = matchRoute("/v1/api/copilotkit/info", "/v1/api/copilotkit");
+    expect(result).toEqual({ method: "info" });
+  });
+
+  it("matches agent route with deep basePath", () => {
+    const result = matchRoute(
+      "/v1/api/copilotkit/agent/default/run",
+      "/v1/api/copilotkit",
+    );
+    expect(result).toEqual({ method: "agent/run", agentId: "default" });
+  });
+
+  it("agentId with hyphens, underscores, and dots", () => {
+    const result = matchRoute("/api/agent/my-agent_v2.0/run", "/api");
+    expect(result).toEqual({
+      method: "agent/run",
+      agentId: "my-agent_v2.0",
+    });
+  });
+
+  it("single segment path without basePath matches info", () => {
+    const result = matchRoute("/info");
+    expect(result).toEqual({ method: "info" });
+  });
+
+  it("case-sensitive matching (INFO does not match info)", () => {
+    const result = matchRoute("/api/INFO", "/api");
+    expect(result).toBeNull();
+  });
+
+  it("case-sensitive matching (Agent vs agent)", () => {
+    const result = matchRoute("/api/Agent/default/run", "/api");
+    expect(result).toBeNull();
+  });
+});

package/src/v2/runtime/__tests__/routing-express.test.ts

@@ -5,7 +5,7 @@ import type { AbstractAgent } from "@ag-ui/client";
 import { Observable, of } from "rxjs";
 
 import { createCopilotEndpointExpress } from "../express";
-import { CopilotRuntime } from "../runtime";
+import { CopilotRuntime } from "../core/runtime";
 
 vi.mock("../handlers/handle-run", () => ({
   handleRunAgent: vi

package/src/v2/runtime/__tests__/routing-single-express.test.ts

@@ -5,7 +5,7 @@ import type { AbstractAgent } from "@ag-ui/client";
 import { Observable, of } from "rxjs";
 
 import { createCopilotEndpointSingleRouteExpress } from "../express";
-import { CopilotRuntime } from "../runtime";
+import { CopilotRuntime } from "../core/runtime";
 
 vi.mock("../handlers/handle-run", () => ({
   handleRunAgent: vi

package/src/v2/runtime/__tests__/routing-single.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from "vitest";
 import type { AbstractAgent } from "@ag-ui/client";
 
 import { createCopilotEndpointSingleRoute } from "../endpoints";
-import { CopilotRuntime } from "../runtime";
+import { CopilotRuntime } from "../core/runtime";
 
 describe("CopilotEndpointSingleRoute routing", () => {
   const createMockRuntime = () => {

package/src/v2/runtime/__tests__/routing.test.ts

@@ -1,5 +1,5 @@
 import { createCopilotEndpoint } from "../endpoints";
-import { CopilotRuntime } from "../runtime";
+import { CopilotRuntime } from "../core/runtime";
 import { describe, it, expect } from "vitest";
 import type { AbstractAgent } from "@ag-ui/client";
 

package/src/v2/runtime/__tests__/runtime.test.ts

@@ -4,7 +4,7 @@ import {
   CopilotIntelligenceRuntime,
   CopilotRuntime,
   CopilotSseRuntime,
-} from "../runtime";
+} from "../core/runtime";
 import type { CopilotKitIntelligence } from "../intelligence-platform";
 import { InMemoryAgentRunner } from "../runner/in-memory";
 import { IntelligenceAgentRunner } from "../runner/intelligence";
@@ -120,4 +120,113 @@ describe("runtime construction", () => {
         .identifyUser,
     ).toBeUndefined();
   });
+
+  it("defaults lockTtlSeconds to 20 and lockHeartbeatIntervalSeconds to 15", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotIntelligenceRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+    });
+
+    expect(runtime.lockTtlSeconds).toBe(20);
+    expect(runtime.lockHeartbeatIntervalSeconds).toBe(15);
+  });
+
+  it("clamps lockTtlSeconds to a maximum of 3600 (1 hour)", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotIntelligenceRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+      lockTtlSeconds: 7200,
+    });
+
+    expect(runtime.lockTtlSeconds).toBe(3600);
+  });
+
+  it("clamps lockHeartbeatIntervalSeconds to a maximum of 3000 (50 minutes)", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotIntelligenceRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+      lockHeartbeatIntervalSeconds: 5000,
+    });
+
+    expect(runtime.lockHeartbeatIntervalSeconds).toBe(3000);
+  });
+
+  it("uses provided values when they are within allowed range", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotIntelligenceRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+      lockTtlSeconds: 30,
+    });
+
+    expect(runtime.lockTtlSeconds).toBe(30);
+    expect(runtime.lockHeartbeatIntervalSeconds).toBe(15);
+  });
+
+  it("stores lock config on CopilotIntelligenceRuntime", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotIntelligenceRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+      lockTtlSeconds: 30,
+      lockKeyPrefix: "custom",
+      lockHeartbeatIntervalSeconds: 10,
+    });
+
+    expect(runtime.lockTtlSeconds).toBe(30);
+    expect(runtime.lockKeyPrefix).toBe("custom");
+    expect(runtime.lockHeartbeatIntervalSeconds).toBe(10);
+  });
+
+  it("forwards lock config through the CopilotRuntime intelligence shim", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+      lockTtlSeconds: 60,
+      lockKeyPrefix: "agent",
+      lockHeartbeatIntervalSeconds: 20,
+    });
+
+    expect(
+      (runtime as CopilotRuntime & { lockTtlSeconds?: number }).lockTtlSeconds,
+    ).toBe(60);
+    expect(
+      (runtime as CopilotRuntime & { lockKeyPrefix?: string }).lockKeyPrefix,
+    ).toBe("agent");
+    expect(
+      (runtime as CopilotRuntime & { lockHeartbeatIntervalSeconds?: number })
+        .lockHeartbeatIntervalSeconds,
+    ).toBe(20);
+  });
+
+  it("exposes lock config as undefined for SSE runtimes", () => {
+    const runtime = new CopilotRuntime({ agents });
+
+    expect(
+      (runtime as CopilotRuntime & { lockTtlSeconds?: number }).lockTtlSeconds,
+    ).toBeUndefined();
+    expect(
+      (runtime as CopilotRuntime & { lockKeyPrefix?: string }).lockKeyPrefix,
+    ).toBeUndefined();
+    expect(
+      (runtime as CopilotRuntime & { lockHeartbeatIntervalSeconds?: number })
+        .lockHeartbeatIntervalSeconds,
+    ).toBeUndefined();
+  });
 });

package/src/v2/runtime/__tests__/telemetry.test.ts

@@ -2,15 +2,27 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { TelemetryClient } from "../telemetry/telemetry-client";
 import scarfClient from "../telemetry/scarf-client";
 
+const { segmentTrackMock } = vi.hoisted(() => ({
+  segmentTrackMock: vi.fn(),
+}));
+
+vi.mock("@segment/analytics-node", () => ({
+  Analytics: vi.fn().mockImplementation(() => ({
+    track: segmentTrackMock,
+  })),
+}));
+
 describe("TelemetryClient", () => {
   let scarfSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
     scarfSpy = vi.spyOn(scarfClient, "logEvent").mockResolvedValue(undefined);
+    segmentTrackMock.mockClear();
   });
 
   afterEach(() => {
-    vi.restoreAllMocks();
+    scarfSpy.mockRestore();
+    segmentTrackMock.mockClear();
   });
 
   it("sends event to scarf when sampled in", async () => {
@@ -32,6 +44,33 @@ describe("TelemetryClient", () => {
     });
   });
 
+  it("sends event with properties to segment when sampled in", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const client = new TelemetryClient({
+      telemetryDisabled: false,
+      sampleRate: 1,
+    });
+
+    await client.capture("oss.runtime.instance_created", {
+      actionsAmount: 5,
+      endpointTypes: ["rest"],
+      endpointsAmount: 2,
+      "cloud.api_key_provided": true,
+      "cloud.public_api_key": "pk_test_123",
+    });
+
+    expect(segmentTrackMock).toHaveBeenCalledTimes(1);
+    const call = segmentTrackMock.mock.calls[0][0];
+    expect(call.event).toBe("oss.runtime.instance_created");
+    expect(call.anonymousId).toMatch(/^anon_/);
+    expect(call.properties).toMatchObject({
+      actionsAmount: 5,
+      endpointsAmount: 2,
+      "cloud.api_key_provided": true,
+      "cloud.public_api_key": "pk_test_123",
+    });
+  });
+
   it("only sends event name to scarf, not properties", async () => {
     const client = new TelemetryClient({
       telemetryDisabled: false,
@@ -67,6 +106,7 @@ describe("TelemetryClient", () => {
     });
 
     expect(scarfSpy).not.toHaveBeenCalled();
+    expect(segmentTrackMock).not.toHaveBeenCalled();
   });
 
   it("does not send events when sampled out", async () => {
@@ -84,6 +124,7 @@ describe("TelemetryClient", () => {
     });
 
     expect(scarfSpy).not.toHaveBeenCalled();
+    expect(segmentTrackMock).not.toHaveBeenCalled();
   });
 
   it("respects sample rate boundary", async () => {
@@ -98,6 +139,26 @@ describe("TelemetryClient", () => {
     expect(scarfSpy).toHaveBeenCalled();
   });
 
+  it("includes global properties in segment track call", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const client = new TelemetryClient({
+      telemetryDisabled: false,
+      sampleRate: 1,
+    });
+
+    client.setGlobalProperties({ "copilotkit.package.name": "test-pkg" });
+
+    await client.capture("oss.runtime.instance_created", {
+      actionsAmount: 1,
+      endpointTypes: [],
+      endpointsAmount: 0,
+      "cloud.api_key_provided": false,
+    });
+
+    const call = segmentTrackMock.mock.calls[0][0];
+    expect(call.properties["copilotkit.package.name"]).toBe("test-pkg");
+  });
+
   it("throws when sample rate is out of range", () => {
     expect(() => new TelemetryClient({ sampleRate: 1.5 })).toThrow(
       "Sample rate must be between 0 and 1",

package/src/v2/runtime/core/fetch-cors.ts

@@ -0,0 +1,136 @@
+/**
+ * Built-in CORS utility for framework-agnostic CopilotKit runtime handler.
+ *
+ * This is a lightweight CORS implementation for web-standard
+ * Request/Response. It's optional — if your framework already handles CORS,
+ * pass `cors: false` or omit it.
+ */
+
+export interface CopilotCorsConfig {
+  origin?: string | string[] | ((origin: string) => string | null);
+  credentials?: boolean;
+  allowMethods?: string[];
+  allowHeaders?: string[];
+  exposeHeaders?: string[];
+  maxAge?: number;
+}
+
+const DEFAULT_METHODS = [
+  "GET",
+  "HEAD",
+  "PUT",
+  "POST",
+  "DELETE",
+  "PATCH",
+  "OPTIONS",
+];
+const DEFAULT_HEADERS = ["*"];
+
+function resolveOrigin(
+  config: CopilotCorsConfig,
+  requestOrigin: string | null,
+): string | null {
+  const { origin } = config;
+  if (!origin) return "*";
+
+  if (typeof origin === "string") return origin;
+
+  if (Array.isArray(origin)) {
+    if (!requestOrigin) return null;
+    return origin.includes(requestOrigin) ? requestOrigin : null;
+  }
+
+  if (typeof origin === "function") {
+    return requestOrigin ? origin(requestOrigin) : null;
+  }
+
+  return "*";
+}
+
+function setCorsHeaders(
+  headers: Headers,
+  config: CopilotCorsConfig,
+  requestOrigin: string | null,
+): void {
+  let allowedOrigin = resolveOrigin(config, requestOrigin);
+  if (!allowedOrigin) return;
+
+  // Per the Fetch spec, Access-Control-Allow-Origin: * combined with
+  // Access-Control-Allow-Credentials: true causes browsers to reject the
+  // response. Auto-resolve wildcard to the request origin when credentials
+  // are enabled; if there is no request origin, skip CORS entirely.
+  if (config.credentials && allowedOrigin === "*") {
+    if (requestOrigin) {
+      allowedOrigin = requestOrigin;
+    } else {
+      return;
+    }
+  }
+
+  headers.set("Access-Control-Allow-Origin", allowedOrigin);
+
+  if (config.credentials) {
+    headers.set("Access-Control-Allow-Credentials", "true");
+  }
+
+  if (config.exposeHeaders?.length) {
+    headers.set(
+      "Access-Control-Expose-Headers",
+      config.exposeHeaders.join(", "),
+    );
+  }
+
+  // Vary on Origin when it's not a fixed wildcard
+  if (allowedOrigin !== "*") {
+    headers.append("Vary", "Origin");
+  }
+}
+
+/**
+ * Handle CORS preflight (OPTIONS) requests.
+ * Returns a 204 Response if it's a preflight, or null if not.
+ */
+export function handleCors(
+  request: Request,
+  config: CopilotCorsConfig,
+): Response | null {
+  if (request.method !== "OPTIONS") return null;
+
+  const requestOrigin = request.headers.get("origin");
+  const headers = new Headers();
+
+  setCorsHeaders(headers, config, requestOrigin);
+
+  const methods = config.allowMethods ?? DEFAULT_METHODS;
+  headers.set("Access-Control-Allow-Methods", methods.join(", "));
+
+  const allowHeaders = config.allowHeaders ?? DEFAULT_HEADERS;
+  headers.set("Access-Control-Allow-Headers", allowHeaders.join(", "));
+
+  if (config.maxAge != null) {
+    headers.set("Access-Control-Max-Age", String(config.maxAge));
+  }
+
+  // Vary headers for correct CDN caching of preflight responses
+  headers.append("Vary", "Access-Control-Request-Headers");
+  headers.append("Vary", "Access-Control-Request-Method");
+
+  return new Response(null, { status: 204, headers });
+}
+
+/**
+ * Add CORS headers to an existing response.
+ */
+export function addCorsHeaders(
+  response: Response,
+  config: CopilotCorsConfig,
+  requestOrigin: string | null,
+): Response {
+  const headers = new Headers(response.headers);
+  setCorsHeaders(headers, config, requestOrigin);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}