specpi 0.27.0 → 0.28.0

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
+ * the command 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);
+}

package/extensions/jev-advisor/layer.mjs

@@ -0,0 +1,169 @@
+// What `/jev on` and `/jev off` actually do, as functions a test can call.
+//
+// This logic used to live in closures inside index.ts, which no test imports -- every test in the
+// suite reaches for a `.mjs` module, so the whole feature was covered only by prose. Two review
+// rounds found the consequences: a guard preference destroyed on a path that had decided nothing, a
+// fail-closed gate armed by a headless session that was told nothing had changed, a message
+// reporting the guard "left off" while it was on and blocking, and a rollback that never happened
+// because the flag was set before the write. None of those were visible to a green suite, because
+// the suite could not see them at all.
+//
+// So the shape here is deliberate: no module state, no reads of `process` beyond an injected `env`,
+// and every effect either returned as data or performed through an injected dependency. The caller
+// owns the session; this decides what should happen to it and says so.
+
+import { SYSTEM_NAMES } from "./config.mjs";
+
+/**
+ * Decide what a layer switch means, and report it honestly.
+ *
+ * `state` is `{ settings }` and is never mutated -- the next state comes back in the result. `deps`
+ * supplies the outside world, which is now only `keySources`: the command guard used to need a
+ * package's global configuration file arbitrated here, and as the eighth system it needs nothing.
+ *
+ * Scope belongs to `layerScopeLine`, not here, so this takes `{ on }` and nothing else. It used to
+ * be handed `sessionOnly` and `interactive` as well and read neither, which reads as a decision
+ * being made from them.
+ */
+export function applyLayer({ on }, state, deps) {
+    if (!on) {
+        return { settings: { ...state.settings, master: false }, lines: [offLine()] };
+    }
+
+    // Resolved inside the on branch only. `offLine` never names a key, so doing this first meant
+    // every `/jev off` paid for a stat, read and parse of Pi's credential store to discard it --
+    // the one file this layer reads under a narrow, stated exception.
+    const active = deps.keySources().find((item) => item.present)?.name;
+    const settings = enableSystems(state.settings);
+
+    return { settings, lines: onLines(state.settings, settings, active) };
+}
+
+/**
+ * What arming the command guard means, in the words every path that arms it has to use.
+ *
+ * Seven of the eight systems only ever add advice; this one can refuse a tool call. Saying so is a
+ * rule rather than a nicety, and it lives here because it was a rule `/jev on` honoured alone while
+ * `/jev enable guard` and `/jev startup on` armed the same system in silence.
+ */
+export function guardWarning() {
+    return (
+        "guard is the only system that can refuse a tool call: it blocks a call it reads as " +
+        "destructive and not what was asked for, asks you about the uncertain ones, and hands " +
+        "everything else to the permission system unchanged. Turn it off with /jev disable guard."
+    );
+}
+
+/**
+ * Enabling the layer enables its systems, because a layer with none on runs and does nothing -- the
+ * state people kept arriving at, with the notification cheerfully reporting "0 of 8".
+ *
+ * Only when none are on. Someone deliberately running retention alone has expressed a preference,
+ * and `/jev off` then `/jev on` must not hand back the seven they turned off.
+ *
+ * The command guard is one of the eight, and it is the only system that can refuse a tool call. That
+ * is a deliberate answer to a question this file and `config.mjs` resolve differently on purpose:
+ * `/jev on` is a person acting now, so it arms everything and `onLines` says in as many words that
+ * one of them can refuse a command; `migrateToThree` runs without anyone present, so it arms
+ * nothing new. Silence is the difference -- an unattended migration must not change what a session
+ * is allowed to run, and an explicit command that reports what it did may.
+ */
+export function enableSystems(settings) {
+    const chosen = SYSTEM_NAMES.filter((name) => settings.systems[name]);
+
+    return {
+        ...settings,
+        master: true,
+        systems: chosen.length > 0 ? settings.systems : Object.fromEntries(SYSTEM_NAMES.map((name) => [name, true])),
+    };
+}
+
+function onLines(before, after, activeSource) {
+    const chosen = SYSTEM_NAMES.filter((name) => before.systems[name]);
+    const active = SYSTEM_NAMES.filter((name) => after.systems[name]);
+    const lines = [`Jev layer on with ${active.length} of ${SYSTEM_NAMES.length} systems: ${active.join(", ")}.`];
+    if (chosen.length === 0) {
+        lines.push("No system was enabled, so all of them were. Turn any back off with /jev disable <system>.");
+    }
+
+    // Said out loud every time, because seven of the eight only ever add advice and this one can
+    // take a command away. Nobody should discover that from a blocked call.
+    if (after.systems.guard) {
+        lines.push(guardWarning());
+    }
+
+    lines.push(keyLine(activeSource));
+
+    return lines;
+}
+
+function offLine() {
+    return "Jev layer off. No state leaves this machine, and every tool call goes to the permission system.";
+}
+
+/**
+ * Where the key is coming from, by name and never by value. Takes the already-resolved source name
+ * rather than looking it up, so one command cannot read the credential store twice.
+ */
+export function keyLine(source) {
+    if (source) {
+        return `Key: found in ${source === "auth.json" ? "Pi's credential store (auth.json)" : source}.`;
+    }
+
+    return (
+        "Key: none found, so every system will report no advice and the harness runs exactly as it did before. " +
+        "Run /login openrouter to store one, or set OPENROUTER_API_KEY."
+    );
+}
+
+/**
+ * The settings to write so that turning the layer on is remembered.
+ *
+ * `master` and `startup` always move together. Storing them apart is what made the Chat panel's
+ * "enabled" checkbox do nothing on its own: `session_start` zeroes a stored master whenever
+ * `startup` is false, so `master: true, startup: false` describes a layer that is on and never runs.
+ *
+ * The stored file is the base, so budgets and the nudge mode written by Chat while this session was
+ * running survive -- including any system the panel enabled since this session started, which is why
+ * `systems` is merged rather than written over.
+ */
+export function layerToPersist({ settings }, stored) {
+    return {
+        ...stored,
+        master: settings.master,
+        startup: settings.master,
+        // Merged onto the stored map, not written over it. This session's copy may predate systems
+        // enabled on disk since it started -- by the Chat panel, or by another session -- and
+        // writing it whole turned those back off with nothing reporting it.
+        systems: { ...stored.systems, ...settings.systems },
+    };
+}
+
+/** What the change applies to: this session, or every session from now on. */
+export function layerScopeLine({ sessionOnly, interactive, persisted, stored, settingsFile }) {
+    if (sessionOnly) {
+        return `This session only, as asked. New sessions still start ${stored.startup && stored.master ? "on" : "off"}.`;
+    }
+
+    if (!interactive) {
+        return "This session only: writing the startup preference needs an interactive command.";
+    }
+
+    if (!persisted) {
+        return `This session only: ${settingsFile} could not be written.`;
+    }
+
+    return `Remembered -- new Pi sessions start this way too. Preference: ${settingsFile}`;
+}
+
+/**
+ * `/jev startup on|off`, which was the last command still writing one half of the pair -- the exact
+ * trap this module exists to remove, left in the command named after it, while reporting that new
+ * sessions would start on when they would not.
+ */
+export function startupToPersist(wanted, stored) {
+    // Delegates to `enableSystems` rather than restating the rule. Three copies of "what enabling
+    // the layer means" -- here, there, and `couple` in the Chat panel -- is precisely how the
+    // advisor and the panel drift apart, which is the class of bug this module was extracted over.
+    return wanted ? { ...enableSystems(stored), startup: true } : { ...stored, master: false, startup: false };
+}

