@copilotkit/shared 1.69.2 → 1.70.0

package/dist/package.cjs

@@ -1,6 +1,6 @@
 
 //#region package.json
-var version = "1.69.2";
+var version = "1.70.0";
 
 //#endregion
 Object.defineProperty(exports, 'version', {

package/dist/package.mjs

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "1.69.2";
+var version = "1.70.0";
 
 //#endregion
 export { version };

package/dist/telemetry/index.d.mts

@@ -1,2 +1,3 @@
-import { TelemetryClient, isTelemetryDisabled } from "./telemetry-client.mjs";
-import { LambdaSendOptions, lambdaClient, parseAndWarnTelemetryId, parseTelemetryIdFromLicense } from "./lambda-client.mjs";
+import { TelemetryCapture, TelemetryClient, TelemetryIdentity, isTelemetryDisabled } from "./telemetry-client.mjs";
+import { SamplingMeta, TELEMETRY_EMITTER_V1, TELEMETRY_EMITTER_V2, TelemetryEmitter, TelemetryTransport, computeSamplingMeta } from "./sampling.mjs";
+import { LambdaSendOptions, firstNonBlankTelemetryId, lambdaClient, parseAndWarnTelemetryId, parseTelemetryIdFromLicense } from "./lambda-client.mjs";

package/dist/telemetry/lambda-client.cjs

@@ -2,6 +2,24 @@
 //#region src/telemetry/lambda-client.ts
 const TELEMETRY_SINK_URL = typeof process !== "undefined" && process.env?.COPILOTKIT_TELEMETRY_URL || "https://telemetry.copilotkit.ai/ingest";
 const FETCH_TIMEOUT_MS = 3e3;
+const TELEMETRY_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+/**
+* 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
+*/
+function firstNonBlankTelemetryId(...candidates) {
+	for (const candidate of candidates) {
+		if (candidate === void 0) continue;
+		const normalized = candidate.replace(/^[\t ]+|[\t ]+$/g, "");
+		if (TELEMETRY_ID_PATTERN.test(normalized)) return normalized;
+	}
+}
 const STRIPPED_KEYS = new Set(["cloud.public_api_key", "cloud.publicApiKey"]);
 function stripCloudKeys(obj) {
 	if (!obj) return {};
@@ -14,12 +32,14 @@ function parseTelemetryIdFromLicense(token) {
 	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");
+		const json = 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);
-		return typeof decoded.telemetry_id === "string" ? decoded.telemetry_id : null;
+		return firstNonBlankTelemetryId(typeof decoded.telemetry_id === "string" ? decoded.telemetry_id : void 0) ?? null;
 	} catch {
 		return null;
 	}
@@ -41,7 +61,7 @@ async function send(opts) {
 			},
 			ts: Math.floor(Date.now() / 1e3)
 		});
