@bobobowis/jev-kit 0.0.0-stage → 0.2.0

package/dist/files/ask.d.ts

@@ -0,0 +1,12 @@
+import type { Answer, State } from "../core/types.ts";
+import type { Decide } from "./decide.ts";
+export interface AskResult {
+    answers: Record<string, Answer>;
+    usage?: unknown;
+    model?: string;
+    state_summary?: unknown;
+}
+/** A JSON string becomes structured state; anything else is sent as the string it is. */
+export declare function parseState(raw: string | Record<string, unknown>): State;
+/** A: any state, any questions, one call. Empty state is refused; Jev cannot judge nothing. */
+export declare function askJev(rawState: string | Record<string, unknown>, questionsJson: string, decide?: Decide): Promise<AskResult>;

package/dist/files/ask.js

@@ -0,0 +1,28 @@
+/**
+ * Level 10, option A: ask_jev on any content.
+ * The general form. 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, validates, and makes one call. The agent never receives the files or the output, only the answers.
+ */
+import { jev } from "../core/client.js";
+import { parseQuestions } from "./ask-files.js";
+/** A JSON string becomes structured state; anything else is sent as the string it is. */
+export function parseState(raw) {
+    if (typeof raw !== "string")
+        return raw;
+    const t = raw.trim();
+    if ((t.startsWith("{") && t.endsWith("}")) || (t.startsWith("[") && t.endsWith("]"))) {
+        try {
+            return JSON.parse(t);
+        }
+        catch { /* not JSON after all, send the text */ }
+    }
+    return raw;
+}
+/** A: any state, any questions, one call. Empty state is refused; Jev cannot judge nothing. */
+export async function askJev(rawState, questionsJson, decide = (s, q) => jev.systemOne(s, q)) {
+    const state = parseState(rawState);
+    if (typeof state === "string" ? !state.trim() : !state || Object.keys(state).length === 0)
+        throw new Error("state is empty");
+    const questions = parseQuestions(questionsJson);
+    const { answers, usage, model } = await decide(state, questions);
+    return { answers, usage, model };
+}

package/dist/files/assemble.d.ts

