@bobobowis/jev-kit 0.0.0-stage → 0.1.0

package/dist/setup/index.d.ts

@@ -0,0 +1,67 @@
+import { type Guard } from "../hooks/handle.ts";
+export type SetupHarness = "claude" | "codex";
+export interface SetupOptions {
+    harness: SetupHarness;
+    /** The project directory. */
+    dir: string;
+    guards?: Guard[];
+    tools?: string[];
+    /** Run the Level 7 advisor hooks. */
+    compact?: boolean;
+    /** A lab level: 6 means the guards, 7 the advisor and should_i_compact, 8 to 10 their tools. */
+    level?: number;
+    /** How the harness runs this package's bin. Defaults to node and its absolute path. */
+    command?: string[];
+    /** Extra `jev hook` flags, for example --lines or --window. */
+    hookArgs?: string[];
+    /** Hook timeout in seconds, as the harness counts it. */
+    timeoutSec?: number;
+}
+export interface FileChange {
+    path: string;
+    before: string | null;
+    after: string;
+    changed: boolean;
+}
+export declare class SetupError extends Error {
+}
+/**
+ * The bin this module ships with: dist/cli/index.js next to dist/setup/. Run through npx or
+ * pnpm dlx, it is `npx -y` on this exact version instead, which outlives the cache.
+ */
+export declare const defaultCommand: (bin?: string) => string[];
+export declare const isJevHookCommand: (command: unknown) => boolean;
+export interface Resolved {
+    guards: Guard[];
+    tools: string[];
+    compact: boolean;
+}
+export declare function resolveSelection(o: Pick<SetupOptions, "guards" | "tools" | "compact" | "level">): Resolved;
+interface HookGroup {
+    matcher?: string;
+    hooks: {
+        type: "command";
+        command: string;
+        timeout?: number;
+    }[];
+}
+/** The hook entries, by event, that a selection needs. Same shape for Claude Code and Codex. */
+export declare function hookGroups(harness: SetupHarness, sel: Resolved, command: string[], extra?: string[], timeoutSec?: number): Record<string, HookGroup[]>;
+/** Drop every hook this tool wrote before, then add the new groups. Unrelated hooks stay in place. */
+export declare function mergeHooks(existing: Record<string, HookGroup[]> | undefined, ours: Record<string, HookGroup[]>): Record<string, HookGroup[]>;
+/** Claude Code: `.mcp.json` for the tools, `.claude/settings.json` for the hooks. */
+export declare function planClaude(o: SetupOptions): FileChange[];
+/** What the MCP server needs from the agent's environment. */
+export declare const MCP_ENV_VARS: string[];
+/** Our block of `.codex/config.toml`: the hooks as arrays of tables, the server as one table. */
+export declare function codexBlock(sel: Resolved, command: string[], extra?: string[], timeoutSec?: number): string;
+/**
+ * Codex: `.codex/config.toml`, loaded once the project is trusted. There is no TOML parser here, so
+ * the file is not rewritten: our entries live in one marked block at the end, replaced on every run.
+ */
+export declare function planCodex(o: SetupOptions): FileChange[];
+/** One line for people: what the selection turns on. */
+export declare function describeSelection(o: Pick<SetupOptions, "guards" | "tools" | "compact" | "level">): string;
+export declare function plan(o: SetupOptions): FileChange[];
+export declare function apply(changes: FileChange[]): void;
+export {};

package/dist/setup/index.js

