@magpie-community/opencode-cursor-auth 0.2.31 → 0.2.33

package/README.md

@@ -240,6 +240,11 @@ go without the list for 5 minutes instead of each waiting for it again.
 ## Usage
 
 magpie shows Cursor Models, Other Models and Total for the billing period.
+A plan of Cursor's merged billing (`GetPlanInfo`'s `isMerged`, the newer
+plans) has no Other Models pool: its included usage is one allowance every
+model draws on, as the dashboard's "Weekly usage limit" shows it. magpie
+shows that as one window, Weekly (Monthly on a monthly plan), for every
+model.
 Accounts with a Grok Bot allowance also show its usage and reset time;
 active trials are labelled separately. A spent Bot allowance doesn't stop
 Cursor requests.
@@ -254,6 +259,19 @@ own spends the team's pool: On-demand shows the pool's spend and limit,
 with the member's own spend beside it, and the account is used up when
 the pool is.
 
+Free credit shows too, as Cursor's own IDE reads it. The plan's bonus
+("+$X free usage on us", `GetCurrentPeriodUsage`'s `bonusSpend` and
+`remainingBonus`) is Free usage: what was spent from it this period, and
+whether more is left; Cursor gives no amount for it. Each credit grant
+(`GetUsageLimitStatusAndActiveGrants`' `activeGrants`, the IDE's "Use your
+$X free credits") is a window of its own, named by its campaign: spent of
+total, when it expires, and its limits. A grant limited to some models
+lists them; one only Cursor's Cloud Agents (or another client) may spend
+says so in its name, since magpie talks as `cursor-agent`. While a bonus
+or a grant magpie can spend has some left, a spent included pool doesn't
+count the account used up for the models it pays for. With "Included
+usage only" on, free credit is shown only.
+
 An Enterprise account's period has no Cursor Models, Other Models or Total
 in `GetCurrentPeriodUsage`: Cursor reports its overall allowance through
 the website's `usage-summary` instead. Magpie shows that as Enterprise,
@@ -273,8 +291,8 @@ In magpie, open the Cursor provider, turn on **Included usage only** under
 applies to every Cursor account, and takes effect at each account's next
 usage reading.
 
-When on, Cursor Models and Other Models (an Enterprise account's allowance)
-are what keep an account in routing: once one is used up, magpie moves its
+When on, Cursor Models and Other Models (a merged plan's Weekly, an
+Enterprise account's allowance) are what keep an account in routing: once one is used up, magpie moves its
 models to the next account until the period resets, even when on-demand
 could still pay for them. On-demand and Total are still shown but never
 keep an account in routing. Use it when on-demand is a shared or paid pool

package/index.mjs

@@ -316,18 +316,27 @@ async function whoIs(tok) {
 
 // plans are the plan each token's account is on, as `cursor-agent about`
 // names it (GetPlanInfo's planName, magpie's card title), asked again after
-// an hour.
+// an hour. merged is GetPlanInfo's isMerged: a plan of Cursor's merged
+// (xAI) billing, whose included usage is one allowance for every model,
+// most of them a week long (includedUsagePeriod), and has no Other Models
+// pool (majiang_ai on X). The dashboard's usage page shows such a plan one
+// meter, the period's totalPercentUsed. period is "weekly", "monthly" or
+// "" (not said). A reply that couldn't be read keeps the last one, else
+// says nothing: undefined merged, which the pools are kept for.
 const plans = new Map()
 const PLAN_TTL = 3600_000
+const PERIODS = { INCLUDED_USAGE_PERIOD_WEEKLY: "weekly", INCLUDED_USAGE_PERIOD_MONTHLY: "monthly", 1: "monthly", 2: "weekly" }
 async function planOf(tok) {
   const had = plans.get(tok)
-  if (had && Date.now() - had.at < PLAN_TTL) return had.plan
+  if (had && Date.now() - had.at < PLAN_TTL) return had
   try {
-    const plan = String((await unary(API, "aiserver.v1.DashboardService/GetPlanInfo", tok))?.planInfo?.planName ?? "").trim()
-    if (plan) plans.set(tok, { plan, at: Date.now() })
-    return plan || had?.plan || ""
+    const info = await unary(API, "aiserver.v1.DashboardService/GetPlanInfo", tok)
+    const plan = String(info?.planInfo?.planName ?? "").trim()
+    const got = { plan: plan || had?.plan || "", merged: info?.isMerged === true, period: PERIODS[info?.planInfo?.includedUsagePeriod] ?? "", at: Date.now() }
+    if (plan || got.merged) plans.set(tok, got)
+    return got
   } catch {
-    return had?.plan ?? ""
+    return had ?? { plan: "" }
   }
 }
 
@@ -532,6 +541,99 @@ async function hardLimit(tok) {
 // dollars, thousands grouped: a team's pool runs to six figures ($451,200.00)
 const dollars = (n) => "$" + n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })
 
+// ---- free credit ------------------------------------------------------------------
+//
+// Cursor gives free usage two ways (CryptoSarom on X, "赠金"), as Cursor
+// 3.x's own client reads them:
+//
+// - the plan's bonus, "+$X free usage on us" under the included usage in
+//   the IDE's usage tooltip: GetCurrentPeriodUsage's planUsage.bonusSpend
+//   (cents spent from it this period), remainingBonus (whether any is
+//   left; no amount is given) and bonusTooltip ("We work with model
+//   providers to give you free usage beyond what you've purchased. Amounts
+//   may vary."). It isn't tied to a model.
+// - credit grants, the IDE's "Use your $X free … credits" banner:
+//   DashboardService/GetUsageLimitStatusAndActiveGrants' activeGrants, each
+//   with totalCents and remainingCents (int64 strings), expiresAtMs, and
+//   its limits: allowedModelIds, allowedModelTags and allowedModelSelections
+//   (the models it may be spent on; none listed is every model) and
+//   allowedClientTypes (the clients that may spend it; none listed is any;
+//   "glass" without "ide" is the IDE's Cloud Agent credits). magpie talks
+//   as cursor-agent, clientType "cli".
+//
+// creditGrants is that reply's activeGrants, [] when it couldn't be read.
+async function creditGrants(tok) {
+  try {
+    const res = await fetch(API + "/aiserver.v1.DashboardService/GetUsageLimitStatusAndActiveGrants", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${tok}`, "Content-Type": "application/json", "Connect-Protocol-Version": "1", ...await teamHeader(tok) },
+      body: "{}",
+      signal: AbortSignal.timeout(15_000),
+    })
+    if (!res.ok) return []
+    const g = (await res.json())?.activeGrants
+    return Array.isArray(g) ? g : []
+  } catch {
+    return []
+  }
+}
+
+// tagOf is a model name as the IDE matches a grant's allowedModelTags to
+// it: lower case, "-" read as "."; a tag matches a name it is part of.
+const tagOf = (s) => String(s).toLowerCase().replace(/-/g, ".")
+
+// credits are the windows of the account's free credit, and what it lets
+// Cursor go on serving once the included usage is spent: all (a bonus or
+// grant magpie can spend on every model still has some left) and covers
+// (the account's model ids a grant limited to some models still pays
+// for). Every credit window is shown only: what stops an account is the
+// included usage it outlasts, which usage() sets aside. plan is
+// planUsage, resets its period's end, ids the account's model ids.
+function credits(plan, grants, ids, resets, now = Date.now()) {
+  const windows = []
+  const covers = new Set()
+  let all = false
+  const bonus = Number(plan?.bonusSpend ?? 0) / 100
+  if (bonus > 0 || plan?.remainingBonus === true) {
+    windows.push({ name: "Free usage", used: 0, display: `+${dollars(bonus)} on us` + (plan?.remainingBonus === true ? ", more left" : ""), ...resets, aside: true })
+    if (plan?.remainingBonus === true) all = true
+  }
+  for (const g of grants) {
+    const total = Number(g?.totalCents ?? 0) / 100
+    const left = Math.max(0, Number(g?.remainingCents ?? 0) / 100)
+    if (!(total > 0) || !Number.isFinite(total) || !Number.isFinite(left)) continue
+    const exp = Number(g.expiresAtMs ?? 0)
+    if (exp > 0 && exp <= now) continue
+    const clients = (g.allowedClientTypes ?? []).map(String)
+    const mine = clients.length === 0 || clients.includes("cli")
+    const named = [...(g.allowedModelIds ?? []), ...(g.allowedModelSelections ?? []).map((m) => m?.modelId).filter(Boolean)].map(String)
+    const tags = (g.allowedModelTags ?? []).map(String)
+    const limited = named.length > 0 || tags.length > 0
+    const bases = new Set(named.map((m) => (poolBase(m) === "auto" ? "default" : poolBase(m))))
+    const fits = (id) => {
+      const b = poolBase(id) === "auto" ? "default" : poolBase(id)
+      return bases.has(b) || tags.some((t) => tagOf(id).includes(tagOf(t)))
+    }
+    const matched = limited ? ids.filter(fits) : []
+    const name = (String(g.campaignName ?? "").trim() || "Free credit") + (mine ? "" : clients.includes("glass") && !clients.includes("ide") ? " (Cloud Agents only)" : ` (${clients.join(", ")} only)`)
+    windows.push({
+      name,
+      used: Math.max(0, Math.min(100, (100 * (total - left)) / total)),
+      display: `${dollars(total - left)} / ${dollars(total)}`,
+      amount: total - left,
+      limit: total,
+      unit: "USD",
+      ...(exp > 0 ? { runsOutAt: new Date(exp).toISOString(), runsOut: left } : {}),
+      ...(limited ? { models: matched.length ? matched : [...named, ...tags] } : {}),
+      aside: true,
+    })
+    if (!mine || !(left > 0)) continue
+    if (!limited) all = true
+    else for (const id of matched) covers.add(id)
+  }
+  return { windows, all, covers }
+}
+
 // INCLUDED_ONLY is the switch (magpie's plugin options, off by default)
 // that keeps an account in routing only while its included usage lasts
 // (magpie-community/plugins#485): on, the included pools (Cursor Models and
@@ -617,7 +719,9 @@ async function enterpriseUsage(tok, includedOnly = false) {
 // the pools are the allowance whatever on-demand allows, and On-demand is
 // shown only. An Enterprise account's period has no planUsage; its
 // allowance comes from usage-summary instead.
-async function usage(tok, ids, includedOnly = false) {
+// plan is planOf's answer, asked alongside (a promise): a merged plan's
+// included usage is one window, Weekly on a weekly plan, for every model.
+async function usage(tok, ids, includedOnly = false, plan = undefined) {
   const [res, hard] = await Promise.all([
     fetch(API + "/aiserver.v1.DashboardService/GetCurrentPeriodUsage", {
       method: "POST",
@@ -627,13 +731,14 @@ async function usage(tok, ids, includedOnly = false) {
     }),
     hardLimit(tok),
   ])
+  const grants = creditGrants(tok)
   if (!res.ok) return { error: statusText(res.status), windows: [] }
   const data = await res.json()
   const u = data?.planUsage
   if (!u) {
     // Prefer measured Enterprise usage before any reset-date-only fallback.
     const windows = await enterpriseUsage(tok, includedOnly)
-    return windows ? { windows } : { windows: [] }
+    return { windows: windows ?? [], credits: credits(undefined, await grants, ids, {}).windows }
   }
   const ms = /^[+-]?\d+$/.test(data.billingCycleEnd ?? "") ? Number(data.billingCycleEnd) : 0
   const resets = ms > 0 ? { resetsAt: new Date(ms).toISOString() } : {}
@@ -654,21 +759,50 @@ async function usage(tok, ids, includedOnly = false) {
   const pool = [...new Set(["auto", ...asked, ...(data.autoBucketModels ?? [])])].filter(inPool)
   const num = (v) => (typeof v === "number" ? v : 0)
   const od = onDemandOf(data, hard)
-  const pooled = !includedOnly && (od.kind === "fixed" || od.kind === "unlimited") ? { aside: true } : {}
+  // free credit that magpie can spend on every model keeps the account
+  // served past its included usage, as on-demand that can pay does; one
+  // limited to some models keeps those models served past a spent pool.
+  // Neither does with includedOnly.
+  const free = credits(u, await grants, [...new Set(asked)], resets)
+  const pooled = !includedOnly && (od.kind === "fixed" || od.kind === "unlimited" || free.all) ? { aside: true } : {}
+  const covers = includedOnly ? new Set() : free.covers
   const onDemand =
     od.kind === "fixed"
-      ? [{ name: "On-demand", used: Math.max(0, Math.min(100, (100 * od.usedDollars) / od.limitDollars)), display: `${dollars(od.usedDollars)} / ${dollars(od.limitDollars)}` + (od.mineDollars === undefined ? "" : ` (you: ${dollars(od.mineDollars)})`), ...resets, ...(includedOnly ? { aside: true } : {}) }]
+      ? [{ name: "On-demand", used: Math.max(0, Math.min(100, (100 * od.usedDollars) / od.limitDollars)), display: `${dollars(od.usedDollars)} / ${dollars(od.limitDollars)}` + (od.mineDollars === undefined ? "" : ` (you: ${dollars(od.mineDollars)})`), ...resets, ...(includedOnly || free.all ? { aside: true } : {}) }]
       : od.kind === "unlimited"
         ? [{ name: "On-demand", used: 0, display: dollars(od.usedDollars), ...resets, aside: true }]
         : []
-  // the two pools fit the line; the total goes in its tooltip
+  // A merged plan has no pools: its included usage is one allowance every
+  // model draws on, which the dashboard shows as the period's
+  // totalPercentUsed, autoPercentUsed the same and apiPercentUsed 0 always.
+  const info = await plan
+  // spent is whether a pool no longer pays: then the models a credit still
+  // pays for are left out of it
+  const spent = (used) => covers.size > 0 && !pooled.aside && used >= 100
+  if (info?.merged === true) {
+    const weekly = info.period === "weekly"
+    const used = num(u.totalPercentUsed)
+    return {
+      windows: [
+        { name: weekly ? "Weekly" : info.period === "monthly" ? "Monthly" : "Included", used, ...resets, ...(weekly ? { span: 604800 } : {}), ...(spent(used) ? { notModels: [...covers] } : {}), ...pooled },
+        ...onDemand,
+      ],
+      credits: free.windows,
+    }
+  }
+  // the two pools fit the line; the total goes in its tooltip. A spent
+  // Cursor Models pool every model of which a credit pays for is aside:
+  // an empty models list would count every model.
+  const auto = num(u.autoPercentUsed), api = num(u.apiPercentUsed)
+  const cursorModels = spent(auto) ? pool.filter((m) => !covers.has(m)) : pool
   return {
     windows: [
-      { name: "Cursor Models", used: num(u.autoPercentUsed), ...resets, models: pool, ...pooled },
-      { name: "Other Models", used: num(u.apiPercentUsed), ...resets, notModels: pool, ...pooled },
+      { name: "Cursor Models", used: auto, ...resets, models: cursorModels.length ? cursorModels : pool, ...(cursorModels.length ? pooled : { aside: true }) },
+      { name: "Other Models", used: api, ...resets, notModels: spent(api) ? [...new Set([...pool, ...covers])] : pool, ...pooled },
       ...onDemand,
       { name: "Total", used: num(u.totalPercentUsed), ...resets, aside: true },
     ],
+    credits: free.windows,
   }
 }
 
@@ -3233,7 +3367,7 @@ export async function CursorAuthPlugin(input) {
           key: INCLUDED_ONLY,
           label: "Included usage only",
           description:
-            "Keeps an account in routing only while its included usage lasts: once Cursor Models or Other Models is used up, magpie moves those models to the next account until the period resets, even if on-demand could pay. On-demand and Total are still shown but never keep an account in routing.",
+            "Keeps an account in routing only while its included usage lasts: once an included pool (Cursor Models, Other Models, a newer plan's Weekly) is used up, magpie moves its models to the next account until it resets, even if on-demand or free credit could pay.",
         },
       ],
       // magpie's: how much of the plan's included usage is gone (the plan
@@ -3246,14 +3380,17 @@ export async function CursorAuthPlugin(input) {
         } catch (e) {
           return { error: e.message, windows: [], signIn: "kept" }
         }
-        const [u, plan, bot] = await Promise.all([usage(tok, Object.keys(provider?.models ?? {}), includedOnly()), planOf(tok), botUsage(tok)])
+        const info = planOf(tok)
+        const [u, { plan }, bot] = await Promise.all([usage(tok, Object.keys(provider?.models ?? {}), includedOnly(), info), info, botUsage(tok)])
         // Bot goes among magpie's three menu-bar rings: before Total, and
         // before an On-demand with no limit, which is only a dollar figure on
         // a ring that never fills (magpie #2213, Morganwan90). An On-demand
         // with a limit stays ahead of it: that is what can stop the account.
+        // Free credit goes after them, with Total: it is shown only.
         const last = (w) => w.name === "Total" || (w.name === "On-demand" && w.aside)
-        const windows = [...u.windows.filter((w) => !last(w)), ...bot, ...u.windows.filter(last)]
-        return { ...u, windows, ...(plan ? { plan } : {}), signIn: "kept" }
+        const { credits: free = [], ...read } = u
+        const windows = [...read.windows.filter((w) => !last(w)), ...bot, ...free, ...read.windows.filter(last)]
+        return { ...read, windows, ...(plan ? { plan } : {}), signIn: "kept" }
       },
     },
     // the session the request is part of, for the conversation_id
@@ -3295,4 +3432,4 @@ export async function CursorAuthPlugin(input) {
 }
 
 // for tests
-export const _internal = { kvReply, listFor, lists, keychain, keychainToken, nativeTransport, onDemandOf,resetH1: () => (h1Until = 0), onH1: () => Date.now() < h1Until, resetTeam: () => { teamRead.at = 0; teamRead.info = null }, expireTeam: () => (teamRead.at = 0),H2, H1, h2Blocked, open, openH1, openH2, STEP_WAIT, stepUsage, usageKey, ledger, owed, flights, misses, unreadable, catalog, usable, request, modelsOf, tokensOf, maxRequired, conversationID, usageOf, sessionOf, SESSION, errorResponse, kept, poolBase, conversation, buildRun, decode, exec, fields, pb, pbValue, pbAny, frame, frames, failure, toolsOf, expiry }
+export const _internal = { credits, kvReply, listFor, lists, keychain, keychainToken, nativeTransport, onDemandOf,resetH1: () => (h1Until = 0), onH1: () => Date.now() < h1Until, resetTeam: () => { teamRead.at = 0; teamRead.info = null }, expireTeam: () => (teamRead.at = 0),H2, H1, h2Blocked, open, openH1, openH2, STEP_WAIT, stepUsage, usageKey, ledger, owed, flights, misses, unreadable, catalog, usable, request, modelsOf, tokensOf, maxRequired, conversationID, usageOf, sessionOf, SESSION, errorResponse, kept, poolBase, conversation, buildRun, decode, exec, fields, pb, pbValue, pbAny, frame, frames, failure, toolsOf, expiry }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpie-community/opencode-cursor-auth",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "description": "Cursor subscriptions (Pro, Pro+, Ultra, Teams) in OpenCode and magpie, through the API cursor-agent talks to",
   "type": "module",
   "main": "./index.mjs",