@@ -0,0 +1,52 @@
+import { type Skipped } from "./prune.ts";
+/** Roughly four characters per token, the same estimate the file reader uses. */
+export declare const tokensOf: (text: string) => number;
+/** Leave room for the questions inside Jev's shared budget. */
+export declare const STATE_TOKEN_BUDGET: number;
+/** A single situation, not a corpus. Many files belong to ask_jev_files. */
+export declare const MAX_FILES_PER_CALL = 20;
+/** The agent's own note is for context, not for pasting content that code could fetch. */
+export declare const MAX_OWN_STATE_CHARS = 8000;
+export interface CommandOutput {
+    command: string;
+    exit_code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type RunCommand = (command: string, cwd: string) => Promise<CommandOutput>;
+export interface AssembleInput {
+    state?: string | Record<string, unknown>;
+    paths?: string[];
+    command?: string;
+}
+export interface Assembled {
+    state: Record<string, unknown>;
+    summary: {
+        own_fields: string[];
+        files: string[];
+        output: string | null;
+        skipped: Skipped[];
+        tokens: number;
+    };
+}
+interface Part {
+    name: string;
+    tokens: number;
+    kind: "own" | "file" | "output";
+}
+export declare class AskStateError extends Error {
+    constructor(message: string);
+}
+/**
+ * Greedy first fit, largest first. Returns groups whose token sums fit the budget, so the error
+ * can say "call 1: these, call 2: those" instead of "too big".
+ */
+export declare function suggestSplit(parts: Part[], budget: number): Part[][];
+/** The message the agent reads when one call cannot hold the situation. */
+export declare function overflowMessage(parts: Part[], budget: number): string;
+/**
+ * Build the state. Own state first, then files, then the command's output. Nothing is truncated:
+ * over the file cap or the token budget, the call is refused with a message that says how to split.
+ */
+export declare function assembleState(input: AssembleInput, cwd: string, run: RunCommand): Promise<Assembled>;
+export {};

package/dist/files/assemble.js

@@ -0,0 +1,129 @@
+/**
+ * Level 10, shared: the state ask_jev sends is assembled in code.
+ * The agent's own state is the base. `paths` become `files`, keyed by path. `command` becomes `output`. One call, one situation. Over the budget, the error names the parts and a split that fits, so the agent can make two calls instead of one truncated one.
+ */
+import { LIMITS } from "../core/types.js";
+import { FileStateError, readFileState } from "./read-state.js";
+import { expandPatterns, pruneFiles } from "./prune.js";
+import { parseState } from "./ask.js";
+/** Roughly four characters per token, the same estimate the file reader uses. */
+export const tokensOf = (text) => Math.ceil(text.length / 4);
+/** Leave room for the questions inside Jev's shared budget. */
+export const STATE_TOKEN_BUDGET = LIMITS.TOTAL_TOKEN_BUDGET - 4000;
+/** A single situation, not a corpus. Many files belong to ask_jev_files. */
+export const MAX_FILES_PER_CALL = 20;
+/** The agent's own note is for context, not for pasting content that code could fetch. */
+export const MAX_OWN_STATE_CHARS = 8000;
+export class AskStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AskStateError";
+    }
+}
+const fmtK = (t) => (t >= 1000 ? `${(t / 1000).toFixed(1)}k` : String(t)) + " tokens";
+/**
+ * Greedy first fit, largest first. Returns groups whose token sums fit the budget, so the error
+ * can say "call 1: these, call 2: those" instead of "too big".
+ */
+export function suggestSplit(parts, budget) {
+    const bins = [];
+    for (const part of [...parts].sort((a, b) => b.tokens - a.tokens)) {
+        const bin = bins.find((b) => b.total + part.tokens <= budget);
+        if (bin) {
+            bin.items.push(part);
+            bin.total += part.tokens;
+        }
+        else
+            bins.push({ total: part.tokens, items: [part] });
+    }
+    return bins.map((b) => b.items);
+}
+function describe(parts) {
+    const files = parts.filter((p) => p.kind === "file").map((p) => p.name);
+    const bits = [];
+    if (parts.some((p) => p.kind === "own"))
+        bits.push("your state");
+    if (files.length)
+        bits.push(`paths [${files.join(", ")}]`);
+    if (parts.some((p) => p.kind === "output"))
+        bits.push("the command");
+    const total = parts.reduce((n, p) => n + p.tokens, 0);
+    return `${bits.join(" + ")} (${fmtK(total)})`;
+}
+/** The message the agent reads when one call cannot hold the situation. */
+export function overflowMessage(parts, budget) {
+    const total = parts.reduce((n, p) => n + p.tokens, 0);
+    const groups = suggestSplit(parts, budget);
+    const oversize = parts.filter((p) => p.tokens > budget);
+    const lines = [
+        `ask_jev: the state is ${fmtK(total)}, the limit per call is ${fmtK(budget)}.`,
+        `Parts: ${[...parts].sort((a, b) => b.tokens - a.tokens).map((p) => `${p.name} ${fmtK(p.tokens)}`).join(", ")}.`,
+    ];
+    if (oversize.length) {
+        lines.push(`Too large for any single call: ${oversize.map((p) => p.name).join(", ")}. Narrow it (a smaller file, a command with less output) or leave it out.`);
+    }
+    if (groups.length > 1 && !oversize.length) {
+        lines.push(`Split into ${groups.length} calls with the same questions_json: ${groups.map((g, i) => `call ${i + 1}: ${describe(g)}`).join("; ")}.`);
+    }
+    return lines.join(" ");
+}
+/**
+ * Build the state. Own state first, then files, then the command's output. Nothing is truncated:
+ * over the file cap or the token budget, the call is refused with a message that says how to split.
+ */
+export async function assembleState(input, cwd, run) {
+    const own = input.state === undefined || input.state === "" ? {} : parseState(input.state);
+    const base = typeof own === "string" ? { text: own } : Array.isArray(own) ? { items: own } : { ...own };
+    const ownText = JSON.stringify(base);
+    if (ownText.length > MAX_OWN_STATE_CHARS) {
+        throw new AskStateError(`ask_jev: your state is ${fmtK(tokensOf(ownText))}; the limit for your own state is ${fmtK(tokensOf("x".repeat(MAX_OWN_STATE_CHARS)))}. Do not paste file contents or command output; pass paths or command instead and code fetches them.`);
+    }
+    const parts = [];
+    if (Object.keys(base).length)
+        parts.push({ name: "your state", tokens: tokensOf(ownText), kind: "own" });
+    const skipped = [];
+    const files = {};
+    if (input.paths?.length) {
+        const expanded = await expandPatterns(input.paths, cwd, true);
+        const pruned = await pruneFiles(expanded, cwd, MAX_FILES_PER_CALL + 1);
+        skipped.push(...pruned.skipped);
+        if (pruned.files.length > MAX_FILES_PER_CALL) {
+            throw new AskStateError(`ask_jev: paths expanded to more than ${MAX_FILES_PER_CALL} files. This tool judges one situation in one call. For many files use ask_jev_files, one call per file in parallel, or narrow the paths.`);
+        }
+        for (const path of pruned.files) {
+            try {
+                const f = await readFileState(path, cwd);
+                files[path] = f.content;
+                parts.push({ name: path, tokens: tokensOf(f.content), kind: "file" });
+            }
+            catch (err) {
+                skipped.push({ path, reason: err instanceof FileStateError ? err.message : String(err?.message ?? err) });
+            }
+        }
+    }
+    let output = null;
+    if (input.command?.trim()) {
+        output = await run(input.command.trim(), cwd);
+        parts.push({ name: `output of \`${output.command}\``, tokens: tokensOf(output.stdout + output.stderr), kind: "output" });
+    }
+    if (!parts.length)
+        throw new AskStateError("ask_jev: nothing to judge. Pass state, paths, or command.");
+    const total = parts.reduce((n, p) => n + p.tokens, 0);
+    if (total > STATE_TOKEN_BUDGET)
+        throw new AskStateError(overflowMessage(parts, STATE_TOKEN_BUDGET));
+    const state = { ...base };
+    if (Object.keys(files).length)
+        state.files = files;
+    if (output)
+        state.output = output;
+    return {
+        state,
+        summary: {
+            own_fields: Object.keys(base),
+            files: Object.keys(files),
+            output: output ? `${output.command}, exit ${output.exit_code}, ${fmtK(tokensOf(output.stdout + output.stderr))}` : null,
+            skipped,
+            tokens: total,
+        },
+    };
+}

