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

package/port/oracle/docs/api.md

@@ -0,0 +1,143 @@
+# API
+
+Everything `pi-typesafe` exports, for extension authors. The library has no dependency on Pi's runtime and is safe in tests. The README covers the tool, the commands, and how to write questions.
+
+## The client
+
+```ts
+import { createTypeSafe, choice, noul, score } from "pi-typesafe";
+
+const typesafe = createTypeSafe({ maxRequests: 5, maxUsdPerDay: 1 });
+const result = await typesafe.evaluate({
+  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"]),
+  },
+});
+result.answers.area.choice;      // "auth" | "ui" | "other"
+result.answers.duplicate.noul;   // 0..1
+result.answers.severity.score;   // 0..2, may be fractional
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `apiKey` | the backend's key (below) | Never returned |
+| `backend` | `typesafe` | `typesafe`, `openrouter`, `commandcode`, or a caller-supplied endpoint object; picks the host, the request path, the default model, and the key |
+| `model` | `jev-latest` (`typesafe/jev-1.13` on OpenRouter, `typesafe/jev` on Command Code) | No model is inferred from submitted content |
+| `timeoutMs` | `15000` | Per request; no automatic retries |
+| `maxInputBytes` | `65536` | UTF-8 JSON bytes, not tokens |
+| `maxRequests` | `20` | Attempts per client instance, failures included |
+| `maxRequestsPerDay`, `maxInputTokensPerDay`, `maxUsdPerDay` | none | Local-day caps, persisted |
+| `usdPerMTok` | `0.042` | Price used for the estimate and the USD cap |
+| `ledger` | the store next to the key | Inject a ledger in tests |
+| `fetch` | global fetch | Inject a transport for offline tests |
+
+A `model` is mapped to the backend's own id form before it is sent: on OpenRouter a bare `jev-latest` goes as `~typesafe/jev-latest` and a bare `jev-1.13` (or `jev-1.13.0`) as `typesafe/jev-1.13`, while an id that already carries an author, such as `vendor/other`, passes unchanged, and TypeSafe sends ids as written. The same mapping applies to a per-request `model` inside `evaluate()`; the limits of 1–100 characters apply to your own id, before mapping. A caller-supplied endpoint's model is never mapped: `defaultModel` and a per-request `model` go on the wire as the caller wrote them.
+
+`DECISIONS_BACKENDS` is the registry behind `backend`: `typesafe`, `openrouter`, and `commandcode`. Command Code serves the same Jev decisions protocol at `api.commandcode.ai` under `/provider/v1/systemone`, with the model id `typesafe/jev`; its model list is public, under `/provider/v1/models`, and arrives in `data` with ids in `id`. Each entry carries `label`, `host`, `keyEnv`, and, when the service does not serve the SDK's own paths, `path` for the judgment request plus `modelsPath`, `modelsField`, and `modelsIdField` for the model list — OpenRouter's and Command Code's lists are renamed to the `models` the SDK reads, with each entry's `id` promoted to the `name` that `listModels()` returns. `modelsVerifyKey: false` marks a backend whose model list is public, and therefore proves nothing about the key: both OpenRouter and Command Code serve theirs without checking one, so `listModels()` there leaves the auth state unverified while the answer check is unchanged and a malformed reply stays a `response` error. `DEFAULT_BACKEND` is `"typesafe"`.
+
+`backend` also accepts a caller-supplied endpoint object (`BackendEndpoint`) wherever a backend name is accepted — `createTypeSafe`, `keySituation`, `resolveApiKey`, `authState`, `ensureApiKey`, and `safeError`. An endpoint names `label`, `host`, and `keyEnv`, and optionally `path`, `modelsPath`, `modelsField`, `modelsIdField`, `modelsVerifyKey`, and `defaultModel`; it is validated on every call, never added to the registry, and without `defaultModel` requires `model` on `createTypeSafe`. `resolveBackend(nameOrEndpoint)` resolves either form to the validated `ResolvedBackend` the client uses (registry `name` when there is one, `host` as origin only, explicit `keyEnv` and `modelsVerifyKey`), and `backendHost(nameOrEndpoint)` returns just the destination host — `api.commandcode.ai`, `gw.example.com:8443` — for consent text. Validation is in this order, and every failure is a `configuration` error whose message never quotes a caller value (a host can carry credentials in its user info), except the label after it is validated:
+
+| Rule | Refusal |
+| --- | --- |
+| `label` is a string, trimmed nonempty, at most 60 characters | `Backend label must be a nonempty string of at most 60 characters.` |
+| `host` is an absolute `https:` URL with no user info, path, query, or fragment (`http:` only for a loopback host) | `Backend host must be an absolute https: URL with no user info, path, query, or fragment …` |
+| `path`, when present, starts with `"/"` and carries no `?` or `#` | `Backend path must be a string that starts with "/".` |
+| `modelsPath`, same rule | `Backend modelsPath must be a string that starts with "/".` |
+| `modelsField` / `modelsIdField`, when present, nonempty strings | `Backend modelsField must be a nonempty string.` / `Backend modelsIdField must be a nonempty string.` |
+| `modelsVerifyKey`, when present, a boolean | `Backend modelsVerifyKey must be a boolean.` |
+| `keyEnv` is a name of letters, digits, and underscores, not starting with a digit | `Backend keyEnv must name an environment variable: letters, digits, and underscores, not starting with a digit.` |
+| `keyEnv` is not `TYPESAFE_API_KEY` in any case | `Backend keyEnv must not be TYPESAFE_API_KEY: the TypeSafe key is only sent to the typesafe backend. Give this endpoint its own variable.` |
+| `defaultModel`, when present, trimmed nonempty, at most 100 characters | `Backend defaultModel must be a nonempty string of at most 100 characters.` |
+
+Anything that is neither a registry name nor such an object is refused with `backend must be a registry name or a backend object.`
+
+The TypeSafe backend takes its key from `TYPESAFE_API_KEY`, then the `/typesafe login` store. Every other backend — registry or endpoint — reads only its own `keyEnv` variable: the store holds a TypeSafe key, and a login verifies against api.typesafe.ai, so neither applies elsewhere, and the TypeSafe key is only ever sent to the typesafe backend. `createTypeSafe` with no `apiKey` and no key in the backend's variable fails with `No API key. Set <keyEnv> in the environment.` before any request is built. Pass the same `backend` to `authState`, `keySituation`, and `ensureApiKey` so what you report matches what you send.
+
+`evaluate(request, { signal })` validates before sending and rejects with `TypeSafeIntegrationError`. `code` is one of `configuration`, `validation`, `budget`, `aborted`, `timeout`, `http`, `connection`, `response`; messages never contain upstream bodies, keys, or your submitted state, and no header value except a numeric `Retry-After` count in seconds (quoted by the 429 advice as `Retry after <n> seconds.`). The advice is backend-aware: a 401 names the backend's own key variable (`Check TYPESAFE_API_KEY.`, `Check OPENROUTER_API_KEY.`, `Check COMMANDCODE_API_KEY.`, or `Check <keyEnv>.` for an endpoint), and a 402 says `Check your account balance.` except on OpenRouter, which says `Insufficient credits. Add credits at https://openrouter.ai/credits.` `listModels()` verifies the key without counting toward `maxRequests`, except on a backend whose model list is public (`modelsVerifyKey: false`, or an endpoint that does not set `modelsVerifyKey: true`), which accepts any key and leaves the auth state unverified.
+
+## Admission
+
+`prepareEvaluationRequest(value, { maxInputBytes })` is the one admission rule, used by the tool, the playground, and `evaluate`. It normalizes the near-miss aliases a model produces (`options` / `levels` / `choices` for `criteria`, a string Noul criterion, a label array for a Choice), validates the schema and JSON-safety, then enforces the byte budget. `DEFAULT_MAX_INPUT_BYTES`, `DEFAULT_MAX_QUESTIONS`, and `DEFAULT_MAX_REQUESTS` hold the shared defaults.
+
+## Batching
+
+`evaluate` is one request: up to 32 questions about one state. Both batching calls preserve input order, bound concurrency (`concurrency`, default 4), never throw, and stop submitting once a `budget` or cancellation failure appears.
+
+| Call | Use |
+| --- | --- |
+| `evaluateAll(request)` | One state, any number of questions: chunks over 32 share the state, then merge into one `answers` map with usage summed |
+| `evaluateMany(requests)` | Several requests: per-request results plus merged answers, `failures`, `skipped` |
+| `chunkEvaluationRequest(request, { maxQuestions })` | The splitter alone; a pure function, no validation |
+| `fanOut(items, worker, { concurrency, signal, stopOn })` | The pool underneath, for your own work |
+
+Every item comes back as `{ ok: true, index, value }` or `{ ok: false, index, error, skipped }`; `skipped` marks work that was never submitted.
+
+## Usage and spend
+
+`getUsage()` returns this client's session counters (`requestsStarted`, `requestsSucceeded`, `requestsFailed`, `inputTokens`, `outputTokens`, `estimatedUsd`). `getSpend()` adds today's persisted totals, the caps in force, and the cap currently reached.
+
+Day caps live in `~/.pi/agent/pi-typesafe/usage.json` (owner-only, atomic, best-effort: an unwritable ledger never fails a request) and roll over at local midnight.
+
+| 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, never raise it. A reached cap raises a `budget` error that names the cap, the amount used, and the day, before anything is submitted. Cost is estimated from input tokens only, because output is free.
+
+`openUsageLedger(options)`, `usagePath()`, `estimateUsd(tokens, usdPerMTok)`, `capsFromEnvironment(env)`, and `mergeCaps(explicit, environment)` expose the same arithmetic for your own display.
+
+## Auth state
+
+`authState({ backend })` never throws for a valid backend. An invalid backend — an unknown name or an endpoint object that fails validation — throws the same `configuration` error as `resolveBackend`, so validate a user-supplied endpoint with `resolveBackend` first. It reports `backend` (the value you passed, `typesafe` by default — a name or your endpoint object), `kind` (`environment`, `stored`, `missing`, `unusable`), `keyName`, `path`, `reason`, `verified`, `verifiedAt`, `lastFailure`, and `usable` — `usable` is false when no key is present or the last authentication outcome was an HTTP 401/403 rejection. Name the backend you pass to `createTypeSafe`, or the report describes a key you do not send. The verification and failure record is one file shared by every backend, so after switching backends the last outcome stands until the next request: a 401 recorded while one backend is in use makes every backend's `authState` report `usable: false`.
+
+`describeAuth(state)` turns that into `{ level: "ok" | "warning" | "error", text }` for a status line or a log. The extension calls both at session start and after a rejection, so an enabled-but-unusable setup is never reported as working.
+
+`recordAuthVerified()` is called by `listModels()` and by the first successful request; `recordAuthFailure(error)` records what degraded TypeSafe; `clearAuthState()` forgets both, and `/typesafe logout` calls it. `keySituation(backend)` and `keySourceLabel(situation)` remain the lower-level, frozen-for-existing-callers pair, and `resolveApiKey(backend)` the pre-0.4.0 one; the `backend` argument is optional and defaults to `typesafe`. An environment situation names the variable it read in `keyEnv`.
+
+## Asking without throwing
+
+```ts
+import { ask } from "pi-typesafe";
+
+const answer = await ask(typesafe, request, { timeoutMs: 5_000, signal: mySignal });
+if (!answer.ok) return { skipped: answer.errorCode === "budget" };
+answer.answers; // typed, plus model, usage, elapsedMs
+```
+
+`ask` merges its deadline into your signal, takes any object with `evaluate` (so tests pass a stub), and never throws: a failure is `{ ok: false, error, errorCode }` with pi-typesafe's own message. Unknown failures become a fixed message, so nothing from the transport reaches the user.
+
+## Calibration: `pi-typesafe/calibrate`
+
+A small, domain-free toolkit for turning labelled cases into thresholds.
+
+```ts
+import { calibrate, formatCalibration, replay, samplesOf } from "pi-typesafe/calibrate";
+
+const results = await replay(cases, data => scoreOne(data), { concurrency: 6 });
+console.log(formatCalibration(calibrate("action guard", samplesOf(results).samples, { minPrecision: 0.8 })));
+```
+
+| Export | Purpose |
+| --- | --- |
+| `auc(samples)` | Rank-based AUC (Mann–Whitney, ties count half); undefined when one class is empty |
+| `metricsAt(samples, threshold)`, `sweep(samples, thresholds)` | Confusion counts plus precision, recall, and flag rate |
+| `defaultThresholds(samples)`, `pickThreshold(rows, floors)` | The distinct-score grid, and the lowest threshold that clears a precision and recall floor |
+| `calibrate(name, samples, options)`, `formatCalibration(calibration)` | AUC, the sweep, a recommendation, and what it misses and flags, as text |
+| `replay(cases, score, options)`, `samplesOf(results)` | Run labelled cases through any scorer with bounded concurrency, keep per-case failures, then extract the scored samples |
+
+`replay` stops on a `budget` failure like the batching calls, and reports each failure with the scorer's own message unless you pass `describeError`.
+
+## Login helpers: `pi-typesafe/ui`
+
+`ensureApiKey(ctx, { backend })`, `loginWithPrompt(ctx)`, and `promptForApiKey(ctx)` use the same hidden input as `/typesafe login`. `ensureApiKey(ctx)` returns the existing key source, or prompts, verifies, and stores a new TypeSafe key (`undefined` when the user cancels). For any other backend it returns the environment source or throws `configuration` naming the variable to set; it never opens the prompt, because the prompt verifies against api.typesafe.ai and writes the TypeSafe store. These need Pi's TUI, so call them only from extension command handlers.
+
+## One agent tool
+
+`typesafe_evaluate` is the only tool the package registers. It already accepts typed Choice, Score, and Noul questions, including the aliases above, so a separate "ask Jev" tool would duplicate the admission seam and give the model two ways to do one thing. `ask()` is the author-facing half of that seam; both run through `prepareEvaluationRequest`, so what one accepts the others accept.
+
+Your extension owns its own user consent and budget; `/typesafe enable` applies only to this package's tool. See [`../examples/decision-extension.ts`](../examples/decision-extension.ts) and [pi-warden](https://github.com/DevMortimer/pi-warden) for a full extension built this way.

