@robhowley/pi-openrouter 0.4.0 → 0.5.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, and model breakdowns, plus automatic `session_id` tagging for dashboard grouping.
+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.
 
 ## Installation
 
@@ -12,8 +12,8 @@ pi install npm:@robhowley/pi-openrouter
 
 Set one of these environment variables:
 
-- `OPENROUTER_MANAGEMENT_KEY` (preferred) — provides full usage data including model breakdowns
-- `OPENROUTER_API_KEY` — basic usage data only
+- `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-...
@@ -26,20 +26,20 @@ 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**
+- **Today's spend** from live tracked turns while Activity API data catches up
 - **Top models** (7d and 30d)
 - **Usage by provider** (30d)
-- **Usage by day** (last 7 days)
+- **Daily spend** (30d)
 
 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.
+<img src="https://raw.githubusercontent.com/robhowley/pi-userland/main/packages/pi-openrouter/img/openrouter-usage-tui.png" alt="OpenRouter Usage Overlay" width="600">
 
 ## Session tracking
 
 `pi-openrouter` automatically tags OpenRouter requests with `session_id` field set to the Pi session's ID.
 
-Can view the Pi session ID with
+View the Pi session ID with
 
 ```bash
 /session  # [uuid]
@@ -54,7 +54,7 @@ The session can be tracked in OpenRouter's logs under the following ID:
 pi:[uuid]
 ```
 
-This feature allows for session level tracking the OpenRouter → Logs → Sessions page. It does not use Pi session names, local paths, repo names, branches, or other local identifiers.
+This enables session-level tracking in the OpenRouter Logs → Sessions page.
 
 ## License
 

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

@@ -4,16 +4,17 @@ import { renderSpendSparkline } from '../chart.js';
 import type { ActivityItem } from '@openrouter/sdk/models/index.js';
 
 describe('aggregateUsage', () => {
-  it('should correctly aggregate today spend regardless of timezone', () => {
+  it('should correctly aggregate today spend using UTC date', () => {
     const credits = {
       totalUsage: 10,
       totalCredits: 100,
     };
 
-    // Get today's date in YYYY-MM-DD format using LOCAL date
+    // Get today's date in YYYY-MM-DD format using UTC date
     // This matches how the API returns dates (YYYY-MM-DD without timezone)
+    // and how the implementation calculates 'today' (using UTC)
     const now = new Date();
-    const todayStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+    const todayStr = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}-${String(now.getUTCDate()).padStart(2, '0')}`;
 
     const analytics: ActivityItem[] = [
       {
@@ -33,9 +34,6 @@ describe('aggregateUsage', () => {
 
     const result = aggregateUsage(credits, analytics);
 
-    // Today should include data from todayStr (date strings compared directly)
-    // This was previously a bug where dates were parsed as UTC timestamps
-    // causing timezone-related filtering errors
     expect(result.today).toBe(6.55);
   });
 

package/extensions/openrouter/cache.ts

@@ -1,16 +1,13 @@
-import type { UsageSummary } from './types.js';
+import type { CacheEntry, UsageSummary } from './types.js';
 import type { ActivityItem } from '@openrouter/sdk/models/index.js';
 import { aggregateUsage } from './format.js';
 import { getCredits, getActivity } from './client.js';
+import { readLocalUsage, aggregateLocal, getCurrentUtcDate, addUtcDays } from './local-usage.js';
+import { ZERO_AGGREGATE } from './types.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>>();
 
@@ -73,8 +70,87 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
     hasActivityData = false;
   }
   const timestamp = Date.now();
-  const summary = aggregateUsage(credits, analytics ?? [], timestamp);
+
+  // Get official aggregate from Activity API data
+  const officialThroughDate = (function (): string | undefined {
+    if (!analytics || analytics.length === 0) return undefined;
+    let maxDate = '';
+    // Match YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
+    const dateRE = /^\d{4}-\d{2}-\d{2}/;
+    for (let i = 0; i < analytics.length; i++) {
+      const d = analytics[i];
+      if (d && d.date && dateRE.test(d.date)) {
+        const datePart = d.date.slice(0, 10); // Extract YYYY-MM-DD
+        if (datePart > maxDate) {
+          maxDate = datePart;
+        }
+      }
+    }
+    return maxDate || undefined;
+  })();
+
+  // Compute official aggregate (only from Activity API data up to officialThroughDate)
+  const officialAggregate =
+    hasActivityData && analytics && analytics.length > 0
+      ? aggregateLocal(
+          analytics.map(
+            (item) =>
+              ({
+                id: item.date + '-' + item.providerName + '-' + item.model,
+                sessionId: 'activity-api',
+                completedAt: item.date + 'T00:00:00.000Z',
+                requests: item.requests || 1,
+                model: item.model,
+                provider: item.providerName,
+                promptTokens: item.promptTokens,
+                completionTokens: item.completionTokens,
+                reasoningTokens: item.reasoningTokens,
+                cost: item.usage,
+              }) as any,
+          ),
+        )
+      : ZERO_AGGREGATE;
+
+  // Read local JSONL after officialThroughDate
+  const localEvents: any[] = [];
+  if (officialThroughDate) {
+    // Read from the day after officialThroughDate to today
+    const localFrom = addUtcDays(officialThroughDate, 1);
+    const localTo = getCurrentUtcDate();
+    try {
+      const localEventsList = await readLocalUsage({
+        fromDateUtc: localFrom,
+        toDateUtc: localTo,
+      });
+      localEvents.push(...localEventsList);
+    } catch (err) {
+      // Fail open - if local read fails, continue with empty local
+      console.log('Local usage read failed:', err);
+    }
+  }
+
+  // Aggregate local events
+  const localAggregate = aggregateLocal(localEvents);
+
+  // Combine official + local
+  const combinedAggregate: any = {
+    requests: officialAggregate.requests + localAggregate.requests,
+    promptTokens: officialAggregate.promptTokens + localAggregate.promptTokens,
+    completionTokens: officialAggregate.completionTokens + localAggregate.completionTokens,
+    reasoningTokens: officialAggregate.reasoningTokens + localAggregate.reasoningTokens,
+    cacheReadTokens: officialAggregate.cacheReadTokens + localAggregate.cacheReadTokens,
+    cacheWriteTokens: officialAggregate.cacheWriteTokens + localAggregate.cacheWriteTokens,
+    cost: officialAggregate.cost + localAggregate.cost,
+  };
+
+  // Build full summary with local events included for 7d/30d totals
+  const summary = aggregateUsage(credits, analytics ?? [], timestamp, localEvents);
   summary.hasActivityData = hasActivityData;
+  summary.officialThroughDate = (officialThroughDate as string | undefined) ?? undefined;
+  summary.official = officialAggregate;
+  summary.local = localAggregate;
+  summary.combined = combinedAggregate;
+
   return summary;
 }
 

