specpi 0.27.0 → 0.29.0

package/extensions/jev-advisor/index.ts

@@ -1,11 +1,12 @@
 import fs from "node:fs";
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { SYSTEM_NAMES, keyPresent, loadSettings, saveSettings, settingsPath } from "./config.mjs";
+import { SYSTEM_NAMES, loadSettings, saveSettings, settingsPath } from "./config.mjs";
+import { keySources } from "./key-source.mjs";
+import { applyLayer, layerScopeLine, layerToPersist, startupToPersist } from "./layer.mjs";
 import { consentPath, granted, revokeConsent } from "./consent.mjs";
 import { createBroker } from "./broker.mjs";
 import { ledgerPath, read as readLedger } from "./ledger.mjs";
 import { usagePath } from "./usage.mjs";
-import { applyConfig as applyGuardConfig, statusLine as guardStatusLine } from "./guard.mjs";
 import * as retention from "./questions/retention.mjs";
 import * as compaction from "./questions/compaction.mjs";
 import * as gap from "./questions/gap.mjs";
@@ -70,14 +71,12 @@ export default function jevAdvisor(pi: ExtensionAPI) {
     let capabilityAsked = false;
     const capabilityDeclined = new Set<string>();
 
-    let guardEnabled = false;
-    const syncGuard = () => {
+    /** Persist the session's switches, or report that it could not be done. */
+    const persistLayer = (result: { settings: any }) => {
         try {
-            return applyGuardConfig(guardEnabled);
+            return saveSettings(layerToPersist(result, loadSettings()));
         } catch {
-            // A guard that cannot be reconfigured keeps whatever posture it has, which
-            // /jev status reports rather than hides.
-            return { applied: false, reason: "unwritable" };
+            return undefined;
         }
     };
 
@@ -92,12 +91,6 @@ export default function jevAdvisor(pi: ExtensionAPI) {
         resetHistory();
         capabilityAsked = false;
         capabilityDeclined.clear();
-        guardEnabled = settings.guard.startup === true;
-        // Deliberately outside the master switch. The guard is a separate package with its own
-        // gate, and whether it is inert is a property of the install rather than a feature of the
-        // advisor, so its configuration is rewritten every session either way. Off is the default
-        // and is a real written configuration, not an absence of one.
-        syncGuard();
     });
 
     pi.on("session_shutdown", () => {
@@ -251,6 +244,15 @@ export default function jevAdvisor(pi: ExtensionAPI) {
             }
         }
 
+        // Every result, not only the ones retention asked about. It was written in one place --
+        // inside retention's success path -- so a session with retention off, or with retention's
+        // budget spent, handed every other system an empty history for its whole length while
+        // their question sets said history was what they weighed.
+        recent.push({ tool: String(event?.toolName ?? ""), outcome: event?.isError === true ? "error" : "ok" });
+        if (recent.length > MAX_RECENT) {
+            recent.shift();
+        }
+
         // Two systems share this hook. Retention wants large read-only results; system 7 wants
         // externally fetched ones whatever their size, because an injected instruction can be two
         // hundred bytes. When both want the same result they are one call: questions are evaluated
@@ -310,11 +312,12 @@ export default function jevAdvisor(pi: ExtensionAPI) {
             }
 
             const { verdict, replacement } = result.decision;
-            if (wantRetention) {
-                recent.push({ tool: event.toolName, outcome: verdict.elide ? "spent" : "kept" });
-                if (recent.length > MAX_RECENT) {
-                    recent.shift();
-                }
+            // Retention knows something the bookkeeping above does not -- whether the result was
+            // spent -- so it refines its own entry rather than appending a second one for the same
+            // call. If anything has been recorded since, the entry is gone and so is the chance.
+            const latest = recent[recent.length - 1];
+            if (wantRetention && latest?.tool === event.toolName) {
+                latest.outcome = verdict.elide ? "spent" : "kept";
             }
 
             if (replacement === undefined) {
@@ -653,7 +656,7 @@ export default function jevAdvisor(pi: ExtensionAPI) {
     pi.registerCommand("jev", {
         description: "Show or change the Jev advisor: master switch, per-system switches and the transmission ledger",
         getArgumentCompletions: (prefix: string) =>
-            ["status", "on", "off", "startup", "enable", "disable", "guard", "ledger", "forget"]
+            ["status", "on", "off", "startup", "enable", "disable", "ledger", "forget"]
                 .filter((value) => value.startsWith(prefix.trim().toLowerCase()))
                 .map((value) => ({ value, label: value })),
         handler: async (args: string, ctx: ExtensionContext) => {
@@ -661,14 +664,33 @@ export default function jevAdvisor(pi: ExtensionAPI) {
             const action = actionRaw.toLowerCase();
             try {
                 if (action === "on" || action === "off") {
-                    settings = { ...settings, master: action === "on" };
-                    const active = SYSTEM_NAMES.filter((name) => settings.systems[name]);
-                    ctx.ui.notify(
-                        action === "on"
-                            ? `Jev advisor on for this session with ${active.length} of ${SYSTEM_NAMES.length} systems enabled${active.length === 0 ? " (enable one with /jev enable <system>)" : `: ${active.join(", ")}`}.`
-                            : "Jev advisor off for this session. No state leaves this machine.",
-                        "info",
-                    );
+                    const on = action === "on";
+                    // `--session` is the old behaviour, kept for the case it was the right one: a
+                    // one-off try that must not change what the next session does.
+                    const sessionOnly = rest.some((value) => /^--?(session|once)$/u.test(value.toLowerCase()));
+                    const unknown = rest.filter((value) => !/^--?(session|once)$/u.test(value.toLowerCase()));
+                    if (unknown.length > 0) {
+                        throw new Error(`Usage: /jev ${action} [--session]`);
+                    }
+
+                    const result = applyLayer({ on }, { settings }, { keySources: () => keySources() });
+                    settings = result.settings;
+                    // Persisting is the default because a switch that forgets is not a switch. The
+                    // old rule -- that only /jev startup may write -- protected against a session
+                    // toggle silently changing tomorrow's sessions, but the cost of that protection
+                    // was a layer people turned on repeatedly and never actually ran.
+                    const persisted = !sessionOnly && ctx.hasUI ? persistLayer(result) : undefined;
+                    const lines = [
+                        ...result.lines,
+                        layerScopeLine({
+                            sessionOnly,
+                            interactive: ctx.hasUI,
+                            persisted,
+                            stored: loadSettings(),
+                            settingsFile: settingsPath(),
+                        }),
+                    ];
+                    ctx.ui.notify(lines.join("\n"), "info");
 
                     return;
                 }
@@ -680,14 +702,41 @@ export default function jevAdvisor(pi: ExtensionAPI) {
                         throw new Error(`Usage: /jev ${action} <${SYSTEM_NAMES.join("|")}>`);
                     }
 
-                    const systems = { ...settings.systems };
-                    for (const name of names) {
-                        systems[name] = action === "enable";
-                    }
-
-                    settings = { ...settings, systems };
+                    const changes = Object.fromEntries(names.map((name) => [name, action === "enable"]));
+                    const systems = { ...settings.systems, ...changes };
+                    // Disabling the last system while the layer is on leaves it running and doing
+                    // nothing -- the state `enableSystems`, `startupToPersist`, `couple` and the
+                    // Chat panel's save check all exist to prevent, reachable through the one path
+                    // that did not check it. Switching the layer off is the honest reading of
+                    // "disable everything", and it is announced rather than inferred.
+                    const emptied = settings.master && SYSTEM_NAMES.every((name) => !systems[name]);
+                    settings = { ...settings, systems, master: emptied ? false : settings.master };
+                    // Persisted like every other switch here, and merged into the stored map rather
+                    // than overwriting it: this session's copy may predate systems enabled on disk
+                    // since it started, and writing it whole turned those back off silently.
+                    const kept = ctx.hasUI
+                        ? (() => {
+                              try {
+                                  const current = loadSettings();
+                                  const merged = { ...current.systems, ...changes };
+                                  const dead = current.master && SYSTEM_NAMES.every((name) => !merged[name]);
+
+                                  return saveSettings({
+                                      ...current,
+                                      systems: merged,
+                                      master: dead ? false : current.master,
+                                      startup: dead ? false : current.startup,
+                                  });
+                              } catch {
+                                  return undefined;
+                              }
+                          })()
+                        : undefined;
                     ctx.ui.notify(
-                        `${action === "enable" ? "Enabled" : "Disabled"} for this session: ${names.join(", ")}.${settings.master ? "" : " The master switch is still off; run /jev on."}`,
+                        `${action === "enable" ? "Enabled" : "Disabled"}: ${names.join(", ")}.` +
+                            `${kept ? " Remembered for new sessions." : " This session only."}` +
+                            `${emptied ? " That was the last system, so the layer was switched off; it would otherwise run and do nothing." : ""}` +
+                            `${!emptied && !settings.master ? " The layer is still off; run /jev on." : ""}`,
                         "info",
                     );
 
@@ -697,8 +746,9 @@ export default function jevAdvisor(pi: ExtensionAPI) {
                 if (action === "startup") {
                     const [choice] = rest;
                     if (!choice) {
+                        const current = loadSettings();
                         ctx.ui.notify(
-                            `Jev starts ${loadSettings().startup ? "on" : "off"} in new sessions. Preference: ${settingsPath()}`,
+                            `Jev starts ${current.startup && current.master ? "on" : "off"} in new sessions. Preference: ${settingsPath()}`,
                             "info",
                         );
 
@@ -713,70 +763,20 @@ export default function jevAdvisor(pi: ExtensionAPI) {
                         throw new Error("Usage: /jev startup [on|off]");
                     }
 
-                    const saved = saveSettings({ ...loadSettings(), startup: choice.toLowerCase() === "on" });
-                    ctx.ui.notify(
-                        saved.startup
-                            ? "New Pi sessions will start with the Jev advisor on. This session is unchanged."
-                            : "New Pi sessions will start with the Jev advisor off. This session is unchanged.",
-                        "info",
-                    );
-
-                    return;
-                }
-
-                if (action === "guard") {
-                    const [verb, choice] = rest.map((value) => value.toLowerCase());
-                    if (!verb) {
-                        ctx.ui.notify(guardStatusLine(), "info");
-
-                        return;
-                    }
-
-                    if (verb === "on" || verb === "off") {
-                        guardEnabled = verb === "on";
-                        const result = syncGuard();
-                        ctx.ui.notify(
-                            result.reason === "not-installed"
-                                ? "specpi-jev-guard is not installed, so there is nothing to switch. Command policy stays with the permission system."
-                                : guardEnabled
-                                  ? "Jev guard on for this session. It scores shell and file calls and defers to the permission system whenever Jev is unavailable or unconfident."
-                                  : "Jev guard off for this session. Every tool call goes straight to the permission system.",
-                            "info",
-                        );
-
-                        return;
-                    }
-
-                    if (verb !== "startup") {
-                        throw new Error("Usage: /jev guard [on|off|startup [on|off]]");
-                    }
-
-                    if (!choice) {
-                        ctx.ui.notify(
-                            `The Jev guard starts ${loadSettings().guard.startup ? "on" : "off"} in new sessions.`,
-                            "info",
-                        );
-
-                        return;
-                    }
-
-                    if (!ctx.hasUI) {
-                        throw new Error("Startup changes require a human interactive command");
-                    }
-
-                    if (!["on", "off"].includes(choice)) {
-                        throw new Error("Usage: /jev guard startup [on|off]");
-                    }
-
-                    const stored = loadSettings();
-                    const saved = saveSettings({
-                        ...stored,
-                        guard: { ...stored.guard, startup: choice === "on" },
-                    });
+                    // Both keys, and the systems with them. Writing `startup` alone was the whole
+                    // two-keys-for-one-intention trap, left in the command named after it: the
+                    // advisor's session_start keeps a stored `master` only when `startup` is true,
+                    // so `startup: true, master: false` starts every future session with the layer
+                    // off while this command cheerfully reported it would start on. And a layer
+                    // that starts on with no system enabled runs and does nothing, so the same rule
+                    // `/jev on` uses applies here: fill them in only when none are chosen.
+                    const wanted = choice.toLowerCase() === "on";
+                    const saved = saveSettings(startupToPersist(wanted, loadSettings()));
+                    const enabled = SYSTEM_NAMES.filter((name) => saved.systems[name]);
                     ctx.ui.notify(
-                        saved.guard.startup
-                            ? "New Pi sessions will start with the Jev guard on. This session is unchanged."
-                            : "New Pi sessions will start with the Jev guard off. This session is unchanged.",
+                        saved.startup && saved.master
+                            ? `New Pi sessions will start with the Jev layer on, with ${enabled.length} of ${SYSTEM_NAMES.length} systems: ${enabled.join(", ")}. This session is unchanged; run /jev on to switch it on now.`
+                            : "New Pi sessions will start with the Jev layer off. This session is unchanged.",
                         "info",
                     );
 
@@ -817,21 +817,29 @@ export default function jevAdvisor(pi: ExtensionAPI) {
 
                 if (action !== "status") {
                     throw new Error(
-                        "Usage: /jev [status|on|off|startup [on|off]|enable <system>|disable <system>|guard [on|off|startup [on|off]]|ledger [n]|forget]",
+                        "Usage: /jev [status|on [--session]|off [--session]|startup [on|off]|enable <system>|disable <system>|ledger [n]|forget]",
                     );
                 }
 
                 const state = broker.status();
+                const sources = keySources();
+                const activeSource = sources.find((source: { present: boolean }) => source.present)?.name;
+                const stored = loadSettings();
                 const lines = [
-                    `master: ${settings.master ? "on" : "off"} (new sessions start ${loadSettings().startup ? "on" : "off"})`,
+                    `master: ${settings.master ? "on" : "off"} (new sessions start ${stored.startup && stored.master ? "on" : "off"})`,
                     ...SYSTEM_NAMES.map((name) => `  ${name}: ${settings.systems[name] ? "on" : "off"}`),
-                    // Both names, because the default route is OpenRouter and naming only the
-                    // other one sends a reader to set the key that returns a bare 401.
-                    `key: ${keyPresent() ? "present" : "missing"} (OPENROUTER_API_KEY, or TYPESAFE_API_KEY with JEV_BACKEND=typesafe)`,
+                    // Every place a key could come from, in the order they are consulted, with the
+                    // one in force marked. A bare "missing" was actively misleading here: it is
+                    // what someone saw who had a perfectly good OpenRouter key stored by /login,
+                    // and it gave them nothing to act on. Names only -- no key is ever printed.
+                    `key: ${activeSource ? `in use from ${activeSource}` : "none found"}`,
+                    ...sources.map(
+                        (source: { name: string; label: string; detail: string; present: boolean }) =>
+                            `  ${source.present ? "found" : "   - "} ${source.label} (${source.detail})`,
+                    ),
                     `consent: ${granted() ? "granted" : "not granted"}`,
                     `calls this session: ${state.callsUsed}/${state.budgets.total} total`,
                     ...SYSTEM_NAMES.map((name) => `  ${name}: ${state.usedBySystem[name] ?? 0}/${state.budgets[name]}`),
-                    guardStatusLine(),
                     `settings: ${settingsPath()}`,
                     `consent file: ${consentPath()}`,
                     `ledger: ${ledgerPath()}`,

package/extensions/jev-advisor/key-source.mjs

@@ -0,0 +1,252 @@
+// Where the Jev layer's key comes from, and the one place that answers it.
+//
+// This file exists because the layer used to answer it wrongly. Jev read `OPENROUTER_API_KEY` from
+// the environment and nothing else, while Pi itself had already resolved an OpenRouter credential
+// for the session through `/login openrouter` and stored it where every other provider stores one.
+// The result was a layer that reported "key: missing" to someone who had a working OpenRouter key
+// sitting in `auth.json`, with no interface anywhere that would have explained the gap. Reading the
+// credential Pi already has is not a new integration; it is stopping an old one from opting out.
+//
+// Pi's documented resolution order (docs/providers.md, "Resolution Order") is:
+//
+//   1. the `--api-key` CLI flag        -- Pi's own, scoped to Pi's model calls, not ours
+//   2. `<agent-dir>/auth.json`         -- what `/login` writes
+//   3. the provider environment variable
+//   4. custom provider keys in models.json
+//
+// We implement 2 then 3, in that order, so a person who has logged in once is served and a person
+// who exports the variable is still served. Step 1 is Pi's alone and step 4 describes provider
+// catalogue entries the decisions endpoint has no equivalent of.
+//
+// Two rules hold everywhere below.
+//
+// The key is returned by exactly one function, `resolveKey()`, and callers pass it straight to a
+// request header. Nothing else here ever sees the value: `keySource()` returns a label so status
+// output, the Chat panel and the ledger can say where a key came from without any of them being a
+// place a key could leak from. That split is the whole reason this is a module rather than two
+// lines in client.mjs.
+//
+// And a missing or malformed credential is never an error. Every failure path returns undefined,
+// the caller reports `unavailable("no-key")`, and the harness does what it did before the layer
+// existed. A credential store that can throw is a credential store that can take the session down.
+
+import fs from "node:fs";
+import path from "node:path";
+import { agentDirectory } from "./config.mjs";
+
+/** Pi's provider id for OpenRouter, from the provider table in its own docs. */
+export const OPENROUTER_PROVIDER = "openrouter";
+
+// auth.json holds one entry per provider and OAuth entries carry refresh and access tokens, so it
+// is meaningfully larger than the 4 KiB settings bound. This is still small enough that anything
+// above it was not written by Pi, and reading it is what stops a hostile or corrupt file from
+// costing the session a multi-megabyte synchronous read on the tool path.
+const MAX_AUTH_BYTES = 256 * 1024;
+
+export function authPath() {
+    return path.join(agentDirectory(), "auth.json");
+}
+
+/**
+ * Pi strips a BOM before parsing and so do we: an auth.json written by a Windows editor parses for
+ * Pi and would otherwise fail here, which is the worst kind of difference -- the key works for
+ * every model call and appears missing to this layer alone.
+ */
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/**
+ * The parsed store, cached against the file's own identity.
+ *
+ * `ask()` resolves a key per request and retention fires on every large read-only tool result, so an
+ * uncached read put a synchronous stat, read and JSON parse of up to 256 KiB on the tool path inside
+ * a 1500 ms latency budget -- where it used to be one `process.env` lookup. The cache key is the
+ * file's size and modification time, so `/login` writing a new credential mid-session invalidates it
+ * on the next call rather than being masked until restart, which a plain memo would have done.
+ *
+ * A file that will not parse is cached as firmly as one that will. Recording only successes left the
+ * worst case uncached: a truncated or hand-edited auth.json threw on every call, so every request
+ * paid a fresh stat, a 256 KiB read and a failing parse inside the same latency budget the cache
+ * exists to protect -- forever, since nothing about it would change until the file did.
+ */
+let parsedStore = { key: "", data: undefined };
+
+function readStore(file, stat) {
+    const identity = `${stat.mtimeMs}:${stat.size}:${file}`;
+    if (parsedStore.key === identity) {
+        return parsedStore.data;
+    }
+
+    let data;
+    try {
+        const parsed = JSON.parse(stripBom(fs.readFileSync(file, "utf8")));
+        data = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+    } catch {
+        // An unreadable or unparseable store is "no credential", which is the same answer the caller
+        // would have reached by catching this; caching it is what stops it being recomputed.
+        data = undefined;
+    }
+
+    parsedStore = { key: identity, data };
+
+    return data;
+}
+
+/**
+ * The raw stored entry for one provider, or undefined. Deliberately not exported: an entry is a
+ * credential, and the only thing outside this file that needs one is the request header.
+ */
+function storedCredential(providerId) {
+    try {
+        const file = authPath();
+        // `stat`, not `lstat`: a symlinked auth.json has to resolve, because dotfile managers like
+        // chezmoi and stow routinely link it into a managed directory. Refusing links here would
+        // recreate the exact divergence this module was written to remove -- Pi resolves the
+        // credential and every model call works, while this layer alone reports "key: none found"
+        // and gives no way to tell that from a missing key.
+        //
+        // config.mjs refuses links on its own files for a reason that does not apply here: those
+        // are writes, where a link can redirect a trusted write somewhere it was not meant to go.
+        // This is a bounded read of a file Pi owns, so an unsupported shape reads as "no credential"
+        // rather than throwing. It is not our file to have opinions about.
+        const stat = fs.statSync(file, { throwIfNoEntry: false });
+        if (!stat || !stat.isFile() || stat.size > MAX_AUTH_BYTES) {
+            return undefined;
+        }
+
+        return readStore(file, stat)?.[providerId];
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * An api_key credential's key, or undefined for anything else.
+ *
+ * An `oauth` entry is ignored rather than unwrapped. Pi refreshes OAuth tokens inside a lock in its
+ * own credential store, and a second process reading an access token out of the file would be
+ * reading a value that may already have been rotated -- and would be doing it without the lock.
+ * OpenRouter's own login mints a durable `api_key` anyway, so the case this skips is not the case
+ * anyone reaches.
+ */
+function apiKeyOf(credential) {
+    if (!credential || typeof credential !== "object" || credential.type !== "api_key") {
+        return undefined;
+    }
+
+    const key = credential.key;
+
+    return typeof key === "string" && key.trim().length > 0 ? key.trim() : undefined;
+}
+
+function environmentKey(name) {
+    const value = process.env[name];
+
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+/**
+ * Whether the credential store is consulted at all.
+ *
+ * `JEV_KEY_SOURCE=environment` restricts resolution to the environment variables. That exists for
+ * this repository's own scripts, and it is a correctness fix rather than a convenience: the
+ * calibration and triage runs load a key from the gitignored `evals/.env` and AGENTS.md promises
+ * "a variable already set in the shell always wins". Once `auth.json` was consulted first, those
+ * runs would silently bill a developer's personal `/login openrouter` account instead of the eval
+ * key, and `--probe` would verify a key the run then did not use.
+ */
+function environmentOnly() {
+    return process.env.JEV_KEY_SOURCE === "environment";
+}
+
+/**
+ * Jev is reached through OpenRouter by default: that is where it is published, it is what
+ * specpi-jev-guard uses, and an OpenRouter key (`sk-or-...`) is rejected by the direct
+ * TypeSafe API with a bare 401. `JEV_BACKEND=typesafe` selects the direct API for a TypeSafe key.
+ *
+ * It lives here rather than in client.mjs because everything below has to bind it. A parameter
+ * defaulting to the string "openrouter" is not a binding: re-exporting such a function under a name
+ * whose previous version read the backend itself silently rebound every no-arg caller to the wrong
+ * route, which is how `keyPresent()` came to report a key that `resolveKey()` would not return.
+ */
+export function backend() {
+    return process.env.JEV_BACKEND === "typesafe" ? "typesafe" : "openrouter";
+}
+
+export function keyEnvName(route = backend()) {
+    return route === "typesafe" ? "TYPESAFE_API_KEY" : "OPENROUTER_API_KEY";
+}
+
+/**
+ * Every place a key for this backend could come from, in the order they are consulted, each with
+ * whether it currently holds one. This is what `/jev status`, `specpi doctor` and the Chat panel
+ * render, and it carries labels only -- never a key, not even a truncated one.
+ *
+ * The list is returned whole rather than filtered to the winner because "which of these do I need
+ * to fix" is the question someone with no key is actually asking, and a bare "missing" has never
+ * answered it.
+ */
+export function keySources(route = backend()) {
+    const variable = keyEnvName(route);
+    const sources = [];
+    // Only the OpenRouter route has a provider entry to read: `auth.json` is keyed by Pi provider
+    // id, and the direct TypeSafe API is not one of Pi's providers.
+    if (route !== "typesafe" && !environmentOnly()) {
+        sources.push({
+            name: "auth.json",
+            label: `Pi credential store (${OPENROUTER_PROVIDER})`,
+            detail: "/login openrouter",
+            present: apiKeyOf(storedCredential(OPENROUTER_PROVIDER)) !== undefined,
+        });
+    }
+
+    sources.push({
+        name: variable,
+        label: `${variable} in the environment`,
+        detail: `export ${variable}=...`,
+        present: environmentKey(variable) !== undefined,
+    });
+
+    // Accepted on the OpenRouter route so an env file predating the OpenRouter default keeps
+    // working. Listed last because it is a compatibility path, and listed at all because a person
+    // whose key is only here should be able to see that that is why it still works.
+    if (route !== "typesafe") {
+        sources.push({
+            name: "TYPESAFE_API_KEY",
+            label: "TYPESAFE_API_KEY in the environment (legacy)",
+            detail: "export TYPESAFE_API_KEY=...",
+            present: environmentKey("TYPESAFE_API_KEY") !== undefined,
+        });
+    }
+
+    return sources;
+}
+
+/** The name of the source a key would be taken from, or undefined when there is none. */
+export function keySource(route = backend()) {
+    return keySources(route).find((source) => source.present)?.name;
+}
+
+/**
+ * The key itself. The only function here that returns one, and the only caller is the request
+ * header in client.mjs.
+ */
+export function resolveKey(route = backend()) {
+    if (route !== "typesafe" && !environmentOnly()) {
+        const stored = apiKeyOf(storedCredential(OPENROUTER_PROVIDER));
+        if (stored) {
+            return stored;
+        }
+    }
+
+    return environmentKey(keyEnvName(route)) ?? (route !== "typesafe" ? environmentKey("TYPESAFE_API_KEY") : undefined);
+}
+
+/**
+ * Whether any source holds a key. Callers only ever ask this; the client reads the value itself at
+ * call time, so a key never has to exist inside a structure that something might log or serialize.
+ */
+export function keyPresent(route = backend()) {
+    return keySources(route).some((source) => source.present);
+}