package/port/oracle/docs/ci-cd.md

@@ -0,0 +1,97 @@
+# CI and continuous delivery
+
+The `CI` workflow runs on every pull request to `main`, pushes to `main`, merge
+queue checks, `v*` tags, and manual runs from the Actions page. There are no path
+filters: documentation-only PRs also report the required check. Like pi-warden,
+this project prepares draft releases but does not automatically publish to npm.
+
+## Contributor checks
+
+- **Workflow lint** runs actionlint 1.7.12 and ShellCheck on the workflow commands.
+- **Check (ubuntu-latest, Node 22.19.0)** tests the minimum supported Node version.
+- Linux also runs Node **24** and **26**; macOS runs Node **24**. Each job installs
+  the lockfile with `npm ci`, then runs `npm run check`: build, typecheck, and
+  offline tests. Build runs first because the public-API example resolves this
+  package's exports through `dist/`; this also checks the generated declarations
+  from a clean checkout. Native Windows is not in this matrix; the existing credential and
+  usage tests assert POSIX file permissions.
+- **Package** builds an actual npm tarball and installs it outside the checkout
+  with install scripts disabled. It checks root and calibration imports without
+  optional Pi peers, verifies all declared JavaScript and type declaration
+  files, then checks the extension, UI helpers, and Pi loader with the peer
+  versions from `package-lock.json`. It also checks package/lockfile version
+  agreement.
+- **CI passed** runs even when another job fails or is skipped, and fails unless
+  all three prerequisites succeeded. This is the stable check to require in the
+  `main` branch rules; do not require only **Package**, which can be skipped.
+
+No TypeSafe or OpenRouter credentials are needed. Tests do not call either
+service. CI does not run `test:live` or any other billable checks. Package
+installation needs access to npm; offline tests themselves use fake transports.
+
+Actions use full commit SHAs, checkout does not retain credentials, and check
+jobs have read-only repository permissions. Jobs have time limits; newer PR
+runs cancel superseded runs. Fork PRs use `pull_request`, never
+`pull_request_target`, and do not receive repository secrets. Dependabot opens
+weekly action and dependency updates; they run the same checks and are not
+merged automatically.
+
+Run the normal gate locally with:
+
+```bash
+npm ci
+npm run check
+npm pack --dry-run # builds and lists the publishable files
+```
+
+For the complete installed-package smoke test, use the workflow's **Package**
+steps or dispatch `CI` from the Actions page after this workflow is on `main`.
+Successful runs retain an `npm-package` artifact for 14 days. It contains the
+verified tarball and `SHA256SUMS`; tag runs also include release notes.
+
+## Release delivery
+
+A tag run must pass the same checks. Before packaging, it must also prove:
+
+1. The tagged commit is an ancestor of `origin/main`.
+2. The package has a stable `X.Y.Z` version and the tag is exactly `vX.Y.Z`.
+3. Both root version fields in `package-lock.json` match `package.json`.
+4. `CHANGELOG.md` has a nonempty `## X.Y.Z` section, not just an HTML comment.
+
+Only a **push of a version tag** can start **Draft release**. The job downloads
+that run's checked artifact, verifies the tarball checksum, and creates a draft
+GitHub release with the notes, tarball, and checksum. PRs, branch pushes, merge
+queues, and manual runs cannot create a release. A manual run on a tag can check
+it, but does not publish or create a draft.
+
+Only the draft job has `contents: write`. It uses the built-in GitHub token,
+does not check out or execute repository code, and uses `--verify-tag` so it
+cannot create a tag. No npm token or other new repository secret is required.
+An existing release for the tag makes creation fail rather than overwrite it;
+inspect any existing draft and assets before retrying a failed delivery.
+
+## Maintainer steps
+
+1. In GitHub's `main` branch rules, require **CI passed** and PR review. This PR
+   does not change repository settings; the checks are not a merge restriction
+   until a maintainer enables the rule.
+2. For a release, update the version with `npm version patch --no-git-tag-version`
+   (or the chosen minor version), so `package.json` and `package-lock.json` stay
+   aligned. Move the release notes below a matching `## X.Y.Z` heading and leave
+   `## Unreleased` at the top. Commit these release files together. Normal
+   contributor PRs leave the version bump to the maintainer.
+3. Merge only after review and a passing **CI passed**. Pull the merged `main`,
+   ensure the checkout is clean, and run `npm ci` and `npm run check`.
+4. Create and push the matching tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+5. Wait for its `CI` run and review the draft. Download its tarball and
+   `SHA256SUMS` to an empty directory, then run `sha256sum --check SHA256SUMS`
+   (`shasum -a 256 --check SHA256SUMS` on macOS).
+6. Publish that verified tarball yourself with `npm publish ./pi-typesafe-X.Y.Z.tgz`,
+   using maintainer credentials and the normal npm authentication checks. Then
+   publish the GitHub draft manually. Do not publish a PR artifact or run
+   `npm publish` from an unreviewed branch.
+
+Merging this workflow creates no tag, npm publication, or published GitHub
+release. The existing manual `npm publish` process can still be used from a
+reviewed, checked release commit; publishing the tagged tarball is preferred
+because it is the exact package tested by the release workflow.

