@pi-in-go/pigpen-pi-typesafe 0.1.0

package/port/mutations.json

@@ -0,0 +1,302 @@
+[
+ {
+  "name": "enabled-by-default",
+  "file": "extension.go",
+  "find": "s.enabled = os.Getenv(envEnabled) == \"1\"\n\ts.backend = backendFromEnv()\n\ts.registerTool()",
+  "replace": "s.enabled = true\n\ts.backend = backendFromEnv()\n\ts.registerTool()"
+ },
+ {
+  "name": "session-start-keeps-optin",
+  "file": "extension.go",
+  "find": "\ts.enabled = os.Getenv(envEnabled) == \"1\"\n\tif backend := backendFromEnv(); backend != s.backend {",
+  "replace": "\tif backend := backendFromEnv(); backend != s.backend {"
+ },
+ {
+  "name": "session-start-callout-always",
+  "file": "extension.go",
+  "find": "if err == nil && s.isEnabled() && report.Level == pitypesafe.LevelError",
+  "replace": "if err == nil && report.Level == pitypesafe.LevelError"
+ },
+ {
+  "name": "session-start-callout-dropped",
+  "file": "extension.go",
+  "find": "s.callOut(ctx, \"start:\"+string(report.Level), \"TypeSafe is enabled but judgments are skipped. \"+report.Text)",
+  "replace": "_ = report"
+ },
+ {
+  "name": "callout-not-deduplicated",
+  "file": "extension.go",
+  "find": "if s.calledOut == key {",
+  "replace": "if false {"
+ },
+ {
+  "name": "callout-headless-notify",
+  "file": "extension.go",
+  "find": "\tif ctx.HasUI() {\n\t\tctx.Notify(text, \"warning\")\n\t\treturn\n\t}",
+  "replace": "\tctx.Notify(text, \"warning\")\n\treturn"
+ },
+ {
+  "name": "callout-warning-level",
+  "file": "extension.go",
+  "find": "ctx.Notify(text, \"warning\")",
+  "replace": "ctx.Notify(text, \"error\")"
+ },
+ {
+  "name": "disabled-message",
+  "file": "tool.go",
+  "find": "TypeSafe is disabled. Ask the operator to run /typesafe enable; do not enable it by editing configuration or environment files.",
+  "replace": "TypeSafe is disabled."
+ },
+ {
+  "name": "disabled-check-removed",
+  "file": "tool.go",
+  "find": "\tenabled, consent := s.admit()\n\tif !enabled {",
+  "replace": "\t_, consent := s.admit()\n\tif false {"
+ },
+ {
+  "name": "auth-callout-only-401",
+  "file": "tool.go",
+  "find": "rejected := safe.Code == pitypesafe.CodeHTTP && (safe.Status == 401 || safe.Status == 403)",
+  "replace": "rejected := false"
+ },
+ {
+  "name": "auth-callout-403-missed",
+  "file": "tool.go",
+  "find": "(safe.Status == 401 || safe.Status == 403)",
+  "replace": "(safe.Status == 401)"
+ },
+ {
+  "name": "auth-callout-text",
+  "file": "tool.go",
+  "find": "TypeSafe is not authenticated (",
+  "replace": "TypeSafe auth problem ("
+ },
+ {
+  "name": "tool-result-details-dropped",
+  "file": "tool.go",
+  "find": "Details: json.RawMessage(details)",
+  "replace": "Details: json.RawMessage(details[:0])"
+ },
+ {
+  "name": "tool-content-not-json",
+  "file": "tool.go",
+  "find": "sdk.ToolResult{Content: string(content)",
+  "replace": "sdk.ToolResult{Content: string(content[:0])"
+ },
+ {
+  "name": "logout-keeps-enabled",
+  "file": "command.go",
+  "find": "\t\ts.resetClient()\n\t\ts.setEnabled(false)\n\t\tif removed {",
+  "replace": "\t\ts.resetClient()\n\t\tif removed {"
+ },
+ {
+  "name": "logout-keeps-auth-state",
+  "file": "command.go",
+  "find": "\t\tpitypesafe.ClearAuthState()\n\t\ts.resetClient()",
+  "replace": "\t\ts.resetClient()"
+ },
+ {
+  "name": "logout-env-note-dropped",
+  "file": "command.go",
+  "find": "text += \" TYPESAFE_API_KEY is still set in the environment.\"",
+  "replace": "_ = text"
+ },
+ {
+  "name": "logout-message",
+  "file": "command.go",
+  "find": "\"No stored key to remove.\"",
+  "replace": "\"Nothing to remove.\""
+ },
+ {
+  "name": "disable-keeps-enabled",
+  "file": "command.go",
+  "find": "\tcase \"disable\":\n\t\ts.setEnabled(false)",
+  "replace": "\tcase \"disable\":\n\t\t_ = 0"
+ },
+ {
+  "name": "disable-message",
+  "file": "command.go",
+  "find": "TypeSafe disabled for future agent calls. In-flight requests are not cancelled.",
+  "replace": "Disabled."
+ },
+ {
+  "name": "usage-text",
+  "file": "command.go",
+  "find": "\"Usage: /typesafe \"+strings.Join(actions, \" | \")",
+  "replace": "\"Usage: /typesafe\""
+ },
+ {
+  "name": "usage-level",
+  "file": "command.go",
+  "find": "strings.Join(actions, \" | \"), \"warning\")",
+  "replace": "strings.Join(actions, \" | \"), \"info\")"
+ },
+ {
+  "name": "headless-message",
+  "file": "command.go",
+  "find": "This command needs interactive Pi. For headless tool use, explicitly set PI_TYPESAFE_ENABLED=1 and TYPESAFE_API_KEY before launching Pi.",
+  "replace": "Needs UI."
+ },
+ {
+  "name": "login-shadow-check-removed",
+  "file": "command.go",
+  "find": "if pitypesafe.EnvKeySet() {\n\t\t\treport(\"TYPESAFE_API_KEY is set in the environment and takes precedence",
+  "replace": "if false {\n\t\t\treport(\"TYPESAFE_API_KEY is set in the environment and takes precedence"
+ },
+ {
+  "name": "login-cancel-message",
+  "file": "command.go",
+  "find": "Login cancelled; nothing was saved.",
+  "replace": "Cancelled."
+ },
+ {
+  "name": "enable-missing-key-check-removed",
+  "file": "command.go",
+  "find": "\t\tcase pitypesafe.KeyMissing:\n\t\t\treport(\"Run /typesafe login first",
+  "replace": "\t\tcase pitypesafe.KeyNotRequired:\n\t\t\treport(\"Run /typesafe login first"
+ },
+ {
+  "name": "enable-unusable-message",
+  "file": "command.go",
+  "find": "The stored key cannot be used. ",
+  "replace": ""
+ },
+ {
+  "name": "enable-confirm-ignored",
+  "file": "command.go",
+  "find": "\t\tif ok {\n\t\t\ts.setEnabled(true)",
+  "replace": "\t\tif ok || true {\n\t\t\ts.setEnabled(true)"
+ },
+ {
+  "name": "enable-never-confirms",
+  "file": "command.go",
+  "find": "ok, err := ctx.Confirm(\"Enable TypeSafe for this session?\", disclosure(backend))",
+  "replace": "ok, err := true, error(nil)"
+ },
+ {
+  "name": "enable-title",
+  "file": "command.go",
+  "find": "\"Enable TypeSafe for this session?\"",
+  "replace": "\"Enable?\""
+ },
+ {
+  "name": "setup-current-label",
+  "file": "command.go",
+  "find": "current = \"configured via \" + pitypesafe.KeySourceLabel(situation)",
+  "replace": "current = \"configured\""
+ },
+ {
+  "name": "playground-invalid-json-message",
+  "file": "command.go",
+  "find": "Invalid JSON. Keep quoted strings on one line; nothing was sent.",
+  "replace": "Invalid JSON."
+ },
+ {
+  "name": "playground-confirm-before-validate",
+  "file": "command.go",
+  "find": "\tvalidated, err := pitypesafe.PrepareEvaluationRequest(request, pitypesafe.PrepareOptions{})\n\tif err != nil {\n\t\treturn err\n\t}\n\tconsent := s.consentNow()\n\tok, err := ctx.Confirm(\"Send this TypeSafe request?\", disclosure(s.currentBackend()))\n\tif err != nil || !ok {\n\t\treturn err\n\t}",
+  "replace": "\tconsent := s.consentNow()\n\tok, err := ctx.Confirm(\"Send this TypeSafe request?\", disclosure(s.currentBackend()))\n\tif err != nil || !ok {\n\t\treturn err\n\t}\n\tvalidated, err := pitypesafe.PrepareEvaluationRequest(request, pitypesafe.PrepareOptions{})\n\tif err != nil {\n\t\treturn err\n\t}"
+ },
+ {
+  "name": "test-confirm-title",
+  "file": "command.go",
+  "find": "\"Send this TypeSafe request?\"",
+  "replace": "\"Send?\""
+ },
+ {
+  "name": "status-model-name",
+  "file": "command.go",
+  "find": "model := pitypesafe.DefaultModelID(pitypesafe.DefaultBackend)",
+  "replace": "model := \"jev\""
+ },
+ {
+  "name": "status-warning-level",
+  "file": "command.go",
+  "find": "if auth.Level == pitypesafe.LevelError && enabled {",
+  "replace": "if auth.Level == pitypesafe.LevelError {"
+ },
+ {
+  "name": "status-session-cap",
+  "file": "command.go",
+  "find": "\"Session %d/%d attempts, %d successful",
+  "replace": "\"Session %d/%d tries, %d successful"
+ },
+ {
+  "name": "result-not-appended",
+  "file": "command.go",
+  "find": "return ctx.AppendEntry(entryType, json.RawMessage(details))",
+  "replace": "_ = details\n\treturn nil"
+ },
+ {
+  "name": "entry-type",
+  "file": "extension.go",
+  "find": "entryType   = \"typesafe-result\"",
+  "replace": "entryType   = \"typesafe-results\""
+ },
+ {
+  "name": "backend-switch-keeps-consent",
+  "file": "command.go",
+  "find": "\ts.consent++\n\ts.enabled = false",
+  "replace": "\ts.consent++"
+ },
+ {
+  "name": "ownmodel-disclosure-typesafe",
+  "file": "tool.go",
+  "find": "if backend == pitypesafe.BackendOwnModel {\n\t\treturn ownModelMsg",
+  "replace": "if false {\n\t\treturn ownModelMsg"
+ },
+ {
+  "name": "format-noul",
+  "file": "format.go",
+  "find": "\"%s: P(yes) = %s\"",
+  "replace": "\"%s: p = %s\""
+ },
+ {
+  "name": "format-choice",
+  "file": "format.go",
+  "find": "%s: %s \u00b7 confidence %s\", label, jsonString(choice)",
+  "replace": "%s: %s (confidence %s)\", label, jsonString(choice)"
+ },
+ {
+  "name": "format-expanded-ignored",
+  "file": "format.go",
+  "find": "if expanded && answer[\"type\"] != \"noul\" {",
+  "replace": "if false {"
+ },
+ {
+  "name": "render-partial",
+  "file": "tool.go",
+  "find": "\"TypeSafe \u00b7 waiting for response\"",
+  "replace": "\"waiting\""
+ },
+ {
+  "name": "render-call-count",
+  "file": "tool.go",
+  "find": "len(questions), where)",
+  "replace": "len(questions)+1, where)"
+ },
+ {
+  "name": "consent-generation-ignored",
+  "file": "extension.go",
+  "find": "\tif s.consent != consent {\n\t\treturn nil, errDestinationChanged",
+  "replace": "\tif false {\n\t\treturn nil, errDestinationChanged"
+ },
+ {
+  "name": "backend-switch-keeps-generation",
+  "file": "command.go",
+  "find": "\ts.backend = choice\n\ts.consent++",
+  "replace": "\ts.backend = choice"
+ },
+ {
+  "name": "trailing-words-are-an-action",
+  "file": "command.go",
+  "find": "\taction := text\n\tif action == \"\" {",
+  "replace": "\taction := text\n\tif len(fields) > 0 {\n\t\taction = fields[0]\n\t}\n\tif action == \"\" {"
+ },
+ {
+  "name": "ownmodel-callout-blames-key",
+  "file": "tool.go",
+  "find": "\t\tif s.currentBackend() == pitypesafe.BackendOwnModel {\n\t\t\t// The own-model",
+  "replace": "\t\tif false {\n\t\t\t// The own-model"
+ }
+]