-		const telemetryId = parseTelemetryIdFromLicense(opts.licenseToken);
+		const telemetryId = firstNonBlankTelemetryId(opts.telemetryId) ?? parseTelemetryIdFromLicense(opts.licenseToken);
 		const headers = {
 			"Content-Type": "application/json",
 			"User-Agent": opts.packageName ? `CopilotKit-Runtime/${opts.packageVersion ?? "unknown"} (${opts.packageName})` : "CopilotKit-Runtime"
@@ -64,6 +84,7 @@ async function send(opts) {
 const lambdaClient = { send };
 
 //#endregion
+exports.firstNonBlankTelemetryId = firstNonBlankTelemetryId;
 exports.lambdaClient = lambdaClient;
 exports.parseAndWarnTelemetryId = parseAndWarnTelemetryId;
 exports.parseTelemetryIdFromLicense = parseTelemetryIdFromLicense;

package/dist/telemetry/lambda-client.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"lambda-client.cjs","names":[],"sources":["../../src/telemetry/lambda-client.ts"],"sourcesContent":["// Telemetry sink client.\n//\n// Posts events to a CopilotKit-controlled telemetry-sink endpoint, which\n// fans out to Scarf, Reo, and any future destinations. Replaces the direct\n// per-vendor calls (scarf-client.ts) so that vendor changes don't require\n// SDK releases and so that downstream services we don't want exposed to\n// OSS readers (e.g. the email-enrichment service backing Reo) stay\n// private.\n//\n// Two attribution modes:\n//   - Identified: a CopilotKit license token is configured. The token is\n//     a JWT (header.payload.sig) whose payload carries `telemetry_id`.\n//     The SDK base64url-decodes the payload — without verifying the\n//     Ed25519 signature, which is the license-verifier's job — and\n//     emits the id via `X-CopilotKit-Telemetry-Id`. The Lambda uses it\n//     to enrich events with the customer's email.\n//   - Anonymous: no license token, or a malformed/non-JWT one. No\n//     telemetry-id header; events still flow, attribution is best-effort\n//     from request-level signals (IP, UA).\n//\n// Note: CopilotCloud customer API keys (`ck_<env>_<id>.<secret>`) are\n// unrelated to telemetry attribution. They flow into Segment / PostHog\n// via the v1 shared TelemetryClient and never reach this code path.\n//\n// Best-effort: every error is swallowed. Telemetry must not break the\n// host application.\n\nconst TELEMETRY_SINK_URL =\n  (typeof process !== \"undefined\" && process.env?.COPILOTKIT_TELEMETRY_URL) ||\n  \"https://telemetry.copilotkit.ai/ingest\";\n\nconst FETCH_TIMEOUT_MS = 3000;\n\nexport interface LambdaSendOptions {\n  event: string;\n  properties?: Record<string, unknown>;\n  globalProperties?: Record<string, unknown>;\n  packageName?: string;\n  packageVersion?: string;\n  // The CopilotKit license token (Ed25519-signed JWT), when one is\n  // configured on the runtime. The sender base64url-decodes the payload\n  // segment to extract `telemetry_id`; missing or malformed tokens\n  // produce an anonymous send.\n  licenseToken?: string;\n}\n\n// These fields aren't used by the telemetry service, so we strip them\n// at the wire boundary rather than rely on every caller to omit them.\n// Both the snake_case and camelCase variants are listed because callers\n// upstream use different conventions.\nconst STRIPPED_KEYS = new Set([\"cloud.public_api_key\", \"cloud.publicApiKey\"]);\n\nfunction stripCloudKeys(\n  obj: Record<string, unknown> | undefined,\n): Record<string, unknown> {\n  if (!obj) return {};\n  const out: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!STRIPPED_KEYS.has(k)) out[k] = v;\n  }\n  return out;\n}\n\n// Pull telemetry_id out of a CopilotKit license token without verifying\n// the signature. The token shape is a standard JWT\n// (`<header>.<payload>.<sig>`) with base64url-encoded segments; the\n// payload is JSON with a `telemetry_id` string field.\n//\n// Verification (Ed25519, key rotation, expiry) is the license-verifier\n// package's job. For telemetry attribution we only need the claimed id —\n// the trust model is claim-only on the Lambda side anyway.\n//\n// Exported so TelemetryClient setters can detect unparseable tokens at\n// configuration time and surface a single warning, instead of silently\n// emitting anonymous events on every capture.\nexport function parseTelemetryIdFromLicense(token?: string): string | null {\n  if (!token) return null;\n  const parts = token.split(\".\");\n  if (parts.length !== 3) return null;\n  try {\n    let b64 = parts[1].replace(/-/g, \"+\").replace(/_/g, \"/\");\n    const padding = (4 - (b64.length % 4)) % 4;\n    b64 += \"=\".repeat(padding);\n    const json =\n      typeof atob === \"function\"\n        ? atob(b64)\n        : Buffer.from(b64, \"base64\").toString(\"utf8\");\n    const decoded = JSON.parse(json) as { telemetry_id?: unknown };\n    return typeof decoded.telemetry_id === \"string\"\n      ? decoded.telemetry_id\n      : null;\n  } catch {\n    return null;\n  }\n}\n\n// Parse the telemetry_id from a license token AND emit the rollout smoke\n// signal if the parse returned null. Returning the parsed id lets callers\n// cache it in one step (avoiding a second parseTelemetryIdFromLicense\n// pass) while keeping the warn text in lockstep between v1 (shared) and\n// v2 (runtime) TelemetryClient.setLicenseToken.\nexport function parseAndWarnTelemetryId(licenseToken: string): string | null {\n  const telemetryId = parseTelemetryIdFromLicense(licenseToken);\n  if (!telemetryId) {\n    console.warn(\n      \"[CopilotKit] License token did not yield a telemetry_id; telemetry events will be sent anonymously.\",\n    );\n  }\n  return telemetryId;\n}\n\nexport async function send(opts: LambdaSendOptions): Promise<void> {\n  try {\n    const body = JSON.stringify({\n      event: opts.event,\n      properties: stripCloudKeys(opts.properties),\n      global_properties: stripCloudKeys(opts.globalProperties),\n      package: {\n        name: opts.packageName,\n        version: opts.packageVersion,\n      },\n      ts: Math.floor(Date.now() / 1000),\n    });\n\n    const telemetryId = parseTelemetryIdFromLicense(opts.licenseToken);\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      \"User-Agent\": opts.packageName\n        ? `CopilotKit-Runtime/${opts.packageVersion ?? \"unknown\"} (${opts.packageName})`\n        : \"CopilotKit-Runtime\",\n    };\n    if (telemetryId) {\n      headers[\"X-CopilotKit-Telemetry-Id\"] = telemetryId;\n    }\n\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);\n    try {\n      await fetch(TELEMETRY_SINK_URL, {\n        method: \"POST\",\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  } catch {\n    // Silent failure — telemetry must not break the application.\n  }\n}\n\nexport const lambdaClient = { send };\n"],"mappings":";;AA2BA,MAAM,qBACH,OAAO,YAAY,eAAe,QAAQ,KAAK,4BAChD;AAEF,MAAM,mBAAmB;AAmBzB,MAAM,gBAAgB,IAAI,IAAI,CAAC,wBAAwB,qBAAqB,CAAC;AAE7E,SAAS,eACP,KACyB;AACzB,KAAI,CAAC,IAAK,QAAO,EAAE;CACnB,MAAM,MAA+B,EAAE;AACvC,MAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,IAAI,CACtC,KAAI,CAAC,cAAc,IAAI,EAAE,CAAE,KAAI,KAAK;AAEtC,QAAO;;AAeT,SAAgB,4BAA4B,OAA+B;AACzE,KAAI,CAAC,MAAO,QAAO;CACnB,MAAM,QAAQ,MAAM,MAAM,IAAI;AAC9B,KAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,KAAI;EACF,IAAI,MAAM,MAAM,GAAG,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,IAAI;EACxD,MAAM,WAAW,IAAK,IAAI,SAAS,KAAM;AACzC,SAAO,IAAI,OAAO,QAAQ;EAC1B,MAAM,OACJ,OAAO,SAAS,aACZ,KAAK,IAAI,GACT,OAAO,KAAK,KAAK,SAAS,CAAC,SAAS,OAAO;EACjD,MAAM,UAAU,KAAK,MAAM,KAAK;AAChC,SAAO,OAAO,QAAQ,iBAAiB,WACnC,QAAQ,eACR;SACE;AACN,SAAO;;;AASX,SAAgB,wBAAwB,cAAqC;CAC3E,MAAM,cAAc,4BAA4B,aAAa;AAC7D,KAAI,CAAC,YACH,SAAQ,KACN,sGACD;AAEH,QAAO;;AAGT,eAAsB,KAAK,MAAwC;AACjE,KAAI;EACF,MAAM,OAAO,KAAK,UAAU;GAC1B,OAAO,KAAK;GACZ,YAAY,eAAe,KAAK,WAAW;GAC3C,mBAAmB,eAAe,KAAK,iBAAiB;GACxD,SAAS;IACP,MAAM,KAAK;IACX,SAAS,KAAK;IACf;GACD,IAAI,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;GAClC,CAAC;EAEF,MAAM,cAAc,4BAA4B,KAAK,aAAa;EAClE,MAAM,UAAkC;GACtC,gBAAgB;GAChB,cAAc,KAAK,cACf,sBAAsB,KAAK,kBAAkB,UAAU,IAAI,KAAK,YAAY,KAC5E;GACL;AACD,MAAI,YACF,SAAQ,+BAA+B;EAGzC,MAAM,aAAa,IAAI,iBAAiB;EACxC,MAAM,YAAY,iBAAiB,WAAW,OAAO,EAAE,iBAAiB;AACxE,MAAI;AACF,SAAM,MAAM,oBAAoB;IAC9B,QAAQ;IACR;IACA;IACA,QAAQ,WAAW;IACpB,CAAC;YACM;AACR,gBAAa,UAAU;;SAEnB;;AAKV,MAAa,eAAe,EAAE,MAAM"}
+{"version":3,"file":"lambda-client.cjs","names":[],"sources":["../../src/telemetry/lambda-client.ts"],"sourcesContent":["// Telemetry sink client.\n//\n// Posts events to a CopilotKit-controlled telemetry-sink endpoint, which\n// fans out to Scarf, Reo, and any future destinations. Replaces the direct\n// per-vendor calls (scarf-client.ts) so that vendor changes don't require\n// SDK releases and so that downstream services we don't want exposed to\n// OSS readers (e.g. the email-enrichment service backing Reo) stay\n// private.\n//\n// Two attribution modes:\n//   - Identified: a standalone telemetry id or a CopilotKit license token is\n//     configured. Standalone identity takes precedence. License tokens are\n//     JWTs (header.payload.sig) whose payload carries `telemetry_id`; the SDK\n//     base64url-decodes the payload — without verifying the Ed25519 signature,\n//     which is the license-verifier's job. The resolved identity is emitted\n//     only via `X-CopilotKit-Telemetry-Id`.\n//   - Anonymous: no license token, or a malformed/non-JWT one. No\n//     telemetry-id header; events still flow, attribution is best-effort\n//     from request-level signals (IP, UA).\n//\n// Note: CopilotCloud customer API keys (`ck_<env>_<id>.<secret>`) are\n// unrelated to telemetry attribution. They flow into Segment / PostHog\n// via the v1 shared TelemetryClient and never reach this code path.\n//\n// Best-effort: every error is swallowed. Telemetry must not break the\n// host application.\n\nconst TELEMETRY_SINK_URL =\n  (typeof process !== \"undefined\" && process.env?.COPILOTKIT_TELEMETRY_URL) ||\n  \"https://telemetry.copilotkit.ai/ingest\";\n\nconst FETCH_TIMEOUT_MS = 3000;\nconst TELEMETRY_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;\n\nexport interface LambdaSendOptions {\n  event: string;\n  properties?: Record<string, unknown>;\n  globalProperties?: Record<string, unknown>;\n  packageName?: string;\n  packageVersion?: string;\n  /** Standalone analytics identity, resolved before any legacy license claim. */\n  telemetryId?: string;\n  // The CopilotKit license token (Ed25519-signed JWT), when one is\n  // configured on the runtime. The sender base64url-decodes the payload\n  // segment to extract `telemetry_id`; missing or malformed tokens\n  // produce an anonymous send.\n  licenseToken?: string;\n}\n\n/**\n * Return the first telemetry identity accepted by the ingest service.\n *\n * Empty and whitespace-only values are unconfigured placeholders and must not\n * suppress a later identity source. Leading and trailing HTTP spaces and tabs\n * are removed before validation. The ingest service accepts 1 to 128 ASCII\n * letters, digits, underscores, and hyphens.\n *\n * @internal\n */\nexport function firstNonBlankTelemetryId(\n  ...candidates: ReadonlyArray<string | undefined>\n): string | undefined {\n  for (const candidate of candidates) {\n    if (candidate === undefined) {\n      continue;\n    }\n\n    const normalized = candidate.replace(/^[\\t ]+|[\\t ]+$/g, \"\");\n    if (TELEMETRY_ID_PATTERN.test(normalized)) {\n      return normalized;\n    }\n  }\n\n  return undefined;\n}\n\n// These fields aren't used by the telemetry service, so we strip them\n// at the wire boundary rather than rely on every caller to omit them.\n// Both the snake_case and camelCase variants are listed because callers\n// upstream use different conventions.\nconst STRIPPED_KEYS = new Set([\"cloud.public_api_key\", \"cloud.publicApiKey\"]);\n\nfunction stripCloudKeys(\n  obj: Record<string, unknown> | undefined,\n): Record<string, unknown> {\n  if (!obj) return {};\n  const out: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!STRIPPED_KEYS.has(k)) out[k] = v;\n  }\n  return out;\n}\n\n// Pull telemetry_id out of a CopilotKit license token without verifying\n// the signature. The token shape is a standard JWT\n// (`<header>.<payload>.<sig>`) with base64url-encoded segments; the\n// payload is UTF-8 JSON with a telemetry_id accepted by the ingest service.\n//\n// Verification (Ed25519, key rotation, expiry) is the license-verifier\n// package's job. For telemetry attribution we only need the claimed id —\n// the trust model is claim-only on the Lambda side anyway.\n//\n// Exported so TelemetryClient setters can detect unparseable tokens at\n// configuration time and surface a single warning, instead of silently\n// emitting anonymous events on every capture.\nexport function parseTelemetryIdFromLicense(token?: string): string | null {\n  if (!token) return null;\n  const parts = token.split(\".\");\n  if (parts.length !== 3) return null;\n  try {\n    const payload = parts[1];\n    if (!/^[A-Za-z0-9_-]+$/.test(payload) || payload.length % 4 === 1) {\n      return null;\n    }\n\n    let b64 = payload.replace(/-/g, \"+\").replace(/_/g, \"/\");\n    const padding = (4 - (b64.length % 4)) % 4;\n    b64 += \"=\".repeat(padding);\n    const json =\n      typeof Buffer !== \"undefined\"\n        ? Buffer.from(b64, \"base64\").toString(\"utf8\")\n        : new TextDecoder().decode(\n            Uint8Array.from(atob(b64), (character) => character.charCodeAt(0)),\n          );\n    const decoded = JSON.parse(json) as { telemetry_id?: unknown };\n    const telemetryId =\n      typeof decoded.telemetry_id === \"string\"\n        ? decoded.telemetry_id\n        : undefined;\n    return firstNonBlankTelemetryId(telemetryId) ?? null;\n  } catch {\n    return null;\n  }\n}\n\n// Parse the telemetry_id from a license token AND emit the rollout smoke\n// signal if the parse returned null. Returning the parsed id lets callers\n// cache it in one step (avoiding a second parseTelemetryIdFromLicense\n// pass) while keeping the warn text in lockstep between v1 (shared) and\n// v2 (runtime) TelemetryClient.setLicenseToken.\nexport function parseAndWarnTelemetryId(licenseToken: string): string | null {\n  const telemetryId = parseTelemetryIdFromLicense(licenseToken);\n  if (!telemetryId) {\n    console.warn(\n      \"[CopilotKit] License token did not yield a telemetry_id; telemetry events will be sent anonymously.\",\n    );\n  }\n  return telemetryId;\n}\n\nexport async function send(opts: LambdaSendOptions): Promise<void> {\n  try {\n    const body = JSON.stringify({\n      event: opts.event,\n      properties: stripCloudKeys(opts.properties),\n      global_properties: stripCloudKeys(opts.globalProperties),\n      package: {\n        name: opts.packageName,\n        version: opts.packageVersion,\n      },\n      ts: Math.floor(Date.now() / 1000),\n    });\n\n    const telemetryId =\n      firstNonBlankTelemetryId(opts.telemetryId) ??\n      parseTelemetryIdFromLicense(opts.licenseToken);\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      \"User-Agent\": opts.packageName\n        ? `CopilotKit-Runtime/${opts.packageVersion ?? \"unknown\"} (${opts.packageName})`\n        : \"CopilotKit-Runtime\",\n    };\n    if (telemetryId) {\n      headers[\"X-CopilotKit-Telemetry-Id\"] = telemetryId;\n    }\n\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);\n    try {\n      await fetch(TELEMETRY_SINK_URL, {\n        method: \"POST\",\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  } catch {\n    // Silent failure — telemetry must not break the application.\n  }\n}\n\nexport const lambdaClient = { send };\n"],"mappings":";;AA2BA,MAAM,qBACH,OAAO,YAAY,eAAe,QAAQ,KAAK,4BAChD;AAEF,MAAM,mBAAmB;AACzB,MAAM,uBAAuB;;;;;;;;;;;AA2B7B,SAAgB,yBACd,GAAG,YACiB;AACpB,MAAK,MAAM,aAAa,YAAY;AAClC,MAAI,cAAc,OAChB;EAGF,MAAM,aAAa,UAAU,QAAQ,oBAAoB,GAAG;AAC5D,MAAI,qBAAqB,KAAK,WAAW,CACvC,QAAO;;;AAWb,MAAM,gBAAgB,IAAI,IAAI,CAAC,wBAAwB,qBAAqB,CAAC;AAE7E,SAAS,eACP,KACyB;AACzB,KAAI,CAAC,IAAK,QAAO,EAAE;CACnB,MAAM,MAA+B,EAAE;AACvC,MAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,IAAI,CACtC,KAAI,CAAC,cAAc,IAAI,EAAE,CAAE,KAAI,KAAK;AAEtC,QAAO;;AAeT,SAAgB,4BAA4B,OAA+B;AACzE,KAAI,CAAC,MAAO,QAAO;CACnB,MAAM,QAAQ,MAAM,MAAM,IAAI;AAC9B,KAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,KAAI;EACF,MAAM,UAAU,MAAM;AACtB,MAAI,CAAC,mBAAmB,KAAK,QAAQ,IAAI,QAAQ,SAAS,MAAM,EAC9D,QAAO;EAGT,IAAI,MAAM,QAAQ,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,IAAI;EACvD,MAAM,WAAW,IAAK,IAAI,SAAS,KAAM;AACzC,SAAO,IAAI,OAAO,QAAQ;EAC1B,MAAM,OACJ,OAAO,WAAW,cACd,OAAO,KAAK,KAAK,SAAS,CAAC,SAAS,OAAO,GAC3C,IAAI,aAAa,CAAC,OAChB,WAAW,KAAK,KAAK,IAAI,GAAG,cAAc,UAAU,WAAW,EAAE,CAAC,CACnE;EACP,MAAM,UAAU,KAAK,MAAM,KAAK;AAKhC,SAAO,yBAHL,OAAO,QAAQ,iBAAiB,WAC5B,QAAQ,eACR,OACsC,IAAI;SAC1C;AACN,SAAO;;;AASX,SAAgB,wBAAwB,cAAqC;CAC3E,MAAM,cAAc,4BAA4B,aAAa;AAC7D,KAAI,CAAC,YACH,SAAQ,KACN,sGACD;AAEH,QAAO;;AAGT,eAAsB,KAAK,MAAwC;AACjE,KAAI;EACF,MAAM,OAAO,KAAK,UAAU;GAC1B,OAAO,KAAK;GACZ,YAAY,eAAe,KAAK,WAAW;GAC3C,mBAAmB,eAAe,KAAK,iBAAiB;GACxD,SAAS;IACP,MAAM,KAAK;IACX,SAAS,KAAK;IACf;GACD,IAAI,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;GAClC,CAAC;EAEF,MAAM,cACJ,yBAAyB,KAAK,YAAY,IAC1C,4BAA4B,KAAK,aAAa;EAChD,MAAM,UAAkC;GACtC,gBAAgB;GAChB,cAAc,KAAK,cACf,sBAAsB,KAAK,kBAAkB,UAAU,IAAI,KAAK,YAAY,KAC5E;GACL;AACD,MAAI,YACF,SAAQ,+BAA+B;EAGzC,MAAM,aAAa,IAAI,iBAAiB;EACxC,MAAM,YAAY,iBAAiB,WAAW,OAAO,EAAE,iBAAiB;AACxE,MAAI;AACF,SAAM,MAAM,oBAAoB;IAC9B,QAAQ;IACR;IACA;IACA,QAAQ,WAAW;IACpB,CAAC;YACM;AACR,gBAAa,UAAU;;SAEnB;;AAKV,MAAa,eAAe,EAAE,MAAM"}

package/dist/telemetry/lambda-client.d.cts

@@ -5,8 +5,21 @@ interface LambdaSendOptions {
   globalProperties?: Record<string, unknown>;
   packageName?: string;
   packageVersion?: string;
+  /** Standalone analytics identity, resolved before any legacy license claim. */
+  telemetryId?: string;
   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
+ */
+declare function firstNonBlankTelemetryId(...candidates: ReadonlyArray<string | undefined>): string | undefined;
 declare function parseTelemetryIdFromLicense(token?: string): string | null;
 declare function parseAndWarnTelemetryId(licenseToken: string): string | null;
 declare function send(opts: LambdaSendOptions): Promise<void>;
@@ -14,5 +27,5 @@ declare const lambdaClient: {
   send: typeof send;
 };
 //#endregion
-export { LambdaSendOptions, lambdaClient, parseAndWarnTelemetryId, parseTelemetryIdFromLicense };
+export { LambdaSendOptions, firstNonBlankTelemetryId, lambdaClient, parseAndWarnTelemetryId, parseTelemetryIdFromLicense };
 //# sourceMappingURL=lambda-client.d.cts.map

package/dist/telemetry/lambda-client.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"lambda-client.d.cts","names":[],"sources":["../../src/telemetry/lambda-client.ts"],"mappings":";UAiCiB,iBAAA;EACf,KAAA;EACA,UAAA,GAAa,MAAA;EACb,gBAAA,GAAmB,MAAA;EACnB,WAAA;EACA,cAAA;EAKA,YAAA;AAAA;AAAA,iBAgCc,2BAAA,CAA4B,KAAA;AAAA,iBA0B5B,uBAAA,CAAwB,YAAA;AAAA,iBAUlB,IAAA,CAAK,IAAA,EAAM,iBAAA,GAAoB,OAAA;AAAA,cAyCxC,YAAA;eAAuB,IAAA;AAAA"}
+{"version":3,"file":"lambda-client.d.cts","names":[],"sources":["../../src/telemetry/lambda-client.ts"],"mappings":";UAkCiB,iBAAA;EACf,KAAA;EACA,UAAA,GAAa,MAAA;EACb,gBAAA,GAAmB,MAAA;EACnB,WAAA;EACA,cAAA;EAHA;EAKA,WAAA;EAKA,YAAA;AAAA;;;;;;;AAaF;;;;iBAAgB,wBAAA,CAAA,GACX,UAAA,EAAY,aAAA;AAAA,iBA6CD,2BAAA,CAA4B,KAAA;AAAA,iBAmC5B,uBAAA,CAAwB,YAAA;AAAA,iBAUlB,IAAA,CAAK,IAAA,EAAM,iBAAA,GAAoB,OAAA;AAAA,cA2CxC,YAAA;eAAuB,IAAA;AAAA"}

package/dist/telemetry/lambda-client.d.mts

@@ -5,8 +5,21 @@ interface LambdaSendOptions {
   globalProperties?: Record<string, unknown>;
   packageName?: string;
   packageVersion?: string;
+  /** Standalone analytics identity, resolved before any legacy license claim. */
+  telemetryId?: string;
   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
+ */
+declare function firstNonBlankTelemetryId(...candidates: ReadonlyArray<string | undefined>): string | undefined;
 declare function parseTelemetryIdFromLicense(token?: string): string | null;
 declare function parseAndWarnTelemetryId(licenseToken: string): string | null;
 declare function send(opts: LambdaSendOptions): Promise<void>;
@@ -14,5 +27,5 @@ declare const lambdaClient: {
   send: typeof send;
 };
 //#endregion
-export { LambdaSendOptions, lambdaClient, parseAndWarnTelemetryId, parseTelemetryIdFromLicense };
+export { LambdaSendOptions, firstNonBlankTelemetryId, lambdaClient, parseAndWarnTelemetryId, parseTelemetryIdFromLicense };
 //# sourceMappingURL=lambda-client.d.mts.map

package/dist/telemetry/lambda-client.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"lambda-client.d.mts","names":[],"sources":["../../src/telemetry/lambda-client.ts"],"mappings":";UAiCiB,iBAAA;EACf,KAAA;EACA,UAAA,GAAa,MAAA;EACb,gBAAA,GAAmB,MAAA;EACnB,WAAA;EACA,cAAA;EAKA,YAAA;AAAA;AAAA,iBAgCc,2BAAA,CAA4B,KAAA;AAAA,iBA0B5B,uBAAA,CAAwB,YAAA;AAAA,iBAUlB,IAAA,CAAK,IAAA,EAAM,iBAAA,GAAoB,OAAA;AAAA,cAyCxC,YAAA;eAAuB,IAAA;AAAA"}
+{"version":3,"file":"lambda-client.d.mts","names":[],"sources":["../../src/telemetry/lambda-client.ts"],"mappings":";UAkCiB,iBAAA;EACf,KAAA;EACA,UAAA,GAAa,MAAA;EACb,gBAAA,GAAmB,MAAA;EACnB,WAAA;EACA,cAAA;EAHA;EAKA,WAAA;EAKA,YAAA;AAAA;;;;;;;AAaF;;;;iBAAgB,wBAAA,CAAA,GACX,UAAA,EAAY,aAAA;AAAA,iBA6CD,2BAAA,CAA4B,KAAA;AAAA,iBAmC5B,uBAAA,CAAwB,YAAA;AAAA,iBAUlB,IAAA,CAAK,IAAA,EAAM,iBAAA,GAAoB,OAAA;AAAA,cA2CxC,YAAA;eAAuB,IAAA;AAAA"}

package/dist/telemetry/lambda-client.mjs

@@ -1,6 +1,24 @@
 //#region src/telemetry/lambda-client.ts
 const TELEMETRY_SINK_URL = typeof process !== "undefined" && process.env?.COPILOTKIT_TELEMETRY_URL || "https://telemetry.copilotkit.ai/ingest";
 const FETCH_TIMEOUT_MS = 3e3;
+const TELEMETRY_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+/**
+* 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
+*/
+function firstNonBlankTelemetryId(...candidates) {
+	for (const candidate of candidates) {
+		if (candidate === void 0) continue;
+		const normalized = candidate.replace(/^[\t ]+|[\t ]+$/g, "");
+		if (TELEMETRY_ID_PATTERN.test(normalized)) return normalized;
+	}
+}
 const STRIPPED_KEYS = new Set(["cloud.public_api_key", "cloud.publicApiKey"]);
 function stripCloudKeys(obj) {
 	if (!obj) return {};
@@ -13,12 +31,14 @@ function parseTelemetryIdFromLicense(token) {
 	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");
+		const json = 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);
-		return typeof decoded.telemetry_id === "string" ? decoded.telemetry_id : null;
+		return firstNonBlankTelemetryId(typeof decoded.telemetry_id === "string" ? decoded.telemetry_id : void 0) ?? null;
 	} catch {
 		return null;
 	}
@@ -40,7 +60,7 @@ async function send(opts) {
 			},
 			ts: Math.floor(Date.now() / 1e3)
 		});
