@robhowley/pi-openrouter 0.3.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+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,35 @@ 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">
 
-## Features
+## Session tracking
 
-- 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)
+`pi-openrouter` automatically tags OpenRouter requests with `session_id` field set to the Pi session's ID.
+
+View the Pi session ID with
+
+```bash
+/session  # [uuid]
+```
+
+The session can be tracked in OpenRouter's logs under the following ID:
+
+```bash
+/openrouter-session
+
+# OpenRouter session_id
+pi:[uuid]
+```
+
+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/__tests__/session.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { isOpenRouterRequest, formatSessionId } from '../session.js';
+
+// =============================================================================
+// Session ID Formatting Tests
+// =============================================================================
+
+describe('formatSessionId', () => {
+  it('adds pi: prefix if missing', () => {
+    expect(formatSessionId('abc123')).toBe('pi:abc123');
+  });
+
+  it('does not add duplicate pi: prefix', () => {
+    expect(formatSessionId('pi:abc123')).toBe('pi:abc123');
+  });
+});
+
+// =============================================================================
+// Request Detection Tests
+// =============================================================================
+
+// Helper to create mock event
+function createEvent(
+  payload: Record<string, unknown>,
+  url?: string,
+  provider?: Record<string, unknown>,
+) {
+  const event: any = { payload };
+  if (url) event.url = url;
+  if (provider) event.provider = provider;
+  return event;
+}
+
+// Helper to create mock context
+function createContext(model: string | Record<string, unknown>) {
+  return { model } as any;
+}
+
+describe('isOpenRouterRequest', () => {
+  // Method 1: Check model string (e.g., "openrouter/anthropic/claude-3.5-sonnet")
+  it('detects OpenRouter by model prefix', () => {
+    const event = createEvent({ model: 'openrouter/anthropic/claude-sonnet-4' });
+    expect(isOpenRouterRequest(event, {})).toBe(true);
+  });
+
+  it('does not detect non-OpenRouter by model prefix', () => {
+    const event = createEvent({ model: 'anthropic/claude-sonnet-4' });
+    expect(isOpenRouterRequest(event, {})).toBe(false);
+  });
+
+  // Method 2: Check baseUrl from context.model
+  it('detects OpenRouter by baseUrl', () => {
+    const event = createEvent({ model: 'qwen/qwen3-coder-next' });
+    const ctx = createContext({ baseUrl: 'https://openrouter.ai/api/v1' });
+    expect(isOpenRouterRequest(event, ctx)).toBe(true);
+  });
+
+  it('does not detect non-OpenRouter by baseUrl', () => {
+    const event = createEvent({ model: 'qwen/qwen3-coder-next' });
+    const ctx = createContext({ baseUrl: 'https://api.anthropic.com' });
+    expect(isOpenRouterRequest(event, ctx)).toBe(false);
+  });
+
+  // Method 3: Check for ZDR provider (Shopify routes to OpenRouter via ZDR)
+  it('detects OpenRouter by ZDR provider', () => {
+    const event = createEvent({ model: 'qwen/qwen3-coder-next' }, undefined, { zdr: true });
+    expect(isOpenRouterRequest(event, {})).toBe(true);
+  });
+
+  it('does not detect non-ZDR provider', () => {
+    const event = createEvent({ model: 'qwen/qwen3-coder-next', provider: 'openrouter' });
+    expect(isOpenRouterRequest(event, {})).toBe(false);
+  });
+
+  // Method 4: Check URL
+  it('detects OpenRouter by URL', () => {
+    const event = createEvent(
+      { model: 'anthropic/claude-sonnet_4', messages: [] },
+      'https://openrouter.ai/api/v1/chat/completions',
+    );
+    expect(isOpenRouterRequest(event, {})).toBe(true);
+  });
+
+  it('does not detect non-OpenRouter by URL', () => {
+    const event = createEvent(
+      { model: 'anthropic/claude-sonnet_4', messages: [] },
+      'https://api.anthropic.com/v1/messages',
+    );
+    expect(isOpenRouterRequest(event, {})).toBe(false);
+  });
+
+  // Combined methods
+  it('detects by multiple methods simultaneously', () => {
+    const event = createEvent(
+      { model: 'openrouter/anthropic/claude-sonnet-4' },
+      'https://openrouter.ai/api/v1/chat/completions',
+    );
+    const ctx = createContext({ baseUrl: 'https://openrouter.ai/api/v1' });
+    expect(isOpenRouterRequest(event, ctx)).toBe(true);
+  });
+});

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>>();
 
@@ -68,13 +65,92 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
   } catch (err) {
     // getActivity() requires a management key; suppress this expected error
     if (!(err instanceof Error) || !err.message.includes('management key')) {
-      console.log('Activity fetch failed:', err);
+      console.log('Activity fetch failed');
     }
     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;
 }
 
@@ -94,9 +170,9 @@ function scheduleRefresh(): void {
           scheduleRefresh();
         }
       }
