specpi 0.26.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/ledger.mjs

@@ -0,0 +1,138 @@
+// "We only send digests" is a promise until someone can check it. This ledger is the check: one
+// line per call recording what was sent, how big it was and what came back, with a SHA-256 of the
+// exact payload and never the payload itself.
+//
+// It doubles as the calibration corpus. Thresholds in this layer are meant to be read off a curve
+// rather than guessed, and the curve has to come from somewhere.
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { jevDirectory, regularFile } from "./config.mjs";
+
+const MAX_LINES = 5000;
+const MAX_LEDGER_BYTES = 8 * 1024 * 1024;
+
+export function ledgerPath() {
+    return path.join(jevDirectory(), "transmissions.jsonl");
+}
+
+export function payloadDigest(payload) {
+    return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+
+/**
+ * Append one record. Ledger failure never fails the call that produced it: an advisor that cannot
+ * write its audit line still must not break the session, so the error is swallowed and the caller
+ * proceeds. The absence of a line is itself visible in `/jev ledger`.
+ */
+export function record(entry) {
+    try {
+        const file = ledgerPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        if (fs.existsSync(file)) {
+            const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+            if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
+                return false;
+            }
+
+            if (stat.size > MAX_LEDGER_BYTES) {
+                rotate(file);
+            }
+        }
+
+        fs.appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`, {
+            mode: 0o600,
+        });
+
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** Keep the newest half. Unbounded growth is a worse failure than losing old audit lines. */
+function rotate(file) {
+    const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    const kept = lines.slice(-Math.floor(MAX_LINES / 2));
+    fs.writeFileSync(file, kept.length > 0 ? `${kept.join("\n")}\n` : "", { mode: 0o600 });
+}
+
+/**
+ * Roll the ledger up into the few numbers a report wants. Kept here rather than in the eval suite
+ * because the shape of a line is this module's business, and a reader that has to know it is a
+ * second copy of the schema waiting to drift.
+ */
+export function summarize(entries) {
+    const lines = Array.isArray(entries) ? entries : [];
+    const bySystem = {};
+    for (const entry of lines) {
+        const name = typeof entry?.system === "string" ? entry.system : "unknown";
+        const bucket = (bySystem[name] ??= {
+            calls: 0,
+            failed: 0,
+            applied: 0,
+            savedBytes: 0,
+            stateBytes: 0,
+            outcomes: {},
+        });
+        bucket.calls += 1;
+        bucket.failed += entry?.ok === true ? 0 : 1;
+        bucket.applied += entry?.applied === true ? 1 : 0;
+        bucket.savedBytes += Number.isFinite(entry?.savedBytes) ? entry.savedBytes : 0;
+        bucket.stateBytes += Number.isFinite(entry?.stateBytes) ? entry.stateBytes : 0;
+        // "Asked 3 times, applied 0" is a number. "Asked 3 times, applied 0, all three because the
+        // result might hold the answer" is a finding.
+        const outcome =
+            typeof entry?.outcome === "string" ? entry.outcome : entry?.ok === true ? "unrecorded" : "failed";
+        bucket.outcomes[outcome] = (bucket.outcomes[outcome] ?? 0) + 1;
+    }
+
+    const totals = Object.values(bySystem);
+
+    return {
+        calls: lines.length,
+        failed: totals.reduce((sum, item) => sum + item.failed, 0),
+        applied: totals.reduce((sum, item) => sum + item.applied, 0),
+        savedBytes: totals.reduce((sum, item) => sum + item.savedBytes, 0),
+        stateBytes: totals.reduce((sum, item) => sum + item.stateBytes, 0),
+        // Named for what retention does, because it is the only system that shortens anything and
+        // the number is meaningless averaged with systems that cannot.
+        elisions: bySystem.retention?.applied ?? 0,
+        bytesDropped: bySystem.retention?.savedBytes ?? 0,
+        bySystem,
+    };
+}
+
+/** Every line, for a caller that wants to summarize rather than display. `read` is for display. */
+export function readAll() {
+    return read(Number.MAX_SAFE_INTEGER);
+}
+
+export function read(limit = 20) {
+    try {
+        const file = ledgerPath();
+        if (!regularFile(file, "Jev ledger")) {
+            return [];
+        }
+    } catch {
+        // An oversize ledger is still readable; only a link or irregular file is refused.
+    }
+
+    try {
+        const lines = fs.readFileSync(ledgerPath(), "utf8").split("\n").filter(Boolean);
+
+        return lines
+            .slice(-Math.max(1, limit))
+            .map((line) => {
+                try {
+                    return JSON.parse(line);
+                } catch {
+                    return undefined;
+                }
+            })
+            .filter(Boolean);
+    } catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,124 @@
+// System 6: decide, once, before the first provider request, whether this session is going to need
+// a withdrawn tool group -- and if so, offer it then rather than in the middle.
+//
+// This is permitted by the standing rule because it is a once-per-session decision made before the
+// first request, which is one of the three cache-safe shapes. It is also distinct from the tool
+// router this project rejected: that rejection was about six tools whose usefulness local state can
+// already determine from wishlist and goal state. "Will this task need a browser" is not in local
+// state, and no amount of inspecting the repository answers it.
+//
+// It exists because Phase 7 measured what the rejection was always assumed to be worth. Flipping
+// Browser QA on at turn 6 of `t3-cascade-ledger` collapsed cached tokens to 3,200 at the next
+// request in three attempts out of three, while the prompt kept climbing, and the re-warm cost 20%
+// of the attempt on average. Arming the same group from the first request cost 16% more than never
+// arming it, against 47% for flipping mid-session. Paying up front is about three times cheaper
+// than paying when the need appears -- so the whole value of this system is moving the decision
+// earlier, and that is all it does.
+//
+// It holds no authority. It activates nothing on its own: it pre-fills the same confirmation the
+// human would have seen from `request_capability`, at turn 0 instead of turn 6. A decline is
+// remembered for the session, and with no interactive human it proposes nothing at all.
+
+import { choice, noul } from "../client.mjs";
+import { choiceValue, nounTrue } from "../gate.mjs";
+import { compact } from "../sanitize.mjs";
+
+export const TASK_KINDS = Object.freeze({
+    code: "Reading or changing source code in this repository",
+    web: "Looking something up online, or reading external pages",
+    ui: "Checking how a page renders or behaves in a browser",
+    ops: "Builds, releases, configuration or tooling",
+    docs: "Writing or editing prose",
+    other: "Anything else",
+});
+
+/**
+ * Cheap, local, and checked before anything is sent. The rule is ask local state first, and while
+ * local state cannot answer "will this need a browser", it answers "is that question worth asking":
+ * a task with no web signal in its wording and a repository with no web assets is not one.
+ */
+const PROMPT_SIGNALS =
+    /\b(https?:\/\/|www\.|url|link|page|site|website|web|browser|render|screenshot|accessibility|a11y|css|dom|localhost|search online|look .{0,12}up)\b/iu;
+
+/** Names that mean this repository has something a browser could open. */
+const WEB_ASSETS = /^(index\.html|.*\.html?|vite\.config\..*|next\.config\..*|svelte\.config\..*|astro\.config\..*)$/iu;
+
+export function promptSignal(prompt) {
+    return PROMPT_SIGNALS.test(String(prompt ?? ""));
+}
+
+/** One bounded readdir of the working directory. Never recursive: this is a hint, not a survey. */
+export function repositorySignal(entries) {
+    return (entries ?? []).slice(0, 200).some((name) => WEB_ASSETS.test(String(name)));
+}
+
+export function localSignals({ prompt, entries }) {
+    const reasons = [];
+    if (promptSignal(prompt)) {
+        reasons.push("prompt-mentions-web");
+    }
+
+    if (repositorySignal(entries)) {
+        reasons.push("repository-has-web-assets");
+    }
+
+    return { ask: reasons.length > 0, reasons };
+}
+
+/**
+ * The prompt is the one place in this layer where the user's own words are sent rather than a
+ * digest of them, and it is bounded hard for that reason. It is the only thing that can answer the
+ * question, and it is one message rather than a transcript.
+ */
+export function buildInput({ prompt, reasons, available, cwdEntries = [] }) {
+    return {
+        request: compact(prompt ?? "", 400),
+        reasons,
+        withdrawnGroups: available,
+        workspaceFiles: cwdEntries.slice(0, 12).map((name) => compact(name, 40)),
+    };
+}
+
+export function questions({ available = [] } = {}) {
+    const asked = { task_kind: choice("What kind of work is this request asking for?", TASK_KINDS) };
+    if (available.includes("web")) {
+        asked.needs_web = noul("Completing this request will require searching the web or fetching an external page");
+    }
+
+    if (available.includes("browser")) {
+        asked.needs_browser = noul(
+            "Completing this request will require opening a page in a browser to check how it renders or behaves",
+        );
+    }
+
+    // Asked whenever the session is capable of it, because the answer is a suggestion to the human
+    // rather than an activation: delegation binds a model and a host and needs its own command.
+    asked.needs_delegation = noul(
+        "This request would be better answered by reading a large set of files than by reasoning about a few",
+    );
+
+    return asked;
+}
+
+/**
+ * Deliberately asymmetric. A false positive costs the group's schema on every request for the rest
+ * of the session and a confirmation the human did not need; a false negative costs nothing at all,
+ * because it leaves today's behaviour exactly as it is and `request_capability` is still there. So
+ * this proposes only on a high bar, and the `capability` thresholds are the strictest in the layer.
+ */
+export function decide(answers, available = []) {
+    const propose = [];
+    if (available.includes("web") && nounTrue(answers?.needs_web, "capability")) {
+        propose.push("web");
+    }
+
+    if (available.includes("browser") && nounTrue(answers?.needs_browser, "capability")) {
+        propose.push("browser");
+    }
+
+    return {
+        propose,
+        taskKind: choiceValue(answers?.task_kind, "capability"),
+        suggestDelegation: nounTrue(answers?.needs_delegation, "capability"),
+    };
+}