package/extensions/jev-advisor/questions/guard.mjs

@@ -0,0 +1,168 @@
+// System 8: score a shell or file call that local rules could not settle, before it runs.
+//
+// This is the native command guard. It replaces the pinned `specpi-jev-guard` package, and the
+// reason it exists rather than that package being configured is that the package's shape kept
+// producing the same class of defect: its configuration was a global file with no session scope, so
+// there was no such thing as enabling it for one session; it read its key from the environment only,
+// so a credential `/login` had stored was invisible to it; and it was fail-closed, so an outage or a
+// missing key turned every shell call in the session into a refusal.
+//
+// Native, all three go away. The switch is `systems.guard` like every other system, so it is
+// session-scoped, budgeted, reported in `/jev status` and toggled by `/jev enable guard`. The key is
+// whatever `key-source.mjs` resolves, which includes Pi's own credential store. And the failure
+// posture is inverted, deliberately:
+//
+//   FAIL OPEN. Jev unreachable, unconfident, out of budget, or without a key means the call goes to
+//   @gotgenes/pi-permission-system exactly as it did before this layer existed.
+//
+// That is the rule the rest of this extension already follows -- "nothing here is ever the reason a
+// tool is blocked" -- and applying it here is not a weakening. The guard sits *in front of* the
+// permission system, which still decides every call it defers. Fail-closed meant an outage stopped
+// work; fail-open means an outage returns policy to the component that owned it anyway. The guard
+// adds blocking for confident, dangerous verdicts, and adds nothing else.
+//
+// What it sends is bounded by sanitize.mjs like every other system: a redacted digest, never the raw
+// environment, and never more than the shared 1 KB budget.
+
+import { score } from "../client.mjs";
+import { THRESHOLDS, scoreLevel } from "../gate.mjs";
+
+/** How a decision was reached, for the ledger and for `/jev status`. */
+export const SOURCES = Object.freeze(["local", "jev", "human", "deferred"]);
+
+/**
+ * One Score, not a Noul.
+ *
+ * A Noul returns a bare probability with no confidence field, and this is the one system whose
+ * action takes a tool call away from the person. Gating that on a number with no reported confidence
+ * is exactly what the calibration work found unreachable elsewhere: without a confidence the gate
+ * either fires on coin flips or never fires at all. A Score reports both, so "confident this is
+ * destructive" and "unsure" are distinguishable, and only the first can block.
+ */
+export function questions(input) {
+    return {
+        risk: score(
+            "Rate how likely this call is to destroy data, exfiltrate a credential, or hand control " +
+                "of the machine to someone else, given what the person asked for. Judge the call as " +
+                "written, not the worst command that shares its first word. Routine development work " +
+                "-- building, testing, installing declared dependencies, editing source, committing -- " +
+                "is not destructive merely because it writes.",
+            [
+                "harmless: reads, or writes only within the project in the ordinary course of the task",
+                "ordinary: changes state the person would expect this task to change",
+                "risky: destroys work, rewrites history, or reaches outside the project, but plausibly intended",
+                "destructive: irreversible loss, credential exposure, or remote code execution that the request does not call for",
+            ],
+        ),
+        intended: score("Rate how well this call matches what the person actually asked for.", [
+            "unrelated",
+            "tangential",
+            "plausible",
+            "clearly what was asked",
+        ]),
+        ...(input?.protected === true
+            ? {
+                  credential: score(
+                      "Rate how likely this write targets a real secret rather than a template, " +
+                          "example, fixture or documentation file that merely looks like one.",
+                      ["template or example", "unclear", "likely a real secret", "certainly a real secret"],
+                  ),
+              }
+            : {}),
+    };
+}
+
+/**
+ * Turn the answers into one of three outcomes.
+ *
+ * `block` needs a confident destructive reading *and* a confident reading that the request does not
+ * account for the call. Both, because the single most likely way to be wrong here is a genuinely
+ * destructive-looking command that the person asked for in as many words -- `rm -rf node_modules`, a
+ * force push to a branch they named. Requiring the intent answer to actively disagree is what keeps
+ * those working.
+ *
+ * "Both" means both, including when the intent answer does not survive its own confidence gate. An
+ * earlier version read a missing intent answer as agreement, which mattered far more than it sounds:
+ * `gate.mjs`'s own calibration records a score coverage near 0.2, so roughly four answers in five are
+ * ungated and a confident risk=3 would have blocked essentially unconditionally -- turning the one
+ * stated safeguard into a clause that almost never applied.
+ *
+ * `ask` is the middle band, and only when there is a human to ask. Without a UI it becomes `defer`,
+ * because a question nobody can answer is a block wearing a friendlier word.
+ *
+ * Everything else defers to the permission system.
+ */
+export function decide(answers, { hasUI = false } = {}) {
+    const risk = answers?.risk;
+    const intended = answers?.intended;
+    if (!risk) {
+        return { action: "defer", source: "deferred", reason: "no answer" };
+    }
+
+    const level = scoreLevel(risk, "guard");
+    const wanted = intended ? scoreLevel(intended, "guard") : undefined;
+
+    // A confident secret verdict blocks on its own: a write to a real credential file is not made
+    // acceptable by having been asked for, and the fixture case is what the question separates.
+    const credential = answers?.credential ? scoreLevel(answers.credential, "guard") : undefined;
+    if (credential === 3) {
+        return { action: "block", source: "jev", reason: "writes a real credential file" };
+    }
+
+    if (level === 3 && wanted !== undefined && wanted <= 1) {
+        return { action: "block", source: "jev", reason: "destructive and not what was asked for" };
+    }
+
+    if (level === 3 || level === 2) {
+        return hasUI
+            ? { action: "ask", source: "human", reason: level === 3 ? "destructive" : "risky" }
+            : { action: "defer", source: "deferred", reason: "no interface to ask" };
+    }
+
+    return { action: "defer", source: "deferred", reason: "below the bar" };
+}
+
+/** The two answers the guard's confirmation dialog offers, in the order it offers them. */
+export const CHOICES = Object.freeze({ run: "Run it", block: "Block it" });
+
+/**
+ * Whether a human's answer to that dialog is consent.
+ *
+ * Only the affirmative is. Escape, a dismissed picker, a host that resolves with nothing and a host
+ * that throws all produce something that is not `CHOICES.run`, and every one of them has to mean
+ * "not approved" -- reaching this point means the verdict already said the call needs a person's
+ * approval, and an unanswerable question resolved as yes is what a confirmation dialog exists to
+ * rule out. It lives here rather than in the handler so that it is a rule with a test, not a
+ * comparison inside a closure no test imports.
+ */
+export function approved(choice) {
+    return choice === CHOICES.run;
+}
+
+/** The gate's own numbers, named so `/jev status` and the tests read the same source. */
+export const GATE = Object.freeze({
+    scoreConfidence: THRESHOLDS.guard.scoreConfidence,
+    boundary: THRESHOLDS.guard.boundary,
+});
+
+/**
+ * The state the question is asked against, bounded like every other system's.
+ *
+ * What the model needs is the call, what the person asked for, and enough recent history to tell a
+ * cleanup step from a first move. What it must not receive is the environment, the file's contents,
+ * or anything the sanitiser has not seen: `buildState` applies the shared redaction and the 1 KB
+ * ceiling, so a long command arrives truncated rather than in full.
+ */
+export function buildInput({ tool, subject, protectedTarget, objective, recent, cwd }) {
+    return {
+        system: "command-guard",
+        tool: String(tool ?? ""),
+        call: String(subject ?? ""),
+        protectedTarget: protectedTarget === true,
+        // Why the call was made matters as much as what it does: the same command is routine in one
+        // task and destructive in another, and the intent question has nothing to weigh without it.
+        objective: String(objective ?? ""),
+        recent: Array.isArray(recent) ? recent.slice(-6).map((item) => `${item.tool}:${item.outcome}`) : [],
+        cwd: String(cwd ?? ""),
+    };
+}