@robhowley/pi-openrouter 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# pi-openrouter
+
+A [Pi](https://pi.dev/) extension that adds an `/openrouter-usage` command for viewing OpenRouter spend, caps, burn rate, and model breakdowns in a terminal overlay.
+
+## Installation
+
+```shell
+pi install npm:@robhowley/pi-openrouter
+```
+
+## Requirements
+
+Set one of these environment variables:
+
+- `OPENROUTER_MANAGEMENT_KEY` (preferred) — provides full usage data including model breakdowns
+- `OPENROUTER_API_KEY` — basic usage data only
+
+```shell
+export OPENROUTER_MANAGEMENT_KEY=sk-or-...
+```
+
+## Usage
+
+Type `/openrouter-usage` in Pi to open the usage overlay.
+
+The overlay shows:
+- **Month spend** vs cap with percentage
+- **7-day spend** with burn rate projection
+- **Today's spend**
+- **Top models** (7d and 30d)
+- **Usage by provider** (30d)
+- **Usage by day** (last 7 days)
+
+The extension refreshes data in the background every 30 seconds (with exponential backoff on errors).
+
+Press `q`, `Esc`, or `Ctrl+C` to close the overlay.
+
+## Features
+
+- Ephemeral TUI overlay — doesn't clutter chat history
+- Auto-refreshing cache — data stays fresh without repeated API calls
+- Graceful degradation — works with API key only (no model breakdowns)
+
+## License
+
+MIT

package/extensions/openrouter/__tests__/format.test.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect } from 'vitest';
+import { aggregateUsage } from '../format.js';
+import type { ActivityItem } from '@openrouter/sdk/models/index.js';
+
+describe('aggregateUsage', () => {
+  it('should calculate from analytics', () => {
+    const credits = {
+      totalUsage: 38.42,
+      totalCredits: 100,
+    };
+    // Use a date that's within the last 7 days of when the test runs.
+    // We use a date from the past month that's been long enough to survive timezone offsets.
+    const date = '2026-05-01';
+    const analytics: ActivityItem[] = [
+      {
+        date: date,
+        model: 'model-1',
+        modelPermaslug: 'model-1-perma',
+        endpointId: 'ep-1',
+        usage: 5.42,
+        byokUsageInference: 0,
+        requests: 10,
+        promptTokens: 1000,
+        completionTokens: 100,
+        reasoningTokens: 0,
+        providerName: 'provider-1',
+      },
+      {
+        date: date,
+        model: 'model-2',
+        modelPermaslug: 'model-2-perma',
+        endpointId: 'ep-2',
+        usage: 3.11,
+        byokUsageInference: 0,
+        requests: 5,
+        promptTokens: 500,
+        completionTokens: 50,
+        reasoningTokens: 0,
+        providerName: 'provider-2',
+      },
+    ];
+
+    const result = aggregateUsage(credits, analytics);
+
+    expect(result.month).toBe(38.42);
+    // Data from May 1 should be in the week (but may not be in "today" depending on timezone)
+    expect(result.week).toBeGreaterThan(0);
+    // Today's data might not be from May 1 due to timezone, so just check month
+  });
+
+  it('should calculate burn rate correctly', () => {
+    const credits = {
+      totalUsage: 38.42,
+      totalCredits: 100,
+    };
+    const analytics: ActivityItem[] = [];
+
+    const result = aggregateUsage(credits, analytics);
+
+    expect(result.burnRate).toBe(0);
+    expect(result.week).toBe(0);
+    expect(result.today).toBe(0);
+  });
+
+  it('should handle empty analytics', () => {
+    const credits = {
+      totalUsage: 18.21,
+      totalCredits: 30,
+    };
+
+    const result = aggregateUsage(credits, []);
+
+    expect(result.month).toBe(18.21);
+    expect(result.week).toBe(0);
+    expect(result.today).toBe(0);
+    expect(result.topModels7d).toEqual([]);
+    expect(result.byModel).toEqual({});
+    expect(result.byKey).toEqual({});
+    expect(result.byDay).toEqual({});
+  });
+
+  it('should aggregate by model', () => {
+    const credits = {
+      totalUsage: 10,
+      totalCredits: 100,
+    };
+    // Use a fixed date that's definitely in the past
+    const date = '2026-05-03';
+    const analytics: ActivityItem[] = [
+      {
+        date: date,
+        model: 'gpt-4',
+        modelPermaslug: 'gpt-4-perma',
+        endpointId: 'ep-1',
+        usage: 5.0,
+        byokUsageInference: 0,
+        requests: 5,
+        promptTokens: 100,
+        completionTokens: 50,
+        reasoningTokens: 0,
+        providerName: 'openai',
+      },
+      {
+        date: date,
+        model: 'claude-3',
+        modelPermaslug: 'claude-3-perma',
+        endpointId: 'ep-2',
+        usage: 3.0,
+        byokUsageInference: 0,
+        requests: 3,
+        promptTokens: 60,
+        completionTokens: 30,
+        reasoningTokens: 0,
+        providerName: 'anthropic',
+      },
+    ];
+
+    const result = aggregateUsage(credits, analytics);
+
+    expect(result.byModel).toEqual({
+      'gpt-4': 5.0,
+      'claude-3': 3.0,
+    });
+    expect(result.topModels7d).toHaveLength(2);
+    const first = result.topModels7d[0]!;
+    expect(first.name).toBe('gpt-4');
+    expect(first.spend).toBe(5.0);
+  });
+
+  it('should aggregate by provider name (not endpoint ID)', () => {
+    const credits = {
+      totalUsage: 10,
+      totalCredits: 100,
+    };
+    const date = '2026-05-01';
+    const analytics: ActivityItem[] = [
+      {
+        date: date,
+        model: 'gpt-4',
+        modelPermaslug: 'gpt-4-perma',
+        endpointId: 'ep-1',
+        usage: 5.0,
+        byokUsageInference: 0,
+        requests: 5,
+        promptTokens: 100,
+        completionTokens: 50,
+        reasoningTokens: 0,
+        providerName: 'openai',
+      },
+      {
+        date: date,
+        model: 'claude-3',
+        modelPermaslug: 'claude-3-perma',
+        endpointId: 'ep-2',
+        usage: 3.0,
+        byokUsageInference: 0,
+        requests: 3,
+        promptTokens: 60,
+        completionTokens: 30,
+        reasoningTokens: 0,
+        providerName: 'openai', // Same provider, different endpoint
+      },
+    ];
+
+    const result = aggregateUsage(credits, analytics);
+
+    // byKey should use providerName, not endpointId
+    expect(result.byKey).toEqual({
+      openai: 8.0, // Total from both endpoints
+    });
+    // Should NOT contain endpoint IDs
+    expect(result.byKey).not.toHaveProperty('ep-1');
+    expect(result.byKey).not.toHaveProperty('ep-2');
+  });
+
+  it('should include 30d model data', () => {
+    const credits = {
+      totalUsage: 100,
+      totalCredits: 200,
+    };
+    // Data from recent dates for 30d
+    const analytics: ActivityItem[] = [
+      {
+        date: '2026-04-15',
+        model: 'gpt-4',
+        modelPermaslug: 'gpt-4-perma',
+        endpointId: 'ep-1',
+        usage: 50.0,
+        byokUsageInference: 0,
+        requests: 10,
+        promptTokens: 1000,
+        completionTokens: 100,
+        reasoningTokens: 0,
+        providerName: 'openai',
+      },
+      {
+        date: '2026-04-20',
+        model: 'claude-3',
+        modelPermaslug: 'claude-3-perma',
+        endpointId: 'ep-2',
+        usage: 30.0,
+        byokUsageInference: 0,
+        requests: 5,
+        promptTokens: 500,
+        completionTokens: 50,
+        reasoningTokens: 0,
+        providerName: 'anthropic',
+      },
+    ];
+
+    const result = aggregateUsage(credits, analytics);
+
+    // topModels30d should be populated
+    expect(result.topModels30d).toHaveLength(2);
+    expect(result.topModels30d[0]).toEqual({ name: 'gpt-4', spend: 50.0 });
+    expect(result.topModels30d[1]).toEqual({ name: 'claude-3', spend: 30.0 });
+  });
+});

