| name | tiered-plan-limits |
| description | Set per-plan caps, quotas, limits, and compute sizes in Companion's billing tiers by deriving the numbers from the existing price/credit ladder, not by inventing round or evenly-doubling numbers. Load when adding or changing a per-tier quantity (automations cap, storage, rate limit, feature quota, or per-plan compute/runtime sizing like vCPU/RAM or sandbox template) or editing PLAN_TIERS / COMPUTER_RUNTIME_TIERS in src/lib/billing/constants.ts. Not for one-off non-tiered constants. |
Tiered plan limits
Problem this handles
When you add a per-tier quantity to a pricing system (a cap, quota, or limit
that differs by plan), the tiers already encode a ratio in their price and
credits. Inventing round numbers (10 / 25 / 100) that look reasonable but
break that ratio is a real, observed failure: shipping maxAutomations at
Plus 10 / Pro 25 / Max 100 drew "did u not see pricing for each plan why is the
multiple off" — because every other field scales 5× then 2×, but 25 is 2.5× of
10. The value was corrected to Pro 50 to restore the ladder.
Activation boundary
Load when: adding or changing a field in PLAN_TIERS or
COMPUTER_RUNTIME_TIERS (src/lib/billing/constants.ts); building a plan gate;
picking a per-plan cap, quota, storage size, rate limit, feature count, or
compute/runtime size (vCPU, RAM, sandbox/E2B template per plan); reviewing such
a change.
Near-misses (do not load): a single non-tiered constant; pricing copy with no
quantitative tier ladder; a flat limit that is identical across all plans.
Procedure
- Open
src/lib/billing/constants.ts and read PLAN_TIERS. Add the new limit
as a sibling field on PlanTierSpec, in the same source of truth as
monthlyDollars / includedCredits — not a separate parallel constant.
- Compute the existing ladder from the fields that already scale with value —
monthlyDollars and includedCredits. As of writing: Plus $20 / 2000cr,
Pro $100 / 10000cr, Max $200 / 20000cr → Plus→Pro = 5×, Pro→Max = 2×.
Re-derive these from the file each time; don't trust this snapshot.
- Set the new field to follow that ladder unless there is a stated product
reason not to. If the limit should follow a different curve (flat cap,
diminishing returns, a hard technical ceiling like Max's storage), say so
explicitly and confirm the curve with the user before shipping — do not
silently pick round numbers.
- Enforce at the single choke point, mirroring
maxAutomationsForPlan →
scheduleTaskForCurrentChat, so both creation paths pass through one gate.
- In your report, state the multiple you used (e.g. "5×/2×, matching price and
credits") so the user can sanity-check the ratio at a glance.
Gotchas
- Roundness is a trap. 10 / 25 / 100 reads as a clean ladder but isn't; anchor
on the ratio the other fields use, not on numbers ending in 0 or 5.
- Evenly doubling every tier is the same trap in disguise. A neat 2×/2× ladder
(Plus 2 vCPU / 2 GiB, Pro 4 / 4, Max 8 / 8) is not the price/credit ladder,
which is 5×/2×. Compute and hardware may legitimately follow a flatter curve
than price — but that is a deviating curve, so state it and confirm with the
user before shipping; do not present the doubled ladder as the obvious plan.
Shipping
COMPUTER_RUNTIME_TIERS at 2/4/8 vCPU drew an immediate user
correction that per-tier doubling was the wrong ladder, and was re-sized to
1 / 2 / 4 vCPU.
- Paused / inactive items count toward caps — pausing must not free a slot
(see the
maxAutomations comment in PlanTierSpec).
emailStorageMb does not scale uniformly (1000 / 25000 / 100000) — confirm
which sibling fields actually share the ladder before copying a ratio; price
and credits are the reliable anchor, storage is bespoke.
Verification
- Assert the new field's adjacent-tier ratios equal the
monthlyDollars /
includedCredits ratios, or that any deviation was explicitly user-approved.
- Exercise the gate live where cheap; where the cap is too high to hit on
staging, say the cap-exceeded branch is unverified rather than implying it.
Sources
src/lib/billing/constants.ts:71-107 — PlanTierSpec, PLAN_TIERS,
maxAutomationsForPlan, baseTierFor.src/lib/billing/constants.ts:107-159 — COMPUTER_RUNTIME_TIERS,
computerRuntimeTierForPlan (per-plan vCPU/RAM and sandbox template).- Trigger transcript c11d13a6 (2026-06-11): shipped 10/25/100, user flagged
the broken multiple; corrected to 10/50/100.
- Trigger transcript 019ec299 (2026-06-13): sized per-plan computer runtime as a
neat 2/4/8 vCPU (2×/2×) ladder; user flagged the doubling, re-sized to 1/2/4.
