@copilotkit/shared 1.69.3 → 1.70.1

package/src/telemetry/telemetry-client.ts

@@ -2,7 +2,12 @@ import { Analytics } from "@segment/analytics-node";
 import type { AnalyticsEvents } from "./events";
 import { flattenObject } from "./utils";
 import { v4 as uuidv4 } from "uuid";
-import { lambdaClient, parseAndWarnTelemetryId } from "./lambda-client";
+import {
+  firstNonBlankTelemetryId,
+  lambdaClient,
+  parseAndWarnTelemetryId,
+} from "./lambda-client";
+import { computeSamplingMeta, TELEMETRY_EMITTER_V1 } from "./sampling";
 
 /**
  * Checks if telemetry is disabled via environment variables.
@@ -22,6 +27,26 @@ export function isTelemetryDisabled(): boolean {
   );
 }
 
+/** Transport identity and sampling authority resolved for one runtime. */
+export interface TelemetryIdentity {
+  telemetryId?: string;
+  licenseToken?: string;
+}
+
+/** Capture-only telemetry client bound to one runtime identity. */
+export interface TelemetryCapture {
+  capture<K extends keyof AnalyticsEvents>(
+    event: K,
+    properties: AnalyticsEvents[K],
+  ): Promise<void>;
+}
+
+interface ResolvedTelemetryIdentity {
+  telemetryId: string | null;
+  licenseToken: string | null;
+  licenseTelemetryId: string | null;
+}
+
 export class TelemetryClient {
   segment: Analytics | undefined;
   globalProperties: Record<string, any> = {};
@@ -30,11 +55,13 @@ export class TelemetryClient {
   // 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.
+  // Standalone analytics identity. This stays separate from the effective
+  // identity so legacy callers continue sending only their license token to
+  // the Lambda transport.
   private telemetryId: string | null = null;
+  // License-derived identity used only as sampling authority. A standalone
+  // telemetry id remains a transport claim and does not bypass sampleRate.
+  private licenseTelemetryId: string | null = null;
   packageName: string;
   packageVersion: string;
   private telemetryDisabled: boolean = false;
@@ -91,35 +118,55 @@ export class TelemetryClient {
   async capture<K extends keyof AnalyticsEvents>(
     event: K,
     properties: AnalyticsEvents[K],
-  ) {
+  ): Promise<void> {
+    return this.captureWithIdentity(event, properties, {
+      telemetryId: this.telemetryId,
+      licenseToken: this.licenseToken,
+      licenseTelemetryId: this.licenseTelemetryId,
+    });
+  }
+
+  private async captureWithIdentity<K extends keyof AnalyticsEvents>(
+    event: K,
+    properties: AnalyticsEvents[K],
+    identity: ResolvedTelemetryIdentity,
+  ): Promise<void> {
     if (this.telemetryDisabled) {
       return;
     }
 
-    // Anonymous callers (no telemetry_id) are gated by sampleRate.
-    // Identified callers (license token with telemetry_id) always send —
+    // Callers without license-derived sampling authority are gated by
+    // sampleRate. Legacy license tokens 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()) {
+    if (!identity.licenseTelemetryId && !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,
+    // Sampling metadata is computed in ./sampling so this client and the
+    // v2 runtime client can't drift apart again — see the note there.
+    const samplingMeta = computeSamplingMeta({
+      telemetryId: identity.licenseTelemetryId,
+      sampleRate: this.sampleRate,
+    });
+
+    // Everything below travels identically on both copies of this event.
+    // The event id is what makes the dual-write dedupable downstream:
+    // one capture() produces one id, stamped on the lambda copy and the
+    // Segment copy alike, so consumers no longer have to infer the
+    // duplication from $lib or from which fields happen to be present
+    // (OSS-1019).
+    const eventMeta = {
+      ...samplingMeta,
+      telemetry_emitter: TELEMETRY_EMITTER_V1,
+      telemetry_event_id: uuidv4(),
     };
 
     const flattenedProperties = flattenObject(properties);
     const propertiesWithGlobal: Record<string, any> = {
       ...this.globalProperties,
-      ...samplingMeta,
+      ...eventMeta,
+      telemetry_transport: "segment",
       ...flattenedProperties,
     };
     const orderedPropertiesWithGlobal = Object.keys(propertiesWithGlobal)
@@ -135,10 +182,15 @@ export class TelemetryClient {
     await lambdaClient.send({
       event,
       properties: flattenedProperties,
-      globalProperties: { ...this.globalProperties, ...samplingMeta },
+      globalProperties: {
+        ...this.globalProperties,
+        ...eventMeta,
+        telemetry_transport: "lambda",
+      },
       packageName: this.packageName,
       packageVersion: this.packageVersion,
-      licenseToken: this.licenseToken ?? undefined,
+      telemetryId: identity.telemetryId ?? undefined,
+      licenseToken: identity.licenseToken ?? undefined,
     });
 
     if (this.segment) {
@@ -169,12 +221,75 @@ 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.
+  /**
+   * 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: {
+    telemetryId?: string;
+    licenseToken?: string;
+  }): void {
+    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: string) {
-    this.licenseToken = licenseToken;
-    this.telemetryId = 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: TelemetryIdentity): TelemetryCapture {
+    const resolvedIdentity = this.resolveTelemetryIdentity(identity);
+
+    return {
+      capture: <K extends keyof AnalyticsEvents>(
+        event: K,
+        properties: AnalyticsEvents[K],
+      ) => this.captureWithIdentity(event, properties, resolvedIdentity),
+    };
+  }
+
+  private resolveTelemetryIdentity(
+    identity: TelemetryIdentity,
+  ): ResolvedTelemetryIdentity {
+    const telemetryId = firstNonBlankTelemetryId(identity.telemetryId);
+    if (telemetryId !== undefined) {
+      return {
+        telemetryId,
+        licenseToken: null,
+        licenseTelemetryId: null,
+      };
+    }
+
+    return {
+      telemetryId: null,
+      licenseToken: identity.licenseToken ?? null,
+      licenseTelemetryId: identity.licenseToken
+        ? parseAndWarnTelemetryId(identity.licenseToken)
+        : null,
+    };
   }
 
   private setSampleRate(sampleRate: number | undefined) {
@@ -198,8 +313,8 @@ export class TelemetryClient {
 
     this.sampleRate = _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.
+    // sampleWeight) is computed per capture() in ./sampling. Only license-
+    // authorized events get effectiveSampleRate=1; standalone transport
+    // identity stays in the sampled population.
   }
 }

package/src/utils/__tests__/conditions.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect } from "vitest";
+import {
+  executeConditions,
+  Condition,
+  ComparisonCondition,
+  LogicalCondition,
+  ExistenceCondition,
+} from "../conditions";
+
+describe("executeConditions", () => {
+  it("returns true when conditions is empty or undefined", () => {
+    expect(executeConditions({ value: { a: 1 } })).toBe(true);
+    expect(executeConditions({ conditions: [], value: { a: 1 } })).toBe(true);
+  });
+
+  it("treats multiple conditions as an implicit AND", () => {
+    const conditions: Condition[] = [
+      { rule: "EQUALS", path: "a", value: 1 },
+      { rule: "EQUALS", path: "b", value: 2 },
+    ];
+    expect(executeConditions({ conditions, value: { a: 1, b: 2 } })).toBe(true);
+    expect(executeConditions({ conditions, value: { a: 1, b: 3 } })).toBe(false);
+  });
+
+  describe("comparison rules", () => {
+    it("EQUALS and NOT_EQUALS", () => {
+      const eq: ComparisonCondition = { rule: "EQUALS", path: "a", value: 5 };
+      const neq: ComparisonCondition = { rule: "NOT_EQUALS", path: "a", value: 5 };
+      expect(executeConditions({ conditions: [eq], value: { a: 5 } })).toBe(true);
+      expect(executeConditions({ conditions: [eq], value: { a: 6 } })).toBe(false);
+      expect(executeConditions({ conditions: [neq], value: { a: 6 } })).toBe(true);
+      expect(executeConditions({ conditions: [neq], value: { a: 5 } })).toBe(false);
+    });
+
+    it("GREATER_THAN and LESS_THAN", () => {
+      const gt: ComparisonCondition = { rule: "GREATER_THAN", path: "n", value: 10 };
+      const lt: ComparisonCondition = { rule: "LESS_THAN", path: "n", value: 10 };
+      expect(executeConditions({ conditions: [gt], value: { n: 11 } })).toBe(true);
+      expect(executeConditions({ conditions: [gt], value: { n: 10 } })).toBe(false);
+      expect(executeConditions({ conditions: [lt], value: { n: 9 } })).toBe(true);
+      expect(executeConditions({ conditions: [lt], value: { n: 10 } })).toBe(false);
+    });
+
+    it("CONTAINS and NOT_CONTAINS only apply to arrays", () => {
+      const contains: ComparisonCondition = { rule: "CONTAINS", path: "tags", value: "ts" };
+      const notContains: ComparisonCondition = { rule: "NOT_CONTAINS", path: "tags", value: "ts" };
+      expect(
+        executeConditions({ conditions: [contains], value: { tags: ["js", "ts"] } }),
+      ).toBe(true);
+      expect(
+        executeConditions({ conditions: [contains], value: { tags: ["js"] } }),
+      ).toBe(false);
+      expect(
+        executeConditions({ conditions: [notContains], value: { tags: ["js"] } }),
+      ).toBe(true);
+      // non-array target always fails both CONTAINS and NOT_CONTAINS
+      expect(
+        executeConditions({ conditions: [contains], value: { tags: "ts" } }),
+      ).toBe(false);
+      expect(
+        executeConditions({ conditions: [notContains], value: { tags: "ts" } }),
+      ).toBe(false);
+    });
+
+    it("MATCHES uses the value as a regular expression", () => {
+      const matches: ComparisonCondition = { rule: "MATCHES", path: "code", value: "^CK-[0-9]+$" };
+      expect(executeConditions({ conditions: [matches], value: { code: "CK-123" } })).toBe(true);
+      expect(executeConditions({ conditions: [matches], value: { code: "nope" } })).toBe(false);
+    });
+
+    it("STARTS_WITH and ENDS_WITH", () => {
+      const sw: ComparisonCondition = { rule: "STARTS_WITH", path: "s", value: "foo" };
+      const ew: ComparisonCondition = { rule: "ENDS_WITH", path: "s", value: "bar" };
+      expect(executeConditions({ conditions: [sw], value: { s: "foobar" } })).toBe(true);
+      expect(executeConditions({ conditions: [sw], value: { s: "barfoo" } })).toBe(false);
+      expect(executeConditions({ conditions: [ew], value: { s: "foobar" } })).toBe(true);
+      expect(executeConditions({ conditions: [ew], value: { s: "barfoo" } })).toBe(false);
+    });
+  });
+
+  describe("existence rules", () => {
+    it("EXISTS passes only for defined non-null values", () => {
+      const exists: ExistenceCondition = { rule: "EXISTS", path: "a" };
+      expect(executeConditions({ conditions: [exists], value: { a: 0 } })).toBe(true);
+      expect(executeConditions({ conditions: [exists], value: { a: "" } })).toBe(true);
+      expect(executeConditions({ conditions: [exists], value: { a: false } })).toBe(true);
+      expect(executeConditions({ conditions: [exists], value: { a: null } })).toBe(false);
+      expect(executeConditions({ conditions: [exists], value: {} })).toBe(false);
+    });
+
+    it("NOT_EXISTS is the inverse of EXISTS", () => {
+      const notExists: ExistenceCondition = { rule: "NOT_EXISTS", path: "a" };
+      expect(executeConditions({ conditions: [notExists], value: { a: 1 } })).toBe(false);
+      expect(executeConditions({ conditions: [notExists], value: { a: null } })).toBe(true);
+      expect(executeConditions({ conditions: [notExists], value: {} })).toBe(true);
+    });
+  });
+
+  describe("logical rules", () => {
+    it("AND requires all nested conditions to pass", () => {
+      const and: LogicalCondition = {
+        rule: "AND",
+        conditions: [
+          { rule: "EQUALS", path: "a", value: 1 },
+          { rule: "EQUALS", path: "b", value: 2 },
+        ],
+      };
+      expect(executeConditions({ conditions: [and], value: { a: 1, b: 2 } })).toBe(true);
+      expect(executeConditions({ conditions: [and], value: { a: 1, b: 3 } })).toBe(false);
+    });
+
+    it("OR passes when any nested condition passes", () => {
+      const or: LogicalCondition = {
+        rule: "OR",
+        conditions: [
+          { rule: "EQUALS", path: "a", value: 1 },
+          { rule: "EQUALS", path: "b", value: 2 },
+        ],
+      };
+      expect(executeConditions({ conditions: [or], value: { a: 9, b: 2 } })).toBe(true);
+      expect(executeConditions({ conditions: [or], value: { a: 9, b: 9 } })).toBe(false);
+    });
+
+    it("NOT inverts the AND of nested conditions", () => {
+      const notAll: LogicalCondition = {
+        rule: "NOT",
+        conditions: [
+          { rule: "EQUALS", path: "a", value: 1 },
+          { rule: "EQUALS", path: "b", value: 2 },
+        ],
+      };
+      // both true → NOT(AND) = false
+      expect(executeConditions({ conditions: [notAll], value: { a: 1, b: 2 } })).toBe(false);
+      // one false → NOT(AND) = true
+      expect(executeConditions({ conditions: [notAll], value: { a: 1, b: 3 } })).toBe(true);
+    });
+  });
+
+  describe("path resolution", () => {
+    it("resolves nested dot paths", () => {
+      const cond: ComparisonCondition = { rule: "EQUALS", path: "user.profile.age", value: 30 };
+      expect(
+        executeConditions({ conditions: [cond], value: { user: { profile: { age: 30 } } } }),
+      ).toBe(true);
+      expect(
+        executeConditions({ conditions: [cond], value: { user: { profile: { age: 31 } } } }),
+      ).toBe(false);
+    });
+
+    it("returns false for a missing nested path (undefined target)", () => {
+      const eq: ComparisonCondition = { rule: "EQUALS", path: "a.b.c", value: 1 };
+      expect(executeConditions({ conditions: [eq], value: {} })).toBe(false);
+    });
+
+    it("uses the whole value when no path is given", () => {
+      const eq: ComparisonCondition = { rule: "EQUALS", value: 42 };
+      expect(executeConditions({ conditions: [eq], value: 42 })).toBe(true);
+      expect(executeConditions({ conditions: [eq], value: 43 })).toBe(false);
+    });
+  });
+});

package/src/utils/console-styling.ts

@@ -53,15 +53,15 @@ export function logCopilotKitPlatformMessage() {
   console.log(
     `%cCopilotKit Warning%c
 
-useCopilotChatHeadless_c provides full compatibility with CopilotKit's newly released Headless UI feature set. To enable this premium feature, add your public license key, available for free at:
+useCopilotChatHeadless_c provides full compatibility with CopilotKit's newly released Headless UI feature set. Headless UI requires a CopilotKit Intelligence license key, available for free at:
 
 %chttps://dashboard.operations.copilotkit.ai%c
 
 Alternatively, useCopilotChat is available for basic programmatic control, and does not require a license key.
 
-To learn more about premium features, read the documentation here:
+To learn more about CopilotKit Intelligence, read the documentation here:
 
-%chttps://docs.copilotkit.ai/premium/overview%c`,
+%chttps://docs.copilotkit.ai/intelligence/overview%c`,
     ConsoleStyles.header,
     ConsoleStyles.body,
     ConsoleStyles.cta,

package/src/utils/types.ts

@@ -46,6 +46,55 @@ export type RuntimeLicenseStatus =
   | "invalid"
   | "unknown";
 
+/** Runtime entitlement authority resolved by a managed or self-hosted backend. */
+interface RuntimeEntitlement {
+  /** Whether the resolved entitlement currently grants product access. */
+  active: boolean;
+  /** Deployment authority that produced this entitlement. */
+  source: "managedOrgSubscription" | "selfHostedDeploymentLicense";
+  /** Boolean feature grants keyed by stable feature id. */
+  features: Record<string, boolean>;
+  /** Numeric limits keyed by stable feature id. */
+  limits: Record<string, number>;
+  /** Optional catalog plan code supplied by the entitlement authority. */
+  planCode?: string;
+  /** Optional lower-level source metadata supplied by the authority. */
+  entitlementSource?: string;
+}
+
+/** Public diagnostic returned when Runtime entitlement resolution is not ready. */
+interface RuntimeEntitlementError {
+  /** Stable backend or SDK error code. */
+  code: string;
+  /** Safe human-readable diagnostic. */
+  message: string;
+  /** Whether a later resolution attempt may succeed without reconfiguration. */
+  retryable: boolean;
+  /** Optional originating request correlation id. */
+  requestId?: string;
+  /** Optional originating trace correlation id. */
+  traceId?: string;
+}
+
+/** Successfully resolved Runtime entitlement response. */
+interface RuntimeEntitlementReadyResponse {
+  status: "ready";
+  entitlement: RuntimeEntitlement;
+  error?: never;
+}
+
+/** Structured non-ready Runtime entitlement response. */
+interface RuntimeEntitlementErrorResponse {
+  status: "degraded" | "misconfigured" | "unavailable";
+  entitlement?: never;
+  error: RuntimeEntitlementError;
+}
+
+/** Final structured Runtime entitlement response exposed through `/info`. */
+export type RuntimeEntitlementResponse =
+  | RuntimeEntitlementReadyResponse
+  | RuntimeEntitlementErrorResponse;
+
 export interface A2UIRuntimeInfo {
   enabled: boolean;
   /**
@@ -77,6 +126,9 @@ export interface RuntimeInfo {
   a2uiEnabled?: boolean;
   a2ui?: A2UIRuntimeInfo;
   openGenerativeUIEnabled?: boolean;
+  /** Structured Runtime-level entitlement authority, when advertised. */
+  runtimeEntitlements?: RuntimeEntitlementResponse;
+  /** Legacy compatibility diagnostic retained for older Core/Inspector clients. */
   licenseStatus?: RuntimeLicenseStatus;
   telemetryDisabled?: boolean;
 }