@oxygen-agent/cli 1.1010.650 → 1.1010.905

package/node_modules/@oxygen/shared/dist/otlp-log-sink.js

@@ -1,5 +1,7 @@
 import { log } from "./log.js";
 import { resolveDeployEnv } from "./deploy-env.js";
+import { processResourceIdentity } from "./process-resource.js";
+import { OXYGEN_VERSION } from "./version.js";
 import { sanitizeLogFields } from "./redaction.js";
 import { trace } from "@opentelemetry/api";
 import { operationalLogSnapshot } from "./operational-telemetry.js";
@@ -44,6 +46,7 @@ async function rejectedRecords(response, batchLength) {
         reader.releaseLock();
     }
 }
+const OTEL_TRACE_ID = /^[a-f\d]{32}$/i;
 // OTLP severity numbers (logs data model): the base of each 4-value band.
 const SEVERITY_NUMBERS = { debug: 5, info: 9, warn: 13, error: 17 };
 // Set by log() on every record; they become the OTLP record's own fields rather
@@ -197,6 +200,10 @@ export function createOtlpLogSink(options) {
             ?? process.env.NODE_ENV
             ?? null,
         "deployment.sha": process.env.OXYGEN_GIT_SHA ?? process.env.VERCEL_GIT_COMMIT_SHA,
+        "service.version": OXYGEN_VERSION,
+        // host.name + service.instance.id: which box and which process emitted a
+        // line, the same identity the trace/metric resources now carry.
+        ...processResourceIdentity(),
         ...resourceOverrides,
     });
     const queue = [];
@@ -277,9 +284,19 @@ export function createOtlpLogSink(options) {
             droppedOverflow += 1;
         }
         const activeSpan = trace.getActiveSpan()?.spanContext();