package/extensions/openrouter/cache.ts

@@ -0,0 +1,115 @@
+import type { UsageSummary } from './types.js';
+import type { ActivityItem } from '@openrouter/sdk/models/index.js';
+import { aggregateUsage } from './format.js';
+import { getCredits, getActivity } from './client.js';
+
+export const CACHE_TTL_MS = 45000;
+export const BACKGROUND_REFRESH_INTERVAL_MS = 30000;
+
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+}
+
+export class TTLCache<T> {
+  private cache = new Map<string, CacheEntry<T>>();
+
+  constructor(private ttlMs: number = CACHE_TTL_MS) {}
+
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() - entry.timestamp > this.ttlMs) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    return entry.data;
+  }
+
+  getTimestamp(key: string): number | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() - entry.timestamp > this.ttlMs) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    return entry.timestamp;
+  }
+
+  set(key: string, data: T): void {
+    this.cache.set(key, { data, timestamp: Date.now() });
+  }
+}
+
+export const usageCache = new TTLCache<UsageSummary>(CACHE_TTL_MS);
+
+let refreshInterval: NodeJS.Timeout | null = null;
+let consecutiveFailures = 0;
+const MAX_RETRY_BACKOFF = 5; // Max 2^5 = 32x base interval (16 min)
+const MAX_RETRY_COUNT = 4; // Stop after 4 consecutive failures
+
+function getBackoffInterval(): number {
+  const backoffMultiplier = Math.min(consecutiveFailures, MAX_RETRY_BACKOFF);
+  return BACKGROUND_REFRESH_INTERVAL_MS * Math.pow(2, backoffMultiplier);
+}
+
+export async function fetchAndAggregate(): Promise<UsageSummary> {
+  const credits = await getCredits();
+  let analytics: ActivityItem[] | null = null;
+  try {
+    analytics = await getActivity();
+  } catch (err) {
+    console.log('Activity fetch failed (management key required):', err);
+  }
+  const timestamp = Date.now();
+  return aggregateUsage(credits, analytics ?? [], timestamp);
+}
+
+function scheduleRefresh(): void {
+  const delay = consecutiveFailures > 0 ? getBackoffInterval() : BACKGROUND_REFRESH_INTERVAL_MS;
+
+  refreshInterval = setInterval(async () => {
+    try {
+      const summary = await fetchAndAggregate();
+      usageCache.set('usage', summary);
+
+      // Reset failure count on success and restart with normal interval
+      if (consecutiveFailures > 0) {
+        consecutiveFailures = 0;
+        stopBackgroundRefresh();
+        scheduleRefresh();
+      }
+    } catch (err) {
+      consecutiveFailures++;
+      console.log(`Background refresh failed (${consecutiveFailures}/${MAX_RETRY_COUNT}):`, err);
+
+      // Stop after max retries reached
+      if (consecutiveFailures >= MAX_RETRY_COUNT) {
+        console.log('Max retries reached, stopping background refresh');
+        stopBackgroundRefresh();
+        // TODO: Fire UI notification for persistent failure
+        return;
+      }
+
+      // Restart with backoff interval
+      stopBackgroundRefresh();
+      scheduleRefresh();
+    }
+  }, delay);
+}
+
+export function startBackgroundRefresh(): void {
+  if (refreshInterval) return;
+  scheduleRefresh();
+}
+
+export function stopBackgroundRefresh(): void {
+  if (refreshInterval) {
+    clearInterval(refreshInterval);
+    refreshInterval = null;
+  }
+}

