@bobobowis/jev-kit 0.0.0-stage → 0.2.0

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;
+}

package/dist/tools/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A Jev tool, defined once for every harness: pi registers it, the MCP server lists it, the CLI
+ * runs it. The name, description, parameters, and payload are the same wherever it appears.
+ */
+import type { Decider } from "../events/index.ts";
+import type { CompactAction } from "../compact/should-compact.ts";
+import type { Evaluation, TurnInput } from "../compact/evaluate.ts";
+/** The subset of JSON Schema the tools use. */
+export interface JsonSchema {
+    type?: "object" | "string" | "boolean" | "array" | "number" | "integer";
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    additionalProperties?: boolean | JsonSchema;
+}
+export interface CompactionSource {
+    /** The session as the harness sees it, or null when it has no history to offer. */
+    input(): TurnInput | null | Promise<TurnInput | null>;
+    /** How the agent can act on a tier under this harness. */
+    action: CompactAction;
+    /** Told about every evaluation, so a harness can keep injecting the latest tier. */
+    onEvaluation?(evaluation: Evaluation): void;
+}
+export interface ToolContext {
+    /** The directory the agent works in. Paths resolve here and may not leave it. */
+    cwd: string;
+    harness: string;
+    decide: Decider;
+    report(kind: string, payload: Record<string, unknown>): void;
+    /** Level 7 only. */
+    compaction?: CompactionSource;
+}
+export interface ToolResult {
+    /** What the agent reads. */
+    text: string;
+    /** The structured result, when the call succeeded. */
+    payload?: unknown;
+    isError?: boolean;
+}
+export interface JevTool {
+    name: string;
+    label: string;
+    description: string;
+    parameters: JsonSchema;
+    execute(params: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+}
+export declare const ok: (payload: unknown) => ToolResult;
+export declare const fail: (text: string) => ToolResult;
+export declare const object: (properties: Record<string, JsonSchema>, required?: string[]) => JsonSchema;
+export declare const str: (description?: string) => JsonSchema;

package/dist/tools/types.js

@@ -0,0 +1,4 @@
+export const ok = (payload) => ({ text: JSON.stringify(payload, null, 2), payload });
+export const fail = (text) => ({ text, isError: true });
+export const object = (properties, required = Object.keys(properties)) => ({ type: "object", properties, required });
+export const str = (description) => (description ? { type: "string", description } : { type: "string" });

package/package.json

@@ -1,6 +1,99 @@
 {
   "name": "@bobobowis/jev-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Jev, TypeSafe AI's System One decision model, as a typed client, guards, file reads, agent tools, hooks, an MCP server, and a CLI. Zero runtime dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "author": "bobobowis",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bobobowis/ten-levels-of-jev.git",
+    "directory": "packages/jev-kit"
+  },
+  "homepage": "https://github.com/bobobowis/ten-levels-of-jev/tree/main/packages/jev-kit#readme",
+  "bugs": "https://github.com/bobobowis/ten-levels-of-jev/issues",
+  "keywords": [
+    "jev",
+    "typesafe",
+    "llm",
+    "classifier",
+    "decision",
+    "guardrails",
+    "claude-code",
+    "codex",
+    "mcp",
+    "hooks",
+    "agents"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./policy": {
+      "types": "./dist/policy/index.d.ts",
+      "default": "./dist/policy/index.js"
+    },
+    "./events": {
+      "types": "./dist/events/index.d.ts",
+      "default": "./dist/events/index.js"
+    },
+    "./files": {
+      "types": "./dist/files/index.d.ts",
+      "default": "./dist/files/index.js"
+    },
+    "./ledger": {
+      "types": "./dist/ledger.d.ts",
+      "default": "./dist/ledger.js"
+    },
+    "./guards": {
+      "types": "./dist/guards/index.d.ts",
+      "default": "./dist/guards/index.js"
+    },
+    "./compact": {
+      "types": "./dist/compact/index.d.ts",
+      "default": "./dist/compact/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "default": "./dist/tools/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "default": "./dist/hooks/index.js"
+    },
+    "./setup": {
+      "types": "./dist/setup/index.d.ts",
+      "default": "./dist/setup/index.js"
+    },
+    "./capabilities": {
+      "types": "./dist/capabilities.d.ts",
+      "default": "./dist/capabilities.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "jev": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "pretest": "tsc -b tsconfig.build.json",
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }