@bobobowis/jev-kit 0.0.0-stage → 0.2.0

package/dist/ledger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Level 10, option C: the spend ledger.
+ * Every ask_jev call is counted against the agent's own turn cost, so the session can say what the habit cost and what it replaced. Numbers in code: nothing here asks Jev anything.
+ */
+export interface JevUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cost?: number;
+}
+/** Jev's list price per input token when the endpoint reports no cost. Output is free. */
+export declare const JEV_INPUT_USD_PER_M = 0.042;
+export interface Ledger {
+    calls: number;
+    questions: number;
+    inputTokens: number;
+    outputTokens: number;
+    usd: number;
+}
+export declare const emptyLedger: () => Ledger;
+export declare function record(ledger: Ledger, usage: JevUsage | undefined, questionCount: number): Ledger;
+/** One line the agent, or the window, can print at the end of a task. */
+export declare function summarize(ledger: Ledger, agentUsd: number): string;

package/dist/ledger.js

@@ -0,0 +1,26 @@
+/**
+ * Level 10, option C: the spend ledger.
+ * Every ask_jev call is counted against the agent's own turn cost, so the session can say what the habit cost and what it replaced. Numbers in code: nothing here asks Jev anything.
+ */
+/** Jev's list price per input token when the endpoint reports no cost. Output is free. */
+export const JEV_INPUT_USD_PER_M = 0.042;
+export const emptyLedger = () => ({ calls: 0, questions: 0, inputTokens: 0, outputTokens: 0, usd: 0 });
+export function record(ledger, usage, questionCount) {
+    const input = usage?.input_tokens ?? 0;
+    const output = usage?.output_tokens ?? 0;
+    return {
+        calls: ledger.calls + 1,
+        questions: ledger.questions + questionCount,
+        inputTokens: ledger.inputTokens + input,
+        outputTokens: ledger.outputTokens + output,
+        usd: ledger.usd + (usage?.cost ?? (input * JEV_INPUT_USD_PER_M) / 1e6),
+    };
+}
+/** One line the agent, or the window, can print at the end of a task. */
+export function summarize(ledger, agentUsd) {
+    if (ledger.calls === 0)
+        return "No Jev calls this session.";
+    const ratio = ledger.usd > 0 ? Math.round(agentUsd / ledger.usd) : 0;
+    return `${ledger.calls} Jev call${ledger.calls === 1 ? "" : "s"}, ${ledger.questions} question${ledger.questions === 1 ? "" : "s"}, $${ledger.usd.toFixed(6)}` +
+        (ratio ? `, the agent's own spend was ${ratio}x that` : "");
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,28 @@
+import type { Decider } from "../events/index.ts";
+import type { CompactionSource, JevTool } from "../tools/types.ts";
+/** Protocol revisions whose tools subset this server speaks. A client's revision is echoed when known. */
+export declare const PROTOCOL_VERSIONS: string[];
+export interface ServerOptions {
+    tools: JevTool[];
+    cwd: string;
+    decide: Decider;
+    report(kind: string, payload: Record<string, unknown>): void;
+    version?: string;
+}
+type Message = {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: any;
+};
+type Reply = Record<string, unknown>;
+/** The Level 7 hooks' notes for the most recent session in the project, for should_i_compact. */
+export declare function latestSessionSource(cwd: string): CompactionSource;
+export declare function instructionsFor(tools: JevTool[]): string;
+/** Handle one message. Returns the reply to send, or null for notifications. */
+export declare function createHandler(opts: ServerOptions): (msg: Message) => Promise<Reply | null>;
+/** Serve until stdin closes. Calls run concurrently; replies go out as each one finishes. */
+export declare function serve(opts: ServerOptions, input?: NodeJS.ReadableStream, output?: {
+    write(s: string): unknown;
+}): Promise<void>;
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,124 @@
+/**
+ * The Jev tools over MCP: newline-delimited JSON-RPC 2.0 on stdio, the subset a tool server needs.
+ * initialize, notifications/initialized, tools/list, tools/call, ping. Unknown methods get -32601,
+ * unknown tools -32602, and a failing tool is an `isError` result, never a crash.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { emptyLedger, record, summarize } from "../ledger.js";
+import { HOOK_LINES } from "../hooks/harness.js";
+import { readState, stateDir } from "../hooks/state.js";
+import { ASK_JEV_NUDGE } from "../tools/ask-jev.js";
+/** Protocol revisions whose tools subset this server speaks. A client's revision is echoed when known. */
+export const PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+/** The Level 7 hooks' notes for the most recent session in the project, for should_i_compact. */
+export function latestSessionSource(cwd) {
+    return {
+        action: "ask_user",
+        input: () => {
+            const dir = stateDir(cwd);
+            let newest = null;
+            try {
+                for (const name of readdirSync(dir)) {
+                    const m = name.match(/^session-(.+)\.json$/);
+                    if (!m)
+                        continue;
+                    const at = statSync(join(dir, name)).mtimeMs;
+                    if (!newest || at > newest.at)
+                        newest = { name: m[1], at };
+                }
+            }
+            catch {
+                return null;
+            }
+            if (!newest)
+                return null;
+            const s = readState(dir, newest.name);
+            if (!s.requests.length)
+                return null;
+            return { requests: s.requests, recentTurn: "", toolsThisTurn: [], usage: null, compactable: true, lines: HOOK_LINES };
+        },
+    };
+}
+export function instructionsFor(tools) {
+    const lines = ["Jev answers typed questions (yes or no, pick one, a score) about files, a command's output, or your own state, in about 300 ms for a fraction of a cent. Prefer it to reasoning a judgment call out yourself."];
+    if (tools.some((t) => t.name === "ask_jev"))
+        lines.push(ASK_JEV_NUDGE);
+    if (tools.some((t) => t.name.startsWith("ask_jev_file")))
+        lines.push("The ask_jev_file tools judge one file without loading it into your context; use read when you need the code itself.");
+    return lines.join("\n\n");
+}
+/** Handle one message. Returns the reply to send, or null for notifications. */
+export function createHandler(opts) {
+    let ledger = emptyLedger();
+    const ctx = {
+        cwd: opts.cwd, harness: "mcp", decide: opts.decide, report: opts.report,
+        compaction: latestSessionSource(opts.cwd),
+    };
+    const ok = (id, result) => ({ jsonrpc: "2.0", id: id ?? null, result });
+    const err = (id, code, message) => ({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+    return async function handle(msg) {
+        const isRequest = msg.id !== undefined && msg.id !== null;
+        switch (msg.method) {
+            case "initialize": {
+                const asked = String(msg.params?.protocolVersion ?? "");
+                return ok(msg.id, {
+                    protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: "jev", version: opts.version ?? "0.0.0" },
+                    instructions: instructionsFor(opts.tools),
+                });
+            }
+            case "ping":
+                return isRequest ? ok(msg.id, {}) : null;
+            case "tools/list":
+                return ok(msg.id, { tools: opts.tools.map((t) => ({ name: t.name, title: t.label, description: t.description, inputSchema: t.parameters })) });
+            case "tools/call": {
+                const name = String(msg.params?.name ?? "");
+                const tool = opts.tools.find((t) => t.name === name);
+                if (!tool)
+                    return err(msg.id, -32602, `Unknown tool: ${name}. This server has ${opts.tools.map((t) => t.name).join(", ")}.`);
+                const r = await tool.execute(msg.params?.arguments ?? {}, ctx);
+                if (tool.name === "ask_jev" && !r.isError) {
+                    const p = r.payload;
+                    ledger = record(ledger, p.usage, Object.keys(p.answers).length);
+                    opts.report("ledger", { ...ledger, summary: summarize(ledger, 0) });
+                }
+                const result = { content: [{ type: "text", text: r.text }], isError: r.isError ?? false };
+                if (!r.isError && r.payload && typeof r.payload === "object" && !Array.isArray(r.payload))
+                    result.structuredContent = r.payload;
+                return ok(msg.id, result);
+            }
+            default:
+                if (msg.method?.startsWith("notifications/") || !isRequest)
+                    return null;
+                return err(msg.id, -32601, `Method not found: ${msg.method}`);
+        }
+    };
+}
+/** Serve until stdin closes. Calls run concurrently; replies go out as each one finishes. */
+export async function serve(opts, input = process.stdin, output = process.stdout) {
+    const handle = createHandler(opts);
+    const send = (reply) => { if (reply)
+        output.write(JSON.stringify(reply) + "\n"); };
+    const pending = new Set();
+    for await (const line of createInterface({ input, crlfDelay: Infinity })) {
+        if (!line.trim())
+            continue;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+            continue;
+        }
+        const p = handle(msg)
+            .then(send)
+            .catch((e) => send(msg.id !== undefined ? { jsonrpc: "2.0", id: msg.id, error: { code: -32603, message: e?.message ?? String(e) } } : null))
+            .finally(() => pending.delete(p));
+        pending.add(p);
+    }
+    await Promise.all(pending);
+}

package/dist/policy/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Policy helpers: the numbers in code that turn answers into decisions.
+ * Jev never sees these. Tuning means changing a number, not a prompt.
+ */
+import type { ScoreAnswer } from "../core/types.ts";
+/** Normalize a score answer to 0-1 against its own top level, so scales of different lengths compare. */
+export declare function normalized(answer: ScoreAnswer): number;
+/** Weighted sum of 0-1 parts. Weights are divided by their total, so they need not add up to 1. */
+export declare function weighted<K extends string>(parts: Record<K, number>, weights: Record<K, number>): number;
+/** The two confidence thresholds a gate reads. */
+export declare const CONFIDENCE: {
+    readonly REVIEW_FLOOR: 0.5;
+    readonly DESTRUCTIVE_BAR: 0.9;
+};
+export type ConfidenceBand = "review" | "confirm" | "act";
+/** The answer says what, confidence says whether: below the floor a human decides, above the bar it runs, in between it asks. */
+export declare function confidenceBand(confidence: number, floor?: number, bar?: number): ConfidenceBand;

package/dist/policy/index.js

@@ -0,0 +1,30 @@
+/** Normalize a score answer to 0-1 against its own top level, so scales of different lengths compare. */
+export function normalized(answer) {
+    const topLevel = Object.keys(answer.legend).length - 1;
+    return topLevel === 0 ? 0 : answer.score / topLevel;
+}
+/** Weighted sum of 0-1 parts. Weights are divided by their total, so they need not add up to 1. */
+export function weighted(parts, weights) {
+    const keys = Object.keys(weights);
+    const total = keys.reduce((n, k) => n + weights[k], 0);
+    if (total <= 0)
+        throw new RangeError("weights must add up to more than 0");
+    return keys.reduce((n, k) => {
+        if (typeof parts[k] !== "number")
+            throw new RangeError(`missing part "${k}"`);
+        return n + (weights[k] / total) * parts[k];
+    }, 0);
+}
+/** The two confidence thresholds a gate reads. */
+export const CONFIDENCE = {
+    REVIEW_FLOOR: 0.5, // below this: don't act, ask a human
+    DESTRUCTIVE_BAR: 0.9, // above this: act without confirmation
+};
+/** The answer says what, confidence says whether: below the floor a human decides, above the bar it runs, in between it asks. */
+export function confidenceBand(confidence, floor = CONFIDENCE.REVIEW_FLOOR, bar = CONFIDENCE.DESTRUCTIVE_BAR) {
+    if (confidence < floor)
+        return "review";
+    if (confidence > bar)
+        return "act";
+    return "confirm";
+}

package/dist/setup/index.d.ts

@@ -0,0 +1,76 @@
+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;
+    /** The bash and MCP gates ask the user when Jev is unsure or leans destructive. Claude Code only. */
+    ask?: boolean;
+    /** The bash and MCP gates approve what Jev is sure only reads. Claude Code only. */
+    allowReadOnly?: 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;
+    ask?: boolean;
+    allowReadOnly?: boolean;
+}
+type Selection = Pick<SetupOptions, "guards" | "tools" | "compact" | "level" | "ask" | "allowReadOnly"> & {
+    harness?: SetupHarness;
+};
+export declare function resolveSelection(o: Selection): 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: Selection): string;
+export declare function plan(o: SetupOptions): FileChange[];
+export declare function apply(changes: FileChange[]): void;
+export {};