package/extensions/openrouter/client.ts

@@ -0,0 +1,65 @@
+import type { ActivityResponse } from '@openrouter/sdk/models/index.js';
+import type { GetCreditsResponse } from '@openrouter/sdk/models/operations/index.js';
+import { OpenRouter } from '@openrouter/sdk/sdk/sdk.js';
+
+let client: OpenRouter | null = null;
+
+function getClient(): OpenRouter {
+  if (client) return client;
+  const apiKey = process.env['OPENROUTER_MANAGEMENT_KEY'] || process.env['OPENROUTER_API_KEY'];
+  if (!apiKey) throw new AuthError('OPENROUTER_API_KEY or OPENROUTER_MANAGEMENT_KEY not set');
+  client = new OpenRouter({ apiKey });
+  return client;
+}
+
+export async function getCredits(): Promise<GetCreditsResponse['data']> {
+  try {
+    const response = await getClient().credits.getCredits();
+    return response.data;
+  } catch (err) {
+    throw mapSdkError(err);
+  }
+}
+
+export async function getActivity(): Promise<ActivityResponse['data']> {
+  try {
+    const response = await getClient().analytics.getUserActivity();
+    return response.data;
+  } catch (err) {
+    throw mapSdkError(err);
+  }
+}
+
+interface SDKError {
+  status?: number;
+  message?: string;
+}
+
+function isSDKError(err: unknown): err is SDKError {
+  return err !== null && typeof err === 'object' && 'status' in err;
+}
+
+function mapSdkError(err: unknown): Error {
+  if (isSDKError(err)) {
+    const status = err.status;
+    const message = err.message ?? 'Unknown error';
+    if (status === 401) return new AuthError(message);
+    return new ApiError(`${status}: ${message}`);
+  }
+  if (err instanceof Error) return err;
+  return new Error(String(err));
+}
+
+export class AuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuthError';
+  }
+}
+
+export class ApiError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}

