@robhowley/pi-openrouter 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-openrouter
 
-A [Pi](https://pi.dev/) extension for OpenRouter usage and session visibility, with an `/openrouter-usage` terminal overlay for spend, caps, burn rate, live tracking, and model breakdowns, plus automatic `session_id` tagging for dashboard grouping.
+A [Pi](https://pi.dev/) extension for live OpenRouter visibility: TUI overlays for spend, credits, key limits, burn rate, and model usage, plus automatic `session_id` tagging for dashboard grouping.
 
 ## Installation
 
@@ -35,6 +35,25 @@ The extension refreshes data in the background every 30 seconds (with exponentia
 
 <img src="https://raw.githubusercontent.com/robhowley/pi-userland/main/packages/pi-openrouter/img/openrouter-usage-tui.png" alt="OpenRouter Usage Overlay" width="600">
 
+## Account health
+
+Type `/openrouter-account` in Pi to open the account health overlay.
+
+The overlay shows:
+
+- **Credits** balance
+- **Total usage** against available credits
+- **Status by key**
+- **Selected key** details
+- **Key spend** vs configured limit
+- **Reset cadence**
+- **BYOK limit behavior**
+- **All visible keys**, when a management key is configured
+
+Select a key from the list to inspect its limit, usage, reset cadence, and BYOK behavior.
+
+<img src="https://raw.githubusercontent.com/robhowley/pi-userland/main/packages/pi-openrouter/img/openrouter-account-tui.png" alt="OpenRouter Account Overlay" width="600">
+
 ## Session tracking
 
 `pi-openrouter` automatically tags OpenRouter requests with `session_id` field set to the Pi session's ID.

package/extensions/openrouter/account-client.ts

@@ -0,0 +1,215 @@
+import { OpenRouter } from '@openrouter/sdk/sdk/sdk.js';
+import type { KeyInfo, KeyStatus } from './account-types.js';
+
+// Re-export error types from client.ts
+import { AuthError, ApiError } from './client.js';
+
+let client: OpenRouter | null = null;
+
+function getClient(): OpenRouter | null {
+  if (client) return client;
+  const apiKey = process.env['OPENROUTER_MANAGEMENT_KEY'] || process.env['OPENROUTER_API_KEY'];
+  if (!apiKey) return null;
+  client = new OpenRouter({ apiKey });
+  return client;
+}
+
+// =============================================================================
+// Account Credits API
+// =============================================================================
+
+export async function getAccountCredits(): Promise<number | null> {
+  const client = getClient();
+  if (!client) return null;
+  try {
+    const response = await client.credits.getCredits();
+    return response.data.totalCredits ?? null;
+  } catch (err) {
+    throw mapSdkError(err);
+  }
+}
+
+// =============================================================================
+// Key Management API
+// =============================================================================
+
+import type { GetCurrentKeyData, ListData } from '@openrouter/sdk/models/operations/index.js';
+
+// Workspace ID for the default workspace (empty string) - used when workspaceId is not specified
+const DEFAULT_WORKSPACE_ID = '';
+
+export async function getAllKeys(): Promise<KeyInfo[] | null> {
+  const client = getClient();
+  if (!client) return null;
+
+  try {
+    // First, get all workspaces
+    const workspacesResponse = await client.workspaces.list();
+    const workspaces: Array<{ id: string; name: string }> = [];
+    for await (const response of workspacesResponse) {
+      // response.result contains the ListWorkspacesResponse with data array
+      for (const workspace of response.result.data) {
+        workspaces.push({ id: workspace.id, name: workspace.name });
+      }
+    }
+
+    // Fetch keys from each workspace and combine them
+    const allKeys: KeyInfo[] = [];
+
+    for (const workspace of workspaces) {
+      const workspaceId = workspace.id || DEFAULT_WORKSPACE_ID;
+      const response = await client.apiKeys.list({ workspaceId, includeDisabled: true });
+      const rawKeys = response.data;
+
+      const keys = rawKeys.map((raw) => rawToKeyInfo(raw, workspace.name));
+      allKeys.push(...keys);
+    }
+
+    return allKeys;
+  } catch (err) {
+    // If management key fails (403), fall back to current key only
+    const sdkErr = err as { status?: number };
+    if (sdkErr.status === 403) {
+      return null;
+    }
+    throw mapSdkError(err);
+  }
+}
+
+export async function getCurrentKey(): Promise<KeyInfo | null> {
+  const client = getClient();
+  if (!client) return null;
+  try {
+    const response = await client.apiKeys.getCurrentKeyMetadata();
+    return rawToKeyInfo(response.data, 'Current Workspace');
+  } catch (err) {
+    throw mapSdkError(err);
+  }
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+function rawToKeyInfo(raw: GetCurrentKeyData | ListData, workspaceName: string): KeyInfo {
+  const used = raw.usage ?? raw.usageMonthly ?? 0;
+
+  // limit is number | null in both GetCurrentKeyData and ListData
+  const limitValue = raw.limit;
+
+  // remaining is number | null in both types
+  const remainingValue = raw.limitRemaining;
+
+  // Determine BYOK status
+  let byok: 'incl' | 'excl' | '?' = '?';
+  if (raw.includeByokInLimit === true) {
+    byok = 'incl';
+  } else if (raw.includeByokInLimit === false) {
+    byok = 'excl';
+  }
+
+  // Determine reset cadence
+  let resetCadence: 'monthly' | 'daily' | 'never' | 'partial' = 'partial';
+  if (raw.limitReset) {
+    const reset = raw.limitReset.toLowerCase();
+    if (reset === 'monthly') {
+      resetCadence = 'monthly';
+    } else if (reset === 'daily') {
+      resetCadence = 'daily';
+    } else if (reset === 'never') {
+      resetCadence = 'never';
+    }
+  }
+
+  // Determine hash (ListData has hash, GetCurrentKeyData doesn't)
+  const hash = 'hash' in raw ? (raw as ListData).hash : 'unknown';
+
+  // Determine name (ListData has name, GetCurrentKeyData doesn't - use label as fallback)
+  const name = 'name' in raw ? (raw as ListData).name : raw.label;
+
+  // Get disabled status (ListData has it, GetCurrentKeyData doesn't)
+  const disabled = 'disabled' in raw ? (raw as ListData).disabled : false;
+
+  // For exactOptionalPropertyTypes, we need to handle optional properties carefully
+  // The SDK returns number | null but KeyInfo expects number | undefined (or just number)
+  // We use type assertion to tell TypeScript that limit/remaining are either number or not set
+
+  // When limitValue is null, we set limit to undefined (or omit it)
+  // When limitValue is a number, we keep it as is
+  let limit: number | undefined;
+  if (limitValue !== null) {
+    limit = limitValue;
+  }
+
+  let remaining: number | undefined;
+  if (remainingValue !== null) {
+    remaining = remainingValue;
+  }
+
+  // Calculate status based on usage percentage
+  let status: KeyStatus;
+  if (disabled) {
+    status = 'disabled';
+  } else if (limit === undefined || limit === null) {
+    status = 'unbounded';
+  } else if (remaining !== undefined && remaining < 0) {
+    status = 'danger';
+  } else if (limit === 0) {
+    status = 'danger';
+  } else {
+    const usedPercent = (used / limit) * 100;
+    if (usedPercent >= 90) {
+      status = 'danger';
+    } else if (usedPercent >= 70) {
+      status = 'caution';
+    } else {
+      status = 'healthy';
+    }
+  }
+
+  // Create the object
+  const keyInfo: KeyInfo = {
+    name,
+    label: raw.label,
+    status,
+    used,
+    spend: used, // spend is the same as usage (in USD)
+    resetCadence,
+    byok,
+    hash,
+    disabled,
+    workspaceName,
+  };
+
+  // Set optional properties explicitly
+  if (limit !== undefined) {
+    keyInfo.limit = limit;
+  }
+  if (remaining !== undefined) {
+    keyInfo.remaining = remaining;
+  }
+
+  return keyInfo;
+}
+
+function mapSdkError(err: unknown): Error {
+  const rawErr = err as { status?: number; message?: string };
+  const status = rawErr.status;
+  const message = rawErr.message ?? 'Unknown error';
+
+  if (status === 401) {
+    return new AuthError(message);
+  }
+  if (status === 403) {
+    return new ApiError(`Forbidden: ${message}`);
+  }
+
+  if (err instanceof Error) return err;
+  return new Error(String(err));
+}
+
+export function getCurrentKeyHash(): string | undefined {
+  // For v1, we don't hash the current API key for comparison
+  // This is a follow-up item from the planning docs
+  return undefined;
+}

package/extensions/openrouter/account-format.ts

@@ -0,0 +1,97 @@
+import type { KeyInfo, KeyStatus, RollupStatus } from './account-types.js';
+
+// =============================================================================
+// Status Computation
+// =============================================================================
+
+/** Compute KeyStatus based on usage/limit ratio */
+export function computeKeyStatus(used: number, limit?: number, disabled?: boolean): KeyStatus {
+  // Disabled keys always show disabled
+  if (disabled) return 'disabled';
+
+  // No limit means unbounded
+  if (limit === undefined) return 'unbounded';
+
+  const usageRatio = used / limit;
+
+  if (usageRatio < 0.7) {
+    return 'healthy';
+  } else if (usageRatio < 0.9) {
+    return 'caution';
+  } else {
+    return 'danger';
+  }
+}
+
+// =============================================================================
+// Formatting
+// =============================================================================
+
+/** Format currency amount */
+export function formatCurrency(amount: number): string {
+  return `$${amount.toFixed(2)}`;
+}
+
+/** Format remaining with optional limit */
+export function formatRemaining(used: number, limit?: number): string {
+  if (limit === undefined) {
+    return `${formatCurrency(used)} / unlimited`;
+  }
+  return `${formatCurrency(used)} / ${formatCurrency(limit)}`;
+}
+
+/** Format remaining text */
+export function formatLeft(remaining?: number): string {
+  if (remaining === undefined) return '-';
+  return formatCurrency(remaining);
+}
+
+// =============================================================================
+// Sorting
+// =============================================================================
+
+/** Sort keys by priority: active first, then spend desc, then usage % desc */
+export function sortKeys(keys: KeyInfo[]): KeyInfo[] {
+  return [...keys].sort((a, b) => {
+    // Active keys first (disabled = false before disabled = true)
+    if (a.disabled !== b.disabled) {
+      return a.disabled ? 1 : -1;
+    }
+
+    // Within active group: spend descending
+    if (a.spend !== b.spend) {
+      return b.spend - a.spend;
+    }
+
+    // Within active group with same spend: usage % descending
+    const usagePercentA = a.limit ? (a.used / a.limit) * 100 : 0;
+    const usagePercentB = b.limit ? (b.used / b.limit) * 100 : 0;
+    if (usagePercentA !== usagePercentB) {
+      return usagePercentB - usagePercentA;
+    }
+
+    // Alphabetically by name as tiebreaker
+    return a.name.localeCompare(b.name);
+  });
+}
+
+// =============================================================================
+// Rollup Status
+// =============================================================================
+
+/** Compute overall account status from individual key statuses */
+export function computeRollupStatus(keys: KeyInfo[]): RollupStatus {
+  if (keys.length === 0) {
+    return { status: 'unavailable' as const };
+  }
+
+  // Count keys by traffic light status
+  const red = keys.filter((k) => k.status === 'disabled' || k.status === 'danger').length;
+  const yellow = keys.filter((k) => k.status === 'caution').length;
+  const green = keys.filter((k) => k.status === 'healthy' || k.status === 'unbounded').length;
+
+  return {
+    status: 'healthy' as const,
+    message: `🔴 ${red}  🟡 ${yellow}  🟢 ${green}`,
+  };
+}

package/extensions/openrouter/account-overlay.ts

@@ -0,0 +1,440 @@
+import { matchesKey, truncateToWidth } from '@mariozechner/pi-tui';
+import type { Theme, ThemeColor } from '@mariozechner/pi-coding-agent';
+import type { KeyInfo, KeyStatus, RollupStatus } from './account-types.js';
+import {
+  computeRollupStatus,
+  formatCurrency,
+  formatRemaining,
+  sortKeys,
+} from './account-format.js';
+import { getAllKeys, getCurrentKey, getAccountCredits } from './account-client.js';
+import type { ExtensionContext } from '@mariozechner/pi-coding-agent';
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const MIN_WIDTH = 65;
+
+// =============================================================================
+// Account Overlay Component
+// =============================================================================
+
+export class AccountOverlayComponent {
+  private lines: string[];
+  private theme: Theme;
+  private onClose: () => void;
+  private width: number;
+  private keyInfo: KeyInfo[] | null;
+  private credits: number | null;
+  private rollupStatus: RollupStatus;
+  private error: string | null;
+  private selectedIndex: number;
+  private refreshTimer: NodeJS.Timeout | null = null;
+  private requestRender: () => void;
+  private isDisposed = false;
+  private ctx: ExtensionContext | null = null;
+
+  constructor(
+    keyInfo: KeyInfo[] | null,
+    credits: number | null,
+    rollupStatus: RollupStatus,
+    error: string | null,
+    theme: Theme,
+    onClose: () => void,
+    requestRender: () => void,
+    ctx?: ExtensionContext,
+  ) {
+    this.theme = theme;
+    this.onClose = onClose;
+    this.requestRender = requestRender;
+    this.keyInfo = keyInfo;
+    this.credits = credits;
+    this.rollupStatus = rollupStatus;
+    this.error = error;
+    this.selectedIndex = 0;
+    this.ctx = ctx || null;
+    this.width = this.calculateWidth();
+    this.lines = this.buildLines();
+
+    // Set up timer to rebuild lines every 30 seconds
+    this.refreshTimer = setInterval(() => {
+      this.invalidate();
+    }, 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();
+      return;
+    }
+
+    // Refresh on r
+    if (matchesKey(data, 'r')) {
+      this.refresh();
+      return;
+    }
+
+    // Key selection with arrow keys
+    if (this.keyInfo && this.keyInfo.length > 0) {
+      if (matchesKey(data, 'up')) {
+        this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+        this.invalidate();
+      } else if (matchesKey(data, 'down')) {
+        this.selectedIndex = Math.min(this.keyInfo.length - 1, this.selectedIndex + 1);
+        this.invalidate();
+      }
+    }
+  }
+
+  wantsKeyRelease = false;
+
+  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
+    this.lines = this.buildLines();
+    // Clamp selected index if key list shrunk after re-sort
+    if (this.keyInfo && this.selectedIndex >= this.keyInfo.length) {
+      this.selectedIndex = this.keyInfo.length - 1;
+    }
+    if (!this.isDisposed) {
+      this.requestRender();
+    }
+  }
+
+  async refresh(): Promise<void> {
+    if (this.isDisposed || !this.ctx) return;
+
+    try {
+      const allKeys = await getAllKeys();
+      let credits: number | null = null;
+      try {
+        credits = await getAccountCredits();
+      } catch {
+        // Silently ignore credit fetch errors
+      }
+
+      let error: string | null = null;
+      let keyInfo: KeyInfo[] | null = null;
+
+      if (allKeys && allKeys.length > 0) {
+        keyInfo = allKeys;
+      } else {
+        error = 'Key list unavailable - set OPENROUTER_MANAGEMENT_KEY for full key inventory.';
+        try {
+          const currentKey = await getCurrentKey();
+          if (currentKey) {
+            keyInfo = [currentKey];
+          }
+        } catch {
+          // Ignore secondary errors
+        }
+      }
+
+      const rollupStatus = keyInfo
+        ? computeRollupStatus(keyInfo)
+        : { status: 'unavailable' as const };
+
+      // Update state
+      this.keyInfo = keyInfo;
+      this.credits = credits;
+      this.rollupStatus = rollupStatus;
+      this.error = error;
+
+      // Reset selection and rebuild
+      this.selectedIndex = 0;
+      this.width = this.calculateWidth();
+      this.lines = this.buildLines();
+
+      this.requestRender();
+    } catch {
+      // Silently ignore refresh errors
+    }
+  }
+
+  private calculateWidth(): number {
+    return Math.max(MIN_WIDTH, this.keyInfo && this.keyInfo.length > 0 ? 55 : 50);
+  }
+
+  private buildLines(): string[] {
+    const th = this.theme;
+    const lines: string[] = [];
+
+    if (this.error) {
+      lines.push(boxTop(this.width));
+      lines.push(
+        row(th.fg('accent', th.bold(' ◈ OpenRouter Account  ·  /openrouter-account')), this.width),
+      );
+      lines.push(emptyRow(this.width));
+      lines.push(row(th.fg('error', this.error), this.width));
+      lines.push(boxBottom(this.width));
+      lines.push(plainRow(th.fg('dim', 'Esc to close'), this.width));
+      return lines;
+    }
+
+    lines.push(boxTop(this.width));
+    lines.push(
+      row(th.fg('accent', th.bold(' ◈ OpenRouter Account  ·  /openrouter-account')), this.width),
+    );
+    lines.push(emptyRow(this.width));
+
+    // Total spend line (sum of all key spends)
+    if (this.keyInfo && this.keyInfo.length > 0) {
+      const totalSpend = this.keyInfo.reduce((sum, k) => sum + k.spend, 0);
+      lines.push(row(` usage      ${formatCurrency(totalSpend)}`, this.width));
+    }
+
+    // Credits line
+    if (this.credits !== null) {
+      lines.push(row(` credits    ${formatCurrency(this.credits)}`, this.width));
+    } else {
+      lines.push(row(th.fg('dim', ' credits          unavailable'), this.width));
+    }
+
+    // Status by key line
+    lines.push(row(` status     ${this.rollupStatus.message}`, this.width));
+    lines.push(emptyRow(this.width));
+
+    if (this.keyInfo && this.keyInfo.length > 0) {
+      // Sort keys - active first, then spend desc, then usage % desc
+      const sortedKeys = sortKeys(this.keyInfo);
+
+      // Current key section - show for selected key
+      // Defensive: ensure index is within bounds before accessing
+      const index = Math.max(0, Math.min(this.selectedIndex, sortedKeys.length - 1));
+      const currentKey = sortedKeys[index];
+      if (currentKey) {
+        lines.push(row(` ${th.fg('accent', 'Selected key')}`, this.width));
+        lines.push(...this.buildKeyDetails(currentKey, th));
+        lines.push(emptyRow(this.width));
+      }
+
+      // All keys section - show all keys in compact format (including current key)
+      lines.push(row(` ${th.fg('accent', 'All keys')}`, this.width));
+      lines.push(row(`   Workspace    Key name           Active   Spend    Used   `, this.width));
+      for (let i = 0; i < sortedKeys.length; i++) {
+        lines.push(this.buildCompactKeyRow(sortedKeys[i]!, th, i === this.selectedIndex));
+      }
+      lines.push(emptyRow(this.width));
+    } else {
+      // No keys available
+      lines.push(row(th.fg('dim', ' No keys available'), this.width));
+    }
+    lines.push(boxBottom(this.width));
+    lines.push(
+      plainRow(th.fg('dim', 'Esc to close  ·  r to refresh  ·  ↑/↓ to select'), this.width),
+    );
+    return lines;
+  }
+
+  private buildKeyDetails(key: KeyInfo, theme: Theme): string[] {
+    const lines: string[] = [];
+
+    // Format status with color
+    const statusColor = this.getStatusColor(key.status);
+    const statusText = key.status;
+    const formattedStatus = theme.fg(statusColor as ThemeColor, statusText);
+
+    // Format used/limit
+    const usedLimitText = formatRemaining(key.used, key.limit);
+
+    // Format reset cadence
+    const resetText = key.resetCadence || 'never';
+
+    lines.push(row(`  name      ${truncate(key.name, 30)}`, this.width));
+    lines.push(row(`  key       ${truncate(key.label, 30)}`, this.width));
+    lines.push(row(`  status    ${formattedStatus}`, this.width));
+    lines.push(row(`  used      ${usedLimitText}`, this.width));
+    lines.push(row(`  reset     ${resetText}`, this.width));
+    lines.push(row(`  byok      ${key.byok}`, this.width));
+
+    return lines;
+  }
+
+  private simplifiedWorkspaceName(workspaceName: string): string {
+    return workspaceName.replace(/Workspace$/, '').trim();
+  }
+
+  private buildCompactKeyRow(key: KeyInfo, theme: Theme, isSelected: boolean): string {
+    // Format spend
+    let spendText: string;
+    if (key.disabled) {
+      spendText = '-';
+    } else {
+      spendText = formatCurrency(key.spend);
+    }
+
+    // Color spend based on value
+    let spendColor: ThemeColor = 'success';
+    if (key.disabled) {
+      spendColor = 'dim';
+    } else if (key.spend >= 100) {
+      spendColor = 'error';
+    } else if (key.spend >= 50) {
+      spendColor = 'warning';
+    }
+
+    // Pad spend to 8 chars for alignment based on visible width
+    const paddedSpend = padToWidth(theme.fg(spendColor as ThemeColor, spendText), 8);
+
+    // Calculate usage percentage
+    let usageText: string;
+    if (key.disabled) {
+      usageText = '-';
+    } else if (key.limit === 0) {
+      usageText = '∞';
+    } else if (key.limit === undefined) {
+      usageText = '-';
+    } else if (key.used !== undefined && key.limit !== undefined) {
+      const percent = Math.round((key.used / key.limit) * 100);
+      usageText = `${percent}%`;
+    } else {
+      usageText = '-';
+    }
+
+    // Color usage based on percentage
+    let usageColor: ThemeColor = 'success';
+    if (key.disabled) {
+      usageColor = 'dim';
+    } else if (usageText === '∞') {
+      usageColor = 'error';
+    } else {
+      const percent = parseInt(usageText, 10);
+      if (percent >= 90) {
+        usageColor = 'error';
+      } else if (percent >= 70) {
+        usageColor = 'warning';
+      } else {
+        usageColor = 'success';
+      }
+    }
+
+    // Pad usage to 6 chars for alignment based on visible width
+    const paddedUsage = padToWidth(theme.fg(usageColor as ThemeColor, usageText), 5);
+
+    const enabledIcon = key.disabled
+      ? this.theme.fg('error' as ThemeColor, '\u2717')
+      : this.theme.fg('success' as ThemeColor, '\u2713');
+
+    // Truncate name and workspace for compact display
+    const name = truncate(key.name, 28);
+    const workspace = truncate(this.simplifiedWorkspaceName(key.workspaceName), 20);
+
+    // Selection indicator
+    const selectionIndicator = isSelected ? '●' : '○';
+
+    return row(
+      ` ${selectionIndicator} ${workspace.padEnd(11)}  ${name.padEnd(21)} ${enabledIcon}     ${paddedSpend}  ${paddedUsage}`,
+      this.width,
+    );
+  }
+
+  private getStatusColor(status: KeyStatus): ThemeColor {
+    switch (status) {
+      case 'danger':
+        return 'error';
+      case 'caution':
+        return 'warning';
+      case 'disabled':
+        return 'error';
+      case 'partial':
+        return 'warning';
+      case 'unbounded':
+        return 'success';
+      default:
+        return 'success';
+    }
+  }
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+function boxTop(width: number): string {
+  return `┌─${'─'.repeat(width - 4)}─┐`;
+}
+
+function boxBottom(width: number): string {
+  return `└─${'─'.repeat(width - 4)}─┘`;
+}
+
+function emptyRow(width: number): string {
+  return `│ ${' '.repeat(width - 4)} │`;
+}
+
+function row(content: string, width: number): string {
+  const innerWidth = width - 4; // -4 for box borders + padding spaces
+  const truncated = truncateToVisibleWidth(content, innerWidth);
+  return `│ ${truncated}${' '.repeat(innerWidth - getVisibleWidth(truncated))} │`;
+}
+
+function plainRow(content: string, width: number): string {
+  const innerWidth = width - 2; // -2 for outer spaces
+  const truncated = truncateToVisibleWidth(content, innerWidth);
+  return ` ${truncated}${' '.repeat(innerWidth - getVisibleWidth(truncated))} `;
+}
+
+// Truncate string to visible width, skipping ANSI escape codes
+function truncateToVisibleWidth(str: string, maxVisibleWidth: number): string {
+  let visibleSoFar = 0;
+  let i = 0;
+
+  while (i < str.length && visibleSoFar < maxVisibleWidth) {
+    const char = str[i];
+
+    if (char === '\x1b') {
+      // Skip ANSI escape sequence
+      // eslint-disable-next-line no-control-regex
+      const ansiMatch = str.slice(i).match(/^\x1b\[[0-9;]*m/);
+      if (ansiMatch) {
+        i += ansiMatch[0].length;
+        continue;
+      }
+    }
+    visibleSoFar++;
+    i++;
+  }
+  return str.slice(0, i);
+}
+
+// Calculate visible width of a string, excluding ANSI escape codes
+function getVisibleWidth(str: string): number {
+  // Remove ANSI escape codes
+  // eslint-disable-next-line no-control-regex
+  const ansiRegex = /\x1b\[[0-9;]*m/g;
+  const cleanStr = str.replace(ansiRegex, '');
+  return cleanStr.length;
+}
+
+// Truncate string to max length, adding ellipsis if needed
+function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  if (maxLen <= 3) return str.slice(0, maxLen);
+  return str.slice(0, maxLen - 3) + '...';
+}
+
+// Pad string to fixed width, accounting for ANSI escape codes
+function padToWidth(str: string, width: number): string {
+  const visibleWidth = getVisibleWidth(str);
+  const paddingNeeded = width - visibleWidth;
+  if (paddingNeeded <= 0) return str;
+  return str + ' '.repeat(paddingNeeded);
+}

package/extensions/openrouter/account-types.ts

@@ -0,0 +1,48 @@
+// Domain types for /openrouter-account command
+
+/** Status of a single key based on usage/limit ratio */
+export type KeyStatus =
+  | 'healthy' // <70% used
+  | 'caution' // 70-89% used
+  | 'danger' // >=90% used
+  | 'unbounded' // no key cap
+  | 'partial' // missing required fields
+  | 'disabled'; // disabled key
+
+/** BYOK (Bring-Your-Own-Key) status */
+export type BYOKStatus = 'incl' | 'excl' | '?';
+
+/** Reset cadence for key limits */
+export type ResetCadence = 'monthly' | 'daily' | 'never' | 'partial';
+
+/** Information about a single OpenRouter key */
+export interface KeyInfo {
+  name: string; // Human-readable name (e.g., "Production", "Development")
+  label: string; // Key value (masked, e.g., "sk-or-v1-4a0...459")
+  status: KeyStatus; // Current health status
+  used: number; // Current usage (currency)
+  limit?: number; // Key cap (optional)
+  remaining?: number; // limit - used
+  resetCadence: ResetCadence; // monthly, daily, never, or partial
+  byok: BYOKStatus; // incl (true), excl (false), ? (unavailable)
+  hash: string; // Key hash for identification
+  disabled: boolean; // Whether key is disabled
+  workspaceName: string; // Name of the workspace this key belongs to
+  spend: number; // Spend associated with this key (in USD)
+}
+
+/** Rollup status for the entire account */
+export type RollupStatus =
+  | { status: 'unavailable'; message?: never }
+  | { status: 'healthy'; message: string }
+  | { status: 'caution'; message: string }
+  | { status: 'danger'; message: string }
+  | { status: 'disabled'; message: string };
+
+/** Account credits info */
+export interface AccountCredits {
+  totalCredits: number; // Total credit cap
+  totalUsage: number; // Total usage
+  remaining?: number; // totalCredits - totalUsage
+  available?: boolean; // Whether credits are available
+}

package/extensions/openrouter/cache.ts

@@ -1,4 +1,4 @@
-import type { CacheEntry, UsageSummary } from './types.js';
+import type { CacheEntry, UsageSummary, LocalUsageEvent, UsageAggregate } from './types.js';
 import type { ActivityItem } from '@openrouter/sdk/models/index.js';
 import { aggregateUsage } from './format.js';
 import { getCredits, getActivity } from './client.js';
@@ -62,11 +62,8 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
   try {
     analytics = await getActivity();
     if (!analytics) hasActivityData = false;
-  } catch (err) {
+  } catch {
     // getActivity() requires a management key; suppress this expected error
-    if (!(err instanceof Error) || !err.message.includes('management key')) {
-      console.log('Activity fetch failed');
-    }
     hasActivityData = false;
   }
   const timestamp = Date.now();
@@ -106,13 +103,13 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
                 completionTokens: item.completionTokens,
                 reasoningTokens: item.reasoningTokens,
                 cost: item.usage,
-              }) as any,
+              }) as LocalUsageEvent,
           ),
         )
       : ZERO_AGGREGATE;
 
   // Read local JSONL after officialThroughDate
