pi-typesafe-router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-typesafe-router contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# pi-typesafe-router
+
+An opt-in [Pi](https://github.com/earendil-works/pi) extension that asks Jev to classify a task, then selects a generation model from your ordered mappings.
+
+Classification supports **TypeSafe direct, Cloudflare Workers AI, and Vercel AI Gateway**. Model fallback happens only before generation. A failed task is never automatically replayed by this extension.
+
+## Setup
+
+Requires Node.js 22.19+ and Pi 0.85.1. This is an unpublished local implementation; no live backend credentials have been tested.
+
+From this checkout, install dependencies and load the extension for one session:
+
+```sh
+npm ci
+pi -e ./src/index.ts
+```
+
+Do not enable this alongside another automatic router. Choose a real provider/model in Pi first, then run:
+
+```text
+/typesafe-router setup typesafe
+```
+
+This creates `~/.pi/agent/typesafe-router.json`, initially **off**, using your selected model for all three routes. It never overwrites a file. Edit the mappings, set `TYPESAFE_API_KEY` in the environment that launches Pi, and restart Pi. Never put the key in your prompt or config file.
+
+For a persistent local installation, use `pi install /absolute/path/to/pi-typesafe-router`. Once published, the equivalent will be `pi install npm:pi-typesafe-router`.
+
+## Usage
+
+Apply configuration and verify the classifier and generation targets, then enable routing:
+
+```text
+/typesafe-router doctor
+/typesafe-router on
+```
+
+`doctor` checks local eligibility, sends one synthetic classifier request, and probes each distinct configured provider/model with an isolated synthetic generation request. No actual conversation transcript or tools are sent. **These requests may incur charges**, even while routing is off; there is no strict monetary cap. Explicit invocation also works headless with `allowHeadless: false`. Doctor never changes the selected model or runs or replays your task.
+
+Doctor must complete successfully, including the classifier check, with at least one locally eligible, successfully probed target in **each** of `quick`, `standard`, and `deep`. Until then, `on`, `shadow`, and automatic input are blocked; `off` and manual Pi use remain available. Subsequent preflight skips failed targets, even the first configured target, and preserves the configured order of remaining successful candidates. A probe is a health snapshot, not a guarantee that a later task will succeed.
+
+Verification is session-only and never persisted. Restart or reload requires doctor again. Changes to routes, credential references, backend configuration, or model metadata—even under the same provider/model ID—invalidate verification. Each doctor refresh discards old proofs; cancellation or incomplete checks never partially unlock routing.
+
+`/typesafe-router` (or `status`) is read-only: it reports the applied configuration, runtime mode, current model, and on-disk differences without network calls. Reports include next steps only where relevant. Pi's built-in `/reload` loads updated extension code; it is not needed for configuration changes—use `/typesafe-router doctor` instead.
+
+Use `shadow` instead of `on` to classify without changing the model. **Shadow mode still transmits text and can incur charges.** `/typesafe-router off` stops classification. `/model` selection also turns automatic routing off. Session mode changes are recorded in that session. `doctor` reloads valid configuration while preserving the current session mode; it never enables routing that is off. Missing or invalid configuration disables routing.
+
+Escape, Ctrl+C, or `/typesafe-router off` cancels preflight and stops the original prompt. If Pi is already resolving generation credentials, cancellation waits for its non-cancellable model setter; verify the selected model before resubmitting. Prompts rejected or cancelled during preflight are not automatically queued or replayed.
+
+After a failed generation, use Pi's `/model` to choose a model, inspect completed tool effects, and manually continue when safe. The router never selects a fallback after generation or replays a task. Pi's own retry and compaction settings remain unchanged.
+
+## Configuration
+
+See the [configuration reference](docs/configuration.md) and examples for [TypeSafe](examples/typesafe.json), [Cloudflare](examples/cloudflare.json), and [Vercel](examples/vercel.json). Only the global file is read; `PI_CODING_AGENT_DIR` relocates it. Project-local configuration is intentionally ignored.
+
+| Backend               | Credential                                   | Model             |
+| --------------------- | -------------------------------------------- | ----------------- |
+| TypeSafe              | `TYPESAFE_API_KEY`                           | `jev-1.13.0`      |
+| Cloudflare Workers AI | `CLOUDFLARE_API_TOKEN`, account ID in config | `typesafe/jev`    |
+| Vercel AI Gateway     | `AI_GATEWAY_API_KEY`                         | `typesafe-ai/jev` |
+
+Backends are explicit; there is no cross-backend failover. Vercel uses the experimental AI SDK evaluation protocol, not a chat-completions endpoint. Missing confidence uses the conservative route; confidence is **not** the probability that the generation model will solve your task.
+
+## Project structure
+
+- `src/classifier.ts`: transport adapters and response validation.
+- `src/config.ts`, `context.ts`, `routing.ts`: schema, bounded text projection, and deterministic policy.
+- `src/index.ts`, `settings.ts`: Pi lifecycle, commands, cancellation, and global settings.
+- `tests/`: synthetic transport, policy, lifecycle, and real Pi SDK tests. No paid API calls.
+- `docs/`: [privacy](docs/privacy.md), [architecture and limits](docs/architecture.md), and [release checklist](docs/releasing.md).
+
+## Contributing
+
+Run `npm run fmt` to format with Oxfmt, and `npm run lint:fix` to apply safe Oxlint fixes. Run `npm run check` before proposing changes; it checks formatting, lint, TypeScript, and tests, and also runs in CI. Tests must remain offline and must not read real credentials. Use `npm run smoke:package` to check the packed extension in an isolated Pi installation. Public benchmark or performance claims require clarification of TypeSafe's terms first.
+
+## License
+
+[MIT](LICENSE). Third-party models, services, and dependencies retain their own terms.

package/docs/architecture.md

@@ -0,0 +1,59 @@
+# Routing before generation
+
+Jev classifies task demand. A local policy chooses eligible generation targets. Neither classifier output nor task text can supply a provider URL, invent a model target, or bypass the configured chains.
+
+```text
+idle user input
+  → current session doctor verification gate
+  → bounded text projection
+  → one explicitly selected classifier adapter
+  → validated quick / standard / deep / uncertain answer
+  → local confidence policy
+  → ordered candidate eligibility checks
+  → serialized Pi model selection
+  → original input continues once
+```
+
+`classify` normalizes three protocols. `chooseRoute` and `candidateChecks` are pure. `registerRouter` owns lifecycle and session-local state. This is not an LLM proxy and does not register a synthetic generation model.
+
+## Lifecycle contract
+
+The implementation targets Pi **0.85.1**. Its idle `input` hook runs before initial generation authentication and compaction. `before_agent_start` is too late for a router that must rescue a missing initial model/auth configuration. Selection happens once at the idle input boundary; streaming steering/follow-up and extension-generated input pass through without classification. Tool-loop selection is sticky by router policy, not by an immutable host guarantee.
+
+The extension returns `handled` when preflight must stop a prompt. Throwing would be unsafe: Pi catches input-hook exceptions and can continue generation. No path uses `sendUserMessage`, resends the original input, or chooses a new model after a generation error. Native Pi retry/overflow recovery is not disabled or replaced. Failure guidance waits for `agent_settled`, after native recovery finishes.
+
+Model selection requires a current successful doctor generation proof, then checks exact catalogue identity, configured auth presence, nonempty scoped-model restrictions, image support, and conservative context/output budgets. A setter returning false or throwing skips to the next candidate before generation. Failed doctor targets are skipped, even when first in a chain; remaining successful candidates keep their configured order. Catalogue eligibility alone does not prove remote credentials, quotas, availability, or task quality. A successful probe is only a health snapshot, not a guarantee of future generation. Context sizing uses Pi's `ctx.getContextUsage()` count, which incorporates provider-reported usage and Pi's trailing-message estimates. Unsent input uses Pi's exported `estimateTokens`; the router does not count serialized metadata or treat bytes as tokens. If Pi reports unknown usage immediately after compaction, the router skips only its context-size check and leaves compaction/accounting to Pi. If no usage API result is available, it sums Pi's message estimates. Counts are not exact candidate-specific tokenization; Pi's current accounting is the shared basis. Unknown post-input changes from templates, context hooks, tools, or other extensions cannot be predicted.
+
+## Cancellation and concurrency
+
+Each operation has an epoch and an AbortController. Classifier credentials and HTTP share a deadline. Late classification/credential results are ignored. Escape/Ctrl+C are intercepted during TUI preflight, and `/typesafe-router off` also invalidates the operation. Headless callers must use `off` during preflight; Pi's normal agent abort signal is not yet active there.
+
+Pi's `setModel()` is asynchronous and has **no cancellation argument**. A timeout race cannot prevent it from later changing the model. The router therefore awaits the actual setter, never starts another selection in parallel, and consumes the cancelled original input afterward. Concurrent input is rejected, even if routing was turned off while authentication was pending. Model selection may finish after cancellation; users must verify it before resubmitting. There is no unsafe rollback to a stale model.
+
+Session navigation is refused while preflight is active, cancelling the operation first. Shutdown/reload cancels and awaits its completion before allowing teardown. If a credential plugin never resolves its model-auth promise, selection and reload can remain blocked; restarting Pi is the recovery. This is an explicit limitation of the host setter, not something a timer can safely fix.
+
+## Failure and recovery
+
+Classification errors, timeouts, invalid responses, or missing keys use `defaultRoute`. Low/missing confidence and explicit uncertainty use `uncertainRoute`. Oversized, empty, and unexpanded slash input skip classification and use the conservative route. No eligible candidate consumes the prompt with an error instead of silently using a stale model. After the doctor gate passes, shadow mode records the proposed route but neither changes the model nor blocks generation for an empty candidate chain. Both on and shadow modes, including automatic input, are blocked without current doctor verification; off/manual Pi use remains available.
+
+After generation fails, guidance points to Pi's `/model`, inspection of completed tool effects, and manual continuation when safe. The router does not select a post-generation fallback or replay a task. Manual model selection disables routing. Do not run multiple routers: Pi does not provide exclusive model-selection ownership between extensions.
+
+## Diagnostics and configuration
+
+`/typesafe-router doctor` serializes with preflight and model selection. It applies valid configuration while retaining the current session's on/off/shadow mode; it never enables an off session. Missing or invalid configuration disables routing. Every refresh invalidates old proofs before checking anything. Readiness requires a completed, successful doctor run: the classifier check must succeed and every quick/standard/deep route must contain at least one locally eligible target with a successful generation probe. Cancellation or incomplete work cannot publish partial readiness.
+
+Doctor checks local eligibility, then runs the synthetic classifier request and one isolated synthetic generation request per distinct configured provider/model concurrently, deduplicated across routes. A shared progress counter counts completed checks (including failures), while the final report preserves configured route order. TUI progress updates one widget above the editor, independent of the footer and routing mode, and clears on completion, failure, or cancellation. Other interfaces receive textual progress notifications. Cancelling doctor aborts the whole batch; partial results cannot grant verification. Generation probes use Pi's `modelRegistry.complete` with the actual credential providers, including OAuth, custom headers, and configured endpoints. Credentials may refresh. Probes contain no actual conversation transcript and use `tools: []`, `maxTokens: 128` where supported, and `maxRetries: 0`. `generationProbeTimeoutMs` bounds each model probe (default 15000 ms), separately from the classifier's `timeoutMs`. These limits are not a strict monetary cap. Explicit invocation authorizes potentially billable diagnostics even while off or headless with `allowHeadless: false`. Doctor never calls the generation model setter, changes the selected model, or runs or replays the original task.
+
+Generation proofs and readiness live only in memory, not session records or config. Restart/reload requires doctor again. The verification identity covers routes, credential references, backend configuration, and model metadata, so changes under the same provider/model IDs still invalidate it. Native auth status and provider references contribute to an in-memory hash; no secrets are persisted. A changed identity requires a fresh successful doctor run, not reuse of old proofs. Effective Pi provider object identity covers native registrations and applied `models.json` changes; a provider-registry refresh can conservatively require doctor again. Classifier-only Pi credential providers are included. Before enabling or routing, every route must still have an eligible verified candidate, including current scope and context limits.
+
+Probe cancellation releases doctor promptly and checks the abort signal again after Pi resolves authentication, before invoking provider transport. A credential plugin that ignores cancellation may still finish authentication or refresh credentials later; its late result cannot start the probe transport or publish verification.
+
+Reports reflect runtime, config path/application result, actual mode, current model, backend/model, credential source, local eligibility, classifier result/latency, generation probe outcomes, and readiness, with conditional next steps. Cancellation and incomplete work are explicit; shutdown suppresses stale output. Off/Escape cancels pending work but cannot release a pending model setter's lock early.
+
+`status`, also the default subcommand, is read-only and makes no network calls. It reports applied configuration and on-disk differences (or inability to check), current activity/model/mode, and a historical last decision. It does not apply configuration or renew verification. Classifier success alone does not prove generation-provider health; successful generation probes do not guarantee later availability, quota, or task quality.
+
+## Verification boundaries
+
+Offline tests validate schema/policy, request serialization, normalized responses, cancellation, no replay, and real SDK extension loading. Packed-install smoke tests exercise Pi's actual extension loader using an isolated profile and installed production dependencies. Synthetic transports do not establish live service contracts or quality. In particular, Gateway confidence metadata needs a live account check; absent confidence stays conservative.
+
+Before claiming savings or quality, evaluate privately on representative coding tasks with pinned versions and per-model success/cost/latency outcomes. Classifier confidence measures concentration, not downstream success probability. TypeSafe's public benchmarking restrictions require permission/clarification before publishing results.

package/docs/configuration.md

@@ -0,0 +1,135 @@
+# Configure task routing
+
+The router reads only `typesafe-router.json` under Pi's agent directory (normally `~/.pi/agent`). `PI_CODING_AGENT_DIR` changes that directory. It does not read project files or discover credentials in a repository.
+
+## Map classes to model chains
+
+Copy an [example](../examples/typesafe.json), or run `/typesafe-router setup typesafe` in Pi. Replace every example target with exact IDs from Pi's model catalogue. A provider ID cannot contain a slash; a model ID can.
+
+```json
+{
+  "version": 1,
+  "mode": "off",
+  "allowHeadless": false,
+  "backend": {
+    "type": "typesafe",
+    "model": "jev-1.13.0",
+    "auth": { "source": "env", "variable": "TYPESAFE_API_KEY" }
+  },
+  "timeoutMs": 1500,
+  "generationProbeTimeoutMs": 15000,
+  "minConfidence": 0.8,
+  "maxContextChars": 12000,
+  "historyMessages": 4,
+  "outputReserveTokens": 8192,
+  "defaultRoute": "deep",
+  "uncertainRoute": "deep",
+  "routes": {
+    "quick": [{ "provider": "your-provider", "model": "your-fast-model" }],
+    "standard": [{ "provider": "your-provider", "model": "your-balanced-model" }],
+    "deep": [
+      { "provider": "your-provider", "model": "your-strong-model" },
+      { "provider": "another-provider", "model": "your-backup-model" }
+    ]
+  }
+}
+```
+
+Each chain contains one to eight distinct targets. Order is authoritative: targets without a current successful doctor generation proof, or failing local eligibility, are skipped; selection stops at the first successful `pi.setModel`. A failed first target does not prevent selection of a later successful one. Remaining successful candidates keep their configured order. Doctor deduplicates probes across chains by exact provider/model identity. There is no random sampling, cost lookup, or per-task remote health probe. `auto`, `smart-router`, and `typesafe-router` virtual providers are rejected.
+
+Unknown fields, duplicate targets, invalid types, and out-of-range settings reject the entire file. Missing, unreadable, or invalid configuration disables routing. Repair the file and run `/typesafe-router doctor` to apply it; explicitly enable routing afterward if desired.
+
+| Setting                    | Default | Accepted values                                                                  |
+| -------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `version`                  | `1`     | `1`                                                                              |
+| `mode`                     | `off`   | `off`, `shadow`, `auto`                                                          |
+| `allowHeadless`            | `false` | Boolean; explicitly permit automatic routing outside TUI                         |
+| `timeoutMs`                | `1500`  | Integer, 100–30000; credentials plus classification                              |
+| `generationProbeTimeoutMs` | `15000` | Integer, 100–60000; timeout for each model’s doctor generation probe             |
+| `minConfidence`            | `0.8`   | Number, 0–1                                                                      |
+| `maxContextChars`          | `12000` | Integer, 256–32000; combined request and history text                            |
+| `historyMessages`          | `4`     | Integer, 0–20                                                                    |
+| `outputReserveTokens`      | `8192`  | Integer, 256–131072; capped at candidate's maximum output                        |
+| `defaultRoute`             | `deep`  | `quick`, `standard`, `deep`; classifier failure/unavailability                   |
+| `uncertainRoute`           | `deep`  | Same values; uncertainty, absent/low confidence, oversized or unexpanded request |
+
+`generationProbeTimeoutMs` is a top-level setting applied separately to each distinct model probe, not a total doctor deadline. Probes request `maxTokens: 128` where supported and `maxRetries: 0`; these are fixed probe options, not configuration fields. They do not establish a strict monetary cap.
+
+Character limits use JavaScript string length. The current request is never truncated. If it cannot fit, classification is skipped and the conservative route is used. Only contiguous newest fitting conversation text is included. Set `historyMessages: 0` for request-only classification.
+
+## Select one classification backend
+
+### TypeSafe direct
+
+```json
+{
+  "type": "typesafe",
+  "model": "jev-1.13.0",
+  "auth": { "source": "env", "variable": "TYPESAFE_API_KEY" }
+}
+```
+
+Requests go to `https://api.typesafe.ai/v1/systemone`. The versioned model ID is the default; explicitly configured aliases may change behavior over time. No automatic retries occur.
+
+### Cloudflare Workers AI
+
+```json
+{
+  "type": "cloudflare",
+  "accountId": "0123456789abcdef0123456789abcdef",
+  "model": "typesafe/jev",
+  "auth": { "source": "env", "variable": "CLOUDFLARE_API_TOKEN" }
+}
+```
+
+Use your own 32-hex-character account ID and a token authorized for Workers AI. The fixed account-scoped REST endpoint is `https://api.cloudflare.com/client/v4/accounts/{accountId}/ai/run`. This is Workers AI evaluation, not arbitrary Cloudflare AI Gateway chat compatibility.
+
+### Vercel AI Gateway
+
+```json
+{
+  "type": "vercel",
+  "model": "typesafe-ai/jev",
+  "zeroDataRetention": true,
+  "auth": { "source": "env", "variable": "AI_GATEWAY_API_KEY" }
+}
+```
+
+This uses AI SDK `experimental_evaluate`, pinned to SDK `7.0.105`, and the Gateway evaluation model interface. No OpenAI-compatible chat endpoint is involved. `zeroDataRetention` defaults to true; the provider may reject unsupported retention options instead of silently weakening them.
+
+Confidence is read from the per-question `providerMetadata.typesafe.confidence.task_class` map. Public documentation identifies the enclosing confidence metadata but does not demonstrate its full shape. Missing confidence remains missing and selects `uncertainRoute`; malformed confidence fails validation and selects `defaultRoute`. Run `/typesafe-router doctor` with your account before relying on this experimental integration. No live service parity is claimed.
+
+### Optional Pi-managed credentials
+
+All backends also accept `{"source":"pi","provider":"your-provider-id"}` as `auth`. This calls Pi 0.85.1's `getProviderAuth` at request time. It is opt-in, never an implicit fallback from a missing environment key. Only the resolved API key is forwarded; custom auth headers are not. A provider credential does not establish that the target evaluation endpoint accepts it. Verify audience, permissions, and backend compatibility yourself. Environment credentials are the recommended initial setup.
+
+## Commands
+
+| Command                                | Effect                                                                                                     |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `setup [typesafe\|cloudflare\|vercel]` | Interactive creation of an off-mode config; never overwrites                                               |
+| `doctor`                               | Apply config, test the classifier and distinct generation targets, and refresh session verification        |
+| `status` (default)                     | Read-only report of applied config, runtime mode, current model/activity, and disk differences; no network |
+| `on` / `shadow` / `off`                | Change session mode; on/shadow require successful doctor; off cancels preflight                            |
+
+Prefix each with `/typesafe-router`. With no subcommand, the command shows status.
+
+`doctor` reloads valid configuration while preserving the current session's on/off/shadow mode, rather than adopting the file's mode. It never enables an off session. Missing or invalid configuration disables routing. It never changes the selected generation model or runs or replays a user task.
+
+Doctor automatically sends one synthetic classifier request and one isolated synthetic generation request per distinct configured provider/model, without confirmation. No actual conversation transcript is sent, and generation probes have `tools: []`. **These requests may incur charges**; there is no strict monetary cap. Explicit invocation authorizes them even with routing off or in print/RPC mode with `allowHeadless: false`. Automatic routing in those modes still requires `allowHeadless: true` and an enabled mode. Headless diagnostics go to stderr, not the assistant's output.
+
+Generation probes run through Pi's `modelRegistry.complete`, using the actual configured credential providers, including OAuth, custom headers, and custom endpoints. Credentials may refresh during diagnostics. This differs from the classifier's optional API-key-only Pi credential reuse described above.
+
+Readiness requires doctor to complete successfully, including the classifier check, and at least one locally eligible, successfully probed target in each of `quick`, `standard`, and `deep`. Not every target must pass. Failed targets are skipped in subsequent preflight, preserving the configured order of remaining successful candidates. Until ready, `on`, `shadow`, and automatic input are blocked; `off` and manual Pi use remain available. A configured startup mode does not bypass verification.
+
+Verification is session-only and never persisted. Restart/reload requires doctor again. Changes to routes, credential references, backend configuration, or model metadata invalidate it even if provider/model IDs stay the same. Native auth status and provider references contribute to an in-memory identity hash; no secrets are persisted. Each doctor refresh invalidates previous proofs. Cancellation or incomplete checks never partially unlock routing; run doctor again to recover.
+
+Doctor reports runtime, config path/application result, actual session mode, current generation model, backend/model, credential source, local eligibility, classifier result/latency, generation probe outcomes, and readiness. Reports give conditional next steps for the actual state. Local eligibility alone does not prove generation-provider health; a successful probe is a health snapshot, not a guarantee of later availability, quota, or task quality.
+
+Status reports the applied configuration, not merely the file on disk. It identifies disk differences or inability to check the file, and labels the last routing decision as historical. It neither applies changes nor tests services. Use doctor to apply and test changes.
+
+Escape/Ctrl+C in the TUI or `off` cancels preflight. While Pi's non-cancellable model setter is pending, the selection lock remains held; verify the selected model before resubmitting. Doctor is serialized with preflight/model selection.
+
+After generation fails, use `/model`, inspect completed tool effects, and manually continue when safe. The router performs no post-generation fallback and never replays a task.
+
+Manual `/model` selection turns routing off. Ordinary tool loops and queued steering/follow-up messages do not reroute. Session-tree navigation turns routing off. Active preflight blocks concurrent submissions and session navigation; after cancellation settles, repeat the desired submission/navigation yourself.

package/docs/privacy.md

@@ -0,0 +1,35 @@
+# What leaves your machine
+
+Enabling `auto` or `shadow` sends the current request and bounded recent user/assistant text to the configured classification backend. That text can contain private code, credentials, or personal data. **This extension is not a secret scanner or redaction system.** Do not enable it for material you cannot share with that backend.
+
+The default projection excludes system prompts, raw tool calls/results, reasoning blocks, image bytes, attachments, compaction summaries, and arbitrary files. If an assistant quotes a tool result or secret in ordinary text, that text can still be included. Slash-command/template input is not classified before expansion; the conservative route is used instead. There is no background classification while the router is off.
+
+## Explicit diagnostics
+
+`/typesafe-router doctor` applies valid configuration, checks local eligibility, and automatically sends one synthetic classifier request plus one isolated synthetic generation request to each distinct configured provider/model. It sends no actual conversation transcript, uses no tools (`tools: []`), asks for no confirmation, and **may incur charges**. Generation probes request `maxTokens: 128` where supported and `maxRetries: 0`, with a per-model `generationProbeTimeoutMs` deadline (default 15000 ms). These bounds are not a strict monetary cap.
+
+Invoking doctor explicitly authorizes these requests even while routing is off or headless with `allowHeadless: false`; that setting still gates automatic routing. Doctor preserves the current session mode and never enables an off session. Missing or invalid configuration disables routing. Doctor never changes the selected model or runs or replays a user task. Isolated synthetic generation probes are not retries of the actual task.
+
+Doctor must complete successfully, including the classifier check, and establish a locally eligible, successful generation candidate for each route before `on`, `shadow`, or automatic input is allowed. Off/manual Pi use remains available. Verification is session-only: restart/reload and identity changes require doctor again. Refresh discards old proofs; cancellation never partially unlocks routing.
+
+`/typesafe-router status` (also the default) is read-only and makes no network calls. It reports applied configuration, runtime mode/current model, and on-disk differences. Local eligibility is not remote generation verification, and successful probes are only health snapshots, not future guarantees.
+
+## Recipients and retention
+
+- Direct: TypeSafe's API.
+- Cloudflare: your account's Workers AI endpoint and its upstream service arrangement.
+- Vercel: AI Gateway and its upstream service arrangement. The request explicitly enables `zeroDataRetention` by default.
+
+The router never silently changes classification backends, follows HTTP redirects, or retries classification. A failed classifier uses a local configured generation route instead. Generation content goes to the model provider selected in Pi, under that provider's normal settings. Doctor also sends synthetic probe content to every distinct configured generation target through Pi's `modelRegistry.complete`, including custom endpoints and their normal provider arrangements.
+
+No-training promises do not establish zero data retention. TypeSafe's enterprise ZDR offering, gateway logging, account controls, and contract terms need separate review. The extension cannot verify a service's retention behavior. Review [TypeSafe's terms](https://typesafe.ai/legal/mca), [Cloudflare's model documentation](https://developers.cloudflare.com/ai/models/typesafe/jev/), and [Vercel's evaluation documentation](https://vercel.com/docs/ai-gateway/modalities/evaluation) before sharing sensitive content.
+
+## Local data and credentials
+
+Configuration is global and contains credential references, not keys. Setup creates it with mode `0600` where supported. Existing files and symlinks are never overwritten. Credentials are resolved at request time and are not placed in session records. For classification, Pi-managed credential reuse is explicit and forwards only an API key, not provider-specific headers. Generation probes instead use Pi's actual credential providers, including OAuth and custom headers. Credentials may refresh during doctor, subject to Pi's normal credential storage behavior.
+
+Generation proofs and readiness are held only in memory; the router never persists them. The verification identity covers routes, credential references, backend configuration, and model metadata, including changes under unchanged provider/model IDs. Native auth status and provider references contribute to an in-memory hash. No secrets are persisted by the router for verification.
+
+Session custom entries contain route/model IDs, classifier labels/probabilities/confidence, normalized usage, elapsed time, safe failure reasons, and skipped candidates. They do not contain request text, raw responses, HTTP error bodies, or API keys. Pi itself already records ordinary conversation content independently of this extension. There is no extension telemetry or external analytics.
+
+Diagnostics report configuration errors without printing Zod values or filesystem error bodies. Model IDs and config paths are shown locally; do not use secrets as identifiers. Gateway/provider warnings are suppressed rather than printed verbatim.

package/docs/releasing.md

@@ -0,0 +1,26 @@
+# Release checklist
+
+Nothing in this repository publishes automatically. The package name was available during research, but is not reserved. There is no configured remote or maintainer identity yet.
+
+## Before the first release
+
+1. Confirm ownership of the npm name and choose the public Git repository. Add accurate `repository`, `homepage`, and `bugs` metadata to `package.json`.
+2. Confirm the MIT license choice and maintainer identity. Review the public artifact list; research, local paths, tests, and development scripts are not shipped.
+3. Run `npm ci`, `npm run check`, and `npm run smoke:package` on the supported Node/Pi versions. Inspect `npm pack --dry-run`.
+4. With explicit approval for network charges, run `/typesafe-router doctor` for each backend and configured generation target set with least-privilege credentials. Doctor preserves session mode and sends a synthetic classifier request plus one isolated generation probe per distinct provider/model, without confirmation, actual conversation transcript, or tools. It may incur charges even while off or headless with `allowHeadless: false`; token/deadline limits are not a strict monetary cap. Confirm response shape, confidence extraction, permissions, and cancellation. Do not capture keys or raw private state in fixtures. Check the following:
+   - Probes use Pi's `modelRegistry.complete` and actual credential providers, including OAuth refresh, custom headers, and custom endpoints. Options are `tools: []`, `maxTokens: 128` where supported, and `maxRetries: 0`. The top-level `generationProbeTimeoutMs` defaults to 15000 and accepts only integers from 100 through 60000, applied per model.
+   - Readiness requires completed doctor success, including the classifier, and at least one locally eligible, successfully probed candidate in every quick/standard/deep route. Failed targets, including the first configured target, are skipped during later preflight; successful targets retain their configured order.
+   - `on`, `shadow`, and automatic input are blocked without readiness; off/manual Pi use remains available. Doctor does not change the selected model or replay a user task.
+   - Proofs are session-only and never persisted. Restart/reload requires doctor again. Route, credential-reference, backend, and model-metadata changes invalidate verification even under unchanged provider/model IDs. Native auth status/provider references contribute to an in-memory hash without persisting secrets.
+   - Refresh invalidates old proofs, and cancellation or incomplete work never partially unlocks routing. Treat successful probes as health snapshots, not guarantees of future generation success.
+5. Privately evaluate representative tasks. Seek clarification of TypeSafe MCA §2.3(f) before public benchmarks, performance numbers, or comparative claims.
+6. Review privacy disclosures and experimental Vercel limitations. Choose the package version and record changes.
+7. Configure npm trusted publishing for the chosen repository/workflow and an approved release environment. Use OIDC provenance rather than storing a long-lived npm token. This step depends on the final repository identity and is intentionally not preconfigured.
+8. Only after release approval, publish the reviewed artifact with public access and provenance. Verify installation into a clean Pi profile.
+9. Verify discovery in Pi's package gallery. The manifest already has the `pi-package` keyword and `pi.extensions` entry; gallery indexing is external and is not guaranteed by a local test.
+
+The local smoke script installs the packed tarball and Pi into a temporary directory, disables resource discovery and network during extension loading, and checks the registered command through the actual loader. It does not alter the user's Pi settings or installed extensions.
+
+## Ongoing releases
+
+Keep host compatibility explicit. The tested host is Pi 0.85.1; wildcard optional peers avoid bundling a competing runtime but do not imply every Pi version is compatible. Re-characterize lifecycle/auth changes on a new host version. AI SDK evaluation is experimental and pinned; review serialization/metadata tests before upgrading it.

package/examples/cloudflare.json

@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "mode": "off",
+  "allowHeadless": false,
+  "backend": {
+    "type": "cloudflare",
+    "model": "typesafe/jev",
+    "accountId": "00000000000000000000000000000000",
+    "auth": {
+      "source": "env",
+      "variable": "CLOUDFLARE_API_TOKEN"
+    }
+  },
+  "timeoutMs": 1500,
+  "minConfidence": 0.8,
+  "maxContextChars": 12000,
+  "historyMessages": 4,
+  "outputReserveTokens": 8192,
+  "routes": {
+    "quick": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_QUICK_MODEL_ID"
+      }
+    ],
+    "standard": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_STANDARD_MODEL_ID"
+      }
+    ],
+    "deep": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_DEEP_MODEL_ID"
+      }
+    ]
+  },
+  "defaultRoute": "deep",
+  "uncertainRoute": "deep"
+}

