@copilotkit/runtime 1.54.1 → 1.55.0-next.8

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

@@ -0,0 +1,123 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  CopilotIntelligenceRuntime,
+  CopilotRuntime,
+  CopilotSseRuntime,
+} from "../runtime";
+import type { CopilotKitIntelligence } from "../intelligence-platform";
+import { InMemoryAgentRunner } from "../runner/in-memory";
+import { IntelligenceAgentRunner } from "../runner/intelligence";
+
+describe("runtime construction", () => {
+  const agents = {};
+  const identifyUser = vi.fn().mockResolvedValue({ id: "user-1" });
+  const createMockIntelligence = (): CopilotKitIntelligence =>
+    ({
+      ɵgetRunnerWsUrl: vi.fn().mockReturnValue("ws://runner.example"),
+      ɵgetRunnerAuthToken: vi.fn().mockReturnValue("token-123"),
+      ɵgetClientWsUrl: vi.fn().mockReturnValue("ws://client.example"),
+    }) as unknown as CopilotKitIntelligence;
+
+  it("builds an SSE runtime by default", () => {
+    const runtime = new CopilotSseRuntime({ agents });
+
+    expect(runtime.mode).toBe("sse");
+
+    expect(runtime.runner).toBeInstanceOf(InMemoryAgentRunner);
+    expect(runtime.intelligence).toBeUndefined();
+  });
+
+  it("builds an Intelligence runtime with an Intelligence runner", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotIntelligenceRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+    });
+
+    expect(runtime.mode).toBe("intelligence");
+
+    expect(runtime.intelligence).toBe(sdk);
+    expect(runtime.runner).toBeInstanceOf(IntelligenceAgentRunner);
+    expect(runtime.generateThreadNames).toBe(true);
+    expect(runtime.identifyUser).toBe(identifyUser);
+    expect(sdk.ɵgetRunnerWsUrl).toHaveBeenCalledTimes(1);
+    expect(sdk.ɵgetRunnerAuthToken).toHaveBeenCalledTimes(1);
+  });
+
+  it("preserves an explicit generateThreadNames=false option in Intelligence mode", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotIntelligenceRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+      generateThreadNames: false,
+    });
+
+    expect(runtime.generateThreadNames).toBe(false);
+  });
+
+  it("keeps CopilotRuntime as an SSE shim when no CopilotKitIntelligence is provided", () => {
+    const runtime = new CopilotRuntime({ agents });
+
+    expect(runtime.mode).toBe("sse");
+
+    expect(runtime.runner).toBeInstanceOf(InMemoryAgentRunner);
+    expect(runtime.intelligence).toBeUndefined();
+  });
+
+  it("keeps CopilotRuntime as an Intelligence shim when CopilotKitIntelligence is provided", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+    });
+
+    expect(runtime.mode).toBe("intelligence");
+
+    expect(runtime.intelligence).toBe(sdk);
+    expect(runtime.runner).toBeInstanceOf(IntelligenceAgentRunner);
+    expect(
+      (runtime as CopilotRuntime & { generateThreadNames?: boolean })
+        .generateThreadNames,
+    ).toBe(true);
+    expect(
+      (
+        runtime as CopilotRuntime & {
+          identifyUser?: typeof identifyUser;
+        }
+      ).identifyUser,
+    ).toBe(identifyUser);
+  });
+
+  it("forwards generateThreadNames=false through the CopilotRuntime intelligence shim", () => {
+    const sdk = createMockIntelligence();
+
+    const runtime = new CopilotRuntime({
+      agents,
+      intelligence: sdk,
+      identifyUser,
+      generateThreadNames: false,
+    });
+
+    expect(runtime.mode).toBe("intelligence");
+    expect(
+      (runtime as CopilotRuntime & { generateThreadNames?: boolean })
+        .generateThreadNames,
+    ).toBe(false);
+  });
+
+  it("exposes identifyUser as undefined for SSE runtimes", () => {
+    const runtime = new CopilotRuntime({ agents });
+
+    expect(
+      (runtime as CopilotRuntime & { identifyUser?: typeof identifyUser })
+        .identifyUser,
+    ).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,167 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { TelemetryClient } from "../telemetry/telemetry-client";
+import scarfClient from "../telemetry/scarf-client";
+
+describe("TelemetryClient", () => {
+  let scarfSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    scarfSpy = vi.spyOn(scarfClient, "logEvent").mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("sends event to scarf 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: 0,
+      endpointTypes: [],
+      endpointsAmount: 0,
+      "cloud.api_key_provided": false,
+    });
+
+    expect(scarfSpy).toHaveBeenCalledWith({
+      event: "oss.runtime.instance_created",
+    });
+  });
+
+  it("only sends event name to scarf, not properties", async () => {
+    const client = new TelemetryClient({
+      telemetryDisabled: false,
+      sampleRate: 1,
+    });
+
+    await client.capture("oss.runtime.copilot_request_created", {
+      "cloud.guardrails.enabled": true,
+      requestType: "run",
+      "cloud.api_key_provided": true,
+      "cloud.public_api_key": "pk_test_123",
+    });
+
+    expect(scarfSpy).toHaveBeenCalledWith({
+      event: "oss.runtime.copilot_request_created",
+    });
+    // Properties should NOT be forwarded to scarf
+    const callArg = scarfSpy.mock.calls[0][0];
+    expect(Object.keys(callArg)).toEqual(["event"]);
+  });
+
+  it("does not send events when telemetryDisabled is true", async () => {
+    const client = new TelemetryClient({
+      telemetryDisabled: true,
+      sampleRate: 1,
+    });
+
+    await client.capture("oss.runtime.instance_created", {
+      actionsAmount: 0,
+      endpointTypes: [],
+      endpointsAmount: 0,
+      "cloud.api_key_provided": false,
+    });
+
+    expect(scarfSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not send events when sampled out", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0.99);
+    const client = new TelemetryClient({
+      telemetryDisabled: false,
+      sampleRate: 0.05,
+    });
+
+    await client.capture("oss.runtime.instance_created", {
+      actionsAmount: 0,
+      endpointTypes: [],
+      endpointsAmount: 0,
+      "cloud.api_key_provided": false,
+    });
+
+    expect(scarfSpy).not.toHaveBeenCalled();
+  });
+
+  it("respects sample rate boundary", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0.04);
+    const client = new TelemetryClient({
+      telemetryDisabled: false,
+      sampleRate: 0.05,
+    });
+
+    await client.capture("oss.runtime.agent_execution_stream_started", {});
+
+    expect(scarfSpy).toHaveBeenCalled();
+  });
+
+  it("throws when sample rate is out of range", () => {
+    expect(() => new TelemetryClient({ sampleRate: 1.5 })).toThrow(
+      "Sample rate must be between 0 and 1",
+    );
+    expect(() => new TelemetryClient({ sampleRate: -0.1 })).toThrow(
+      "Sample rate must be between 0 and 1",
+    );
+  });
+});
+
+describe("ScarfClient", () => {
+  let originalFetch: typeof fetch;
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+    fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 200 }));
+    global.fetch = fetchMock as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("sends GET request to scarf gateway with event as query param", async () => {
+    await scarfClient.logEvent({ event: "oss.runtime.instance_created" });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, options] = fetchMock.mock.calls[0];
+    expect(url).toContain("https://copilotkit.gateway.scarf.sh/");
+    expect(url).toContain("event=oss.runtime.instance_created");
+    expect(options.method).toBe("GET");
+  });
+
+  it("silently fails on network error", async () => {
+    fetchMock.mockRejectedValue(new Error("Network error"));
+
+    // Should not throw
+    await expect(
+      scarfClient.logEvent({ event: "oss.runtime.instance_created" }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("silently fails on non-ok response", async () => {
+    fetchMock.mockResolvedValue(new Response("", { status: 500 }));
+
+    // Should not throw
+    await expect(
+      scarfClient.logEvent({ event: "oss.runtime.instance_created" }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("skips null and undefined values in query params", async () => {
+    await scarfClient.logEvent({
+      event: "oss.runtime.instance_created",
+      nullVal: null,
+      undefinedVal: undefined,
+      validVal: "test",
+    });
+
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toContain("event=oss.runtime.instance_created");
+    expect(url).toContain("validVal=test");
+    expect(url).not.toContain("nullVal");
+    expect(url).not.toContain("undefinedVal");
+  });
+});

package/src/v2/runtime/__tests__/thread-names.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest";
+import type { Message } from "@ag-ui/client";
+
+import {
+  ɵnormalizeGeneratedTitle as normalizeGeneratedTitle,
+  ɵbuildThreadTitlePrompt as buildThreadTitlePrompt,
+  ɵhasThreadName as hasThreadName,
+} from "../handlers/intelligence/thread-names";
+
+// ---------------------------------------------------------------------------
+// normalizeGeneratedTitle
+// ---------------------------------------------------------------------------
+
+describe("normalizeGeneratedTitle", () => {
+  it("extracts title from valid JSON response", () => {
+    expect(normalizeGeneratedTitle('{"title":"Budget Review"}')).toBe(
+      "Budget Review",
+    );
+  });
+
+  it("extracts title from JSON wrapped in code fences", () => {
+    expect(
+      normalizeGeneratedTitle('```json\n{"title":"Budget Review"}\n```'),
+    ).toBe("Budget Review");
+  });
+
+  it("strips surrounding quotes from plain text", () => {
+    expect(normalizeGeneratedTitle('"Budget Review"')).toBe("Budget Review");
+    expect(normalizeGeneratedTitle("'Budget Review'")).toBe("Budget Review");
+    expect(normalizeGeneratedTitle("`Budget Review`")).toBe("Budget Review");
+  });
+
+  it("strips markdown characters", () => {
+    expect(normalizeGeneratedTitle("**Budget** _Review_")).toBe(
+      "Budget Review",
+    );
+    expect(normalizeGeneratedTitle("# Budget Review")).toBe("Budget Review");
+    expect(normalizeGeneratedTitle("[Budget](Review)")).toBe("BudgetReview");
+  });
+
+  it("strips trailing punctuation", () => {
+    expect(normalizeGeneratedTitle("Budget Review.")).toBe("Budget Review");
+    expect(normalizeGeneratedTitle("Budget Review!")).toBe("Budget Review");
+    expect(normalizeGeneratedTitle("Budget Review?")).toBe("Budget Review");
+    expect(normalizeGeneratedTitle("Budget Review;")).toBe("Budget Review");
+  });
+
+  it("collapses whitespace", () => {
+    expect(normalizeGeneratedTitle("Budget   Review")).toBe("Budget Review");
+    expect(normalizeGeneratedTitle("  Budget  Review  ")).toBe("Budget Review");
+  });
+
+  it("returns null for empty or whitespace-only input", () => {
+    expect(normalizeGeneratedTitle("")).toBeNull();
+    expect(normalizeGeneratedTitle("   ")).toBeNull();
+  });
+
+  it("returns null when all content is stripped", () => {
+    expect(normalizeGeneratedTitle("***")).toBeNull();
+    expect(normalizeGeneratedTitle("[]()")).toBeNull();
+  });
+
+  it("truncates titles longer than 80 characters", () => {
+    const long = "A".repeat(100);
+    const result = normalizeGeneratedTitle(long);
+    expect(result).not.toBeNull();
+    expect(result!.length).toBeLessThanOrEqual(80);
+  });
+
+  it("returns null when title has more than 8 words", () => {
+    expect(
+      normalizeGeneratedTitle("one two three four five six seven eight nine"),
+    ).toBeNull();
+  });
+
+  it("accepts title with exactly 8 words", () => {
+    expect(
+      normalizeGeneratedTitle("one two three four five six seven eight"),
+    ).toBe("one two three four five six seven eight");
+  });
+
+  it("handles JSON with non-string title gracefully", () => {
+    // Falls back to raw text path
+    expect(normalizeGeneratedTitle('{"title":42}')).toBe('{"title":42}');
+  });
+
+  it("handles malformed JSON gracefully", () => {
+    expect(normalizeGeneratedTitle("{not json}")).toBe("{not json}");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildThreadTitlePrompt
+// ---------------------------------------------------------------------------
+
+describe("buildThreadTitlePrompt", () => {
+  const msg = (role: string, content: string): Message =>
+    ({ id: `msg-${role}`, role, content }) as Message;
+
+  it("returns null for empty messages", () => {
+    expect(buildThreadTitlePrompt([])).toBeNull();
+    expect(
+      buildThreadTitlePrompt(undefined as unknown as Message[]),
+    ).toBeNull();
+  });
+
+  it("builds a prompt from user and assistant messages", () => {
+    const messages = [
+      msg("user", "What is the weather?"),
+      msg("assistant", "It is sunny today."),
+    ];
+
+    const result = buildThreadTitlePrompt(messages);
+    expect(result).toContain("Generate a short title");
+    expect(result).toContain("user: What is the weather?");
+    expect(result).toContain("assistant: It is sunny today.");
+  });
+
+  it("filters out tool role messages", () => {
+    const messages = [
+      msg("user", "Search for cats"),
+      msg("tool", '{"results": []}'),
+      msg("assistant", "Found some cats."),
+    ];
+
+    const result = buildThreadTitlePrompt(messages);
+    expect(result).not.toContain("tool:");
+    expect(result).toContain("user: Search for cats");
+    expect(result).toContain("assistant: Found some cats.");
+  });
+
+  it("includes system and developer messages", () => {
+    const messages = [
+      msg("system", "You are helpful."),
+      msg("developer", "Be concise."),
+      msg("user", "Hello"),
+    ];
+
+    const result = buildThreadTitlePrompt(messages);
+    expect(result).toContain("system: You are helpful.");
+    expect(result).toContain("developer: Be concise.");
+  });
+
+  it("takes only the last 8 messages", () => {
+    const messages = Array.from({ length: 12 }, (_, i) =>
+      msg("user", `Message ${i}`),
+    );
+
+    const result = buildThreadTitlePrompt(messages)!;
+    // Should contain messages 4-11 (last 8) but not 0-3
+    expect(result).not.toContain("Message 3");
+    expect(result).toContain("Message 4");
+    expect(result).toContain("Message 11");
+  });
+
+  it("skips messages with empty content", () => {
+    const messages = [msg("user", ""), msg("assistant", "Hello")];
+
+    const result = buildThreadTitlePrompt(messages);
+    expect(result).not.toContain("user:");
+    expect(result).toContain("assistant: Hello");
+  });
+
+  it("returns null when all messages have empty content", () => {
+    const messages = [msg("user", ""), msg("assistant", "")];
+    expect(buildThreadTitlePrompt(messages)).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// hasThreadName
+// ---------------------------------------------------------------------------
+
+describe("hasThreadName", () => {
+  it("returns true for non-empty strings", () => {
+    expect(hasThreadName("Budget Review")).toBe(true);
+  });
+
+  it("returns false for null and undefined", () => {
+    expect(hasThreadName(null)).toBe(false);
+    expect(hasThreadName(undefined)).toBe(false);
+  });
+
+  it("returns false for empty or whitespace-only strings", () => {
+    expect(hasThreadName("")).toBe(false);
+    expect(hasThreadName("   ")).toBe(false);
+  });
+});

package/src/v2/runtime/endpoints/express-single.ts

@@ -0,0 +1,231 @@
+import express from "express";
+import type {
+  Request as ExpressRequest,
+  Response as ExpressResponse,
+  NextFunction,
+  Router,
+} from "express";
+import cors from "cors";
+
+import { CopilotRuntimeLike } from "../runtime";
+import { handleRunAgent } from "../handlers/handle-run";
+import { handleConnectAgent } from "../handlers/handle-connect";
+import { handleStopAgent } from "../handlers/handle-stop";
+import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
+import { handleTranscribe } from "../handlers/handle-transcribe";
+import { logger } from "@copilotkit/shared";
+import {
+  callBeforeRequestMiddleware,
+  callAfterRequestMiddleware,
+} from "../middleware";
+import {
+  createFetchRequestFromExpress,
+  sendFetchResponse,
+} from "./express-utils";
+import {
+  createJsonRequest,
+  expectString,
+  MethodCall,
+  parseMethodCall,
+} from "./single-route-helpers";
+
+interface CopilotSingleRouteExpressParams {
+  runtime: CopilotRuntimeLike;
+  basePath: string;
+}
+
+export function createCopilotEndpointSingleRouteExpress({
+  runtime,
+  basePath,
+}: CopilotSingleRouteExpressParams): Router {
+  const router = express.Router();
+  const routePath = normalizeSingleRoutePath(basePath);
+
+  router.use(
+    cors({
+      origin: "*",
+      methods: ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH", "OPTIONS"],
+      allowedHeaders: ["*"],
+    }),
+  );
+
+  router.post(routePath, createSingleRouteHandler(runtime));
+
+  router.use((req, res) => {
+    res.status(404).json({ error: "Not found" });
+  });
+
+  return router;
+}
+
+function createSingleRouteHandler(runtime: CopilotRuntimeLike) {
+  return async (
+    req: ExpressRequest,
+    res: ExpressResponse,
+    next: NextFunction,
+  ) => {
+    const path = req.originalUrl ?? req.path;
+    let request = createFetchRequestFromExpress(req);
+
+    try {
+      const maybeModifiedRequest = await callBeforeRequestMiddleware({
+        runtime,
+        request,
+        path,
+      });
+      if (maybeModifiedRequest) {
+        request = maybeModifiedRequest;
+      }
+    } catch (error) {
+      logger.error(
+        { err: error, url: request.url, path },
+        "Error running before request middleware",
+      );
+      if (error instanceof Response) {
+        try {
+          await sendFetchResponse(res, error);
+        } catch (streamError) {
+          next(streamError);
+        }
+        return;
+      }
+      next(error);
+      return;
+    }
+
+    let methodCall: MethodCall;
+    try {
+      methodCall = await parseMethodCall(request);
+    } catch (error) {
+      if (error instanceof Response) {
+        logger.warn({ url: request.url }, "Invalid single-route payload");
+        try {
+          await sendFetchResponse(res, error);
+        } catch (streamError) {
+          next(streamError);
+        }
+        return;
+      }
+      logger.warn(
+        { err: error, url: request.url },
+        "Invalid single-route payload",
+      );
+      res.status(400).json({
+        error: "invalid_request",
+        message:
+          error instanceof Error ? error.message : "Invalid request payload",
+      });
+      return;
+    }
+
+    try {
+      let response: Response;
+      switch (methodCall.method) {
+        case "agent/run": {
+          const agentId = expectString(methodCall.params, "agentId");
+          const handlerRequest = createJsonRequest(request, methodCall.body);
+          response = await handleRunAgent({
+            runtime,
+            request: handlerRequest,
+            agentId,
+          });
+          break;
+        }
+        case "agent/connect": {
+          const agentId = expectString(methodCall.params, "agentId");
+          const handlerRequest = createJsonRequest(request, methodCall.body);
+          response = await handleConnectAgent({
+            runtime,
+            request: handlerRequest,
+            agentId,
+          });
+          break;
+        }
+        case "agent/stop": {
+          const agentId = expectString(methodCall.params, "agentId");
+          const threadId = expectString(methodCall.params, "threadId");
+          response = await handleStopAgent({
+            runtime,
+            request,
+            agentId,
+            threadId,
+          });
+          break;
+        }
+        case "info": {
+          response = await handleGetRuntimeInfo({ runtime, request });
+          break;
+        }
+        case "transcribe": {
+          const handlerRequest = createJsonRequest(request, methodCall.body);
+          response = await handleTranscribe({
+            runtime,
+            request: handlerRequest,
+          });
+          break;
+        }
+        default: {
+          const exhaustive: never = methodCall.method;
+          return exhaustive;
+        }
+      }
+
+      const responseForMiddleware = response.clone();
+      await sendFetchResponse(res, response);
+      callAfterRequestMiddleware({
+        runtime,
+        response: responseForMiddleware,
+        path,
+      }).catch((error) => {
+        logger.error(
+          { err: error, url: req.originalUrl ?? req.url, path },
+          "Error running after request middleware",
+        );
+      });
+    } catch (error) {
+      if (error instanceof Response) {
+        const errorResponseForMiddleware = error.clone();
+        try {
+          await sendFetchResponse(res, error);
+        } catch (streamError) {
+          next(streamError);
+          return;
+        }
+        callAfterRequestMiddleware({
+          runtime,
+          response: errorResponseForMiddleware,
+          path,
+        }).catch((mwError) => {
+          logger.error(
+            { err: mwError, url: req.originalUrl ?? req.url, path },
+            "Error running after request middleware",
+          );
+        });
+        return;
+      }
+      logger.error(
+        { err: error, url: request.url, path },
+        "Error running single-route handler",
+      );
+      next(error);
+    }
+  };
+}
+
+function normalizeSingleRoutePath(path: string): string {
+  if (!path) {
+    throw new Error(
+      "basePath must be provided for Express single-route endpoint",
+    );
+  }
+
+  if (!path.startsWith("/")) {
+    return `/${path}`;
+  }
+
+  if (path.length > 1 && path.endsWith("/")) {
+    return path.slice(0, -1);
+  }
+
+  return path;
+}