package/dist/files/decide.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The one call every file helper makes. Defaults to the shared client; tools and hooks pass
+ * a reporting decider instead, so the call lands on the event channel.
+ */
+import type { Answer, Questions, State } from "../core/types.ts";
+export type Decide = (state: State, questions: Questions) => Promise<{
+    answers: Record<string, Answer>;
+    usage?: unknown;
+    model?: string;
+}>;

package/dist/files/decide.js

@@ -0,0 +1 @@
+export {};

package/dist/files/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Files become Jev's state, never the agent's context: read one file, expand and prune many,
+ * ask about each in parallel, pick one, or assemble one situation from state, paths, and a command.
+ */
+export * from "./decide.ts";
+export * from "./read-state.ts";
+export * from "./prune.ts";
+export * from "./ask-file-bool.ts";
+export * from "./ask-file-choice.ts";
+export * from "./ask-file-score.ts";
+export * from "./ask-files.ts";
+export * from "./pick-first.ts";
+export * from "./ask.ts";
+export * from "./assemble.ts";

package/dist/files/index.js

@@ -0,0 +1,14 @@
+/**
+ * Files become Jev's state, never the agent's context: read one file, expand and prune many,
+ * ask about each in parallel, pick one, or assemble one situation from state, paths, and a command.
+ */
+export * from "./decide.js";
+export * from "./read-state.js";
+export * from "./prune.js";
+export * from "./ask-file-bool.js";
+export * from "./ask-file-choice.js";
+export * from "./ask-file-score.js";
+export * from "./ask-files.js";
+export * from "./pick-first.js";
+export * from "./ask.js";
+export * from "./assemble.js";

