@copilotkit/shared 1.57.3 → 1.58.0

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

@@ -0,0 +1,111 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { send } from "./lambda-client";
+
+describe("lambda-client send()", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let originalFetch: typeof fetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+    fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 202 }));
+    global.fetch = fetchMock as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  function bodyOf(callIdx = 0): {
+    properties: Record<string, unknown>;
+    global_properties: Record<string, unknown>;
+  } {
+    const init = fetchMock.mock.calls[callIdx][1] as RequestInit;
+    return JSON.parse(init.body as string);
+  }
+
+  function headersOf(callIdx = 0): Record<string, string> {
+    const init = fetchMock.mock.calls[callIdx][1] as RequestInit;
+    return init.headers as Record<string, string>;
+  }
+
+  test("strips cloud.public_api_key from properties before sending", async () => {
+    await send({
+      event: "oss.runtime.copilot_request_created",
+      properties: {
+        requestType: "run",
+        "cloud.api_key_provided": true,
+        "cloud.public_api_key": "ck_live_abc.secret-blob",
+      },
+    });
+
+    const body = bodyOf();
+    expect(body.properties).not.toHaveProperty("cloud.public_api_key");
+    // Boolean indicator stays — it's not the key itself.
+    expect(body.properties).toMatchObject({
+      requestType: "run",
+      "cloud.api_key_provided": true,
+    });
+  });
+
+  test("strips cloud.publicApiKey from globalProperties (v1 camelCase variant)", async () => {
+    await send({
+      event: "oss.runtime.instance_created",
+      globalProperties: {
+        "cloud.publicApiKey": "ck_live_abc.secret-blob",
+        "cloud.baseUrl": "https://api.cloud.copilotkit.ai",
+        sampleRate: 0.05,
+      },
+    });
+
+    const body = bodyOf();
+    expect(body.global_properties).not.toHaveProperty("cloud.publicApiKey");
+    // baseUrl is unrelated to attribution and rides through.
+    expect(body.global_properties).toMatchObject({
+      "cloud.baseUrl": "https://api.cloud.copilotkit.ai",
+      sampleRate: 0.05,
+    });
+  });
+
+  test("emits X-CopilotKit-Telemetry-Id when license JWT carries telemetry_id", async () => {
+    const payload = Buffer.from('{"telemetry_id":"abc-123"}').toString(
+      "base64url",
+    );
+    const token = `header.${payload}.sig`;
+
+    await send({
+      event: "oss.runtime.instance_created",
+      licenseToken: token,
+    });
+
+    expect(headersOf()["X-CopilotKit-Telemetry-Id"]).toBe("abc-123");
+  });
+
+  test("falls through to anonymous when license JWT has no telemetry_id", async () => {
+    const payload = Buffer.from('{"license_id":"foo"}').toString("base64url");
+    const token = `header.${payload}.sig`;
+
+    await send({
+      event: "oss.runtime.instance_created",
+      licenseToken: token,
+    });
+
+    expect(headersOf()["X-CopilotKit-Telemetry-Id"]).toBeUndefined();
+  });
+
+  test("falls through to anonymous when license token isn't a JWT shape", async () => {
+    await send({
+      event: "oss.runtime.instance_created",
+      licenseToken: "not-a-jwt",
+    });
+
+    expect(headersOf()["X-CopilotKit-Telemetry-Id"]).toBeUndefined();
+  });
+
+  test("swallows fetch errors silently", async () => {
+    fetchMock.mockRejectedValueOnce(new Error("network down"));
+
+    await expect(
+      send({ event: "oss.runtime.instance_created" }),
+    ).resolves.toBeUndefined();
+  });
+});

package/src/telemetry/lambda-client.ts