package/port/oracle/examples/decision-extension.ts

@@ -0,0 +1,41 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ask, authState, createTypeSafe, choice, describeAuth, noul } from "pi-typesafe";
+
+// A separate extension using the public API, not pi-typesafe's private modules.
+// It owns its own consent and request budget; it does not reuse /typesafe enable.
+export default function decisionExample(pi: ExtensionAPI): void {
+  pi.registerCommand("decision-demo", {
+    description: "Send one synthetic, batched decision request to TypeSafe",
+    async handler(_args, ctx) {
+      if (!ctx.hasUI) return;
+      // Say which key is in effect before showing a data notice, so a missing one is not mistaken for consent.
+      const auth = describeAuth(authState());
+      if (auth.level === "error") {
+        ctx.ui.notify(auth.text, "warning");
+        return;
+      }
+      if (!await ctx.ui.confirm("Send a TypeSafe request?", "This synthetic example goes to api.typesafe.ai and may incur charges.")) return;
+      try {
+        // One client instance, one session budget, and a daily spend cap the script cannot forget.
+        const client = createTypeSafe({ maxRequests: 1, maxUsdPerDay: 1 });
+        const answer = await ask(client, {
+          state: "Please refund the duplicate charge.",
+          questions: {
+            team: choice("Which team should handle the request?", {
+              billing: "Payments and refunds", engineering: "Software defects", other: "Anything else",
+            }),
+            refund: noul("Is the sender requesting a refund?"),
+          },
+        }, { timeoutMs: 5_000 });
+        if (!answer.ok) {
+          ctx.ui.notify(answer.errorCode === "budget" ? `No request was sent: ${answer.error}` : "The example could not complete.", "warning");
+          return;
+        }
+        ctx.ui.notify(`Team: ${answer.answers.team.choice}; P(refund): ${answer.answers.refund.noul}; ${answer.elapsedMs} ms`, "info");
+      } catch (error) {
+        // createTypeSafe rejects an unusable key store; ask() never throws.
+        ctx.ui.notify(error instanceof Error ? error.message : "The example could not start.", "error");
+      }
+    },
+  });
+}