package/extensions/openrouter/format.ts

@@ -1,56 +1,94 @@
 import type { ActivityItem } from '@openrouter/sdk/models/index.js';
 import type { ModelStats, ProviderStats, TokenStats, UsageSummary } from './types.js';
+import { ZERO_AGGREGATE, type LocalUsageEvent } from './types.js';
+import { getUtcDateFromTimestamp } from './local-usage.js';
 
-/** Convert a Date to YYYY-MM-DD string in local timezone (matching API format) */
-function localISODate(date: Date): string {
-  const year = date.getFullYear();
-  const month = String(date.getMonth() + 1).padStart(2, '0');
-  const day = String(date.getDate()).padStart(2, '0');
-  return `${year}-${month}-${day}`;
+/** Convert a Date to YYYY-MM-DD string in UTC (matching OpenRouter API format) */
+function utcISODate(date: Date): string {
+  return date.toISOString().slice(0, 10);
 }
 
 export function aggregateUsage(
   credits: { totalUsage: number; totalCredits?: number },
   analytics: ActivityItem[],
   timestamp: number = Date.now(),
+  localEvents: LocalUsageEvent[] = [],
 ): UsageSummary {
   const now = new Date();
-  const startOfDay = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  // Use UTC dates to match OpenRouter API (which uses UTC)
+  const startOfDay = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
   const startOfWeek = new Date(startOfDay);
-  startOfWeek.setDate(startOfWeek.getDate() - 7);
+  startOfWeek.setUTCDate(startOfWeek.getUTCDate() - 7);
 
   const weekData = analytics.filter((d) => {
-    // API dates are YYYY-MM-DD; compare by local date boundary
-    return d.date >= localISODate(startOfWeek);
+    // API dates are YYYY-MM-DD in UTC; compare by UTC date boundary
+    return d.date >= utcISODate(startOfWeek);
   });
 
   const todayData = analytics.filter((d) => {
-    // API dates are YYYY-MM-DD; compare by local date boundary
-    return d.date >= localISODate(startOfDay);
+    // API dates are YYYY-MM-DD in UTC; compare by UTC date boundary
+    return d.date >= utcISODate(startOfDay);
   });
 
-  const week = sumSpend(weekData);
-  const today = sumSpend(todayData);
+  const weekFromAnalytics = sumSpend(weekData);
+  const todayFromAnalytics = sumSpend(todayData);
   const month = credits.totalUsage;
 
+  // Add local events to compute combined totals
+  const weekFromLocal = localEvents
+    .filter((e) => getUtcDateFromTimestamp(e.completedAt) >= utcISODate(startOfWeek))
+    .reduce((sum, e) => sum + (e.cost || 0), 0);
+  const todayFromLocal = localEvents
+    .filter((e) => getUtcDateFromTimestamp(e.completedAt) >= utcISODate(startOfDay))
+    .reduce((sum, e) => sum + (e.cost || 0), 0);
+
+  const week = weekFromAnalytics + weekFromLocal;
+  const today = todayFromAnalytics + todayFromLocal;
+
+  // Merge analytics with local events for model/provider stats
+  // Convert local events to ActivityItem-like format for existing functions
+  const localItems = localEvents.map((e) => ({
+    date: getUtcDateFromTimestamp(e.completedAt),
+    usage: e.cost || 0,
+    promptTokens: e.promptTokens || 0,
+    completionTokens: e.completionTokens || 0,
+    reasoningTokens: e.reasoningTokens || 0,
+    requests: e.requests || 1,
+    model: e.model || 'unknown',
+    providerName: e.provider || 'unknown',
+    // Required fields that aren't used by our functions
+    byokUsageInference: 0,
+    endpointId: 'local-turns',
+    modelPermaslug: e.model || 'unknown',
+  }));
+
+  const allData = [...analytics, ...localItems] as any[];
+
   // Build model stats for both 7d and 30d windows
-  const modelStatsMap = buildModelStats(weekData, analytics);
+  // Use allData (combined API + local) for 30d, weekData (combined) for 7d
+  const modelStatsMap = buildModelStats(weekData, allData);
   const topModels = Array.from(modelStatsMap.values())
     .sort((a, b) => b.spend30d - a.spend30d)
     .slice(0, 10);
 
-  return {
+  const summary = {
     today,
     week,
     month,
     cap: credits.totalCredits ?? 0,
     burnRate: (week / 7) * 30,
     topModels,
-    byProvider: buildProviderStats(analytics),
-    byDay: aggregateByDay(analytics),
+    byProvider: buildProviderStats(allData),
+    byDay: aggregateByDay(allData),
     timestamp,
     hasActivityData: true, // aggregateUsage is only called when analytics data is available
-  };
+    officialThroughDate: undefined as string | undefined,
+    official: ZERO_AGGREGATE,
+    local: ZERO_AGGREGATE,
+    combined: ZERO_AGGREGATE,
+  } as UsageSummary;
+
+  return summary;
 }
 
 function sumSpend(data: ActivityItem[]): number {
@@ -62,8 +100,9 @@ function aggregateTokens(data: ActivityItem[]): TokenStats {
     (acc, d) => {
       acc.input += d.promptTokens || 0;
       acc.output += d.completionTokens || 0;
-      acc.reasoning += d.reasoningTokens || 0;
-      acc.total += (d.promptTokens || 0) + (d.completionTokens || 0) + (d.reasoningTokens || 0);
+      acc.reasoning += (d.reasoningTokens || 0) as number;
+      acc.total +=
+        (d.promptTokens || 0) + (d.completionTokens || 0) + ((d.reasoningTokens || 0) as number);
       return acc;
     },
     { input: 0, output: 0, reasoning: 0, total: 0 } as TokenStats,

package/extensions/openrouter/index.ts

@@ -9,6 +9,7 @@ import {
 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 crypto from 'node:crypto';
 
 // Store the current session state for use in command handlers
@@ -47,6 +48,7 @@ export default function (pi: ExtensionAPI) {
   // Install before_provider_request hook once
   if (!sessionTrackingInstalled) {
     sessionTrackingInstalled = true;
+
     pi.on('before_provider_request', (event, ctx) => {
       try {
         // Validate the payload exists
@@ -79,6 +81,70 @@ export default function (pi: ExtensionAPI) {
     });
   }
 
+  // Hook turn_end to capture completed OpenRouter turns for local logging
+  pi.on('turn_end', async (event, ctx) => {
+    try {
+      const turnEvent = event as unknown as Record<string, unknown>;
+
+      const message = turnEvent['message'] as Record<string, unknown> | undefined;
+      if (!message) return;
+
+      // Check if this is an OpenRouter request based on the message content/model
+      const isOpenRouter = isOpenRouterRequest(
+        { type: 'before_provider_request', payload: message } as unknown as Parameters<
+          typeof isOpenRouterRequest
+        >[0],
+        ctx,
+      );
+      if (!isOpenRouter) return;
+
+      // Check if the message has usage data
+      const usage = (message as { usage?: unknown })['usage'] as
+        | {
+            input?: number;
+            output?: number;
+            cacheRead?: number;
+            cacheWrite?: number;
+            totalTokens?: number;
+            cost?: {
+              input?: number;
+              output?: number;
+              cacheRead?: number;
+              cacheWrite?: number;
+              total?: number;
+            };
+          }
+        | undefined;
+      if (!usage) return;
+
+      // Extract model from the message
+      const model = message['model'] as string | undefined;
+      const responseModel = message['responseModel'] as string | undefined;
+      const modelToLog = model || responseModel;
+
+      // Calculate total cost from usage.cost.total
+      const totalCost = usage.cost?.total;
+
+      const localEvent = {
+        id: crypto.randomUUID(),
+        generationId: message['responseId'],
+        sessionId: getCurrentSessionId(ctx),
+        completedAt: new Date().toISOString(),
+        model: modelToLog,
+        promptTokens: usage.input,
+        completionTokens: usage.output,
+        cacheReadTokens: usage.cacheRead,
+        cacheWriteTokens: usage.cacheWrite,
+        cost: totalCost,
+      } as LocalUsageEvent;
+
+      // Write to local JSONL - fail open (don't throw)
+      writeLocalUsage(localEvent).catch(() => {});
+    } catch {
+      // Fail open - silently ignore errors
+    }
+  });
+
   pi.on('session_shutdown', () => {
     stopBackgroundRefresh();
   });

package/extensions/openrouter/local-usage.ts

@@ -0,0 +1,148 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import type { LocalUsageEvent, UsageAggregate } from './types.js';
+import { ZERO_AGGREGATE } from './types.js';
+
+export type { LocalUsageEvent };
+
+const LOCAL_USAGE_DIR = path.join(os.homedir(), '.pi', 'openrouter', 'usage');
+
+/**
+ * Get current UTC date as YYYY-MM-DD
+ */
+export function getCurrentUtcDate(): string {
+  const now = new Date();
+  return now.toISOString().slice(0, 10);
+}
+
+/**
+ * Extract UTC date from ISO timestamp (YYYY-MM-DDTHH:mm:ss.sssZ)
+ */
+export function getUtcDateFromTimestamp(isoString: string): string {
+  return isoString.slice(0, 10);
+}
+
+/**
+ * Add days to a YYYY-MM-DD date string, return new YYYY-MM-DD in UTC
+ */
+export function addUtcDays(dateStr: string, days: number): string {
+  const date = new Date(dateStr + 'T00:00:00Z');
+  if (isNaN(date.getTime())) {
+    throw new Error(`Invalid date string: ${dateStr}`);
+  }
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * Iterate dates from start to end (inclusive), return array of YYYY-MM-DD strings
+ */
+export function* iterateDates(start: string, end: string): Generator<string> {
+  let current = start;
+  while (current <= end) {
+    yield current;
+    current = addUtcDays(current, 1);
+  }
+}
+
+/**
+ * Append a single LocalUsageEvent to the appropriate daily JSONL file.
+ * File is determined by UTC date from completedAt.
+ */
+export async function writeLocalUsage(event: LocalUsageEvent): Promise<void> {
+  try {
+    const dateStr = getUtcDateFromTimestamp(event.completedAt);
+    const filePath = path.join(LOCAL_USAGE_DIR, `${dateStr}.jsonl`);
+
+    await fs.mkdir(LOCAL_USAGE_DIR, { recursive: true });
+
+    const line = JSON.stringify(event) + '\n';
+    await fs.appendFile(filePath, line, 'utf8');
+  } catch (err) {
+    // Fail open - log but don't throw to avoid breaking the user experience
+    console.error('[local-usage] Failed to write usage event:', err);
+  }
+}
+
+export interface ReadLocalUsageOptions {
+  /** Start date inclusive (YYYY-MM-DD) */
+  fromDateUtc: string;
+  /** End date inclusive (YYYY-MM-DD) */
+  toDateUtc: string;
+}
+
+/**
+ * Read local usage events from JSONL files for the given date range.
+ * Tolerates missing files, blank lines, and malformed lines.
+ */
+export async function readLocalUsage(options: ReadLocalUsageOptions): Promise<LocalUsageEvent[]> {
+  const events: LocalUsageEvent[] = [];
+
+  for (const dateStr of iterateDates(options.fromDateUtc, options.toDateUtc)) {
+    const filePath = path.join(LOCAL_USAGE_DIR, `${dateStr}.jsonl`);
+
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      const lines = content.split('\n');
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+
+        try {
+          const event = JSON.parse(trimmed) as LocalUsageEvent;
+          events.push(event);
+        } catch (parseErr) {
+          // Skip malformed lines but continue
+          console.warn(`[local-usage] Malformed line in ${dateStr}.jsonl:`, parseErr);
+        }
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        // Missing file is OK - just no data for this date
+        continue;
+      }
+      console.error(`[local-usage] Failed to read ${dateStr}.jsonl:`, err);
+      // Continue to next date despite error
+    }
+  }
+
+  return events;
+}
+
+/**
+ * Aggregate local usage events into UsageAggregate.
+ * Deduplicates by id (first occurrence wins).
+ */
+export function aggregateLocal(events: LocalUsageEvent[]): UsageAggregate {
+  if (events.length === 0) {
+    return ZERO_AGGREGATE;
+  }
+
+  // Deduplicate by id
+  const seen = new Set<string>();
+  const unique: LocalUsageEvent[] = [];
+
+  for (const event of events) {
+    if (seen.has(event.id)) continue;
+    seen.add(event.id);
+    unique.push(event);
+  }
+
+  // Aggregate
+  const result = unique.reduce(
+    (acc, event) => {
+      acc.requests += event.requests ?? 1;
+      acc.promptTokens += event.promptTokens || 0;
+      acc.completionTokens += event.completionTokens || 0;
+      acc.reasoningTokens += event.reasoningTokens || 0;
+      acc.cacheReadTokens += event.cacheReadTokens || 0;
+      acc.cacheWriteTokens += event.cacheWriteTokens || 0;
+      acc.cost += event.cost || 0;
+      return acc;
+    },
+    { ...ZERO_AGGREGATE },
+  );
+  return result;
+}

package/extensions/openrouter/overlay.ts

@@ -188,9 +188,12 @@ export class UsageOverlayComponent {
     }
     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));
+    // Today row on its own line - shows tilde since from local logs
+    const todayReqStr =
+      summary.local.requests > 0 ? ` · ${fmtCount(summary.local.requests)} reqs` : '';
+    lines.push(
+      rowRightAligned(` Today ~$${fmt(summary.local.cost)}${todayReqStr}`, '  ', this.width),
+    );
     lines.push(emptyRow(this.width));
 
     // Top models (7d table)
@@ -227,8 +230,32 @@ export class UsageOverlayComponent {
     // 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));
+      const timestampStr = refreshDate.toLocaleTimeString('en-US', {
+        hour: 'numeric',
+        minute: '2-digit',
+        second: '2-digit',
+      });
+
+      // Build footer parts (always show all parts)
+      const footerParts: string[] = [];
+      footerParts.push(`Updated ${timestampStr}`);
+
+      // Official through date - show if available
+      if (summary.officialThroughDate) {
+        const date = new Date(summary.officialThroughDate + 'T00:00:00Z');
+        if (!isNaN(date.getTime())) {
+          const dateStr = date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+          footerParts.push(`API through ${dateStr}`);
+        }
+      } else {
+        // Show placeholder when no activity data is available
+        footerParts.push('API data pending');
+      }
+
+      // Today from tracked turns
+      footerParts.push('Today from tracked turns');
+
+      lines.push(row(` ${footerParts.join('  ·  ')}`, this.width));
       lines.push(emptyRow(this.width));
 
       // Warning if data is limited due to missing management key

package/extensions/openrouter/types.ts

@@ -33,8 +33,72 @@ export interface UsageSummary {
   byDay: Record<string, number>;
   timestamp: number;
   hasActivityData: boolean;
+
+  /** Date of latest official Activity API data (YYYY-MM-DD) */
+  officialThroughDate?: string | undefined;
+
+  /** Aggregate from Activity API */
+  official: UsageAggregate;
+
+  /** Aggregate from local JSONL after officialThroughDate */
+  local: UsageAggregate;
+
+  /** Combined official + local */
+  combined: UsageAggregate;
 }
 
+export interface LocalUsageEvent {
+  /** UUID for deduplication */
+  id: string;
+
+  /** Generation ID from OpenRouter **/
+  generationId: string;
+
+  /** Existing pi-openrouter session ID */
+  sessionId: string;
+
+  /** ISO 8601 UTC timestamp */
+  completedAt: string;
+
+  /** Always 1 per completed turn; typed as number for flexibility */
+  requests?: number;
+
+  model?: string;
+
+  /**
+   * Actual OpenRouter routed provider (NOT "openrouter").
+   * Examples: "ionstream/fp8", "parasail/bf16", "inceptron/int4"
+   */
+  provider?: string;
+
+  promptTokens?: number;
+  completionTokens?: number;
+  reasoningTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  cost?: number;
+}
+
+export interface UsageAggregate {
+  requests: number;
+  promptTokens: number;
+  completionTokens: number;
+  reasoningTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  cost: number;
+}
+
+export const ZERO_AGGREGATE: UsageAggregate = {
+  requests: 0,
+  promptTokens: 0,
+  completionTokens: 0,
+  reasoningTokens: 0,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  cost: 0,
+};
+
 export interface CacheEntry<T> {
   data: T;
   timestamp: number;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@robhowley/pi-openrouter",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
-  "description": "OpenRouter usage TUI overlay with caps, spend, burn rate, models, and session_id tracking.",
+  "description": "OpenRouter usage TUI overlay with caps, burn rate, models, live tracking, and session_id tagging.",
+  "license": "MIT",
   "files": [
     "extensions",
     "README.md",