@@ -0,0 +1,209 @@
+/**
+ * Wire Jev into a project's agent config: the MCP server for the tools, hook entries for the guards
+ * and the compaction advisor. Merges into what is there. Entries it wrote before are recognized by
+ * their marker (the `jev` server name, hook commands running `hook --harness <name>`) and replaced;
+ * everything else is left as it was. A file that is not valid JSON is refused, never overwritten.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ALL_GUARDS } from "../hooks/handle.js";
+import { LEVEL_TOOLS, selectTools } from "../tools/sets.js";
+export class SetupError extends Error {
+}
+/** npx and pnpm dlx unpack into a cache they may clear, so a path into one would stop working. */
+const EPHEMERAL = /[\\/](_npx|dlx)[\\/]/;
+/**
+ * The bin this module ships with: dist/cli/index.js next to dist/setup/. Run through npx or
+ * pnpm dlx, it is `npx -y` on this exact version instead, which outlives the cache.
+ */
+export const defaultCommand = (bin = fileURLToPath(new URL(`../cli/index.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`, import.meta.url))) => {
+    if (!EPHEMERAL.test(bin))
+        return [process.execPath, bin];
+    const pkg = JSON.parse(readFileSync(resolve(dirname(bin), "../../package.json"), "utf8"));
+    return ["npx", "-y", `${pkg.name}@${pkg.version}`];
+};
+const quote = (s) => (/^[A-Za-z0-9_./:@=,+-]+$/.test(s) ? s : JSON.stringify(s));
+const MARKER = /\shook --harness (claude|codex)(\s|$)/;
+export const isJevHookCommand = (command) => typeof command === "string" && MARKER.test(command);
+export function resolveSelection(o) {
+    const guards = new Set(o.guards ?? []);
+    const tools = new Set(o.tools ?? []);
+    let compact = o.compact ?? false;
+    if (o.level !== undefined) {
+        if (o.level === 6)
+            ALL_GUARDS.forEach((g) => guards.add(g));
+        else if (LEVEL_TOOLS[o.level]) {
+            LEVEL_TOOLS[o.level].forEach((t) => tools.add(t));
+            if (o.level === 7)
+                compact = true;
+        }
+        else
+            throw new SetupError(`level ${o.level} has nothing to set up; levels 6 to 10 do`);
+    }
+    for (const g of guards)
+        if (!ALL_GUARDS.includes(g))
+            throw new SetupError(`unknown guard ${g}; known: ${ALL_GUARDS.join(", ")}`);
+    try {
+        selectTools({ names: [...tools] });
+    }
+    catch (err) {
+        throw new SetupError(err.message);
+    }
+    if (!guards.size && !tools.size && !compact)
+        throw new SetupError("nothing to set up: pass --guards, --tools, --compact, or --level");
+    return { guards: [...guards], tools: [...tools], compact };
+}
+/** The hook entries, by event, that a selection needs. Same shape for Claude Code and Codex. */
+export function hookGroups(harness, sel, command, extra = [], timeoutSec = 10) {
+    const run = (event, flags) => ({ type: "command", command: [...command, "hook", "--harness", harness, "--event", event, ...flags, ...extra].map(quote).join(" "), timeout: timeoutSec });
+    const out = {};
+    const guardFlag = (gs) => ["--guards", gs.join(",")];
+    const pre = [];
+    if (sel.guards.includes("bash"))
+        pre.push("Bash");
+    if (sel.guards.includes("write"))
+        pre.push(...(harness === "codex" ? ["apply_patch"] : ["Write", "Edit", "MultiEdit", "NotebookEdit"]));
+    if (pre.length)
+        out.PreToolUse = [{ matcher: pre.join("|"), hooks: [run("PreToolUse", guardFlag(sel.guards.filter((g) => g !== "result")))] }];
+    if (sel.guards.includes("result"))
+        out.PostToolUse = [{ matcher: harness === "codex" ? "Bash" : "Read|Bash", hooks: [run("PostToolUse", guardFlag(["result"]))] }];
+    if (sel.compact) {
+        out.UserPromptSubmit = [{ hooks: [run("UserPromptSubmit", ["--compact"])] }];
+        out.Stop = [{ hooks: [run("Stop", ["--compact"])] }];
+        out.PreCompact = [{ hooks: [run("PreCompact", [])] }];
+    }
+    return out;
+}
+/** Drop every hook this tool wrote before, then add the new groups. Unrelated hooks stay in place. */
+export function mergeHooks(existing, ours) {
+    const merged = {};
+    for (const [event, groups] of Object.entries(existing ?? {})) {
+        const kept = (Array.isArray(groups) ? groups : [])
+            .map((g) => ({ ...g, hooks: (g?.hooks ?? []).filter((h) => !isJevHookCommand(h?.command)) }))
+            .filter((g) => g.hooks.length);
+        if (kept.length)
+            merged[event] = kept;
+    }
+    for (const [event, groups] of Object.entries(ours))
+        merged[event] = [...(merged[event] ?? []), ...groups];
+    return merged;
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return { text: null, value: {} };
+    const text = readFileSync(path, "utf8");
+    if (!text.trim())
+        return { text, value: {} };
+    try {
+        const value = JSON.parse(text);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("not a JSON object");
+        return { text, value };
+    }
+    catch (err) {
+        throw new SetupError(`${path} is not valid JSON (${err.message}); fix or move it, then run jev setup again. Nothing was written.`);
+    }
+}
+const change = (path, before, value) => {
+    const after = JSON.stringify(value, null, 2) + "\n";
+    return { path, before, after, changed: before === null ? true : JSON.stringify(JSON.parse(before)) !== JSON.stringify(value) };
+};
+/** Claude Code: `.mcp.json` for the tools, `.claude/settings.json` for the hooks. */
+export function planClaude(o) {
+    const sel = resolveSelection(o);
+    const command = o.command ?? defaultCommand();
+    const dir = resolve(o.dir);
+    const out = [];
+    const mcpPath = join(dir, ".mcp.json");
+    const mcp = readJson(mcpPath);
+    const servers = { ...(mcp.value.mcpServers ?? {}) };
+    if (sel.tools.length)
+        servers.jev = { command: command[0], args: [...command.slice(1), "mcp", "--tools", sel.tools.join(",")] };
+    else
+        delete servers.jev;
+    if (sel.tools.length || mcp.text !== null)
+        out.push(change(mcpPath, mcp.text, { ...mcp.value, mcpServers: servers }));
+    const settingsPath = join(dir, ".claude", "settings.json");
+    const settings = readJson(settingsPath);
+    const hooks = mergeHooks(settings.value.hooks, hookGroups("claude", sel, command, o.hookArgs, o.timeoutSec));
+    const next = { ...settings.value };
+    if (Object.keys(hooks).length)
+        next.hooks = hooks;
+    else
+        delete next.hooks;
+    if (Object.keys(hooks).length || settings.text !== null)
+        out.push(change(settingsPath, settings.text, next));
+    return out;
+}
+const BLOCK_START = "# >>> jev setup: managed by `jev setup`; this block is replaced on every run";
+const BLOCK_END = "# <<< jev setup";
+/** What the MCP server needs from the agent's environment. */
+export const MCP_ENV_VARS = ["TYPESAFE_API_KEY", "OPENROUTER_API_KEY", "JEV_EVENT_DIR", "JEV_STATE_DIR"];
+const tomlString = (s) => JSON.stringify(s); // JSON escapes are valid TOML basic-string escapes
+const tomlArray = (xs) => `[${xs.map(tomlString).join(", ")}]`;
+/** Our block of `.codex/config.toml`: the hooks as arrays of tables, the server as one table. */
+export function codexBlock(sel, command, extra = [], timeoutSec = 10) {
+    const lines = [BLOCK_START];
+    for (const [event, groups] of Object.entries(hookGroups("codex", sel, command, extra, timeoutSec))) {
+        for (const g of groups) {
+            lines.push("", `[[hooks.${event}]]`);
+            if (g.matcher)
+                lines.push(`matcher = ${tomlString(g.matcher)}`);
+            for (const h of g.hooks)
+                lines.push(`[[hooks.${event}.hooks]]`, `type = "command"`, `command = ${tomlString(h.command)}`, `timeout = ${h.timeout ?? timeoutSec}`);
+        }
+    }
+    if (sel.tools.length) {
+        lines.push("", "[mcp_servers.jev]", `command = ${tomlString(command[0])}`, `args = ${tomlArray([...command.slice(1), "mcp", "--tools", sel.tools.join(",")])}`, `default_tools_approval_mode = "approve"`, 
+        // Codex starts MCP servers with a clean environment; hooks inherit it, servers do not.
+        `env_vars = ${tomlArray(MCP_ENV_VARS)}`);
+    }
+    lines.push(BLOCK_END);
+    return lines.join("\n") + "\n";
+}
+/**
+ * Codex: `.codex/config.toml`, loaded once the project is trusted. There is no TOML parser here, so
+ * the file is not rewritten: our entries live in one marked block at the end, replaced on every run.
+ */
+export function planCodex(o) {
+    const sel = resolveSelection(o);
+    const command = o.command ?? defaultCommand();
+    const path = join(resolve(o.dir), ".codex", "config.toml");
+    const before = existsSync(path) ? readFileSync(path, "utf8") : null;
+    const text = before ?? "";
+    const start = text.indexOf(BLOCK_START);
+    const end = text.indexOf(BLOCK_END);
+    if ((start === -1) !== (end === -1) || end < start) {
+        throw new SetupError(`${path} has a broken jev setup block (a start or end marker is missing); fix or remove it, then run jev setup again. Nothing was written.`);
+    }
+    const outside = start === -1 ? text : text.slice(0, start) + text.slice(end + BLOCK_END.length);
+    if (/^\s*\[\s*mcp_servers\.jev\s*\]/m.test(outside)) {
+        throw new SetupError(`${path} already defines [mcp_servers.jev] outside the jev setup block; remove it or rename it, then run jev setup again. Nothing was written.`);
+    }
+    const block = codexBlock(sel, command, o.hookArgs, o.timeoutSec);
+    const rest = outside.replace(/\s+$/, "");
+    const after = (rest ? rest + "\n\n" : "") + block;
+    return [{ path, before, after, changed: before !== after }];
+}
+/** One line for people: what the selection turns on. */
+export function describeSelection(o) {
+    const sel = resolveSelection(o);
+    const parts = [
+        sel.guards.length ? `guards ${sel.guards.join(",")}` : "",
+        sel.compact ? "compaction advisor" : "",
+        sel.tools.length ? `tools ${sel.tools.join(",")}` : "",
+    ].filter(Boolean);
+    return parts.join("; ");
+}
+export function plan(o) {
+    return o.harness === "claude" ? planClaude(o) : planCodex(o);
+}
+export function apply(changes) {
+    for (const c of changes) {
+        if (!c.changed)
+            continue;
+        mkdirSync(dirname(c.path), { recursive: true });
+        writeFileSync(c.path, c.after);
+    }
+}