package/extensions/openrouter/format.ts

@@ -0,0 +1,88 @@
+import type { ActivityItem } from '@openrouter/sdk/models/index.js';
+import type { UsageSummary } from './types.js';
+
+export function aggregateUsage(
+  credits: { totalUsage: number; totalCredits?: number },
+  analytics: ActivityItem[],
+  timestamp: number = Date.now(),
+): UsageSummary {
+  const now = new Date();
+  const startOfDay = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const startOfWeek = new Date(startOfDay);
+  startOfWeek.setDate(startOfWeek.getDate() - 7);
+
+  const weekData = analytics.filter((d) => {
+    const ts = new Date(d.date);
+    return ts >= startOfWeek;
+  });
+
+  const todayData = analytics.filter((d) => {
+    const ts = new Date(d.date);
+    return ts >= startOfDay;
+  });
+
+  const week = sumSpend(weekData);
+  const today = sumSpend(todayData);
+  const month = credits.totalUsage;
+
+  // Top models by 7d spend
+  const modelSpend7d = aggregateByModel(weekData);
+  const topModels7d = Object.entries(modelSpend7d)
+    .map(([name, spend]) => ({ name, spend }))
+    .sort((a, b) => b.spend - a.spend)
+    .slice(0, 3);
+
+  // Top models by 30d spend
+  const modelSpend30d = aggregateByModel(analytics);
+  const topModels30d = Object.entries(modelSpend30d)
+    .map(([name, spend]) => ({ name, spend }))
+    .sort((a, b) => b.spend - a.spend)
+    .slice(0, 3);
+
+  return {
+    today,
+    week,
+    month,
+    cap: credits.totalCredits ?? 0,
+    burnRate: (week / 7) * 30,
+    topModels7d,
+    topModels30d,
+    byModel: aggregateByModel(analytics),
+    byKey: aggregateByProvider(analytics),
+    byDay: aggregateByDay(analytics),
+    timestamp,
+  };
+}
+
+function sumSpend(data: ActivityItem[]): number {
+  return data.reduce((sum, d) => sum + d.usage, 0);
+}
+
+function aggregateByModel(data: ActivityItem[]): Record<string, number> {
+  return data.reduce(
+    (acc, d) => {
+      acc[d.model] = (acc[d.model] || 0) + d.usage;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+}
+
+function aggregateByProvider(data: ActivityItem[]): Record<string, number> {
+  return data.reduce(
+    (acc, d) => {
+      acc[d.providerName] = (acc[d.providerName] || 0) + d.usage;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+}
+
+function aggregateByDay(data: ActivityItem[]): Record<string, number> {
+  const byDay: Record<string, number> = {};
+  for (const d of data) {
+    const day = d.date;
+    byDay[day] = (byDay[day] || 0) + d.usage;
+  }
+  return byDay;
+}

package/extensions/openrouter/index.ts

@@ -0,0 +1,94 @@
+import type { ExtensionAPI, ExtensionContext } from '@mariozechner/pi-coding-agent';
+import type { UsageSummary } from './types.js';
+import {
+  usageCache,
+  startBackgroundRefresh,
+  stopBackgroundRefresh,
+  fetchAndAggregate,
+} from './cache.js';
+import { AuthError } from './client.js';
+import { UsageOverlayComponent } from './overlay.js';
+
+export default function (pi: ExtensionAPI) {
+  startBackgroundRefresh();
+
+  pi.on('session_start', async (_event, ctx) => {
+    ctx.ui.notify('OpenRouter extension loaded', 'info');
+  });
+
+  pi.on('session_shutdown', () => {
+    stopBackgroundRefresh();
+  });
+
+  pi.registerCommand('openrouter-usage', {
+    description: 'Show OpenRouter usage: caps, spend, burn rate, and model breakdowns',
+    getArgumentCompletions: () => null,
+    handler: async (args, ctx) => {
+      const subcommand = args.trim() || undefined;
+      await showUsageOverlay(ctx, subcommand);
+    },
+  });
+}
+
+async function showUsageOverlay(ctx: ExtensionContext, _subcommand?: string) {
+  const cachedSummary = usageCache.get('usage');
+  const lastFetchTimestamp = usageCache.getTimestamp('usage');
+  const cachedMinutesAgo = lastFetchTimestamp
+    ? Math.round((Date.now() - lastFetchTimestamp) / 60000)
+    : null;
+
+  if (cachedSummary) {
+    await showOverlay(ctx, cachedSummary, null, cachedMinutesAgo);
+    return;
+  }
+
+  let error: string | null = null;
+  let summary: UsageSummary | null = null;
+
+  try {
+    summary = await fetchAndAggregate();
+    usageCache.set('usage', summary);
+
+    await showOverlay(ctx, summary, null, 0);
+  } catch (error_) {
+    const err = error_ as Error;
+    error =
+      err instanceof AuthError
+        ? 'OpenRouter API key not found. Set OPENROUTER_MANAGEMENT_KEY (preferred) or OPENROUTER_API_KEY to use /usage.'
+        : `API Error: ${err.message}`;
+    await showOverlay(ctx, null, error, cachedMinutesAgo || 0);
+  }
+}
+
+async function showOverlay(
+  ctx: ExtensionContext,
+  summary: UsageSummary | null,
+  error: string | null,
+  cachedMinutesAgo: number | null,
+) {
+  await ctx.ui.custom<void>(
+    (_tui, theme, _keybindings, done) => {
+      const overlayComponent = new UsageOverlayComponent(
+        summary,
+        error,
+        cachedMinutesAgo,
+        theme,
+        done,
+        () => _tui.requestRender(),
+      );
+
+      return {
+        handleInput: (data: string) => {
+          overlayComponent.handleInput(data);
+          _tui.requestRender();
+        },
+        render: (width: number) => overlayComponent.render(width),
+        invalidate: () => overlayComponent.invalidate(),
+        dispose: () => {
+          overlayComponent.dispose();
+        },
+      };
+    },
+    { overlay: true },
+  );
+}

package/extensions/openrouter/overlay.ts

@@ -0,0 +1,334 @@
+import { matchesKey, truncateToWidth } from '@mariozechner/pi-tui';
+import type { Theme } from '@mariozechner/pi-coding-agent';
+import type { UsageSummary } from './types.js';
+import { usageCache } from './cache.js';
+
+const MIN_WIDTH = 44;
+const MAX_WIDTH = 80;
+
+export class UsageOverlayComponent {
+  private lines: string[];
+  private theme: Theme;
+  private onClose: () => void;
+  private width: number;
+  private summary: UsageSummary | null;
+  private error: string | null;
+  private cachedMinutesAgo: number | null;
+  private refreshTimer: NodeJS.Timeout | null = null;
+  private requestRender: () => void;
+  private isDisposed = false;
+
+  constructor(
+    summary: UsageSummary | null,
+    error: string | null,
+    cachedMinutesAgo: number | null,
+    theme: Theme,
+    onClose: () => void,
+    requestRender: () => void,
+  ) {
+    this.theme = theme;
+    this.onClose = onClose;
+    this.requestRender = requestRender;
+    this.summary = summary;
+    this.error = error;
+    this.cachedMinutesAgo = cachedMinutesAgo;
+    this.width = this.calculateWidth(summary);
+    this.lines = this.buildLines(summary, error, cachedMinutesAgo);
+
+    // Set up timer to rebuild lines every 30 seconds to update "last refreshed" time
+    this.refreshTimer = setInterval(() => {
+      this.invalidate();
+      // Force re-render by calling requestRender on the TUI
+      // We need to store a reference to requestRender to do this
+    }, 30000);
+  }
+
+  dispose(): void {
+    this.isDisposed = true;
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+
+  handleInput(data: string): void {
+    // Close on q, escape, or ctrl+c
+    if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c') || data === 'q') {
+      this.onClose();
+    }
+  }
+
+  render(width: number): string[] {
+    // Center the overlay if terminal is wider
+    const padding = Math.max(0, Math.floor((width - this.width) / 2));
+    const pad = ' '.repeat(padding);
+
+    return this.lines.map((line) => truncateToWidth(pad + line, width));
+  }
+
+  invalidate(): void {
+    if (this.isDisposed) return;
+    // Rebuild lines to update "last refreshed" time from fresh cached data
+    const freshSummary = usageCache.get('usage');
+    this.lines = this.buildLines(freshSummary || this.summary, this.error, this.cachedMinutesAgo);
+    this.requestRender();
+  }
+
+  private calculateWidth(summary: UsageSummary | null): number {
+    if (!summary) return MIN_WIDTH;
+
+    let maxWidth = MIN_WIDTH;
+
+    // Calculate width needed for top models table
+    if (summary.topModels7d.length > 0 || summary.topModels30d.length > 0) {
+      const allModelNames = [
+        ...summary.topModels7d.map((m) => m.name),
+        ...summary.topModels30d.map((m) => m.name),
+      ];
+      const maxModelNameLen = allModelNames.reduce((max, name) => Math.max(max, name.length), 0);
+      const amountWidth = 8; // "$X.XX" + padding
+      const rowWidth = 2 + maxModelNameLen + 2 + amountWidth + 2 + amountWidth + 2;
+      maxWidth = Math.max(maxWidth, rowWidth);
+    }
+
+    // Calculate width needed for provider table
+    if (summary.byKey && Object.keys(summary.byKey).length > 0) {
+      const maxProviderLen = Object.keys(summary.byKey).reduce(
+        (max, name) => Math.max(max, name.length),
+        0,
+      );
+      const amountWidth = 8;
+      const rowWidth = 2 + maxProviderLen + 2 + amountWidth + 2;
+      maxWidth = Math.max(maxWidth, rowWidth);
+    }
+
+    // Calculate width needed for by-day table
+    if (summary.byDay && Object.keys(summary.byDay).length > 0) {
+      maxWidth = Math.max(maxWidth, 21);
+    }
+
+    // Ensure we have room for main stats
+    // "Month $X.XX / $X.XX cap (XX%)" - max ~35 chars
+    // "burn ~$X.XX" = 13 chars + space + "Today $X.XX" = 11
+    // Need: 35 + 1 + 13 + 2 (borders) = 51, or 35 + 1 + 11 + 2 = 49
+    // Use 46 as it fits both cases with proper padding
+    maxWidth = Math.max(maxWidth, 46);
+
+    return Math.min(maxWidth, MAX_WIDTH);
+  }
+
+  private buildLines(
+    summary: UsageSummary | null,
+    error: string | null,
+    cachedMinutesAgo: number | null,
+  ): string[] {
+    const th = this.theme;
+    const lines: string[] = [];
+
+    if (error) {
+      lines.push(boxTop(this.width));
+      lines.push(row('OpenRouter Usage', this.width));
+      lines.push(emptyRow(this.width));
+      lines.push(row(th.fg('error', error), this.width));
+      if (cachedMinutesAgo !== null) {
+        lines.push(
+          row(th.fg('dim', `(last successful fetch: ${cachedMinutesAgo}m ago)`), this.width),
+        );
+      }
+      lines.push(boxBottom(this.width));
+      lines.push(plainRow(th.fg('dim', 'Esc to close'), this.width));
+      return lines;
+    }
+
+    if (!summary) {
+      lines.push(boxTop(this.width));
+      lines.push(row('OpenRouter Usage', this.width));
+      lines.push(emptyRow(this.width));
+      lines.push(row(th.fg('dim', 'No usage data available.'), this.width));
+      lines.push(boxBottom(this.width));
+      lines.push(plainRow(th.fg('dim', 'Esc to close'), this.width));
+      return lines;
+    }
+
+    // Summary view (subcommand views TODO)
+    lines.push(boxTop(this.width));
+    lines.push(row('OpenRouter Usage', this.width));
+    lines.push(emptyRow(this.width));
+
+    // Month row: amount stays with label, cap percentage right-aligned
+    const monthLeftBase = `Month $${fmt(summary.month)} / $${fmt(summary.cap)}`;
+    const monthRight = `cap (${summary.cap > 0 ? Math.round((summary.month / summary.cap) * 100) : 0}%)`;
+    lines.push(rowRightAligned(monthLeftBase, monthRight, this.width));
+
+    // 7d row: amount stays with label, burn rate right-aligned
+    const weekLeftBase = `7d    $${fmt(summary.week)}`;
+    const weekRight = `burn ~$${fmt(summary.burnRate)}`;
+    lines.push(rowRightAligned(weekLeftBase, weekRight, this.width));
+
+    // Today row on its own line
+    const todayContent = `Today $${fmt(summary.today)}`;
+    lines.push(rowRightAligned(todayContent, '', this.width));
+    lines.push(emptyRow(this.width));
+
+    // Top models - 7d and 30d as columns
+    if (summary.topModels7d.length > 0 || summary.topModels30d.length > 0) {
+      // Calculate column widths
+      const allModelNames = [
+        ...summary.topModels7d.map((m) => m.name),
+        ...summary.topModels30d.map((m) => m.name),
+      ];
+      const maxModelNameLen = allModelNames.reduce((max, name) => Math.max(max, name.length), 0);
+      const headerModelWidth = Math.max(7, maxModelNameLen);
+      const amountWidth = 8; // "$X.XX" + padding
+
+      lines.push(row('Top models', this.width));
+      lines.push(
+        row(
+          `  Model${' '.repeat(headerModelWidth - 5)}  ${'7d'.padStart(amountWidth)}  ${'30d'.padStart(amountWidth)}`,
+          this.width,
+        ),
+      );
+      lines.push(
+        row(
+          `  ${'-'.repeat(headerModelWidth)}  ${'-'.repeat(amountWidth)}  ${'-'.repeat(amountWidth)}`,
+          this.width,
+        ),
+      );
+
+      // Build spend map from 7d data
+      const spendMap = new Map<string, { spend7d: number; spend30d: number }>();
+      for (const m of summary.topModels7d) {
+        spendMap.set(m.name, { spend7d: m.spend, spend30d: 0 });
+      }
+      // Add/update with 30d data
+      for (const m of summary.topModels30d) {
+        const existing = spendMap.get(m.name);
+        spendMap.set(m.name, {
+          spend7d: existing?.spend7d ?? 0,
+          spend30d: m.spend,
+        });
+      }
+
+      // Sort by 30d spend (primary), then 7d (secondary)
+      const sortedModels = Array.from(spendMap.entries())
+        .sort((a, b) => b[1].spend30d - a[1].spend30d || b[1].spend7d - a[1].spend7d)
+        .slice(0, 6); // Show top 6 models
+
+      for (const [name, spends] of sortedModels) {
+        const spend7dStr = spends.spend7d > 0 ? `$${fmt(spends.spend7d)}` : '-';
+        const spend30dStr = spends.spend30d > 0 ? `$${fmt(spends.spend30d)}` : '-';
+        const modelLabel = name; // Don't truncate - let the row function handle it
+        lines.push(
+          row(
+            `  ${modelLabel}${' '.repeat(Math.max(0, headerModelWidth - name.length))}  ${spend7dStr.padStart(amountWidth)}  ${spend30dStr.padStart(amountWidth)}`,
+            this.width,
+          ),
+        );
+      }
+      lines.push(emptyRow(this.width));
+    }
+
+    // Usage by Provider
+    if (summary.byKey && Object.keys(summary.byKey).length > 0) {
+      const sortedProviders = Object.entries(summary.byKey)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 6);
+      const maxProviderLen = sortedProviders.reduce((max, [name]) => Math.max(max, name.length), 0);
+
+      lines.push(row('By provider', this.width));
+      lines.push(row(`  Provider${' '.repeat(maxProviderLen - 8)}  30d`, this.width));
+      lines.push(row(`  ${'-'.repeat(maxProviderLen)}  ------`, this.width));
+
+      for (const [provider, spend] of sortedProviders) {
+        lines.push(
+          row(
+            `  ${provider}${' '.repeat(maxProviderLen - provider.length)}  $${fmt(spend)}`,
+            this.width,
+          ),
+        );
+      }
+      lines.push(emptyRow(this.width));
+    }
+
+    // Usage by Day (7d)
+    if (summary.byDay && Object.keys(summary.byDay).length > 0) {
+      const sortedDays = Object.entries(summary.byDay)
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .slice(-7); // Last 7 days
+      const maxDateLen = sortedDays.reduce((max, [date]) => Math.max(max, date.length), 0);
+
+      lines.push(row('By day', this.width));
+      lines.push(row(`  Date${' '.repeat(maxDateLen - 4)}  Amount`, this.width));
+      lines.push(row(`  ${'-'.repeat(maxDateLen)}  ------`, this.width));
+
+      for (const [day, spend] of sortedDays) {
+        lines.push(
+          row(`  ${day}${' '.repeat(maxDateLen - day.length)}  $${fmt(spend)}`, this.width),
+        );
+      }
+      lines.push(emptyRow(this.width));
+    }
+
+    // Last refresh time at the bottom
+    if (summary?.timestamp) {
+      const refreshDate = new Date(summary.timestamp);
+      const timestampStr = refreshDate.toLocaleTimeString();
+      lines.push(row(`Last refreshed: ${timestampStr}`, this.width));
+      lines.push(emptyRow(this.width));
+    }
+
+    lines.push(boxBottom(this.width));
+    lines.push(plainRow(th.fg('dim', 'Esc to close'), this.width));
+    return lines;
+  }
+}
+
+// Helper functions
+function boxTop(width: number): string {
+  return `┌${'─'.repeat(width - 2)}┐`;
+}
+
+function boxBottom(width: number): string {
+  return `└${'─'.repeat(width - 2)}┘`;
+}
+
+function emptyRow(width: number): string {
+  return `│${' '.repeat(width - 2)}│`;
+}
+
+function row(content: string, width: number): string {
+  const truncated = content.length > width - 2 ? content.slice(0, width - 2) : content;
+  return `│${truncated}${' '.repeat(width - 2 - truncated.length)}│`;
+}
+
+function plainRow(content: string, width: number): string {
+  const truncated = content.length > width - 2 ? content.slice(0, width - 2) : content;
+  return ` ${truncated}${' '.repeat(width - 1 - truncated.length)} `;
+}
+
+// Helper to create a row with left content padded to align right content
+function rowRightAligned(leftContent: string, rightContent: string, width: number): string {
+  const boxInnerWidth = width - 2; // -2 for box borders
+  const rightWidth = rightContent.length;
+
+  if (rightWidth === 0) {
+    // No right content - just pad left to full width
+    const leftPadded = leftContent.padEnd(boxInnerWidth, ' ');
+    return row(leftPadded, width);
+  }
+
+  // Account for the space between left and right content
+  const remainingWidth = boxInnerWidth - rightWidth - 1;
+
+  // Pad left content to align right content
+  const leftPadded =
+    leftContent.length > remainingWidth
+      ? leftContent.slice(0, remainingWidth - 3) + '...'
+      : leftContent.padEnd(remainingWidth, ' ');
+
+  return row(`${leftPadded} ${rightContent}`, width);
+}
+
+function fmt(value: number): string {
+  return value.toFixed(2);
+}

package/extensions/openrouter/types.ts

@@ -0,0 +1,18 @@
+export interface UsageSummary {
+  today: number;
+  week: number;
+  month: number;
+  cap: number;
+  burnRate: number;
+  topModels7d: { name: string; spend: number }[];
+  topModels30d: { name: string; spend: number }[];
+  byModel?: Record<string, number>;
+  byKey?: Record<string, number>;
+  byDay?: Record<string, number>;
+  timestamp: number;
+}
+
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@robhowley/pi-openrouter",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Terminal overlay for OpenRouter usage: caps, spend, burn rate, and model breakdowns.",
+  "files": [
+    "extensions",
+    "README.md",
+    "../LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "openrouter"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/openrouter"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/robhowley/pi-userland.git",
+    "directory": "packages/pi-openrouter"
+  },
+  "homepage": "https://github.com/robhowley/pi-userland/tree/main/packages/pi-openrouter",
+  "scripts": {
+    "lint": "eslint extensions/",
+    "format:check": "prettier --check extensions/",
+    "format:write": "prettier --write extensions/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run __tests__"
+  },
+  "dependencies": {
+    "@mariozechner/pi-tui": "*",
+    "@openrouter/sdk": "^0.12.21"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.17"
+  }
+}