feat: Enhance MetricLine with periodDurationMs for pace tracking

- Added periodDurationMs field to MetricLine in API and schema documentation.
- Updated progress line implementation to utilize the new periodDurationMs for pace tracking.
- Clarified documentation on how periodDurationMs interacts with resetsAt for usage metrics.

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

docs/plugins/api.md

@@ -312,6 +312,7 @@ ctx.line.progress({
     suffix?: string                 // Required when kind="count" (e.g. "credits")
   },
   resetsAt?: string | null,         // Optional: ISO timestamp for when usage resets
+  periodDurationMs?: number,        // Optional: period length in ms for pace tracking
   color?: string,                   // Optional: hex color for progress bar
 }): MetricLine
 ```
@@ -321,6 +322,7 @@ Notes:
 - `used` may exceed `limit` (overages).
 - For `format.kind: "percent"`, `limit` must be `100`.
 - Prefer setting `resetsAt` (via `ctx.util.toIso(...)`) instead of putting reset info in other lines.
+- `periodDurationMs`: when provided with `resetsAt`, enables the pace tracking indicator (shows if usage rate will exhaust quota before reset).
 
 **Example:**
 

docs/plugins/schema.md

@@ -147,6 +147,7 @@ type MetricLine =
         | { kind: "dollars" }
         | { kind: "count"; suffix: string };
       resetsAt?: string; // ISO timestamp
+      periodDurationMs?: number; // period length in ms for pace tracking
       color?: string;
     }
   | { type: "badge"; label: string; text: string; color?: string; subtitle?: string }
@@ -155,6 +156,7 @@ type MetricLine =
 - `color`: optional hex string (e.g. `#22c55e`)
 - `subtitle`: optional text displayed below the line in smaller muted text
 - `resetsAt`: optional ISO timestamp (UI shows "Resets in ..." automatically)
+- `periodDurationMs`: optional period length in milliseconds (enables pace indicator when combined with `resetsAt`)
 
 ### Text Line
 

plugins/codex/plugin.js

@@ -273,18 +273,13 @@
       if (reviewWindow) {
         const used = reviewWindow.used_percent
         if (typeof used === "number") {
-          // Use reset_after_seconds if available, otherwise fall back to session duration
-          var reviewPeriodMs = PERIOD_SESSION_MS
-          if (typeof reviewWindow.reset_after_seconds === "number") {
-            reviewPeriodMs = reviewWindow.reset_after_seconds * 1000
-          }
           lines.push(ctx.line.progress({
             label: "Reviews",
             used: used,
             limit: 100,
             format: { kind: "percent" },
             resetsAt: getResetsAtIso(ctx, nowSec, reviewWindow),
-            periodDurationMs: reviewPeriodMs
+            periodDurationMs: PERIOD_SESSION_MS
           }))
         }
       }