package/port/oracle/extensions/index.js

@@ -0,0 +1,2 @@
+// Pi entry point. Kept at extensions/index.js so Pi lists the extension as "pi-typesafe".
+export { default } from "../dist/extension.js";

package/port/oracle/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "pi-typesafe",
+  "version": "0.8.0",
+  "description": "TypeSafe AI (Jev) decisions for Pi: batched Choice/Score/Noul evaluation tool, terminal playground, and a typed API other extensions build on.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ryan Gapac",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DevMortimer/pi-typesafe.git"
+  },
+  "homepage": "https://github.com/DevMortimer/pi-typesafe#readme",
+  "bugs": "https://github.com/DevMortimer/pi-typesafe/issues",
+  "funding": "https://github.com/sponsors/DevMortimer",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "typesafe",
+    "jev",
+    "structured-decisions"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./extension": {
+      "types": "./dist/extension.d.ts",
+      "import": "./dist/extension.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "import": "./dist/ui.js"
+    },
+    "./calibrate": {
+      "types": "./dist/calibrate.d.ts",
+      "import": "./dist/calibrate.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "extensions",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.js"
+    ],
+    "image": "https://raw.githubusercontent.com/DevMortimer/pi-typesafe/main/docs/preview.png"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "test:live": "node --env-file=.env scripts/live-smoke.mjs",
+    "dev:pi": "node scripts/dev-pi.mjs",
+    "check": "npm run build && npm run typecheck && npm test",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@typesafe-ai/sdk": "^0.6.0",
+    "typebox": "^1.3.31"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.85.1 <1",
+    "@earendil-works/pi-tui": ">=0.85.1 <1"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.86.1",
+    "@earendil-works/pi-tui": "^0.86.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
+  }
+}