+        // A request correlation id that is not an OTel trace id (the CLI's UUID
+        // `x-oxygen-trace-id`) cannot be the record's traceId, but it is the one key
+        // a customer can quote; keep it as an attribute instead of discarding it,
+        // and let the active span supply the real trace/span ids.
+        const requestTraceId = typeof record.trace_id === "string" && record.trace_id !== ""
+            && !OTEL_TRACE_ID.test(record.trace_id) ? record.trace_id : null;
+        const { trace_id: _requestTraceId, ...withoutRequestTraceId } = record;
+        const base = requestTraceId
+            ? { ...withoutRequestTraceId, "oxygen.request_trace_id": requestTraceId }
+            : record;
         queue.push(operationalLogSnapshot(sanitizeLogFields({
-            ...record,
-            ...(activeSpan && (!record.trace_id || record.trace_id === activeSpan.traceId)
+            ...base,
+            ...(activeSpan && (requestTraceId || !record.trace_id || record.trace_id === activeSpan.traceId)
                 ? { trace_id: activeSpan.traceId, span_id: activeSpan.spanId }
                 : {}),
         })));

package/node_modules/@oxygen/shared/dist/plan-band.d.ts

@@ -0,0 +1,234 @@
+import { type LimitsTier } from "./plan-limits.js";
+import { type RepricingOptions } from "./repricing.js";
+import { type WorkspaceTableCapacityStatus } from "./table-capacity.js";
+/**
+ * The seven plan bands of the 2026-09 repricing (spec § 4, slice S06): free
+ * plus one band per Oxygen plan size. They sit BESIDE the five-rung
+ * `LimitsTier`, which cannot tell $49 from $99 or $199 from $499, so any limit
+ * that differs between those sizes (storage, the per-delivery spend default)
+ * is resolved from the band instead of the rung.
+ *
+ * A band never changes a limit by itself. Until a limit is re-keyed onto the
+ * band, it keeps reading its rung, and `PLAN_BAND_LIMITS_TIER` says which rung
+ * that is.
+ */
+export type PlanBand = "free" | "49" | "99" | "199" | "499" | "999" | "1999";
+export declare const PLAN_BAND_ORDER: readonly PlanBand[];
+/** The limits rung each band enforces at today. */
+export declare const PLAN_BAND_LIMITS_TIER: Readonly<Record<PlanBand, LimitsTier>>;
+/**
+ * L4.1 (repricing 2026-09, slice S55; decision record "Worker share"): a
+ * tenant's share of the legacy worker's tenant queue while other tenants wait.
+ * A weight-16 tenant gets sixteen quanta for every one a weight-1 tenant gets;
+ * with nobody else waiting every tenant is served at once, whatever its weight.
+ * It is a scheduling share, never a sold limit: capacity is sized so contention
+ * is rare (`.agents/skills/oxygen-worker-performance`, "Worker share target").
+ * An org whose band is not yet resolved schedules at the free weight.
+ */
+export declare const PLAN_BAND_WORKER_SHARE_WEIGHT: Readonly<Record<PlanBand, number>>;
+/**
+ * PROPOSED (P-57, repricing spec § 4): a grandfathered or legacy plan takes the
+ * band of the limits rung it enforces at today, so no grandfathered customer
+ * loses a storage or rate limit. The pro rung spans $199–$499, whose columns
+ * differ only in the per-delivery spend default, which grandfathered plans
+ * resolve from their own monthly credits instead (P-62); it maps to the lower
+ * band. Enterprise enforces at the scale rung and therefore takes the top band.
+ */
+export declare const LEGACY_PLAN_BAND_BY_LIMITS_TIER: Readonly<Record<LimitsTier, PlanBand>>;
+/**
+ * Map a raw plan-tier string (subscription `tier`, metadata tier, legacy plan
+ * key, or an Oxygen plan key like `oxygen_499`) onto its band. Unknown or absent
+ * tiers land on the unentitled "free" band, the same fail-closed rule as
+ * `limitsTierForPlanTier`.
+ */
+export declare function planBandForPlanTier(tier: string | null | undefined): PlanBand;
+/**
+ * The band of an org whose limits rung is already resolved (no second lookup).
+ * An unentitled org keeps no plan tier, so it takes the free band.
+ */
+export declare function planBandForLimitsResolution(resolution: {
+    planTier: string | null;
+    entitled: boolean;
+}): PlanBand;
+/** The band's monthly price, read from the Oxygen plan it names; null for free. */
+export declare function planBandMonthlyPriceCents(band: PlanBand): number | null;
+export declare function planBandLabel(band: PlanBand): string;
+/**
+ * PROPOSED (P-54): the free plan keeps a 50-credit default. It has no monthly
+ * grant to take 10% of (10% of its one-time 1,000 would be 100).
+ */
+export declare const FREE_PLAN_DEFAULT_DELIVERY_CREDIT_CEILING = 50;
+/**
+ * A plan size's target default delivery ceiling: 10% of its monthly credits,
+ * rounded half up (decision L5.1; the volume bonus counts, the partner bonus
+ * does not, P-54). This is the target, not always the value in force: see
+ * `resolveDefaultTriggerRunCreditCeilingForPlan`.
+ */
+export declare function planBandDeliveryCreditCeilingTarget(band: PlanBand): number;
+/** What an org's plan resolves to: the raw plan tier and its limits rung. */
+export type PlanSpendResolution = {
+    planTier: string | null;
+    limitsTier: LimitsTier;
+};
+/**
+ * The default credit ceiling of one LIVE workflow run fired by an unattended
+ * trigger (cron, webhook, event) that declares no `max_credits`, for a plan.
+ * `null` means no default applies (enterprise); an explicit cap always wins and
+ * is never clamped by this.
+ */
+export declare function resolveDefaultTriggerRunCreditCeilingForPlan(resolution: PlanSpendResolution, options?: RepricingOptions): number | null;
+/** The same default for one standing or webhook table auto-run batch. */
+export declare function resolveDefaultAutoRunBatchCreditCeilingForPlan(resolution: PlanSpendResolution, options?: RepricingOptions): number | null;
+/**
+ * Public webhook ingress (repricing 2026-09, decision L4.4, ratified
+ * 2026-09-26): deliveries a minute that one webhook target (a Table endpoint,
+ * a workflow or Agent trigger, the workspace's RB2B receiver) accepts. It used
+ * to be a flat 600 per target, with 60 per sender IP on most targets. Every
+ * value rises, so this is live on release rather than held behind the
+ * repricing switch.
+ */
+export declare const PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE: Readonly<Record<PlanBand, number>>;
+/**
+ * PROPOSED (P-50, repricing spec § 4.4): the decision raises the per-IP limit
+ * "to match", read as equal to the per-target limit (a share of 1). One sender
+ * (a form tool, a CRM) usually posts from one address, so any lower per-IP
+ * limit would cap a real integration below its plan's rate.
+ */
+export declare const PUBLIC_WEBHOOK_INGRESS_PER_IP_SHARE_OF_TARGET = 1;
+export declare const PUBLIC_WEBHOOK_INGRESS_WINDOW_SECONDS = 60;
+export type PublicWebhookIngressLimits = {
+    perTargetPerMinute: number;
+    perSenderIpPerMinute: number;
+    windowSeconds: number;
+};
+/** The webhook ingress limits a band enforces. */
+export declare function resolvePublicWebhookIngressLimits(band: PlanBand): PublicWebhookIngressLimits;
+/** The webhook ingress limits of one band, as the `/api/cli/limits` contract reports them. */
+export declare function describeWebhookIngress(band: PlanBand): PlanBandLimitsReport["webhooks"];
+/**
+ * Request rates, per minute unless named otherwise. The totals bound every
+ * `/api/cli/*` call; the operation buckets bind first for the calls a script
+ * makes most (row reads and writes, live tool and AI calls, dry runs, bulk
+ * imports). A 429 names the bucket it hit in `error.details.bucket`: the
+ * totals are `cli.requests`, the others `tenant_read.requests`,
+ * `tenant_write.requests`, `tool_live.requests` / `ai_live.requests`,
+ * `tool_dry_run.requests` and `bulk_import.requests`.
+ */
+export type ApiRateLimitsReport = {
+    org_requests_per_minute: number;
+    key_requests_per_minute: number;
+    tenant_read_requests_per_key_per_minute: number;
+    tenant_write_requests_per_key_per_minute: number;
+    live_action_requests_per_key_per_minute: number;
+    live_action_requests_per_org_per_hour: number;
+    tool_dry_run_requests_per_key_per_minute: number;
+    bulk_import_tables_per_org_per_hour: number;
+    /**
+     * Row budgets shared by every key in the workspace: each row a request reads
+     * or writes is one unit (`tenant_read.units`, `tenant_write.units`). The
+     * window is an hour on free and a day on paid plans.
+     */
+    rows_read_per_org: {
+        rows: number;
+        window_seconds: number;
+    };
+    rows_written_per_org: {
+        rows: number;
+        window_seconds: number;
+    };
+};
+/** The API rates a limits rung enforces, read from `PLAN_LIMITS`. */
+export declare function describeApiRateLimits(tier: LimitsTier): ApiRateLimitsReport;
+/**
+ * The limits in force today for one band, as the `/api/cli/limits` contract
+ * reports them. Every value is read from the constant that enforces it; nothing
+ * here is a second copy. Monthly credits are the Oxygen plan's grant (free has
+ * none, so its org-daily guard does not apply).
+ */
+export type PlanBandLimitsReport = {
+    band: PlanBand;
+    label: string;
+    monthly_price_usd: number | null;
+    monthly_credits: number | null;
+    /**
+     * Credits granted above face value ($1 = 100 credits), repricing 2026-09
+     * decision 1.3: 0 up to $199, then +5% / +10% / +15% on $499 / $999 / $1,999.
+     * Already included in `monthly_credits`. Null on free, which has no plan grant.
+     */
+    volume_bonus_credits: number | null;
+    volume_bonus_percent: number | null;
+    /** What 100 plan credits cost on this size, the volume bonus included. */
+    usd_per_100_credits: number | null;
+    limits_tier: LimitsTier;
+    api: ApiRateLimitsReport;
+    storage: {
+        table_row_limit: number;
+        workspace_row_limit: number;
+        workspace_database_warning_bytes: number;
+        workspace_database_limit_bytes: number;
+        /** Equal to rows per Table (PROPOSED P-60): one file can fill an empty Table. */
+        import_max_rows_per_file: number;
+        import_max_file_bytes: number;
+        /**
+         * Where the values above stand against the ratified ladder (decision F.2):
+         * `in_force`, `scheduled` (they move to `target` at `effective_at`) or
+         * `awaiting_capacity_test` (`target` applies once the rows-per-Table
+         * capacity test at this size passes). A cut is announced only once the
+         * repricing date is set, so `target` is null while nothing is pending.
+         */
+        status: WorkspaceTableCapacityStatus["status"];
+        effective_at: string | null;
+        target: PlanBandStorageTarget | null;
+    };
+    spend: {
+        trigger_run_credit_ceiling: number | null;
+        auto_run_batch_credit_ceiling: number | null;
+        agent_run_max_total_credits: number;
+        agent_run_max_inference_credits: number;
+        /** Paid work the attended Copilot may start without an approval card. */
+        copilot_approval_free_per_call_credits: number;
+        copilot_approval_free_per_session_credits: number;
+        /** The platform's runaway bound on one attended Copilot turn (every plan). */
+        copilot_attended_turn_backstop_credits: number;
+        org_daily_guard_warn_credits: number | null;
+        org_daily_guard_block_credits: number | null;
+        byok_column_run_max_rows: number | null;
+        byok_provider_daily_calls: number | null;
+    };
+    /**
+     * Table work limits (L6): rows one write request may carry, and columns one
+     * action run or standing auto-run may carry.
+     */
+    tables: {
+        max_rows_per_write_request: number;
+        max_columns_per_run: number;
+    };
+    /** The raw signal-event feed: events per read and look-back days. */
+    signals: {
+        max_events: number;
+        max_window_days: number;
+    };
+    /** Public webhook ingress, per target and per sender IP (decision L4.4). */
+    webhooks: {
+        ingress_requests_per_target_per_minute: number;
+        ingress_requests_per_sender_ip_per_minute: number;
+        window_seconds: number;
+    };
+    workflows: {
+        /** Fastest cron schedule a workflow or Agent trigger may use, in force now. */
+        cron_min_interval_minutes: number;
+    };
+};
+/** The storage values a band moves to, in the `/api/cli/limits` field names. */
+export type PlanBandStorageTarget = {
+    table_row_limit: number;
+    workspace_row_limit: number;
+    workspace_database_warning_bytes: number;
+    workspace_database_limit_bytes: number;
+    import_max_rows_per_file: number;
+};
+/** A band's storage status as `/api/cli/limits` reports it (`plan_bands[].storage` and `storage_capacity`). */
+export declare function describePlanBandStorageStatus(band: PlanBand, options?: RepricingOptions): Pick<PlanBandLimitsReport["storage"], "status" | "effective_at" | "target">;
+export declare function describePlanBandLimits(band: PlanBand, options?: RepricingOptions): PlanBandLimitsReport;
+/** Every band's limits in force today, smallest first. */
+export declare function describePlanBandLadder(options?: RepricingOptions): PlanBandLimitsReport[];

package/node_modules/@oxygen/shared/dist/plan-band.js

@@ -0,0 +1,312 @@
+import { planVolumeBonusCredits, planVolumeBonusPercent, resolveBasePricingPlan } from "./billing.js";
+import { planLimitsForTier, limitsTierForPlanTier, resolveCronMinIntervalMinutes, resolvePlanAgentCreditLimits, } from "./plan-limits.js";
+import { COPILOT_ATTENDED_INFERENCE_CREDIT_CEILING, DEFAULT_AUTO_RUN_BATCH_CREDIT_CEILING, DEFAULT_BYOK_COLUMN_RUN_MAX_ROWS, DEFAULT_BYOK_PROVIDER_DAILY_CALL_CAP, DEFAULT_TRIGGER_RUN_CREDIT_CEILING, copilotApprovalFreeAllowanceForBand, resolveOrgDailySpendGuard, resolveSpendSafetyPlanTier, } from "./spend-safety.js";
+import { isRepricingInForce, tenthOfMonthlyCreditsRoundedHalfUp, } from "./repricing.js";
+import { describeWorkspaceTableCapacityStatus, resolveWorkspaceTableCapacity, } from "./table-capacity.js";
+export const PLAN_BAND_ORDER = [
+    "free",
+    "49",
+    "99",
+    "199",
+    "499",
+    "999",
+    "1999",
+];
+/** The limits rung each band enforces at today. */
+export const PLAN_BAND_LIMITS_TIER = Object.freeze({
+    free: "free",
+    "49": "starter",
+    "99": "starter",
+    "199": "pro",
+    "499": "pro",
+    "999": "team",
+    "1999": "scale",
+});
+/**
+ * L4.1 (repricing 2026-09, slice S55; decision record "Worker share"): a
+ * tenant's share of the legacy worker's tenant queue while other tenants wait.
+ * A weight-16 tenant gets sixteen quanta for every one a weight-1 tenant gets;
+ * with nobody else waiting every tenant is served at once, whatever its weight.
+ * It is a scheduling share, never a sold limit: capacity is sized so contention
+ * is rare (`.agents/skills/oxygen-worker-performance`, "Worker share target").
+ * An org whose band is not yet resolved schedules at the free weight.
+ */
+export const PLAN_BAND_WORKER_SHARE_WEIGHT = Object.freeze({
+    free: 1,
+    "49": 2,
+    "99": 2,
+    "199": 4,
+    "499": 4,
+    "999": 8,
+    "1999": 16,
+});
+/**
+ * PROPOSED (P-57, repricing spec § 4): a grandfathered or legacy plan takes the
+ * band of the limits rung it enforces at today, so no grandfathered customer
+ * loses a storage or rate limit. The pro rung spans $199–$499, whose columns
+ * differ only in the per-delivery spend default, which grandfathered plans
+ * resolve from their own monthly credits instead (P-62); it maps to the lower
+ * band. Enterprise enforces at the scale rung and therefore takes the top band.
+ */
+export const LEGACY_PLAN_BAND_BY_LIMITS_TIER = Object.freeze({
+    free: "free",
+    starter: "99",
+    pro: "199",
+    team: "999",
+    scale: "1999",
+});
+/**
+ * Map a raw plan-tier string (subscription `tier`, metadata tier, legacy plan
+ * key, or an Oxygen plan key like `oxygen_499`) onto its band. Unknown or absent
+ * tiers land on the unentitled "free" band, the same fail-closed rule as
+ * `limitsTierForPlanTier`.
+ */
+export function planBandForPlanTier(tier) {
+    const plan = resolveBasePricingPlan(tier);
+    if (!plan || plan.tier === "free")
+        return "free";
+    if (plan.tier === "oxygen")
+        return oxygenPlanBand(plan.monthlyPriceCents);
+    return LEGACY_PLAN_BAND_BY_LIMITS_TIER[limitsTierForPlanTier(tier)];
+}
+/**
+ * The band of an org whose limits rung is already resolved (no second lookup).
+ * An unentitled org keeps no plan tier, so it takes the free band.
+ */
+export function planBandForLimitsResolution(resolution) {
+    return resolution.entitled ? planBandForPlanTier(resolution.planTier) : "free";
+}
+/**
+ * An Oxygen plan sits on the largest size at or below its price. A plan with no
+ * resolvable price takes the entry size, the same rung `limitsTierForPlanTier`
+ * gives it.
+ */
+function oxygenPlanBand(monthlyPriceCents) {
+    if (monthlyPriceCents === null)
+        return "49";
+    let band = "49";
+    for (const candidate of PLAN_BAND_ORDER) {
+        const price = planBandMonthlyPriceCents(candidate);
+        if (price !== null && price <= monthlyPriceCents)
+            band = candidate;
+    }
+    return band;
+}
+/** The band's monthly price, read from the Oxygen plan it names; null for free. */
+export function planBandMonthlyPriceCents(band) {
+    if (band === "free")
+        return null;
+    return resolveBasePricingPlan(`oxygen_${band}`)?.monthlyPriceCents ?? null;
+}
+export function planBandLabel(band) {
+    return band === "free" ? "Free" : `Oxygen $${Number(band).toLocaleString("en-US")}`;
+}
+// ---- Default credit ceiling of one unattended delivery (decision L5.1) ------
+/**
+ * PROPOSED (P-54): the free plan keeps a 50-credit default. It has no monthly
+ * grant to take 10% of (10% of its one-time 1,000 would be 100).
+ */
+export const FREE_PLAN_DEFAULT_DELIVERY_CREDIT_CEILING = 50;
+/**
+ * The grandfathered plans that take 10% of their OWN monthly credits (PROPOSED
+ * P-62: Starter 990, Pro 2,490, Team 7,490) rather than their band's. Other
+ * legacy plan keys take the band of the rung they enforce at (P-57).
+ */
+const OWN_CREDITS_DELIVERY_CEILING_PLAN_KEYS = new Set(["starter", "pro", "team"]);
+/**
+ * A plan size's target default delivery ceiling: 10% of its monthly credits,
+ * rounded half up (decision L5.1; the volume bonus counts, the partner bonus
+ * does not, P-54). This is the target, not always the value in force: see
+ * `resolveDefaultTriggerRunCreditCeilingForPlan`.
+ */
+export function planBandDeliveryCreditCeilingTarget(band) {
+    if (band === "free")
+        return FREE_PLAN_DEFAULT_DELIVERY_CREDIT_CEILING;
+    const monthlyCredits = resolveBasePricingPlan(`oxygen_${band}`)?.monthlyCredits;
+    if (typeof monthlyCredits !== "number" || !(monthlyCredits > 0)) {
+        throw new Error(`plan-band: no monthly credits for the ${band} plan`);
+    }
+    return tenthOfMonthlyCreditsRoundedHalfUp(monthlyCredits);
+}
+function planBandForSpendResolution(resolution) {
+    return resolution.planTier
+        ? planBandForPlanTier(resolution.planTier)
+        : LEGACY_PLAN_BAND_BY_LIMITS_TIER[resolution.limitsTier];
+}
+function resolveDeliveryCreditCeiling(resolution, preRepricingTable, options) {
+    const before = preRepricingTable[resolveSpendSafetyPlanTier(resolution.planTier, resolution.limitsTier)];
+    // Enterprise runs on custom limits and has no default, before or after.
+    if (before === null || before === undefined)
+        return null;
+    const ownPlan = resolution.planTier && OWN_CREDITS_DELIVERY_CEILING_PLAN_KEYS.has(resolution.planTier)
+        ? resolveBasePricingPlan(resolution.planTier)
+        : null;
+    const target = ownPlan && typeof ownPlan.monthlyCredits === "number" && ownPlan.monthlyCredits > 0
+        ? tenthOfMonthlyCreditsRoundedHalfUp(ownPlan.monthlyCredits)
+        : planBandDeliveryCreditCeilingTarget(planBandForSpendResolution(resolution));
+    // A larger default ships on release; a smaller one is a tightening and waits
+    // for the effective-date switch (`spend.<band>.default_delivery_credit_ceiling`).
+    if (target >= before)
+        return target;
+    return isRepricingInForce(options) ? target : before;
+}
+/**
+ * The default credit ceiling of one LIVE workflow run fired by an unattended
+ * trigger (cron, webhook, event) that declares no `max_credits`, for a plan.
+ * `null` means no default applies (enterprise); an explicit cap always wins and
+ * is never clamped by this.
+ */
+export function resolveDefaultTriggerRunCreditCeilingForPlan(resolution, options = {}) {
+    return resolveDeliveryCreditCeiling(resolution, DEFAULT_TRIGGER_RUN_CREDIT_CEILING, options);
+}
+/** The same default for one standing or webhook table auto-run batch. */
+export function resolveDefaultAutoRunBatchCreditCeilingForPlan(resolution, options = {}) {
+    return resolveDeliveryCreditCeiling(resolution, DEFAULT_AUTO_RUN_BATCH_CREDIT_CEILING, options);
+}
+/** The spend resolution a plan size stands for (its Oxygen plan key). */
+function bandSpendResolution(band) {
+    return { planTier: band === "free" ? null : `oxygen_${band}`, limitsTier: PLAN_BAND_LIMITS_TIER[band] };
+}
+/**
+ * Public webhook ingress (repricing 2026-09, decision L4.4, ratified
+ * 2026-09-26): deliveries a minute that one webhook target (a Table endpoint,
+ * a workflow or Agent trigger, the workspace's RB2B receiver) accepts. It used
+ * to be a flat 600 per target, with 60 per sender IP on most targets. Every
+ * value rises, so this is live on release rather than held behind the
+ * repricing switch.
+ */
+export const PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE = Object.freeze({
+    free: 600,
+    "49": 1_500,
+    "99": 1_500,
+    "199": 3_000,
+    "499": 3_000,
+    "999": 6_000,
+    "1999": 12_000,
+});
+/**
+ * PROPOSED (P-50, repricing spec § 4.4): the decision raises the per-IP limit
+ * "to match", read as equal to the per-target limit (a share of 1). One sender
+ * (a form tool, a CRM) usually posts from one address, so any lower per-IP
+ * limit would cap a real integration below its plan's rate.
+ */
+export const PUBLIC_WEBHOOK_INGRESS_PER_IP_SHARE_OF_TARGET = 1;
+export const PUBLIC_WEBHOOK_INGRESS_WINDOW_SECONDS = 60;
+/** The webhook ingress limits a band enforces. */
+export function resolvePublicWebhookIngressLimits(band) {
+    const perTarget = PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE[band];
+    return {
+        perTargetPerMinute: perTarget,
+        perSenderIpPerMinute: Math.round(perTarget * PUBLIC_WEBHOOK_INGRESS_PER_IP_SHARE_OF_TARGET),
+        windowSeconds: PUBLIC_WEBHOOK_INGRESS_WINDOW_SECONDS,
+    };
+}
+/** The webhook ingress limits of one band, as the `/api/cli/limits` contract reports them. */
+export function describeWebhookIngress(band) {
+    const ingress = resolvePublicWebhookIngressLimits(band);
+    return {
+        ingress_requests_per_target_per_minute: ingress.perTargetPerMinute,
+        ingress_requests_per_sender_ip_per_minute: ingress.perSenderIpPerMinute,
+        window_seconds: ingress.windowSeconds,
+    };
+}
+/** The API rates a limits rung enforces, read from `PLAN_LIMITS`. */
+export function describeApiRateLimits(tier) {
+    const cli = planLimitsForTier(tier).cli;
+    return {
+        org_requests_per_minute: cli.global.orgRequestsPerMinute,
+        key_requests_per_minute: cli.global.keyRequestsPerMinute,
+        tenant_read_requests_per_key_per_minute: cli.tenantRead.requestsPerMinute,
+        tenant_write_requests_per_key_per_minute: cli.tenantWrite.requestsPerMinute,
+        // ai_live and tool_live are separate buckets with equal limits at every rung.
+        live_action_requests_per_key_per_minute: cli.toolLive.requestsPerMinute,
+        // Both org windows are hourly on every rung (pinned by plan-band.test.ts).
+        live_action_requests_per_org_per_hour: cli.toolLive.orgRequests.limit,
+        tool_dry_run_requests_per_key_per_minute: cli.toolDryRun.requestsPerMinute,
+        bulk_import_tables_per_org_per_hour: cli.bulkImport.orgRequests.limit,
+        rows_read_per_org: { rows: cli.tenantRead.orgUnits.limit, window_seconds: cli.tenantRead.orgUnits.windowSeconds },
+        rows_written_per_org: { rows: cli.tenantWrite.orgUnits.limit, window_seconds: cli.tenantWrite.orgUnits.windowSeconds },
+    };
+}
+function storageTarget(limits) {
+    return {
+        table_row_limit: limits.tableRowLimit,
+        workspace_row_limit: limits.workspaceRowLimit,
+        workspace_database_warning_bytes: limits.workspaceDatabaseWarningBytes,
+        workspace_database_limit_bytes: limits.workspaceDatabaseLimitBytes,
+        import_max_rows_per_file: limits.tableRowLimit,
+    };
+}
+/** A band's storage status as `/api/cli/limits` reports it (`plan_bands[].storage` and `storage_capacity`). */
+export function describePlanBandStorageStatus(band, options = {}) {
+    const status = describeWorkspaceTableCapacityStatus(band, options);
+    return {
+        status: status.status,
+        effective_at: status.effectiveAt?.toISOString() ?? null,
+        target: status.target ? storageTarget(status.target) : null,
+    };
+}
+export function describePlanBandLimits(band, options = {}) {
+    const limitsTier = PLAN_BAND_LIMITS_TIER[band];
+    const storage = resolveWorkspaceTableCapacity(band, options);
+    const limits = planLimitsForTier(limitsTier);
+    const monthlyPriceCents = planBandMonthlyPriceCents(band);
+    const monthlyCredits = band === "free"
+        ? null
+        : resolveBasePricingPlan(`oxygen_${band}`)?.monthlyCredits ?? null;
+    const dailyGuard = resolveOrgDailySpendGuard(monthlyCredits, { ...options, freePlan: band === "free" });
+    const agentLimits = resolvePlanAgentCreditLimits(limitsTier, options);
+    const copilotAllowance = copilotApprovalFreeAllowanceForBand(band);
+    return {
+        band,
+        label: planBandLabel(band),
+        monthly_price_usd: monthlyPriceCents === null ? null : monthlyPriceCents / 100,
+        monthly_credits: monthlyCredits,
+        volume_bonus_credits: band === "free" ? null : planVolumeBonusCredits(`oxygen_${band}`),
+        volume_bonus_percent: band === "free" ? null : planVolumeBonusPercent(`oxygen_${band}`),
+        usd_per_100_credits: monthlyPriceCents === null || !monthlyCredits
+            ? null
+            // Four decimals: $1,999 buys 229,885 credits, $0.8696 per 100.
+            : Math.round((monthlyPriceCents / monthlyCredits) * 10_000) / 10_000,
+        limits_tier: limitsTier,
+        api: describeApiRateLimits(limitsTier),
+        storage: {
+            table_row_limit: storage.tableRowLimit,
+            workspace_row_limit: storage.workspaceRowLimit,
+            workspace_database_warning_bytes: storage.workspaceDatabaseWarningBytes,
+            workspace_database_limit_bytes: storage.workspaceDatabaseLimitBytes,
+            import_max_rows_per_file: storage.tableRowLimit,
+            import_max_file_bytes: limits.import.maxFileBytes,
+            ...describePlanBandStorageStatus(band, options),
+        },
+        spend: {
+            trigger_run_credit_ceiling: resolveDefaultTriggerRunCreditCeilingForPlan(bandSpendResolution(band), options),
+            auto_run_batch_credit_ceiling: resolveDefaultAutoRunBatchCreditCeilingForPlan(bandSpendResolution(band), options),
+            agent_run_max_total_credits: agentLimits.maxTotalCredits,
+            agent_run_max_inference_credits: agentLimits.maxInferenceCredits,
+            copilot_approval_free_per_call_credits: copilotAllowance.perCallCredits,
+            copilot_approval_free_per_session_credits: copilotAllowance.perSessionCredits,
+            copilot_attended_turn_backstop_credits: COPILOT_ATTENDED_INFERENCE_CREDIT_CEILING,
+            org_daily_guard_warn_credits: dailyGuard?.warnCredits ?? null,
+            org_daily_guard_block_credits: dailyGuard?.blockCredits ?? null,
+            byok_column_run_max_rows: DEFAULT_BYOK_COLUMN_RUN_MAX_ROWS[limitsTier],
+            byok_provider_daily_calls: DEFAULT_BYOK_PROVIDER_DAILY_CALL_CAP[limitsTier],
+        },
+        tables: {
+            max_rows_per_write_request: limits.cli.maxWriteRowsPerRequest,
+            max_columns_per_run: limits.tableActions.maxActionsPerRun,
+        },
+        signals: {
+            max_events: limits.signals.maxEvents,
+            max_window_days: limits.signals.maxWindowDays,
+        },
+        webhooks: describeWebhookIngress(band),
+        workflows: {
+            cron_min_interval_minutes: resolveCronMinIntervalMinutes(limitsTier, options),
+        },
+    };
+}
+/** Every band's limits in force today, smallest first. */
+export function describePlanBandLadder(options = {}) {
+    return PLAN_BAND_ORDER.map((band) => describePlanBandLimits(band, options));
+}