package/dist/files/pick-first.d.ts

@@ -0,0 +1,16 @@
+import type { Decide } from "./decide.ts";
+export interface Candidate {
+    path: string;
+    /** One line the first pass produced, for example the answers gist. Optional. */
+    note?: string;
+}
+export interface FirstPick {
+    path: string | null;
+    confidence: number;
+    probabilities: Record<string, number>;
+}
+/** Keys are the paths themselves. `none` is the exit when nothing fits. */
+export declare function pickQuestion(question: string, candidates: Candidate[]): {
+    pick: import("../core/types.ts").ChoiceQuestion;
+};
+export declare function pickFirstFile(question: string, candidates: Candidate[], decide?: Decide, floor?: number): Promise<FirstPick>;

package/dist/files/pick-first.js

@@ -0,0 +1,24 @@
+/**
+ * Level 9, option C: pick the file to open first.
+ * A second pass over what the first pass found: one Choice over the surviving paths, keyed by path, so the pick is always a real file. Code prunes the list to the cap before the call.
+ */
+import { jev } from "../core/client.js";
+import { choice } from "../core/helpers.js";
+import { LIMITS } from "../core/types.js";
+/** Keys are the paths themselves. `none` is the exit when nothing fits. */
+export function pickQuestion(question, candidates) {
+    const criteria = {};
+    for (const c of candidates.slice(0, LIMITS.MAX_CHOICE_OPTIONS - 1))
+        criteria[c.path] = c.note ?? null;
+    criteria.none = "No file in the list fits";
+    return { pick: choice(question, criteria) };
+}
+export async function pickFirstFile(question, candidates, decide = (s, q) => jev.systemOne(s, q), floor = 0.3) {
+    if (!candidates.length)
+        return { path: null, confidence: 0, probabilities: {} };
+    const state = { question, files: candidates.map((c) => c.path) };
+    const { answers } = await decide(state, pickQuestion(question, candidates));
+    const a = answers.pick;
+    const path = a.choice === "none" || a.confidence < floor ? null : a.choice;
+    return { path, confidence: a.confidence, probabilities: a.probabilities };
+}

package/dist/files/prune.d.ts

@@ -0,0 +1,13 @@
+/** Dependencies, VCS, build output, and every harness or Jev state directory. */
+export declare const SKIP_DIRS: Set<string>;
+export interface Skipped {
+    path: string;
+    reason: string;
+}
+/** Patterns are globs, files, or directories. A directory means its files, or everything below it when recursive. */
+export declare function expandPatterns(patterns: string[], cwd: string, recursive: boolean): Promise<string[]>;
+/** What survives, and why each dropped file dropped. Nothing here calls Jev. */
+export declare function pruneFiles(paths: string[], cwd: string, cap?: number): Promise<{
+    files: string[];
+    skipped: Skipped[];
+}>;

package/dist/files/prune.js