-		const telemetryId = parseTelemetryIdFromLicense(opts.licenseToken);
+		const telemetryId = firstNonBlankTelemetryId(opts.telemetryId) ?? parseTelemetryIdFromLicense(opts.licenseToken);
 		const headers = {
 			"Content-Type": "application/json",
 			"User-Agent": opts.packageName ? `CopilotKit-Runtime/${opts.packageVersion ?? "unknown"} (${opts.packageName})` : "CopilotKit-Runtime"
@@ -63,5 +83,5 @@ async function send(opts) {
 const lambdaClient = { send };
 
 //#endregion
-export { lambdaClient, parseAndWarnTelemetryId, parseTelemetryIdFromLicense };
+export { firstNonBlankTelemetryId, lambdaClient, parseAndWarnTelemetryId, parseTelemetryIdFromLicense };
 //# sourceMappingURL=lambda-client.mjs.map

package/dist/telemetry/lambda-client.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"lambda-client.mjs","names":[],"sources":["../../src/telemetry/lambda-client.ts"],"sourcesContent":["// Telemetry sink client.\n//\n// Posts events to a CopilotKit-controlled telemetry-sink endpoint, which\n// fans out to Scarf, Reo, and any future destinations. Replaces the direct\n// per-vendor calls (scarf-client.ts) so that vendor changes don't require\n// SDK releases and so that downstream services we don't want exposed to\n// OSS readers (e.g. the email-enrichment service backing Reo) stay\n// private.\n//\n// Two attribution modes:\n//   - Identified: a CopilotKit license token is configured. The token is\n//     a JWT (header.payload.sig) whose payload carries `telemetry_id`.\n//     The SDK base64url-decodes the payload — without verifying the\n//     Ed25519 signature, which is the license-verifier's job — and\n//     emits the id via `X-CopilotKit-Telemetry-Id`. The Lambda uses it\n//     to enrich events with the customer's email.\n//   - Anonymous: no license token, or a malformed/non-JWT one. No\n//     telemetry-id header; events still flow, attribution is best-effort\n//     from request-level signals (IP, UA).\n//\n// Note: CopilotCloud customer API keys (`ck_<env>_<id>.<secret>`) are\n// unrelated to telemetry attribution. They flow into Segment / PostHog\n// via the v1 shared TelemetryClient and never reach this code path.\n//\n// Best-effort: every error is swallowed. Telemetry must not break the\n// host application.\n\nconst TELEMETRY_SINK_URL =\n  (typeof process !== \"undefined\" && process.env?.COPILOTKIT_TELEMETRY_URL) ||\n  \"https://telemetry.copilotkit.ai/ingest\";\n\nconst FETCH_TIMEOUT_MS = 3000;\n\nexport interface LambdaSendOptions {\n  event: string;\n  properties?: Record<string, unknown>;\n  globalProperties?: Record<string, unknown>;\n  packageName?: string;\n  packageVersion?: string;\n  // The CopilotKit license token (Ed25519-signed JWT), when one is\n  // configured on the runtime. The sender base64url-decodes the payload\n  // segment to extract `telemetry_id`; missing or malformed tokens\n  // produce an anonymous send.\n  licenseToken?: string;\n}\n\n// These fields aren't used by the telemetry service, so we strip them\n// at the wire boundary rather than rely on every caller to omit them.\n// Both the snake_case and camelCase variants are listed because callers\n// upstream use different conventions.\nconst STRIPPED_KEYS = new Set([\"cloud.public_api_key\", \"cloud.publicApiKey\"]);\n\nfunction stripCloudKeys(\n  obj: Record<string, unknown> | undefined,\n): Record<string, unknown> {\n  if (!obj) return {};\n  const out: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!STRIPPED_KEYS.has(k)) out[k] = v;\n  }\n  return out;\n}\n\n// Pull telemetry_id out of a CopilotKit license token without verifying\n// the signature. The token shape is a standard JWT\n// (`<header>.<payload>.<sig>`) with base64url-encoded segments; the\n// payload is JSON with a `telemetry_id` string field.\n//\n// Verification (Ed25519, key rotation, expiry) is the license-verifier\n// package's job. For telemetry attribution we only need the claimed id —\n// the trust model is claim-only on the Lambda side anyway.\n//\n// Exported so TelemetryClient setters can detect unparseable tokens at\n// configuration time and surface a single warning, instead of silently\n// emitting anonymous events on every capture.\nexport function parseTelemetryIdFromLicense(token?: string): string | null {\n  if (!token) return null;\n  const parts = token.split(\".\");\n  if (parts.length !== 3) return null;\n  try {\n    let b64 = parts[1].replace(/-/g, \"+\").replace(/_/g, \"/\");\n    const padding = (4 - (b64.length % 4)) % 4;\n    b64 += \"=\".repeat(padding);\n    const json =\n      typeof atob === \"function\"\n        ? atob(b64)\n        : Buffer.from(b64, \"base64\").toString(\"utf8\");\n    const decoded = JSON.parse(json) as { telemetry_id?: unknown };\n    return typeof decoded.telemetry_id === \"string\"\n      ? decoded.telemetry_id\n      : null;\n  } catch {\n    return null;\n  }\n}\n\n// Parse the telemetry_id from a license token AND emit the rollout smoke\n// signal if the parse returned null. Returning the parsed id lets callers\n// cache it in one step (avoiding a second parseTelemetryIdFromLicense\n// pass) while keeping the warn text in lockstep between v1 (shared) and\n// v2 (runtime) TelemetryClient.setLicenseToken.\nexport function parseAndWarnTelemetryId(licenseToken: string): string | null {\n  const telemetryId = parseTelemetryIdFromLicense(licenseToken);\n  if (!telemetryId) {\n    console.warn(\n      \"[CopilotKit] License token did not yield a telemetry_id; telemetry events will be sent anonymously.\",\n    );\n  }\n  return telemetryId;\n}\n\nexport async function send(opts: LambdaSendOptions): Promise<void> {\n  try {\n    const body = JSON.stringify({\n      event: opts.event,\n      properties: stripCloudKeys(opts.properties),\n      global_properties: stripCloudKeys(opts.globalProperties),\n      package: {\n        name: opts.packageName,\n        version: opts.packageVersion,\n      },\n      ts: Math.floor(Date.now() / 1000),\n    });\n\n    const telemetryId = parseTelemetryIdFromLicense(opts.licenseToken);\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      \"User-Agent\": opts.packageName\n        ? `CopilotKit-Runtime/${opts.packageVersion ?? \"unknown\"} (${opts.packageName})`\n        : \"CopilotKit-Runtime\",\n    };\n    if (telemetryId) {\n      headers[\"X-CopilotKit-Telemetry-Id\"] = telemetryId;\n    }\n\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);\n    try {\n      await fetch(TELEMETRY_SINK_URL, {\n        method: \"POST\",\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  } catch {\n    // Silent failure — telemetry must not break the application.\n  }\n}\n\nexport const lambdaClient = { send };\n"],"mappings":";AA2BA,MAAM,qBACH,OAAO,YAAY,eAAe,QAAQ,KAAK,4BAChD;AAEF,MAAM,mBAAmB;AAmBzB,MAAM,gBAAgB,IAAI,IAAI,CAAC,wBAAwB,qBAAqB,CAAC;AAE7E,SAAS,eACP,KACyB;AACzB,KAAI,CAAC,IAAK,QAAO,EAAE;CACnB,MAAM,MAA+B,EAAE;AACvC,MAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,IAAI,CACtC,KAAI,CAAC,cAAc,IAAI,EAAE,CAAE,KAAI,KAAK;AAEtC,QAAO;;AAeT,SAAgB,4BAA4B,OAA+B;AACzE,KAAI,CAAC,MAAO,QAAO;CACnB,MAAM,QAAQ,MAAM,MAAM,IAAI;AAC9B,KAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,KAAI;EACF,IAAI,MAAM,MAAM,GAAG,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,IAAI;EACxD,MAAM,WAAW,IAAK,IAAI,SAAS,KAAM;AACzC,SAAO,IAAI,OAAO,QAAQ;EAC1B,MAAM,OACJ,OAAO,SAAS,aACZ,KAAK,IAAI,GACT,OAAO,KAAK,KAAK,SAAS,CAAC,SAAS,OAAO;EACjD,MAAM,UAAU,KAAK,MAAM,KAAK;AAChC,SAAO,OAAO,QAAQ,iBAAiB,WACnC,QAAQ,eACR;SACE;AACN,SAAO;;;AASX,SAAgB,wBAAwB,cAAqC;CAC3E,MAAM,cAAc,4BAA4B,aAAa;AAC7D,KAAI,CAAC,YACH,SAAQ,KACN,sGACD;AAEH,QAAO;;AAGT,eAAsB,KAAK,MAAwC;AACjE,KAAI;EACF,MAAM,OAAO,KAAK,UAAU;GAC1B,OAAO,KAAK;GACZ,YAAY,eAAe,KAAK,WAAW;GAC3C,mBAAmB,eAAe,KAAK,iBAAiB;GACxD,SAAS;IACP,MAAM,KAAK;IACX,SAAS,KAAK;IACf;GACD,IAAI,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;GAClC,CAAC;EAEF,MAAM,cAAc,4BAA4B,KAAK,aAAa;EAClE,MAAM,UAAkC;GACtC,gBAAgB;GAChB,cAAc,KAAK,cACf,sBAAsB,KAAK,kBAAkB,UAAU,IAAI,KAAK,YAAY,KAC5E;GACL;AACD,MAAI,YACF,SAAQ,+BAA+B;EAGzC,MAAM,aAAa,IAAI,iBAAiB;EACxC,MAAM,YAAY,iBAAiB,WAAW,OAAO,EAAE,iBAAiB;AACxE,MAAI;AACF,SAAM,MAAM,oBAAoB;IAC9B,QAAQ;IACR;IACA;IACA,QAAQ,WAAW;IACpB,CAAC;YACM;AACR,gBAAa,UAAU;;SAEnB;;AAKV,MAAa,eAAe,EAAE,MAAM"}
+{"version":3,"file":"lambda-client.mjs","names":[],"sources":["../../src/telemetry/lambda-client.ts"],"sourcesContent":["// Telemetry sink client.\n//\n// Posts events to a CopilotKit-controlled telemetry-sink endpoint, which\n// fans out to Scarf, Reo, and any future destinations. Replaces the direct\n// per-vendor calls (scarf-client.ts) so that vendor changes don't require\n// SDK releases and so that downstream services we don't want exposed to\n// OSS readers (e.g. the email-enrichment service backing Reo) stay\n// private.\n//\n// Two attribution modes:\n//   - Identified: a standalone telemetry id or a CopilotKit license token is\n//     configured. Standalone identity takes precedence. License tokens are\n//     JWTs (header.payload.sig) whose payload carries `telemetry_id`; the SDK\n//     base64url-decodes the payload — without verifying the Ed25519 signature,\n//     which is the license-verifier's job. The resolved identity is emitted\n//     only via `X-CopilotKit-Telemetry-Id`.\n//   - Anonymous: no license token, or a malformed/non-JWT one. No\n//     telemetry-id header; events still flow, attribution is best-effort\n//     from request-level signals (IP, UA).\n//\n// Note: CopilotCloud customer API keys (`ck_<env>_<id>.<secret>`) are\n// unrelated to telemetry attribution. They flow into Segment / PostHog\n// via the v1 shared TelemetryClient and never reach this code path.\n//\n// Best-effort: every error is swallowed. Telemetry must not break the\n// host application.\n\nconst TELEMETRY_SINK_URL =\n  (typeof process !== \"undefined\" && process.env?.COPILOTKIT_TELEMETRY_URL) ||\n  \"https://telemetry.copilotkit.ai/ingest\";\n\nconst FETCH_TIMEOUT_MS = 3000;\nconst TELEMETRY_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;\n\nexport interface LambdaSendOptions {\n  event: string;\n  properties?: Record<string, unknown>;\n  globalProperties?: Record<string, unknown>;\n  packageName?: string;\n  packageVersion?: string;\n  /** Standalone analytics identity, resolved before any legacy license claim. */\n  telemetryId?: string;\n  // The CopilotKit license token (Ed25519-signed JWT), when one is\n  // configured on the runtime. The sender base64url-decodes the payload\n  // segment to extract `telemetry_id`; missing or malformed tokens\n  // produce an anonymous send.\n  licenseToken?: string;\n}\n\n/**\n * Return the first telemetry identity accepted by the ingest service.\n *\n * Empty and whitespace-only values are unconfigured placeholders and must not\n * suppress a later identity source. Leading and trailing HTTP spaces and tabs\n * are removed before validation. The ingest service accepts 1 to 128 ASCII\n * letters, digits, underscores, and hyphens.\n *\n * @internal\n */\nexport function firstNonBlankTelemetryId(\n  ...candidates: ReadonlyArray<string | undefined>\n): string | undefined {\n  for (const candidate of candidates) {\n    if (candidate === undefined) {\n      continue;\n    }\n\n    const normalized = candidate.replace(/^[\\t ]+|[\\t ]+$/g, \"\");\n    if (TELEMETRY_ID_PATTERN.test(normalized)) {\n      return normalized;\n    }\n  }\n\n  return undefined;\n}\n\n// These fields aren't used by the telemetry service, so we strip them\n// at the wire boundary rather than rely on every caller to omit them.\n// Both the snake_case and camelCase variants are listed because callers\n// upstream use different conventions.\nconst STRIPPED_KEYS = new Set([\"cloud.public_api_key\", \"cloud.publicApiKey\"]);\n\nfunction stripCloudKeys(\n  obj: Record<string, unknown> | undefined,\n): Record<string, unknown> {\n  if (!obj) return {};\n  const out: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!STRIPPED_KEYS.has(k)) out[k] = v;\n  }\n  return out;\n}\n\n// Pull telemetry_id out of a CopilotKit license token without verifying\n// the signature. The token shape is a standard JWT\n// (`<header>.<payload>.<sig>`) with base64url-encoded segments; the\n// payload is UTF-8 JSON with a telemetry_id accepted by the ingest service.\n//\n// Verification (Ed25519, key rotation, expiry) is the license-verifier\n// package's job. For telemetry attribution we only need the claimed id —\n// the trust model is claim-only on the Lambda side anyway.\n//\n// Exported so TelemetryClient setters can detect unparseable tokens at\n// configuration time and surface a single warning, instead of silently\n// emitting anonymous events on every capture.\nexport function parseTelemetryIdFromLicense(token?: string): string | null {\n  if (!token) return null;\n  const parts = token.split(\".\");\n  if (parts.length !== 3) return null;\n  try {\n    const payload = parts[1];\n    if (!/^[A-Za-z0-9_-]+$/.test(payload) || payload.length % 4 === 1) {\n      return null;\n    }\n\n    let b64 = payload.replace(/-/g, \"+\").replace(/_/g, \"/\");\n    const padding = (4 - (b64.length % 4)) % 4;\n    b64 += \"=\".repeat(padding);\n    const json =\n      typeof Buffer !== \"undefined\"\n        ? Buffer.from(b64, \"base64\").toString(\"utf8\")\n        : new TextDecoder().decode(\n            Uint8Array.from(atob(b64), (character) => character.charCodeAt(0)),\n          );\n    const decoded = JSON.parse(json) as { telemetry_id?: unknown };\n    const telemetryId =\n      typeof decoded.telemetry_id === \"string\"\n        ? decoded.telemetry_id\n        : undefined;\n    return firstNonBlankTelemetryId(telemetryId) ?? null;\n  } catch {\n    return null;\n  }\n}\n\n// Parse the telemetry_id from a license token AND emit the rollout smoke\n// signal if the parse returned null. Returning the parsed id lets callers\n// cache it in one step (avoiding a second parseTelemetryIdFromLicense\n// pass) while keeping the warn text in lockstep between v1 (shared) and\n// v2 (runtime) TelemetryClient.setLicenseToken.\nexport function parseAndWarnTelemetryId(licenseToken: string): string | null {\n  const telemetryId = parseTelemetryIdFromLicense(licenseToken);\n  if (!telemetryId) {\n    console.warn(\n      \"[CopilotKit] License token did not yield a telemetry_id; telemetry events will be sent anonymously.\",\n    );\n  }\n  return telemetryId;\n}\n\nexport async function send(opts: LambdaSendOptions): Promise<void> {\n  try {\n    const body = JSON.stringify({\n      event: opts.event,\n      properties: stripCloudKeys(opts.properties),\n      global_properties: stripCloudKeys(opts.globalProperties),\n      package: {\n        name: opts.packageName,\n        version: opts.packageVersion,\n      },\n      ts: Math.floor(Date.now() / 1000),\n    });\n\n    const telemetryId =\n      firstNonBlankTelemetryId(opts.telemetryId) ??\n      parseTelemetryIdFromLicense(opts.licenseToken);\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      \"User-Agent\": opts.packageName\n        ? `CopilotKit-Runtime/${opts.packageVersion ?? \"unknown\"} (${opts.packageName})`\n        : \"CopilotKit-Runtime\",\n    };\n    if (telemetryId) {\n      headers[\"X-CopilotKit-Telemetry-Id\"] = telemetryId;\n    }\n\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);\n    try {\n      await fetch(TELEMETRY_SINK_URL, {\n        method: \"POST\",\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  } catch {\n    // Silent failure — telemetry must not break the application.\n  }\n}\n\nexport const lambdaClient = { send };\n"],"mappings":";AA2BA,MAAM,qBACH,OAAO,YAAY,eAAe,QAAQ,KAAK,4BAChD;AAEF,MAAM,mBAAmB;AACzB,MAAM,uBAAuB;;;;;;;;;;;AA2B7B,SAAgB,yBACd,GAAG,YACiB;AACpB,MAAK,MAAM,aAAa,YAAY;AAClC,MAAI,cAAc,OAChB;EAGF,MAAM,aAAa,UAAU,QAAQ,oBAAoB,GAAG;AAC5D,MAAI,qBAAqB,KAAK,WAAW,CACvC,QAAO;;;AAWb,MAAM,gBAAgB,IAAI,IAAI,CAAC,wBAAwB,qBAAqB,CAAC;AAE7E,SAAS,eACP,KACyB;AACzB,KAAI,CAAC,IAAK,QAAO,EAAE;CACnB,MAAM,MAA+B,EAAE;AACvC,MAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,IAAI,CACtC,KAAI,CAAC,cAAc,IAAI,EAAE,CAAE,KAAI,KAAK;AAEtC,QAAO;;AAeT,SAAgB,4BAA4B,OAA+B;AACzE,KAAI,CAAC,MAAO,QAAO;CACnB,MAAM,QAAQ,MAAM,MAAM,IAAI;AAC9B,KAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,KAAI;EACF,MAAM,UAAU,MAAM;AACtB,MAAI,CAAC,mBAAmB,KAAK,QAAQ,IAAI,QAAQ,SAAS,MAAM,EAC9D,QAAO;EAGT,IAAI,MAAM,QAAQ,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,IAAI;EACvD,MAAM,WAAW,IAAK,IAAI,SAAS,KAAM;AACzC,SAAO,IAAI,OAAO,QAAQ;EAC1B,MAAM,OACJ,OAAO,WAAW,cACd,OAAO,KAAK,KAAK,SAAS,CAAC,SAAS,OAAO,GAC3C,IAAI,aAAa,CAAC,OAChB,WAAW,KAAK,KAAK,IAAI,GAAG,cAAc,UAAU,WAAW,EAAE,CAAC,CACnE;EACP,MAAM,UAAU,KAAK,MAAM,KAAK;AAKhC,SAAO,yBAHL,OAAO,QAAQ,iBAAiB,WAC5B,QAAQ,eACR,OACsC,IAAI;SAC1C;AACN,SAAO;;;AASX,SAAgB,wBAAwB,cAAqC;CAC3E,MAAM,cAAc,4BAA4B,aAAa;AAC7D,KAAI,CAAC,YACH,SAAQ,KACN,sGACD;AAEH,QAAO;;AAGT,eAAsB,KAAK,MAAwC;AACjE,KAAI;EACF,MAAM,OAAO,KAAK,UAAU;GAC1B,OAAO,KAAK;GACZ,YAAY,eAAe,KAAK,WAAW;GAC3C,mBAAmB,eAAe,KAAK,iBAAiB;GACxD,SAAS;IACP,MAAM,KAAK;IACX,SAAS,KAAK;IACf;GACD,IAAI,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;GAClC,CAAC;EAEF,MAAM,cACJ,yBAAyB,KAAK,YAAY,IAC1C,4BAA4B,KAAK,aAAa;EAChD,MAAM,UAAkC;GACtC,gBAAgB;GAChB,cAAc,KAAK,cACf,sBAAsB,KAAK,kBAAkB,UAAU,IAAI,KAAK,YAAY,KAC5E;GACL;AACD,MAAI,YACF,SAAQ,+BAA+B;EAGzC,MAAM,aAAa,IAAI,iBAAiB;EACxC,MAAM,YAAY,iBAAiB,WAAW,OAAO,EAAE,iBAAiB;AACxE,MAAI;AACF,SAAM,MAAM,oBAAoB;IAC9B,QAAQ;IACR;IACA;IACA,QAAQ,WAAW;IACpB,CAAC;YACM;AACR,gBAAa,UAAU;;SAEnB;;AAKV,MAAa,eAAe,EAAE,MAAM"}

package/dist/telemetry/sampling.cjs

@@ -0,0 +1,28 @@
+
+//#region src/telemetry/sampling.ts
+/** Identifies which client emitted an event. */
+const TELEMETRY_EMITTER_V1 = "v1-shared";
+const TELEMETRY_EMITTER_V2 = "v2-runtime";
+/**
+* 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.
+*/
+function computeSamplingMeta({ telemetryId, sampleRate }) {
+	const identified = Boolean(telemetryId);
+	const effectiveSampleRate = identified ? 1 : sampleRate;
+	return {
+		sampleRate: effectiveSampleRate,
+		sampleRateAdjustmentFactor: 1 - effectiveSampleRate,
+		sampleWeight: 1 / effectiveSampleRate,
+		telemetry_identified: identified
+	};
+}
+
+//#endregion
+exports.TELEMETRY_EMITTER_V1 = TELEMETRY_EMITTER_V1;
+exports.TELEMETRY_EMITTER_V2 = TELEMETRY_EMITTER_V2;
+exports.computeSamplingMeta = computeSamplingMeta;
+//# sourceMappingURL=sampling.cjs.map

package/dist/telemetry/sampling.cjs.map

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

package/dist/telemetry/sampling.d.cts

@@ -0,0 +1,37 @@
+//#region src/telemetry/sampling.d.ts
+/** Identifies which client emitted an event. */
+declare const TELEMETRY_EMITTER_V1 = "v1-shared";
+declare const TELEMETRY_EMITTER_V2 = "v2-runtime";
+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.
+ */
+type TelemetryTransport = "segment" | "lambda";
+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.
+ */
+declare function computeSamplingMeta({
+  telemetryId,
+  sampleRate
+}: {
+  telemetryId: string | null;
+  sampleRate: number;
+}): SamplingMeta;
+//#endregion
+export { SamplingMeta, TELEMETRY_EMITTER_V1, TELEMETRY_EMITTER_V2, TelemetryEmitter, TelemetryTransport, computeSamplingMeta };
+//# sourceMappingURL=sampling.d.cts.map

package/dist/telemetry/sampling.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.cts","names":[],"sources":["../../src/telemetry/sampling.ts"],"mappings":";;cAea,oBAAA;AAAA,cACA,oBAAA;AAAA,KAED,gBAAA,UACD,oBAAA,UACA,oBAAA;;;AAJX;;;KAWY,kBAAA;AAAA,UAEK,YAAA;EAXL;EAaV,UAAA;EACA,0BAAA;EAbS;EAeT,YAAA;EAPU;EASV,oBAAA;AAAA;;;AAPF;;;;;iBAiBgB,mBAAA,CAAA;EACd,WAAA;EACA;AAAA;EAEA,WAAA;EACA,UAAA;AAAA,IACE,YAAA"}

package/dist/telemetry/sampling.d.mts

@@ -0,0 +1,37 @@
+//#region src/telemetry/sampling.d.ts
+/** Identifies which client emitted an event. */
+declare const TELEMETRY_EMITTER_V1 = "v1-shared";
+declare const TELEMETRY_EMITTER_V2 = "v2-runtime";
+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.
+ */
+type TelemetryTransport = "segment" | "lambda";
+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.
+ */
+declare function computeSamplingMeta({
+  telemetryId,
+  sampleRate
+}: {
+  telemetryId: string | null;
+  sampleRate: number;
+}): SamplingMeta;
+//#endregion
+export { SamplingMeta, TELEMETRY_EMITTER_V1, TELEMETRY_EMITTER_V2, TelemetryEmitter, TelemetryTransport, computeSamplingMeta };
+//# sourceMappingURL=sampling.d.mts.map

package/dist/telemetry/sampling.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.mts","names":[],"sources":["../../src/telemetry/sampling.ts"],"mappings":";;cAea,oBAAA;AAAA,cACA,oBAAA;AAAA,KAED,gBAAA,UACD,oBAAA,UACA,oBAAA;;;AAJX;;;KAWY,kBAAA;AAAA,UAEK,YAAA;EAXL;EAaV,UAAA;EACA,0BAAA;EAbS;EAeT,YAAA;EAPU;EASV,oBAAA;AAAA;;;AAPF;;;;;iBAiBgB,mBAAA,CAAA;EACd,WAAA;EACA;AAAA;EAEA,WAAA;EACA,UAAA;AAAA,IACE,YAAA"}

package/dist/telemetry/sampling.mjs

@@ -0,0 +1,25 @@
+//#region src/telemetry/sampling.ts
+/** Identifies which client emitted an event. */
+const TELEMETRY_EMITTER_V1 = "v1-shared";
+const TELEMETRY_EMITTER_V2 = "v2-runtime";
+/**
+* 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.
+*/
+function computeSamplingMeta({ telemetryId, sampleRate }) {
+	const identified = Boolean(telemetryId);
+	const effectiveSampleRate = identified ? 1 : sampleRate;
+	return {
+		sampleRate: effectiveSampleRate,
+		sampleRateAdjustmentFactor: 1 - effectiveSampleRate,
+		sampleWeight: 1 / effectiveSampleRate,
+		telemetry_identified: identified
+	};
+}
+
+//#endregion
+export { TELEMETRY_EMITTER_V1, TELEMETRY_EMITTER_V2, computeSamplingMeta };
+//# sourceMappingURL=sampling.mjs.map

package/dist/telemetry/sampling.mjs.map

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

package/dist/telemetry/telemetry-client.cjs

@@ -1,6 +1,7 @@
 const require_runtime = require('../_virtual/_rolldown/runtime.cjs');
 const require_utils = require('./utils.cjs');
 const require_lambda_client = require('./lambda-client.cjs');
+const require_sampling = require('./sampling.cjs');
 let uuid = require("uuid");
 let _segment_analytics_node = require("@segment/analytics-node");
 
@@ -20,6 +21,7 @@ var TelemetryClient = class {
 		this.cloudConfiguration = null;
 		this.licenseToken = null;
 		this.telemetryId = null;
+		this.licenseTelemetryId = null;
 		this.telemetryDisabled = false;
 		this.sampleRate = .05;
 		this.anonymousId = `anon_${(0, uuid.v4)()}`;
@@ -38,18 +40,28 @@ var TelemetryClient = class {
 		return Math.random() < this.sampleRate;
 	}
 	async capture(event, properties) {
+		return this.captureWithIdentity(event, properties, {
+			telemetryId: this.telemetryId,
+			licenseToken: this.licenseToken,
+			licenseTelemetryId: this.licenseTelemetryId
+		});
+	}
+	async captureWithIdentity(event, properties, identity) {
 		if (this.telemetryDisabled) return;
-		if (!this.telemetryId && !this.shouldSendEvent()) return;
-		const effectiveSampleRate = this.telemetryId ? 1 : this.sampleRate;
-		const samplingMeta = {
-			sampleRate: effectiveSampleRate,
-			sampleRateAdjustmentFactor: 1 - effectiveSampleRate,
-			sampleWeight: 1 / effectiveSampleRate
+		if (!identity.licenseTelemetryId && !this.shouldSendEvent()) return;
+		const eventMeta = {
+			...require_sampling.computeSamplingMeta({
+				telemetryId: identity.licenseTelemetryId,
+				sampleRate: this.sampleRate
+			}),
+			telemetry_emitter: require_sampling.TELEMETRY_EMITTER_V1,
+			telemetry_event_id: (0, uuid.v4)()
 		};
 		const flattenedProperties = require_utils.flattenObject(properties);
 		const propertiesWithGlobal = {
 			...this.globalProperties,
-			...samplingMeta,
+			...eventMeta,
+			telemetry_transport: "segment",
 			...flattenedProperties
 		};
 		const orderedPropertiesWithGlobal = Object.keys(propertiesWithGlobal).sort().reduce((obj, key) => {
@@ -61,11 +73,13 @@ var TelemetryClient = class {
 			properties: flattenedProperties,
 			globalProperties: {
 				...this.globalProperties,
-				...samplingMeta
+				...eventMeta,
+				telemetry_transport: "lambda"
 			},
 			packageName: this.packageName,
 			packageVersion: this.packageVersion,
-			licenseToken: this.licenseToken ?? void 0
+			telemetryId: identity.telemetryId ?? void 0,
+			licenseToken: identity.licenseToken ?? void 0
 		});
 		if (this.segment) this.segment.track({
 			anonymousId: this.anonymousId,
@@ -87,9 +101,56 @@ var TelemetryClient = class {
 			baseUrl: properties.baseUrl
 		} });
 	}
+	/**
+	* Atomically configure standalone, legacy, or anonymous telemetry identity.
+	*
+	* A standalone id takes transport precedence over a supplied legacy license
+	* token, but only a license-derived id grants sampling authority. Neither
+	* value is added to event properties.
+	*
+	* @param identity - One standalone id, one legacy license token, or neither.
+	*/
+	setTelemetryIdentity(identity) {
+		const resolvedIdentity = this.resolveTelemetryIdentity(identity);
+		this.telemetryId = resolvedIdentity.telemetryId;
+		this.licenseToken = resolvedIdentity.licenseToken;
+		this.licenseTelemetryId = resolvedIdentity.licenseTelemetryId;
+	}
+	/**
+	* Configure legacy license-derived telemetry identity.
+	*
+	* @param licenseToken - License token whose telemetry claim identifies sends.
+	*/
 	setLicenseToken(licenseToken) {
-		this.licenseToken = licenseToken;
-		this.telemetryId = require_lambda_client.parseAndWarnTelemetryId(licenseToken);
+		this.setTelemetryIdentity({ licenseToken });
+	}
+	/**
+	* Create an immutable capture scope for one runtime.
+	*
+	* The scope shares this client's sinks, process-wide opt-out, global
+	* properties, and sampling settings, but snapshots transport identity and
+	* license-derived sampling authority. Constructing another runtime cannot
+	* rewrite an existing scope.
+	*
+	* @param identity - The runtime's construction-time telemetry identity.
+	* @returns A capture-only client bound to that identity.
+	*/
+	createScope(identity) {
+		const resolvedIdentity = this.resolveTelemetryIdentity(identity);
+		return { capture: (event, properties) => this.captureWithIdentity(event, properties, resolvedIdentity) };
+	}
+	resolveTelemetryIdentity(identity) {
+		const telemetryId = require_lambda_client.firstNonBlankTelemetryId(identity.telemetryId);
+		if (telemetryId !== void 0) return {
+			telemetryId,
+			licenseToken: null,
+			licenseTelemetryId: null
+		};
+		return {
+			telemetryId: null,
+			licenseToken: identity.licenseToken ?? null,
+			licenseTelemetryId: identity.licenseToken ? require_lambda_client.parseAndWarnTelemetryId(identity.licenseToken) : null
+		};
 	}
 	setSampleRate(sampleRate) {
 		let _sampleRate;