pi-braid-providers 1.0.6 → 1.0.7

package/README.md

@@ -1,243 +1,94 @@
 # pi-braid-providers
 
-```bash
-pi install npm:pi-braid-providers
-```
+Key rotation, provider failover, and route health for the [pi](https://github.com/earendil-works/pi)
+coding agent: several keys per provider, a dead key retired instead of retried, and a failover to a
+healthier route when a provider's ring runs dry.
 
-One command, no clone, no build: `pi install` registers the package with pi and installs it under pi's npm directory.
-
-Additional LLM providers for `pi-coding-agent`, built on a generalized **API key ring** for multi-key rotation and self-healing.
-
-The `providers` workspace registers providers into pi at session start. The key-ring machinery that both the agent loop and direct extension LLM calls use ships here; the provider itself is the **`agent-zero`** setup: the multi-vendor gateway that proxies Venice's models, configured from a catalog file resolved at runtime.
-
-> **A fresh install registers no provider.** The `agent-zero` model catalog
-> (Venice's models) and gateway URL are read from a userland catalog file
-> resolved at runtime (see `venice-catalog.ts`) that this package does not
-> include. Without it the extension loads with the key-ring machinery active
-> and zero registered providers; a synthetic route can be registered through
-> `registerRoute` (`ring-lifecycle.ts`), the seam the test suite uses for its
-> multi-route coverage.
-
-## The key ring
-
-Each provider gets its own key ring with **exponential backoff**:
-
-- **Multi-key rotation.** Keys load from `${PREFIX}_P0` … `${PREFIX}_P9` in the
-  environment, falling back to the bare `PREFIX` var when no numbered keys
-  exist. On a quota/auth/403 error the active key is exhausted and the next
-  request serves the next healthy key.
-- **Persisted state.** Exhausted-key state persists to
-  `~/.pi/agent/.key-ring-state-<provider>.json`, so restarts skip known-dead
-  keys instead of retrying them and hitting the same 403. The file lives in
-  pi's agent directory (`state-paths.ts` owns the resolution); if no absolute
-  home can be resolved, the ring refuses to persist and says so rather than
-  writing a path relative to the cwd.
-- **Self-healing turn retry.** When a turn fails and a fresh key remains, an
-  explicit marker is appended so pi-core re-runs the turn on the next key
-  automatically. Fatal account-level errors (quota exhausted, billing, balance)
-  are never masqueraded as retryable.
-- **Direct-call feedback.** Direct extension LLM calls (an extension's own
-  `completeSimple`/`streamSimple` use)
-  feed 429/403 back into the ring too, so no dead key is served on those paths.
-- **Diagnostics.** Rotation/exhaustion events route through a throttled notify
-  sink (not `console.*`); a loud _all-keys-exhausted_ warning fires when every
-  key is in backoff.
-
-## Installation
+## Install
 
 ```bash
 pi install npm:pi-braid-providers
 ```
 
-Or register the workspace in `~/.pi/agent/settings.json`:
-
-```json
-{
-  "packages": ["file:~/pi-braid/packages/providers"]
-}
-```
-
-## Pre-send payload guard
+Then name your routes (see Configuration). Until a route and its key are configured, the extension
+loads the machinery and registers no provider: inert, not broken.
 
-| Setting                              | Default | Effect                                                                                                                                                                                                                                   | Read cadence                                    |
-| ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| `braid.context.presendGuard.enabled` | `true`  | When enabled, if an estimated request exceeds 90% of a known model context window, oversized strings that can be flushed are written losslessly to disk and replaced by stubs. `false` skips the guard; unknown windows are not guessed. | Re-read at use time for every provider request. |
+## What you get
 
-## What this does not do
+| Surface            | What it gives you                                                                                                                                                     |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Multi-key rotation | Numbered keys per provider, falling back to the bare variable. On a quota, auth or 403 error the active key is retired and the next request uses the next healthy one |
+| Persisted state    | Key-ring state on disk, so a restart skips keys already known dead instead of retrying the same 403                                                                   |
+| Turn retry         | When a turn fails and a fresh key remains, the next key serves the retry; fatal account errors are never disguised as retryable                                       |
+| Failover           | An ordered route table, walked one rotation per episode, with one notice to the owner and a bounded fail-back probe that returns when the dead route recovers         |
+| Route health       | `ring_health` reports each ring and each route's last probe: read-only, key hashes only, never writes                                                                 |
+| Request guard      | `braid.context.presendGuard` flushes oversized strings to disk above 90% of a known window, so a large request shrinks instead of being rejected                      |
 
-- It does not ship a provider catalog. The `agent-zero` model list and gateway URL are read from a
-  catalog file resolved at runtime; without it the extension loads the key-ring machinery and
-  registers zero providers.
-- It does not rotate to a route you did not configure - a route is recognized only by the model ids
-  it declares.
-- It does not retry a fatal account error (quota exhausted, billing, balance) as if it were transient.
+## Configuration
 
-## Activation preconditions
+### Routes
 
-- `AGENT_ZERO_API_KEY` (or the numbered `AGENT_ZERO_API_KEY_P0`-`P9` rotation keys) set.
-- A userland catalog file for the `agent-zero` route; otherwise zero providers register and only a
-  synthetic route (via `registerRoute`) can serve traffic.
+`braid.providers.routes` is an ordered array; array order is rotation order. Each entry names the
+provider id pi will expose, the environment variable prefix its keys load from, and optionally the
+model ids it serves and a non-billable status probe:
 
-## Environment variables
-
-```bash
-AGENT_ZERO_API_KEY=<your-agent-zero-gateway-key>
-# Optional: multiple gateway keys for rotation
-AGENT_ZERO_API_KEY_P0=<key-1>
-AGENT_ZERO_API_KEY_P1=<key-2>
+```json
+{
+  "braid": {
+    "providers": {
+      "routes": [
+        {
+          "provider": "venice-direct",
+          "keys": "VENICE_API_KEY",
+          "probe": {
+            "url": "https://api.venice.ai/api/v1/api_keys/rate_limits",
+            "balanceFloorUsd": 1
+          }
+        }
+      ]
+    }
+  }
+}
 ```
 
-Env vars are resolved at request time by the key ring (`auth.apiKey.resolve`).
-`warnBelowKeyCount` (default 4) surfaces keys-remaining on each rotation so
-you know when to top up.
+A route is recognized by the model ids it declares, so a route you did not configure is never
+routed to. With no `routes` key, the two routes this build carries are used in order: the gateway
+route, whose model catalog comes from a userland file that this package does not ship, and
+`venice-direct`, which serves Venice's own API. Without that catalog the gateway route does not
+register, and only routes you configure serve traffic. A route's `probe` declares a status
+endpoint that is checked with the route's own key, at registration and on a bounded interval
+afterwards; the check is never a billable call, and its result steers routing only while it is
+fresher than `braid.providers.probeFreshnessMs`.
 
-## The two routes
+### Settings
 
-When the userland catalog exists, two providers register:
+| Key                                  | Default               | Effect                                                                            |
+| ------------------------------------ | --------------------- | --------------------------------------------------------------------------------- |
+| `braid.providers.routes`             | the pair above        | Ordered route table; a configured array replaces the default pair entirely        |
+| `braid.providers.probeFreshnessMs`   | `900000` (15 minutes) | How long a recorded probe or death may steer routing; `0` disables probe steering |
+| `braid.context.presendGuard.enabled` | `true`                | The 90% request guard described above                                             |
 
-| Provider id     | Serves             | Via                                                 | Key prefix           |
-| --------------- | ------------------ | --------------------------------------------------- | -------------------- |
-| `agent-zero`    | Venice's models    | agent-zero gateway (`https://llm.agent-zero.ai/v1`) | `AGENT_ZERO_API_KEY` |
-| `venice-direct` | The same model ids | Venice's own API (`https://api.venice.ai/api/v1`)   | `VENICE_API_KEY`     |
+### Environment
 
-`agent-zero` is the primary. On any registered route's key-ring death (a quota/auth/403 error that leaves its ring with zero usable keys), the **rotation engine** (ring-lifecycle.ts) walks the ordered route table and engages the first route that is not the dead route, has a usable key, and can serve the dead turn's model id - directly (a shared id) or through its `models` map. The order is `braid.providers.routes` (`[{ provider, keys, modelIds?, models?, venicePayload? }]`), array order being the rotation order; with no `routes` key the default pair is `agent-zero` then `venice-direct`, so an `agent-zero` death still falls over to Venice's own API. The table is the only attribution source: a route is recognized by the model ids it declares (`modelIds` plus the provider ids its `models` map resolves to) and takes the Venice payload tweak only when it sets `venicePayload` - off by default for a configured route, on for the default pair. A route the owner did not configure is neither routed to nor shaped. Exactly one rotation per episode: the engage swaps the session model for the retrying turn and emits one owner-visible whisper. A bounded fail-back probe (`FAILBACK_PROBE_INTERVAL_MS`, 10 min) re-checks the dead route at most once per interval at `turn_end` boundaries; when it recovers the session fails back automatically (one fail-back whisper) and the engage re-arms. State is in-memory per extension load; `session_start` resets the engine.
+`AGENT_ZERO_API_KEY` for the gateway route, `VENICE_API_KEY` for the direct route; numbered
+suffixes (`_P0` through `_P9`) add rotation keys, and the bare variable is used when no numbered
+key exists.
 
-## Health-routed entries (`auto`)
+## Limits
 
-A route can carry a virtual entry selectable as `<provider>/auto`: one model
-that answers each request with the first healthy route in the configured order,
-so a per-spawn route decision becomes a per-request one. The auto route spans
-several providers, so its entry lives under this package's own `braid`
-namespace: `braid/auto` exists whenever this build carries the agent-zero route;
-`opencode-go/auto` whenever the owner's route table names that provider -
-`opencode-go` sits ahead of the gateway in the live table, so a session that
-starts there leaves by the health walk instead of by hand. The entry declares
-no context window, max tokens or input types (pi reads those from the physical
-model that answered) and never dispatches its own id: a request with no
-previous physical model resolves its base id from the route table, or from the
-configured `defaultModel`, and the thinking level is resolved against the
-target model's own map. A provider that already ships a physical `auto` skips
-its own entry with one diagnostic, so a virtual entry can never shadow a real
-model.
+- It is not a proxy or a gateway you can point other tools at: it plugs into pi's model registry.
+- A route you did not configure is never routed to.
+- Fatal account errors (quota, billing, balance) stop the turn rather than rotate.
+- Ring and route state live directly under `~/.pi/agent/`, not under `braid/`:
+  `.key-ring-state-<provider>.json` and `.provider-route-state.json`. Key material is never
+  written, only key hashes.
 
-## Route probes and cross-session state
-
-A route may declare a non-billable status capability in the ordered route table:
-
-```json
-{
-  "provider": "venice-direct",
-  "keys": "VENICE_API_KEY",
-  "probe": {
-    "url": "https://api.venice.ai/api/v1/api_keys/rate_limits",
-    "balanceFloorUsd": 1
-  }
-}
-```
+## For maintainers
 
-When present, one probe runs at extension registration - a plain GET at the
-declared URL with the route's own key as a bearer token, never an inference
-call - and the outcome is recorded per route in
-`~/.pi/agent/.provider-route-state.json`: the last probe, the last recorded
-death (its key identity as a hash, never the key), the fail-back target and the
-warmed model ids. A later session reads that file instead of re-learning it.
-The probe never throws, never rotates a key and never starts a billable call;
-the write is lock- and CAS-guarded exactly like the key-ring state, because
-every pi process on the host shares the file.
-
-A recorded outcome carries the endpoint's own remaining figure as
-`remainingUsd` (Venice's `balances.USD`, OpenRouter's `limit_remaining`), so no
-consumer has to derive remaining by subtracting a monthly figure from a cap. A
-route whose status document reports a spendable USD balance is classified
-against `probe.balanceFloorUsd` (default `1`, owner-configurable per route):
-above the floor is `ok`, at or below it but above zero is `degraded`, and zero
-or below is `unavailable`. A route whose status endpoint answers 200 while the
-account has no spendable balance therefore no longer reads as healthy.
-
-Two rules keep the layers honest:
-
-- **The runner is provider-agnostic.** Which provider ids exist and what their
-  status responses look like lives in ONE adapter table in `probe.ts`. A
-  provider absent from it is reported unavailable rather than guessed at.
-- **The state store interprets nothing.** It writes down an opaque record per
-  route and reads it back; the probe vocabulary and the death classes belong to
-  the layers that produce them.
-
-A route without a `probe` descriptor is never probed. Absent probes, resolution
-and rotation are unchanged.
-
-## Ring and route health
-
-`ring-health.ts` is the read side of those two files: it summarizes them for a
-human or a consumer script without writing, locking or interpreting anything, so
-"which keys are in backoff, and what did each route last look like" needs no
-knowledge of either store's write protocol.
-
-- `ringHealth(providerId, { stateDir?, file? })` reads one ring file
-  (`~/.pi/agent/.key-ring-state-<provider>.json`, or an explicit path).
-  `{ provider, present: false }` means no file, or one this reader cannot
-  trust; otherwise it carries `rev`, `savedAt`, `activeIndex` and one entry per
-  key: `{ exhausted, exhaustedAt, retryCount, exhaustedBy, keyHash }`.
-- `routeHealth({ stateDir?, providers?, routeState? })` reports every route it
-  can see - the ids the caller names, the routes the route store already
-  carries, and the providers with a ring file - as
-  `{ provider, ring, lastProbe, deathClass, deathAt, failback, warmModels }`.
-  Facts the route store has not recorded come back as `null`, `0` or `[]`.
-
-Four rules hold the reader to its layer:
-
-- **Read-only.** No write, no lock, no migration. The stores own the one write
-  protocol; a reader that could write would be a second one.
-- **Hash-only.** The ring file holds `hash`, never the key, and the reader
-  copies named fields instead of forwarding the document - so a value the ring
-  never wrote cannot leak through here.
-- **Provider-blind.** Every provider id is an argument or is discovered from
-  the files; none is hardcoded, so a configured route table needs no code
-  change here.
-- **Tolerant, never throwing.** An absent file is the normal empty state and
-  stays silent; a malformed, partial or wrong-version file is the same
-  `present: false` plus exactly one diagnostic.
-
-The reader takes its file paths from its caller or derives them from the
-provider id; it writes no state file of its own and reads the route document
-through `route-state.ts`'s reader. Nothing in `packages/core` imports it: an
-external consumer imports the package, never the other way round.
-
-`formatRingHealth(routes, freshness)` and `summarizeRouteHealth(routes, freshness)`
-turn a report into the `ring_health` tool's text and its `details` payload.
-
-- `braid.providers.probeFreshnessMs` (default `900000` ms, 15 minutes) controls
-  how long a recorded unavailable probe or shape-death result can steer routing.
-  `0` or less disables probe steering. The ring-health renderers receive the
-  same resolved window and mark a death `(expired)` when the router's
-  `deathInForce` predicate would no longer act on it, its timestamp is absent,
-  or the window is off.
-
-## Disabling the provider
-
-The registration lives in `index.ts` behind the venice-catalog seam: remove
-(or chmod) the userland catalog file and no provider is registered. All
-ring-lifecycle logic stays in `ring-lifecycle.ts`, unit-testable without
-loading pi-ai.
-
-## Package layout
+The route table internals, the probe adapter table, the state store protocol and the failure
+classes are in [AGENTS.md](https://github.com/kifirkin/pi-braid/blob/main/packages/providers/AGENTS.md),
+which the tarball does not carry.
 
-```
-providers/
-├── index.ts           # registers the configured routes + wires key-ring/rotation events
-├── venice-catalog.ts  # userland catalog seam (the models file, resolved at runtime)
-├── venice-direct.ts   # the venice-direct route module: constants, key ring, model configs
-├── key-ring.ts        # multi-key rotation + backoff + persistence
-├── ring-lifecycle.ts  # per-request ring attribution, exhaust/self-heal, route-order rotation engine
-├── probe.ts           # provider-agnostic probe runner + the adapter table
-├── route-state.ts     # cross-session route state, lock + CAS writes
-├── ring-health.ts     # read-only health surface over the key-ring + route state files
-├── log.ts             # notify-sink routing (no console.*)
-└── test/              # fixture-driven behavior pins
-```
+## License
 
-> The registered id was `venice`, then `a0`, now `agent-zero` - each rename
-> follows the gateway the provider serves models through. `venice-direct`, the
-> `VENICE_API_KEY` family and `venice-models.json` are unchanged; the gateway's
-> own credential namespace moved from `A0_VENICE_API_KEY` to `AGENT_ZERO_API_KEY`
-> with the last rename.
+[MIT](LICENSE)

package/build-info.json

@@ -1,9 +1,9 @@
 {
   "name": "pi-braid-providers",
-  "version": "1.0.6",
-  "sha": "752d2e6e9b45037a8ebcc17f3d6f90c905b2c71c",
-  "shaShort": "752d2e6",
+  "version": "1.0.7",
+  "sha": "3a3de965131cd125b58a807b064a43d37b7f466f",
+  "shaShort": "3a3de965",
   "branch": "detached",
   "dirty": false,
-  "packedAt": "2026-10-19T11:29:20.919Z"
+  "packedAt": "2026-11-11T22:45:21.903Z"
 }

package/index.ts

@@ -1,8 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createProvider } from "@earendil-works/pi-ai";
-// `Type` ships with pi-ai's own typebox re-export, so the tool schema adds no
-// dependency to a package that resolves only @earendil-works/* from npm.
-import { Type } from "@earendil-works/pi-ai";
+// pi-ai re-exported typebox's `Type` until 1.5.0 and no longer does, so the
+// builder comes from the package that owns it, at the peer floor the sibling
+// packages declare.
+import { Type } from "typebox";
 import {
   completeSimple,
   openAICompletionsApi,
@@ -48,7 +49,11 @@ import {
 import { loadVeniceCatalog } from "./venice-catalog.js";
 import type { ChatModelConfig } from "./venice-catalog.js";
 import { keyRingAuth, withKeyRingAuth } from "./ring-provider";
-import { shrinkDoomedPayload, isPresendGuardEnabled } from "./presend-guard";
+import {
+  buildContextWindowIndex,
+  readPresendPolicy,
+  shrinkDoomedPayload,
+} from "./presend-guard";
 import { probeRoute } from "./probe.js";
 import {
   formatRingHealth,
@@ -850,25 +855,29 @@ export default async function (pi: ExtensionAPI) {
   }
 
   // Model-id → catalog context window for the pre-send guard.
-  // Built once at factory load from the catalog this package owns (venice-catalog.ts).
-  const presendContextWindows = new Map<string, number>();
-  for (const m of veniceCatalog?.models ?? []) {
-    if (typeof m.contextWindow === "number" && m.contextWindow > 0) {
-      presendContextWindows.set(m.id, m.contextWindow);
-    }
-  }
+  // Built once at factory load from the catalog this package owns
+  // (venice-catalog.ts): exact ids, plus the normalized spelling a route may
+  // use for the same model. A dot-form request id (the route sends
+  // `deepseek-v4.1-flash`, the catalog spells `deepseek-v4-1-flash`) would
+  // otherwise resolve to no window and the guard would silently no-op.
+  const presendWindows = buildContextWindowIndex(veniceCatalog?.models ?? []);
 
   pi.on("before_provider_request", async (event: any) => {
     // Ring-lifecycle first (WAF/key shaping), then the pre-send guard on
-    // the (possibly reshaped) payload. The guard no-ops unless the payload is
-    // DOOMED for a KNOWN model; its returned payload (when present) replaces
-    // the outgoing body per pi-core's emitBeforeProviderRequest semantics.
+    // the (possibly reshaped) payload. The token arm no-ops unless the payload
+    // is DOOMED for a KNOWN model; the byte arm no-ops unless the owner
+    // declared a cap (a request above the report threshold still writes one
+    // line). Its returned payload (when present) replaces the outgoing body
+    // per pi-core's emitBeforeProviderRequest semantics.
     const shaped = handleBeforeProviderRequest(event.payload);
     const outgoing = shaped ?? event.payload;
     try {
-      if (!isPresendGuardEnabled()) return shaped;
+      const policy = readPresendPolicy();
+      if (!policy.enabled) return shaped;
       const guard = shrinkDoomedPayload(outgoing, {
-        resolveContextWindow: (modelId) => presendContextWindows.get(modelId),
+        resolveContextWindow: (modelId) => presendWindows.resolve(modelId),
+        maxRequestBytes: policy.maxRequestBytes,
+        reportBytesAbove: policy.reportBytesAbove,
       });
       return guard?.payload ?? shaped;
     } catch {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-braid-providers",
-  "version": "1.0.6",
-  "description": "LLM provider for pi-coding-agent: Venice models via the agent-zero gateway, with a multi-key ring",
+  "version": "1.0.7",
+  "description": "Key rotation, provider failover, and route health for the pi coding agent, so one dead key or provider does not end the session.",
   "type": "module",
   "files": [
     "*.ts",
@@ -14,12 +14,12 @@
   },
   "keywords": [
     "pi-package",
-    "pi",
+    "braid",
     "pi-coding-agent",
-    "extension",
-    "providers",
-    "llm",
-    "venice.ai"
+    "llm-provider",
+    "api-key-rotation",
+    "failover",
+    "venice"
   ],
   "pi": {
     "extensions": [
@@ -38,11 +38,12 @@
   },
   "devDependencies": {
     "typescript": "6.0.2",
-    "@earendil-works/pi-ai": "^1.2.0"
+    "@earendil-works/pi-ai": "^1.5.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^1.2.0",
-    "@earendil-works/pi-coding-agent": "^1.2.0"
+    "@earendil-works/pi-ai": "^1.5.0",
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "typebox": "^1.1.38"
   },
   "author": "kifirkin",
   "license": "MIT",
@@ -56,6 +57,6 @@
   },
   "homepage": "https://github.com/kifirkin/pi-braid/tree/main/packages/providers",
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24.0.0"
   }
 }