@@ -0,0 +1,87 @@
+/**
+ * Level 9, option B: expand and prune.
+ * Globs and directories become a file list in code. Dependencies, VCS folders, binaries, and files over the budget drop out with a reason. The 255 cap is enforced before any call is made.
+ */
+import { glob, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { LIMITS } from "../core/types.js";
+import { isInside, MAX_FILE_CHARS, toPosix } from "./read-state.js";
+/** Dependencies, VCS, build output, and every harness or Jev state directory. */
+export const SKIP_DIRS = new Set(["node_modules", ".git", ".sessions", "dist", "build", "coverage", ".pi", ".claude", ".codex", ".jev"]);
+const GLOB_CHARS = /[*?[\]{}]/;
+/** Patterns are globs, files, or directories. A directory means its files, or everything below it when recursive. */
+export async function expandPatterns(patterns, cwd, recursive) {
+    const out = new Set();
+    for (const raw of patterns) {
+        const pattern = raw.trim();
+        if (!pattern)
+            continue;
+        if (GLOB_CHARS.test(pattern)) {
+            for await (const p of glob(pattern, { cwd }))
+                out.add(toPosix(String(p)));
+            continue;
+        }
+        const full = isAbsolute(pattern) ? pattern : resolve(cwd, pattern);
+        let info;
+        try {
+            info = await stat(full);
+        }
+        catch {
+            out.add(toPosix(pattern));
+            continue;
+        } // let prune report it
+        if (info.isFile()) {
+            out.add(toPosix(pattern));
+            continue;
+        }
+        for await (const p of glob(recursive ? `${pattern.replace(/\/+$/, "")}/**/*` : `${pattern.replace(/\/+$/, "")}/*`, { cwd }))
+            out.add(toPosix(String(p)));
+    }
+    return [...out].sort();
+}
+/** What survives, and why each dropped file dropped. Nothing here calls Jev. */
+export async function pruneFiles(paths, cwd, cap = LIMITS.MAX_CHOICE_OPTIONS) {
+    const files = [];
+    const skipped = [];
+    for (const raw of paths) {
+        const path = toPosix(raw);
+        const full = isAbsolute(raw) ? raw : resolve(cwd, raw);
+        const rel = relative(cwd, full);
+        if (!isInside(full, cwd)) {
+            skipped.push({ path, reason: "outside the repo" });
+            continue;
+        }
+        if (rel.split(sep).some((part) => SKIP_DIRS.has(part))) {
+            skipped.push({ path, reason: "skipped directory" });
+            continue;
+        }
+        let info;
+        try {
+            info = await stat(full);
+        }
+        catch {
+            skipped.push({ path, reason: "not found" });
+            continue;
+        }
+        if (!info.isFile())
+            continue;
+        if (info.size === 0) {
+            skipped.push({ path, reason: "empty" });
+            continue;
+        }
+        if (info.size > MAX_FILE_CHARS) {
+            skipped.push({ path, reason: `too large, ${info.size} bytes` });
+            continue;
+        }
+        if (/\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|tgz|woff2?|ttf|mp[34]|mov|lock)$/i.test(path)) {
+            skipped.push({ path, reason: "binary or lock file" });
+            continue;
+        }
+        if (files.length >= cap) {
+            skipped.push({ path, reason: `over the ${cap} file cap; narrow the pattern` });
+            continue;
+        }
+        files.push(path);
+    }
+    return { files, skipped };
+}

package/dist/files/read-state.d.ts

@@ -0,0 +1,17 @@
+/** Roughly four characters per token. The budget is shared with the questions, so leave room. */
+export declare const MAX_FILE_CHARS: number;
+/** A type, not an interface, so it is assignable to State's record shape. */
+export type FileState = {
+    path: string;
+    content: string;
+};
+export declare class FileStateError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/** Paths in results use `/` on every OS. */
+export declare const toPosix: (path: string) => string;
+/** Whether `full` is `cwd` or below it. A different Windows drive counts as outside. */
+export declare function isInside(full: string, cwd: string): boolean;
+/** Read one file under `cwd` as state. Errors name the path and the reason, so a tool can report them per file. */
+export declare function readFileState(path: string, cwd: string): Promise<FileState>;

package/dist/files/read-state.js