-    } catch (err) {
+    } catch {
       consecutiveFailures++;
-      console.log(`Background refresh failed (${consecutiveFailures}/${MAX_RETRY_COUNT}):`, err);
+      console.log(`Background refresh failed (${consecutiveFailures}/${MAX_RETRY_COUNT})`);
 
       // Stop after max retries reached
       if (consecutiveFailures >= MAX_RETRY_COUNT) {

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

@@ -8,10 +8,141 @@ import {
 } from './cache.js';
 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
+let currentSessionState: OpenRouterSessionState | null = null;
+let sessionTrackingInstalled = false;
+
+// =============================================================================
+// Session State Management
+// =============================================================================
+
+function getCurrentSessionId(ctx: { sessionManager: { getSessionId(): string } }): string {
+  if (currentSessionState) {
+    return currentSessionState.sessionId;
+  }
+
+  try {
+    const sessionId = ctx.sessionManager.getSessionId();
+    let formattedSessionId: string;
+    if (sessionId && sessionId !== '') {
+      formattedSessionId = formatSessionId(sessionId);
+    } else {
+      formattedSessionId = formatSessionId(crypto.randomUUID());
+    }
+
+    currentSessionState = { sessionId: formattedSessionId };
+    return formattedSessionId;
+  } catch {
+    // Generate fallback on any error
+    const fallbackId = formatSessionId(crypto.randomUUID());
+    currentSessionState = { sessionId: fallbackId };
+    return fallbackId;
+  }
+}
 
 export default function (pi: ExtensionAPI) {
-  pi.on('session_start', async (_event, ctx) => {
-    ctx.ui.notify('OpenRouter extension loaded', 'info');
+  // Install before_provider_request hook once
+  if (!sessionTrackingInstalled) {
+    sessionTrackingInstalled = true;
+
+    pi.on('before_provider_request', (event, ctx) => {
+      try {
+        // Validate the payload exists
+        const ev = event as unknown as Record<string, unknown>;
+        const payload = ev['payload'] as Record<string, unknown> | undefined;
+        if (!payload) {
+          return;
+        }
+
+        // Check if this is an OpenRouter request
+        const isOpenRouter = isOpenRouterRequest(event, ctx);
+        if (!isOpenRouter) {
+          return;
+        }
+
+        // Do not overwrite existing session_id
+        if ('session_id' in payload && payload['session_id'] !== undefined) {
+          return;
+        }
+
+        // Add session_id to the payload (OpenRouter-specific field)
+        return {
+          ...payload,
+          session_id: getCurrentSessionId(ctx),
+        };
+      } catch {
+        // Fail open - silently ignore errors
+        return;
+      }
+    });
+  }
+
+  // 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', () => {
@@ -22,11 +153,20 @@ export default function (pi: ExtensionAPI) {
     description: 'Show OpenRouter usage: caps, spend, burn rate, and model breakdowns',
     getArgumentCompletions: () => null,
     handler: async (args, ctx) => {
-      startBackgroundRefresh(); // Start cache refresh on first use
+      startBackgroundRefresh();
       const subcommand = args.trim() || undefined;
       await showUsageOverlay(ctx, subcommand);
     },
   });
+
+  pi.registerCommand('openrouter-session', {
+    description: 'Show the current OpenRouter session ID for request grouping',
+    getArgumentCompletions: () => null,
+    handler: async (_args, ctx) => {
+      const idToShow = getCurrentSessionId(ctx);
+      ctx.ui.notify(`OpenRouter session_id\n${idToShow}`, 'info');
+    },
+  });
 }
 
 async function showUsageOverlay(ctx: ExtensionContext, _subcommand?: string) {

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/session.ts

@@ -0,0 +1,60 @@
+import type { BeforeProviderRequestEvent } from '@mariozechner/pi-coding-agent';
+
+// =============================================================================
+// Types & State
+// =============================================================================
+
+export type OpenRouterSessionState = {
+  sessionId: string;
+};
+
+// =============================================================================
+// State Factory
+// =============================================================================
+
+export function formatSessionId(sessionId: string): string {
+  if (sessionId.startsWith('pi:')) {
+    return sessionId;
+  }
+  return `pi:${sessionId}`;
+}
+
+// =============================================================================
+// Detection Logic
+// =============================================================================
+
+export function isOpenRouterRequest(event: BeforeProviderRequestEvent, _ctx: unknown): boolean {
+  const ev = event as unknown as Record<string, unknown>;
+
+  // Method 1: Check model string (e.g., "openrouter/anthropic/claude-3.5-sonnet")
+  const payload = ev['payload'] as Record<string, unknown> | undefined;
+  const model = String(payload?.['model'] ?? '');
+  if (model.includes('openrouter/')) {
+    return true;
+  }
+
+  // Method 2: Check baseUrl from context.model
+  // OpenRouter models have baseUrl starting with https://openrouter.ai/api/v1
+  const context = _ctx as Record<string, unknown>;
+  const ctxModel = context['model'] as Record<string, unknown> | undefined;
+  const baseUrl = ctxModel?.['baseUrl'] as string | undefined;
+  if (baseUrl?.includes('openrouter.ai')) {
+    return true;
+  }
+
+  // Method 3: Check for ZDR provider (Shopify routes to OpenRouter via ZDR)
+  const provider = ev['provider'] as Record<string, unknown> | undefined;
+  if (provider?.['zdr'] === true) {
+    return true;
+  }
+
+  // Method 4: Check URL
+  const url = String(
+    (ev['url'] as string | undefined) ?? (ev['endpoint'] as string | undefined) ?? '',
+  );
+  if (url.includes('openrouter.ai')) {
+    return true;
+  }
+
+  return false;
+}

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.3.1",
+  "version": "0.5.0",
   "type": "module",
-  "description": "Terminal overlay for OpenRouter usage: caps, spend, burn rate, and model breakdowns.",
+  "description": "OpenRouter usage TUI overlay with caps, burn rate, models, live tracking, and session_id tagging.",
+  "license": "MIT",
   "files": [
     "extensions",
     "README.md",