pi-smart-router 0.12.0 → 0.12.1

package/.pi/extensions/smart-router/command-formatters.ts

@@ -4,9 +4,14 @@ import {
 } from '../../../src/infrastructure/telemetry/telemetry-limits.js';
 import type {
   ModelProfile,
+  PriceCatalog,
   RoutingDecision,
   RoutingTelemetry,
 } from '../../../src/domain/types/index.js';
+import {
+  aggregateSessionStatsFromFleet,
+  type SessionStatsSnapshot,
+} from '../../../src/infrastructure/telemetry/session-stats.js';
 import { SMART_ROUTER_USAGE } from './commands.js';
 import {
   DEFAULT_TELEMETRY_CONTRIB_EXPORT_LIMIT,
@@ -19,6 +24,8 @@ import {
 import { formatPricingStalenessLine } from './pricing-lifecycle.js';
 import type { FleetMode, SmartRouterCommand, SmartRouterRuntime } from './types.js';
 
+export type { SessionStatsSnapshot };
+
 /** Opaque / virtual auto ids that hide the concrete delegated fleet model (SP-178). */
 function isBareOrSmartRouterAuto(modelId: string): boolean {
   return modelId === 'auto' || modelId === 'smart-router/auto';
@@ -149,6 +156,10 @@ export function parseSmartRouterArgs(args: string): SmartRouterCommand {
     return { command: 'history', limit: parseHistoryLimit(tokens[1]) };
   }
 
+  if (tokens[0] === 'stats') {
+    return { command: 'stats', limit: parseHistoryLimit(tokens[1]) };
+  }
+
   if (tokens[0] === 'mode' && (tokens[1] === 'scoped' || tokens[1] === 'all')) {
     return { command: 'mode', mode: tokens[1] };
   }
@@ -245,4 +256,86 @@ export function formatHistoryMessage(
     .join('\n');
 }
 
+function formatUsd(value: number): string {
+  if (!Number.isFinite(value)) {
+    return 'n/a';
+  }
+  if (Math.abs(value) >= 1) {
+    return `$${value.toFixed(4)}`;
+  }
+  return `$${value.toFixed(6)}`;
+}
+
+function formatShare(value: number | null): string {
+  if (value === null) {
+    return 'n/a';
+  }
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+function formatMean(value: number | null, suffix: string): string {
+  if (value === null) {
+    return 'n/a';
+  }
+  if (suffix === 'ms') {
+    return `${value.toFixed(1)}${suffix}`;
+  }
+  return `${formatUsd(value)}${suffix}`;
+}
+
+/**
+ * Operator-facing text for `/smart-router stats` (privacy-safe aggregates only).
+ */
+export function formatStatsMessage(
+  entries: readonly RoutingTelemetry[],
+  options?: {
+    fleet?: readonly ModelProfile[];
+    priceCatalog?: PriceCatalog | null;
+  },
+): string {
+  const snapshot = aggregateSessionStatsFromFleet(
+    entries,
+    options?.fleet,
+    options?.priceCatalog,
+  );
+
+  if (snapshot.entry_count === 0) {
+    return 'No routing stats yet (empty telemetry window).';
+  }
+
+  const lines = [
+    `Entries: ${snapshot.entry_count}`,
+    `Cost: total ${formatUsd(snapshot.total_cost_usd)} | mean ${formatMean(snapshot.mean_cost_usd, '')}`,
+    `Latency: total ${snapshot.total_latency_ms.toFixed(0)}ms | mean ${formatMean(snapshot.mean_latency_ms, 'ms')}`,
+    `Planning delegate share: ${formatShare(snapshot.planning_delegate_share)} (direct ${formatShare(snapshot.direct_share)})`,
+    `Local vs cloud (when known): local ${formatShare(snapshot.local_share)} | cloud ${formatShare(snapshot.cloud_share)}`,
+    'Role cost breakdown:',
+    `  primary (pin path): ${snapshot.role_cost.primary.count} | ${formatUsd(snapshot.role_cost.primary.total_cost_usd)}`,
+    `  planning_delegate: ${snapshot.role_cost.planning_delegate.count} | ${formatUsd(snapshot.role_cost.planning_delegate.total_cost_usd)}`,
+    `  other: ${snapshot.role_cost.other.count} | ${formatUsd(snapshot.role_cost.other.total_cost_usd)}`,
+  ];
+
+  if (snapshot.frontier_savings_usd !== undefined) {
+    lines.push(
+      `Vs always-frontier savings (est.): ${formatUsd(snapshot.frontier_savings_usd)}`,
+      '  formula: sum max(0, tokens/1e6 * frontier_cost_per_1m - estimated_cost_usd); omitted when prices missing',
+    );
+  } else {
+    lines.push('Vs always-frontier savings: (omitted — frontier prices unavailable)');
+  }
+
+  return lines.join('\n');
+}
+
+/** JSON snapshot helper for automation (same aggregate as formatStatsMessage). */
+export function buildStatsSnapshot(
+  entries: readonly RoutingTelemetry[],
+  options?: {
+    fleet?: readonly ModelProfile[];
+    priceCatalog?: PriceCatalog | null;
+  },
+): SessionStatsSnapshot {
+  return aggregateSessionStatsFromFleet(entries, options?.fleet, options?.priceCatalog);
+}
+
 export type { FleetMode };

package/.pi/extensions/smart-router/commands.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 
 import {
   formatHistoryMessage,
+  formatStatsMessage,
   formatStatusMessage,
   parseSmartRouterArgs,
 } from './command-formatters.js';
@@ -13,13 +14,14 @@ import { FLEET_MODE_ENTRY_TYPE } from './session-lifecycle.js';
 import type { SmartRouterRuntime } from './types.js';
 
 export const SMART_ROUTER_USAGE =
-  '/smart-router [status] | history [limit] | mode scoped|all | pricing refresh | export dataset [--limit N] | export telemetry-contrib [--limit N] | feedback good|bad | unpin';
+  '/smart-router [status] | history [limit] | stats [limit] | mode scoped|all | pricing refresh | export dataset [--limit N] | export telemetry-contrib [--limit N] | feedback good|bad | unpin';
 
 type CompletionItem = { value: string; label: string };
 
 const TOP_LEVEL: CompletionItem[] = [
   { value: 'status', label: 'Show last routing decision' },
   { value: 'history', label: 'Show recent routing history' },
+  { value: 'stats', label: 'Show session stats + role cost breakdown' },
   { value: 'mode', label: 'Switch fleet mode (scoped or all)' },
   { value: 'pricing', label: 'Manage pricing catalog' },
   { value: 'export', label: 'Export opt-in routing dataset' },
@@ -52,6 +54,8 @@ export const SMART_ROUTER_FULL_INVOCATIONS = [
   'status',
   'history',
   'history 10',
+  'stats',
+  'stats 50',
   'mode scoped',
   'mode all',
   'pricing refresh',
@@ -100,6 +104,10 @@ export function getSmartRouterArgumentCompletions(prefix: string): CompletionIte
     return [{ value: 'history', label: 'Show recent routing history' }];
   }
 
+  if (tokens[0] === 'stats') {
+    return [{ value: 'stats', label: 'Show session stats + role cost breakdown' }];
+  }
+
   const firstToken = tokens[0] ?? '';
   const filtered = filterByPrefix(TOP_LEVEL, firstToken);
   return filtered.length > 0 ? filtered : null;
@@ -143,7 +151,7 @@ export function registerSmartRouterCommand(
 ): void {
   pi.registerCommand('smart-router', {
     description:
-      'Show routing status/history, switch fleet mode (scoped|all), refresh pricing, or export dataset',
+      'Show routing status/history/stats, switch fleet mode (scoped|all), refresh pricing, or export dataset',
     getArgumentCompletions: getSmartRouterArgumentCompletions,
     handler: async (args, ctx) => {
       try {
@@ -167,6 +175,20 @@ export function registerSmartRouterCommand(
           return;
         }
 
+        if (parsed.command === 'stats') {
+          throwIfCommandAborted(signal);
+          const rows = await runtime.store.listTelemetry({ limit: parsed.limit });
+          throwIfCommandAborted(signal);
+          ctx.ui.notify(
+            formatStatsMessage(rows, {
+              fleet: runtime.streamDeps.fleet,
+              priceCatalog: runtime.priceCatalog,
+            }),
+            'info',
+          );
+          return;
+        }
+
         if (parsed.command === 'pricing') {
           throwIfCommandAborted(signal);
           const { modelCount, lastUpdated } = await refreshPricingCatalog(

package/.pi/extensions/smart-router/index.ts

@@ -36,6 +36,7 @@ import {
 } from './fleet-bootstrap.js';
 import {
   formatHistoryMessage,
+  formatStatsMessage,
   formatStatusMessage,
   parseSmartRouterArgs,
   resolveHistoryModelId,
@@ -82,6 +83,7 @@ export {
   formatLmuStatus,
   formatPricingStalenessLine,
   formatHistoryMessage,
+  formatStatsMessage,
   formatStatusMessage,
   getDatasetExportPath,
   getRouterStateDbPath,

package/.pi/extensions/smart-router/types.ts

@@ -34,6 +34,7 @@ export type FleetMode = 'scoped' | 'all';
 export type SmartRouterCommand =
   | { command: 'status' }
   | { command: 'history'; limit: number }
+  | { command: 'stats'; limit: number }
   | { command: 'mode'; mode: FleetMode }
   | { command: 'pricing'; subcommand: 'refresh' }
   | { command: 'export'; subcommand: 'dataset'; limit: number }

package/README.md

@@ -111,7 +111,7 @@ After installing via `pi install npm:pi-smart-router` (or from clone — see bel
 
 1. Authenticate providers (`/login`) and enable models in your scoped list if you use one (`/scoped-models`)
 2. `/model smart-router/auto` — every turn runs through the routing pipeline
-3. `/smart-router status` or `/smart-router history` — inspect routing decisions
+3. `/smart-router status`, `/smart-router history`, or `/smart-router stats` — inspect routing decisions and window aggregates
 
 Set `SMART_ROUTER_LOG_ROUTING=1` before starting pi to print each routing decision to stderr (see [Environment variables](#environment-variables)).
 
@@ -180,7 +180,7 @@ pi exposes two different **auto** models. They are easy to confuse but play diff
 **When to use `smart-router/auto`:**
 
 - You want cost/capability-aware model selection across your full authenticated fleet
-- You rely on session pinning, failover, or `/smart-router status` / `history` telemetry
+- You rely on session pinning, failover, or `/smart-router status` / `history` / `stats` telemetry
 - Tool-heavy sessions with Gemini economical models work via in-repo replay repair; add `cursor/auto` for unrepairable Google replay edge cases (see [pi-smart-router#85](https://github.com/beettlle/pi-smart-router/issues/85))
 
 Cursor models (`cursor/*`, `composer-*`, and the opaque fleet id `default`) map to **frontier-cloud** tier in `pi-model-mapper.ts` so HyDRA can score them against Gemini and Claude instead of treating them as unknown economical models ([pi-smart-router#40](https://github.com/beettlle/pi-smart-router/issues/40), [pi-smart-router#70](https://github.com/beettlle/pi-smart-router/issues/70)). Related: [pi-smart-router#23](https://github.com/beettlle/pi-smart-router/issues/23) (turn envelope / pin order), [pi-smart-router#37](https://github.com/beettlle/pi-smart-router/issues/37) (Gemini `thought_signature` errors).
@@ -198,6 +198,7 @@ Cursor models bill against your **Cursor Pro subscription quota**, not per-token
 | `/smart-router` | Same as `status` (default when no subcommand is given) |
 | `/smart-router status` | Show fleet mode, fleet size, pricing freshness/staleness, and the last routing decision (stage, tier, selected model, latency) |
 | `/smart-router history` | Show recent routing telemetry from SQLite (default limit; optional numeric limit, e.g. `/smart-router history 20`). Displays the concrete delegated model id (never bare virtual `auto`) |
+| `/smart-router stats` | Privacy-safe session/window aggregates from routing telemetry: count, mean cost/latency, planning_delegate vs direct share, local vs cloud when distinguishable, and role cost breakdown (primary pin path / planning_delegate / other). Optional vs-always-frontier savings when frontier fleet prices exist (omitted otherwise). Optional numeric limit, e.g. `/smart-router stats 50` |
 | `/smart-router mode scoped` | Route only among pi's **enabled model patterns** (default) |
 | `/smart-router mode all` | Route among **all authenticated models** in the registry |
 | `/smart-router pricing refresh` | Manually fetch LiteLLM pricing from `LITELLM_PRICING_URL`, persist to SQLite, and rebuild the fleet with updated rates |

package/config/benchmark-profiles.json

@@ -7,8 +7,8 @@
       "livecodebench": "https://livecodebench.github.io/leaderboard.html",
       "bfcl": "https://gorilla.cs.berkeley.edu/leaderboard.html"
     },
-    "scrape_date": "2026-07-12",
-    "catalog_freeze_date": "2026-07-12"
+    "scrape_date": "2026-07-14",
+    "catalog_freeze_date": "2026-07-14"
   },
   "aliases": {
     "claude-3-5-sonnet": "claude-sonnet-4-6",

package/dist/infrastructure/telemetry/session-stats.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Privacy-safe session / window stats over RoutingTelemetry (SP-207 / #118).
+ *
+ * Aggregates only numeric and categorical telemetry fields — never prompt,
+ * message, or tool-argument bodies.
+ */
+import type { ModelProfile, PriceCatalog, RoutingTelemetry, Tier } from '../../domain/types/index.js';
+export type RoleCostBucket = 'primary' | 'planning_delegate' | 'other';
+export type DeploymentClass = 'local' | 'cloud' | 'unknown';
+export interface RoleBucketStats {
+    readonly count: number;
+    readonly total_cost_usd: number;
+}
+export interface RoleCostBreakdown {
+    readonly primary: RoleBucketStats;
+    readonly planning_delegate: RoleBucketStats;
+    readonly other: RoleBucketStats;
+}
+/**
+ * Compact JSON snapshot for automation / MCP (llm-use `stats_snapshot` analog).
+ * Optional `frontier_savings_usd` is omitted when prices are unavailable (fail closed).
+ */
+export interface SessionStatsSnapshot {
+    readonly entry_count: number;
+    readonly total_cost_usd: number;
+    readonly mean_cost_usd: number | null;
+    readonly total_latency_ms: number;
+    readonly mean_latency_ms: number | null;
+    /** Share of entries with planning_delegate_path === 'delegate' (0–1), null if empty. */
+    readonly planning_delegate_share: number | null;
+    /** Share of entries with non-delegate path (direct / none / null). */
+    readonly direct_share: number | null;
+    /** Share classified as local (zero-tier) when distinguishable; null if none classified. */
+    readonly local_share: number | null;
+    /** Share classified as cloud when distinguishable; null if none classified. */
+    readonly cloud_share: number | null;
+    readonly role_cost: RoleCostBreakdown;
+    /**
+     * Estimated USD saved vs always-frontier baseline.
+     * Formula: sum over entries with token counts of
+     *   max(0, tokens/1e6 * frontier_cost_per_1m - estimated_cost_usd).
+     * Omitted when frontier price inputs are missing (fail closed).
+     */
+    readonly frontier_savings_usd?: number;
+}
+export interface AggregateSessionStatsOptions {
+    /**
+     * USD per 1M tokens for the always-frontier baseline.
+     * When absent / non-finite / ≤0, `frontier_savings_usd` is omitted.
+     */
+    readonly frontier_cost_per_1m?: number;
+    /** Optional model_id → tier map (e.g. from fleet) for local vs cloud. */
+    readonly tier_by_model_id?: ReadonlyMap<string, Tier>;
+}
+/** Mutually exclusive role for cost bucketing. */
+export declare function classifyRoleCostBucket(entry: RoutingTelemetry): RoleCostBucket;
+export declare function classifyDeployment(entry: RoutingTelemetry, tierByModelId?: ReadonlyMap<string, Tier>): DeploymentClass;
+/**
+ * Resolve always-frontier cost/1M from fleet + optional catalog.
+ * Returns undefined when no positive frontier price is available (fail closed).
+ */
+export declare function resolveFrontierCostPer1M(fleet?: readonly ModelProfile[], catalog?: PriceCatalog | null): number | undefined;
+/**
+ * Pure aggregate over routing telemetry for operator stats.
+ * Does not read or emit prompt/message/tool bodies.
+ */
+export declare function aggregateSessionStats(entries: readonly RoutingTelemetry[], options?: AggregateSessionStatsOptions): SessionStatsSnapshot;
+/**
+ * Optional vs-always-frontier savings. Returns undefined when price input is
+ * missing or non-positive (fail closed) or when no entry has token counts.
+ */
+export declare function estimateFrontierSavingsUsd(entries: readonly RoutingTelemetry[], frontierCostPer1M: number | undefined): number | undefined;
+/** Convenience: aggregate with fleet/catalog-derived tier map + frontier price. */
+export declare function aggregateSessionStatsFromFleet(entries: readonly RoutingTelemetry[], fleet?: readonly ModelProfile[], catalog?: PriceCatalog | null): SessionStatsSnapshot;
+/** Keys that must never appear on a stats snapshot (privacy). */
+export declare const SESSION_STATS_FORBIDDEN_KEYS: readonly ["prompt", "prompt_text", "messages", "content", "tool_calls", "tool_args", "pepper"];
+export declare function assertSessionStatsPrivacySafe(snapshot: SessionStatsSnapshot): void;
+//# sourceMappingURL=session-stats.d.ts.map

package/dist/infrastructure/telemetry/session-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-stats.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/telemetry/session-stats.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,YAAY,EAEZ,YAAY,EACZ,gBAAgB,EAChB,IAAI,EACL,MAAM,6BAA6B,CAAC;AAErC,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,mBAAmB,GAAG,OAAO,CAAC;AAEvE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,eAAe,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,wFAAwF;IACxF,QAAQ,CAAC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CACvD;AAED,kDAAkD;AAClD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,cAAc,CAQ9E;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,EACvB,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,GACxC,eAAe,CAUjB;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,EAC/B,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,GAC5B,MAAM,GAAG,SAAS,CA6BpB;AAcD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,OAAO,GAAE,4BAAiC,GACzC,oBAAoB,CA+DtB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,iBAAiB,EAAE,MAAM,GAAG,SAAS,GACpC,MAAM,GAAG,SAAS,CA4BpB;AAED,mFAAmF;AACnF,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,EAC/B,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,GAC5B,oBAAoB,CAOtB;AAED,iEAAiE;AACjE,eAAO,MAAM,4BAA4B,gGAQ/B,CAAC;AAEX,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAOlF"}

package/dist/infrastructure/telemetry/session-stats.js

@@ -0,0 +1,187 @@
+/**
+ * Privacy-safe session / window stats over RoutingTelemetry (SP-207 / #118).
+ *
+ * Aggregates only numeric and categorical telemetry fields — never prompt,
+ * message, or tool-argument bodies.
+ */
+/** Mutually exclusive role for cost bucketing. */
+export function classifyRoleCostBucket(entry) {
+    if (entry.planning_delegate_path === 'delegate') {
+        return 'planning_delegate';
+    }
+    if (entry.pin_reason != null) {
+        return 'primary';
+    }
+    return 'other';
+}
+export function classifyDeployment(entry, tierByModelId) {
+    const fromFleet = tierByModelId?.get(entry.selected_model_id);
+    const tier = fromFleet ?? entry.tier_hint;
+    if (tier === 'zero-tier') {
+        return 'local';
+    }
+    if (tier === 'economical-cloud' || tier === 'frontier-cloud') {
+        return 'cloud';
+    }
+    return 'unknown';
+}
+function isPlanningDelegate(path) {
+    return path === 'delegate';
+}
+/**
+ * Resolve always-frontier cost/1M from fleet + optional catalog.
+ * Returns undefined when no positive frontier price is available (fail closed).
+ */
+export function resolveFrontierCostPer1M(fleet, catalog) {
+    const candidates = [];
+    if (fleet) {
+        for (const model of fleet) {
+            if (model.tier !== 'frontier-cloud') {
+                continue;
+            }
+            const cost = model.pricing.fallback_cost_per_1m;
+            if (Number.isFinite(cost) && cost > 0) {
+                candidates.push(cost);
+            }
+            if (catalog) {
+                const key = model.pricing.registry_key ?? model.id;
+                const fromCatalog = catalog.user_overrides[key] ?? catalog.registry_snapshot[key];
+                if (fromCatalog !== undefined && Number.isFinite(fromCatalog) && fromCatalog > 0) {
+                    candidates.push(fromCatalog);
+                }
+            }
+        }
+    }
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    // Upper-bound “always frontier” baseline: most expensive known frontier rate.
+    return Math.max(...candidates);
+}
+function buildTierMap(fleet) {
+    if (!fleet || fleet.length === 0) {
+        return undefined;
+    }
+    const map = new Map();
+    for (const model of fleet) {
+        map.set(model.id, model.tier);
+        map.set(`${model.provider}/${model.id}`, model.tier);
+    }
+    return map;
+}
+/**
+ * Pure aggregate over routing telemetry for operator stats.
+ * Does not read or emit prompt/message/tool bodies.
+ */
+export function aggregateSessionStats(entries, options = {}) {
+    const tierByModelId = options.tier_by_model_id;
+    const roleAccum = {
+        primary: { count: 0, total_cost_usd: 0 },
+        planning_delegate: { count: 0, total_cost_usd: 0 },
+        other: { count: 0, total_cost_usd: 0 },
+    };
+    let totalCost = 0;
+    let totalLatency = 0;
+    let delegateCount = 0;
+    let localCount = 0;
+    let cloudCount = 0;
+    let classifiedDeployment = 0;
+    for (const entry of entries) {
+        const cost = Number.isFinite(entry.estimated_cost_usd) ? entry.estimated_cost_usd : 0;
+        const latency = Number.isFinite(entry.routing_latency_ms) ? entry.routing_latency_ms : 0;
+        totalCost += cost;
+        totalLatency += latency;
+        if (isPlanningDelegate(entry.planning_delegate_path)) {
+            delegateCount += 1;
+        }
+        const role = classifyRoleCostBucket(entry);
+        roleAccum[role].count += 1;
+        roleAccum[role].total_cost_usd += cost;
+        const deployment = classifyDeployment(entry, tierByModelId);
+        if (deployment === 'local') {
+            localCount += 1;
+            classifiedDeployment += 1;
+        }
+        else if (deployment === 'cloud') {
+            cloudCount += 1;
+            classifiedDeployment += 1;
+        }
+    }
+    const n = entries.length;
+    const snapshot = {
+        entry_count: n,
+        total_cost_usd: totalCost,
+        mean_cost_usd: n > 0 ? totalCost / n : null,
+        total_latency_ms: totalLatency,
+        mean_latency_ms: n > 0 ? totalLatency / n : null,
+        planning_delegate_share: n > 0 ? delegateCount / n : null,
+        direct_share: n > 0 ? (n - delegateCount) / n : null,
+        local_share: classifiedDeployment > 0 ? localCount / classifiedDeployment : null,
+        cloud_share: classifiedDeployment > 0 ? cloudCount / classifiedDeployment : null,
+        role_cost: {
+            primary: { ...roleAccum.primary },
+            planning_delegate: { ...roleAccum.planning_delegate },
+            other: { ...roleAccum.other },
+        },
+    };
+    const frontierSavings = estimateFrontierSavingsUsd(entries, options.frontier_cost_per_1m);
+    if (frontierSavings !== undefined) {
+        return { ...snapshot, frontier_savings_usd: frontierSavings };
+    }
+    return snapshot;
+}
+/**
+ * Optional vs-always-frontier savings. Returns undefined when price input is
+ * missing or non-positive (fail closed) or when no entry has token counts.
+ */
+export function estimateFrontierSavingsUsd(entries, frontierCostPer1M) {
+    if (frontierCostPer1M === undefined ||
+        !Number.isFinite(frontierCostPer1M) ||
+        frontierCostPer1M <= 0) {
+        return undefined;
+    }
+    let savings = 0;
+    let counted = 0;
+    for (const entry of entries) {
+        const tokens = entry.estimated_input_tokens;
+        if (tokens === null || !Number.isFinite(tokens) || tokens < 0) {
+            continue;
+        }
+        const actual = Number.isFinite(entry.estimated_cost_usd) ? entry.estimated_cost_usd : 0;
+        const frontierCost = (tokens / 1_000_000) * frontierCostPer1M;
+        savings += Math.max(0, frontierCost - actual);
+        counted += 1;
+    }
+    if (counted === 0) {
+        return undefined;
+    }
+    return savings;
+}
+/** Convenience: aggregate with fleet/catalog-derived tier map + frontier price. */
+export function aggregateSessionStatsFromFleet(entries, fleet, catalog) {
+    const tierMap = buildTierMap(fleet);
+    const frontierCost = resolveFrontierCostPer1M(fleet, catalog);
+    return aggregateSessionStats(entries, {
+        ...(tierMap ? { tier_by_model_id: tierMap } : {}),
+        ...(frontierCost !== undefined ? { frontier_cost_per_1m: frontierCost } : {}),
+    });
+}
+/** Keys that must never appear on a stats snapshot (privacy). */
+export const SESSION_STATS_FORBIDDEN_KEYS = [
+    'prompt',
+    'prompt_text',
+    'messages',
+    'content',
+    'tool_calls',
+    'tool_args',
+    'pepper',
+];
+export function assertSessionStatsPrivacySafe(snapshot) {
+    const json = JSON.stringify(snapshot);
+    for (const key of SESSION_STATS_FORBIDDEN_KEYS) {
+        if (json.includes(`"${key}"`)) {
+            throw new Error(`Stats snapshot contains forbidden privacy key: ${key}`);
+        }
+    }
+}
+//# sourceMappingURL=session-stats.js.map

package/dist/infrastructure/telemetry/session-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-stats.js","sourceRoot":"","sources":["../../../src/infrastructure/telemetry/session-stats.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-smart-router",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Auto-model router middleware for the pi.dev coding agent",
   "type": "module",
   "license": "MIT",

package/src/infrastructure/telemetry/session-stats.ts

@@ -0,0 +1,290 @@
+/**
+ * Privacy-safe session / window stats over RoutingTelemetry (SP-207 / #118).
+ *
+ * Aggregates only numeric and categorical telemetry fields — never prompt,
+ * message, or tool-argument bodies.
+ */
+
+import type {
+  ModelProfile,
+  PlanningDelegatePath,
+  PriceCatalog,
+  RoutingTelemetry,
+  Tier,
+} from '../../domain/types/index.js';
+
+export type RoleCostBucket = 'primary' | 'planning_delegate' | 'other';
+
+export type DeploymentClass = 'local' | 'cloud' | 'unknown';
+
+export interface RoleBucketStats {
+  readonly count: number;
+  readonly total_cost_usd: number;
+}
+
+export interface RoleCostBreakdown {
+  readonly primary: RoleBucketStats;
+  readonly planning_delegate: RoleBucketStats;
+  readonly other: RoleBucketStats;
+}
+
+/**
+ * Compact JSON snapshot for automation / MCP (llm-use `stats_snapshot` analog).
+ * Optional `frontier_savings_usd` is omitted when prices are unavailable (fail closed).
+ */
+export interface SessionStatsSnapshot {
+  readonly entry_count: number;
+  readonly total_cost_usd: number;
+  readonly mean_cost_usd: number | null;
+  readonly total_latency_ms: number;
+  readonly mean_latency_ms: number | null;
+  /** Share of entries with planning_delegate_path === 'delegate' (0–1), null if empty. */
+  readonly planning_delegate_share: number | null;
+  /** Share of entries with non-delegate path (direct / none / null). */
+  readonly direct_share: number | null;
+  /** Share classified as local (zero-tier) when distinguishable; null if none classified. */
+  readonly local_share: number | null;
+  /** Share classified as cloud when distinguishable; null if none classified. */
+  readonly cloud_share: number | null;
+  readonly role_cost: RoleCostBreakdown;
+  /**
+   * Estimated USD saved vs always-frontier baseline.
+   * Formula: sum over entries with token counts of
+   *   max(0, tokens/1e6 * frontier_cost_per_1m - estimated_cost_usd).
+   * Omitted when frontier price inputs are missing (fail closed).
+   */
+  readonly frontier_savings_usd?: number;
+}
+
+export interface AggregateSessionStatsOptions {
+  /**
+   * USD per 1M tokens for the always-frontier baseline.
+   * When absent / non-finite / ≤0, `frontier_savings_usd` is omitted.
+   */
+  readonly frontier_cost_per_1m?: number;
+  /** Optional model_id → tier map (e.g. from fleet) for local vs cloud. */
+  readonly tier_by_model_id?: ReadonlyMap<string, Tier>;
+}
+
+/** Mutually exclusive role for cost bucketing. */
+export function classifyRoleCostBucket(entry: RoutingTelemetry): RoleCostBucket {
+  if (entry.planning_delegate_path === 'delegate') {
+    return 'planning_delegate';
+  }
+  if (entry.pin_reason != null) {
+    return 'primary';
+  }
+  return 'other';
+}
+
+export function classifyDeployment(
+  entry: RoutingTelemetry,
+  tierByModelId?: ReadonlyMap<string, Tier>,
+): DeploymentClass {
+  const fromFleet = tierByModelId?.get(entry.selected_model_id);
+  const tier = fromFleet ?? entry.tier_hint;
+  if (tier === 'zero-tier') {
+    return 'local';
+  }
+  if (tier === 'economical-cloud' || tier === 'frontier-cloud') {
+    return 'cloud';
+  }
+  return 'unknown';
+}
+
+function isPlanningDelegate(path: PlanningDelegatePath | null): boolean {
+  return path === 'delegate';
+}
+
+/**
+ * Resolve always-frontier cost/1M from fleet + optional catalog.
+ * Returns undefined when no positive frontier price is available (fail closed).
+ */
+export function resolveFrontierCostPer1M(
+  fleet?: readonly ModelProfile[],
+  catalog?: PriceCatalog | null,
+): number | undefined {
+  const candidates: number[] = [];
+
+  if (fleet) {
+    for (const model of fleet) {
+      if (model.tier !== 'frontier-cloud') {
+        continue;
+      }
+      const cost = model.pricing.fallback_cost_per_1m;
+      if (Number.isFinite(cost) && cost > 0) {
+        candidates.push(cost);
+      }
+      if (catalog) {
+        const key = model.pricing.registry_key ?? model.id;
+        const fromCatalog =
+          catalog.user_overrides[key] ?? catalog.registry_snapshot[key];
+        if (fromCatalog !== undefined && Number.isFinite(fromCatalog) && fromCatalog > 0) {
+          candidates.push(fromCatalog);
+        }
+      }
+    }
+  }
+
+  if (candidates.length === 0) {
+    return undefined;
+  }
+
+  // Upper-bound “always frontier” baseline: most expensive known frontier rate.
+  return Math.max(...candidates);
+}
+
+function buildTierMap(fleet?: readonly ModelProfile[]): ReadonlyMap<string, Tier> | undefined {
+  if (!fleet || fleet.length === 0) {
+    return undefined;
+  }
+  const map = new Map<string, Tier>();
+  for (const model of fleet) {
+    map.set(model.id, model.tier);
+    map.set(`${model.provider}/${model.id}`, model.tier);
+  }
+  return map;
+}
+
+/**
+ * Pure aggregate over routing telemetry for operator stats.
+ * Does not read or emit prompt/message/tool bodies.
+ */
+export function aggregateSessionStats(
+  entries: readonly RoutingTelemetry[],
+  options: AggregateSessionStatsOptions = {},
+): SessionStatsSnapshot {
+  const tierByModelId = options.tier_by_model_id;
+  const roleAccum = {
+    primary: { count: 0, total_cost_usd: 0 },
+    planning_delegate: { count: 0, total_cost_usd: 0 },
+    other: { count: 0, total_cost_usd: 0 },
+  };
+
+  let totalCost = 0;
+  let totalLatency = 0;
+  let delegateCount = 0;
+  let localCount = 0;
+  let cloudCount = 0;
+  let classifiedDeployment = 0;
+
+  for (const entry of entries) {
+    const cost = Number.isFinite(entry.estimated_cost_usd) ? entry.estimated_cost_usd : 0;
+    const latency = Number.isFinite(entry.routing_latency_ms) ? entry.routing_latency_ms : 0;
+    totalCost += cost;
+    totalLatency += latency;
+
+    if (isPlanningDelegate(entry.planning_delegate_path)) {
+      delegateCount += 1;
+    }
+
+    const role = classifyRoleCostBucket(entry);
+    roleAccum[role].count += 1;
+    roleAccum[role].total_cost_usd += cost;
+
+    const deployment = classifyDeployment(entry, tierByModelId);
+    if (deployment === 'local') {
+      localCount += 1;
+      classifiedDeployment += 1;
+    } else if (deployment === 'cloud') {
+      cloudCount += 1;
+      classifiedDeployment += 1;
+    }
+  }
+
+  const n = entries.length;
+  const snapshot: SessionStatsSnapshot = {
+    entry_count: n,
+    total_cost_usd: totalCost,
+    mean_cost_usd: n > 0 ? totalCost / n : null,
+    total_latency_ms: totalLatency,
+    mean_latency_ms: n > 0 ? totalLatency / n : null,
+    planning_delegate_share: n > 0 ? delegateCount / n : null,
+    direct_share: n > 0 ? (n - delegateCount) / n : null,
+    local_share: classifiedDeployment > 0 ? localCount / classifiedDeployment : null,
+    cloud_share: classifiedDeployment > 0 ? cloudCount / classifiedDeployment : null,
+    role_cost: {
+      primary: { ...roleAccum.primary },
+      planning_delegate: { ...roleAccum.planning_delegate },
+      other: { ...roleAccum.other },
+    },
+  };
+
+  const frontierSavings = estimateFrontierSavingsUsd(entries, options.frontier_cost_per_1m);
+  if (frontierSavings !== undefined) {
+    return { ...snapshot, frontier_savings_usd: frontierSavings };
+  }
+
+  return snapshot;
+}
+
+/**
+ * Optional vs-always-frontier savings. Returns undefined when price input is
+ * missing or non-positive (fail closed) or when no entry has token counts.
+ */
+export function estimateFrontierSavingsUsd(
+  entries: readonly RoutingTelemetry[],
+  frontierCostPer1M: number | undefined,
+): number | undefined {
+  if (
+    frontierCostPer1M === undefined ||
+    !Number.isFinite(frontierCostPer1M) ||
+    frontierCostPer1M <= 0
+  ) {
+    return undefined;
+  }
+
+  let savings = 0;
+  let counted = 0;
+
+  for (const entry of entries) {
+    const tokens = entry.estimated_input_tokens;
+    if (tokens === null || !Number.isFinite(tokens) || tokens < 0) {
+      continue;
+    }
+    const actual = Number.isFinite(entry.estimated_cost_usd) ? entry.estimated_cost_usd : 0;
+    const frontierCost = (tokens / 1_000_000) * frontierCostPer1M;
+    savings += Math.max(0, frontierCost - actual);
+    counted += 1;
+  }
+
+  if (counted === 0) {
+    return undefined;
+  }
+
+  return savings;
+}
+
+/** Convenience: aggregate with fleet/catalog-derived tier map + frontier price. */
+export function aggregateSessionStatsFromFleet(
+  entries: readonly RoutingTelemetry[],
+  fleet?: readonly ModelProfile[],
+  catalog?: PriceCatalog | null,
+): SessionStatsSnapshot {
+  const tierMap = buildTierMap(fleet);
+  const frontierCost = resolveFrontierCostPer1M(fleet, catalog);
+  return aggregateSessionStats(entries, {
+    ...(tierMap ? { tier_by_model_id: tierMap } : {}),
+    ...(frontierCost !== undefined ? { frontier_cost_per_1m: frontierCost } : {}),
+  });
+}
+
+/** Keys that must never appear on a stats snapshot (privacy). */
+export const SESSION_STATS_FORBIDDEN_KEYS = [
+  'prompt',
+  'prompt_text',
+  'messages',
+  'content',
+  'tool_calls',
+  'tool_args',
+  'pepper',
+] as const;
+
+export function assertSessionStatsPrivacySafe(snapshot: SessionStatsSnapshot): void {
+  const json = JSON.stringify(snapshot);
+  for (const key of SESSION_STATS_FORBIDDEN_KEYS) {
+    if (json.includes(`"${key}"`)) {
+      throw new Error(`Stats snapshot contains forbidden privacy key: ${key}`);
+    }
+  }
+}