@cwillam/pi-minimax-usage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christoph Willam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# pi-minimax-usage
+
+Pi extension that puts your MiniMax Token Plan usage in the status bar.
+
+```
+MiniMax 5h●43% ↺3h12m  wk●12% ↺4d8h
+```
+
+Two windows: the 5-hour rolling quota and the weekly quota, each as used-percent with a reset countdown. Colour shifts at 70 % (yellow) and 90 % (red). The block vanishes when you switch away from MiniMax.
+
+> Not affiliated with, endorsed by, or sponsored by MiniMax Inc. "MiniMax" is a trademark of MiniMax Inc. This extension only reads the publicly documented quota endpoint.
+
+## Install
+
+```
+pi install npm:@cwillam/pi-minimax-usage
+```
+
+Make sure the `minimax` provider is configured in pi (API key available). Restart Pi, switch to a MiniMax model, the block shows up in the footer within about a second.
+
+## Slash command
+
+```
+/minimax-usage           show current snapshot
+/minimax-usage refresh   force-poll now
+/minimax-usage help      command help
+```
+
+## Settings
+
+Optional, under `minimaxUsage` in `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "minimaxUsage": {
+    "refreshIntervalMs": 30000,   // min 5000, default 60000
+    "host": "global",             // "global" or "cn"
+    "endpoint": "https://www.minimax.io/v1/token_plan/remains"  // overrides host, must be on the allowlist
+  }
+}
+```
+
+The `endpoint` setting only accepts the two documented MiniMax URLs (exact match). Anything else is ignored, falls back to `host`.
+
+## How it works
+
+On session start or model switch, it grabs the API key for the `minimax` provider via `ctx.modelRegistry.getApiKeyForProvider()` and polls `GET /v1/token_plan/remains` every `refreshIntervalMs`. The response's `general` bucket gives two `*_remaining_percent` fields (5h + weekly); the extension inverts them to consumed-% and paints the footer.
+
+Wire-format details the parser handles:
+
+- HTTP 200 even on auth failure — the real code lives in `base_resp.status_code` (`1004` = no key, `2049` = wrong host)
+- The `*_remaining_percent` fields are **remaining**, not consumed — inverted to match the rest of the app
+- Timestamps are epoch milliseconds, not seconds
+- Only the `general` bucket is shown; video/other buckets are ignored
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `MiniMax no api key` | No credential for `minimax` provider | Configure it like any other pi provider |
+| `MiniMax 1004` or `MiniMax invalid key` | Key rejected for this host | Flip `host` between `global` / `cn`, or set `endpoint` to the matching URL |
+| Block doesn't appear | Active provider isn't `minimax` | Check with `/model` |
+| Stale data after model switch | Cached state cleared on switch | Next poll (~1 s) repopulates it |
+
+Run `/minimax-usage` to see the current snapshot, error, and last-poll timestamp.
+
+## Credits
+
+Wire-format field names came from [ai-usagebar (Rust)](https://docs.rs/ai-usagebar/latest/ai_usagebar/minimax/types/index.html). Architectural pattern borrowed from [@d3ara1n/pi-usage-block](https://github.com/d3ara1n/pi-extensions).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@cwillam/pi-minimax-usage",
+  "version": "1.0.0",
+  "description": "Pi extension: live MiniMax Token Plan usage (5h + weekly) in the status bar. Not affiliated with MiniMax Inc.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit --strict --target es2022 --module esnext --moduleResolution bundler src/index.ts"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "minimax",
+    "minimax-api",
+    "minimax-token-plan",
+    "usage",
+    "status-bar",
+    "quota"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Christoph Willam",
+    "email": "info@cwillam.de"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cwillam/pi-minimax-usage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cwillam/pi-minimax-usage/issues"
+  },
+  "homepage": "https://github.com/cwillam/pi-minimax-usage#readme",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,418 @@
+/**
+ * minimax-usage — footer status block + slash command for the MiniMax Token Plan.
+ *
+ * Polls the documented quota endpoint `GET /v1/token_plan/remains` and renders
+ * two windows (5h rolling + weekly) as used-percentage with a reset countdown.
+ * Not affiliated with MiniMax Inc. — see LICENSE.
+ *
+ * Wire-format quirks the parser handles:
+ *   - HTTP 200 even on auth failure — real status lives in `base_resp.status_code`
+ *     (1004 = no key, 2049 = wrong host for key)
+ *   - `current_interval_remaining_percent` is REMAINING, not consumed — inverted here
+ *   - All timestamps are epoch milliseconds (NOT seconds)
+ *   - `general` bucket covers text/coding; other buckets are ignored
+ *
+ * Optional settings (under `minimaxUsage` in pi's settings.json):
+ *   - `refreshIntervalMs` (number, default 60000)
+ *   - `endpoint` (string, default https://www.minimax.io/v1/token_plan/remains)
+ *   - `host` ("global" | "cn", default "global") — flips the endpoint domain
+ */
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionCommandContext,
+  Theme as PiTheme,
+} from "@earendil-works/pi-coding-agent";
+
+const STATUS_KEY = "minimax-usage";
+const COMMAND_NAME = "minimax-usage";
+const PROVIDER_ID = "minimax";
+const DEFAULT_POLL_MS = 60_000;
+
+const ENDPOINTS = {
+  global: "https://www.minimax.io/v1/token_plan/remains",
+  cn: "https://www.minimaxi.com/v1/token_plan/remains",
+} as const;
+type Host = keyof typeof ENDPOINTS;
+
+type QuotaWindow = {
+  period: string;
+  used: number;
+  limit: number;
+  resetAt?: Date;
+};
+
+type ExtensionSettings = {
+  minimaxUsage?: {
+    refreshIntervalMs?: number;
+    endpoint?: string;
+    host?: Host;
+  };
+};
+
+type StatusSnapshot = {
+  active: boolean;
+  hasKey: boolean;
+  lastPollAt: Date | undefined;
+  windows: QuotaWindow[] | undefined;
+  error: string | undefined;
+  endpoint: string;
+  nextPollInMs: number | undefined;
+};
+
+type PollingState = {
+  ctx: ExtensionContext | undefined;
+  alive: boolean;
+  activeProviderId: string | undefined;
+  apiKey: string | undefined;
+  lastWindows: QuotaWindow[] | undefined;
+  lastError: string | undefined;
+  lastPollAt: Date | undefined;
+  nextPollTimer: ReturnType<typeof setTimeout> | undefined;
+  intervalTimer: ReturnType<typeof setInterval> | undefined;
+  intervalMs: number;
+  endpoint: string;
+};
+
+const state: PollingState = {
+  ctx: undefined,
+  alive: false,
+  activeProviderId: undefined,
+  apiKey: undefined,
+  lastWindows: undefined,
+  lastError: undefined,
+  lastPollAt: undefined,
+  nextPollTimer: undefined,
+  intervalTimer: undefined,
+  intervalMs: DEFAULT_POLL_MS,
+  endpoint: ENDPOINTS.global,
+};
+
+function getSettings(): ExtensionSettings["minimaxUsage"] {
+  // `settings` exists on the runtime context but isn't surfaced in the
+  // public ExtensionContext type; access via a typed cast.
+  const raw = (
+    state.ctx as unknown as { settings?: ExtensionSettings } | undefined
+  )?.settings;
+  return raw?.minimaxUsage;
+}
+
+/** Allowlist of acceptable endpoint URLs (defence against SSRF via `endpoint` setting). */
+const ALLOWED_ENDPOINTS: ReadonlySet<string> = new Set(
+  Object.values(ENDPOINTS),
+);
+
+function resolveEndpoint(): string {
+  const cfg = getSettings();
+  // Honour `endpoint` only if it matches an allowlisted MiniMax URL exactly.
+  if (cfg?.endpoint && ALLOWED_ENDPOINTS.has(cfg.endpoint)) return cfg.endpoint;
+  return ENDPOINTS[cfg?.host ?? "global"];
+}
+
+function resolveIntervalMs(): number {
+  const ms = getSettings()?.refreshIntervalMs;
+  return Number.isFinite(ms) && (ms as number) >= 5_000
+    ? (ms as number)
+    : DEFAULT_POLL_MS;
+}
+
+// ── formatting ────────────────────────────────────────────────────────────
+
+function fmtPct(used: number, limit: number): string {
+  if (!Number.isFinite(used) || !Number.isFinite(limit) || limit <= 0)
+    return "—";
+  return `${Math.round((used / limit) * 100)}%`;
+}
+
+function fmtCountdown(ms: number): string {
+  if (ms <= 0) return "now";
+  const m = Math.round(ms / 60_000);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  return rm ? `${h}h${rm}m` : `${h}h`;
+}
+
+function fmtAge(seconds: number): string {
+  if (seconds < 60) return `${Math.round(seconds)}s ago`;
+  const m = Math.round(seconds / 60);
+  if (m < 60) return `${m}m ago`;
+  return `${Math.floor(m / 60)}h${m % 60}m ago`;
+}
+
+function parseEpochMs(raw: unknown): Date | undefined {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  const d = new Date(n);
+  return Number.isNaN(d.getTime()) ? undefined : d;
+}
+
+type Level = "success" | "warning" | "error";
+
+function usageLevel(used: number, limit: number): Level {
+  if (limit <= 0) return "success";
+  const r = used / limit;
+  if (r >= 0.9) return "error";
+  if (r >= 0.7) return "warning";
+  return "success";
+}
+
+// ── parser ────────────────────────────────────────────────────────────────
+
+type Envelope = {
+  base_resp?: { status_code?: number; status_msg?: string };
+  model_remains?: Array<{
+    model_name?: string;
+    end_time?: number | string;
+    weekly_end_time?: number | string;
+    current_interval_remaining_percent?: number | string;
+    current_weekly_remaining_percent?: number | string;
+  }>;
+};
+
+function parseQuota(envelope: Envelope): {
+  windows: QuotaWindow[];
+  error?: string;
+} {
+  const code = envelope.base_resp?.status_code;
+  if (code !== undefined && code !== 0) {
+    return {
+      windows: [],
+      error: envelope.base_resp?.status_msg ?? `status ${code}`,
+    };
+  }
+  const rows = Array.isArray(envelope.model_remains)
+    ? envelope.model_remains
+    : [];
+  const windows: QuotaWindow[] = [];
+  for (const r of rows) {
+    if (r.model_name !== "general") continue; // text/coding bucket only
+    const intervalRemain = Number(r.current_interval_remaining_percent);
+    if (Number.isFinite(intervalRemain)) {
+      windows.push({
+        period: "5h",
+        used: Math.max(0, 100 - intervalRemain),
+        limit: 100,
+        resetAt: parseEpochMs(r.end_time),
+      });
+    }
+    const weekRemain = Number(r.current_weekly_remaining_percent);
+    if (Number.isFinite(weekRemain)) {
+      windows.push({
+        period: "wk",
+        used: Math.max(0, 100 - weekRemain),
+        limit: 100,
+        resetAt: parseEpochMs(r.weekly_end_time),
+      });
+    }
+  }
+  return { windows };
+}
+
+// ── network ───────────────────────────────────────────────────────────────
+
+async function pollOnce(): Promise<void> {
+  if (!state.ctx || !state.alive || !state.apiKey) return;
+  try {
+    const resp = await fetch(state.endpoint, {
+      headers: { Authorization: `Bearer ${state.apiKey}` },
+    });
+    const data = (await resp.json()) as Envelope;
+    const parsed = parseQuota(data);
+    if (parsed.error) {
+      state.lastError = parsed.error;
+    } else if (parsed.windows.length > 0) {
+      state.lastWindows = parsed.windows;
+      state.lastError = undefined;
+    }
+    state.lastPollAt = new Date();
+  } catch (err) {
+    state.lastError = err instanceof Error ? err.message : String(err);
+    state.lastPollAt = new Date();
+  }
+}
+
+// ── render ────────────────────────────────────────────────────────────────
+
+function render(): void {
+  if (!state.ctx || !state.alive) return;
+  if (state.activeProviderId !== PROVIDER_ID) {
+    state.ctx.ui.setStatus(STATUS_KEY, undefined);
+    return;
+  }
+  const theme: PiTheme = state.ctx.ui.theme;
+  if (!state.apiKey) {
+    state.ctx.ui.setStatus(
+      STATUS_KEY,
+      `${theme.fg("dim", "MiniMax")} ${theme.fg("warning", "no api key")}`,
+    );
+    return;
+  }
+  if (state.lastError) {
+    state.ctx.ui.setStatus(
+      STATUS_KEY,
+      `${theme.fg("dim", "MiniMax")} ${theme.fg("warning", state.lastError)}`,
+    );
+    return;
+  }
+  if (!state.lastWindows?.length) return; // first poll pending
+
+  const parts = state.lastWindows.map((w) => {
+    const lvl = usageLevel(w.used, w.limit);
+    let text = `${theme.fg("dim", w.period)}${theme.fg(lvl, "●")}${theme.fg("dim", fmtPct(w.used, w.limit))}`;
+    if (w.resetAt) {
+      const remaining = w.resetAt.getTime() - Date.now();
+      text += theme.fg("dim", ` ↺${fmtCountdown(remaining)}`);
+    }
+    return text;
+  });
+  state.ctx.ui.setStatus(
+    STATUS_KEY,
+    `${theme.fg("dim", "MiniMax")} ${parts.join(" ")}`,
+  );
+}
+
+function snapshot(): StatusSnapshot {
+  return {
+    active: state.activeProviderId === PROVIDER_ID,
+    hasKey: Boolean(state.apiKey),
+    lastPollAt: state.lastPollAt,
+    windows: state.lastWindows,
+    error: state.lastError,
+    endpoint: state.endpoint,
+    nextPollInMs:
+      state.alive && state.activeProviderId === PROVIDER_ID && state.apiKey
+        ? state.intervalMs
+        : undefined,
+  };
+}
+
+function formatSnapshotForNotify(snap: StatusSnapshot): string {
+  if (!snap.active)
+    return "MiniMax is not the active provider — block is hidden.";
+  if (!snap.hasKey) return "No API key configured for provider 'minimax'.";
+  if (snap.error) return `Last error: ${snap.error}`;
+  if (!snap.windows?.length)
+    return "No quota data yet — first poll pending or empty response.";
+  const lines = snap.windows.map((w) => {
+    const reset = w.resetAt
+      ? ` resets in ${fmtCountdown(w.resetAt.getTime() - Date.now())}`
+      : "";
+    return `  ${w.period}: ${fmtPct(w.used, w.limit)} used${reset}`;
+  });
+  const lastPoll = snap.lastPollAt
+    ? fmtAge((Date.now() - snap.lastPollAt.getTime()) / 1000)
+    : "never";
+  return [
+    `MiniMax Token Plan (${snap.endpoint})`,
+    ...lines,
+    `last poll: ${lastPoll}`,
+  ].join("\n");
+}
+
+// ── lifecycle ─────────────────────────────────────────────────────────────
+
+async function startPolling(): Promise<void> {
+  stopPolling();
+  if (state.activeProviderId !== PROVIDER_ID || !state.ctx) return;
+  state.endpoint = resolveEndpoint();
+  state.intervalMs = resolveIntervalMs();
+  state.apiKey =
+    await state.ctx.modelRegistry?.getApiKeyForProvider?.(PROVIDER_ID);
+  render();
+  if (!state.apiKey) return;
+  await pollOnce();
+  render();
+  state.intervalTimer = setInterval(() => {
+    if (state.alive) void pollOnce().then(render);
+  }, state.intervalMs);
+}
+
+function stopPolling(): void {
+  if (state.intervalTimer) clearInterval(state.intervalTimer);
+  if (state.nextPollTimer) clearTimeout(state.nextPollTimer);
+  state.intervalTimer = undefined;
+  state.nextPollTimer = undefined;
+}
+
+function resetState(): void {
+  state.lastWindows = undefined;
+  state.lastError = undefined;
+  state.lastPollAt = undefined;
+  state.apiKey = undefined;
+}
+
+// ── entrypoint ────────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI): void {
+  pi.on("model_select", (event) => {
+    state.activeProviderId = event.model.provider;
+    if (state.activeProviderId === PROVIDER_ID) {
+      void startPolling();
+    } else {
+      stopPolling();
+      resetState();
+    }
+    render();
+  });
+
+  pi.on("session_start", async (_e, ctx) => {
+    if (!ctx.hasUI) return;
+    state.ctx = ctx;
+    state.alive = true;
+    state.activeProviderId = ctx.model?.provider;
+    await startPolling();
+  });
+
+  pi.on("session_shutdown", () => {
+    state.alive = false;
+    stopPolling();
+    state.ctx = undefined;
+    state.activeProviderId = undefined;
+    resetState();
+  });
+
+  pi.registerCommand(COMMAND_NAME, {
+    description: "MiniMax Token Plan usage: show status, refresh, or help",
+    handler: async (args: string, cmdCtx: ExtensionCommandContext) => {
+      const sub = args.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+      if (sub === "refresh") {
+        if (state.activeProviderId !== PROVIDER_ID) {
+          cmdCtx.ui.notify("MiniMax is not the active provider.", "warning");
+          return;
+        }
+        if (!state.apiKey) {
+          cmdCtx.ui.notify(
+            "No API key configured for provider 'minimax'.",
+            "warning",
+          );
+          return;
+        }
+        await pollOnce();
+        render();
+        cmdCtx.ui.notify(formatSnapshotForNotify(snapshot()), "info");
+        return;
+      }
+      if (sub === "help" || sub === "--help" || sub === "-h") {
+        cmdCtx.ui.notify(
+          [
+            `${COMMAND_NAME} — MiniMax Token Plan usage`,
+            "",
+            "Usage:",
+            `  /${COMMAND_NAME}          show current status`,
+            `  /${COMMAND_NAME} refresh  force-poll the quota endpoint now`,
+            `  /${COMMAND_NAME} help     this help`,
+            "",
+            "Configuration (in pi's settings.json, under `minimaxUsage`):",
+            "  refreshIntervalMs: poll interval in ms (min 5000, default 60000)",
+            "  host: 'global' (default) or 'cn'",
+            "  endpoint: full override URL",
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+      cmdCtx.ui.notify(formatSnapshotForNotify(snapshot()), "info");
+    },
+  });
+}