package/dist/tools/ask-jev.d.ts

@@ -0,0 +1,7 @@
+import { type RunCommand } from "../files/assemble.ts";
+import { type JevTool } from "./types.ts";
+/** The usage guidance: a system prompt line under pi, server instructions under MCP. */
+export declare const ASK_JEV_NUDGE: string;
+/** `run` is the unguarded runner the gate wraps; tests pass a fake. */
+export declare function makeAskJev(run?: RunCommand): JevTool;
+export declare const askJev: JevTool;

package/dist/tools/ask-jev.js

@@ -0,0 +1,42 @@
+/**
+ * Level 10: ask_jev on any situation. The agent passes its own state, paths for code to read,
+ * a command for code to run, and its question block. Code assembles one state and makes one call.
+ * A command runs through the bash gate first. Over the budget, the error names the parts and a split.
+ */
+import { parseQuestions } from "../files/ask-files.js";
+import { AskStateError, assembleState } from "../files/assemble.js";
+import { ASK_JEV_DESCRIPTION } from "./description.js";
+import { gatedRunner } from "./run-command.js";
+import { fail, object, ok, str } from "./types.js";
+/** The usage guidance: a system prompt line under pi, server instructions under MCP. */
+export const ASK_JEV_NUDGE = "You have ask_jev. When you need a classification, a risk score, or a yes or no with a confidence, " +
+    "prefer it over reasoning it out yourself. Give it paths or a command instead of pasting content. " +
+    "It answers in 300 ms and costs almost nothing.";
+/** `run` is the unguarded runner the gate wraps; tests pass a fake. */
+export function makeAskJev(run) {
+    return {
+        name: "ask_jev",
+        label: "Ask Jev",
+        description: ASK_JEV_DESCRIPTION,
+        parameters: object({
+            questions_json: str("The question block, a JSON object keyed by question id"),
+            state: str("Your own state: plain text, or a JSON object as a string. Short. Not for pasting files or output."),
+            paths: { type: "array", items: { type: "string" }, description: "Files or globs for code to read into files[\"path\"]. Up to 20 files." },
+            command: str("A command for code to run in the repo; its result goes into output. Runs through the bash gate."),
+        }, ["questions_json"]),
+        async execute(p, ctx) {
+            try {
+                const questions = parseQuestions(p.questions_json);
+                const { state, summary } = await assembleState({ state: p.state, paths: p.paths, command: p.command }, ctx.cwd, gatedRunner(ctx, run));
+                const result = await ctx.decide("ask_jev", state, questions, { summary });
+                return ok({ answers: result.answers, state_summary: summary, usage: result.usage, model: result.model });
+            }
+            catch (err) {
+                const text = err instanceof AskStateError ? err.message : `ask_jev error: ${err?.message ?? err}`;
+                ctx.report("error", { hook: "ask_jev", message: text });
+                return fail(text);
+            }
+        },
+    };
+}
+export const askJev = makeAskJev();