package/port/oracle/scripts/dev-pi.mjs

@@ -0,0 +1,23 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { loadEnvFile } from 'node:process';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+// Optional: a private .env can supply TYPESAFE_API_KEY; otherwise use /typesafe login inside Pi.
+try {
+  loadEnvFile(join(root, '.env'));
+} catch {
+  // No .env present; the stored key from /typesafe login (if any) is used.
+}
+// --no-extensions keeps an installed pi-typesafe (or other extensions) from loading alongside the working tree.
+const child = spawn('pi', ['--no-extensions', '-e', root, ...process.argv.slice(2)], {
+  cwd: root,
+  env: process.env,
+  stdio: 'inherit',
+});
+child.on('error', () => {
+  console.error('Could not start Pi. Install the Pi CLI and make it available on PATH.');
+  process.exitCode = 1;
+});
+child.on('exit', code => { process.exitCode = code ?? 1; });

package/port/oracle/scripts/live-smoke.mjs

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict';
+import { createTypeSafe, choice, noul, score } from '../dist/index.js';
+
+// One explicitly requested, billable call with synthetic data only.
+try {
+  const client = createTypeSafe({ maxRequests: 1 });
+  const result = await client.evaluate({
+    state: { message: 'I was charged twice for my subscription. Please help today.' },
+    questions: {
+      category: choice('Which team should handle this message?', {
+        billing: 'Charges and payments', technical: 'Software failures', other: 'None of these',
+      }),
+      urgent: noul('Does the sender request help today?'),
+      frustration: score('How frustrated does the sender sound?', [
+        'A neutral request without expressed frustration',
+        'Expressed frustration while remaining civil',
+        'Explicit anger or threats',
+      ]),
+    },
+  });
+  assert.equal(result.answers.category.choice, 'billing');
+  assert.ok(result.answers.urgent.noul > 0.5);
+  assert.ok(result.answers.frustration.score >= 0 && result.answers.frustration.score <= 2);
+  assert.equal(client.getUsage().requestsStarted, 1);
+  console.log(JSON.stringify({
+    passed: true, model: result.model, elapsedMs: result.elapsedMs, usage: result.usage,
+    category: result.answers.category.choice,
+    urgent: result.answers.urgent.noul,
+    frustration: result.answers.frustration.score,
+  }, null, 2));
+} catch (error) {
+  // Do not dump errors, request bodies, environment, or stacks containing credentials.
+  console.error(JSON.stringify({ passed: false, code: error?.code ?? 'assertion-or-configuration', status: error?.status }));
+  process.exitCode = 1;
+}

