plugins: Conditional primary metrics + Cursor credits balance (#68)

* feat(cursor): add credits balance retrieval and display in progress lines

- Introduced a new API endpoint to fetch credit grants balance.
- Updated the progress display to include credits usage alongside plan usage.
- Enhanced error handling for credit grants fetch failures.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(plugins): implement primary candidates for progress lines

- Updated plugin.json files to replace the "primary" flag with "primaryOrder" for defining primary metrics.
- Enhanced the cursor plugin to prioritize "Credits" in the display order when available.
- Adjusted the plugin types to support an array of primary candidates, allowing for more flexible metric selection.
- Updated tests to validate the new primary candidates functionality.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(cursor): update state database path for testing and adjust plan usage calculation

- Changed the state database path to a test location for debugging purposes.
- Updated the plan usage calculation to handle cases where totalSpend may not be directly available, ensuring accurate display of usage metrics.

* fix(cursor): update state database path for production use

- Changed the state database path to the production location for proper functionality.
- Removed the temporary test path comment for clarity.

* fix: address PR review feedback

- Fix trailing zeros dropped in currency formatting (C2): set minimumFractionDigits
  for non-integer values
- Add fail-loud null check for pu.limit (C3): throw explicit error when API
  response is missing required plan usage data instead of silently returning NaN
- Add tests for new validation paths

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: robinebers

plugins/claude/plugin.json

@@ -7,7 +7,7 @@
   "icon": "icon.svg",
   "brandColor": "#DE7356",
   "lines": [
-    { "type": "progress", "label": "Session", "scope": "overview", "primary": true },
+    { "type": "progress", "label": "Session", "scope": "overview", "primaryOrder": 1 },
     { "type": "progress", "label": "Weekly", "scope": "overview" },
     { "type": "progress", "label": "Sonnet", "scope": "detail" },
     { "type": "progress", "label": "Extra usage", "scope": "detail" }

plugins/codex/plugin.json

@@ -7,7 +7,7 @@
   "icon": "icon.svg",
   "brandColor": "#74AA9C",
   "lines": [
-    { "type": "progress", "label": "Session", "scope": "overview", "primary": true },
+    { "type": "progress", "label": "Session", "scope": "overview", "primaryOrder": 1 },
     { "type": "progress", "label": "Weekly", "scope": "overview" },
     { "type": "progress", "label": "Reviews", "scope": "detail" },
     { "type": "progress", "label": "Credits", "scope": "detail" }

plugins/cursor/plugin.js

@@ -5,6 +5,7 @@
   const USAGE_URL = BASE_URL + "/aiserver.v1.DashboardService/GetCurrentPeriodUsage"
   const PLAN_URL = BASE_URL + "/aiserver.v1.DashboardService/GetPlanInfo"
   const REFRESH_URL = BASE_URL + "/oauth/token"
+  const CREDITS_URL = BASE_URL + "/aiserver.v1.DashboardService/GetCreditGrantsBalance"
   const CLIENT_ID = "KbZUR41cY7W6zRSdpSUJ7I7mLYBKOCmB"
   const REFRESH_BUFFER_MS = 5 * 60 * 1000 // refresh 5 minutes before expiration
 
@@ -237,6 +238,16 @@
       ctx.host.log.warn("plan info fetch failed: " + String(e))
     }
 
+    let creditGrants = null
+    try {
+      const creditsResp = connectPost(ctx, CREDITS_URL, accessToken)
+      if (creditsResp.status >= 200 && creditsResp.status < 300) {
+        creditGrants = ctx.util.tryParseJson(creditsResp.bodyText)
+      }
+    } catch (e) {
+      ctx.host.log.warn("credit grants fetch failed: " + String(e))
+    }
+
     let plan = null
     if (planName) {
       const planLabel = ctx.fmt.planLabel(planName)
@@ -247,9 +258,32 @@
 
     const lines = []
     const pu = usage.planUsage
+
+    // Credits first (if available) - highest priority primary metric
+    if (creditGrants && creditGrants.hasCreditGrants === true) {
+      const total = parseInt(creditGrants.totalCents, 10)
+      const used = parseInt(creditGrants.usedCents, 10)
+      if (total > 0 && !isNaN(total) && !isNaN(used)) {
+        lines.push(ctx.line.progress({
+          label: "Credits",
+          used: ctx.fmt.dollars(used),
+          limit: ctx.fmt.dollars(total),
+          format: { kind: "dollars" },
+        }))
+      }
+    }
+
+    // Plan usage (always present) - fallback primary metric
+    // API may return totalSpend directly, or we calculate from limit - remaining
+    if (typeof pu.limit !== "number") {
+      throw "Plan usage limit missing from API response."
+    }
+    const planUsed = typeof pu.totalSpend === "number"
+      ? pu.totalSpend
+      : pu.limit - (pu.remaining ?? 0)
     lines.push(ctx.line.progress({
       label: "Plan usage",
-      used: ctx.fmt.dollars(pu.totalSpend),
+      used: ctx.fmt.dollars(planUsed),
       limit: ctx.fmt.dollars(pu.limit),
       format: { kind: "dollars" },
       resetsAt: ctx.util.toIso(usage.billingCycleEnd),
@@ -259,6 +293,7 @@
       lines.push(ctx.line.text({ label: "Bonus spend", value: "$" + String(ctx.fmt.dollars(pu.bonusSpend)) }))
     }
 
+    // On-demand (if available) - not a primary candidate
     const su = usage.spendLimitUsage
     if (su) {
       const limit = su.individualLimit ?? su.pooledLimit ?? 0

plugins/cursor/plugin.json

@@ -7,7 +7,8 @@
   "icon": "icon.svg",
   "brandColor": "#000000",
   "lines": [
-    { "type": "progress", "label": "Plan usage", "scope": "overview", "primary": true },
+    { "type": "progress", "label": "Credits", "scope": "overview", "primaryOrder": 1 },
+    { "type": "progress", "label": "Plan usage", "scope": "overview", "primaryOrder": 2 },
     { "type": "progress", "label": "On-demand", "scope": "detail" }
   ]
 }

plugins/cursor/plugin.test.js

@@ -51,6 +51,38 @@ describe("cursor plugin", () => {
     expect(() => plugin.probe(ctx)).toThrow("Usage tracking disabled")
   })
 
+  it("throws on missing plan usage limit", async () => {
+    const ctx = makeCtx()
+    ctx.host.sqlite.query.mockReturnValue(JSON.stringify([{ value: "token" }]))
+    ctx.host.http.request.mockReturnValue({
+      status: 200,
+      bodyText: JSON.stringify({
+        enabled: true,
+        planUsage: { totalSpend: 1200 }, // missing limit
+      }),
+    })
+    const plugin = await loadPlugin()
+    expect(() => plugin.probe(ctx)).toThrow("Plan usage limit missing")
+  })
+
+  it("calculates planUsed from limit - remaining when totalSpend missing", async () => {
+    const ctx = makeCtx()
+    ctx.host.sqlite.query.mockReturnValue(JSON.stringify([{ value: "token" }]))
+    ctx.host.http.request.mockReturnValue({
+      status: 200,
+      bodyText: JSON.stringify({
+        enabled: true,
+        planUsage: { limit: 2400, remaining: 1200 }, // no totalSpend
+      }),
+    })
+    const plugin = await loadPlugin()
+    const result = plugin.probe(ctx)
+    const planLine = result.lines.find((l) => l.label === "Plan usage")
+    expect(planLine).toBeTruthy()
+    // used = limit - remaining = 2400 - 1200 = 1200
+    expect(planLine.used).toBe(12) // ctx.fmt.dollars divides by 100
+  })
+
   it("renders usage + plan info", async () => {
     const ctx = makeCtx()
     ctx.host.sqlite.query.mockReturnValue(JSON.stringify([{ value: "token" }]))
@@ -182,6 +214,71 @@ describe("cursor plugin", () => {
     expect(result.lines.find((line) => line.label === "Plan usage")).toBeTruthy()
   })
 
+  it("outputs Credits first when available", async () => {
+    const ctx = makeCtx()
+    ctx.host.sqlite.query.mockReturnValue(JSON.stringify([{ value: "token" }]))
+    ctx.host.http.request.mockImplementation((opts) => {
+      if (String(opts.url).includes("GetCurrentPeriodUsage")) {
+        return {
+          status: 200,
+          bodyText: JSON.stringify({
+            enabled: true,
+            planUsage: { totalSpend: 1200, limit: 2400 },
+            spendLimitUsage: { individualLimit: 5000, individualRemaining: 1000 },
+          }),
+        }
+      }
+      if (String(opts.url).includes("GetCreditGrantsBalance")) {
+        return {
+          status: 200,
+          bodyText: JSON.stringify({
+            hasCreditGrants: true,
+            totalCents: 10000,
+            usedCents: 500,
+          }),
+        }
+      }
+      return { status: 200, bodyText: "{}" }
+    })
+    const plugin = await loadPlugin()
+    const result = plugin.probe(ctx)
+    
+    // Credits should be first in the lines array
+    expect(result.lines[0].label).toBe("Credits")
+    expect(result.lines[1].label).toBe("Plan usage")
+    // On-demand should come after
+    const onDemandIndex = result.lines.findIndex((l) => l.label === "On-demand")
+    expect(onDemandIndex).toBeGreaterThan(1)
+  })
+
+  it("outputs Plan usage first when Credits not available", async () => {
+    const ctx = makeCtx()
+    ctx.host.sqlite.query.mockReturnValue(JSON.stringify([{ value: "token" }]))
+    ctx.host.http.request.mockImplementation((opts) => {
+      if (String(opts.url).includes("GetCurrentPeriodUsage")) {
+        return {
+          status: 200,
+          bodyText: JSON.stringify({
+            enabled: true,
+            planUsage: { totalSpend: 1200, limit: 2400 },
+          }),
+        }
+      }
+      if (String(opts.url).includes("GetCreditGrantsBalance")) {
+        return {
+          status: 200,
+          bodyText: JSON.stringify({ hasCreditGrants: false }),
+        }
+      }
+      return { status: 200, bodyText: "{}" }
+    })
+    const plugin = await loadPlugin()
+    const result = plugin.probe(ctx)
+    
+    // Plan usage should be first when Credits not available
+    expect(result.lines[0].label).toBe("Plan usage")
+  })
+
   it("refreshes token when expired and persists new access token", async () => {
     const ctx = makeCtx()
 

plugins/mock/plugin.json

@@ -9,7 +9,7 @@
   "lines": [
     { "type": "text", "label": "Config", "scope": "overview" },
     { "type": "badge", "label": "Case", "scope": "overview" },
-    { "type": "progress", "label": "Percent", "scope": "overview" },
+    { "type": "progress", "label": "Percent", "scope": "overview", "primaryOrder": 1 },
     { "type": "progress", "label": "Dollars", "scope": "detail" },
     { "type": "text", "label": "Now", "scope": "detail" },
     { "type": "badge", "label": "Warning", "scope": "detail" }

src-tauri/src/lib.rs

@@ -27,7 +27,9 @@ pub struct PluginMeta {
     pub icon_url: String,
     pub brand_color: Option<String>,
     pub lines: Vec<ManifestLineDto>,
-    pub primary_progress_label: Option<String>,
+    /// Ordered list of primary metric candidates (sorted by primaryOrder).
+    /// Frontend picks the first one that exists in runtime data.
+    pub primary_candidates: Vec<String>,
 }
 
 #[derive(Debug, Clone, Serialize)]
@@ -214,12 +216,16 @@ fn list_plugins(state: tauri::State<'_, Mutex<AppState>>) -> Vec<PluginMeta> {
     plugins
         .into_iter()
         .map(|plugin| {
-            let primary_progress_label = plugin
+            // Extract primary candidates: progress lines with primary_order, sorted by order
+            let mut candidates: Vec<_> = plugin
                 .manifest
                 .lines
                 .iter()
-                .find(|line| line.primary && line.line_type == "progress")
-                .map(|line| line.label.clone());
+                .filter(|line| line.line_type == "progress" && line.primary_order.is_some())
+                .collect();
+            candidates.sort_by_key(|line| line.primary_order.unwrap());
+            let primary_candidates: Vec<String> =
+                candidates.iter().map(|line| line.label.clone()).collect();
 
             PluginMeta {
                 id: plugin.manifest.id,
@@ -236,7 +242,7 @@ fn list_plugins(state: tauri::State<'_, Mutex<AppState>>) -> Vec<PluginMeta> {
                         scope: line.scope.clone(),
                     })
                     .collect(),
-                primary_progress_label,
+                primary_candidates,
             }
         })
         .collect()