package/dist/tools/compact-tool.d.ts

@@ -0,0 +1,2 @@
+import { type JevTool } from "./types.ts";
+export declare const shouldICompact: JevTool;

package/dist/tools/compact-tool.js

@@ -0,0 +1,33 @@
+/**
+ * Level 7, option B: should_i_compact on demand. The same four questions and tiers as the turn-end
+ * hook, but the agent asks. The harness supplies the session view; without one the tool says so.
+ */
+import { compactVerdict } from "../compact/compact-on-demand.js";
+import { evaluateCompaction } from "../compact/evaluate.js";
+import { fail, ok } from "./types.js";
+const NO_SIGNALS = {
+    switched_gears: { type: "noul", noul: 0 }, at_boundary: { type: "noul", noul: 0 },
+    needs_history: { type: "score", score: 2 }, mid_operation: { type: "noul", noul: 0 },
+};
+export const shouldICompact = {
+    name: "should_i_compact",
+    label: "Should I compact",
+    description: "Ask whether now is a good moment to compact the conversation. Returns should_compact, a tier " +
+        "(silent, notice, recommend, request), the reason, and the current context percent. Cheap, call it freely.",
+    parameters: { type: "object", properties: {} },
+    async execute(_p, ctx) {
+        try {
+            const source = ctx.compaction;
+            const input = source ? await source.input() : null;
+            if (!source || !input) {
+                return fail("should_i_compact error: no session history is available to this tool. Enable the Level 7 hooks (jev setup --level 7) so the session is recorded.");
+            }
+            const r = await evaluateCompaction(input, "should_i_compact", ctx.decide, ctx.report, source.action);
+            source.onEvaluation?.(r);
+            return ok(compactVerdict(r.decision, r.answers ?? NO_SIGNALS, r.usage, input.lines, source.action));
+        }
+        catch (err) {
+            return fail(`should_i_compact error: ${err?.message ?? err}`);
+        }
+    },
+};

