@openlines/opl-pi-sht 0.2.10 → 0.2.11

package/README.md

@@ -15,6 +15,8 @@
 A portable collection of various Pi coding agent extensions. Repository directories and config files use `opl-`; established Pi-facing commands and tool names stay compatible.
 
 >
+> ### v0.2.11 - OpenRouter key-limit usage in opl-footer
+> - `opl-footer` added an OpenRouter API key's used amount, cap, and percentage.
 > ### v0.2.10 - Codex subscription usage in opl-footer
 > - `opl-footer` added ChatGPT Codex subs 5-hour/weekly quota segment with reset countdowns and stale-snapshot fallback.
 > ### v0.2.9 - pi dependencies patch, updated test scripts
@@ -24,7 +26,7 @@ A portable collection of various Pi coding agent extensions. Repository director
 >
 > See [CHANGELOG](CHANGELOG.md) for more details.
 >
-> `Current project state also marked 'SAFE' for pi v0.99.x release`
+> `Current project state also marked 'SAFE' for pi v1.0.0 release`
 >
 
 ## Installation
@@ -139,7 +141,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 
 ### See what the agent is doing
 
-- **`opl-footer`** surfaces model, cost, token and cache activity, git state, agent status, per-turn timing, and an optional exact remaining ChatGPT Codex 5-hour/weekly subscription-quota segment with reset countdowns and stale-snapshot fallback; `/configure-opl` edits and reorders its layout interactively.
+- **`opl-footer`** surfaces model, cost, token and cache activity, git state, agent status, per-turn timing, an optional exact remaining ChatGPT Codex subscription-quota segment, and optional OpenRouter API-key cap usage. The OpenRouter segment resolves Pi's active key locally and calls only OpenRouter's key endpoint; keys and response bodies are neither persisted nor logged. `/configure-opl` edits and reorders its layout interactively.
 - **`opl-input`** is a configurable editor that reflects the active mode's identity, so you always know which mode you are typing into.
 ![input-footer](images/ss-input-footer.png)
 

package/configs/opl-footer.json.sample

