@tangle-network/agent-app 0.16.1 → 0.19.0

package/dist/model-resolution/index.js

@@ -0,0 +1,123 @@
+// src/model-resolution/index.ts
+function canonicalModelId(model) {
+  if (model.id.includes("/")) return model.id;
+  const provider = model._provider ?? model.provider;
+  return provider ? `${provider}/${model.id}` : model.id;
+}
+function createChatModelResolution(defaults) {
+  const DEFAULT_ROUTER_MODEL = defaults.routerModel;
+  const DEFAULT_SANDBOX_OPENAI_MODEL = defaults.sandboxOpenaiModel;
+  const DEFAULT_ROUTER_BASE_URL = defaults.routerBaseUrl;
+  const allowlist = new Set(
+    [
+      DEFAULT_ROUTER_MODEL,
+      DEFAULT_SANDBOX_OPENAI_MODEL,
+      ...defaults.extraAllowlist ?? []
+    ].filter((model) => typeof model === "string" && model.length > 0)
+  );
+  function resolveChatModel({
+    requestedModel,
+    backend,
+    env = process.env
+  }) {
+    const selectedModel = cleanModelId(requestedModel);
+    if (selectedModel) return { backend, model: selectedModel, source: "request" };
+    if (backend === "router") {
+      const routerModel = cleanModelId(env.MODEL_NAME);
+      return {
+        backend,
+        model: routerModel ?? DEFAULT_ROUTER_MODEL,
+        source: routerModel ? "env:MODEL_NAME" : "default"
+      };
+    }
+    const sandboxModel = cleanModelId(env.MODEL_NAME);
+    if (sandboxModel) return { backend, model: sandboxModel, source: "env:MODEL_NAME" };
+    const modelProvider = env.MODEL_PROVIDER ?? (env.TANGLE_API_KEY ? "openai-compat" : env.OPENAI_API_KEY ? "openai" : void 0);
+    if (modelProvider === "openai" || modelProvider === "openai-compat") {
+      return { backend, model: DEFAULT_SANDBOX_OPENAI_MODEL, source: "default" };
+    }
+    return { backend, source: "sandbox-default" };
+  }
+  async function validateChatModelId(modelId, {
+    routerBaseUrl = DEFAULT_ROUTER_BASE_URL,
+    loadModels
+  }) {
+    const cleaned = cleanModelId(modelId);
+    if (!cleaned) {
+      return { succeeded: false, error: "Model id must be a non-empty string." };
+    }
+    if (!isWellFormedModelId(cleaned)) {
+      return { succeeded: false, error: `Model id is malformed: ${cleaned}` };
+    }
+    if (allowlist.has(cleaned)) {
+      return { succeeded: true, value: cleaned };
+    }
+    if (typeof routerBaseUrl !== "string" || routerBaseUrl.length === 0) {
+      return { succeeded: false, error: "Router base URL is required to validate against the catalog." };
+    }
+    let catalog;
+    try {
+      catalog = await loadModels(routerBaseUrl);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { succeeded: false, error: `Could not validate model catalog: ${message}` };
+    }
+    const ids = new Set(catalog.flatMap(catalogIdsForModel));
+    if (ids.has(cleaned)) {
+      return { succeeded: true, value: cleaned };
+    }
+    if (!cleaned.includes("/")) {
+      const canonicalBySuffix = /* @__PURE__ */ new Map();
+      for (const model of catalog) {
+        const canonical = canonicalModelIdOrUndefined(model);
+        if (!canonical || !canonical.includes("/")) continue;
+        const suffix = canonical.split("/").slice(1).join("/");
+        const entries = canonicalBySuffix.get(suffix);
+        if (entries) entries.push(canonical);
+        else canonicalBySuffix.set(suffix, [canonical]);
+      }
+      const matches = canonicalBySuffix.get(cleaned);
+      const only = matches && matches.length === 1 ? matches[0] : void 0;
+      if (only) {
+        return { succeeded: true, value: only };
+      }
+    }
+    return { succeeded: false, error: `Model is not available: ${cleaned}` };
+  }
+  return {
+    resolveChatModel,
+    validateChatModelId,
+    DEFAULT_ROUTER_MODEL,
+    DEFAULT_SANDBOX_OPENAI_MODEL,
+    DEFAULT_ROUTER_BASE_URL
+  };
+}
+function cleanModelId(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function isWellFormedModelId(modelId) {
+  if (modelId.length > 200) return false;
+  return /^[A-Za-z0-9._/@:-]+$/.test(modelId);
+}
+function catalogIdsForModel(model) {
+  const ids = /* @__PURE__ */ new Set();
+  if (typeof model.id === "string" && model.id.trim()) ids.add(model.id.trim());
+  if (typeof model.id === "string" && model.id.trim() && !model.id.includes("/")) {
+    const canonical = canonicalModelId(model);
+    if (canonical.includes("/")) ids.add(canonical);
+  }
+  return [...ids];
+}
+function canonicalModelIdOrUndefined(model) {
+  if (typeof model.id !== "string" || !model.id.trim()) return void 0;
+  return canonicalModelId(model);
+}
+export {
+  catalogIdsForModel,
+  cleanModelId,
+  createChatModelResolution,
+  isWellFormedModelId
+};
+//# sourceMappingURL=index.js.map

package/dist/model-resolution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/model-resolution/index.ts"],"sourcesContent":["/**\n * Chat-time model resolution: a precedence resolver and a fail-closed catalog\n * validator that sit on top of a product's boot-time model config.\n *\n * `resolveChatModel` picks the model id for a chat turn by precedence:\n *   request id > env MODEL_NAME > provider default > sandbox default.\n *\n * `validateChatModelId` is the fail-closed gate: it returns a typed outcome and\n * accepts an id only if it is in the constructed allowlist OR served by the live\n * router catalog (loaded through an injected boundary). A bare id with no\n * provider prefix resolves to its canonical id only when the suffix is unique\n * across the catalog, so an ambiguous suffix is rejected rather than silently\n * assigned a provider.\n *\n * The product injects one value — `modelDefaults` — and supplies the catalog\n * loader per call. `ModelInfo` is the router /v1/models wire shape and\n * `canonicalModelId` the bare->prefixed id helper, both defined locally so this\n * engine module carries no UI-package coupling.\n */\n\n/** The router /v1/models entry shape this module reads. Minimal on purpose. */\nexport interface ModelInfo {\n  id: string\n  name?: string\n  _provider?: string\n  provider?: string\n}\n\n/** Canonical (provider-prefixed) id for a catalog entry: pass through an id that\n *  already carries a provider, else prefix the entry's provider when present. */\nfunction canonicalModelId(model: ModelInfo): string {\n  if (model.id.includes('/')) return model.id\n  const provider = model._provider ?? model.provider\n  return provider ? `${provider}/${model.id}` : model.id\n}\n\n/** Which execution path the chat turn runs on. Product-supplied per turn. */\nexport type ChatBackend = 'router' | 'sandbox'\n\nexport type ChatModelSource =\n  | 'request'\n  | 'env:MODEL_NAME'\n  | 'default'\n  | 'sandbox-default'\n\nexport interface ResolvedChatModel {\n  backend: ChatBackend\n  model?: string\n  source: ChatModelSource\n}\n\nexport interface ChatModelValidationSuccess {\n  succeeded: true\n  value: string\n}\n\nexport interface ChatModelValidationFailure {\n  succeeded: false\n  error: string\n}\n\nexport type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure\n\n/** The catalog-fetch boundary: maps a router base URL to the raw model list. */\nexport type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>\n\n/**\n * The single product-injected seam.\n *\n * - `routerModel` / `sandboxOpenaiModel`: the two `DEFAULT_*` ids used by the\n *   precedence ladder and seeded into the allowlist.\n * - `routerBaseUrl`: catalog endpoint base; overridable per validate call.\n * - `extraAllowlist`: additional ids accepted without a catalog round-trip.\n */\nexport interface ChatModelDefaults {\n  routerModel: string\n  sandboxOpenaiModel: string\n  routerBaseUrl?: string\n  extraAllowlist?: string[]\n}\n\nexport interface ResolveChatModelOptions {\n  requestedModel?: string\n  backend: ChatBackend\n  /** Env to read (defaults to process.env). Inject for non-node runtimes. */\n  env?: Record<string, string | undefined>\n}\n\nexport interface ValidateChatModelIdOptions {\n  routerBaseUrl?: string\n  /** Catalog loader. No default body is baked in; the consumer supplies it. */\n  loadModels: LoadModels\n}\n\nexport interface ChatModelResolution {\n  resolveChatModel: (options: ResolveChatModelOptions) => ResolvedChatModel\n  validateChatModelId: (\n    modelId: unknown,\n    options: ValidateChatModelIdOptions,\n  ) => Promise<ChatModelValidationResult>\n  DEFAULT_ROUTER_MODEL: string\n  DEFAULT_SANDBOX_OPENAI_MODEL: string\n  DEFAULT_ROUTER_BASE_URL?: string\n}\n\nexport function createChatModelResolution(defaults: ChatModelDefaults): ChatModelResolution {\n  const DEFAULT_ROUTER_MODEL = defaults.routerModel\n  const DEFAULT_SANDBOX_OPENAI_MODEL = defaults.sandboxOpenaiModel\n  const DEFAULT_ROUTER_BASE_URL = defaults.routerBaseUrl\n\n  const allowlist = new Set(\n    [\n      DEFAULT_ROUTER_MODEL,\n      DEFAULT_SANDBOX_OPENAI_MODEL,\n      ...(defaults.extraAllowlist ?? []),\n    ].filter((model): model is string => typeof model === 'string' && model.length > 0),\n  )\n\n  function resolveChatModel({\n    requestedModel,\n    backend,\n    env = process.env,\n  }: ResolveChatModelOptions): ResolvedChatModel {\n    const selectedModel = cleanModelId(requestedModel)\n    if (selectedModel) return { backend, model: selectedModel, source: 'request' }\n\n    if (backend === 'router') {\n      const routerModel = cleanModelId(env.MODEL_NAME)\n      return {\n        backend,\n        model: routerModel ?? DEFAULT_ROUTER_MODEL,\n        source: routerModel ? 'env:MODEL_NAME' : 'default',\n      }\n    }\n\n    const sandboxModel = cleanModelId(env.MODEL_NAME)\n    if (sandboxModel) return { backend, model: sandboxModel, source: 'env:MODEL_NAME' }\n\n    const modelProvider = env.MODEL_PROVIDER\n      ?? (env.TANGLE_API_KEY ? 'openai-compat' : env.OPENAI_API_KEY ? 'openai' : undefined)\n    if (modelProvider === 'openai' || modelProvider === 'openai-compat') {\n      return { backend, model: DEFAULT_SANDBOX_OPENAI_MODEL, source: 'default' }\n    }\n\n    return { backend, source: 'sandbox-default' }\n  }\n\n  async function validateChatModelId(\n    modelId: unknown,\n    {\n      routerBaseUrl = DEFAULT_ROUTER_BASE_URL,\n      loadModels,\n    }: ValidateChatModelIdOptions,\n  ): Promise<ChatModelValidationResult> {\n    const cleaned = cleanModelId(modelId)\n    if (!cleaned) {\n      return { succeeded: false, error: 'Model id must be a non-empty string.' }\n    }\n    if (!isWellFormedModelId(cleaned)) {\n      return { succeeded: false, error: `Model id is malformed: ${cleaned}` }\n    }\n    if (allowlist.has(cleaned)) {\n      return { succeeded: true, value: cleaned }\n    }\n    if (typeof routerBaseUrl !== 'string' || routerBaseUrl.length === 0) {\n      return { succeeded: false, error: 'Router base URL is required to validate against the catalog.' }\n    }\n\n    let catalog: ModelInfo[]\n    try {\n      catalog = await loadModels(routerBaseUrl)\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err)\n      return { succeeded: false, error: `Could not validate model catalog: ${message}` }\n    }\n\n    // Exact match against any id the catalog serves (canonical or bare).\n    const ids = new Set(catalog.flatMap(catalogIdsForModel))\n    if (ids.has(cleaned)) {\n      return { succeeded: true, value: cleaned }\n    }\n\n    // A bare request id (no provider prefix) may name a model the catalog only\n    // serves under a provider-prefixed id (e.g. request \"gpt-5\" -> catalog\n    // \"openai/gpt-5\"). Resolve it to the canonical id the router serves, but only\n    // when the bare suffix is unique across the catalog -- an ambiguous suffix\n    // (e.g. \"openai/x\" vs \"vertex/x\") stays rejected so we never silently pick a\n    // provider for the caller.\n    if (!cleaned.includes('/')) {\n      const canonicalBySuffix = new Map<string, string[]>()\n      for (const model of catalog) {\n        const canonical = canonicalModelIdOrUndefined(model)\n        if (!canonical || !canonical.includes('/')) continue\n        const suffix = canonical.split('/').slice(1).join('/')\n        const entries = canonicalBySuffix.get(suffix)\n        if (entries) entries.push(canonical)\n        else canonicalBySuffix.set(suffix, [canonical])\n      }\n      const matches = canonicalBySuffix.get(cleaned)\n      const only = matches && matches.length === 1 ? matches[0] : undefined\n      if (only) {\n        return { succeeded: true, value: only }\n      }\n    }\n\n    return { succeeded: false, error: `Model is not available: ${cleaned}` }\n  }\n\n  return {\n    resolveChatModel,\n    validateChatModelId,\n    DEFAULT_ROUTER_MODEL,\n    DEFAULT_SANDBOX_OPENAI_MODEL,\n    DEFAULT_ROUTER_BASE_URL,\n  }\n}\n\nexport function cleanModelId(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\nexport function isWellFormedModelId(modelId: string): boolean {\n  if (modelId.length > 200) return false\n  return /^[A-Za-z0-9._/@:-]+$/.test(modelId)\n}\n\nexport function catalogIdsForModel(model: ModelInfo): string[] {\n  const ids = new Set<string>()\n  if (typeof model.id === 'string' && model.id.trim()) ids.add(model.id.trim())\n\n  if (typeof model.id === 'string' && model.id.trim() && !model.id.includes('/')) {\n    const canonical = canonicalModelId(model)\n    if (canonical.includes('/')) ids.add(canonical)\n  }\n\n  // The bare suffix of a provider-prefixed id (e.g. \"openai/gpt-5\" -> \"gpt-5\")\n  // is NOT added here: a bare request id resolves to its canonical id only\n  // through the uniqueness-gated path in validateChatModelId, so an ambiguous\n  // suffix never slips through as an exact match.\n  return [...ids]\n}\n\n/** The canonical id for a catalog entry, or undefined when the entry has no id. */\nfunction canonicalModelIdOrUndefined(model: ModelInfo): string | undefined {\n  if (typeof model.id !== 'string' || !model.id.trim()) return undefined\n  return canonicalModelId(model)\n}\n"],"mappings":"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","names":[]}

package/dist/platform/index.d.ts

@@ -325,6 +325,30 @@ interface PlatformUsageProductRow {
     totalSpent: number;
     count: number;
 }
+/** Lifecycle of a per-product seat subscription, mirroring the Stripe states
+ *  the platform persists. 'none' = the user has never held this seat. */
+type SeatStatus = 'none' | 'active' | 'trialing' | 'past_due' | 'canceled';
+/**
+ * Per-product entitlement snapshot from the platform — the single read that
+ * tells a product whether to show its workspace or the seat paywall. Shape
+ * matches `GET /v1/billing/product-entitlement?product=<id>`.
+ *
+ * `hasSeat` and `onFreeTier` are computed platform-side from the raw seat row
+ * + cumulative spend so the gate is identical across all five products:
+ * - `hasSeat`     — an active/trialing seat whose period has not lapsed.
+ * - `onFreeTier`  — no active seat AND cumulative spend below the free cap
+ *                   ($2 / 200¢ lifetime). Keys off lifetime spend, not wallet
+ *                   balance, so a router top-up never re-opens free access.
+ */
+interface ProductEntitlement {
+    seatStatus: SeatStatus;
+    /** ISO timestamp the active seat's paid period runs until; null when none. */
+    currentPeriodEnd: string | null;
+    /** Cumulative inference spend across the whole suite, in dollars. */
+    lifetimeSpentUsd: number;
+    hasSeat: boolean;
+    onFreeTier: boolean;
+}
 interface PlatformBillingHttp {
     /** GET /v1/plans/current (user bearer). */
     getSubscription(userApiKey: string): Promise<PlatformSubscriptionInfo>;
@@ -332,6 +356,8 @@ interface PlatformBillingHttp {
     getBalance(userApiKey: string): Promise<PlatformBalanceSnapshot>;
     /** GET /v1/billing/usage (user bearer). */
     getUsageByProduct(userApiKey: string): Promise<PlatformUsageProductRow[]>;
+    /** GET /v1/billing/product-entitlement?product=<id> (user bearer). */
+    getProductEntitlement(userApiKey: string, productId: string): Promise<ProductEntitlement>;
     /** POST /v1/billing/deduct (service token). */
     deduct(input: {
         platformUserId: string;
@@ -342,8 +368,17 @@ interface PlatformBillingHttp {
     }): Promise<void>;
     /** Absolute URL of the platform's billing-management surface. */
     billingUrl(): string;
+    /** Absolute URL of the $100/mo seat checkout for `productId`. */
+    seatCheckoutUrl(productId: string): string;
 }
 declare function createPlatformBillingHttp(opts: PlatformBillingHttpOptions): PlatformBillingHttp;
+/**
+ * Platform Stripe checkout URL for a product's $100/mo seat. One shared price
+ * carries `metadata.productId`; the platform distinguishes the product from
+ * the `product` query param (not five distinct prices). Mirrors the
+ * `billingUrl()` shape — a deterministic platform-rooted URL, no network call.
+ */
+declare function seatCheckoutUrl(baseUrl: string, productId: string): string;
 interface TangleTierPolicy {
     concurrency: number;
     overageAllowed: boolean;
@@ -364,6 +399,41 @@ interface TangleTierState {
  * on the billable path choose their posture explicitly.
  */
 declare function readTangleTierState(http: PlatformBillingHttp, userApiKey: string | null | undefined, policy?: Record<TanglePlanTier, TangleTierPolicy>): Promise<TangleTierState>;
+/** Lifetime free-tier cap: $2 (200¢) cumulative inference spend, expressed in
+ *  dollars. Free product access ends once cumulative spend crosses this. */
+declare const FREE_TIER_SPEND_CAP_USD = 2;
+/**
+ * Default name of the per-app feature flag gating seat billing. While OFF the
+ * entitlement read is skipped and access fails OPEN (entitled) so nothing
+ * changes live until a product flips the flag.
+ */
+declare const DEFAULT_SEAT_BILLING_ENABLED_ENV_VAR = "SEAT_BILLING_ENABLED";
+interface SeatBillingFlagOptions {
+    env?: Record<string, string | undefined>;
+    /** Override the flag name; default {@link DEFAULT_SEAT_BILLING_ENABLED_ENV_VAR}. */
+    flagEnvVar?: string;
+}
+/**
+ * Seat billing is OFF unless the flag is explicitly truthy ('true'/'1'/'on'/
+ * 'enabled'). Default OFF — pre-rollout, the paywall never engages. Returns
+ * false when no env is available (browser bundles) so the client stays
+ * fail-open there too.
+ */
+declare function isSeatBillingEnabled(opts?: SeatBillingFlagOptions): boolean;
+/**
+ * Read a user's entitlement for one product. Fails OPEN: an absent key,
+ * disabled flag, or unreachable seat endpoint all return a permissive snapshot
+ * (`hasSeat: true`) so consumers never break pre-rollout. The platform owns the
+ * `hasSeat`/`onFreeTier` computation; this client only transports + degrades
+ * safely.
+ *
+ * @param flag — pass {@link isSeatBillingEnabled} (or your own boolean) so the
+ *   product owns when the gate engages. When false, no network call is made.
+ */
+declare function getProductEntitlement(http: Pick<PlatformBillingHttp, 'getProductEntitlement'>, userApiKey: string | null | undefined, productId: string, flag?: boolean): Promise<ProductEntitlement>;
+/** Entitled = holds an active seat OR is still inside the free tier. The one
+ *  predicate all five products gate on. */
+declare function isProductEntitled(ent: ProductEntitlement): boolean;
 interface PlatformIdentityStore {
     resolveIdentity(userId: string): Promise<PlatformIdentity | null>;
 }
@@ -429,4 +499,4 @@ interface AssertBillableBalanceOptions {
  */
 declare function assertBillableBalance(state: BillableBalanceState, opts?: AssertBillableBalanceOptions): void;
 
-export { type AdminGuardOptions, type AssertBillableBalanceOptions, type AuthGuard, type AuthGuardOptions, type BetterAuthSessionCookieMinterOptions, type BetterAuthSessionCookieSource, type BillableBalanceState, DEFAULT_TANGLE_TIER_POLICY, type HubClientLike, type HubProxyContext, type HubProxyRouteArgs, type HubProxyRoutes, type PlatformBalanceSnapshot, type PlatformBillingHttp, PlatformBillingHttpError, type PlatformBillingHttpOptions, type PlatformIdentityStore, type PlatformSubscriptionInfo, type PlatformUsageProductRow, type SsoStateConfig, TangleBearerMissingError, type TanglePlanTier, type TangleSsoAccountStore, type TangleSsoAuthClient, type TangleSsoExchangeResult, type TangleSsoHandlerOptions, type TangleSsoHandlers, type TangleSsoSessionCookieArgs, TangleSsoUserCreateError, type TangleTierPolicy, type TangleTierState, assertBillableBalance, createAdminGuard, createAuthGuard, createBetterAuthSessionCookieMinter, createHubProxyRoutes, createPlatformBillingHttp, createSignedSsoState, createTanglePlatformBillingClient, createTangleSsoHandlers, isPlatformBillingHttpError, isPlatformHubErrorLike, isTangleBearerMissingError, normalizeTanglePlanTier, parseAdminEmails, readTangleTierState, signSessionCookieValue, verifySignedSsoState };
+export { type AdminGuardOptions, type AssertBillableBalanceOptions, type AuthGuard, type AuthGuardOptions, type BetterAuthSessionCookieMinterOptions, type BetterAuthSessionCookieSource, type BillableBalanceState, DEFAULT_SEAT_BILLING_ENABLED_ENV_VAR, DEFAULT_TANGLE_TIER_POLICY, FREE_TIER_SPEND_CAP_USD, type HubClientLike, type HubProxyContext, type HubProxyRouteArgs, type HubProxyRoutes, type PlatformBalanceSnapshot, type PlatformBillingHttp, PlatformBillingHttpError, type PlatformBillingHttpOptions, type PlatformIdentityStore, type PlatformSubscriptionInfo, type PlatformUsageProductRow, type ProductEntitlement, type SeatBillingFlagOptions, type SeatStatus, type SsoStateConfig, TangleBearerMissingError, type TanglePlanTier, type TangleSsoAccountStore, type TangleSsoAuthClient, type TangleSsoExchangeResult, type TangleSsoHandlerOptions, type TangleSsoHandlers, type TangleSsoSessionCookieArgs, TangleSsoUserCreateError, type TangleTierPolicy, type TangleTierState, assertBillableBalance, createAdminGuard, createAuthGuard, createBetterAuthSessionCookieMinter, createHubProxyRoutes, createPlatformBillingHttp, createSignedSsoState, createTanglePlatformBillingClient, createTangleSsoHandlers, getProductEntitlement, isPlatformBillingHttpError, isPlatformHubErrorLike, isProductEntitled, isSeatBillingEnabled, isTangleBearerMissingError, normalizeTanglePlanTier, parseAdminEmails, readTangleTierState, seatCheckoutUrl, signSessionCookieValue, verifySignedSsoState };

package/dist/platform/index.js

@@ -376,6 +376,20 @@ function createPlatformBillingHttp(opts) {
         count: row.count ?? 0
       }));
     },
+    async getProductEntitlement(userApiKey, productId) {
+      const slug = encodeURIComponent(productId);
+      const body = await userRead(userApiKey, `/v1/billing/product-entitlement?product=${slug}`);
+      const data = body.data ?? {};
+      const hasSeat = data.hasSeat === true;
+      return {
+        seatStatus: data.seatStatus ?? "none",
+        currentPeriodEnd: data.currentPeriodEnd ?? null,
+        lifetimeSpentUsd: data.lifetimeSpentUsd ?? 0,
+        hasSeat,
+        // Free access only when there is no seat AND the platform says so.
+        onFreeTier: !hasSeat && data.onFreeTier === true
+      };
+    },
     async deduct(input) {
       const headers = new Headers();
       headers.set("Authorization", `Bearer ${resolveServiceToken()}`);
@@ -395,9 +409,16 @@ function createPlatformBillingHttp(opts) {
     },
     billingUrl() {
       return `${baseUrl}/app/billing`;
+    },
+    seatCheckoutUrl(productId) {
+      return seatCheckoutUrl(baseUrl, productId);
     }
   };
 }
+function seatCheckoutUrl(baseUrl, productId) {
+  const root = baseUrl.replace(/\/+$/, "");
+  return `${root}/app/billing/seat/checkout?product=${encodeURIComponent(productId)}`;
+}
 var DEFAULT_TANGLE_TIER_POLICY = {
   free: { concurrency: 1, overageAllowed: false },
   pro: { concurrency: Number.POSITIVE_INFINITY, overageAllowed: true },
@@ -425,6 +446,34 @@ async function readTangleTierState(http, userApiKey, policy = DEFAULT_TANGLE_TIE
     ...policy[subscription.tier]
   };
 }
+var FREE_TIER_SPEND_CAP_USD = 2;
+var DEFAULT_SEAT_BILLING_ENABLED_ENV_VAR = "SEAT_BILLING_ENABLED";
+function isSeatBillingEnabled(opts = {}) {
+  const env = opts.env ?? (typeof process !== "undefined" ? process.env : void 0);
+  if (!env) return false;
+  const flag = env[opts.flagEnvVar ?? DEFAULT_SEAT_BILLING_ENABLED_ENV_VAR]?.trim().toLowerCase();
+  return flag === "true" || flag === "1" || flag === "on" || flag === "enabled";
+}
+async function getProductEntitlement(http, userApiKey, productId, flag = true) {
+  if (!flag || !userApiKey) return failOpenEntitlement();
+  try {
+    return await http.getProductEntitlement(userApiKey, productId);
+  } catch {
+    return failOpenEntitlement();
+  }
+}
+function failOpenEntitlement() {
+  return {
+    seatStatus: "active",
+    currentPeriodEnd: null,
+    lifetimeSpentUsd: 0,
+    hasSeat: true,
+    onFreeTier: false
+  };
+}
+function isProductEntitled(ent) {
+  return ent.hasSeat || ent.onFreeTier;
+}
 function createTanglePlatformBillingClient(http, identity) {
   return {
     resolveIdentity: (userId) => identity.resolveIdentity(userId),
@@ -484,7 +533,9 @@ function assertBillableBalance(state, opts = {}) {
   );
 }
 export {
+  DEFAULT_SEAT_BILLING_ENABLED_ENV_VAR,
   DEFAULT_TANGLE_TIER_POLICY,
+  FREE_TIER_SPEND_CAP_USD,
   PlatformBillingHttpError,
   TangleBearerMissingError,
   TangleSsoUserCreateError,
@@ -497,12 +548,16 @@ export {
   createSignedSsoState,
   createTanglePlatformBillingClient,
   createTangleSsoHandlers,
+  getProductEntitlement,
   isPlatformBillingHttpError,
   isPlatformHubErrorLike,
+  isProductEntitled,
+  isSeatBillingEnabled,
   isTangleBearerMissingError,
   normalizeTanglePlanTier,
   parseAdminEmails,
   readTangleTierState,
+  seatCheckoutUrl,
   signSessionCookieValue,
   verifySignedSsoState
 };