package/dist/tools/description.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Level 10, option B: the tool description is the teaching.
+ * The prompt says what to ask. The description says how: what Jev is, the three question types, when a typed answer beats reasoning, and when it does not.
+ */
+export declare const ASK_JEV_DESCRIPTION: string;

package/dist/tools/description.js

@@ -0,0 +1,20 @@
+/**
+ * Level 10, option B: the tool description is the teaching.
+ * The prompt says what to ask. The description says how: what Jev is, the three question types, when a typed answer beats reasoning, and when it does not.
+ */
+export const ASK_JEV_DESCRIPTION = [
+    "Ask Jev, a fast decision model, typed questions about one situation: files, a command's output, your own state, or any mix. It answers in about 300 ms for a fraction of a cent, and each answer is a number you can branch on, not prose. Use it whenever a judgment call would otherwise cost you a long think.",
+    "",
+    "Do not paste content you already have; that costs output tokens. Pass paths and code reads the files into files[\"path\"]. Pass command and code runs it in the repo and puts the result into output {command, exit_code, stdout, stderr}. Use state for what only you can say: a customer report, your plan, a line of context. Plain text or a JSON object as a string; your field names are kept as is. You can combine all three, and you never receive the files or the output, only the answers.",
+    "",
+    "One call judges one situation: up to 20 files and about 60k tokens in total. Over that the call is refused with a message naming the parts and a split that fits; make two calls with the same questions_json. For many files judged separately use ask_jev_files instead.",
+    "",
+    "questions_json: a JSON object keyed by question id. Three types:",
+    '  noul   {"type":"noul","instructions":"Is `output` a real failure rather than a flaky one?","criteria":{"true":"...","false":"..."}}  -> { noul: 0..1 }',
+    '  choice {"type":"choice","instructions":"What kind of failure is `output`?","criteria":{"bug_in_code":"...","wrong_test":"...","environment":"...","other":"..."}}  -> { choice, confidence, probabilities }',
+    '  score  {"type":"score","instructions":"How risky is `diff`?","criteria":["Isolated, tested","Some callers","Security sensitive, no tests"]}  -> { score, confidence, legend }',
+    "",
+    "Write questions against files[\"path\"], output, or your own field names. Good uses: run the tests through command and classify the failure before choosing a fix, put git diff through command and score its risk before committing, pass the customer's words as state with the relevant paths and decide bug or expected, decide whether a request is clear enough to plan.",
+    "Ask every question you might need in one call; they share the state. Always give a choice an `other` option. Describe situations, not degrees.",
+    "Not for: exact lookups, counting, math, or anything a grep answers. Not a substitute for reading code you need to edit.",
+].join("\n");

