@robhowley/pi-openrouter 0.3.0 → 0.4.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, and model breakdowns, plus automatic `session_id` tagging for dashboard grouping.
 
 ## Installation
 
@@ -35,11 +35,26 @@ The extension refreshes data in the background every 30 seconds (with exponentia
 
 Press `q`, `Esc`, or `Ctrl+C` to close the overlay.
 
-## 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.
+
+Can 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 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.
 
 ## License
 

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

@@ -68,7 +68,7 @@ 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;
   }
@@ -94,9 +94,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/index.ts

@@ -8,11 +8,76 @@ import {
 } from './cache.js';
 import { AuthError } from './client.js';
 import { UsageOverlayComponent } from './overlay.js';
+import { formatSessionId, isOpenRouterRequest, type OpenRouterSessionState } from './session.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;
+      }
+    });
+  }
 
   pi.on('session_shutdown', () => {
     stopBackgroundRefresh();
@@ -22,11 +87,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/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/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@robhowley/pi-openrouter",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
-  "description": "Terminal overlay for OpenRouter usage: caps, spend, burn rate, and model breakdowns.",
+  "description": "OpenRouter usage TUI overlay with caps, spend, burn rate, models, and session_id tracking.",
   "files": [
     "extensions",
     "README.md",
@@ -19,7 +19,7 @@
     "extensions": [
       "./extensions/openrouter"
     ],
-    "image": "https://raw.githubusercontent.com/roberthowley/pi-userland/main/packages/pi-openrouter/img/openrouter-usage-tui.png"
+    "image": "https://raw.githubusercontent.com/robhowley/pi-userland/main/packages/pi-openrouter/img/openrouter-usage-tui.png"
   },
   "repository": {
     "type": "git",