@llblab/pi-codex-usage 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.8.0: Spark Model Usage Status
+
+- Added active-bucket status support for `GPT-5.3-Codex-Spark`. Impact: selecting the Spark Codex subscription model now shows the parallel Spark rate-limit bucket with a `spark` label, while regular Codex models keep the existing `codex` bucket/status behavior.
+- Added parsing for backend `additional_rate_limits`, including the Spark `GPT-5.3-Codex-Spark` / `codex_bengalfox` limit. Impact: Spark quota can be shown from the same Pi-auth usage response path as normal Codex quota instead of relying only on app-server fallback.
+
 ## 0.7.0: Exhausted Quota Visibility
 
 - Added exhausted-quota warning background for the statusline quota bar. Impact: when either the 5-hour or weekly Codex window has 0% remaining, the bar keeps its shape but switches from the selected background to the error background for faster visual detection.

package/README.md

@@ -15,9 +15,11 @@ This repository is a minimal fork of [`narumiruna/pi-extensions/extensions/pi-co
 ## Features
 
 - Shows an empty statusline bar immediately, then refreshes every 30 seconds while the active Pi model uses `openai-codex`
-- Statusline output stays compact, with the `codex` label accented and the quota bar plus weekly reset countdown drawn on a themed background
-- When `pi-telegram` is available, the same compact value appears as `codex: <value>` in the `/start` menu status text for active OpenAI Codex subscription models
-- Additional returned buckets, including Spark-specific limits, are ignored
+- Statusline output stays compact, with the active usage label accented and the quota bar plus weekly reset countdown drawn on a themed background
+- Regular Codex subscription models show the primary `codex` quota bucket
+- `GPT-5.3-Codex-Spark` shows the parallel Spark quota bucket with the `spark` label
+- When `pi-telegram` is available, the same compact value appears as `codex: <value>` or `spark: <value>` in the `/start` menu status text for active OpenAI Codex subscription models
+- Additional returned buckets unrelated to the active Codex/Spark model are ignored
 - Pi OpenAI Codex provider auth is used first
 - Codex CLI app-server remains available as a fallback
 - Missing auth, subscription, plan, or quota windows are shown as `n/a`, not as an error
@@ -41,12 +43,18 @@ pi install git:github.com/llblab/pi-codex-usage
 
 ## Statusline
 
-Normal usage:
+Regular Codex usage:
 
 ```text
 codex ██████▀▀▀▀ 6d
 ```
 
+Spark model usage:
+
+```text
+spark ██████████ 7d
+```
+
 The ten-character bar encodes two twenty-step limits at once: 40 total bits of quota state in 10 terminal cells. Each step is 5%: the top quadrants are the 5-hour limit, and the bottom quadrants are the weekly limit. If either quota window is exhausted, the bar keeps the same shape but switches to the error background color.
 
 When the weekly reset time is available, the bar is followed by a countdown. More than a day remains is shown in 144-minute day-tenth steps such as `7d`, `6.9d`, `6.6d`, `5.1d`, `5d`, `3.7d`, `3d`, `2d`, `1.9d`, `1.5d`, and `1.1d`, rounded upward to the next tenth. At 24 hours and below it switches to upward-rounded 6-minute hour-tenth steps such as `24h`, `23.7h`, `20.1h`, `20h`, `19.9h`, `1.4h`, `1.3h`, `1.2h`, `1.1h`, and `1h`. Under an hour it switches to floored minutes, and under a minute to seconds. After the reset timestamp passes, `0s` is held until the next successful quota refresh reports the new weekly window.
@@ -77,9 +85,10 @@ If `@llblab/pi-telegram` is loaded with the public status-line provider API, thi
 
 ```text
 codex: ██████▀▀▀▀ 6d
+spark: ██████████ 7d
 ```
 
-The value is the same compact quota bar plus weekly reset countdown used by the terminal statusline. If `pi-telegram` is absent, older, or the active model is not a Codex subscription model, no Telegram row is added.
+The value is the same compact quota bar plus weekly reset countdown used by the terminal statusline, and the label follows the active Codex/Spark model. If `pi-telegram` is absent, older, or the active model is not a Codex subscription model, no Telegram row is added.
 
 ## Auth
 

package/index.ts

@@ -20,7 +20,11 @@ const REFRESH_INTERVAL_MS = 30 * SECOND_MS;
 const REDRAW_BLINK_MS = 150;
 const STATUS_KEY = "aa-codex-usage";
 const MAX_ERROR_BODY_CHARS = 600;
-const STATUS_LABEL_TEXT = "codex";
+const DEFAULT_STATUS_LABEL_TEXT = "codex";
+const SPARK_STATUS_LABEL_TEXT = "spark";
+const CODEX_USAGE_LIMIT_ID = "codex";
+const SPARK_USAGE_LIMIT_ID = "spark";
+const SPARK_MODEL_KEY = "gpt-5.3-codex-spark";
 const DUAL_BAR_WIDTH = 10;
 const TELEGRAM_STATUS_IMPORT_SPECIFIERS = [
   "@llblab/pi-telegram/status",
@@ -49,7 +53,7 @@ type UsageSource = "pi-auth" | "codex-app-server";
 type TimeoutHandle = ReturnType<typeof setTimeout> & { unref?: () => void };
 type PiModel = NonNullable<ExtensionContext["model"]>;
 export type CodexUsageModel = Pick<PiModel, "id" | "name" | "provider">;
-type CodexUsageTelegramStatusModel = Pick<PiModel, "provider">;
+type CodexUsageTelegramStatusModel = Pick<PiModel, "id" | "name" | "provider">;
 type TelegramStatusLineProviderResult =
   | { label: string; value: string }
   | undefined;
@@ -99,6 +103,13 @@ export type NormalizedRateLimitWindow = {
 
 type RateLimitStatusPayload = {
   rate_limit?: unknown;
+  additional_rate_limits?: unknown;
+};
+
+type BackendAdditionalRateLimit = {
+  limit_name?: unknown;
+  metered_feature?: unknown;
+  rate_limit?: unknown;
 };
 
 type BackendRateLimitDetails = {
@@ -167,8 +178,8 @@ export default function codexUsage(pi: ExtensionAPI) {
       ({ activeModel }) => {
         if (!isOpenAICodexModel(activeModel)) return undefined;
         if (!cache) return undefined;
-        const value = formatCodexUsageStatusValue(cache.report);
-        return value ? { label: "codex", value } : undefined;
+        const value = formatCodexUsageStatusValue(cache.report, activeModel);
+        return value ? { label: activeUsageLabel(activeModel), value } : undefined;
       },
     )
       .then((unregister) => {
@@ -219,7 +230,7 @@ export default function codexUsage(pi: ExtensionAPI) {
     model: CodexUsageModel | undefined,
   ) => {
     if (statuslineCountdownTimer) clearTimeout(statuslineCountdownTimer);
-    const delayMs = nextResetCountdownDelayMs(report);
+    const delayMs = nextResetCountdownDelayMs(report, Date.now(), model);
     if (delayMs === undefined) {
       statuslineCountdownTimer = undefined;
       return;
@@ -268,11 +279,16 @@ export default function codexUsage(pi: ExtensionAPI) {
     else scheduleTemporaryStatuslineClear(ctx);
   };
 
-  const queryCurrentUsage = (ctx: ExtensionContext) => {
+  const queryCurrentUsage = (
+    ctx: ExtensionContext,
+    model: CodexUsageModel | undefined,
+  ) => {
     if (!inFlightUsageQuery) {
-      inFlightUsageQuery = queryUsage(ctx, {
-        timeoutMs: DEFAULT_TIMEOUT_MS,
-      }).finally(() => {
+      inFlightUsageQuery = queryUsage(
+        ctx,
+        { timeoutMs: DEFAULT_TIMEOUT_MS },
+        model,
+      ).finally(() => {
         inFlightUsageQuery = undefined;
       });
     }
@@ -305,7 +321,7 @@ export default function codexUsage(pi: ExtensionAPI) {
       return;
     }
 
-    const result = await queryCurrentUsage(ctx);
+    const result = await queryCurrentUsage(ctx, model);
     if (requestId !== statuslineRequestId) return;
     if (!isOpenAICodexModel(ctx.model)) {
       clearUsageStatusline(ctx);
@@ -373,6 +389,26 @@ function isOpenAICodexModel(
   return model?.provider === CODEX_PROVIDER_ID;
 }
 
+function isSparkCodexModel(
+  model: Pick<PiModel, "id" | "name" | "provider"> | undefined,
+): boolean {
+  if (!isOpenAICodexModel(model)) return false;
+  const key = `${model?.id ?? ""} ${model?.name ?? ""}`.toLowerCase();
+  return key.includes(SPARK_MODEL_KEY);
+}
+
+function activeUsageLimitId(
+  model: Pick<PiModel, "id" | "name" | "provider"> | undefined,
+): string {
+  return isSparkCodexModel(model) ? SPARK_USAGE_LIMIT_ID : CODEX_USAGE_LIMIT_ID;
+}
+
+function activeUsageLabel(
+  model: Pick<PiModel, "id" | "name" | "provider"> | undefined,
+): string {
+  return isSparkCodexModel(model) ? SPARK_STATUS_LABEL_TEXT : DEFAULT_STATUS_LABEL_TEXT;
+}
+
 async function importTelegramStatusLineModule(): Promise<
   TelegramStatusLineModule | undefined
 > {
@@ -401,25 +437,29 @@ async function registerCodexUsageTelegramStatusLine(
 async function queryUsage(
   ctx: ExtensionContext,
   options: Pick<QueryUsageOptions, "timeoutMs">,
+  model: CodexUsageModel | undefined,
 ): Promise<QueryUsageResult> {
   const errors: UsageQueryError[] = [];
+  const sources = isSparkCodexModel(model)
+    ? (["codex-app-server", "pi-auth"] as const)
+    : (["pi-auth", "codex-app-server"] as const);
 
-  try {
-    const report = await queryViaPiAuth(ctx, options.timeoutMs);
-    return { ok: true, report };
-  } catch (cause) {
-    errors.push({ source: "pi-auth", message: errorMessage(cause), cause });
-  }
-
-  try {
-    const report = await queryViaCodexAppServer(options.timeoutMs);
-    return { ok: true, report };
-  } catch (cause) {
-    errors.push({
-      source: "codex-app-server",
-      message: errorMessage(cause),
-      cause,
-    });
+  for (const source of sources) {
+    try {
+      const report =
+        source === "pi-auth"
+          ? await queryViaPiAuth(ctx, options.timeoutMs)
+          : await queryViaCodexAppServer(options.timeoutMs);
+      if (selectUsageSnapshot(report, activeUsageLimitId(model))) {
+        return { ok: true, report };
+      }
+      errors.push({
+        source,
+        message: `${source} returned no displayable ${activeUsageLabel(model)} rate-limit windows`,
+      });
+    } catch (cause) {
+      errors.push({ source, message: errorMessage(cause), cause });
+    }
   }
 
   return { ok: false, errors };
@@ -711,17 +751,42 @@ export function normalizeBackendPayload(
   _capturedAt: number,
   _source: UsageSource,
 ): CodexUsageReport {
-  const snapshot = normalizeBackendSnapshot(
-    "codex",
+  const snapshots: NormalizedRateLimitSnapshot[] = [];
+  const primarySnapshot = normalizeBackendSnapshot(
+    CODEX_USAGE_LIMIT_ID,
     payload.rate_limit,
     _capturedAt,
   );
-  if (!snapshot) {
+  if (primarySnapshot) snapshots.push(primarySnapshot);
+
+  if (Array.isArray(payload.additional_rate_limits)) {
+    for (const item of payload.additional_rate_limits) {
+      const additional = assertObject(
+        item,
+        "additional rate limit",
+      ) as BackendAdditionalRateLimit;
+      const snapshot = normalizeBackendSnapshot(
+        backendAdditionalLimitId(additional),
+        additional.rate_limit,
+        _capturedAt,
+      );
+      if (snapshot) snapshots.push(snapshot);
+    }
+  }
+
+  if (snapshots.length === 0) {
     throw new Error(
       "Codex usage endpoint returned no displayable rate-limit windows.",
     );
   }
-  return { snapshots: [snapshot] };
+  return { snapshots };
+}
+
+function backendAdditionalLimitId(limit: BackendAdditionalRateLimit): string {
+  const raw = `${asString(limit.limit_name) ?? ""} ${asString(limit.metered_feature) ?? ""}`;
+  return raw.toLowerCase().includes("spark")
+    ? SPARK_USAGE_LIMIT_ID
+    : normalizedUsageKey(raw) ?? CODEX_USAGE_LIMIT_ID;
 }
 
 function normalizeBackendSnapshot(
@@ -859,15 +924,16 @@ function mergeSnapshot(
 export function formatCodexUsageStatusline(
   report: CodexUsageReport,
   ctx: ExtensionContext,
-  _model?: CodexUsageModel,
+  model?: CodexUsageModel,
 ): string {
-  const value = formatCodexUsageStatusValue(report);
-  if (!value) return formatStatuslineText(ctx, "n/a");
+  const value = formatCodexUsageStatusValue(report, model);
+  if (!value) return formatStatuslineText(ctx, "n/a", model);
   const [bar, countdown] = value.split(" ", 2);
   const barText = formatStatuslineBarText(
     ctx,
     bar ?? "",
-    hasExhaustedQuotaWindow(report) ? "toolErrorBg" : "selectedBg",
+    hasExhaustedQuotaWindow(report, model) ? "toolErrorBg" : "selectedBg",
+    model,
   );
   return countdown
     ? `${barText} ${ctx.ui.theme.fg("dim", countdown)}`
@@ -882,31 +948,40 @@ export function formatCodexUsageBar(
 
 export function formatCodexUsageStatusValue(
   report: CodexUsageReport,
+  modelOrNow?: CodexUsageModel | number,
   now = Date.now(),
 ): string | undefined {
-  const snapshot = selectPrimaryCodexSnapshot(report);
+  const model = typeof modelOrNow === "number" ? undefined : modelOrNow;
+  const capturedNow = typeof modelOrNow === "number" ? modelOrNow : now;
+  const snapshot = selectActiveUsageSnapshot(report, model);
   if (!snapshot || (!snapshot.primary && !snapshot.secondary)) return undefined;
   const bar = formatDualLimitBar(snapshot.primary, snapshot.secondary);
   if (isQuotaWindowExhausted(snapshot.primary) && snapshot.primary?.resetAt) {
-    const primaryCountdown = formatResetCountdown(snapshot.primary.resetAt, now);
+    const primaryCountdown = formatResetCountdown(
+      snapshot.primary.resetAt,
+      capturedNow,
+    );
     const weeklyCountdown = snapshot.secondary?.resetAt
-      ? formatResetCountdown(snapshot.secondary.resetAt, now)
+      ? formatResetCountdown(snapshot.secondary.resetAt, capturedNow)
       : undefined;
     return weeklyCountdown
       ? `${bar} ${primaryCountdown}/${weeklyCountdown}`
       : `${bar} ${primaryCountdown}`;
   }
-  const countdown = formatWeeklyResetCountdown(report, now);
+  const countdown = formatWeeklyResetCountdown(report, model, capturedNow);
   return countdown ? `${bar} ${countdown}` : bar;
 }
 
 export function formatWeeklyResetCountdown(
   report: CodexUsageReport,
+  modelOrNow?: CodexUsageModel | number,
   now = Date.now(),
 ): string | undefined {
-  const resetAt = selectPrimaryCodexSnapshot(report)?.secondary?.resetAt;
+  const model = typeof modelOrNow === "number" ? undefined : modelOrNow;
+  const capturedNow = typeof modelOrNow === "number" ? modelOrNow : now;
+  const resetAt = selectActiveUsageSnapshot(report, model)?.secondary?.resetAt;
   if (resetAt === undefined) return undefined;
-  return formatResetCountdown(resetAt, now);
+  return formatResetCountdown(resetAt, capturedNow);
 }
 
 export function formatResetCountdown(
@@ -930,8 +1005,9 @@ export function formatResetCountdown(
 export function nextResetCountdownDelayMs(
   report: CodexUsageReport,
   now = Date.now(),
+  model?: CodexUsageModel,
 ): number | undefined {
-  const snapshot = selectPrimaryCodexSnapshot(report);
+  const snapshot = selectActiveUsageSnapshot(report, model);
   const resetTimes = [snapshot?.secondary?.resetAt];
   if (isQuotaWindowExhausted(snapshot?.primary)) {
     resetTimes.push(snapshot?.primary?.resetAt);
@@ -972,14 +1048,21 @@ function formatTenths(value: number): string {
   return value % 10 === 0 ? String(value / 10) : (value / 10).toFixed(1);
 }
 
-function formatReportBar(report: CodexUsageReport): string | undefined {
-  const snapshot = selectPrimaryCodexSnapshot(report);
+function formatReportBar(
+  report: CodexUsageReport,
+  model?: CodexUsageModel,
+): string | undefined {
+  const snapshot = selectActiveUsageSnapshot(report, model);
   if (!snapshot || (!snapshot.primary && !snapshot.secondary)) return undefined;
   return formatDualLimitBar(snapshot.primary, snapshot.secondary);
 }
 
-function formatStatuslineText(ctx: ExtensionContext, value: string): string {
-  const label = ctx.ui.theme.fg("accent", STATUS_LABEL_TEXT);
+function formatStatuslineText(
+  ctx: ExtensionContext,
+  value: string,
+  model?: CodexUsageModel,
+): string {
+  const label = ctx.ui.theme.fg("accent", activeUsageLabel(model));
   return `${label} ${ctx.ui.theme.fg("dim", value)}`;
 }
 
@@ -987,8 +1070,9 @@ function formatStatuslineBarText(
   ctx: ExtensionContext,
   bar: string,
   background: "selectedBg" | "toolErrorBg" = "selectedBg",
+  model?: CodexUsageModel,
 ): string {
-  const label = ctx.ui.theme.fg("accent", STATUS_LABEL_TEXT);
+  const label = ctx.ui.theme.fg("accent", activeUsageLabel(model));
   const value = ctx.ui.theme.bg(background, ctx.ui.theme.fg("dim", bar));
   return `${label} ${value}`;
 }
@@ -1001,7 +1085,7 @@ function formatStatuslineProblem(
   ctx: ExtensionContext,
   errors: UsageQueryError[],
 ): string {
-  const label = ctx.ui.theme.fg("accent", STATUS_LABEL_TEXT);
+  const label = ctx.ui.theme.fg("accent", DEFAULT_STATUS_LABEL_TEXT);
   const value = isUsageUnavailable(errors)
     ? ctx.ui.theme.fg("muted", "n/a")
     : ctx.ui.theme.fg("error", "error");
@@ -1030,12 +1114,6 @@ function isUnavailableError(error: UsageQueryError): boolean {
   );
 }
 
-function selectPrimaryCodexSnapshot(
-  report: CodexUsageReport,
-): NormalizedRateLimitSnapshot | undefined {
-  return report.snapshots.find(isPrimaryCodexSnapshot);
-}
-
 function normalizedUsageKey(value: string | undefined): string | undefined {
   const key = value
     ?.toLowerCase()
@@ -1090,18 +1168,32 @@ function isQuotaWindowExhausted(
   return window !== undefined && remainingPercent(window) <= 0;
 }
 
-function hasExhaustedQuotaWindow(report: CodexUsageReport): boolean {
-  const snapshot = selectPrimaryCodexSnapshot(report);
+function hasExhaustedQuotaWindow(
+  report: CodexUsageReport,
+  model?: CodexUsageModel,
+): boolean {
+  const snapshot = selectActiveUsageSnapshot(report, model);
   return (
     isQuotaWindowExhausted(snapshot?.primary) ||
     isQuotaWindowExhausted(snapshot?.secondary)
   );
 }
 
-function isPrimaryCodexSnapshot(
-  snapshot: NormalizedRateLimitSnapshot,
-): boolean {
-  return normalizedUsageKey(snapshot.limitId) === "codex";
+function selectActiveUsageSnapshot(
+  report: CodexUsageReport,
+  model: CodexUsageModel | undefined,
+): NormalizedRateLimitSnapshot | undefined {
+  return selectUsageSnapshot(report, activeUsageLimitId(model));
+}
+
+function selectUsageSnapshot(
+  report: CodexUsageReport,
+  limitId: string,
+): NormalizedRateLimitSnapshot | undefined {
+  const normalizedLimitId = normalizedUsageKey(limitId);
+  return report.snapshots.find(
+    (snapshot) => normalizedUsageKey(snapshot.limitId) === normalizedLimitId,
+  );
 }
 
 function clampPercent(value: number): number {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-codex-usage",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "Minimal Pi extension that shows primary Codex ChatGPT subscription usage limits.",
   "keywords": [