package/dist/tools/file-tools.d.ts

@@ -0,0 +1,7 @@
+import { type JevTool } from "./types.ts";
+export declare const QUESTION_SCHEMA: string;
+export declare const askJevFileBool: JevTool;
+export declare const askJevFileChoice: JevTool;
+export declare const askJevFileScore: JevTool;
+export declare const askJevFiles: JevTool;
+export declare const pickFirstFileTool: JevTool;

package/dist/tools/file-tools.js

@@ -0,0 +1,127 @@
+/**
+ * Levels 8 and 9: judgments about files the agent never loads.
+ *
+ *   ask_jev_file_bool(path, question, yes?, no?)
+ *   ask_jev_file_choice(path, question, options)
+ *   ask_jev_file_score(path, question, levels)
+ *   ask_jev_files(paths_or_globs, questions_json, recursive?)   one call per file, in parallel
+ *   pick_first_file(question, candidates)                        a second pass: which to open first
+ */
+import { askFileBool } from "../files/ask-file-bool.js";
+import { askFileChoice } from "../files/ask-file-choice.js";
+import { askFileScore } from "../files/ask-file-score.js";
+import { askFiles } from "../files/ask-files.js";
+import { pickFirstFile } from "../files/pick-first.js";
+import { FileStateError } from "../files/read-state.js";
+import { fail, object, ok, str } from "./types.js";
+const WHEN = "Use this for a judgment about what a file does or contains, without reading it into your context. " +
+    "Write the question against `content`, which is the file's text. Use the read tool instead when you need the code itself, to edit or quote it. " +
+    "Exact lookups, does this string appear, how many lines, belong to grep, not here.";
+export const QUESTION_SCHEMA = 'questions_json is a JSON object keyed by question id. Three types. ' +
+    'noul: {"type":"noul","instructions":"Does `content` ...?","criteria":{"true":"...","false":"..."}} returns a probability of yes. ' +
+    'choice: {"type":"choice","instructions":"Which ... is `content`?","criteria":{"option_a":"when it applies","option_b":"...","other":"none of the above"}} returns one of your keys plus confidence, up to 255 options. ' +
+    'score: {"type":"score","instructions":"How ... is `content`?","criteria":["lowest situation","...","highest situation"]} returns a position on your levels, two to ten of them. ' +
+    "Write every question against `content`, the file's text; `path` is also in the state. Ask every question you might need in one block, it is one call per file either way.";
+const fileFail = (err) => fail(err instanceof FileStateError ? err.message : `error: ${err?.message ?? err}`);
+const PATH = str("File path, relative to the repo");
+export const askJevFileBool = {
+    name: "ask_jev_file_bool",
+    label: "Ask Jev about a file, yes or no",
+    description: `Yes or no about one file. Returns { path, answer, noul } where noul is the probability of yes, 0 to 1. ${WHEN}`,
+    parameters: object({
+        path: PATH,
+        question: str("A yes or no question about `content`, for example: Does `content` validate authentication tokens?"),
+        yes: str("What counts as yes"),
+        no: str("What counts as no"),
+    }, ["path", "question"]),
+    async execute(p, ctx) {
+        try {
+            return ok(await askFileBool(p.path, p.question, ctx.cwd, { yes: p.yes, no: p.no }, (s, q) => ctx.decide("ask_jev_file_bool", s, q, { path: p.path })));
+        }
+        catch (err) {
+            return fileFail(err);
+        }
+    },
+};
+export const askJevFileChoice = {
+    name: "ask_jev_file_choice",
+    label: "Ask Jev about a file, pick one",
+    description: `Pick one option about one file. Returns { path, choice, confidence, probabilities }. The choice is always one of your options; an "other" option is added if you leave none. ${WHEN}`,
+    parameters: object({
+        path: PATH,
+        question: str("The question, for example: Which layer is `content`?"),
+        options: { type: "object", additionalProperties: { type: "string" }, description: "Option name to a one line description of when it applies. Up to 255." },
+    }),
+    async execute(p, ctx) {
+        try {
+            return ok(await askFileChoice(p.path, p.question, p.options, ctx.cwd, (s, q) => ctx.decide("ask_jev_file_choice", s, q, { path: p.path })));
+        }
+        catch (err) {
+            return fileFail(err);
+        }
+    },
+};
+export const askJevFileScore = {
+    name: "ask_jev_file_score",
+    label: "Ask Jev about a file, on a scale",
+    description: `A position on a scale you define, about one file. Returns { path, score, top, nearest, confidence, legend }. Levels are ordered low to high, two to ten of them, each a described situation. ${WHEN}`,
+    parameters: object({
+        path: PATH,
+        question: str("The question, for example: How risky is a refactor of `content`?"),
+        levels: { type: "array", items: { type: "string" }, description: "Ordered low to high, each level a situation, for example: Isolated and well tested" },
+    }),
+    async execute(p, ctx) {
+        try {
+            return ok(await askFileScore(p.path, p.question, p.levels, ctx.cwd, (s, q) => ctx.decide("ask_jev_file_score", s, q, { path: p.path })));
+        }
+        catch (err) {
+            return fileFail(err);
+        }
+    },
+};
+export const askJevFiles = {
+    name: "ask_jev_files",
+    label: "Ask Jev about many files",
+    description: "Ask the same typed questions of many files at once without reading any of them. Code expands globs and directories, " +
+        "drops node_modules, .git, binaries, and files over the budget, caps the list at 255, then makes one Jev call per file in parallel. " +
+        "Returns { results: [{ path, answers }], skipped: [{ path, reason }], calls }. " + QUESTION_SCHEMA +
+        " Use read when you need a file's code; use grep for exact strings.",
+    parameters: object({
+        paths_or_globs: { type: "array", items: { type: "string" }, description: 'Files, directories, or globs, relative to the repo, for example ["src/**/*.ts"] or ["src/http"]' },
+        questions_json: str("The question block as a JSON string"),
+        recursive: { type: "boolean", description: "For directories: include every file below them. Default false." },
+    }, ["paths_or_globs", "questions_json"]),
+    async execute(p, ctx) {
+        try {
+            return ok(await askFiles(p.paths_or_globs, p.questions_json, ctx.cwd, {
+                recursive: p.recursive ?? false,
+                decide: (s, q) => ctx.decide("ask_jev_files", s, q, { path: s.path }),
+            }));
+        }
+        catch (err) {
+            return fail(`error: ${err?.message ?? err}`);
+        }
+    },
+};
+export const pickFirstFileTool = {
+    name: "pick_first_file",
+    label: "Pick the file to open first",
+    description: "After ask_jev_files, choose which of a list of files to open first for a goal. One Choice keyed by path, so the pick is always a real file. " +
+        "Returns { path | null, confidence, probabilities }. Pass a short note per path if you have one, for example the answers you already got.",
+    parameters: object({
+        question: str("The goal, for example: Which file should I open first to fix the proration bug?"),
+        candidates: {
+            type: "array",
+            items: object({ path: str(), note: str() }, ["path"]),
+            description: "Paths, with an optional one line note each",
+        },
+    }),
+    async execute(p, ctx) {
+        try {
+            return ok(await pickFirstFile(p.question, p.candidates, (s, q) => ctx.decide("pick_first_file", s, q)));
+        }
+        catch (err) {
+            return fail(`error: ${err?.message ?? err}`);
+        }
+    },
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The Jev tools, one definition per tool for every harness, and the sets each surface exposes.
+ */
+export * from "./types.ts";
+export * from "./description.ts";
+export * from "./file-tools.ts";
+export * from "./ask-jev.ts";
+export * from "./compact-tool.ts";
+export * from "./run-command.ts";
+export * from "./sets.ts";

package/dist/tools/index.js

@@ -0,0 +1,10 @@
+/**
+ * The Jev tools, one definition per tool for every harness, and the sets each surface exposes.
+ */
+export * from "./types.js";
+export * from "./description.js";
+export * from "./file-tools.js";
+export * from "./ask-jev.js";
+export * from "./compact-tool.js";
+export * from "./run-command.js";
+export * from "./sets.js";

package/dist/tools/run-command.d.ts

@@ -0,0 +1,7 @@
+import { type CommandOutput, type RunCommand } from "../files/assemble.ts";
+import type { ToolContext } from "./types.ts";
+export declare const COMMAND_TIMEOUT_MS = 60000;
+export declare const MAX_OUTPUT_CHARS = 200000;
+export declare function runCommand(command: string, cwd: string): Promise<CommandOutput>;
+/** A runner that refuses what the bash gate blocks, reporting the gate's verdict either way. */
+export declare function gatedRunner(ctx: ToolContext, run?: RunCommand): RunCommand;

package/dist/tools/run-command.js

@@ -0,0 +1,27 @@
+/**
+ * Run a command for a state. The output is captured, never streamed to the agent, and the
+ * command passes the bash gate first: a state should only ever need reads.
+ */
+import { exec } from "node:child_process";
+import { BLOCK_NOTICE, gateBashCommand } from "../guards/bash-gate.js";
+import { AskStateError } from "../files/assemble.js";
+export const COMMAND_TIMEOUT_MS = 60_000;
+export const MAX_OUTPUT_CHARS = 200_000;
+export function runCommand(command, cwd) {
+    return new Promise((resolve) => {
+        exec(command, { cwd, timeout: COMMAND_TIMEOUT_MS, maxBuffer: MAX_OUTPUT_CHARS * 4, env: { ...process.env, CI: "1" } }, (err, stdout, stderr) => {
+            const code = err && typeof err.code === "number" ? err.code : err ? null : 0;
+            resolve({ command, exit_code: code, stdout: String(stdout).slice(0, MAX_OUTPUT_CHARS), stderr: String(stderr).slice(0, MAX_OUTPUT_CHARS) });
+        });
+    });
+}
+/** A runner that refuses what the bash gate blocks, reporting the gate's verdict either way. */
+export function gatedRunner(ctx, run = runCommand) {
+    return async (command, cwd) => {
+        const gate = await gateBashCommand(command, cwd, (s, q) => ctx.decide("ask_jev command gate", s, q));
+        ctx.report("hook", { hook: "ask_jev command", tool: "bash", command, block: gate.block, reason: gate.reason });
+        if (gate.block)
+            throw new AskStateError(`ask_jev: the command was refused by the bash gate: ${gate.reason}. ${BLOCK_NOTICE} ask_jev commands should only read.`);
+        return run(command, cwd);
+    };
+}

package/dist/tools/sets.d.ts

@@ -0,0 +1,9 @@
+import type { JevTool } from "./types.ts";
+export declare const ALL_TOOLS: JevTool[];
+export declare const LEVEL_TOOLS: Record<number, string[]>;
+export declare const toolByName: (name: string) => JevTool | undefined;
+/** By level, by names, or all of them. Unknown names and levels are errors, not silent drops. */
+export declare function selectTools(opts?: {
+    level?: number;
+    names?: string[];
+}): JevTool[];

package/dist/tools/sets.js

@@ -0,0 +1,32 @@
+/**
+ * Which tools a surface exposes. The package speaks tool names; level numbers are the lab's alias.
+ */
+import { askJev } from "./ask-jev.js";
+import { shouldICompact } from "./compact-tool.js";
+import { askJevFileBool, askJevFileChoice, askJevFileScore, askJevFiles, pickFirstFileTool } from "./file-tools.js";
+export const ALL_TOOLS = [shouldICompact, askJevFileBool, askJevFileChoice, askJevFileScore, askJevFiles, pickFirstFileTool, askJev];
+export const LEVEL_TOOLS = {
+    7: ["should_i_compact"],
+    8: ["ask_jev_file_bool", "ask_jev_file_choice", "ask_jev_file_score"],
+    9: ["ask_jev_files", "pick_first_file"],
+    10: ["ask_jev"],
+};
+export const toolByName = (name) => ALL_TOOLS.find((t) => t.name === name);
+/** By level, by names, or all of them. Unknown names and levels are errors, not silent drops. */
+export function selectTools(opts = {}) {
+    if (opts.level !== undefined && opts.names?.length)
+        throw new Error("pass a level or tool names, not both");
+    if (opts.level !== undefined) {
+        const names = LEVEL_TOOLS[opts.level];
+        if (!names)
+            throw new Error(`no Jev tools for level ${opts.level}; tools exist for levels ${Object.keys(LEVEL_TOOLS).join(", ")}`);
+        return names.map((n) => toolByName(n));
+    }
+    if (opts.names?.length) {
+        const unknown = opts.names.filter((n) => !toolByName(n));
+        if (unknown.length)
+            throw new Error(`unknown tool ${unknown.join(", ")}; known: ${ALL_TOOLS.map((t) => t.name).join(", ")}`);
+        return opts.names.map((n) => toolByName(n));
+    }
+    return ALL_TOOLS;
+}