package/dist/setup/index.js

@@ -0,0 +1,221 @@
+/**
+ * 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, LEVEL6_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)
+            LEVEL6_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");
+    const ladder = o.ask || o.allowReadOnly;
+    if (ladder && !guards.has("bash") && !guards.has("mcp"))
+        throw new SetupError("--ask and --allow-read-only apply to the bash and mcp guards; add one of them to --guards");
+    if (o.harness === "codex" && (ladder || guards.has("mcp"))) {
+        throw new SetupError("Codex hooks can only deny, so the mcp guard, --ask, and --allow-read-only are Claude Code only");
+    }
+    return { guards: [...guards], tools: [...tools], compact, ...(o.ask ? { ask: true } : {}), ...(o.allowReadOnly ? { allowReadOnly: true } : {}) };
+}
+/** 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 ladder = [...(sel.ask ? ["--ask"] : []), ...(sel.allowReadOnly ? ["--allow-read-only"] : [])];
+    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"]));
+    const preGuards = sel.guards.filter((g) => g === "bash" || g === "write");
+    if (pre.length)
+        out.PreToolUse = [{ matcher: pre.join("|"), hooks: [run("PreToolUse", [...guardFlag(preGuards), ...(sel.guards.includes("bash") ? ladder : [])])] }];
+    if (sel.guards.includes("mcp"))
+        (out.PreToolUse ??= []).push({ matcher: "mcp__.*", hooks: [run("PreToolUse", [...guardFlag(["mcp"]), ...ladder])] });
+    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.ask ? "ask when unsure" : "",
+        sel.allowReadOnly ? "approve read only" : "",
+        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;