@copilotkit/shared 1.69.2 → 1.70.0

package/dist/utils/types.d.cts

@@ -28,6 +28,48 @@ interface ThreadEndpointRuntimeInfo {
   realtimeMetadata: boolean;
 }
 type RuntimeLicenseStatus = "valid" | "none" | "expired" | "expiring" | "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`. */
+type RuntimeEntitlementResponse = RuntimeEntitlementReadyResponse | RuntimeEntitlementErrorResponse;
 interface A2UIRuntimeInfo {
   enabled: boolean;
   /**
@@ -58,9 +100,12 @@ 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;
 }
 //#endregion
-export { A2UIRuntimeInfo, AgentDescription, IntelligenceRuntimeInfo, MaybePromise, NonEmptyRecord, RUNTIME_MODE_INTELLIGENCE, RUNTIME_MODE_SSE, RuntimeInfo, RuntimeLicenseStatus, RuntimeMode, ThreadEndpointRuntimeInfo };
+export { A2UIRuntimeInfo, AgentDescription, IntelligenceRuntimeInfo, MaybePromise, NonEmptyRecord, RUNTIME_MODE_INTELLIGENCE, RUNTIME_MODE_SSE, RuntimeEntitlementResponse, RuntimeInfo, RuntimeLicenseStatus, RuntimeMode, ThreadEndpointRuntimeInfo };
 //# sourceMappingURL=types.d.cts.map

package/dist/utils/types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/utils/types.ts"],"mappings":";;;KAEY,YAAA,MAAkB,CAAA,GAAI,WAAA,CAAY,CAAA;;AAA9C;;KAKY,cAAA,MACV,CAAA,SAAU,MAAA,0BACA,CAAA,yBAEJ,CAAA;;;;UAMS,gBAAA;EACf,IAAA;EACA,SAAA;EACA,WAAA;EACA,YAAA,GAAe,iBAAA;AAAA;AAAA,KAGL,WAAA;AAAA,cAEC,gBAAA;AAAA,cACA,yBAAA;AAAA,UAEI,uBAAA;EACf,KAAA;AAAA;AAAA,UAGe,yBAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA;EACA,gBAAA;AAAA;AAAA,KAGU,oBAAA;AAAA,UAQK,eAAA;EACf,OAAA;EAtCM;;;AAMR;EAqCE,MAAA;AAAA;AAAA,UAGe,WAAA;EACf,OAAA;EACA,MAAA,EAAQ,MAAA,SAAe,gBAAA;EACvB,6BAAA;EACA,IAAA,EAAM,WAAA;EACN,YAAA,GAAe,uBAAA;EACf,eAAA,GAAkB,yBAAA;EA1Cc;EA4ChC,iBAAA;EAzCqB;;;;AAEvB;EA6CE,WAAA;;;;AA5CF;EAiDE,WAAA;EACA,IAAA,GAAO,eAAA;EACP,uBAAA;EACA,aAAA,GAAgB,oBAAA;EAChB,iBAAA;AAAA"}
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/utils/types.ts"],"mappings":";;;KAEY,YAAA,MAAkB,CAAA,GAAI,WAAA,CAAY,CAAA;;AAA9C;;KAKY,cAAA,MACV,CAAA,SAAU,MAAA,0BACA,CAAA,yBAEJ,CAAA;;;;UAMS,gBAAA;EACf,IAAA;EACA,SAAA;EACA,WAAA;EACA,YAAA,GAAe,iBAAA;AAAA;AAAA,KAGL,WAAA;AAAA,cAEC,gBAAA;AAAA,cACA,yBAAA;AAAA,UAEI,uBAAA;EACf,KAAA;AAAA;AAAA,UAGe,yBAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA;EACA,gBAAA;AAAA;AAAA,KAGU,oBAAA;;UASF,kBAAA;EAtCF;EAwCN,MAAA;EAxCO;EA0CP,MAAA;EApC+B;EAsC/B,QAAA,EAAU,MAAA;EAlCsB;EAoChC,MAAA,EAAQ,MAAA;EAtCR;EAwCA,QAAA;EAtCA;EAwCA,iBAAA;AAAA;;UAIQ,uBAAA;EAzCa;EA2CrB,IAAA;EA3CqB;EA6CrB,OAAA;EA3CW;EA6CX,SAAA;;EAEA,SAAA;EA/C4C;EAiD5C,OAAA;AAAA;;UAIQ,+BAAA;EACR,MAAA;EACA,WAAA,EAAa,kBAAA;EACb,KAAA;AAAA;;UAIQ,+BAAA;EACR,MAAA;EACA,WAAA;EACA,KAAA,EAAO,uBAAA;AAAA;;KAIG,0BAAA,GACR,+BAAA,GACA,+BAAA;AAAA,UAEa,eAAA;EACf,OAAA;EA7DgB;;AAGlB;;EA+DE,MAAA;AAAA;AAAA,UAGe,WAAA;EACf,OAAA;EACA,MAAA,EAAQ,MAAA,SAAe,gBAAA;EACvB,6BAAA;EACA,IAAA,EAAM,WAAA;EACN,YAAA,GAAe,uBAAA;EACf,eAAA,GAAkB,yBAAA;EAzDlB;EA2DA,iBAAA;EAzDA;;;;;EA+DA,WAAA;EAvDQ;;;;EA4DR,WAAA;EACA,IAAA,GAAO,eAAA;EACP,uBAAA;EAtDA;EAwDA,mBAAA,GAAsB,0BAAA;EAtDf;EAwDP,aAAA,GAAgB,oBAAA;EAChB,iBAAA;AAAA"}

package/dist/utils/types.d.mts

@@ -28,6 +28,48 @@ interface ThreadEndpointRuntimeInfo {
   realtimeMetadata: boolean;
 }
 type RuntimeLicenseStatus = "valid" | "none" | "expired" | "expiring" | "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`. */
+type RuntimeEntitlementResponse = RuntimeEntitlementReadyResponse | RuntimeEntitlementErrorResponse;
 interface A2UIRuntimeInfo {
   enabled: boolean;
   /**
@@ -58,9 +100,12 @@ 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;
 }
 //#endregion
-export { A2UIRuntimeInfo, AgentDescription, IntelligenceRuntimeInfo, MaybePromise, NonEmptyRecord, RUNTIME_MODE_INTELLIGENCE, RUNTIME_MODE_SSE, RuntimeInfo, RuntimeLicenseStatus, RuntimeMode, ThreadEndpointRuntimeInfo };
+export { A2UIRuntimeInfo, AgentDescription, IntelligenceRuntimeInfo, MaybePromise, NonEmptyRecord, RUNTIME_MODE_INTELLIGENCE, RUNTIME_MODE_SSE, RuntimeEntitlementResponse, RuntimeInfo, RuntimeLicenseStatus, RuntimeMode, ThreadEndpointRuntimeInfo };
 //# sourceMappingURL=types.d.mts.map

package/dist/utils/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/utils/types.ts"],"mappings":";;;KAEY,YAAA,MAAkB,CAAA,GAAI,WAAA,CAAY,CAAA;;AAA9C;;KAKY,cAAA,MACV,CAAA,SAAU,MAAA,0BACA,CAAA,yBAEJ,CAAA;;;;UAMS,gBAAA;EACf,IAAA;EACA,SAAA;EACA,WAAA;EACA,YAAA,GAAe,iBAAA;AAAA;AAAA,KAGL,WAAA;AAAA,cAEC,gBAAA;AAAA,cACA,yBAAA;AAAA,UAEI,uBAAA;EACf,KAAA;AAAA;AAAA,UAGe,yBAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA;EACA,gBAAA;AAAA;AAAA,KAGU,oBAAA;AAAA,UAQK,eAAA;EACf,OAAA;EAtCM;;;AAMR;EAqCE,MAAA;AAAA;AAAA,UAGe,WAAA;EACf,OAAA;EACA,MAAA,EAAQ,MAAA,SAAe,gBAAA;EACvB,6BAAA;EACA,IAAA,EAAM,WAAA;EACN,YAAA,GAAe,uBAAA;EACf,eAAA,GAAkB,yBAAA;EA1Cc;EA4ChC,iBAAA;EAzCqB;;;;AAEvB;EA6CE,WAAA;;;;AA5CF;EAiDE,WAAA;EACA,IAAA,GAAO,eAAA;EACP,uBAAA;EACA,aAAA,GAAgB,oBAAA;EAChB,iBAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/utils/types.ts"],"mappings":";;;KAEY,YAAA,MAAkB,CAAA,GAAI,WAAA,CAAY,CAAA;;AAA9C;;KAKY,cAAA,MACV,CAAA,SAAU,MAAA,0BACA,CAAA,yBAEJ,CAAA;;;;UAMS,gBAAA;EACf,IAAA;EACA,SAAA;EACA,WAAA;EACA,YAAA,GAAe,iBAAA;AAAA;AAAA,KAGL,WAAA;AAAA,cAEC,gBAAA;AAAA,cACA,yBAAA;AAAA,UAEI,uBAAA;EACf,KAAA;AAAA;AAAA,UAGe,yBAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA;EACA,gBAAA;AAAA;AAAA,KAGU,oBAAA;;UASF,kBAAA;EAtCF;EAwCN,MAAA;EAxCO;EA0CP,MAAA;EApC+B;EAsC/B,QAAA,EAAU,MAAA;EAlCsB;EAoChC,MAAA,EAAQ,MAAA;EAtCR;EAwCA,QAAA;EAtCA;EAwCA,iBAAA;AAAA;;UAIQ,uBAAA;EAzCa;EA2CrB,IAAA;EA3CqB;EA6CrB,OAAA;EA3CW;EA6CX,SAAA;;EAEA,SAAA;EA/C4C;EAiD5C,OAAA;AAAA;;UAIQ,+BAAA;EACR,MAAA;EACA,WAAA,EAAa,kBAAA;EACb,KAAA;AAAA;;UAIQ,+BAAA;EACR,MAAA;EACA,WAAA;EACA,KAAA,EAAO,uBAAA;AAAA;;KAIG,0BAAA,GACR,+BAAA,GACA,+BAAA;AAAA,UAEa,eAAA;EACf,OAAA;EA7DgB;;AAGlB;;EA+DE,MAAA;AAAA;AAAA,UAGe,WAAA;EACf,OAAA;EACA,MAAA,EAAQ,MAAA,SAAe,gBAAA;EACvB,6BAAA;EACA,IAAA,EAAM,WAAA;EACN,YAAA,GAAe,uBAAA;EACf,eAAA,GAAkB,yBAAA;EAzDlB;EA2DA,iBAAA;EAzDA;;;;;EA+DA,WAAA;EAvDQ;;;;EA4DR,WAAA;EACA,IAAA,GAAO,eAAA;EACP,uBAAA;EAtDA;EAwDA,mBAAA,GAAsB,0BAAA;EAtDf;EAwDP,aAAA,GAAgB,oBAAA;EAChB,iBAAA;AAAA"}

package/dist/utils/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../../src/utils/types.ts"],"sourcesContent":["import type { AgentCapabilities } from \"@ag-ui/core\";\n\nexport type MaybePromise<T> = T | PromiseLike<T>;\n\n/**\n * More specific utility for records with at least one key\n */\nexport type NonEmptyRecord<T> =\n  T extends Record<string, unknown>\n    ? keyof T extends never\n      ? never\n      : T\n    : never;\n\n/**\n * Type representing an agent's basic information\n */\nexport interface AgentDescription {\n  name: string;\n  className: string;\n  description: string;\n  capabilities?: AgentCapabilities;\n}\n\nexport type RuntimeMode = \"sse\" | \"intelligence\";\n\nexport const RUNTIME_MODE_SSE = \"sse\" as const;\nexport const RUNTIME_MODE_INTELLIGENCE = \"intelligence\" as const;\n\nexport interface IntelligenceRuntimeInfo {\n  wsUrl: string;\n}\n\nexport interface ThreadEndpointRuntimeInfo {\n  list: boolean;\n  inspect: boolean;\n  mutations: boolean;\n  realtimeMetadata: boolean;\n}\n\nexport type RuntimeLicenseStatus =\n  | \"valid\"\n  | \"none\"\n  | \"expired\"\n  | \"expiring\"\n  | \"invalid\"\n  | \"unknown\";\n\nexport interface A2UIRuntimeInfo {\n  enabled: boolean;\n  /**\n   * Agent ids the runtime applies A2UI to. When omitted, A2UI applies to\n   * every agent served by the runtime.\n   */\n  agents?: string[];\n}\n\nexport interface RuntimeInfo {\n  version: string;\n  agents: Record<string, AgentDescription>;\n  audioFileTranscriptionEnabled: boolean;\n  mode: RuntimeMode;\n  intelligence?: IntelligenceRuntimeInfo;\n  threadEndpoints?: ThreadEndpointRuntimeInfo;\n  /** Whether this runtime exposes trusted inspector metadata. */\n  inspectorMetadata?: boolean;\n  /**\n   * When true, the runtime exposes POST /agent/:agentId/suggest for stateless\n   * suggestion generation. Absent on older runtimes; clients fall back to a\n   * client-side agent run.\n   */\n  suggestions?: boolean;\n  /**\n   * @deprecated Use `a2ui` instead, which preserves per-agent scoping.\n   * Kept for backward compatibility with older clients.\n   */\n  a2uiEnabled?: boolean;\n  a2ui?: A2UIRuntimeInfo;\n  openGenerativeUIEnabled?: boolean;\n  licenseStatus?: RuntimeLicenseStatus;\n  telemetryDisabled?: boolean;\n}\n"],"mappings":";AA0BA,MAAa,mBAAmB;AAChC,MAAa,4BAA4B"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../../src/utils/types.ts"],"sourcesContent":["import type { AgentCapabilities } from \"@ag-ui/core\";\n\nexport type MaybePromise<T> = T | PromiseLike<T>;\n\n/**\n * More specific utility for records with at least one key\n */\nexport type NonEmptyRecord<T> =\n  T extends Record<string, unknown>\n    ? keyof T extends never\n      ? never\n      : T\n    : never;\n\n/**\n * Type representing an agent's basic information\n */\nexport interface AgentDescription {\n  name: string;\n  className: string;\n  description: string;\n  capabilities?: AgentCapabilities;\n}\n\nexport type RuntimeMode = \"sse\" | \"intelligence\";\n\nexport const RUNTIME_MODE_SSE = \"sse\" as const;\nexport const RUNTIME_MODE_INTELLIGENCE = \"intelligence\" as const;\n\nexport interface IntelligenceRuntimeInfo {\n  wsUrl: string;\n}\n\nexport interface ThreadEndpointRuntimeInfo {\n  list: boolean;\n  inspect: boolean;\n  mutations: boolean;\n  realtimeMetadata: boolean;\n}\n\nexport type RuntimeLicenseStatus =\n  | \"valid\"\n  | \"none\"\n  | \"expired\"\n  | \"expiring\"\n  | \"invalid\"\n  | \"unknown\";\n\n/** Runtime entitlement authority resolved by a managed or self-hosted backend. */\ninterface RuntimeEntitlement {\n  /** Whether the resolved entitlement currently grants product access. */\n  active: boolean;\n  /** Deployment authority that produced this entitlement. */\n  source: \"managedOrgSubscription\" | \"selfHostedDeploymentLicense\";\n  /** Boolean feature grants keyed by stable feature id. */\n  features: Record<string, boolean>;\n  /** Numeric limits keyed by stable feature id. */\n  limits: Record<string, number>;\n  /** Optional catalog plan code supplied by the entitlement authority. */\n  planCode?: string;\n  /** Optional lower-level source metadata supplied by the authority. */\n  entitlementSource?: string;\n}\n\n/** Public diagnostic returned when Runtime entitlement resolution is not ready. */\ninterface RuntimeEntitlementError {\n  /** Stable backend or SDK error code. */\n  code: string;\n  /** Safe human-readable diagnostic. */\n  message: string;\n  /** Whether a later resolution attempt may succeed without reconfiguration. */\n  retryable: boolean;\n  /** Optional originating request correlation id. */\n  requestId?: string;\n  /** Optional originating trace correlation id. */\n  traceId?: string;\n}\n\n/** Successfully resolved Runtime entitlement response. */\ninterface RuntimeEntitlementReadyResponse {\n  status: \"ready\";\n  entitlement: RuntimeEntitlement;\n  error?: never;\n}\n\n/** Structured non-ready Runtime entitlement response. */\ninterface RuntimeEntitlementErrorResponse {\n  status: \"degraded\" | \"misconfigured\" | \"unavailable\";\n  entitlement?: never;\n  error: RuntimeEntitlementError;\n}\n\n/** Final structured Runtime entitlement response exposed through `/info`. */\nexport type RuntimeEntitlementResponse =\n  | RuntimeEntitlementReadyResponse\n  | RuntimeEntitlementErrorResponse;\n\nexport interface A2UIRuntimeInfo {\n  enabled: boolean;\n  /**\n   * Agent ids the runtime applies A2UI to. When omitted, A2UI applies to\n   * every agent served by the runtime.\n   */\n  agents?: string[];\n}\n\nexport interface RuntimeInfo {\n  version: string;\n  agents: Record<string, AgentDescription>;\n  audioFileTranscriptionEnabled: boolean;\n  mode: RuntimeMode;\n  intelligence?: IntelligenceRuntimeInfo;\n  threadEndpoints?: ThreadEndpointRuntimeInfo;\n  /** Whether this runtime exposes trusted inspector metadata. */\n  inspectorMetadata?: boolean;\n  /**\n   * When true, the runtime exposes POST /agent/:agentId/suggest for stateless\n   * suggestion generation. Absent on older runtimes; clients fall back to a\n   * client-side agent run.\n   */\n  suggestions?: boolean;\n  /**\n   * @deprecated Use `a2ui` instead, which preserves per-agent scoping.\n   * Kept for backward compatibility with older clients.\n   */\n  a2uiEnabled?: boolean;\n  a2ui?: A2UIRuntimeInfo;\n  openGenerativeUIEnabled?: boolean;\n  /** Structured Runtime-level entitlement authority, when advertised. */\n  runtimeEntitlements?: RuntimeEntitlementResponse;\n  /** Legacy compatibility diagnostic retained for older Core/Inspector clients. */\n  licenseStatus?: RuntimeLicenseStatus;\n  telemetryDisabled?: boolean;\n}\n"],"mappings":";AA0BA,MAAa,mBAAmB;AAChC,MAAa,4BAA4B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/shared",
-  "version": "1.69.2",
+  "version": "1.70.0",
   "private": false,
   "keywords": [
     "ai",
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ag-ui/client": "0.0.57",
+    "@ag-ui/client": "0.0.59",
     "@copilotkit/license-verifier": "~0.5.0",
     "@segment/analytics-node": "^2.1.2",
     "@standard-schema/spec": "^1.0.0",

package/src/__tests__/license-context.test.ts

@@ -1,33 +1,232 @@
-import { describe, it, expect } from "vitest";
+import { expect, test } from "vitest";
 import { createLicenseContextValue } from "../index";
 import type { RuntimeLicenseStatus } from "../utils/types";
 
-describe("createLicenseContextValue", () => {
-  it("fails open when no status is known", () => {
-    for (const status of [null, undefined] as const) {
-      const ctx = createLicenseContextValue(status);
-      expect(ctx.status).toBeNull();
-      expect(ctx.license).toBeNull();
-      expect(ctx.checkFeature("chat")).toBe(true);
-      expect(ctx.getLimit("chat")).toBeNull();
-    }
+test("license context fails open when no status is known", () => {
+  for (const status of [null, undefined] as const) {
+    const ctx = createLicenseContextValue(status);
+    expect(ctx.status).toBeNull();
+    expect(ctx.license).toBeNull();
+    expect(ctx.checkFeature("chat")).toBe(true);
+    expect(ctx.getLimit("chat")).toBeNull();
+  }
+});
+
+test.each(["valid", "none", "expiring", "unknown"] as RuntimeLicenseStatus[])(
+  "license context enables features for %s status",
+  (status) => {
+    const ctx = createLicenseContextValue(status);
+    expect(ctx.status).toBe(status);
+    expect(ctx.checkFeature("chat")).toBe(true);
+  },
+);
+
+test.each(["expired", "invalid"] as RuntimeLicenseStatus[])(
+  "license context disables features for %s status",
+  (status) => {
+    const ctx = createLicenseContextValue(status);
+    expect(ctx.status).toBe(status);
+    expect(ctx.checkFeature("chat")).toBe(false);
+  },
+);
+
+test("license context uses ready active feature grants and numeric limits", () => {
+  const ctx = createLicenseContextValue("valid", {
+    status: "ready",
+    entitlement: {
+      active: true,
+      source: "managedOrgSubscription",
+      features: {
+        chat: true,
+        threads: false,
+      },
+      limits: {
+        threads: 25,
+      },
+    },
   });
 
-  it.each(["valid", "none", "expiring", "unknown"] as RuntimeLicenseStatus[])(
-    "enables features for %s status",
-    (status) => {
-      const ctx = createLicenseContextValue(status);
-      expect(ctx.status).toBe(status);
-      expect(ctx.checkFeature("chat")).toBe(true);
+  expect(ctx.checkFeature("chat")).toBe(true);
+  expect(ctx.checkFeature("threads")).toBe(false);
+  expect(ctx.checkFeature("unknown")).toBe(false);
+  expect(ctx.getLimit("threads")).toBe(25);
+  expect(ctx.getLimit("unknown")).toBeNull();
+});
+
+test.each([0, 25])(
+  "license context treats an own threads.max_count limit of %s as a thread grant",
+  (threadLimit) => {
+    const ctx = createLicenseContextValue("valid", {
+      status: "ready",
+      entitlement: {
+        active: true,
+        source: "managedOrgSubscription",
+        features: {},
+        limits: { "threads.max_count": threadLimit },
+      },
+    });
+
+    expect(ctx.checkFeature("threads")).toBe(true);
+    expect(ctx.getLimit("threads.max_count")).toBe(threadLimit);
+  },
+);
+
+test.each([
+  {
+    source: "managedOrgSubscription" as const,
+    features: {},
+    limits: {
+      "threads.retention_hours": 72,
+      "threads.max_count": 200,
+    },
+  },
+  {
+    source: "selfHostedDeploymentLicense" as const,
+    features: {
+      deployment_via_helm_chart: true,
+      msteams: true,
+    },
+    limits: {
+      "threads.retention_hours": 336,
+      "threads.max_count": 25000,
+    },
+  },
+])(
+  "license context preserves legacy UI features for an active $source payload",
+  (entitlement) => {
+    const ctx = createLicenseContextValue("valid", {
+      status: "ready",
+      entitlement: {
+        active: true,
+        ...entitlement,
+      },
+    });
+
+    for (const feature of ["chat", "popup", "sidebar", "threads"]) {
+      expect(ctx.checkFeature(feature)).toBe(true);
+    }
+    expect(ctx.checkFeature("unknown")).toBe(false);
+  },
+);
+
+test.each(["chat", "popup", "sidebar"])(
+  "license context preserves an explicit %s denial",
+  (feature) => {
+    const ctx = createLicenseContextValue("valid", {
+      status: "ready",
+      entitlement: {
+        active: true,
+        source: "managedOrgSubscription",
+        features: { [feature]: false },
+        limits: {},
+      },
+    });
+
+    expect(ctx.checkFeature(feature)).toBe(false);
+  },
+);
+
+test.each([true, false])(
+  "license context preserves a legacy threads feature value of %s",
+  (threads) => {
+    const ctx = createLicenseContextValue("valid", {
+      status: "ready",
+      entitlement: {
+        active: true,
+        source: "selfHostedDeploymentLicense",
+        features: { threads },
+        limits: {},
+      },
+    });
+
+    expect(ctx.checkFeature("threads")).toBe(threads);
+  },
+);
+
+test("license context denies features and limits for a ready inactive entitlement", () => {
+  const ctx = createLicenseContextValue("none", {
+    status: "ready",
+    entitlement: {
+      active: false,
+      source: "managedOrgSubscription",
+      features: {
+        chat: true,
+      },
+      limits: {
+        threads: 25,
+      },
     },
-  );
-
-  it.each(["expired", "invalid"] as RuntimeLicenseStatus[])(
-    "disables features for %s status",
-    (status) => {
-      const ctx = createLicenseContextValue(status);
-      expect(ctx.status).toBe(status);
-      expect(ctx.checkFeature("chat")).toBe(false);
+  });
+
+  expect(ctx.checkFeature("chat")).toBe(false);
+  expect(ctx.getLimit("threads")).toBeNull();
+});
+
+test.each(["valid", "expiring"] as RuntimeLicenseStatus[])(
+  "license context preserves a %s legacy fallback for an inactive self-hosted entitlement",
+  (status) => {
+    const ctx = createLicenseContextValue(status, {
+      status: "ready",
+      entitlement: {
+        active: false,
+        source: "selfHostedDeploymentLicense",
+        features: {
+          threads: false,
+        },
+        limits: {
+          threads: 0,
+        },
+      },
+    });
+
+    expect(ctx.status).toBe(status);
+    expect(ctx.checkFeature("threads")).toBe(true);
+    expect(ctx.getLimit("threads")).toBeNull();
+  },
+);
+
+test.each([
+  { status: undefined, expectedStatus: "none" },
+  { status: "none", expectedStatus: "none" },
+  { status: "expired", expectedStatus: "expired" },
+  { status: "invalid", expectedStatus: "invalid" },
+  { status: "unknown", expectedStatus: "unknown" },
+] as const)(
+  "license context denies an inactive self-hosted entitlement with $status legacy status",
+  ({ status, expectedStatus }) => {
+    const ctx = createLicenseContextValue(status, {
+      status: "ready",
+      entitlement: {
+        active: false,
+        source: "selfHostedDeploymentLicense",
+        features: {
+          threads: true,
+        },
+        limits: {
+          threads: 25,
+        },
+      },
+    });
+
+    expect(ctx.status).toBe(expectedStatus);
+    expect(ctx.checkFeature("threads")).toBe(false);
+    expect(ctx.getLimit("threads")).toBeNull();
+  },
+);
+
+test("license context ignores inherited feature and limit keys", () => {
+  const ctx = createLicenseContextValue("valid", {
+    status: "ready",
+    entitlement: {
+      active: true,
+      source: "managedOrgSubscription",
+      features: {},
+      limits: {},
     },
-  );
+  });
+
+  for (const feature of ["toString", "constructor"]) {
+    expect(ctx.checkFeature(feature)).toBe(false);
+    expect(ctx.getLimit(feature)).toBeNull();
+  }
 });

package/src/index.ts

@@ -33,7 +33,10 @@ export type {
 } from "@copilotkit/license-verifier";
 
 import type { LicensePayload } from "@copilotkit/license-verifier";
-import type { RuntimeLicenseStatus } from "./utils/types";
+import type {
+  RuntimeEntitlementResponse,
+  RuntimeLicenseStatus,
+} from "./utils/types";
 
 // LicenseContextValue was dropped from license-verifier's public API in
 // 0.3.0, so it is defined here. The context shape is owned by this package
@@ -44,40 +47,93 @@ import type { RuntimeLicenseStatus } from "./utils/types";
  * Frontend providers create their own context using this shape.
  */
 export interface LicenseContextValue {
-  /** Server-reported license status from the runtime's /info endpoint. Null until known. */
+  /** Effective license status after structured entitlement precedence. Null until known. */
   status: RuntimeLicenseStatus | null;
   /** The license payload if available. Always null on the client; the payload stays server-side. */
   license: LicensePayload | null;
-  /** Whether a specific feature is licensed. Returns true if no licensing is active (no token). */
+  /** Whether a feature is licensed. Ready entitlements override legacy status behavior. */
   checkFeature: (feature: string) => boolean;
-  /** Get a numeric feature limit. Returns null if not applicable. */
+  /** Get a numeric feature limit. Zero means unlimited; null means not applicable. */
   getLimit: (feature: string) => number | null;
 }
 
+/** Read a record value without traversing its prototype chain. */
+function getOwnRecordValue<Value>(
+  record: Readonly<Record<string, Value>>,
+  key: string,
+): Value | undefined {
+  return Object.prototype.hasOwnProperty.call(record, key)
+    ? record[key]
+    : undefined;
+}
+
+/** Legacy UI surfaces that remain available for every active entitlement. */
+function isLegacyUiFeature(feature: string): boolean {
+  return feature === "chat" || feature === "popup" || feature === "sidebar";
+}
+
 /**
- * Client-safe license context factory, driven by the license status the
+ * Client-safe license context factory, driven by the license authority the
  * runtime reports via /info.
  *
- * Features are enabled unless the runtime definitively reports the license
- * as "expired" or "invalid". A null/"none"/"unknown" status fails open
- * (unlicensed = unrestricted, with branding), and "expiring" keeps features
- * on while the provider surfaces a warning banner. Per-feature data is not
- * in /info yet, so checkFeature is uniform across features and getLimit has
- * no limits to report. This is inlined here to avoid importing the full
- * license-verifier bundle (which depends on Node's `crypto`) into browser
- * bundles.
+ * A ready managed entitlement is authoritative in both directions. A ready
+ * active self-hosted entitlement is also authoritative, while an inactive
+ * self-hosted response preserves the legacy signed-license fallback. Active
+ * entitlements supply feature grants and limits; authoritative inactive
+ * entitlements deny every feature and limit. Older runtimes that report only a
+ * status retain the legacy behavior: features are enabled unless the status is
+ * "expired" or "invalid", and no limits are reported. This is inlined here to
+ * avoid importing the full license-verifier bundle (which depends on Node's
+ * `crypto`) into browser bundles.
  */
 export function createLicenseContextValue(
   status: RuntimeLicenseStatus | null | undefined,
+  runtimeEntitlements?: RuntimeEntitlementResponse,
 ): LicenseContextValue {
-  const resolvedStatus = status ?? null;
+  const readyEntitlement =
+    runtimeEntitlements?.status === "ready"
+      ? runtimeEntitlements.entitlement
+      : null;
+  const hasUsableSelfHostedLegacyFallback =
+    readyEntitlement &&
+    !readyEntitlement.active &&
+    readyEntitlement.source === "selfHostedDeploymentLicense" &&
+    (status === "valid" || status === "expiring");
+  const featureAuthority =
+    readyEntitlement && !hasUsableSelfHostedLegacyFallback
+      ? readyEntitlement
+      : null;
+  const activeEntitlement = featureAuthority?.active ? featureAuthority : null;
+  const resolvedStatus = activeEntitlement
+    ? "valid"
+    : readyEntitlement?.source === "managedOrgSubscription"
+      ? "none"
+      : featureAuthority
+        ? (status ?? "none")
+        : (status ?? null);
   const featuresEnabled =
     resolvedStatus !== "expired" && resolvedStatus !== "invalid";
+
   return {
     status: resolvedStatus,
     license: null,
-    checkFeature: () => featuresEnabled,
-    getLimit: () => null,
+    checkFeature: (feature) =>
+      featureAuthority
+        ? activeEntitlement
+          ? feature === "threads" &&
+            Object.prototype.hasOwnProperty.call(
+              activeEntitlement.limits,
+              "threads.max_count",
+            )
+            ? true
+            : (getOwnRecordValue(activeEntitlement.features, feature) ??
+              isLegacyUiFeature(feature))
+          : false
+        : featuresEnabled,
+    getLimit: (feature) =>
+      activeEntitlement
+        ? (getOwnRecordValue(activeEntitlement.limits, feature) ?? null)
+        : null,
   };
 }
 

package/src/telemetry/index.ts

@@ -1,5 +1,7 @@
 export * from "./telemetry-client";
+export * from "./sampling";
 export {
+  firstNonBlankTelemetryId,
   lambdaClient,
   parseTelemetryIdFromLicense,
   parseAndWarnTelemetryId,