@@ -0,0 +1,153 @@
+// Telemetry sink client.
+//
+// Posts events to a CopilotKit-controlled telemetry-sink endpoint, which
+// fans out to Scarf, Reo, and any future destinations. Replaces the direct
+// per-vendor calls (scarf-client.ts) so that vendor changes don't require
+// SDK releases and so that downstream services we don't want exposed to
+// OSS readers (e.g. the email-enrichment service backing Reo) stay
+// 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.
+//   - 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).
+//
+// Note: CopilotCloud customer API keys (`ck_<env>_<id>.<secret>`) are
+// unrelated to telemetry attribution. They flow into Segment / PostHog
+// via the v1 shared TelemetryClient and never reach this code path.
+//
+// Best-effort: every error is swallowed. Telemetry must not break the
+// host application.
+
+const TELEMETRY_SINK_URL =
+  (typeof process !== "undefined" && process.env?.COPILOTKIT_TELEMETRY_URL) ||
+  "https://telemetry.copilotkit.ai/ingest";
+
+const FETCH_TIMEOUT_MS = 3000;
+
+export interface LambdaSendOptions {
+  event: string;
+  properties?: Record<string, unknown>;
+  globalProperties?: Record<string, unknown>;
+  packageName?: string;
+  packageVersion?: 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
+  // produce an anonymous send.
+  licenseToken?: string;
+}
+
+// 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
+// upstream use different conventions.
+const STRIPPED_KEYS = new Set(["cloud.public_api_key", "cloud.publicApiKey"]);
+
+function stripCloudKeys(
+  obj: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!obj) return {};
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (!STRIPPED_KEYS.has(k)) out[k] = v;
+  }
+  return out;
+}
+
+// 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.
+//
+// Verification (Ed25519, key rotation, expiry) is the license-verifier
+// package's job. For telemetry attribution we only need the claimed id —
+// the trust model is claim-only on the Lambda side anyway.
+//
+// Exported so TelemetryClient setters can detect unparseable tokens at
+// configuration time and surface a single warning, instead of silently
+// emitting anonymous events on every capture.
+export function parseTelemetryIdFromLicense(token?: string): string | null {
+  if (!token) return null;
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    let b64 = parts[1].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");
+    const decoded = JSON.parse(json) as { telemetry_id?: unknown };
+    return typeof decoded.telemetry_id === "string"
+      ? decoded.telemetry_id
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// Parse the telemetry_id from a license token AND emit the rollout smoke
+// signal if the parse returned null. Returning the parsed id lets callers
+// cache it in one step (avoiding a second parseTelemetryIdFromLicense
+// pass) while keeping the warn text in lockstep between v1 (shared) and
+// v2 (runtime) TelemetryClient.setLicenseToken.
+export function parseAndWarnTelemetryId(licenseToken: string): string | null {
+  const telemetryId = parseTelemetryIdFromLicense(licenseToken);
+  if (!telemetryId) {
+    console.warn(
+      "[CopilotKit] License token did not yield a telemetry_id; telemetry events will be sent anonymously.",
+    );
+  }
+  return telemetryId;
+}
+
+export async function send(opts: LambdaSendOptions): Promise<void> {
+  try {
+    const body = JSON.stringify({
+      event: opts.event,
+      properties: stripCloudKeys(opts.properties),
+      global_properties: stripCloudKeys(opts.globalProperties),
+      package: {
+        name: opts.packageName,
+        version: opts.packageVersion,
+      },
+      ts: Math.floor(Date.now() / 1000),
+    });
+
+    const telemetryId = parseTelemetryIdFromLicense(opts.licenseToken);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "User-Agent": opts.packageName
+        ? `CopilotKit-Runtime/${opts.packageVersion ?? "unknown"} (${opts.packageName})`
+        : "CopilotKit-Runtime",
+    };
+    if (telemetryId) {
+      headers["X-CopilotKit-Telemetry-Id"] = telemetryId;
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      await fetch(TELEMETRY_SINK_URL, {
+        method: "POST",
+        headers,
+        body,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  } catch {
+    // Silent failure — telemetry must not break the application.
+  }
+}
+
+export default { send };

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

@@ -0,0 +1,289 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { MockInstance } from "vitest";
+import lambdaClient from "./lambda-client";
+import { TelemetryClient, isTelemetryDisabled } from "./telemetry-client";
+
+// Module mock so constructing TelemetryClient doesn't spin up segment's
+// internal flush queue. Class-based (not vi.fn) so `vi.restoreAllMocks()`
+// between tests doesn't wipe the `track` binding on subsequent `new
+// Analytics(...)` calls.
+const { segmentTrackMock } = vi.hoisted(() => ({
+  segmentTrackMock: vi.fn(),
+}));
+vi.mock("@segment/analytics-node", () => ({
+  Analytics: class {
+    track = segmentTrackMock;
+  },
+}));
+
+describe("v1 TelemetryClient", () => {
+  let lambdaSpy: MockInstance<typeof lambdaClient.send>;
+
+  beforeEach(() => {
+    lambdaSpy = vi.spyOn(lambdaClient, "send").mockResolvedValue(undefined);
+    segmentTrackMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function makeClient(
+    overrides: Partial<ConstructorParameters<typeof TelemetryClient>[0]> = {},
+  ): TelemetryClient {
+    return new TelemetryClient({
+      packageName: "@copilotkit/shared",
+      packageVersion: "1.0.0",
+      sampleRate: 1,
+      ...overrides,
+    });
+  }
+
+  function jwtWith(payload: Record<string, unknown>): string {
+    const b64 = Buffer.from(JSON.stringify(payload)).toString("base64url");
+    return `header.${b64}.sig`;
+  }
+
+  const baseInstanceEvent = {
+    actionsAmount: 0,
+    endpointsAmount: 0,
+    endpointTypes: [],
+    "cloud.api_key_provided": false,
+  } as const;
+
+  test("capture sends to both sinks when sampled in (anonymous, one decision gates both)", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const client = makeClient({ sampleRate: 0.05 });
+
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy).toHaveBeenCalledTimes(1);
+    expect(segmentTrackMock).toHaveBeenCalledTimes(1);
+    expect(segmentTrackMock.mock.calls[0][0]).toMatchObject({
+      event: "oss.runtime.instance_created",
+    });
+  });
+
+  test("capture skips both sinks when anonymous and sampled out", async () => {
+    // Math.random=0.99 vs sampleRate=0.05 — anonymous caller is gated out;
+    // neither sink should fire under the new one-decision-both-sinks model.
+    vi.spyOn(Math, "random").mockReturnValue(0.99);
+    const client = makeClient({ sampleRate: 0.05 });
+
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy).not.toHaveBeenCalled();
+    expect(segmentTrackMock).not.toHaveBeenCalled();
+  });
+
+  test("identified callers bypass the sample gate (lambda + segment fire even when Math.random would fail)", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0.99);
+    const client = makeClient({ sampleRate: 0.05 });
+    client.setLicenseToken(jwtWith({ telemetry_id: "abc-123" }));
+
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy).toHaveBeenCalledTimes(1);
+    expect(segmentTrackMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("identified callers send to both sinks on every capture", async () => {
+    const client = makeClient({ sampleRate: 0.05 });
+    client.setLicenseToken(jwtWith({ telemetry_id: "abc-123" }));
+
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy).toHaveBeenCalledTimes(2);
+    expect(segmentTrackMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("capture short-circuits both sinks when telemetryDisabled is true", async () => {
+    const client = makeClient({ telemetryDisabled: true });
+
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy).not.toHaveBeenCalled();
+    expect(segmentTrackMock).not.toHaveBeenCalled();
+  });
+
+  test("setLicenseToken forwards the token in subsequent capture", async () => {
+    const token = jwtWith({ telemetry_id: "abc-123" });
+    const client = makeClient();
+    client.setLicenseToken(token);
+
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy).toHaveBeenCalledTimes(1);
+    expect(lambdaSpy.mock.calls[0][0].licenseToken).toBe(token);
+  });
+
+  test("capture sends licenseToken=undefined when setLicenseToken was never called", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const client = makeClient();
+
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy.mock.calls[0][0].licenseToken).toBeUndefined();
+  });
+
+  test("setLicenseToken warns once when the token has no telemetry_id", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const client = makeClient();
+
+    client.setLicenseToken(jwtWith({ license_id: "x" }));
+
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toMatch(/telemetry_id/);
+  });
+
+  test("setLicenseToken does not warn when the token carries telemetry_id", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const client = makeClient();
+
+    client.setLicenseToken(jwtWith({ telemetry_id: "abc-123" }));
+
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  test("identified events carry sampleWeight=1 (anonymous events carry 1/sampleRate)", async () => {
+    // Anonymous: sampleWeight should be 1 / sampleRate so downstream
+    // weight-based extrapolation reconstructs true volume.
+    // Identified: bypassing the gate means each event represents itself,
+    // so sampleWeight must be 1 — not the population's 1/sampleRate.
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const anonClient = makeClient({ sampleRate: 0.05 });
+    await anonClient.capture("oss.runtime.instance_created", baseInstanceEvent);
+    expect(lambdaSpy.mock.calls[0][0].globalProperties).toMatchObject({
+      sampleRate: 0.05,
+      sampleWeight: 20,
+    });
+    expect(segmentTrackMock.mock.calls[0][0]).toMatchObject({
+      properties: expect.objectContaining({
+        sampleRate: 0.05,
+        sampleWeight: 20,
+      }),
+    });
+
+    lambdaSpy.mockClear();
+    segmentTrackMock.mockReset();
+
+    const idClient = makeClient({ sampleRate: 0.05 });
+    idClient.setLicenseToken(jwtWith({ telemetry_id: "abc-123" }));
+    await idClient.capture("oss.runtime.instance_created", baseInstanceEvent);
+    expect(lambdaSpy.mock.calls[0][0].globalProperties).toMatchObject({
+      sampleRate: 1,
+      sampleWeight: 1,
+    });
+    expect(segmentTrackMock.mock.calls[0][0]).toMatchObject({
+      properties: expect.objectContaining({ sampleRate: 1, sampleWeight: 1 }),
+    });
+  });
+
+  test("malformed license token stays anonymous and remains sample-gated", async () => {
+    // parseTelemetryIdFromLicense returns null for any of: empty token,
+    // wrong-shape (not three dot-separated segments), base64/JSON parse
+    // failure. A misconfigured customer must not flip to identified-bypass.
+    vi.spyOn(Math, "random").mockReturnValue(0.99);
+    vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const client = makeClient({ sampleRate: 0.05 });
+
+    client.setLicenseToken("not-a-jwt");
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy).not.toHaveBeenCalled();
+    expect(segmentTrackMock).not.toHaveBeenCalled();
+  });
+
+  test("setLicenseToken cache is overwritable (good token replaced by bad → back to anonymous gate)", async () => {
+    // Pins the cache as last-write-wins so a refactor to first-write-wins
+    // (e.g. `this.telemetryId ??= parseAndWarnTelemetryId(...)`) doesn't
+    // leak identified-bypass status across license replacements.
+    vi.spyOn(Math, "random").mockReturnValue(0.99);
+    vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const client = makeClient({ sampleRate: 0.05 });
+
+    client.setLicenseToken(jwtWith({ telemetry_id: "abc-123" }));
+    client.setLicenseToken(jwtWith({ license_id: "no-telemetry-id" }));
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    expect(lambdaSpy).not.toHaveBeenCalled();
+    expect(segmentTrackMock).not.toHaveBeenCalled();
+  });
+
+  test("setCloudConfiguration writes cloud keys into globalProperties for both sinks", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0);
+    const client = makeClient({ sampleRate: 1 });
+    client.setCloudConfiguration({
+      publicApiKey: "ck_live_test.secret",
+      baseUrl: "https://api.cloud.copilotkit.ai",
+    });
+
+    await client.capture("oss.runtime.instance_created", baseInstanceEvent);
+
+    // v1 still ships cloud.publicApiKey through globalProperties — the
+    // lambda-client.send sanitization strips it at the wire (covered in
+    // lambda-client.test.ts), and Segment retains it intentionally for
+    // existing CopilotCloud user analytics.
+    expect(lambdaSpy.mock.calls[0][0].globalProperties).toMatchObject({
+      "cloud.publicApiKey": "ck_live_test.secret",
+      "cloud.baseUrl": "https://api.cloud.copilotkit.ai",
+    });
+    expect(segmentTrackMock.mock.calls[0][0]).toMatchObject({
+      properties: expect.objectContaining({
+        "cloud.publicApiKey": "ck_live_test.secret",
+        "cloud.baseUrl": "https://api.cloud.copilotkit.ai",
+      }),
+    });
+  });
+
+  test("constructor rejects sampleRate outside [0, 1]", () => {
+    expect(() => makeClient({ sampleRate: 1.5 })).toThrow(
+      "Sample rate must be between 0 and 1",
+    );
+    expect(() => makeClient({ sampleRate: -0.1 })).toThrow(
+      "Sample rate must be between 0 and 1",
+    );
+  });
+
+  test("constructor rejects NaN sampleRate from a malformed env override", () => {
+    // parseFloat('nonsense') = NaN; without the explicit guard, NaN slips
+    // past the range check (all NaN comparisons are false) and produces a
+    // silent always-drop. Guard the validator with Number.isNaN.
+    const original = process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE;
+    process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE = "not-a-number";
+    try {
+      expect(() => makeClient()).toThrow("Sample rate must be between 0 and 1");
+    } finally {
+      if (original === undefined) {
+        delete process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE;
+      } else {
+        process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE = original;
+      }
+    }
+  });
+});
+
+describe("isTelemetryDisabled", () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  test.each([
+    ["COPILOTKIT_TELEMETRY_DISABLED", "true"],
+    ["COPILOTKIT_TELEMETRY_DISABLED", "1"],
+    ["DO_NOT_TRACK", "true"],
+    ["DO_NOT_TRACK", "1"],
+  ])("returns true when %s=%s", (key, val) => {
+    process.env[key] = val;
+    expect(isTelemetryDisabled()).toBe(true);
+  });
+
+  test("returns false when no opt-out env var is set", () => {
+    delete process.env.COPILOTKIT_TELEMETRY_DISABLED;
+    delete process.env.DO_NOT_TRACK;
+    expect(isTelemetryDisabled()).toBe(false);
+  });
+});

