@copilotkit/shared 1.69.3 → 1.70.0

package/src/telemetry/lambda-client.test.ts

@@ -1,5 +1,167 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-import { send } from "./lambda-client";
+import { parseTelemetryIdFromLicense, send } from "./lambda-client";
+
+const EXPECTED_TELEMETRY_SINK_URL =
+  process.env.COPILOTKIT_TELEMETRY_URL ??
+  "https://telemetry.copilotkit.ai/ingest";
+const TELEMETRY_ID_HEADER = "x-copilotkit-telemetry-id";
+const LEGACY_IDENTITY_PAYLOAD = Buffer.from(
+  JSON.stringify({ telemetry_id: "legacy-telemetry-id" }),
+).toString("base64url");
+const INVALID_BASE64URL_PAYLOADS = [
+  {
+    label: "a dollar sign",
+    payload: `${LEGACY_IDENTITY_PAYLOAD}$`,
+  },
+  {
+    label: "a space",
+    payload: `${LEGACY_IDENTITY_PAYLOAD} `,
+  },
+  {
+    label: "a line break",
+    payload: `${LEGACY_IDENTITY_PAYLOAD}\n`,
+  },
+  {
+    label: "an impossible length",
+    payload: `${Buffer.from(JSON.stringify({ telemetry_id: "xx" })).toString(
+      "base64url",
+    )}A`,
+  },
+] as const;
+
+test("normalizes surrounding HTTP whitespace in a legacy license identity", () => {
+  const telemetryId = "\t legacy-telemetry-id \t";
+  const payload = Buffer.from(
+    JSON.stringify({ telemetry_id: telemetryId }),
+  ).toString("base64url");
+
+  expect(parseTelemetryIdFromLicense(`header.${payload}.sig`)).toBe(
+    "legacy-telemetry-id",
+  );
+});
+
+test("rejects an ingest-invalid UTF-8 legacy identity in the browser fallback", () => {
+  const payload = Buffer.from(
+    JSON.stringify({ telemetry_id: "tenant-é" }),
+  ).toString("base64url");
+  vi.stubGlobal("Buffer", undefined);
+
+  try {
+    expect(parseTelemetryIdFromLicense(`header.${payload}.sig`)).toBeNull();
+  } finally {
+    vi.unstubAllGlobals();
+  }
+});
+
+test.each(INVALID_BASE64URL_PAYLOADS)(
+  "rejects a legacy payload with $label in Node and the browser fallback",
+  ({ payload }) => {
+    const token = `header.${payload}.sig`;
+
+    expect(parseTelemetryIdFromLicense(token)).toBeNull();
+
+    vi.stubGlobal("Buffer", undefined);
+    try {
+      expect(parseTelemetryIdFromLicense(token)).toBeNull();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  },
+);
+
+/**
+ * Captures the telemetry request without replacing fetch with an untyped mock.
+ */
+function setupCapturedRequest() {
+  let capturedRequest:
+    | {
+        bodyText: string;
+        headers: Record<string, string>;
+        rawTelemetryIdHeader: string | undefined;
+        url: string;
+      }
+    | undefined;
+  const fetchMock = vi
+    .spyOn(globalThis, "fetch")
+    .mockImplementation((input, init) => {
+      if (typeof init?.body !== "string") {
+        throw new Error("Expected telemetry request body to be a string");
+      }
+      if (
+        init.headers === undefined ||
+        init.headers instanceof Headers ||
+        Array.isArray(init.headers)
+      ) {
+        throw new Error("Expected telemetry request headers to be a record");
+      }
+
+      capturedRequest = {
+        bodyText: init.body,
+        headers: Object.fromEntries(new Headers(init.headers).entries()),
+        rawTelemetryIdHeader:
+          init.headers["X-CopilotKit-Telemetry-Id"] ?? undefined,
+        url: String(input),
+      };
+      return Promise.resolve(new Response(null, { status: 202 }));
+    });
+
+  const readRequest = () => {
+    if (!capturedRequest) {
+      throw new Error("Expected telemetry send to reach fetch successfully");
+    }
+    return capturedRequest;
+  };
+
+  return {
+    readRequest,
+    teardown: () => fetchMock.mockRestore(),
+  };
+}
+
+test.each(["bad\nid", "bad\u0000id", "tenant-🚀"])(
+  "header-invalid legacy identity %j sends anonymously instead of dropping the event",
+  async (invalidTelemetryId) => {
+    const payload = Buffer.from(
+      JSON.stringify({ telemetry_id: invalidTelemetryId }),
+    ).toString("base64url");
+    const { readRequest, teardown } = setupCapturedRequest();
+
+    try {
+      await send({
+        event: "oss.runtime.instance_created",
+        licenseToken: `header.${payload}.sig`,
+      });
+
+      expect(readRequest().rawTelemetryIdHeader).toBeUndefined();
+    } finally {
+      teardown();
+    }
+  },
+);
+
+test.each(INVALID_BASE64URL_PAYLOADS)(
+  "legacy payload with $label sends anonymously in Node and the browser fallback",
+  async ({ payload }) => {
+    const { readRequest, teardown } = setupCapturedRequest();
+    const sendMalformedToken = () =>
+      send({
+        event: "oss.runtime.instance_created",
+        licenseToken: `header.${payload}.sig`,
+      });
+
+    try {
+      await sendMalformedToken();
+      expect(readRequest().rawTelemetryIdHeader).toBeUndefined();
+
+      vi.stubGlobal("Buffer", undefined);
+      await sendMalformedToken();
+      expect(readRequest().rawTelemetryIdHeader).toBeUndefined();
+    } finally {
+      vi.unstubAllGlobals();
+      teardown();
+    }
+  },
+);
 
 describe("lambda-client send()", () => {
   let fetchMock: ReturnType<typeof vi.fn>;
@@ -109,3 +271,176 @@ describe("lambda-client send()", () => {
     ).resolves.toBeUndefined();
   });
 });