@@ -1,5 +1,5 @@
 {
-  "_comment": "Available segment IDs: pi, model, path, git, thinking, caveman, plan_mode, chat_mode, mode_switcher, separator, token_in, token_out, token_total, cache_read, cache_write, cost, context_pct, context_total, session_stats, perf_stats, status, codex_usage, text:<literal>. codex_usage is hidden by default; add it to any row to show ChatGPT Codex subscription windows.",
+  "_comment": "Available segment IDs: pi, model, path, git, thinking, caveman, plan_mode, chat_mode, mode_switcher, separator, token_in, token_out, token_total, cache_read, cache_write, cost, context_pct, context_total, session_stats, perf_stats, status, codex_usage, openrouter_usage, text:<literal>. codex_usage and openrouter_usage are hidden by default; add codex_usage to show ChatGPT Codex subscription windows, or openrouter_usage to show the active OpenRouter API-key limit usage.",
   "row1LeftSegments": [
     "pi",
     "separator",

package/extensions/opl-footer/README.md

@@ -32,6 +32,7 @@ The third row is populated after the first completed turn. Its session and perfo
 - **Git integration**: branch plus staged, unstaged, and untracked counts, with invalidation after relevant file and Git commands
 - **Token and cost tracking**: total, cache, input/output, and accumulated cost segments
 - **Codex subscription quota**: optional exact 5-hour and weekly ChatGPT Codex usage percentages with reset countdowns and stale-snapshot fallback
+- **OpenRouter key-limit usage**: optional per-key paid-usage amount, limit, and percentage with stale-snapshot fallback
 - **Session statistics**: prompt, API-call, and model tool-call counts
 - **Performance statistics**: cumulative LLM/tool duration, most recent user-prompt-to-completion turnaround time, average time to first token, output rate, and cache-hit percentage
 - **Thinking, mode, and status indicators**: thinking-level colors plus caveman, plan, chat, unified mode, and `Working`/`Waiting`/`Ready` status segments
@@ -93,6 +94,7 @@ See the tracked [`configs/opl-footer.json.sample`](../../configs/opl-footer.json
 | `perf_stats` | LLM/tool timing, TTFT, output rate, and cache-hit percentage | Hidden until the first prompt |
 | `status` | `Working`, `Waiting`, or `Ready` | `accent`, `warning`, and `success` theme colors respectively; optional and hidden by default |
 | `codex_usage` | `5h 76% ↻2h18m · W 37% ↻3d7h` | Exact remaining ChatGPT Codex subscription quota; OAuth-only, optional and hidden by default; a retained snapshot is marked `(stale)` after refresh failure |
+| `openrouter_usage` | `$3.4500 / $25.0000 (13.8%)` | OpenRouter API-key limit usage; only on the selected `openrouter` provider, optional and hidden by default; a retained snapshot is marked `(stale)` after refresh failure |
 | `separator` | `\|` divider | Coloured via `separator` in `colors` |
 | `text:...` | Literal text, e.g. `text:⚡` | — |
 
@@ -102,6 +104,12 @@ Add `codex_usage` to any row through `/configure-opl` or `opl-footer.json`. Whil
 
 No OAuth token, account ID, or response body is written to disk, logged, added to the Pi session, or sent anywhere other than `chatgpt.com` for that request. **The footer retains only the parsed 5-hour/weekly percentage and reset time in process memory for the active session.** The endpoint is an internal ChatGPT backend API and can change without notice. A failed refresh keeps the most recent exact snapshot and marks it `(stale)`; if no request has ever succeeded, the segment stays hidden. Disabling the segment prevents future requests and discards any result from a request already in flight.
 
+## OpenRouter Usage
+
+Add `openrouter_usage` to any row through `/configure-opl` or `opl-footer.json`. While the selected model provider is `openrouter`, the footer resolves the same API key Pi uses for inference and sends `GET https://openrouter.ai/api/v1/key` from the local Pi process. It renders the configured per-key limit as `$<limit - limit_remaining> / $<limit> (<percent>%)`; an absent, malformed, or unlimited key cap leaves the segment hidden. The numerator deliberately uses OpenRouter's authoritative `limit_remaining`, rather than `usage` or `byok_usage`, because those ledgers may not both count against the key limit.
+
+It runs after session start, model selection, and settled agent turns, with a 30-second refresh floor and a 15-second request timeout. No API key or response body is written to disk, logged, added to the Pi session, or sent anywhere other than `openrouter.ai`. A failed refresh keeps the most recent exact snapshot and marks it `(stale)`; if no request has ever succeeded, the segment stays hidden. Disabling the segment prevents future requests and discards any result from a request already in flight.
+
 ## Context Bar
 
 The `context_pct` segment's bar is fully configurable via `segmentOptions.contextBar`:

package/extensions/opl-footer/config.ts

@@ -27,7 +27,7 @@ export const CONFIGURABLE_SEGMENTS: StatusLineSegmentId[] = [
   "pi", "model", "path", "git", "thinking", "caveman", "plan_mode",
   "chat_mode", "mode_switcher", "token_in", "token_out", "token_total",
   "cache_read", "cache_write", "cost", "context_pct", "context_total",
-  "session_stats", "perf_stats", "status", "codex_usage",
+  "session_stats", "perf_stats", "status", "codex_usage", "openrouter_usage",
 ];
 
 const DEFAULT_LAYOUTS: Record<FooterLayoutKey, StatusLineSegmentId[]> = {

package/extensions/opl-footer/index.ts

@@ -13,6 +13,7 @@ import { getIcons } from "./icons.js";
 import { getDefaultColors, fg } from "./theme.js";
 import { showFooterConfigurator } from "./configure.js";
 import { fetchCodexUsage, refreshCodexUsageSnapshot, type CodexUsageSnapshot } from "./codex-usage.js";
+import { fetchOpenRouterUsage, refreshOpenRouterUsageSnapshot, type OpenRouterUsageSnapshot } from "./openrouter-usage.js";
 
 const GIT_BRANCH_PATTERNS: RegExp[] = [
   // init/clone included: creating a repo mid-session must clear the not-a-repo back-off.
@@ -123,6 +124,51 @@ export default function footer(pi: ExtensionAPI) {
   let codexUsageLastAttempt = 0;
   let codexUsageGeneration = 0;
   let codexUsageInFlight: Promise<void> | null = null;
+  let openRouterUsage: OpenRouterUsageSnapshot | null = null;
+  let openRouterUsageLastAttempt = 0;
+  let openRouterUsageGeneration = 0;
+  let openRouterUsageInFlight: Promise<void> | null = null;
+
+  const refreshOpenRouterUsage = (ctx: ExtensionContext, force = false): Promise<void> => {
+    const isOpenRouter = ctx.model?.provider === "openrouter";
+    if (!isOpenRouter) {
+      openRouterUsageGeneration++;
+      openRouterUsageInFlight = null;
+      openRouterUsage = null;
+      tuiRef?.requestRender();
+      return Promise.resolve();
+    }
+
+    const config = getEffectiveConfig();
+    const enabled = LAYOUT_ROWS.some((row) => config[row]?.includes("openrouter_usage"));
+    if (!enabled) {
+      openRouterUsageGeneration++;
+      openRouterUsageInFlight = null;
+      openRouterUsage = null;
+      openRouterUsageLastAttempt = 0;
+      tuiRef?.requestRender();
+      return Promise.resolve();
+    }
+    if (openRouterUsageInFlight) return openRouterUsageInFlight;
+
+    const now = Date.now();
+    if (!force && now - openRouterUsageLastAttempt < CODEX_USAGE_REFRESH_MS) return Promise.resolve();
+    openRouterUsageLastAttempt = now;
+    const generation = ++openRouterUsageGeneration;
+
+    let request: Promise<void>;
+    request = refreshOpenRouterUsageSnapshot(openRouterUsage, () => fetchOpenRouterUsage(ctx))
+      .then((snapshot) => {
+        if (generation !== openRouterUsageGeneration) return;
+        openRouterUsage = snapshot;
+        tuiRef?.requestRender();
+      })
+      .finally(() => {
+        if (openRouterUsageInFlight === request) openRouterUsageInFlight = null;
+      });
+    openRouterUsageInFlight = request;
+    return request;
+  };
 
   const refreshCodexUsage = (ctx: ExtensionContext, force = false): Promise<void> => {
     const model = ctx.model;
@@ -184,6 +230,7 @@ export default function footer(pi: ExtensionAPI) {
       await showFooterConfigurator(ctx, () => {
         tuiRef?.requestRender();
         void refreshCodexUsage(ctx, true);
+        void refreshOpenRouterUsage(ctx, true);
       });
     },
   });
@@ -198,6 +245,10 @@ export default function footer(pi: ExtensionAPI) {
     codexUsageLastAttempt = 0;
     codexUsageGeneration++;
     codexUsageInFlight = null;
+    openRouterUsage = null;
+    openRouterUsageLastAttempt = 0;
+    openRouterUsageGeneration++;
+    openRouterUsageInFlight = null;
     llmMs = 0;
     toolMs = 0;
     ttftSamples = [];
@@ -212,11 +263,13 @@ export default function footer(pi: ExtensionAPI) {
     if (ctx.hasUI) {
       setupFooter(ctx);
       void refreshCodexUsage(ctx, true);
+      void refreshOpenRouterUsage(ctx, true);
     }
   });
 
   pi.on("model_select", async (_event: unknown, ctx: ExtensionContext) => {
     void refreshCodexUsage(ctx, true);
+    void refreshOpenRouterUsage(ctx, true);
   });
 
   // Track user-prompt-to-completion turnaround. agent_start may fire multiple
@@ -237,6 +290,7 @@ export default function footer(pi: ExtensionAPI) {
     statusTracker.agentSettled();
     tuiRef?.requestRender();
     void refreshCodexUsage(_ctx);
+    void refreshOpenRouterUsage(_ctx);
   });
 
   pi.on("turn_start", async (_event: unknown, _ctx: ExtensionContext) => {
@@ -402,6 +456,7 @@ export default function footer(pi: ExtensionAPI) {
       sessionStats: { prompts: branchPrompts, apiCalls: branchApiCalls, toolCalls: branchToolCalls, llmMs, toolMs, ttftSamples, lastTurnaroundMs },
       agentStatus: statusTracker.status(),
       codexUsage,
+      openRouterUsage,
     };
   }
 

package/extensions/opl-footer/openrouter-usage.ts

@@ -0,0 +1,77 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const USAGE_URL = "https://openrouter.ai/api/v1/key";
+const REQUEST_TIMEOUT_MS = 15_000;
+
+export interface OpenRouterUsageSnapshot {
+  used: number;
+  limit: number;
+  fetchedAt: number;
+  stale: boolean;
+}
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type UsageRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): UsageRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as UsageRecord
+    : null;
+}
+
+export function parseOpenRouterUsage(data: unknown, fetchedAt = Date.now()): OpenRouterUsageSnapshot | null {
+  const root = asRecord(data);
+  const key = asRecord(root?.data);
+  const limit = key?.limit;
+  const remaining = key?.limit_remaining;
+  if (
+    typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0 ||
+    typeof remaining !== "number" || !Number.isFinite(remaining)
+  ) return null;
+
+  return {
+    used: Math.max(0, Math.round((limit - remaining) * 1_000_000_000) / 1_000_000_000),
+    limit,
+    fetchedAt,
+    stale: false,
+  };
+}
+
+export async function refreshOpenRouterUsageSnapshot(
+  previous: OpenRouterUsageSnapshot | null,
+  load: () => Promise<OpenRouterUsageSnapshot>,
+): Promise<OpenRouterUsageSnapshot | null> {
+  try {
+    return await load();
+  } catch {
+    return previous ? { ...previous, stale: true } : null;
+  }
+}
+
+export async function fetchOpenRouterUsage(
+  ctx: ExtensionContext,
+  fetchFn: FetchLike = globalThis.fetch,
+  fetchedAt = Date.now(),
+): Promise<OpenRouterUsageSnapshot> {
+  const model = ctx.model;
+  if (!model || model.provider !== "openrouter") {
+    throw new Error("OpenRouter usage requires an openrouter model");
+  }
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok || !auth.apiKey) throw new Error("OpenRouter authentication is unavailable");
+
+  const response = await fetchFn(USAGE_URL, {
+    headers: {
+      Authorization: `Bearer ${auth.apiKey}`,
+      Accept: "application/json",
+      "User-Agent": "opl-footer-openrouter-usage",
+    },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`OpenRouter usage request failed (${response.status})`);
+
+  const snapshot = parseOpenRouterUsage(await response.json(), fetchedAt);
+  if (!snapshot) throw new Error("OpenRouter usage response contained no usable key limit");
+  return snapshot;
+}

package/extensions/opl-footer/segments/index.ts

@@ -15,6 +15,7 @@ import { modeSwitcherSegment } from "./mode-switcher.js";
 import { sessionStatsSegment, perfStatsSegment } from "./session-stats.js";
 import { statusSegment } from "./status.js";
 import { codexUsageSegment } from "./codex-usage.js";
+import { openRouterUsageSegment } from "./openrouter-usage.js";
 
 const SEGMENTS = {
   pi: piSegment,
@@ -39,6 +40,7 @@ const SEGMENTS = {
   perf_stats: perfStatsSegment,
   status: statusSegment,
   codex_usage: codexUsageSegment,
+  openrouter_usage: openRouterUsageSegment,
 };
 
 export function renderSegment(id: StatusLineSegmentId, ctx: SegmentContext): RenderedSegment {

package/extensions/opl-footer/segments/openrouter-usage.ts

@@ -0,0 +1,21 @@
+import type { RenderedSegment, SegmentContext } from "../types.js";
+import { applyColor } from "../theme.js";
+
+function formatUsd(value: number): string {
+  return `$${value.toFixed(4)}`;
+}
+
+export const openRouterUsageSegment = {
+  id: "openrouter_usage" as const,
+  render(ctx: SegmentContext): RenderedSegment {
+    const snapshot = ctx.openRouterUsage;
+    if (!snapshot) return { content: "", visible: false };
+
+    const percent = (snapshot.used / snapshot.limit) * 100;
+    const stale = snapshot.stale ? applyColor(ctx.theme, "dim", " (stale)") : "";
+    return {
+      content: `${formatUsd(snapshot.used)} / ${formatUsd(snapshot.limit)} (${percent.toFixed(1)}%)${stale}`,
+      visible: true,
+    };
+  },
+};

package/extensions/opl-footer/types.ts

@@ -1,6 +1,7 @@
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import type { IconSet } from "./icons.js";
 import type { CodexUsageSnapshot } from "./codex-usage.js";
+import type { OpenRouterUsageSnapshot } from "./openrouter-usage.js";
 
 // Theme color - either a pi theme color name or a custom hex color
 export type ColorValue = ThemeColor | `#${string}`;
@@ -56,6 +57,7 @@ export type StatusLineSegmentId =
   | "perf_stats"
   | "status"
   | "codex_usage"
+  | "openrouter_usage"
   | "separator"
   | `text:${string}`;
 
@@ -134,6 +136,7 @@ export interface SegmentContext {
   sessionStats: SessionStats;
   agentStatus: AgentStatus;
   codexUsage: CodexUsageSnapshot | null;
+  openRouterUsage: OpenRouterUsageSnapshot | null;
   now?: number;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, tool and session safety, fingerprinted /init, model benchmarking, web access, and browser automation.",
   "repository": {
     "type": "git",