package/src/telemetry/telemetry-client.ts

@@ -1,8 +1,8 @@
 import { Analytics } from "@segment/analytics-node";
-import { AnalyticsEvents } from "./events";
+import type { AnalyticsEvents } from "./events";
 import { flattenObject } from "./utils";
 import { v4 as uuidv4 } from "uuid";
-import scarfClient from "./scarf-client";
+import lambdaClient, { parseAndWarnTelemetryId } from "./lambda-client";
 
 /**
  * Checks if telemetry is disabled via environment variables.
@@ -26,9 +26,22 @@ export class TelemetryClient {
   segment: Analytics | undefined;
   globalProperties: Record<string, any> = {};
   cloudConfiguration: { publicApiKey: string; baseUrl: string } | null = null;
+  // EIP / Intelligence license token (Ed25519-signed JWT). The lambda
+  // client decodes its payload to extract telemetry_id. Customer API
+  // keys are NOT used here — they flow only into Segment.
+  private licenseToken: string | null = null;
+  // Parsed telemetry_id from the license-token JWT payload. Cached at
+  // setLicenseToken time so `capture()` can branch on identified vs
+  // anonymous without re-parsing per event. Null when the token is
+  // absent or yielded no telemetry_id.
+  private telemetryId: string | null = null;
   packageName: string;
   packageVersion: string;
   private telemetryDisabled: boolean = false;
+  // Client-side sampling rate for anonymous events. Identified events
+  // (those whose license token yielded a telemetry_id) bypass the gate
+  // entirely. Applied uniformly to both the lambda sink and Segment —
+  // one dice roll per capture, both sinks see the same decision.
   private sampleRate: number = 0.05;
   private anonymousId = `anon_${uuidv4()}`;
 
@@ -79,13 +92,34 @@ export class TelemetryClient {
     event: K,
     properties: AnalyticsEvents[K],
   ) {
-    if (!this.shouldSendEvent() || !this.segment) {
+    if (this.telemetryDisabled) {
+      return;
+    }
+
+    // Anonymous callers (no telemetry_id) are gated by sampleRate.
+    // Identified callers (license token with telemetry_id) always send —
+    // the volume is bounded by paying-customer count and full fidelity
+    // per identified customer is worth the marginal cost.
+    if (!this.telemetryId && !this.shouldSendEvent()) {
       return;
     }
 
+    // Identified events ship at 100% effective rate, anonymous events at
+    // sampleRate. Compute per-event so downstream weight-based extrapolation
+    // (sampleWeight = 1 / effectiveRate) is correct for both populations;
+    // a single global sampleWeight would overweight identified-customer
+    // counts by 1/sampleRate.
+    const effectiveSampleRate = this.telemetryId ? 1 : this.sampleRate;
+    const samplingMeta = {
+      sampleRate: effectiveSampleRate,
+      sampleRateAdjustmentFactor: 1 - effectiveSampleRate,
+      sampleWeight: 1 / effectiveSampleRate,
+    };
+
     const flattenedProperties = flattenObject(properties);
     const propertiesWithGlobal = {
       ...this.globalProperties,
+      ...samplingMeta,
       ...flattenedProperties,
     };
     const orderedPropertiesWithGlobal = Object.keys(propertiesWithGlobal)
@@ -98,15 +132,22 @@ export class TelemetryClient {
         {} as Record<string, any>,
       );
 
-    this.segment.track({
-      anonymousId: this.anonymousId,
+    await lambdaClient.send({
       event,
-      properties: { ...orderedPropertiesWithGlobal },
+      properties: flattenedProperties,
+      globalProperties: { ...this.globalProperties, ...samplingMeta },
+      packageName: this.packageName,
+      packageVersion: this.packageVersion,
+      licenseToken: this.licenseToken ?? undefined,
     });
 
-    await scarfClient.logEvent({
-      event,
-    });
+    if (this.segment) {
+      this.segment.track({
+        anonymousId: this.anonymousId,
+        event,
+        properties: { ...orderedPropertiesWithGlobal },
+      });
+    }
   }
 
   setGlobalProperties(properties: Record<string, any>) {
@@ -128,6 +169,14 @@ export class TelemetryClient {
     });
   }
 
+  // The license token isn't added to globalProperties — we don't want
+  // the JWT itself shipped on every event. Only its decoded telemetry_id
+  // travels, in the X-CopilotKit-Telemetry-Id header set by lambda-client.
+  setLicenseToken(licenseToken: string) {
+    this.licenseToken = licenseToken;
+    this.telemetryId = parseAndWarnTelemetryId(licenseToken);
+  }
+
   private setSampleRate(sampleRate: number | undefined) {
     let _sampleRate: number;
 
@@ -139,15 +188,18 @@ export class TelemetryClient {
       _sampleRate = parseFloat(process.env.COPILOTKIT_TELEMETRY_SAMPLE_RATE);
     }
 
-    if (_sampleRate < 0 || _sampleRate > 1) {
+    // Number.isNaN guards against parseFloat("nonsense") slipping past the
+    // range check (all NaN comparisons are false), which would silently
+    // drop every anonymous event with no signal — especially important
+    // since the default is now 0.05, making env-var overrides more common.
+    if (Number.isNaN(_sampleRate) || _sampleRate < 0 || _sampleRate > 1) {
       throw new Error("Sample rate must be between 0 and 1");
     }
 
     this.sampleRate = _sampleRate;
-    this.setGlobalProperties({
-      sampleRate: this.sampleRate,
-      sampleRateAdjustmentFactor: 1 - this.sampleRate,
-      sampleWeight: 1 / this.sampleRate,
-    });
+    // Per-event sampling metadata (sampleRate/sampleRateAdjustmentFactor/
+    // sampleWeight) is computed in capture() so identified events get
+    // their own effectiveSampleRate=1 weight instead of the anonymous
+    // population's 1/sampleRate.
   }
 }