+
+const lambdaIdentityTransportCases = [
+  {
+    label: "standalone identity over a legacy license identity",
+    explicitTelemetryId: "explicit-telemetry-id",
+    licenseTelemetryId: "license-telemetry-id",
+    expectedTelemetryId: "explicit-telemetry-id",
+  },
+  {
+    label: "normalized standalone identity over a legacy license identity",
+    explicitTelemetryId: "\t explicit-telemetry-id \t",
+    licenseTelemetryId: "license-telemetry-id",
+    expectedTelemetryId: "explicit-telemetry-id",
+  },
+  {
+    label: "legacy license identity without a standalone identity",
+    explicitTelemetryId: undefined,
+    licenseTelemetryId: "license-telemetry-id",
+    expectedTelemetryId: "license-telemetry-id",
+  },
+  {
+    label: "legacy license identity with an empty standalone identity",
+    explicitTelemetryId: "",
+    licenseTelemetryId: "license-telemetry-id",
+    expectedTelemetryId: "license-telemetry-id",
+  },
+  {
+    label: "legacy license identity with a whitespace-only standalone identity",
+    explicitTelemetryId: " \t ",
+    licenseTelemetryId: "license-telemetry-id",
+    expectedTelemetryId: "license-telemetry-id",
+  },
+  {
+    label: "legacy license identity with a header-invalid standalone identity",
+    explicitTelemetryId: "bad\nid",
+    licenseTelemetryId: "license-telemetry-id",
+    expectedTelemetryId: "license-telemetry-id",
+  },
+  {
+    label: "legacy license identity with an ingest-invalid standalone identity",
+    explicitTelemetryId: "team.prod",
+    licenseTelemetryId: "license-telemetry-id",
+    expectedTelemetryId: "license-telemetry-id",
+  },
+  {
+    label: "legacy license identity with an overlong standalone identity",
+    explicitTelemetryId: "a".repeat(129),
+    licenseTelemetryId: "license-telemetry-id",
+    expectedTelemetryId: "license-telemetry-id",
+  },
+] as const;
+
+test.each(lambdaIdentityTransportCases)(
+  "sends $label only through the telemetry identity header",
+  async ({ explicitTelemetryId, licenseTelemetryId, expectedTelemetryId }) => {
+    const payload = Buffer.from(
+      JSON.stringify({ telemetry_id: licenseTelemetryId }),
+    ).toString("base64url");
+    const licenseToken = `header.${payload}.sig`;
+    const { readRequest, teardown } = setupCapturedRequest();
+
+    try {
+      await send({
+        event: "oss.runtime.instance_created",
+        properties: { requestType: "run" },
+        globalProperties: { sampleRate: 0.25 },
+        packageName: "@copilotkit/runtime",
+        packageVersion: "1.2.3",
+        licenseToken,
+        telemetryId: explicitTelemetryId,
+      });
+
+      const { bodyText, headers, rawTelemetryIdHeader, url } = readRequest();
+      expect(url).toBe(EXPECTED_TELEMETRY_SINK_URL);
+      expect(rawTelemetryIdHeader).toBe(expectedTelemetryId);
+      expect(headers).toEqual({
+        "content-type": "application/json",
+        [TELEMETRY_ID_HEADER]: expectedTelemetryId,
+        "user-agent": "CopilotKit-Runtime/1.2.3 (@copilotkit/runtime)",
+      });
+      expect(JSON.parse(bodyText)).toEqual({
+        event: "oss.runtime.instance_created",
+        properties: { requestType: "run" },
+        global_properties: { sampleRate: 0.25 },
+        package: {
+          name: "@copilotkit/runtime",
+          version: "1.2.3",
+        },
+        ts: expect.any(Number),
+      });
+
+      const nonIdentityHeaders = Object.entries(headers).filter(
+        ([name]) => name !== TELEMETRY_ID_HEADER,
+      );
+      const nonIdentityHeaderText = JSON.stringify(nonIdentityHeaders);
+      for (const identity of [explicitTelemetryId, licenseTelemetryId]) {
+        if (identity === undefined || identity.trim().length === 0) continue;
+        expect(url).not.toContain(identity);
+        expect(bodyText).not.toContain(identity);
+        expect(nonIdentityHeaderText).not.toContain(identity);
+      }
+    } finally {
+      teardown();
+    }
+  },
+);
+
+test.each(["", " \t "])(
+  "blank standalone identity %j without a legacy identity sends no identity header",
+  async (blankTelemetryId) => {
+    const { readRequest, teardown } = setupCapturedRequest();
+
+    try {
+      await send({
+        event: "oss.runtime.instance_created",
+        telemetryId: blankTelemetryId,
+      });
+
+      expect(readRequest().headers[TELEMETRY_ID_HEADER]).toBeUndefined();
+    } finally {
+      teardown();
+    }
+  },
+);
+
+test.each([
+  "bad\nid",
+  "bad\rid",
+  "bad\u0000id",
+  "bad\u0001id",
+  "bad\u007fid",
+  "tenant-🚀",
+])(
+  "header-invalid standalone identity %j sends anonymously instead of dropping the event",
+  async (invalidTelemetryId) => {
+    const { readRequest, teardown } = setupCapturedRequest();
+
+    try {
+      await send({
+        event: "oss.runtime.instance_created",
+        telemetryId: invalidTelemetryId,
+      });
+
+      const { headers, rawTelemetryIdHeader } = readRequest();
+      expect(rawTelemetryIdHeader).toBeUndefined();
+      expect(headers[TELEMETRY_ID_HEADER]).toBeUndefined();
+    } finally {
+      teardown();
+    }
+  },
+);
+
+test("does not treat COPILOTKIT_TELEMETRY_ID as an identity alias", async () => {
+  const originalTelemetryId = process.env.COPILOTKIT_TELEMETRY_ID;
+  const envTelemetryId = "environment-telemetry-id";
+  process.env.COPILOTKIT_TELEMETRY_ID = envTelemetryId;
+  const { readRequest, teardown } = setupCapturedRequest();
+
+  try {
+    await send({ event: "oss.runtime.instance_created" });
+
+    const { bodyText, headers } = readRequest();
+    expect(headers[TELEMETRY_ID_HEADER]).toBeUndefined();
+    expect(bodyText).not.toContain(envTelemetryId);
+  } finally {
+    if (originalTelemetryId === undefined) {
+      delete process.env.COPILOTKIT_TELEMETRY_ID;
+    } else {
+      process.env.COPILOTKIT_TELEMETRY_ID = originalTelemetryId;
+    }
+    teardown();
+  }
+});

