pi-smart-router 0.19.0 → 0.19.2

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

@@ -6,7 +6,7 @@ import {
   type Context,
   type Model,
   type SimpleStreamOptions,
-  streamSimple as defaultDelegateStream,
+  streamSimple as compatDelegateStream,
 } from '@earendil-works/pi-ai/compat';
 
 import { parseAssistantMessageError } from '../../../src/infrastructure/delegation/provider-error.js';
@@ -21,9 +21,55 @@ import {
   type FailoverNoticeInfo,
   type FlushDelegatedEventsOptions,
 } from './delegation-runtime.js';
-import type { StreamDelegationDeps } from './types.js';
+import type { DelegateStreamFn, StreamDelegationDeps } from './types.js';
 import { throwIfAborted } from './utils.js';
 
+/**
+ * Minimal structural view of pi's composed provider (pi-coding-agent
+ * `ModelRegistry.getProvider()` → `composeModelProvider`). Typed structurally
+ * because `getProvider` only exists on newer pi-coding-agent versions (0.84+);
+ * the extension must keep loading against older ones.
+ */
+interface ComposedProviderLike {
+  streamSimple: DelegateStreamFn;
+}
+
+type RegistryWithProviders = StreamDelegationDeps['modelRegistry'] & {
+  getProvider?: (providerId: string) => ComposedProviderLike | undefined;
+};
+
+/**
+ * Resolve the stream entrypoint for a delegation target (SP-238, #160).
+ *
+ * Priority:
+ * 1. Explicit `deps.delegateStream` injection (tests / operator override).
+ * 2. The **composed provider** from `modelRegistry.getProvider(model.provider)` —
+ *    the same path pi's own agent loop delegates through. Its `streamSimple`
+ *    checks extension-registered providers (`extension.streamSimple` when
+ *    `model.api === extension.api`) before falling back to pi-ai's built-in
+ *    registry, so custom-API models (claude-bridge et al.) resolve correctly.
+ * 3. Bare `pi-ai/compat streamSimple` — dispatches only on `model.api` against
+ *    pi-ai's private built-in registry; used when no composed provider exists
+ *    (older pi-coding-agent, or providers never composed through ModelRuntime).
+ */
+function resolveDelegateStream(
+  targetModel: Model<Api>,
+  deps: StreamDelegationDeps,
+): DelegateStreamFn {
+  if (deps.delegateStream) {
+    return deps.delegateStream;
+  }
+  const registry = deps.modelRegistry as RegistryWithProviders;
+  const provider =
+    typeof registry.getProvider === 'function'
+      ? registry.getProvider(targetModel.provider)
+      : undefined;
+  if (provider && typeof provider.streamSimple === 'function') {
+    return (model, context, options) => provider.streamSimple(model, context, options);
+  }
+  return compatDelegateStream;
+}
+
 function isTerminalEvent(
   event: AssistantMessageEvent,
 ): event is Extract<AssistantMessageEvent, { type: 'done' | 'error' }> {
@@ -52,7 +98,7 @@ export async function collectDelegatedStream(
     options,
     headroomContext,
   );
-  const delegateStream = deps.delegateStream ?? defaultDelegateStream;
+  const delegateStream = resolveDelegateStream(targetModel, deps);
   const inner = delegateStream(targetModel, context, delegationOptions);
   const events: AssistantMessageEvent[] = [];
   let finalMessage: AssistantMessage | undefined;
@@ -119,7 +165,7 @@ export async function pipeDelegatedStream(
     options,
     headroomContext,
   );
-  const delegateStream = deps.delegateStream ?? defaultDelegateStream;
+  const delegateStream = resolveDelegateStream(targetModel, deps);
   const inner = delegateStream(targetModel, context, delegationOptions);
   const events: AssistantMessageEvent[] = [];
   let finalMessage: AssistantMessage | undefined;

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

@@ -57,7 +57,12 @@ export interface StreamDelegationDeps {
   /** Cheap scope fingerprint check before each routed turn. */
   ensureFleetFresh?: () => Promise<void>;
   readonly executionLedger: ExecutionLedger;
-  /** Injectable for tests; production uses pi-ai streamSimple. */
+  /**
+   * Injectable stream override for tests; when unset, delegation resolves the
+   * stream through `modelRegistry.getProvider(...)` (composed provider, which
+   * knows extension-registered custom APIs — SP-238, #160), falling back to
+   * pi-ai/compat `streamSimple` when no composed provider exists.
+   */
   delegateStream?: DelegateStreamFn;
   /** Injectable planning delegate sub-call; production uses frontier stream delegate. */
   spawnPlanningDelegate?: PlanningDelegateSpawnFn;

package/README.md

@@ -263,6 +263,50 @@ npm run verify:ci
 
 `RouterPipeline.route()` calls on a single router instance are **single-flight**: concurrent calls are serialized internally (SP-230, [#141](https://github.com/beettlle/pi-smart-router/issues/141)). The pipeline keeps per-route transient state on instance fields while stages run, so overlapping executions are queued rather than interleaved — each queued call waits at most one routing latency. This applies to `createRouter()` / `createRouterFromFleet()` handles: a shared `router.dispatch` is safe to call concurrently, and serialization does not change routing policy outcomes. For parallel routing throughput, create separate router instances.
 
+## Library vs extension
+
+pi-smart-router ships in two shapes, and they are **not** feature-identical ([#153](https://github.com/beettlle/pi-smart-router/issues/153)):
+
+| Path | What you get |
+|------|--------------|
+| **Pi extension** (`pi install npm:pi-smart-router`, or project-local `.pi/extensions/smart-router/` when developing from clone) | The full product — the routing pipeline **plus** the stream-level behaviors below |
+| **npm library** (`createRouter()` / `createRouterFromFleet()` / `GatewayDispatch`) | The routing core — the 12-stage pipeline, fleet mapping, telemetry, and gateway health/failover *selection*. Stream-level behaviors are stubbed or left to your embedder loop |
+
+### Extension-only capabilities
+
+These behaviors run in `.pi/extensions/smart-router/` and have **no equivalent in the library API**:
+
+| Capability | Extension implementation | Library status |
+|------------|--------------------------|----------------|
+| **Planning delegate spawn** — cache-preserving ephemeral frontier sub-call on planning turns, with observation injection and bounded timeouts (SP-144, SP-213 / [#71](https://github.com/beettlle/pi-smart-router/issues/71), [#120](https://github.com/beettlle/pi-smart-router/issues/120)) | `.pi/extensions/smart-router/planning-delegate.ts` — compressed-context sub-call via `streamSimple`; falls back to direct frontier with a documented `fallback_reason` | The pipeline still emits `planning_delegate` decisions with delegate model and compressed limits, but **nothing spawns the delegate** — an embedder must implement the sub-call itself or accept direct-frontier routing |
+| **Stream failover loop** — live provider-error failover across candidate models with user-facing notices (atomic state machine, [#33](https://github.com/beettlle/pi-smart-router/issues/33)) | `.pi/extensions/smart-router/route-and-delegate.ts` (~L377–595) — retries stream delegation across alternates, emits failover notices, ends in SP-226 fail-open safe default | `GatewayDispatch.selectFailover()` only **selects** an alternate model; no stream retry loop runs. The embedder owns iterating over failures and re-dispatching |
+| **Output headroom escalation** — exclude failover candidates whose context window cannot fit input plus the required output floor (SP-108) | `route-and-delegate.ts` + `.pi/extensions/smart-router/delegation-runtime.ts` — per-attempt `computeOutputHeadroom` checks; `headroomExcludedModelIds` accumulate across the failover loop | `src/domain/delegation/output-headroom.ts` ships the helper, but **no library caller wires it** into `GatewayDispatch.dispatch()` — the embedder must apply it per attempt |
+| **Cursor quota handling** — subscription-quota exhaustion detection and failover to `cursor/auto` or economical API models with `cursor_quota_exhausted` telemetry (SP-097 / [#70](https://github.com/beettlle/pi-smart-router/issues/70)) | The extension stream loop catches quota errors from live streams and drives `selectFailover` reactively | Detection and failover *selection* exist in `src/infrastructure/gateway/gateway-dispatch.ts` (`isCursorQuotaExhaustedError`, per-model quota tracking), but the **reactive trigger lives in the extension's stream loop** — library dispatch alone does not observe provider stream errors |
+
+### The middleware is a lifecycle stub, not a router
+
+`createPiRouterMiddleware()` / `RouterHandle.register()` (`src/api/middleware/pi-router-middleware.ts`) registers **lifecycle hooks only** — compaction flags and `model_select` overrides consumed when building the next routing request. It does **not** intercept LLM streams, route requests, or delegate inference. The production stream path lives in the pi extension (`route-and-delegate.ts`, `stream-delegation.ts`, `delegate-stream.ts`), not in the npm-exported middleware. Treat `middleware` as a flag registrar; routing happens through your call to `router.dispatch.dispatch()` or the extension's stream path.
+
+### Recommended integration path
+
+- **pi users:** install the **extension** (`pi install npm:pi-smart-router`). It is the full product — everything in the table above works out of the box, including failover, delegate spawn, headroom escalation, and quota reaction.
+- **npm embedders:** you get the **routing core** (12-stage pipeline, fleet mapping, telemetry, gateway health tracking, failover *selection*). Plan to implement your own stream delegation, failover iteration, headroom checks, and planning-delegate spawn around the decisions the pipeline returns — or track [#149](https://github.com/beettlle/pi-smart-router/issues/149) (**extension public facade**), the migration plan for exposing the extension's stream/delegation surface as supported library API so this gap closes over time. Until #149 lands, the extension modules also import `src/**` internals directly, so deep imports into `src/` are not a stable API.
+
+```text
+pi extension path (full product)        npm library path (routing core)
+────────────────────────────────        ───────────────────────────────
+pi (host agent)                         your host application
+  └─ .pi/extensions/smart-router/         └─ createRouter() / createRouterFromFleet()
+       ├─ routing pipeline (src/)  ════════    ├─ routing pipeline (src/)        ← shared core
+       ├─ stream failover loop          ✗      ├─ GatewayDispatch: health tracking,
+       ├─ planning delegate spawn       ✗      │   failover selection only
+       ├─ output headroom escalation    ✗      ├─ lifecycle middleware (stub: hooks only)
+       └─ cursor quota failover         ✗      └─ embedder implements: stream loop,
+                                            delegate spawn, headroom checks, quota reaction
+```
+
+`✗` = capability exists only on the extension path today; [#149](https://github.com/beettlle/pi-smart-router/issues/149) is the plan to close the gap.
+
 ## Fleet behavior
 
 When you use `smart-router/auto`, the extension does **not** read `config/models.yaml`. Instead:
@@ -1275,19 +1319,21 @@ Confirm https://pi.dev/packages/pi-smart-router shows the new version (may lag n
 
 ## Develop with pi-spine (agent models)
 
-This repo is developed with [pi-spine](https://github.com/beettlle/pi-spine) batches. Agent model pins live in [`.spine/spine-config.json`](.spine/spine-config.json) under `agents.*`. Use **canonical** `provider/model` ids from `pi --list-models` (not TUI labels like `glm-5.2 [zai]`). Run `spine doctor` before real-pi batches.
+This repo is developed with [pi-spine](https://github.com/beettlle/pi-spine) batches. Agent model pins live in [`.spine/spine-config.json`](.spine/spine-config.json) under `agents.*`. Use **canonical** `provider/model` ids from `pi --list-models` (not TUI labels like `glm-5.3 [zai]`). Run `spine doctor` before real-pi batches.
 
 Named profiles (`agents.profiles` + `agents.activeProfile`) and `agents.escalatePolicy` are configured in spine-config ([pi-spine#216](https://github.com/beettlle/pi-spine/issues/216) / SP-664). Live stack resolves from `activeProfile` over the base `agents` block. Hybrid cost/quality recipes are documented upstream in [pi-spine#210](https://github.com/beettlle/pi-spine/issues/210).
 
+**Sale window (through 2026-09-09 UTC+8):** plan review and supervisor use `zai/glm-5.3-flash` (Z.AI 50% promo). After the promo, revert plan to `google/gemini-flash-latest` and supervisor to `google/gemini-flash-lite-latest` if desired.
+
 ### Default profile (`activeProfile: "default"`)
 
 | Role | Model | Thinking |
 |------|--------|----------|
-| Worker | `zai/glm-5.2` | `high` |
-| Plan review | `google/gemini-flash-latest` | `low` |
-| Code review | `kimi-coding/kimi-k2-thinking` | `high` |
+| Worker | `kimi-coding/k3` | `high` |
+| Plan review | `zai/glm-5.3-flash` | `low` |
+| Code review | `kimi-coding/kimi-for-coding` | `high` |
 | Final review | `google/gemini-3.1-pro-preview` | `high` |
-| Supervisor | `google/gemini-flash-lite-latest` | `off` |
+| Supervisor | `zai/glm-5.3-flash` | `off` |
 
 ### When to escalate (hard packets / sticky failures)
 
@@ -1297,12 +1343,12 @@ Escalate when:
 - The worker stalls or oscillates on multi-file design
 - The packet needs deeper reasoning than the default stack delivered
 
-### Tier 1 — mid escalate
+### Tier 1 — budget escalate
 
-Switches the worker to `kimi-coding/kimi-for-coding` (reviewer pins inherit default).
+Switches the worker to `zai/glm-5.3` (same list price as 5.2; plan/supervisor stay on sale Flash).
 
 ```bash
-spine settings set agents.activeProfile mid
+spine settings set agents.activeProfile budget
 spine batch retry <SP-ID>
 # restore:
 spine settings set agents.activeProfile default
@@ -1313,7 +1359,7 @@ spine settings set agents.activeProfile default
 | Role | Model | Thinking |
 |------|--------|----------|
 | Worker | `kimi-coding/k3` | `high` |
-| Plan | `kimi-coding/kimi-k2-thinking` | `medium` |
+| Plan | `kimi-coding/kimi-for-coding` | `medium` |
 | Code | `google/gemini-3.1-pro-preview` | `high` |
 | Final | `google/gemini-3.1-pro-preview` | `high` |
 

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-08-28",
-    "catalog_freeze_date": "2026-08-28"
+    "scrape_date": "2026-08-29",
+    "catalog_freeze_date": "2026-08-29"
   },
   "aliases": {
     "anthropic/claude-opus-4": "claude-opus-4-5",

package/package.json

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