package/examples/typesafe.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "mode": "off",
+  "allowHeadless": false,
+  "backend": {
+    "type": "typesafe",
+    "model": "jev-1.13.0",
+    "auth": {
+      "source": "env",
+      "variable": "TYPESAFE_API_KEY"
+    }
+  },
+  "timeoutMs": 1500,
+  "minConfidence": 0.8,
+  "maxContextChars": 12000,
+  "historyMessages": 4,
+  "outputReserveTokens": 8192,
+  "routes": {
+    "quick": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_QUICK_MODEL_ID"
+      }
+    ],
+    "standard": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_STANDARD_MODEL_ID"
+      }
+    ],
+    "deep": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_DEEP_MODEL_ID"
+      }
+    ]
+  },
+  "defaultRoute": "deep",
+  "uncertainRoute": "deep"
+}

package/examples/vercel.json

@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "mode": "off",
+  "allowHeadless": false,
+  "backend": {
+    "type": "vercel",
+    "model": "typesafe-ai/jev",
+    "auth": {
+      "source": "env",
+      "variable": "AI_GATEWAY_API_KEY"
+    },
+    "zeroDataRetention": true
+  },
+  "timeoutMs": 1500,
+  "minConfidence": 0.8,
+  "maxContextChars": 12000,
+  "historyMessages": 4,
+  "outputReserveTokens": 8192,
+  "routes": {
+    "quick": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_QUICK_MODEL_ID"
+      }
+    ],
+    "standard": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_STANDARD_MODEL_ID"
+      }
+    ],
+    "deep": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_DEEP_MODEL_ID"
+      }
+    ]
+  },
+  "defaultRoute": "deep",
+  "uncertainRoute": "deep"
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "pi-typesafe-router",
+  "version": "0.1.0",
+  "description": "Opt-in Jev task routing for Pi with TypeSafe, Cloudflare and Vercel backends and ordered preflight model fallbacks",
+  "keywords": [
+    "jev",
+    "model-routing",
+    "pi-extension",
+    "pi-package",
+    "typesafe"
+  ],
+  "license": "MIT",
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "docs/privacy.md",
+    "docs/configuration.md",
+    "docs/architecture.md",
+    "docs/releasing.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "fmt": "oxfmt --write .",
+    "fmt:check": "oxfmt --check .",
+    "lint": "oxlint --deny-warnings src tests scripts",
+    "lint:fix": "oxlint --fix --deny-warnings src tests scripts",
+    "check": "npm run fmt:check && npm run lint && npm run typecheck && npm test",
+    "smoke:package": "node scripts/package-smoke.mjs",
+    "prepack": "npm run typecheck"
+  },
+  "dependencies": {
+    "ai": "7.0.105",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@oxlint/plugins": "1.83.0",
+    "@types/node": "^22.0.0",
+    "oxfmt": "0.68.0",
+    "oxlint": "1.83.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}