package/src/telemetry/lambda-client.ts

@@ -8,12 +8,12 @@
 // private.
 //
 // Two attribution modes:
-//   - Identified: a CopilotKit license token is configured. The token is
-//     a JWT (header.payload.sig) whose payload carries `telemetry_id`.
-//     The SDK base64url-decodes the payload — without verifying the
-//     Ed25519 signature, which is the license-verifier's job — and
-//     emits the id via `X-CopilotKit-Telemetry-Id`. The Lambda uses it
-//     to enrich events with the customer's email.
+//   - Identified: a standalone telemetry id or a CopilotKit license token is
+//     configured. Standalone identity takes precedence. License tokens are
+//     JWTs (header.payload.sig) whose payload carries `telemetry_id`; the SDK
+//     base64url-decodes the payload — without verifying the Ed25519 signature,
+//     which is the license-verifier's job. The resolved identity is emitted
+//     only via `X-CopilotKit-Telemetry-Id`.
 //   - Anonymous: no license token, or a malformed/non-JWT one. No
 //     telemetry-id header; events still flow, attribution is best-effort
 //     from request-level signals (IP, UA).
@@ -30,6 +30,7 @@ const TELEMETRY_SINK_URL =
   "https://telemetry.copilotkit.ai/ingest";
 
 const FETCH_TIMEOUT_MS = 3000;