-  const localEvents: any[] = [];
+  const localEvents: LocalUsageEvent[] = [];
   if (officialThroughDate) {
     // Read from the day after officialThroughDate to today
     const localFrom = addUtcDays(officialThroughDate, 1);
@@ -123,9 +120,8 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
         toDateUtc: localTo,
       });
       localEvents.push(...localEventsList);
-    } catch (err) {
+    } catch {
       // Fail open - if local read fails, continue with empty local
-      console.log('Local usage read failed:', err);
     }
   }
 
@@ -133,7 +129,7 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
   const localAggregate = aggregateLocal(localEvents);
 
   // Combine official + local
-  const combinedAggregate: any = {
+  const combinedAggregate: UsageAggregate = {
     requests: officialAggregate.requests + localAggregate.requests,
     promptTokens: officialAggregate.promptTokens + localAggregate.promptTokens,
     completionTokens: officialAggregate.completionTokens + localAggregate.completionTokens,
@@ -172,11 +168,9 @@ function scheduleRefresh(): void {
       }
     } catch {
       consecutiveFailures++;
-      console.log(`Background refresh failed (${consecutiveFailures}/${MAX_RETRY_COUNT})`);
 
       // 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;

package/extensions/openrouter/format.ts

@@ -62,7 +62,7 @@ export function aggregateUsage(
     modelPermaslug: e.model || 'unknown',
   }));
 