@@ -0,0 +1,47 @@
+/**
+ * Level 8, shared: the file becomes Jev's state, never the agent's context.
+ * Code reads it, refuses binaries and files over the budget, and hands back `{ path, content }`. Every ask_jev_file tool starts here.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { LIMITS } from "../core/types.js";
+/** Roughly four characters per token. The budget is shared with the questions, so leave room. */
+export const MAX_FILE_CHARS = (LIMITS.TOTAL_TOKEN_BUDGET - 4000) * 4;
+export class FileStateError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.name = "FileStateError";
+        this.path = path;
+    }
+}
+const looksBinary = (buf) => buf.subarray(0, 8192).includes(0);
+/** Paths in results use `/` on every OS. */
+export const toPosix = (path) => path.split(sep).join("/");
+/** Whether `full` is `cwd` or below it. A different Windows drive counts as outside. */
+export function isInside(full, cwd) {
+    const rel = relative(resolve(cwd), full);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/** Read one file under `cwd` as state. Errors name the path and the reason, so a tool can report them per file. */
+export async function readFileState(path, cwd) {
+    const full = isAbsolute(path) ? path : resolve(cwd, path);
+    if (!isInside(full, cwd))
+        throw new FileStateError(`outside the repo: ${toPosix(path)}`, path);
+    let info;
+    try {
+        info = await stat(full);
+    }
+    catch {
+        throw new FileStateError(`not found: ${path}`, path);
+    }
+    if (!info.isFile())
+        throw new FileStateError(`not a file: ${path}`, path);
+    if (info.size > MAX_FILE_CHARS) {
+        throw new FileStateError(`too large for one Jev call: ${path} is ${info.size} bytes, the limit is ${MAX_FILE_CHARS}`, path);
+    }
+    const buf = await readFile(full);
+    if (looksBinary(buf))
+        throw new FileStateError(`binary: ${path}`, path);
+    return { path: toPosix(path), content: buf.toString("utf8") };
+}

package/dist/guards/bash-gate.d.ts

@@ -0,0 +1,65 @@
+import type { ChoiceAnswer, NoulAnswer, Questions, State } from "../core/types.ts";
+export declare const BASH_QUESTIONS: {
+    effect: import("../core/types.ts").ChoiceQuestion;
+    destructive_intent: import("../core/types.ts").NoulQuestion;
+};
+export interface BashGateAnswers {
+    effect: ChoiceAnswer;
+    destructive_intent: NoulAnswer;
+    /** Asked only with a ladder that asks. */
+    outward?: NoulAnswer;
+}
+/** With `ask`, one more question: a command can change nothing here and still publish or deploy. */
+export declare const BASH_LADDER_QUESTIONS: {
+    outward: import("../core/types.ts").NoulQuestion;
+    effect: import("../core/types.ts").ChoiceQuestion;
+    destructive_intent: import("../core/types.ts").NoulQuestion;
+};
+/** The outward Noul at which a laddered command asks. */
+export declare const BASH_OUTWARD = 0.5;
+export interface BashThresholds {
+    /** Confidence the irreversible pick needs before it blocks on its own. */
+    irreversible: number;
+    /** The destructive Noul above which the command blocks whatever the effect pick. */
+    destructive: number;
+}
+export declare const BASH_THRESHOLDS: BashThresholds;
+/**
+ * What a hook does with a call, on the Level 4 ladder: deny it, ask the user, approve it without
+ * the harness's own prompt, or pass it to the harness's usual permissions.
+ */
+export type Verdict = "deny" | "ask" | "allow" | "pass";
+export interface Ladder {
+    /** Ask the user, instead of passing, when Jev is unsure or leans destructive without blocking. */
+    ask?: boolean;
+    /** Approve what Jev is sure only reads, so the harness doesn't prompt for it. */
+    allowReadOnly?: boolean;
+    /** Below this confidence a human decides. */
+    floor?: number;
+    /** Above this confidence a read-only pick is approved. */
+    bar?: number;
+}
+export interface GateDecision {
+    block: boolean;
+    reason: string;
+    /** Set when a ladder was given; `block` is then `verdict === "deny"`. */
+    verdict?: Verdict;
+}
+/** What the agent reads after every block. The block is the answer, not a puzzle to route around. */
+export declare const BLOCK_NOTICE = "This block is final. Do not try to work around it with another command, another tool, a different path, or an encoding that does the same thing. Stop and tell the user what was blocked and why.";
+/** Block or allow. A hook has no third option, so the middle ground allows and says why. */
+export declare function gateBash(a: BashGateAnswers, t?: BashThresholds): GateDecision;
+/**
+ * The bash gate on the Level 4 ladder. Blocks stay blocks. Below them, an irreversible pick, a
+ * destructive lean, or confidence under the floor asks the user; a read-only pick above the bar is
+ * approved. Without `ask` or `allowReadOnly` this is gateBash.
+ */
+export declare function bashVerdict(a: BashGateAnswers, ladder?: Ladder, t?: BashThresholds): GateDecision;
+export type Decide = (state: State, questions: Questions) => Promise<{
+    answers: Record<string, unknown>;
+}>;
+/**
+ * A: one call before the command runs. `decide` defaults to the shared client; the extension passes a reporting one.
+ * With a ladder the decision carries a verdict.
+ */
+export declare function gateBashCommand(command: string, cwd: string, decide?: Decide, ladder?: Ladder): Promise<GateDecision>;

package/dist/guards/bash-gate.js

@@ -0,0 +1,78 @@
+/**
+ * Level 6, option A: bash gate.
+ * In the tool_call hook, before any bash command runs: what does it do to the machine, and does it mean to destroy something? Irreversible or destructive blocks. The agent only sees the reason.
+ */
+import { jev } from "../core/client.js";
+import { choice, noul } from "../core/helpers.js";
+import { CONFIDENCE } from "../policy/index.js";
+export const BASH_QUESTIONS = {
+    effect: choice("What does running `command` in `cwd` do to the machine?", {
+        read_only: "Lists, reads, searches, tests, builds into a scratch directory; nothing durable changes",
+        reversible: "Changes files or state that git or a reinstall can restore: edits, installs, generated output",
+        irreversible: "Deletes or overwrites things with no way back: removing directories, force pushing, dropping data, rewriting history",
+    }),
+    destructive_intent: noul("Does `command` aim to remove or wipe something rather than build or inspect?", {
+        true: "rm -rf, drop, purge, force, reset --hard, truncate, overwriting real data",
+        false: "Reading, listing, testing, installing, generating, or editing in place",
+    }),
+};
+/** With `ask`, one more question: a command can change nothing here and still publish or deploy. */
+export const BASH_LADDER_QUESTIONS = {
+    ...BASH_QUESTIONS,
+    outward: noul("Does `command` reach people or systems outside this machine: publish, deploy, push to production, send, or run code downloaded from the internet?", {
+        true: "npm publish, kubectl apply, terraform apply, a migration against a remote database, curl ... | sh, sending email",
+        false: "Works only on this machine and this repository, or only downloads dependencies through the package manager",
+    }),
+};
+/** The outward Noul at which a laddered command asks. */
+export const BASH_OUTWARD = 0.5;
+export const BASH_THRESHOLDS = { irreversible: 0.6, destructive: 0.7 };
+/** What the agent reads after every block. The block is the answer, not a puzzle to route around. */
+export const BLOCK_NOTICE = "This block is final. Do not try to work around it with another command, another tool, a different path, or an encoding that does the same thing. Stop and tell the user what was blocked and why.";
+/** Block or allow. A hook has no third option, so the middle ground allows and says why. */
+export function gateBash(a, t = BASH_THRESHOLDS) {
+    if (a.effect.choice === "irreversible" && a.effect.confidence >= t.irreversible) {
+        return { block: true, reason: `irreversible (${a.effect.confidence.toFixed(2)}): nothing would restore what this removes or overwrites` };
+    }
+    if (a.destructive_intent.noul >= t.destructive) {
+        return { block: true, reason: `destructive intent (${a.destructive_intent.noul.toFixed(2)}): this command aims to wipe something` };
+    }
+    return { block: false, reason: `${a.effect.choice} (${a.effect.confidence.toFixed(2)}), destructive ${a.destructive_intent.noul.toFixed(2)}` };
+}
+/** Bash read below the destructive line, where a ladder asks rather than passes. */
+const LEANS_DESTRUCTIVE = 0.4;
+/** The most destructive intent a command may show and still be approved as read-only. */
+const READ_ONLY_INTENT = 0.1;
+/**
+ * The bash gate on the Level 4 ladder. Blocks stay blocks. Below them, an irreversible pick, a
+ * destructive lean, or confidence under the floor asks the user; a read-only pick above the bar is
+ * approved. Without `ask` or `allowReadOnly` this is gateBash.
+ */
+export function bashVerdict(a, ladder = {}, t = BASH_THRESHOLDS) {
+    const d = gateBash(a, t);
+    if (d.block)
+        return { ...d, verdict: "deny" };
+    const floor = ladder.floor ?? CONFIDENCE.REVIEW_FLOOR, bar = ladder.bar ?? CONFIDENCE.DESTRUCTIVE_BAR;
+    if (ladder.ask) {
+        if (a.effect.confidence < floor)
+            return { block: false, verdict: "ask", reason: `Jev is unsure what this does (${a.effect.choice} at ${a.effect.confidence.toFixed(2)})` };
+        if (a.effect.choice === "irreversible")
+            return { block: false, verdict: "ask", reason: `may be irreversible (${a.effect.confidence.toFixed(2)})` };
+        if (a.destructive_intent.noul >= LEANS_DESTRUCTIVE)
+            return { block: false, verdict: "ask", reason: `leans destructive (${a.destructive_intent.noul.toFixed(2)})` };
+        if (a.outward && a.outward.noul >= BASH_OUTWARD)
+            return { block: false, verdict: "ask", reason: `reaches outside this machine (${a.outward.noul.toFixed(2)}): it publishes, deploys, sends, or runs downloaded code` };
+    }
+    if (ladder.allowReadOnly && a.effect.choice === "read_only" && a.effect.confidence > bar && a.destructive_intent.noul < READ_ONLY_INTENT && (a.outward?.noul ?? 0) < BASH_OUTWARD) {
+        return { block: false, verdict: "allow", reason: `read only (${a.effect.confidence.toFixed(2)})` };
+    }
+    return { ...d, verdict: "pass" };
+}
+/**
+ * A: one call before the command runs. `decide` defaults to the shared client; the extension passes a reporting one.
+ * With a ladder the decision carries a verdict.
+ */
+export async function gateBashCommand(command, cwd, decide = (s, q) => jev.systemOne(s, q), ladder) {
+    const { answers } = await decide({ command, cwd }, ladder?.ask ? BASH_LADDER_QUESTIONS : BASH_QUESTIONS);
+    return ladder ? bashVerdict(answers, ladder) : gateBash(answers);
+}

package/dist/guards/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Guards: the Level 6 decisions a hook runs before and after a tool call. Each file keeps its questions and thresholds together.
+ */
+export * from "./bash-gate.ts";
+export * from "./write-gate.ts";
+export * from "./result-screen.ts";
+export * from "./mcp-gate.ts";

package/dist/guards/index.js

@@ -0,0 +1,7 @@
+/**
+ * Guards: the Level 6 decisions a hook runs before and after a tool call. Each file keeps its questions and thresholds together.
+ */
+export * from "./bash-gate.js";
+export * from "./write-gate.js";
+export * from "./result-screen.js";
+export * from "./mcp-gate.js";