+const TELEMETRY_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
 
 export interface LambdaSendOptions {
   event: string;
@@ -37,6 +38,8 @@ export interface LambdaSendOptions {
   globalProperties?: Record<string, unknown>;
   packageName?: string;
   packageVersion?: string;
+  /** Standalone analytics identity, resolved before any legacy license claim. */
+  telemetryId?: string;
   // The CopilotKit license token (Ed25519-signed JWT), when one is
   // configured on the runtime. The sender base64url-decodes the payload
   // segment to extract `telemetry_id`; missing or malformed tokens
@@ -44,6 +47,33 @@ export interface LambdaSendOptions {
   licenseToken?: string;
 }
 
+/**
+ * Return the first telemetry identity accepted by the ingest service.
+ *
+ * Empty and whitespace-only values are unconfigured placeholders and must not
+ * suppress a later identity source. Leading and trailing HTTP spaces and tabs
+ * are removed before validation. The ingest service accepts 1 to 128 ASCII
+ * letters, digits, underscores, and hyphens.
+ *
+ * @internal
+ */
+export function firstNonBlankTelemetryId(
+  ...candidates: ReadonlyArray<string | undefined>
+): string | undefined {
+  for (const candidate of candidates) {
+    if (candidate === undefined) {
+      continue;
+    }
+
+    const normalized = candidate.replace(/^[\t ]+|[\t ]+$/g, "");
+    if (TELEMETRY_ID_PATTERN.test(normalized)) {
+      return normalized;
+    }
+  }
+
+  return undefined;
+}
+
 // These fields aren't used by the telemetry service, so we strip them
 // at the wire boundary rather than rely on every caller to omit them.
 // Both the snake_case and camelCase variants are listed because callers
@@ -64,7 +94,7 @@ function stripCloudKeys(
 // Pull telemetry_id out of a CopilotKit license token without verifying
 // the signature. The token shape is a standard JWT
 // (`<header>.<payload>.<sig>`) with base64url-encoded segments; the
-// payload is JSON with a `telemetry_id` string field.
+// payload is UTF-8 JSON with a telemetry_id accepted by the ingest service.
 //
 // Verification (Ed25519, key rotation, expiry) is the license-verifier
 // package's job. For telemetry attribution we only need the claimed id —
@@ -78,17 +108,26 @@ export function parseTelemetryIdFromLicense(token?: string): string | null {
   const parts = token.split(".");
   if (parts.length !== 3) return null;
   try {
-    let b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const payload = parts[1];
+    if (!/^[A-Za-z0-9_-]+$/.test(payload) || payload.length % 4 === 1) {
+      return null;
+    }
+
+    let b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
     const padding = (4 - (b64.length % 4)) % 4;
     b64 += "=".repeat(padding);
     const json =
-      typeof atob === "function"
-        ? atob(b64)
-        : Buffer.from(b64, "base64").toString("utf8");
+      typeof Buffer !== "undefined"
+        ? Buffer.from(b64, "base64").toString("utf8")
+        : new TextDecoder().decode(
+            Uint8Array.from(atob(b64), (character) => character.charCodeAt(0)),
+          );
     const decoded = JSON.parse(json) as { telemetry_id?: unknown };
-    return typeof decoded.telemetry_id === "string"
-      ? decoded.telemetry_id
-      : null;
+    const telemetryId =
+      typeof decoded.telemetry_id === "string"
+        ? decoded.telemetry_id
+        : undefined;
+    return firstNonBlankTelemetryId(telemetryId) ?? null;
   } catch {
     return null;
   }
@@ -122,7 +161,9 @@ export async function send(opts: LambdaSendOptions): Promise<void> {
       ts: Math.floor(Date.now() / 1000),
     });
 
-    const telemetryId = parseTelemetryIdFromLicense(opts.licenseToken);
+    const telemetryId =
+      firstNonBlankTelemetryId(opts.telemetryId) ??
+      parseTelemetryIdFromLicense(opts.licenseToken);
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
       "User-Agent": opts.packageName

package/src/telemetry/sampling.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import {
+  computeSamplingMeta,
+  TELEMETRY_EMITTER_V1,
+  TELEMETRY_EMITTER_V2,
+} from "./sampling";
+
+describe("computeSamplingMeta", () => {
+  test("anonymous callers get the population weight 1/sampleRate", () => {
+    // The gate let 5% through, so each surviving event stands for 20.
+    expect(
+      computeSamplingMeta({ telemetryId: null, sampleRate: 0.05 }),
+    ).toEqual({
+      sampleRate: 0.05,
+      sampleRateAdjustmentFactor: 0.95,
+      sampleWeight: 20,
+      telemetry_identified: false,
+    });
+  });
+
+  test("identified callers get weight 1 — they bypassed the gate", () => {
+    // The branch that matters: an identified event represents only itself,
+    // so weighting it by the anonymous population's 20 would inflate every
+    // paying customer's volume 20×.
+    expect(
+      computeSamplingMeta({ telemetryId: "abc-123", sampleRate: 0.05 }),
+    ).toEqual({
+      sampleRate: 1,
+      sampleRateAdjustmentFactor: 0,
+      sampleWeight: 1,
+      telemetry_identified: true,
+    });
+  });
+
+  test("telemetry_identified stays true when sampleRate=1 makes the weights identical", () => {
+    // COPILOTKIT_TELEMETRY_SAMPLE_RATE=1 gives anonymous events weight 1
+    // too, so weight alone stops separating the populations. This is the
+    // case that makes the flag worth carrying rather than inferring
+    // (OSS-1018).
+    const anon = computeSamplingMeta({ telemetryId: null, sampleRate: 1 });
+    const identified = computeSamplingMeta({
+      telemetryId: "abc-123",
+      sampleRate: 1,
+    });
+
+    expect(anon.sampleWeight).toBe(identified.sampleWeight);
+    expect(anon.telemetry_identified).toBe(false);
+    expect(identified.telemetry_identified).toBe(true);
+  });
+
+  test("an empty telemetry_id is anonymous, not identified", () => {
+    // parseTelemetryIdFromLicense only returns strings or null, but a
+    // token carrying `telemetry_id: ""` would otherwise read as identified
+    // and silently bypass the sample gate.
+    expect(
+      computeSamplingMeta({ telemetryId: "", sampleRate: 0.05 }),
+    ).toMatchObject({ sampleWeight: 20, telemetry_identified: false });
+  });
+
+  test("the two emitter markers are distinct", () => {
+    // Downstream separates the populations by this value; if they ever
+    // collide the dedupe rule silently keeps or drops both.
+    expect(TELEMETRY_EMITTER_V1).not.toBe(TELEMETRY_EMITTER_V2);
+  });
+});

package/src/telemetry/sampling.ts

@@ -0,0 +1,70 @@
+// Per-event telemetry metadata shared by both TelemetryClients.
+//
+// Two clients emit `oss.runtime.*`: the v1 client in this package and the
+// v2 client in @copilotkit/runtime. Both gate anonymous events at
+// `sampleRate` and let identified callers (a license token that yielded a
+// telemetry_id) through at 100%, so real volume can only be recovered
+// downstream as sum(sampleWeight) — a flat multiplier is wrong whenever
+// the identified share moves, which it does as Intelligence keys roll out.
+//
+// The two clients computed this independently and drifted: v2 sampled but
+// stamped nothing, leaving ~24% of runtime volume unweightable from the
+// data alone (OSS-1017). Computing it here is what stops them drifting
+// again.
+
+/** Identifies which client emitted an event. */
+export const TELEMETRY_EMITTER_V1 = "v1-shared";
+export const TELEMETRY_EMITTER_V2 = "v2-runtime";
+
+export type TelemetryEmitter =
+  | typeof TELEMETRY_EMITTER_V1
+  | typeof TELEMETRY_EMITTER_V2;
+
+/**
+ * Which wire an event copy travelled on. The v1 client sends each capture
+ * to both, so this is what tells the two copies apart downstream
+ * (OSS-1019); the v2 client only ever sends to the lambda sink.
+ */
+export type TelemetryTransport = "segment" | "lambda";
+
+export interface SamplingMeta {
+  /** The rate this event was actually gated at: 1 when identified. */
+  sampleRate: number;
+  sampleRateAdjustmentFactor: number;
+  /** Multiply by this to extrapolate the population the event stands for. */
+  sampleWeight: number;
+  /** Whether the event bypassed the sample gate. */
+  telemetry_identified: boolean;
+}
+
+/**
+ * Compute the sampling block for one captured event.
+ *
+ * `telemetryId` is the caller's parsed license telemetry_id, or null when
+ * anonymous — it decides the branch, and is deliberately not returned:
+ * only the non-PII shape below travels on the event.
+ */
+export function computeSamplingMeta({
+  telemetryId,
+  sampleRate,
+}: {
+  telemetryId: string | null;
+  sampleRate: number;
+}): SamplingMeta {
+  const identified = Boolean(telemetryId);
+  // Identified events ship at a 100% effective rate, anonymous ones at
+  // sampleRate. Computed per event because a single global weight would
+  // overweight identified-customer counts by 1/sampleRate.
+  const effectiveSampleRate = identified ? 1 : sampleRate;
+
+  return {
+    sampleRate: effectiveSampleRate,
+    sampleRateAdjustmentFactor: 1 - effectiveSampleRate,
+    sampleWeight: 1 / effectiveSampleRate,
+    // Stated outright rather than inferred from sampleWeight === 1:
+    // under COPILOTKIT_TELEMETRY_SAMPLE_RATE=1 anonymous events also
+    // weigh 1, and the two populations stop being distinguishable
+    // (OSS-1018).
+    telemetry_identified: identified,
+  };
+}