-  const allData = [...analytics, ...localItems] as any[];
+  const allData = [...analytics, ...localItems];
 
   // Build model stats for both 7d and 30d windows
   // Use allData (combined API + local) for 30d, weekData (combined) for 7d

package/extensions/openrouter/index.ts

@@ -10,6 +10,11 @@ import { AuthError } from './client.js';
 import { UsageOverlayComponent } from './overlay.js';
 import { formatSessionId, isOpenRouterRequest, type OpenRouterSessionState } from './session.js';
 import { writeLocalUsage, type LocalUsageEvent } from './local-usage.js';
+import { AccountOverlayComponent } from './account-overlay.js';
+import { computeRollupStatus, sortKeys } from './account-format.js';
+import { getAllKeys, getCurrentKey, getAccountCredits } from './account-client.js';
+import type { KeyInfo } from './account-types.js';
+import type { RollupStatus } from './account-types.js';
 import crypto from 'node:crypto';
 
 // Store the current session state for use in command handlers
@@ -167,6 +172,140 @@ export default function (pi: ExtensionAPI) {
       ctx.ui.notify(`OpenRouter session_id\n${idToShow}`, 'info');
     },
   });
+
+  pi.registerCommand('openrouter-account', {
+    description: 'Show OpenRouter account and key health',
+    getArgumentCompletions: () => null,
+    handler: async (_args, ctx) => {
+      await showAccountOverlay(ctx);
+    },
+  });
+}
+
+async function showAccountOverlay(ctx: ExtensionContext) {
+  let error: string | null = null;
+  let keyInfo: KeyInfo[] | null = null;
+  let credits: number | null = null;
+
+  try {
+    // Try to get all keys with management key
+    const allKeys = await getAllKeys();
+
+    if (allKeys && allKeys.length > 0) {
+      keyInfo = allKeys;
+    } else {
+      // getAllKeys() returns null or empty array when management key isn't available
+      // or when the API call fails with 403
+      error = 'Key list unavailable - set OPENROUTER_MANAGEMENT_KEY for full key inventory.';
+
+      // Fall back to current key only
+      try {
+        const currentKey = await getCurrentKey();
+        if (currentKey) {
+          keyInfo = [currentKey];
+          // Clear the error since we successfully got current key
+          error = null;
+        } else {
+          error = 'Failed to retrieve current key metadata. Check your API key permissions.';
+        }
+      } catch (err) {
+        error = `Failed to retrieve current key: ${(err as Error).message}`;
+      }
+    }
+
+    // Try to get account credits
+    credits = await getAccountCredits();
+
+    // Set error if we have no keys and no credits
+    if (!keyInfo && !credits) {
+      error =
+        'OpenRouter API key not found. Set OPENROUTER_MANAGEMENT_KEY (preferred) or OPENROUTER_API_KEY to use /openrouter-account.';
+    }
+
+    // Set error if we have credits but no keys
+    if (!keyInfo && credits !== null) {
+      error =
+        error ||
+        'Key information unavailable. Set OPENROUTER_MANAGEMENT_KEY for full key inventory.';
+    }
+
+    // Compute rollup status
+    const rollupStatus = keyInfo
+      ? computeRollupStatus(keyInfo)
+      : { status: 'unavailable' as const };
+
+    // Sort keys
+    if (keyInfo) {
+      const sortedKeys = sortKeys(keyInfo);
+      keyInfo = sortedKeys;
+    }
+
+    await showAccountOverlayComponent(ctx, keyInfo, credits, rollupStatus, error);
+  } 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 /openrouter-account.'
+        : `API Error: ${err.message}`;
+
+    // Try to get current key for overlay even on error
+    try {
+      const currentKey = await getCurrentKey();
+      if (currentKey) {
+        keyInfo = [currentKey];
+      }
+    } catch {
+      // Ignore secondary errors
+    }
+
+    const rollupStatus = keyInfo
+      ? computeRollupStatus(keyInfo)
+      : { status: 'unavailable' as const };
+
+    await showAccountOverlayComponent(ctx, keyInfo, credits, rollupStatus, error);
+  }
+}
+
+async function showAccountOverlayComponent(
+  ctx: ExtensionContext,
+  keyInfo: KeyInfo[] | null,
+  credits: number | null,
+  rollupStatus: RollupStatus,
+  error: string | null,
+) {
+  await ctx.ui.custom<void>(
+    (_tui, theme, _keybindings, done) => {
+      const overlayComponent = new AccountOverlayComponent(
+        keyInfo,
+        credits,
+        rollupStatus,
+        error,
+        theme,
+        done,
+        () => _tui.requestRender(),
+        ctx,
+      );
+
+      return {
+        handleInput: (data: string) => {
+          overlayComponent.handleInput(data);
+          _tui.requestRender();
+        },
+        render: (width: number) => overlayComponent.render(width),
+        invalidate: () => overlayComponent.invalidate(),
+        dispose: () => {
+          overlayComponent.dispose();
+        },
+        wantsKeyRelease: false,
+      };
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        width: 100,
+      },
+    },
+  );
 }
 
 async function showUsageOverlay(ctx: ExtensionContext, _subcommand?: string) {

package/extensions/openrouter/overlay.ts

@@ -369,8 +369,8 @@ export class UsageOverlayComponent {
     lines.push(row(` By provider (30d)`, this.width));
     lines.push(
       row(
-        `    ${'Provider'.padEnd(COLS.model)}  ${'$'.padStart(COLS.spend)}  ` +
-          `${'tok'.padStart(COLS.tokens)}  ${'$/M'.padStart(COLS.costPerM)}  ` +
+        `    ${'Provider'.padEnd(COLS.model)}  ${'30d $'.padStart(COLS.spend)}  ` +
+          `${'30d tok'.padStart(COLS.tokens)}  ${'$/M'.padStart(COLS.costPerM)}  ` +
           `${'reqs'.padStart(COLS.reqs)}`,
         this.width,
       ),

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@robhowley/pi-openrouter",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
-  "description": "OpenRouter usage TUI overlay with caps, burn rate, models, live tracking, and session_id tagging.",
+  "description": "Live OpenRouter TUI overlays for spend, credits, key limits, burn rate, model usage, and session tagging.",
   "license": "MIT",
   "files": [
     "extensions",