@herbertgao/pi-extensions 2026.9.7 → 2026.9.9

package/node_modules/pi-lens/dist/tools/lens-diagnostic-mark.js

@@ -45,8 +45,9 @@ import * as path from "node:path";
 import { Type } from "../clients/deps/typebox.js";
 import { markDisposition, normalizeMessage, } from "../clients/diagnostic-dispositions.js";
 import { insertSuppressComment } from "../clients/dispatch/suppress-writer.js";
-import { getFileDiagnostics, } from "../clients/widget-state.js";
+import { normalizeMapKey } from "../clients/path-utils.js";
 import { resolveLensToolName } from "../clients/tool-config.js";
+import { getFileDiagnostics, } from "../clients/widget-state.js";
 const DISPOSITIONS = [
     "false-positive",
     "suppress",
@@ -70,11 +71,22 @@ function isBlank(text) {
  * violation) are ambiguous; per #802 this picks the match CLOSEST to the
  * caller's line rather than guessing — the conservative choice for suppress,
  * which must never place a comment above the wrong site.
+ *
+ * #3160: `getFileDiagnostics` keys with `normalizeEphemeralMapKey` — case-
+ * preserving on POSIX by design (no filesystem I/O on that hot path) — but
+ * the widget's own writers key from `ctx.filePath`, which
+ * `createDispatchContext` already canonicalizes to the on-disk casing
+ * (#2016/#3098). `absPath` here is the caller's RAW spelling, so on a
+ * case-insensitive filesystem a mis-cased mark call must derive the same
+ * canonical key the writers used or it silently misses the live diagnostic
+ * and falls through to the fuzzy fallback below — do NOT case-fold
+ * `normalizeEphemeralMapKey` itself for this: on a case-sensitive filesystem
+ * that would merge two genuinely different files.
  */
 function widgetCrossCheck(absPath, tool, rule, message, callerLine) {
     let diagnostics;
     try {
-        diagnostics = getFileDiagnostics(absPath);
+        diagnostics = getFileDiagnostics(normalizeMapKey(absPath));
     }
     catch {
         return undefined;

package/node_modules/pi-lens/dist/tools/lens-diagnostics.js

@@ -18,13 +18,13 @@ import { DEPENDENCY_DRIFT_MAX_DELIVERIES } from "../clients/blocker-freshness.js
 import { freshnessFromMtime } from "../clients/freshness.js";
 import { applyFindingPolicy, loadProjectRulePolicyMap, } from "../clients/dispatch/finding-policy.js";
 import { gateFindingsByPathFreshness } from "../clients/advisory-provenance.js";
-import { markUnreconciledFindings } from "../clients/finding-delivery-gate.js";
+import { formatCacheAgeLabel, markUnreconciledFindings, } from "../clients/finding-delivery-gate.js";
 import { normalizeRuleId } from "../clients/dispatch/rule-id-normalize.js";
 import { applyRulePolicy, } from "../clients/dispatch/rule-policy.js";
 import { compactRenderResult } from "./render-compact.js";
 import { combineAbortSignals } from "../clients/deadline-utils.js";
 import { getProjectIgnoreMatcher } from "../clients/file-utils.js";
-import { isAtOrAboveHomeDir, normalizeEphemeralMapKey, normalizeFilePath, realpathOrResolve, } from "../clients/path-utils.js";
+import { isAtOrAboveHomeDir, normalizeEphemeralMapKey, normalizeFilePath, normalizeMapKey, realpathOrResolve, } from "../clients/path-utils.js";
 import { getLSPService } from "../clients/lsp/index.js";
 import { retireInlineBlockerAndResyncGuard } from "../clients/git-guard.js";
 import { primaryServerId, resolveLspCwdForFile, } from "../clients/lsp/config.js";
@@ -508,7 +508,7 @@ function formatProjectDeltaDiagnostic(diagnostic, stale) {
  * rule/message), live -> unchanged. See `clients/finding-delivery-gate.ts`
  * surface `lens-diagnostics:mode-delta`.
  */
-function appendProjectDiagnosticsDeltaLines(lines, cwd, report, severity, includeFile) {
+function appendProjectDiagnosticsDeltaLines(groups, cwd, report, severity, includeFile) {
     const scoped = (report?.diagnostics ?? []).filter((diagnostic) => includeFile(diagnostic.filePath) &&
         matchesSeverity(projectDiagnosticToWidget(diagnostic, diagnostic.filePath), severity));
     const gated = gateFindingsByPathFreshness({
@@ -532,11 +532,9 @@ function appendProjectDiagnosticsDeltaLines(lines, cwd, report, severity, includ
         byFile.set(filePath, bucket);
     }
     for (const [filePath, fileDiagnostics] of byFile) {
-        const rel = path.relative(cwd, filePath);
-        if (!lines.includes(rel))
-            lines.push(rel);
+        const group = getDeltaFileGroup(groups, cwd, filePath);
         for (const diagnostic of fileDiagnostics) {
-            lines.push(formatProjectDeltaDiagnostic(diagnostic, staleSet.has(diagnostic)));
+            group.projectLines.push(formatProjectDeltaDiagnostic(diagnostic, staleSet.has(diagnostic)));
         }
     }
     return diagnostics.length;
@@ -723,7 +721,15 @@ function applyDeltaFreshnessGate(files, cwd, generatedAt) {
     }
     for (const f of gated.stale) {
         const arr = byFile.get(f.filePath) ?? [];
-        arr.push({ ...f.warning, stale: true, line: undefined });
+        // Fix B (#3167): carry the stamp the row was judged against so the render
+        // can emit one age label per file group — the row's own observation stamp,
+        // not the report-level one (the #2504 r4 multi-stamp case).
+        arr.push({
+            ...f.warning,
+            stale: true,
+            line: undefined,
+            staleAsOf: effectiveAt,
+        });
         byFile.set(f.filePath, arr);
     }
     return files
@@ -733,10 +739,34 @@ function applyDeltaFreshnessGate(files, cwd, generatedAt) {
     }))
         .filter((file) => file.warnings.length > 0);
 }
+function getDeltaFileGroup(groups, cwd, filePath) {
+    const rel = path.relative(cwd, filePath);
+    let group = groups.get(rel);
+    if (!group) {
+        group = {
+            rel,
+            actionableLines: [],
+            qualityLines: [],
+            projectLines: [],
+            incomplete: false,
+        };
+        groups.set(rel, group);
+    }
+    return group;
+}
 // @delivery-surface: lens-diagnostics:mode-delta
 function formatDeltaMode(cacheManager, cwd, severity, pathsScope) {
     const actionableEntry = cacheManager.readCache("actionable-warnings", cwd);
     const qualityEntry = cacheManager.readCache("code-quality-warnings", cwd);
+    // #3170: files whose re-verify pass could not complete inside its budget —
+    // their rows render as carried, plus this explicit gap label (never a
+    // false clean). Computed from the RAW actionable-warnings cache entries
+    // because the freshness pipeline below rebuilds the file shape. The
+    // re-verify only ever writes the actionable-warnings cache — the quality
+    // report's file shape carries no such marker.
+    const reverifyIncompletePaths = new Set((actionableEntry?.data?.files ?? [])
+        .filter((file) => file.reVerifyIncomplete)
+        .map((file) => normalizeMapKey(file.filePath)));
     const actionable = actionableEntry?.data;
     const quality = qualityEntry?.data;
     // Project rule policy (`.pi-lens.json` `rules.<id>.disable` /
@@ -778,32 +808,69 @@ function formatDeltaMode(cacheManager, cwd, severity, pathsScope) {
         warnings: matchingWarnings(file.warnings),
     }))
         .filter((file) => file.warnings.length > 0);
-    const lines = [];
+    // #3196: one grouping pass keyed by file — every tier below appends into
+    // the SAME per-file group (see `DeltaFileGroup`/`getDeltaFileGroup`), so a
+    // file present in more than one report always renders its rows under its
+    // own header, wherever that header ends up in the final buffer.
+    const groups = new Map();
     // Fixable warnings from actionable-warnings and quality cache entries retain
     // their own severity tier. Apply the same threshold semantics as the LSP path.
+    // F5/F10 (#3168): at most ONE label group (age and/or #3170's re-verify
+    // gap) per file. The actionable tier is folded first, so its stale row (if
+    // any) wins the group's age label; the quality tier only supplies one when
+    // the actionable tier had none for that file (#3168 F10(c)'s quality-only
+    // shape). The `(re-verify incomplete)` flag is a fact about the file (from
+    // the raw actionable cache, independent of which tier's rows happen to
+    // render it), so it is recorded on the group the first time either tier
+    // touches that file and never predicted.
     if (filteredActionableFiles.length > 0) {
         for (const file of filteredActionableFiles) {
-            const rel = path.relative(cwd, file.filePath);
-            lines.push(`${rel}`);
+            const group = getDeltaFileGroup(groups, cwd, file.filePath);
             for (const w of file.warnings) {
                 const where = w.stale ? STALE_LINE_MARKER : `L${w.line ?? "?"}`;
-                lines.push(`  ⚠ ${where}  ${w.rule ?? w.code ?? w.tool}  ${w.message}`);
+                group.actionableLines.push(`  ⚠ ${where}  ${w.rule ?? w.code ?? w.tool}  ${w.message}`);
+            }
+            const key = normalizeMapKey(file.filePath);
+            if (reverifyIncompletePaths.has(key))
+                group.incomplete = true;
+            if (!group.staleRow) {
+                const staleWarning = file.warnings.find((w) => w.stale);
+                if (staleWarning)
+                    group.staleRow = { staleAsOf: staleWarning.staleAsOf };
             }
         }
     }
     // Quality issues
     if (filteredQualityFiles.length > 0) {
         for (const file of filteredQualityFiles) {
-            const rel = path.relative(cwd, file.filePath);
-            if (!lines.includes(rel))
-                lines.push(rel);
+            const group = getDeltaFileGroup(groups, cwd, file.filePath);
             for (const w of file.warnings) {
                 const where = w.stale ? STALE_LINE_MARKER : `L${w.line ?? "?"}`;
-                lines.push(`  ℹ ${where}  ${w.rule ?? w.code ?? w.tool}  ${w.message}`);
+                group.qualityLines.push(`  ℹ ${where}  ${w.rule ?? w.code ?? w.tool}  ${w.message}`);
+            }
+            const key = normalizeMapKey(file.filePath);
+            if (reverifyIncompletePaths.has(key))
+                group.incomplete = true;
+            if (!group.staleRow) {
+                const staleWarning = file.warnings.find((w) => w.stale);
+                if (staleWarning)
+                    group.staleRow = { staleAsOf: staleWarning.staleAsOf };
             }
         }
     }
-    const projectDeltaCount = appendProjectDiagnosticsDeltaLines(lines, cwd, projectDelta, severity, includeFile);
+    const projectDeltaCount = appendProjectDiagnosticsDeltaLines(groups, cwd, projectDelta, severity, includeFile);
+    const lines = [];
+    for (const group of groups.values()) {
+        lines.push(group.rel);
+        lines.push(...group.actionableLines);
+        lines.push(...group.qualityLines);
+        lines.push(...group.projectLines);
+        if (group.staleRow) {
+            lines.push(`  (${formatCacheAgeLabel(group.staleRow.staleAsOf)})`);
+        }
+        if (group.incomplete)
+            lines.push("  (re-verify incomplete)");
+    }
     const selectedActionableFiles = filteredActionableFiles;
     const selectedQualityFiles = filteredQualityFiles;
     const aw = selectedActionableFiles.reduce((count, file) => count + file.warnings.length, 0);

package/node_modules/pi-lens/dist/tools/lsp-diagnostics.js

@@ -23,7 +23,8 @@ import { classifyCascadeWaitTier } from "../clients/lsp/wait-policy/index.js";
 import { attemptTsserverSyncDiagnostics } from "../clients/lsp/tsserver-sync.js";
 import { convertLspDiagnostics } from "../clients/dispatch/utils/lsp-diagnostics.js";
 import { demoteInferredProjectDiagnostics } from "../clients/lsp/inferred-project.js";
-import { isBlocking, reconcileScanDiagnostics, } from "../clients/widget-state.js";
+import { normalizeMapKey } from "../clients/path-utils.js";
+import { countRetainedSuppressedRows, isBlocking, reconcileScanDiagnostics, } from "../clients/widget-state.js";
 import { makeProgressReporter } from "./scan-progress.js";
 import { isWarmAttached, tryWarmAttachedDiagnostics, } from "../clients/warm-attach.js";
 import { extensionsForLanguage, SCAN_LANGUAGE_PRIORITY, } from "../clients/language-registry.js";
@@ -239,7 +240,18 @@ onConfirmedNoBlockers, getService = getLSPService) {
                 // Preserve input order (including duplicate entries); normalize each
                 // path before grouping so Windows separators and dot segments cannot
                 // change cache/group identity. Explicit lists never enter the walker.
-                const absPaths = rawPaths.map((entry) => path.normalize(path.isAbsolute(entry) ? entry : path.resolve(cwd, entry)));
+                // #3160/#3182: `path.resolve(cwd, entry)` folds dot segments (and
+                // separators) structurally — it ignores `cwd` whenever `entry` is
+                // already absolute, so the old `path.isAbsolute` ternary is
+                // redundant. `normalizeMapKey` then adopts on-disk CASING where the
+                // path exists — an agent-typed, possibly mis-cased `paths` entry
+                // must key `reconcileScanDiagnostics`'s widget-state write the same
+                // way a canonical writer (clients/pipeline.ts's ctx.filePath) or the
+                // #3160-fixed lens_diagnostic_mark reader would. `path.resolve`
+                // stays required for the relative→absolute step: `normalizeMapKey`
+                // folds dot segments itself since #3184, but never resolves against
+                // `cwd` (a cwd fold there broke every monorepo, #2490).
+                const absPaths = rawPaths.map((entry) => normalizeMapKey(path.resolve(cwd, entry)));
                 return runBatchFileDiagnostics(absPaths, severity, lspService, {
                     concurrency,
                     waitMs,
@@ -264,9 +276,12 @@ onConfirmedNoBlockers, getService = getLSPService) {
                     details: {},
                 };
             }
-            const absPath = path.isAbsolute(rawPath)
-                ? rawPath
-                : path.resolve(cwd, rawPath);
+            // #3184: the single-`path` sibling of the `paths` batch above, and
+            // keyed the same way — `runFileDiagnostics` hands this straight to
+            // `reconcileScanDiagnostics`, whose `normalizeEphemeralMapKey` key
+            // derivation folds neither dot segments nor casing. Same expression as
+            // :444 so both modes of this tool write under ONE key per file.
+            const absPath = normalizeMapKey(path.resolve(cwd, rawPath));
             let stat;
             try {
                 stat = fs.statSync(absPath);
@@ -616,6 +631,17 @@ severity) {
             // otherwise have SEEN, never one per finding (AGENTS.md "bounded
             // observability"). `total` is the in-scope population for the same
             // reason the count is, so the record and the rendered line agree.
+            //
+            // #3158 round 2 F4: `retainedSuppressed` is the widget store's
+            // SUCCESS-path number — how many suppressed rows the store is carrying
+            // INTO this scan, written by the scans before it. Until this, retention
+            // was observable only when its per-file cap truncated
+            // (`widget-suppressed-retention-capped`), so a healthy footer chip had no
+            // record behind it at all. Folded into the record this lane already emits
+            // rather than added as a second one: same cardinality (one per filtered
+            // file per scan, never one per row), no new sink, and the two numbers are
+            // read together — `suppressed` is what THIS scan dropped,
+            // `retainedSuppressed` is what the footer chip is still counting.
             logLatency({
                 type: "phase",
                 toolName: "lsp_diagnostics",
@@ -625,6 +651,7 @@ severity) {
                 metadata: {
                     suppressed,
                     total: inScopeBefore,
+                    retainedSuppressed: countRetainedSuppressedRows(file),
                 },
             });
         }

package/node_modules/pi-lens/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "4.2.0",
+	"version": "4.2.1",
 	"type": "module",
 	"description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
 	"repository": {

package/node_modules/pi-typesafe/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/node_modules/pi-typesafe/README.md

@@ -0,0 +1,153 @@
+# pi-typesafe
+
+[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. 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 install
+npm run check        # typecheck, offline tests, build
+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)
+```
+
+## License
+
+MIT

package/node_modules/pi-typesafe/dist/ask.d.ts

@@ -0,0 +1,32 @@
+import type { Questions, SystemOneRequest } from "@typesafe-ai/sdk";
+import type { Evaluation, TypeSafe } from "./client.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 declare const DEFAULT_ASK_TIMEOUT_MS = 15000;
+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 declare function ask<Q extends Questions>(judge: Judge, request: SystemOneRequest<Q>, options?: AskOptions): Promise<AskAnswer<Q>>;

package/node_modules/pi-typesafe/dist/ask.js

@@ -0,0 +1,25 @@
+import { TypeSafeIntegrationError } from "./errors.js";
+/** 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.";
+/**
+ * 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(judge, request, options = {}) {
+    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 };
+    }
+}

package/node_modules/pi-typesafe/dist/auth.d.ts

@@ -0,0 +1,56 @@
+import type { KeySource } from "./credentials.js";
+import { TypeSafeIntegrationError } from "./errors.js";
+import type { IntegrationErrorCode } from "./errors.js";
+/** The last request that degraded TypeSafe, with no upstream body, header, key, or submitted state. */
+export interface AuthFailure {
+    readonly code: IntegrationErrorCode;
+    readonly status?: number;
+    readonly message: string;
+    readonly at: string;
+}
+/**
+ * The whole answer to "is Jev actually available right now": which key is in effect, whether it has been accepted, and
+ * the last failure that degraded it. Consumers must consult this instead of treating their own consent flag as proof
+ * that judgments will happen — an enabled extension with no key used to look identical to a working one.
+ */
+export interface AuthState {
+    /** Same kinds as KeySituation: where the key in effect comes from. */
+    readonly kind: "environment" | "stored" | "missing" | "unusable";
+    readonly source?: KeySource;
+    /** Where the key would be read from. */
+    readonly path: string;
+    /** Why a stored key cannot be used, when that is the case. */
+    readonly reason?: string;
+    /** Short human label for the key source: `TYPESAFE_API_KEY`, `/typesafe login`, `no key`, `unusable key`. */
+    readonly keyName: string;
+    /** True when the key in effect was accepted by api.typesafe.ai (login verifies it; a successful request proves it). */
+    readonly verified: boolean;
+    readonly verifiedAt?: string;
+    /** The last failure, cleared by the next successful request. */
+    readonly lastFailure?: AuthFailure;
+    /** A key is present and the last authentication outcome was not a rejection. False means judgments are skipped. */
+    readonly usable: boolean;
+}
+/** The auth-state file: one small, owner-only record that outlives the process that wrote it. */
+export declare function authStatePath(): string;
+/** What the key situation, the last outcome, and the clock add up to. Never throws. */
+export declare function authState(options?: {
+    path?: string;
+}): AuthState;
+/** Record that the key was accepted: login verification, or any successful request. Clears the last failure. */
+export declare function recordAuthVerified(at?: Date): void;
+/** Record the failure that degraded TypeSafe. The verification timestamp is kept so a recovered key stays known. */
+export declare function recordAuthFailure(error: TypeSafeIntegrationError, at?: Date): void;
+/** Forget verification and degradation: used when the key itself changes (login or logout). */
+export declare function clearAuthState(): void;
+export interface AuthReport {
+    /** `error` when judgments are skipped or were rejected, `warning` when the key is unverified, otherwise `ok`. */
+    readonly level: "ok" | "warning" | "error";
+    /** One line naming the key source and, when degraded, the reason. Safe to display. */
+    readonly text: string;
+}
+/**
+ * One line plus a level, so a status command, a headless log, or a consumer's own status line can call out a degraded
+ * state instead of reporting "enabled".
+ */
+export declare function describeAuth(state?: AuthState): AuthReport;