pi-smart-router 0.19.4 → 0.20.0

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

@@ -312,9 +312,16 @@ export function formatStatsMessage(
     return 'No routing stats yet (empty telemetry window).';
   }
 
+  const costBasisLabel =
+    snapshot.cost_basis === 'actual'
+      ? 'actual'
+      : snapshot.cost_basis === 'mixed'
+        ? `mixed (${snapshot.actual_usage_count}/${snapshot.entry_count} actual)`
+        : 'estimated';
+
   const lines = [
     `Entries: ${snapshot.entry_count}`,
-    `Cost: total ${formatUsd(snapshot.total_cost_usd)} | mean ${formatMean(snapshot.mean_cost_usd, '')}`,
+    `Cost (${costBasisLabel}): 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)}`,
@@ -324,10 +331,19 @@ export function formatStatsMessage(
     `  other: ${snapshot.role_cost.other.count} | ${formatUsd(snapshot.role_cost.other.total_cost_usd)}`,
   ];
 
+  if (snapshot.actual_usage_count > 0) {
+    lines.push(
+      `Actual usage: ${snapshot.actual_usage_count}/${snapshot.entry_count} entries with host-reported tokens` +
+        (snapshot.actual_total_tokens !== null
+          ? ` | ${snapshot.actual_total_tokens} actual tokens`
+          : ''),
+    );
+  }
+
   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',
+      `Vs always-frontier savings: ${formatUsd(snapshot.frontier_savings_usd)} (${snapshot.cost_basis === 'estimated' ? 'est.' : 'actuals preferred, est. when missing'})`,
+      '  formula: sum max(0, tokens/1e6 * frontier_cost_per_1m - cost); tokens/cost prefer actuals; omitted when prices missing',
     );
   } else {
     lines.push('Vs always-frontier savings: (omitted — frontier prices unavailable)');

package/.pi/extensions/smart-router/delegate-stream.ts

@@ -10,6 +10,12 @@ import {
 } from '@earendil-works/pi-ai/compat';
 
 import { parseAssistantMessageError } from '../../../src/infrastructure/delegation/provider-error.js';
+import { extractUsageActuals } from '../../../src/infrastructure/telemetry/routing-telemetry.js';
+import {
+  resolveAdaptiveReasoning,
+  type AdaptiveReasoningResult,
+  type AdaptiveReasoningSignal,
+} from '../../../src/domain/delegation/adaptive-reasoning.js';
 import {
   buildDelegationContext,
   forwardDelegatedEvent,
@@ -89,6 +95,7 @@ export async function collectDelegatedStream(
   deps: StreamDelegationDeps,
   options: SimpleStreamOptions | undefined,
   headroomContext?: DelegationHeadroomContext,
+  reasoning?: AdaptiveReasoningResult,
 ): Promise<DelegatedStreamResult> {
   throwIfAborted(options);
 
@@ -97,6 +104,7 @@ export async function collectDelegatedStream(
     targetModel,
     options,
     headroomContext,
+    reasoning,
   );
   const delegateStream = resolveDelegateStream(targetModel, deps);
   const inner = delegateStream(targetModel, context, delegationOptions);
@@ -156,6 +164,7 @@ export async function pipeDelegatedStream(
   options: SimpleStreamOptions | undefined,
   headroomContext: DelegationHeadroomContext | undefined,
   pipe: PipeDelegatedStreamOptions,
+  reasoning?: AdaptiveReasoningResult,
 ): Promise<PipedDelegatedStreamResult> {
   throwIfAborted(options);
 
@@ -164,6 +173,7 @@ export async function pipeDelegatedStream(
     targetModel,
     options,
     headroomContext,
+    reasoning,
   );
   const delegateStream = resolveDelegateStream(targetModel, deps);
   const inner = delegateStream(targetModel, context, delegationOptions);
@@ -257,11 +267,29 @@ function recordDelegateOutcome(
   deps: StreamDelegationDeps,
   sessionId: string | undefined,
   result: DelegatedStreamResult,
+  requestId?: string,
 ): void {
   if (!result.finalMessage) {
     return;
   }
 
+  // SP-241 / #164: capture post-turn usage actuals (success and
+  // failed-with-usage terminals). Fail open — extraction/hook errors and
+  // missing usage must never fail the route.
+  if (requestId !== undefined) {
+    try {
+      const actuals = extractUsageActuals(result.finalMessage.usage);
+      if (actuals) {
+        deps.onDelegationUsage?.(requestId, actuals);
+      }
+    } catch (error) {
+      console.warn(
+        '[smart-router] usage actuals capture failed (fail open)',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
   if (result.failed) {
     const parsed = parseAssistantMessageError(result.finalMessage);
     deps.router.dispatch.recordOutcome(targetModel.id, parsed);
@@ -282,6 +310,11 @@ function recordDelegateOutcome(
 /**
  * Delegate with outcome recording. When `pipe` is provided, live-forwards to outer
  * (holding the terminal event). Otherwise collects into a buffer (planning / probes).
+ *
+ * SP-245 (#166): when `reasoningSignal` is provided, the adaptive reasoning
+ * policy resolves the effective thinking level from turn signals and merges it
+ * into the delegated stream options (never lowering an explicit operator
+ * /thinking; fail open on non-reasoning models).
  */
 export async function delegateWithOutcome(
   targetModel: Model<Api>,
@@ -291,12 +324,54 @@ export async function delegateWithOutcome(
   sessionId: string | undefined,
   headroomContext?: DelegationHeadroomContext,
   pipe?: PipeDelegatedStreamOptions,
+  /** Routing request id for post-turn usage actuals capture (SP-241, #164). */
+  requestId?: string,
+  /** Turn/routing signals for adaptive reasoning (SP-245, #166). */
+  reasoningSignal?: AdaptiveReasoningSignal,
 ): Promise<PipedDelegatedStreamResult | DelegatedStreamResult> {
+  const reasoning = reasoningSignal
+    ? resolveAdaptiveReasoning(
+        targetModel,
+        reasoningSignal,
+        options?.reasoning,
+        // SP-246 (#166): operator enable/disable + floor/ceiling knobs.
+        deps.adaptiveReasoningConfig
+          ? {
+              enabled: deps.adaptiveReasoningConfig.enabled,
+              ...(deps.adaptiveReasoningConfig.min_level !== undefined
+                ? { floor: deps.adaptiveReasoningConfig.min_level }
+                : {}),
+              ...(deps.adaptiveReasoningConfig.max_level !== undefined
+                ? { ceiling: deps.adaptiveReasoningConfig.max_level }
+                : {}),
+            }
+          : undefined,
+      )
+    : undefined;
+
+  // SP-246 (#166): reasoning telemetry (requested / applied / reason code).
+  // Fail open — telemetry must never fail the route.
+  if (reasoningSignal && reasoning && requestId !== undefined) {
+    try {
+      deps.onDelegationReasoning?.(requestId, {
+        reasoning_level_requested: options?.reasoning ?? null,
+        reasoning_level_applied: reasoning.reasoning ?? null,
+        reasoning_reason_code: reasoning.reasonCode,
+      });
+    } catch (error) {
+      console.warn(
+        '[smart-router] reasoning telemetry callback failed (fail open)',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
   const delegationContext = buildDelegationContext(
     context,
     targetModel,
     deps,
     sessionId,
+    reasoning,
   );
 
   const result = pipe
@@ -307,6 +382,7 @@ export async function delegateWithOutcome(
         options,
         headroomContext,
         pipe,
+        reasoning,
       )
     : await collectDelegatedStream(
         targetModel,
@@ -314,9 +390,10 @@ export async function delegateWithOutcome(
         deps,
         options,
         headroomContext,
+        reasoning,
       );
 
-  recordDelegateOutcome(targetModel, deps, sessionId, result);
+  recordDelegateOutcome(targetModel, deps, sessionId, result, requestId);
 
   return result;
 }

package/.pi/extensions/smart-router/delegation-runtime.ts

@@ -13,6 +13,10 @@ import {
 } from '@earendil-works/pi-ai/compat';
 import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
 
+import {
+  applyConcisenessHint,
+  type AdaptiveReasoningResult,
+} from '../../../src/domain/delegation/adaptive-reasoning.js';
 import {
   isGoogleDelegationTarget,
   normalizeDelegationContext,
@@ -87,6 +91,7 @@ export async function resolveDelegationOptions(
   targetModel: Model<Api>,
   callerOptions?: SimpleStreamOptions,
   headroomContext?: DelegationHeadroomContext,
+  reasoning?: AdaptiveReasoningResult,
 ): Promise<SimpleStreamOptions> {
   const auth = await modelRegistry.getApiKeyAndHeaders(targetModel);
   if (!auth.ok) {
@@ -124,6 +129,14 @@ export async function resolveDelegationOptions(
     ...(auth.headers !== undefined ? { headers: auth.headers } : {}),
     ...(mergedEnv !== undefined ? { env: mergedEnv } : {}),
     ...(maxTokens !== undefined ? { maxTokens } : {}),
+    // SP-245 (#166): adaptive reasoning policy merge — applied after the
+    // caller pick so the policy-effective level wins, while every other
+    // DELEGATION_CALLER_OPTION_KEYS entry (incl. thinkingBudgets) passes
+    // through untouched. Explicit operator /thinking floors are already
+    // resolved inside the policy result.
+    ...(reasoning?.reasoning !== undefined
+      ? { reasoning: reasoning.reasoning }
+      : {}),
   };
 }
 
@@ -146,6 +159,7 @@ export function buildDelegationContext(
   targetModel: Model<Api>,
   deps: StreamDelegationDeps,
   sessionId: string | undefined,
+  reasoning?: AdaptiveReasoningResult,
 ): Context {
   const sessionExecution = sessionId
     ? deps.executionLedger.getLastExecution(sessionId)
@@ -155,11 +169,13 @@ export function buildDelegationContext(
     sessionExecution,
   });
 
-  if (isGoogleDelegationTarget(targetModel)) {
-    return repairGeminiReplayContext(normalized, targetModel, sessionExecution);
-  }
+  const repaired = isGoogleDelegationTarget(targetModel)
+    ? repairGeminiReplayContext(normalized, targetModel, sessionExecution)
+    : normalized;
 
-  return normalized;
+  // SP-245 (#166): light conciseness nudge only when the policy resolved a
+  // low/minimal effective level on a high-verbosity (GLM-class) profile.
+  return applyConcisenessHint(repaired, reasoning);
 }
 
 export function createErrorMessage(

package/.pi/extensions/smart-router/extension-setup.ts

@@ -120,6 +120,9 @@ export async function createSmartRouterRuntime(cwd: string): Promise<{
       executionLedger,
       lifecycleHookState,
       planningDelegateConfig: operatorConfig.planning_delegate,
+      ...(operatorConfig.adaptive_reasoning !== undefined
+        ? { adaptiveReasoningConfig: operatorConfig.adaptive_reasoning }
+        : {}),
       datasetRecorder,
       outcomeRecorder,
       sessionPinner,
@@ -138,6 +141,32 @@ export async function createSmartRouterRuntime(cwd: string): Promise<{
         }
         runtime.syncRegisteredLimits?.(limits);
       },
+      onDelegationUsage(requestId, actuals) {
+        // SP-241 / #164: persist post-turn usage actuals onto the routing
+        // telemetry row. Fail open — a telemetry write must never fail the
+        // route, and stores without update support simply skip actuals.
+        try {
+          runtime.store.updateTelemetryUsageActuals?.(requestId, actuals);
+        } catch (error) {
+          console.warn(
+            '[smart-router] failed to persist usage actuals (fail open)',
+            error instanceof Error ? error.message : String(error),
+          );
+        }
+      },
+      onDelegationReasoning(requestId, fields) {
+        // SP-246 / #166: persist the adaptive reasoning decision (requested /
+        // applied level + reason code) onto the routing telemetry row. Fail
+        // open — telemetry must never fail the route.
+        try {
+          runtime.store.updateTelemetryReasoning?.(requestId, fields);
+        } catch (error) {
+          console.warn(
+            '[smart-router] failed to persist reasoning telemetry (fail open)',
+            error instanceof Error ? error.message : String(error),
+          );
+        }
+      },
     },
   };
 

package/.pi/extensions/smart-router/planning-delegate.ts

@@ -27,6 +27,7 @@ import type {
   PlanningDelegateObservability,
   RoutingDecision,
 } from '../../../src/domain/types/index.js';
+import { resolveAdaptiveReasoning } from '../../../src/domain/delegation/adaptive-reasoning.js';
 import { DEFAULT_PLANNING_DELEGATE_CONFIG } from '../../../src/domain/types/schemas.js';
 import {
   createPlanningDelegateObservability,
@@ -190,11 +191,33 @@ export async function defaultSpawnPlanningDelegate(
   deps: StreamDelegationDeps,
 ): Promise<PlanningDelegateSpawnResult> {
   try {
+    // SP-245 (#166): planning sub-calls keep higher reasoning — the adaptive
+    // policy resolves at least `medium` for planning turns (explicit operator
+    // /thinking floors still win inside the policy). SP-246: honor the
+    // operator enable/disable + floor/ceiling knobs.
+    const reasoning = resolveAdaptiveReasoning(
+      frontierModel,
+      { turnType: 'planning' },
+      options?.reasoning,
+      deps.adaptiveReasoningConfig
+        ? {
+            enabled: deps.adaptiveReasoningConfig.enabled,
+            ...(deps.adaptiveReasoningConfig.min_level !== undefined
+              ? { floor: deps.adaptiveReasoningConfig.min_level }
+              : {}),
+            ...(deps.adaptiveReasoningConfig.max_level !== undefined
+              ? { ceiling: deps.adaptiveReasoningConfig.max_level }
+              : {}),
+          }
+        : undefined,
+    );
     const result = await collectDelegatedStream(
       frontierModel,
       compressedContext,
       deps,
       options,
+      undefined,
+      reasoning,
     );
     if (result.failed || !result.finalMessage) {
       return {

package/.pi/extensions/smart-router/route-and-delegate.ts

@@ -9,6 +9,7 @@ import type {
 
 import { safeCloudDefault } from '../../../src/domain/pipeline/safe-default.js';
 import { computeOutputHeadroom } from '../../../src/domain/delegation/output-headroom.js';
+import { resolvePeakPricingAdjustment } from '../../../src/domain/pricing/peak-pricing.js';
 import {
   CONTEXT_OVERFLOW_NO_FIT,
   resolveContextOverflowFallback,
@@ -84,6 +85,14 @@ function logRoutingDecision(
     return;
   }
 
+  // SP-244 / #165: surface peak vs off-peak pricing rationale for the selected
+  // model (Z.ai GLM Coding Plan / DeepSeek API windows; multiplier 1 + window
+  // 'none' for non-target providers — fail open).
+  const peakPricing = resolvePeakPricingAdjustment({
+    id: delegate?.modelId ?? decision.selected_model_id,
+    ...(delegate?.provider !== undefined ? { provider: delegate.provider } : {}),
+  });
+
   console.warn(
     '[smart-router] routing decision',
     JSON.stringify({
@@ -93,6 +102,12 @@ function logRoutingDecision(
       stage: decision.stage,
       reason_code: decision.reason_code,
       routing_latency_ms: decision.routing_latency_ms,
+      pricing_window: peakPricing.window,
+      peak_pricing: {
+        window: peakPricing.window,
+        cost_multiplier: peakPricing.cost_multiplier,
+        adapter_id: peakPricing.adapter_id,
+      },
       features: decision.features ?? null,
       delegate,
     }),
@@ -521,6 +536,15 @@ export async function routeAndDelegate(
           ...(failoverNotice !== undefined ? { failoverNotice } : {}),
           contextWindow: targetModel.contextWindow,
         },
+        decision.request_id,
+        // SP-245 (#166): adaptive reasoning policy — effective thinking level
+        // from this turn's envelope + routing decision (recomputed per
+        // failover iteration so escalation targets re-evaluate).
+        {
+          turnType: request.turn_type,
+          decision,
+          ...(targetProfile !== undefined ? { profile: targetProfile } : {}),
+        },
       );
 
       if (!isPipedResult(result)) {
@@ -761,6 +785,7 @@ export async function routeAndDelegate(
           ...(failoverNotice !== undefined ? { failoverNotice } : {}),
           contextWindow: fallbackModel.contextWindow,
         },
+        decision.request_id,
       );
       if (isPipedResult(fallbackResult)) {
         commitPipedTerminal(fallbackResult);

package/.pi/extensions/smart-router/stream-delegation.ts

@@ -8,6 +8,7 @@ import {
 } from '@earendil-works/pi-ai/compat';
 
 import type { RoutingDecision, RoutingFeatureSidecar } from '../../../src/domain/types/index.js';
+import { resolvePeakPricingAdjustment } from '../../../src/domain/pricing/peak-pricing.js';
 import { createErrorMessage } from './delegation-runtime.js';
 import { routeAndDelegate } from './route-and-delegate.js';
 import type { StreamDelegationDeps } from './types.js';
@@ -24,6 +25,14 @@ export function logRoutingDecision(
     return;
   }
 
+  // SP-244 / #165: surface peak vs off-peak pricing rationale for the selected
+  // model (Z.ai GLM Coding Plan / DeepSeek API windows; multiplier 1 + window
+  // 'none' for non-target providers — fail open).
+  const peakPricing = resolvePeakPricingAdjustment({
+    id: delegate?.modelId ?? decision.selected_model_id,
+    ...(delegate?.provider !== undefined ? { provider: delegate.provider } : {}),
+  });
+
   console.warn(
     '[smart-router] routing decision',
     JSON.stringify({
@@ -33,6 +42,12 @@ export function logRoutingDecision(
       stage: decision.stage,
       reason_code: decision.reason_code,
       routing_latency_ms: decision.routing_latency_ms,
+      pricing_window: peakPricing.window,
+      peak_pricing: {
+        window: peakPricing.window,
+        cost_multiplier: peakPricing.cost_multiplier,
+        adapter_id: peakPricing.adapter_id,
+      },
       features: decision.features ?? null,
       delegate,
     }),

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

@@ -11,10 +11,13 @@ import type { HydraMatcher } from '../../../src/domain/matching/hydra-matcher.js
 import { ExecutionLedger } from '../../../src/domain/delegation/execution-ledger.js';
 import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
 import type {
+  AdaptiveReasoningConfig,
   ModelProfile,
   PlanningDelegateConfig,
   PriceCatalog,
   RoutingDecision,
+  RoutingReasoningTelemetry,
+  RoutingUsageActuals,
 } from '../../../src/domain/types/index.js';
 import type { PlanningDelegateSpawnFn } from './planning-delegate.js';
 import type { StorePort } from '../../../src/domain/types/store-port.js';
@@ -68,6 +71,8 @@ export interface StreamDelegationDeps {
   spawnPlanningDelegate?: PlanningDelegateSpawnFn;
   /** Planning delegate knobs incl. global + per-call timeout bounds (SP-213, #120). */
   readonly planningDelegateConfig?: PlanningDelegateConfig;
+  /** Adaptive reasoning knobs: enable/disable + floor/ceiling (SP-246, #166). */
+  readonly adaptiveReasoningConfig?: AdaptiveReasoningConfig;
   readonly lifecycleHookState?: LifecycleHookState;
   readonly datasetRecorder?: DatasetRecorder;
   readonly outcomeRecorder?: OutcomeRecorder;
@@ -82,6 +87,18 @@ export interface StreamDelegationDeps {
     readonly contextWindow?: number;
     readonly maxTokens?: number;
   }) => void;
+  /**
+   * Fired after a delegated stream ends with host-reported usage actuals
+   * (SP-241, #164). Also fires on failed-with-usage terminals. Implementations
+   * must not throw — actuals capture never fails the route.
+   */
+  onDelegationUsage?: (requestId: string, actuals: RoutingUsageActuals) => void;
+  /**
+   * Fired after the adaptive reasoning policy resolves the effective thinking
+   * level for a delegated stream (SP-246, #166). Implementations must not
+   * throw — reasoning telemetry must never fail the route.
+   */
+  onDelegationReasoning?: (requestId: string, fields: RoutingReasoningTelemetry) => void;
 }
 
 export interface SmartRouterRuntime {

package/README.md

@@ -218,7 +218,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 stats` | Privacy-safe session/window aggregates from routing telemetry: count, mean cost/latency with `cost_basis` labeling (actual vs estimated, SP-241), planning_delegate vs direct share, local vs cloud when distinguishable, and role cost breakdown. Optional vs-always-frontier savings when frontier fleet prices exist (omitted otherwise). The JSON snapshot (`buildStatsSnapshot`, automation surface) additionally carries warm rolling `cost_calibration` actual/estimate buckets (SP-242). 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 |
@@ -441,6 +441,9 @@ Cluster IDs are stable reason-code prefixes (`cluster_low_stakes_general`, `clus
 | `SMART_ROUTER_PLANNING_DELEGATE_EXCLUDE_EXECUTION_HISTORY` | `true` | Exclude tool execution history from delegate payload |
 | `SMART_ROUTER_PLANNING_DELEGATE_GLOBAL_TIMEOUT_MS` | `120000` | Global cap (ms) on the whole planning-delegate stage per planning turn — bounds fan-out wall-clock so a stalled worker cannot hang TTFT ([#120](https://github.com/beettlle/pi-smart-router/issues/120)) |
 | `SMART_ROUTER_PLANNING_DELEGATE_SUB_CALL_TIMEOUT_MS` | `30000` | Per-call cap (ms) on each delegate sub-call worker; on expiry the worker is cancelled/abandoned and routing falls back to direct frontier with `planning_delegate_timeout` ([#120](https://github.com/beettlle/pi-smart-router/issues/120)) |
+| `SMART_ROUTER_ADAPTIVE_REASONING_ENABLED` | `true` | Master switch for the adaptive thinking-level policy ([#166](https://github.com/beettlle/pi-smart-router/issues/166)); `false` passes the session thinking level through unchanged |
+| `SMART_ROUTER_ADAPTIVE_REASONING_MIN_LEVEL` | (unset) | Floor on policy-derived thinking levels (`minimal\|low\|medium\|high\|xhigh\|max`) — see [Adaptive reasoning](#adaptive-reasoning-thinking-level-166) |
+| `SMART_ROUTER_ADAPTIVE_REASONING_MAX_LEVEL` | (unset) | Ceiling on policy-derived thinking levels (incl. turn-class upgrades) — see [Adaptive reasoning](#adaptive-reasoning-thinking-level-166) |
 | `SMART_ROUTER_PREFIX_CACHE_WEIGHT` | `0.20` | SAAR weight on warm prefix value in cache breakeven math (0–1; [#73](https://github.com/beettlle/pi-smart-router/issues/73)) |
 | `SMART_ROUTER_IDLE_TIMEOUT_SECONDS` | `300` | SAAR idle seconds before pin reopens for full re-route |
 | `SMART_ROUTER_SWITCH_THRESHOLD` | `0.5` | SAAR switch score gate (0–1) for tier upgrades during hard-lock |
@@ -459,6 +462,7 @@ When `SMART_ROUTER_LOG_ROUTING=1`, prefer the canonical payload from `buildRouti
 | `tier_hint` | Yes (top-level + `cluster_summary`) | Null when no tier hint |
 | `local_eligible_reason` | Yes (top-level + `features`) | Null when local_zero did not evaluate eligibility |
 | `cluster_id` | Yes (top-level + `cluster_summary`) | Null when no cluster match |
+| `pricing_window` | Yes (top-level + `peak_pricing_summary`) | Peak vs off-peak rationale for the selected model (SP-244 / #165); the extension stderr logger carries `pricing_window` + `peak_pricing` |
 
 **Gap:** the pi extension’s live stderr path (`logRoutingDecision` in `.pi/extensions/smart-router`) still emits a slim JSON object (`selected_model_id`, `stage`, `reason_code`, `features`, `delegate`) and does **not** yet call `buildRoutingDecisionLogPayload`. SQLite `/smart-router history` and the payload builder carry the full checklist; wire the extension logger in a follow-up if dogfood needs identical stderr shape.
 
@@ -515,6 +519,41 @@ When a **planning** turn would route primary inference to frontier while a warm
 
 See [routing-roadmap.md](docs/routing-roadmap.md) §2 P0 and GitHub [#71](https://github.com/beettlle/pi-smart-router/issues/71) for acceptance criteria.
 
+### Adaptive reasoning (thinking level) (#166)
+
+Adaptive reasoning tunes the **thinking intensity of the model already selected** — it never changes which model runs. Per turn class:
+
+| Turn class | Policy level |
+|-----------|--------------|
+| `tool_result` | `minimal` |
+| `main_loop` | `low` |
+| planning / `planning_delegate` | `medium` |
+| frontier escalation / `loop_escalation` | `high` |
+
+pi passes the session thinking level on every call; the router treats pi's ambient default (`medium`) as adjustable by policy, and any **other** explicit level as an operator `/thinking` floor that is **never lowered** (a turn-class upgrade may still raise it). Chatty profiles (high `verbosity_factor`) additionally get a one-line conciseness nudge at `minimal`/`low`.
+
+**Three knobs that sound alike, do different things:**
+
+| Knob | Acts on | What it changes |
+|------|---------|-----------------|
+| **Adaptive reasoning** (`adaptive_reasoning.*`) | The delegated call's `reasoning` option | Thinking *intensity* of the already-selected model — cost of thinking, not model choice |
+| `frugality.lambda_verbosity` | Multi-objective **selection** scoring | Which model gets picked — penalizes verbose models while ranking candidates; never touches the delegated call's reasoning option |
+| `/thinking` (pi session command) | The caller-provided reasoning level | Explicit operator override — an explicit level is never lowered by policy or bounds |
+
+**Operator knobs** (config `adaptive_reasoning` / env):
+
+| Key | Env var | Default | Effect |
+|-----|---------|---------|--------|
+| `enabled` | `SMART_ROUTER_ADAPTIVE_REASONING_ENABLED` | `true` | When `false`, the policy is skipped — delegated calls pass the session thinking level through unchanged (`reasoning_reason_code: adaptive_reasoning_disabled`) |
+| `min_level` | `SMART_ROUTER_ADAPTIVE_REASONING_MIN_LEVEL` | (none) | Floor: policy-derived levels are raised to at least this level. Discrete level (`minimal\|low\|medium\|high\|xhigh\|max`) — deliberately **not** a free-form verbosity percent |
+| `max_level` | `SMART_ROUTER_ADAPTIVE_REASONING_MAX_LEVEL` | (none) | Ceiling: policy-derived levels (incl. turn-class upgrades) are capped at this level. When `min_level` exceeds `max_level` (e.g. via env), the ceiling wins (cost-safe) |
+
+Floor/ceiling bind only what the policy itself derives. An explicit operator `/thinking` choice is never **lowered** by either bound (a floor can still *raise* one via the policy-upgrade path). Both bounds re-clamp down to the model's supported levels.
+
+**Fail-open behavior:** models that do not support reasoning options (`reasoning: false`, or a `thinkingLevelMap` mapping every relevant level to `null`) pass caller options through unchanged — telemetry records `reasoning_reason_code: reasoning_unsupported` and the route never fails. Providers that ignore reasoning options degrade to a no-op.
+
+**Telemetry:** each routed delegation records `reasoning_level_requested` (the session/caller level), `reasoning_level_applied` (the effective delegated level), and `reasoning_reason_code` (e.g. `turn_envelope_main_loop`, `operator_thinking_floor`, `operator_floor_applied`, `operator_ceiling_applied`, `reasoning_unsupported`) on the routing telemetry row — enriched post-delegation like usage actuals ([SP-241](https://github.com/beettlle/pi-smart-router/issues/164)). Inspect via `/smart-router history`.
+
 ### Degraded neural failover sandwich (#119)
 
 When the encoder/neural stage (HyDRA) **fails, is misconfigured, or exceeds its latency budget without a selection**, routing fails open through a cheap chain instead of crashing the host agent ([#119](https://github.com/beettlle/pi-smart-router/issues/119)):
@@ -587,6 +626,48 @@ When `quotaWindowPosition` is omitted, λ stays at 1 and quota premiums are zero
 
 See [routing-roadmap.md](docs/routing-roadmap.md) §2 P2 and GitHub [#78](https://github.com/beettlle/pi-smart-router/issues/78).
 
+### Usage actuals (post-turn capture)
+
+When pi reports an assistant message `usage` object after a delegated turn, the smart-router persists it onto that turn's routing telemetry row ([#164](https://github.com/beettlle/pi-smart-router/issues/164)): `actual_cost_usd`, `actual_input_tokens`, `actual_output_tokens`, and cache read/write token counts — while retaining `estimated_cost_usd`. Capture fails open: library embeds and non-pi hosts that report no usage simply leave the actual fields null, and a telemetry write error never fails the route. Subscription/OAuth models report `cost.total === 0`: token actuals are still recorded, but no USD is invented — `/smart-router stats` labels its totals `cost_basis: 'actual' | 'estimated' | 'mixed'` accordingly.
+
+### Rolling cost calibration (v0.20.0 usage actuals)
+
+**Rolling cost calibration** soft-biases future cost estimates with the ratio your models *actually* bill versus what the router estimated ([#164](https://github.com/beettlle/pi-smart-router/issues/164)). It is built from the privacy-safe post-turn [usage actuals](#usage-actuals-post-turn-capture) — no new state to configure, and prompt/message bodies are never touched.
+
+**How it works**
+
+1. Every routed turn records an `estimated_cost_usd` (input tokens × catalog rate) and, when pi reports it, an `actual_cost_usd` on the same telemetry row.
+2. `buildCostCalibrationPrior` derives per-**model** and per-**tier** mean `actual / estimate` ratios over the rolling telemetry window. Per-pair outliers are clamped (±10×) before averaging; the aggregate is clamped to a soft band of **[0.5, 2.0]** so calibration can never hard-ban or hard-favor a model on cost alone.
+3. When warm (≥ 3 usable pairs per bucket), the ratio multiplies the tier's base per-1M cost **before** the virtual-cost v2 λ/premium/KV chain — so quota decay and cache credits compound on the calibrated base. Model buckets win over tier buckets.
+4. `estimateRoutingCost` accepts the same prior as an optional argument, soft-biasing per-request cost estimates identically.
+
+**Cold start fails open.** No prior, an empty prior, or a bucket below the warmup threshold resolves ratio 1 — the catalog estimate is used unchanged. Subscription rows (host reports `cost.total === 0`) never contribute: stats and calibration never invent USD.
+
+**Where it applies**
+
+- **Expected-cost tier selection** — pass `costCalibration` into `selectTierByExpectedCost` / `computeExpectedCost` (library API, same pattern as `heatBias`). A warm ratio that doubles an economical tier's effective cost can flip the next selection to frontier; the price-delta and pin-economics hard gates still apply after the soft bias.
+- **Pre-route estimates** — `estimateRoutingCost(model, request, catalog, calibration?)`; the router pipeline's uncalibrated call is unchanged.
+- **`/smart-router stats`** — the aggregate's JSON snapshot (`aggregateSessionStats` / `buildStatsSnapshot`, the automation/MCP surface) carries a `cost_calibration` array (model buckets first, then tier buckets, each `{key, kind, ratio, samples}`); omitted entirely when cold so automation can treat absence as catalog-only. The human-readable stats text keeps rendering cost basis and role breakdown only.
+
+**Observing the bias** — run with `SMART_ROUTER_LOG_ROUTING=1` and read the expected-cost gate line: calibrated winners carry a `[cost-calib ×N.NN from rolling actuals (SP-242)]` note on the rationale, and each tier's `calibrationRatio` appears in the expected-cost breakdown (`features.tier_selection.tier_costs[]`).
+
+**Knobs** (`DEFAULT_COST_CALIBRATION_CONFIG`): `minSamples` 3 (warmup), `minRatio`/`maxRatio` 0.5/2.0 (soft band), `sampleMinRatio`/`sampleMaxRatio` 0.1/10 (per-pair outlier clamp). Not a vendor peak-clock schedule — see [#165](https://github.com/beettlle/pi-smart-router/issues/165) for time-of-day pricing.
+
+### Peak/off-peak pricing adapters (v0.20.0, #165)
+
+Two vendors publish documented **time-of-day rate cards**. The peak-pricing adapters (`src/domain/pricing/peak-pricing.js`, SP-243) soft-bias the resolved cost-per-1M by the current pricing window — they never hard-ban a model, and non-target providers (OpenAI / Anthropic / Gemini / local / unknown) always resolve `window: 'none'` with multiplier 1 (fail open).
+
+| Vendor | Adapter | Peak window | Off-peak rate | Docs |
+|--------|---------|-------------|---------------|------|
+| Z.ai GLM Coding Plan | `zai` (matches `zai`/`glm`/`zhipu` providers and `glm-*` ids) | Mon–Fri 14:00–18:00 Asia/Singapore (UTC+8) | 0.5× the standard credit rate | [Z.ai GLM Coding Plan docs](https://docs.z.ai/devpack/overview) |
+| DeepSeek pay-as-you-go API | `deepseek` (matches `deepseek` provider / ids) | Mon–Fri 01:00–04:00 and 06:00–10:00 UTC | ½ the peak rate on cache-hit input, cache-miss input, and output | [DeepSeek Models & Pricing](https://api-docs.deepseek.com/quick_start/pricing) |
+
+**Z.ai plan profiles.** The default plan profile is `credits` — off-peak usage at 0.5× the standard credit rate, peak at 1×. **Legacy plans** (e.g. GLM-5.3 legacy at 3× peak / 1× off-peak, Flash at 1.2× / 0.4×) share the same window but use different multipliers; they are available **only** via an explicit operator override (`PeakPricingConfig.zai`: `plan_profile: 'legacy'` plus documented `peak_multiplier` / `off_peak_multiplier`). The adapter never scrapes the live account plan — legacy multipliers are documented override inputs, not detected state.
+
+**Configuration.** Adapters are on by default; `PeakPricingConfig.enabled: false` returns to flat rates. `PeakPricingConfig.deepseek.off_peak_multiplier` overrides the documented 0.5 off-peak discount if DeepSeek changes its schedule.
+
+**Observing the window.** Every routed turn records `pricing_window: 'peak' | 'off_peak' | 'none'` on its telemetry row (SP-243). With `SMART_ROUTER_LOG_ROUTING=1`, the routing-decision payload surfaces the rationale as top-level `pricing_window` plus `peak_pricing_summary` (`window`, `cost_multiplier`, `adapter_id`) on the canonical `buildRoutingDecisionLogPayload`, and `pricing_window` + `peak_pricing` on the extension stderr logger (SP-244).
+
 ### P(success) training export (baseline classifier)
 
 When `SMART_ROUTER_DATASET=1`, the router records privacy-safe dataset rows and behavioral outcome labels. Export labeled training data from pi:

package/config/operator-config.json.example

@@ -74,5 +74,15 @@
       "max_tool_use_requirement": "Ceiling (0–1) on cheap predicted tool_use for local_zero dispatch. Effective limit is min(local model tool_use capability, this value). Default 0.25 keeps format/lint local while skipping agentic git/bash/edit/explore/delete/repo cues (SP-177, #98)."
     }
   },
+  "adaptive_reasoning": {
+    "enabled": true,
+    "min_level": "low",
+    "max_level": "high",
+    "_documentation": {
+      "enabled": "When false, adaptive reasoning is skipped — delegated calls pass the caller (session) thinking level through unchanged. Default true (SP-246, #166).",
+      "min_level": "Optional floor on policy-derived thinking levels (minimal | low | medium | high | xhigh | max). Routine tool_result/main_loop turns policy-resolve to minimal/low; a floor raises that. Never lowers an explicit operator /thinking choice. Omit for no floor.",
+      "max_level": "Optional ceiling on policy-derived thinking levels, including turn-class upgrades. When min_level would exceed max_level (e.g. via env), the ceiling wins. Omit for no ceiling."
+    }
+  },
   "pin_only_fallback": false
 }

package/dist/config/defaults.d.ts

@@ -3,8 +3,8 @@
  * Values sourced from specs/001-build-smart-router/data-model.md § Configuration (Operator).
  */
 import { type OperatorConfig } from '../domain/types/schemas.js';
-export { DEFAULT_LOCAL_ZERO_CONFIG, DEFAULT_PLANNING_DELEGATE_CONFIG, DEFAULT_SAAR_CONFIG, DEFAULT_SPECULATIVE_PREWARM_CONFIG, DEFAULT_WORKLOAD_HEAT_CONFIG, resolvePlanningDelegateConfigFromEnv, resolveSaarConfigFromEnv, } from '../domain/types/schemas.js';
-/** Merge operator env overrides onto defaults (SAAR and planning delegate sections). */
+export { DEFAULT_ADAPTIVE_REASONING_CONFIG, DEFAULT_LOCAL_ZERO_CONFIG, DEFAULT_PLANNING_DELEGATE_CONFIG, DEFAULT_SAAR_CONFIG, DEFAULT_SPECULATIVE_PREWARM_CONFIG, DEFAULT_WORKLOAD_HEAT_CONFIG, resolveAdaptiveReasoningConfigFromEnv, resolvePlanningDelegateConfigFromEnv, resolveSaarConfigFromEnv, } from '../domain/types/schemas.js';
+/** Merge operator env overrides onto defaults (adaptive reasoning, SAAR and planning delegate sections). */
 export declare function resolveOperatorConfigFromEnv(base?: OperatorConfig): OperatorConfig;
 export declare const DEFAULT_OPERATOR_CONFIG: Readonly<OperatorConfig>;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/config/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,kCAAkC,EAClC,4BAA4B,EAC5B,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AAEpC,wFAAwF;AACxF,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,cAAwC,GAC7C,cAAc,CAMhB;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,cAAc,CAqCnD,CAAC"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAWL,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,iCAAiC,EACjC,yBAAyB,EACzB,gCAAgC,EAChC,mBAAmB,EACnB,kCAAkC,EAClC,4BAA4B,EAC5B,qCAAqC,EACrC,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AAEpC,4GAA4G;AAC5G,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,cAAwC,GAC7C,cAAc,CAOhB;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,cAAc,CAuCnD,CAAC"}