package/port/oracle/.env.example

@@ -0,0 +1,4 @@
+# Copy this file to .env and enter your key locally. Never commit .env.
+TYPESAFE_API_KEY=
+# Optional, explicit consent for automated/headless Pi tool calls:
+# PI_TYPESAFE_ENABLED=1

package/port/oracle/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+## Unreleased
+
+<!-- Empty. Next release starts here. -->
+
+## 0.8.0
+
+### Added
+
+- A `commandcode` backend for the same Jev decisions protocol: `createTypeSafe({ backend: "commandcode" })` sends judgments to `api.commandcode.ai` under `/provider/v1/systemone` with the key from `COMMANDCODE_API_KEY` and the model `typesafe/jev`; its public model list does not verify a key.
+- `backend` accepts a caller-supplied endpoint object wherever a backend name is accepted (`createTypeSafe`, `keySituation`, `resolveApiKey`, `authState`, `ensureApiKey`, `safeError`): an endpoint names its own `label`, `host`, `keyEnv`, and optionally `path`, `defaultModel`, and model-list fields, is validated on every call, never reads `TYPESAFE_API_KEY` or the login store, and is never added to the registry. An invalid backend makes `authState` and `keySituation` throw `configuration`; validate user input with `resolveBackend` first.
+- `resolveBackend(nameOrEndpoint)` resolves either form to the validated backend the client uses, and `backendHost(nameOrEndpoint)` reports the destination host for consent text, alongside the `BackendEndpoint`, `BackendSpec`, and `ResolvedBackend` types.
+- `TypeSafeBackend` now includes `"commandcode"`; a consumer with an exhaustive `switch` over it sees a new member.
+
+## 0.7.4
+
+### Fixed
+
+- A bare Jev model id is mapped to the backend's own form before it is sent — on OpenRouter `jev-latest` goes as `~typesafe/jev-latest` and `jev-1.13` as `typesafe/jev-1.13`, for the client default and a per-request `model` alike — so OpenRouter no longer answers 400, and `/typesafe status` reports the model the configured backend actually sends.
+
+## 0.7.3
+
+### Changed
+
+- Dependency updates: `typebox` 1.3.31 to 1.3.34 (runtime); `typescript` 6.0.3 to 7.0.2, `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 0.85.1 to 0.86.1, `@types/node` 22.20.3 to 22.20.4, and `tsx` 4.23.13 to 4.23.15 (development). No change to the public API.
+
+## 0.7.2
+
+### Fixed
+
+- HTTP advice is backend-aware: `safeError(error, backend?)` names the backend's key variable on a 401 (`Check OPENROUTER_API_KEY.` on OpenRouter, `Check TYPESAFE_API_KEY.` by default), a 402 now says `Insufficient credits. Add credits at https://openrouter.ai/credits.` on OpenRouter and `Check your account balance.` elsewhere without marking the key unusable, and a 429 appends `Retry after <n> seconds.` when the response carries a numeric `Retry-After` header. One-argument `safeError` calls are unchanged.
+
+## 0.7.1
+
+### Fixed
+
+- `listModels()` asks each backend for its own model list. It requested the SDK's `/v1/models` on every backend, so on OpenRouter it fetched an HTML page and always failed; it now uses `/api/v1/models` and reads the list from OpenRouter's `data` field (#11).
+- `listModels()` on OpenRouter returns model ids (`vendor/model`), the values `model:` accepts, instead of display names.
+- A public model list no longer proves a key. OpenRouter serves its list without checking the key, so a successful `listModels()` there leaves `authState({ backend: "openrouter" })` unverified rather than recording a garbage key as verified.
+
+### Added
+
+- `BackendConfig` gains optional `modelsPath`, `modelsField`, `modelsIdField`, and `modelsVerifyKey`, documented in the API reference.
+
+## 0.7.0
+
+### Fixed
+
+- Key reporting and login can name the judgment backend: `keySituation(backend)`, `resolveApiKey(backend)`, `authState({ backend })`, and `ensureApiKey(ctx, { backend })` read the backend's own environment variable, `describeAuth` labels the key by backend and names the variable to set, and `AuthState` carries `backend`. Before, every surface reported the TypeSafe key, so an OpenRouter user saw "TypeSafe key: missing" while judgments ran, and `ensureApiKey` opened the TypeSafe login and verified the pasted key against api.typesafe.ai (#9).
+- `createTypeSafe({ backend: "openrouter" })` no longer falls back to `TYPESAFE_API_KEY` or the login store when `OPENROUTER_API_KEY` is unset; a TypeSafe key was being sent to OpenRouter.
+
+### Added
+
+- `DEFAULT_BACKEND` export and a `label` on every `DECISIONS_BACKENDS` entry.
+
+### Docs
+
+- Document the `backend` option, `DECISIONS_BACKENDS`, and which key each backend reads in the README and the API reference; the OpenRouter backend shipped in 0.6.0 without either.
+
+## 0.6.2
+
+### Fixed
+
+- Describe every field the agent authors in the `typesafe_evaluate` schema (`state`, `questions`, `type`, `instructions`, `criteria`, `model`) and show one request payload in the prompt guidelines, so the first call no longer has to fail to learn the shape (#6, #7).
+
+## 0.6.1
+
+### Fixed
+
+- Send OpenRouter judgments to `/api/alpha/decisions` instead of the TypeSafe SDK's default `/v1/systemone` path, while preserving caller-supplied transports (#2).
+- Keep the lockfile's root package version aligned with the published package.
+- Build declarations before checking public-API examples so `npm run check` works from a clean checkout.
+
+### Added
+
+- Contributor CI for supported Node versions on Linux and macOS, workflow lint, installed-package smoke tests, and a combined `CI passed` check.
+- Verified package artifacts, tag-triggered draft GitHub releases, weekly dependency updates, and contributor/release guidance; npm publication remains manual.
+
+## 0.6.0
+
+### Added
+
+- `backend` option on `TypeSafeOptions` to route judgments to different services (`"typesafe"` or `"openrouter"`).
+- `DECISIONS_BACKENDS` registry mapping backend names to `{ host, keyEnv }` configs.
+- Backend-specific env var resolution: `OPENROUTER_API_KEY` for openrouter, `TYPESAFE_API_KEY` for typesafe.
+- Default model changes per backend: `jev-latest` for typesafe, `typesafe/jev-1.13` for openrouter.
+
+## 0.5.0
+
+- Initial tracked release.

package/port/oracle/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to pi-typesafe
+
+pi-typesafe is the TypeSafe client other Pi extensions build on: key storage, consent, budgets, validated responses, and the `typesafe_evaluate` tool. A small, predictable surface is the feature. Please keep it that way.
+
+## Report
+
+- **A bug.** Use the "Bug" template with the Pi and pi-typesafe versions, the error text Pi showed, and the smallest sequence that reproduces it. `/typesafe status` output helps.
+- **A gap for extension authors.** Use the "Extension author request" template: what you are building, what the client does not let you do, and the smallest API that would.
+- **Security.** A way to expose a key, an upstream response body, or submitted content: use the private security advisory, not a public issue.
+
+## Change
+
+1. `npm ci`, then `npm run check` (build, typecheck, offline tests with an injected `fetch`). It must pass before and after your change.
+2. Behaviour changes come with tests in `tests/`. Everything is testable offline through the `fetch` option; no test may need a key or the network.
+3. `npm run test:live` sends one billable request with your own key. Run it when you touch the transport or the response validation and say so in the PR.
+
+## Rules the code keeps
+
+- **The public API is `src/index.ts`.** Adding an export needs a line in [docs/api.md](docs/api.md); removing or changing one needs a minor version bump until 1.0 and a note in the release.
+- **No new runtime dependencies without a reason in the PR.** Today: `@typesafe-ai/sdk` and `typebox`.
+- **Nothing from upstream reaches the user unvalidated.** Responses are checked against the questions before a caller sees them; an invalid response is an error, never a partial answer.
+- **Errors carry a code and a safe message.** Never a response body, never the key, never the submitted state.
+- **Keys are owner-only and never returned.** `resolveApiKey` tells you where a key came from, not what it is.
+- **Consent and budget are enforced here, not in callers.** `maxRequests` counts attempts, including failures; a caller cannot exceed it by retrying. Daily caps live in the same client so a script cannot opt out by forgetting them.
+
+## Commits and pull requests
+
+- One change per commit, a message that says what and why, no tool or AI attribution lines.
+- One topic per PR; update the README in the same PR when behaviour changes.
+- Releases are cut by the maintainer; do not bump `package.json` in a PR unless the maintainer requests it. Release bumps update `package-lock.json` and `CHANGELOG.md` too.
+- GitHub Actions checks supported Node versions, Linux and macOS, and the installed npm package without API keys. **CI passed** is the combined merge gate; see [CI and continuous delivery](docs/ci-cd.md) for branch-rule setup and the manual release process.
+
+## Where to ask
+
+Issues here, or the Pi and TypeSafe Discord servers. Critique the code, not the person.

package/port/oracle/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Gapac
+
+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/port/oracle/README.md

@@ -0,0 +1,159 @@
+# pi-typesafe
+
+[![CI](https://github.com/DevMortimer/pi-typesafe/actions/workflows/ci.yml/badge.svg)](https://github.com/DevMortimer/pi-typesafe/actions/workflows/ci.yml)
+
+[Jev](https://typesafe.ai) inside [Pi](https://pi.dev). Jev is TypeSafe's judgment model: send it some state and typed questions and it returns probabilities instead of prose, in well under a second, for a fraction of a cent. This package gives Pi three things built on it:
+
+- **A tool for the agent.** `typesafe_evaluate` hands small structured judgments (classify, triage, compare, score) to Jev and returns calibrated numbers in one batched call.
+- **A playground.** `/typesafe test` and `/typesafe playground` run requests from the terminal without touching the model's context.
+- **A typed API for other extensions.** One client, one key store, one login prompt, so extensions such as [pi-warden](https://github.com/DevMortimer/pi-warden) do not each ask for a key — and so a long run can tell you whether Jev was reachable and what it cost.
+
+![Pi triaging three bug reports with one batched TypeSafe call: the prompt, the rendered TypeSafe answers, and the agent's verdict](https://raw.githubusercontent.com/DevMortimer/pi-typesafe/main/docs/preview.png)
+
+Independent project. Not affiliated with TypeSafe AI or the Pi authors.
+
+## In one minute
+
+```bash
+pi install npm:pi-typesafe
+```
+
+Then, inside Pi:
+
+1. `/typesafe login` and paste a key from [console.typesafe.ai](https://console.typesafe.ai). Input is hidden; the key is verified against the API and saved to `~/.pi/agent/pi-typesafe/auth.json` with owner-only permissions.
+2. `/typesafe test` sends one built-in sample request and shows the answers.
+3. `/typesafe enable` lets the agent call the tool for this session, after you confirm the data notice.
+
+Requires Pi 0.85 or newer and Node.js 22.19 or newer. Usage is billed to your TypeSafe account. For CI or scripts set `TYPESAFE_API_KEY` in the environment instead; it takes precedence over the stored key. Do not paste the key into chat, command arguments, or project files.
+
+## The three question types
+
+Jev answers three kinds of question about the state you send. Every question in a request runs in parallel and in isolation, so adding questions barely changes the latency.
+
+| Type | Asks | Returns |
+| --- | --- | --- |
+| **Choice** | Which of these options fits? | the chosen key, a probability per option, confidence |
+| **Score** | Where on this ordered rubric does it sit? | a position (may be fractional), probabilities, confidence |
+| **Noul** | Is this statement true? | a probability from 0 to 1 |
+
+```json
+{
+  "state": { "message": "I was charged twice. Please help today." },
+  "questions": {
+    "team": { "type": "choice", "instructions": "Which team should handle this?",
+              "criteria": { "billing": "Charges and payments", "technical": "Software failures", "other": "None of these" } },
+    "urgent": { "type": "noul", "instructions": "Does the sender request help today?" },
+    "frustration": { "type": "score", "instructions": "How frustrated does the sender sound?",
+                     "criteria": ["Neutral request", "Frustrated but civil", "Explicit anger or threats"] }
+  }
+}
+```
+
+Read probabilities and confidence alongside the answer. Confidence describes how concentrated the distribution is; it is not proof of correctness or permission to act.
+
+## The agent tool
+
+`typesafe_evaluate` is registered at startup but **disabled until you run `/typesafe enable`** in the session. For automated or headless runs, set `PI_TYPESAFE_ENABLED=1` explicitly.
+
+The tool accepts JSON `state` plus 1 to 32 questions and returns answers, model, token usage, and elapsed time. Good uses: triaging a list of issues in one call, deciding which of several files a change belongs to, checking whether a reply answers the question that was asked, scoring candidates against a rubric you wrote. Bad uses: anything that needs reasoning across steps, or a single question that mixes several judgments.
+
+## Writing questions that work
+
+The question text is the whole program. Jev answers exactly what is asked, so ambiguity shows up as a middling probability rather than an error.
+
+- **Ask about what the state says, not what you would conclude.** A report that says "happens every time" scored `P(yes) = 0.36` for `Is the bug reproducible from the text?` because that can also mean "could a reader reproduce it using only this text?". `Does the reporter state that the problem occurs consistently?` is the intended question.
+- **Describe situations in Score levels, not degrees.** `"Workaround exists"` is checkable; `"medium"` is not.
+- **Include a no-match option** in a Choice (`other`, `unclear`) when nothing may fit; the model cannot pick an option you omitted.
+- **One judgment per question.** Split independent dimensions into separate questions and batch them in one request; they run in parallel and cannot see each other.
+- **Name the state fields you mean** with backticks (`` `report.body` ``) when the state has several parts.
+
+The [TypeSafe docs](https://docs.typesafe.ai/primitives) cover each primitive in detail.
+
+## Availability and spend
+
+An enabled extension with no usable key looks exactly like a working one — one evaluation ran keyless for hours before anyone noticed. Three answers exist now, and `/typesafe status` prints all of them:
+
+- **Is Jev reachable?** `authState()` reports the key source, whether it has been accepted, and the last failure that degraded it; `describeAuth()` turns that into a level and one safe line. The extension calls both at session start and after an authentication rejection, so a headless run says judgments are skipped instead of quietly falling back to its offline path.
+- **What has this run cost?** `getSpend()` returns session counters, today's persisted counters, and the cap currently reached. Cost is estimated from input tokens only, because output is free.
+- **When does it stop?** `maxRequests` bounds a client instance. Three caps bound a local day, survive restarts, and stop a request before it is submitted:
+
+| Option | Environment | Bounds |
+| --- | --- | --- |
+| `maxRequestsPerDay` | `PI_TYPESAFE_MAX_REQUESTS_PER_DAY` | requests |
+| `maxInputTokensPerDay` | `PI_TYPESAFE_MAX_INPUT_TOKENS_PER_DAY` | input tokens |
+| `maxUsdPerDay` | `PI_TYPESAFE_MAX_USD_PER_DAY` | estimated spend |
+
+The environment may lower an explicit cap but never raise it. A reached cap raises a `budget` error naming the cap, the amount used, and the day.
+
+Need more than one request? `evaluateAll(request)` asks any number of questions about one state (over 32 are chunked and fanned out), and `evaluateMany(requests)` runs several requests at once. Both preserve order, bound concurrency, never throw, and stop submitting once the budget is gone. [`pi-typesafe/calibrate`](docs/api.md#calibration-pi-typesafecalibrate) turns labelled cases into thresholds with AUC, a sweep, and a replay runner.
+
+## Commands
+
+| Command | Effect |
+| --- | --- |
+| `/typesafe login` | Enter and verify an API key (hidden input), then store it |
+| `/typesafe logout` | Delete the stored key and disable the tool |
+| `/typesafe setup` | Check which key is in use; starts login if none |
+| `/typesafe status` | Opt-in state, key state, session and today's counters, cost estimate, any reached cap |
+| `/typesafe enable` | Confirm the data notice and allow agent tool calls this session |
+| `/typesafe disable` | Stop future agent tool calls |
+| `/typesafe test` | Send one built-in sample request |
+| `/typesafe playground` | Edit request JSON in Pi's editor, confirm, view results |
+
+Playground and test results are shown in the terminal only; they do not enter the model's context.
+
+## Questions people ask
+
+**Do I need a key to install?**
+Install works without one; nothing is sent until you log in and enable the tool. Jev is new and access may be limited at the moment. Keys come from [console.typesafe.ai](https://console.typesafe.ai).
+
+**What does a request cost?**
+Whatever TypeSafe bills for the input tokens of your state and questions; output is free. At the listed rate ($42 per billion input tokens at the time of writing) a few hundred tokens cost well under a hundredth of a cent. The per-session cap is 20 attempts, and `maxUsdPerDay` stops a long run at a number you choose.
+
+**Why not just ask the main model?**
+The main model can answer any of these questions in prose. It is slower, costs more per call, and grades its own work. Jev returns a calibrated number your code or the agent can branch on, in a quarter of a second, from a separate model. That matters most when the same question is asked many times: every tool call, every file, every issue in a list.
+
+**What is sent?**
+Only the state and questions you (or the agent, once enabled) submit, to `https://api.typesafe.ai` only. No files, conversation history, or telemetry. Error messages never include upstream response bodies, headers, keys, or your submitted state.
+
+**Limits?**
+Per request: 32 questions and 64 KiB of JSON. Per session: 20 attempts, 15-second timeout, no automatic retries. Per day: no cap unless you set one. Session limits reset when a session starts or reloads; daily counters live in `~/.pi/agent/pi-typesafe/usage.json` and roll over at local midnight. The SDK's `TYPESAFE_BASE_URL` and `TYPESAFE_LOG_LEVEL` overrides are ignored.
+
+## For extension authors
+
+Import the library from your own extension. It has no dependency on Pi and is safe in tests.
+
+```ts
+import { ask, createTypeSafe, choice, noul, score } from "pi-typesafe";
+
+const typesafe = createTypeSafe({ maxRequests: 5, maxUsdPerDay: 1 });  // key: TYPESAFE_API_KEY, else the login store
+const answer = await ask(typesafe, {
+  state: { title: "Login fails after update", body: "..." },
+  questions: {
+    area: choice("Which area does this report concern?", { auth: "Sign-in", ui: "Layout", other: null }),
+    duplicate: noul("Does the report describe the same defect as `known_issue`?"),
+    severity: score("How severe is the defect?", ["Cosmetic", "Workaround exists", "Blocking"]),
+  },
+}, { timeoutMs: 5_000 });
+if (!answer.ok) return { skipped: answer.errorCode === "budget" };  // never throws
+```
+
+Your extension owns its own user consent and budget; `/typesafe enable` applies only to this package's tool. Check `authState()` rather than your own consent flag before you report that judgments are on.
+
+Judgments can also go through OpenRouter: `createTypeSafe({ backend: "openrouter" })` sends them to `openrouter.ai` with the key from `OPENROUTER_API_KEY`. Command Code serves the same protocol: `createTypeSafe({ backend: "commandcode" })` sends them to `api.commandcode.ai` with the key from `COMMANDCODE_API_KEY` and the model `typesafe/jev`. Or pass a `BackendEndpoint` object as `backend` to name any host that serves the protocol: it brings its own key variable, never reads `TYPESAFE_API_KEY`, and `backendHost()` reports its destination host for your consent text. These backends have no login store, so `/typesafe login` does not apply to them. Pass the same `backend` to `authState`, `keySituation`, and `ensureApiKey`, or the status you report describes the TypeSafe key while the requests use another one. The `/typesafe` commands and the `typesafe_evaluate` tool always use the TypeSafe backend. Every export — the client, `ask`, batching, the usage ledger, auth state, and the `pi-typesafe/calibrate` and `pi-typesafe/ui` entry points — is in [docs/api.md](docs/api.md).
+
+## Development
+
+```bash
+npm ci
+npm run check        # build, typecheck, offline tests
+cp .env.example .env # add your key locally; .env is git-ignored
+npm run test:live    # one billable sample request
+npm run dev:pi       # start Pi with only this working tree as extension (.env optional)
+```
+
+Pull requests run key-free checks on Linux and macOS, supported Node versions, and the installed npm package. Version tags prepare a draft release; npm publishing stays manual. See [Contributing](CONTRIBUTING.md) and [CI and continuous delivery](docs/ci-cd.md).
+
+## License
+
+MIT