package/port/oracle/src/ask.ts

@@ -0,0 +1,42 @@
+import type { Questions, SystemOneRequest } from "@typesafe-ai/sdk";
+import type { Evaluation, TypeSafe } from "./client.js";
+import { TypeSafeIntegrationError } from "./errors.js";
+import type { IntegrationErrorCode } from "./errors.js";
+
+/** Anything with pi-typesafe's `evaluate`: the real client in a session, a stub in tests. */
+export type Judge = Pick<TypeSafe, "evaluate">;
+
+/** Default per-ask deadline; matches the client's own request timeout. */
+export const DEFAULT_ASK_TIMEOUT_MS = 15_000;
+
+const FALLBACK_MESSAGE = "TypeSafe request failed.";
+
+export interface AskOptions {
+  /** Per-ask deadline, merged with the caller's own signal. Default: DEFAULT_ASK_TIMEOUT_MS. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export type AskAnswer<Q extends Questions> =
+  | { readonly ok: true; readonly answers: Evaluation<Q>["answers"]; readonly model: string; readonly usage: Evaluation<Q>["usage"]; readonly elapsedMs: number }
+  | { readonly ok: false; readonly error: string; readonly errorCode?: IntegrationErrorCode };
+
+/**
+ * One typed Jev request that never throws: a failure comes back as `{ ok: false }` with pi-typesafe's own message
+ * (which carries no upstream body, header, key, or submitted state) and its code, so a caller can stop asking after a
+ * `budget` error. The per-ask timeout is merged into the caller's signal, so either can cancel the request.
+ *
+ * This is the author-facing "ask Jev" seam. Agents get the same admission through the `typesafe_evaluate` tool; the two
+ * share `prepareEvaluationRequest`, so what one accepts the other accepts.
+ */
+export async function ask<Q extends Questions>(judge: Judge, request: SystemOneRequest<Q>, options: AskOptions = {}): Promise<AskAnswer<Q>> {
+  const timeout = AbortSignal.timeout(options.timeoutMs ?? DEFAULT_ASK_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+  try {
+    const result = await judge.evaluate(request, { signal });
+    return { ok: true, answers: result.answers, model: result.model, usage: result.usage, elapsedMs: result.elapsedMs };
+  } catch (error) {
+    if (error instanceof TypeSafeIntegrationError) return { ok: false, error: error.message, errorCode: error.code };
+    return { ok: false, error: FALLBACK_MESSAGE };
+  }
+}