@bobobowis/jev-kit 0.0.0-stage → 0.2.0

package/dist/core/helpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Question builders, matching the @typesafe-ai/sdk helper style.
+ * Answer types are inferred from the question you build.
+ */
+import type { ChoiceAnswer, ChoiceCriteria, ChoiceQuestion, Instructions, NoulAnswer, NoulCriteria, NoulQuestion, Question, ScoreAnswer, ScoreCriteria, ScoreQuestion } from "./types.ts";
+export declare function noul(instructions: Instructions, criteria?: NoulCriteria): NoulQuestion;
+export declare function choice(instructions: Instructions, criteria: ChoiceCriteria): ChoiceQuestion;
+export declare function score(instructions: Instructions, criteria: ScoreCriteria): ScoreQuestion;
+/** Infer the answer type a question returns. */
+export type AnswerOf<Q> = Q extends NoulQuestion ? NoulAnswer : Q extends ChoiceQuestion ? ChoiceAnswer : Q extends ScoreQuestion ? ScoreAnswer : never;
+/** Typed question map -> typed answer map. */
+export type AnswersOf<Q extends Record<string, Question>> = {
+    [K in keyof Q]: AnswerOf<Q[K]>;
+};

package/dist/core/helpers.js

@@ -0,0 +1,9 @@
+export function noul(instructions, criteria) {
+    return criteria ? { type: "noul", instructions, criteria } : { type: "noul", instructions };
+}
+export function choice(instructions, criteria) {
+    return { type: "choice", instructions, criteria };
+}
+export function score(instructions, criteria) {
+    return { type: "score", instructions, criteria };
+}

package/dist/core/mock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MockJev — a deterministic, offline stand-in for the real System One endpoint.
+ *
+ * It exists so every level in this codebase runs (and its tests pass) without an
+ * API key. It mimics the exact wire contract: typed answers, probability
+ * distributions that sum to 1, legends on scores, and confidence derived from
+ * how peaked the distribution is.
+ *
+ * How it decides: token overlap between the flattened state and each option /
+ * level / criteria description, run through a softmax. It is a stand-in for
+ * *shape*, not for intelligence — with a real key, the same code paths hit
+ * https://api.typesafe.ai/v1/systemone and nothing else changes.
+ */
+import type { State, SystemOneRequest, SystemOneResponse } from "./types.ts";
+/** Flatten any state shape into text the overlap engine can read. */
+export declare function flattenState(state: State): string;
+export declare class MockJev {
+    readonly model = "jev-1.13.0-mock";
+    systemOne(req: SystemOneRequest): SystemOneResponse;
+}

package/dist/core/mock.js

@@ -0,0 +1,132 @@
+const STOPWORDS = new Set([
+    "the", "a", "an", "and", "or", "but", "if", "then", "than", "of", "to", "in", "on", "at", "for",
+    "with", "without", "is", "are", "was", "were", "be", "been", "being", "do", "does", "did", "done",
+    "this", "that", "these", "those", "it", "its", "as", "by", "from", "into", "about", "against",
+    "between", "through", "during", "before", "after", "above", "below", "up", "down", "out", "off",
+    "over", "under", "again", "further", "once", "here", "there", "when", "where", "why", "how",
+    "all", "any", "both", "each", "few", "more", "most", "other", "some", "such", "no", "nor", "not",
+    "only", "own", "same", "so", "too", "very", "s", "t", "can", "will", "just", "don", "should",
+    "now", "d", "ll", "m", "o", "re", "ve", "y", "i", "you", "we", "they", "he", "she", "what",
+    "which", "who", "whom", "am", "has", "have", "had", "having", "message", "text", "given",
+]);
+function stem(t) {
+    if (t.length > 4 && t.endsWith("ing"))
+        return t.slice(0, -3);
+    if (t.length > 4 && t.endsWith("ed"))
+        return t.slice(0, -2);
+    if (t.length > 3 && t.endsWith("es"))
+        return t.slice(0, -2);
+    if (t.length > 3 && t.endsWith("s") && !t.endsWith("ss"))
+        return t.slice(0, -1);
+    return t;
+}
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[`_*#>/\[\]{}()"',.;:!?\\-]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t))
+        .map(stem));
+}
+/** Flatten any state shape into text the overlap engine can read. */
+export function flattenState(state) {
+    if (typeof state === "string")
+        return state;
+    return JSON.stringify(state, null, 2);
+}
+function instructionsText(q) {
+    if (typeof q.instructions === "string")
+        return q.instructions;
+    return JSON.stringify(q.instructions);
+}
+function softmax(values, temperature = 0.6) {
+    if (values.every((v) => v === 0)) {
+        return values.map(() => 1 / values.length);
+    }
+    const max = Math.max(...values);
+    const exps = values.map((v) => Math.exp((v - max) / temperature));
+    const sum = exps.reduce((a, b) => a + b, 0);
+    return exps.map((e) => e / sum);
+}
+/** Affinity: how many meaningful tokens the state shares with a description, weighted by rarity-free overlap. */
+function affinity(stateTokens, description) {
+    const descTokens = tokenize(description);
+    let shared = 0;
+    for (const t of descTokens)
+        if (stateTokens.has(t))
+            shared++;
+    return shared;
+}
+function round(n, places = 4) {
+    const f = 10 ** places;
+    return Math.round(n * f) / f;
+}
+function noulAnswer(q, stateTokens) {
+    const yesText = instructionsText(q) + " " + (q.criteria?.true ?? "");
+    const noText = q.criteria?.false ?? "";
+    const yes = affinity(stateTokens, yesText);
+    const no = affinity(stateTokens, noText);
+    // Smoothed signal in [-1, 1]; logistic to [0, 1]. No signal -> 0.5.
+    const k = 2.5;
+    const signal = (yes - no) / (yes + no + k);
+    const p = 1 / (1 + Math.exp(-4 * signal));
+    return { type: "noul", noul: round(p) };
+}
+function choiceAnswer(q, stateTokens) {
+    const entries = Object.entries(q.criteria);
+    const affinities = entries.map(([option, desc]) => {
+        const keyText = option.replace(/_/g, " ");
+        return affinity(stateTokens, keyText) * 1.5 + affinity(stateTokens, desc ?? "") * 1.0;
+    });
+    const probs = softmax(affinities);
+    const probabilities = {};
+    entries.forEach(([option], i) => (probabilities[option] = round(probs[i])));
+    let best = 0;
+    entries.forEach((_, i) => {
+        if (probs[i] > probs[best])
+            best = i;
+    });
+    return {
+        type: "choice",
+        choice: entries[best][0],
+        probabilities,
+        confidence: round(probs[best]),
+    };
+}
+function scoreAnswer(q, stateTokens) {
+    const affinities = q.criteria.map((level) => affinity(stateTokens, level) + 1e-9);
+    const probs = softmax(affinities);
+    const legend = {};
+    q.criteria.forEach((level, i) => (legend[String(i)] = level));
+    const probabilities = {};
+    q.criteria.forEach((_, i) => (probabilities[String(i)] = round(probs[i])));
+    const scoreValue = probs.reduce((acc, p, i) => acc + p * i, 0);
+    const confidence = Math.max(...probs);
+    return {
+        type: "score",
+        score: round(scoreValue, 2),
+        legend,
+        probabilities,
+        confidence: round(confidence),
+    };
+}
+export class MockJev {
+    model = "jev-1.13.0-mock";
+    systemOne(req) {
+        const stateTokens = tokenize(flattenState(req.state));
+        const answers = {};
+        for (const [id, q] of Object.entries(req.questions)) {
+            if (q.type === "noul")
+                answers[id] = noulAnswer(q, stateTokens);
+            else if (q.type === "choice")
+                answers[id] = choiceAnswer(q, stateTokens);
+            else
+                answers[id] = scoreAnswer(q, stateTokens);
+        }
+        const usage = {
+            input_tokens: Math.ceil(flattenState(req.state).length / 4) + 20 * Object.keys(req.questions).length,
+            output_tokens: 20 * Object.keys(req.questions).length,
+        };
+        return { model: this.model, answers, usage };
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * TypeSafe System One API types — the exact wire contract for Jev.
+ *
+ * One endpoint: POST https://api.typesafe.ai/v1/systemone
+ * You send a `state` and a map of typed `questions`; you get back one typed
+ * `answer` per question, keyed by the IDs you chose.
+ */
+/** The content being evaluated. A plain string, or structured data. */
+export type State = string | Record<string, unknown> | unknown[];
+/**
+ * What to ask about the state. Can be a plain string, or a structured object
+ * that puts the question in one field and the data it refers to in others.
+ */
+export type Instructions = string | Record<string, unknown>;
+/** Optional clarification of what yes and no mean. */
+export interface NoulCriteria {
+    true?: string;
+    false?: string;
+}
+/** A map of option -> rubric description. Use null when an option needs no detail. Max 255 options. */
+export type ChoiceCriteria = Record<string, string | null>;
+/** An ordered array of level descriptions, low to high. 2-10 levels. */
+export type ScoreCriteria = string[];
+export interface NoulQuestion {
+    type: "noul";
+    instructions: Instructions;
+    criteria?: NoulCriteria;
+}
+export interface ChoiceQuestion {
+    type: "choice";
+    instructions: Instructions;
+    criteria: ChoiceCriteria;
+}
+export interface ScoreQuestion {
+    type: "score";
+    instructions: Instructions;
+    criteria: ScoreCriteria;
+}
+export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+/** Question IDs are for your code. They are not sent to the model and are not used in inference. */
+export type Questions = Record<string, Question>;
+export interface NoulAnswer {
+    type: "noul";
+    /** The probability the answer is yes. 0 = strong no, 1 = strong yes, 0.5 = uncertain. */
+    noul: number;
+}
+export interface ChoiceAnswer {
+    type: "choice";
+    /** The highest-probability option. Always one you defined. */
+    choice: string;
+    /** Every option mapped to its probability. Floats that sum to 1. */
+    probabilities: Record<string, number>;
+    /** How certain the model is, derived from the shape of the distribution. */
+    confidence: number;
+}
+export interface ScoreAnswer {
+    type: "score";
+    /** Probability-weighted position along the levels. Can land between levels. */
+    score: number;
+    /** Each level number mapped back to its description. */
+    legend: Record<string, string>;
+    /** Each level mapped to its probability. Floats that sum to 1. */
+    probabilities: Record<string, number>;
+    confidence: number;
+}
+export type Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+export interface SystemOneRequest {
+    /** Defaults to "jev-latest". */
+    model?: string;
+    state: State;
+    questions: Questions;
+}
+export interface SystemOneUsage {
+    input_tokens: number;
+    output_tokens: number;
+    /** Provider-reported USD cost. Only finite, nonnegative numbers are trusted. */
+    cost?: unknown;
+    [key: string]: unknown;
+}
+export interface SystemOneResponse {
+    /** The versioned model that answered. Log it. */
+    model: string;
+    answers: Record<string, Answer>;
+    usage: SystemOneUsage;
+    /** Provider extensions are retained, not stripped during validation. */
+    [key: string]: unknown;
+}
+/** Client-side validation limits, mirrored from the published API. */
+export declare const LIMITS: {
+    readonly MAX_CHOICE_OPTIONS: 255;
+    readonly MIN_SCORE_LEVELS: 2;
+    readonly MAX_SCORE_LEVELS: 10;
+    /** Approximate shared token budget for state + all questions. */
+    readonly TOTAL_TOKEN_BUDGET: 64000;
+};
+export declare class QuestionValidationError extends Error {
+    constructor(message: string);
+}
+/** Validate runtime input as well as TypeScript callers, before any transport. */
+export declare function validateRequest(request: unknown): asserts request is SystemOneRequest;
+/** Validate a request's question shapes before it is ever sent. */
+export declare function validateQuestions(questions: unknown): asserts questions is Questions;

package/dist/core/types.js

@@ -0,0 +1,82 @@
+/**
+ * TypeSafe System One API types — the exact wire contract for Jev.
+ *
+ * One endpoint: POST https://api.typesafe.ai/v1/systemone
+ * You send a `state` and a map of typed `questions`; you get back one typed
+ * `answer` per question, keyed by the IDs you chose.
+ */
+/** Client-side validation limits, mirrored from the published API. */
+export const LIMITS = {
+    MAX_CHOICE_OPTIONS: 255,
+    MIN_SCORE_LEVELS: 2,
+    MAX_SCORE_LEVELS: 10,
+    /** Approximate shared token budget for state + all questions. */
+    TOTAL_TOKEN_BUDGET: 64_000,
+};
+export class QuestionValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "QuestionValidationError";
+    }
+}
+const isRecord = (value) => value !== null && typeof value === "object" &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+/** Validate runtime input as well as TypeScript callers, before any transport. */
+export function validateRequest(request) {
+    if (!isRecord(request))
+        throw new QuestionValidationError("Expected a request object.");
+    if (typeof request.state !== "string" && !isRecord(request.state) && !Array.isArray(request.state)) {
+        throw new QuestionValidationError("State must be a string, object, or array.");
+    }
+    if (request.model !== undefined && (typeof request.model !== "string" || !request.model.trim())) {
+        throw new QuestionValidationError("Model must be a nonblank string.");
+    }
+    validateQuestions(request.questions);
+}
+/** Validate a request's question shapes before it is ever sent. */
+export function validateQuestions(questions) {
+    if (!isRecord(questions) || Object.keys(questions).length === 0) {
+        throw new QuestionValidationError("Questions must be a nonempty object.");
+    }
+    for (const [id, q] of Object.entries(questions)) {
+        if (!isRecord(q))
+            throw new QuestionValidationError(`Question "${id}" must be an object.`);
+        if (q.type !== "noul" && q.type !== "choice" && q.type !== "score") {
+            throw new QuestionValidationError(`Question "${id}" has a missing or unknown type.`);
+        }
+        if (typeof q.instructions === "string" ? !q.instructions.trim() : !isRecord(q.instructions)) {
+            throw new QuestionValidationError(`Question "${id}" needs nonblank string or object instructions.`);
+        }
+        if (q.type === "noul" && q.criteria !== undefined) {
+            if (!isRecord(q.criteria) || Object.entries(q.criteria).some(([key, value]) => !["true", "false"].includes(key) || (value !== undefined && typeof value !== "string"))) {
+                throw new QuestionValidationError(`Noul "${id}" criteria must map true/false to descriptions.`);
+            }
+        }
+        if (q.type === "choice") {
+            if (!isRecord(q.criteria)) {
+                throw new QuestionValidationError(`Choice "${id}" criteria must be an object.`);
+            }
+            const options = Object.keys(q.criteria);
+            if (options.length === 0) {
+                throw new QuestionValidationError(`Choice "${id}" has no options.`);
+            }
+            if (options.length > LIMITS.MAX_CHOICE_OPTIONS) {
+                throw new QuestionValidationError(`Choice "${id}" has ${options.length} options; the maximum is ${LIMITS.MAX_CHOICE_OPTIONS}.`);
+            }
+            if (Object.values(q.criteria).some((value) => value !== null && typeof value !== "string")) {
+                throw new QuestionValidationError(`Choice "${id}" descriptions must be strings or null.`);
+            }
+        }
+        if (q.type === "score") {
+            if (!Array.isArray(q.criteria)) {
+                throw new QuestionValidationError(`Score "${id}" criteria must be an array.`);
+            }
+            if (q.criteria.length < LIMITS.MIN_SCORE_LEVELS || q.criteria.length > LIMITS.MAX_SCORE_LEVELS) {
+                throw new QuestionValidationError(`Score "${id}" must have between ${LIMITS.MIN_SCORE_LEVELS} and ${LIMITS.MAX_SCORE_LEVELS} levels; got ${q.criteria.length}.`);
+            }
+            if (q.criteria.some((level) => typeof level !== "string" || !level.trim())) {
+                throw new QuestionValidationError(`Score "${id}" levels must be nonblank strings.`);
+            }
+        }
+    }
+}

package/dist/events/index.d.ts

@@ -0,0 +1,44 @@
+import { type JevClient } from "../core/client.ts";
+import { type Answer, type Questions, type State, type SystemOneUsage } from "../core/types.ts";
+export declare const EVENT_PREFIX = "JEV_EVENT ";
+export interface JevEventLine {
+    kind: string;
+    at: number;
+    harness: string;
+    [field: string]: unknown;
+}
+export interface Reporter {
+    readonly harness: string;
+    /** Where events go: the file path, "stderr", or "off". */
+    readonly target: string;
+    report(kind: string, payload?: Record<string, unknown>): void;
+}
+export interface ReporterOptions {
+    /** Names who produced the events: pi, claude, codex, mcp, cli, ... */
+    harness: string;
+    /** Defaults to JEV_EVENT_DIR. */
+    dir?: string;
+    /** No event directory means no events, instead of stderr lines. */
+    quiet?: boolean;
+    /** Also called with every event, for a harness's own record (pi session entries). Errors are ignored. */
+    onEvent?: (kind: string, payload: Record<string, unknown>) => void;
+    stderr?: {
+        write(chunk: string): unknown;
+    };
+}
+export declare function createReporter(opts: ReporterOptions): Reporter;
+export interface Decision {
+    answers: Record<string, Answer>;
+    usage: SystemOneUsage;
+    model: string;
+    ms: number;
+}
+/** One Jev call that validates, calls, times, and reports. `source` names who asked, a hook or a tool. */
+export type Decider = (source: string, state: State, questions: Questions, extra?: Record<string, unknown>) => Promise<Decision>;
+/**
+ * `extra` must not use the keys the report already sets: source, state, questions, answers, usage, model, ms.
+ * The client defaults to the shared, auto-selected one.
+ */
+export declare function createDecider(reporter: Reporter, client?: () => Pick<JevClient, "systemOne">): Decider;
+/** Parse one `JEV_EVENT ` stderr line, or null when the line is something else. */
+export declare function parseEventLine(line: string): JevEventLine | null;

package/dist/events/index.js

@@ -0,0 +1,77 @@
+/**
+ * The event channel every tool, hook, and CLI run reports on.
+ *
+ * With JEV_EVENT_DIR set, each process appends JSON lines to its own file, `<dir>/<harness>-<pid>.jsonl`,
+ * so no two processes share a file and large events never tear. Without it, events go to stderr as
+ * `JEV_EVENT {json}` lines, unless the reporter is quiet (the general CLI keeps stderr readable).
+ * A failed write falls back to stderr and never fails the caller.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { sharedJev } from "../core/client.js";
+import { validateQuestions } from "../core/types.js";
+export const EVENT_PREFIX = "JEV_EVENT ";
+export function createReporter(opts) {
+    const stderr = opts.stderr ?? process.stderr;
+    const dir = opts.dir ?? process.env.JEV_EVENT_DIR?.trim() ?? "";
+    let file = dir ? join(dir, `${opts.harness}-${process.pid}.jsonl`) : "";
+    let ready = false;
+    const toStderr = (line) => {
+        try {
+            stderr.write(EVENT_PREFIX + line + "\n");
+        }
+        catch { /* nowhere left to report */ }
+    };
+    return {
+        harness: opts.harness,
+        get target() { return file || (opts.quiet ? "off" : "stderr"); },
+        report(kind, payload = {}) {
+            const line = JSON.stringify({ kind, at: Date.now(), harness: opts.harness, ...payload });
+            try {
+                opts.onEvent?.(kind, payload);
+            }
+            catch { /* optional record */ }
+            if (file) {
+                try {
+                    if (!ready) {
+                        mkdirSync(dir, { recursive: true });
+                        ready = true;
+                    }
+                    appendFileSync(file, line + "\n");
+                    return;
+                }
+                catch (err) {
+                    file = "";
+                    toStderr(JSON.stringify({ kind: "error", at: Date.now(), harness: opts.harness, hook: "events", message: `cannot write ${dir}: ${err.message}; reporting on stderr` }));
+                }
+            }
+            if (!opts.quiet)
+                toStderr(line);
+        },
+    };
+}
+/**
+ * `extra` must not use the keys the report already sets: source, state, questions, answers, usage, model, ms.
+ * The client defaults to the shared, auto-selected one.
+ */
+export function createDecider(reporter, client = sharedJev) {
+    return async (source, state, questions, extra = {}) => {
+        validateQuestions(questions);
+        const started = performance.now();
+        const result = await client().systemOne(state, questions);
+        const out = { answers: result.answers, usage: result.usage, model: result.model, ms: Math.round(performance.now() - started) };
+        reporter.report("jev", { source, state, questions, answers: out.answers, usage: out.usage, model: out.model, ms: out.ms, ...extra });
+        return out;
+    };
+}
+/** Parse one `JEV_EVENT ` stderr line, or null when the line is something else. */
+export function parseEventLine(line) {
+    if (!line.startsWith(EVENT_PREFIX))
+        return null;
+    try {
+        return JSON.parse(line.slice(EVENT_PREFIX.length));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/files/ask-file-bool.d.ts

@@ -0,0 +1,12 @@
+import type { Decide } from "./decide.ts";
+export interface FileBool {
+    path: string;
+    answer: boolean;
+    noul: number;
+    usage?: unknown;
+}
+/** A: the question is written against `content`; the tool description says so. */
+export declare function askFileBool(path: string, question: string, cwd: string, criteria?: {
+    yes?: string;
+    no?: string;
+}, decide?: Decide): Promise<FileBool>;

package/dist/files/ask-file-bool.js

@@ -0,0 +1,15 @@
+/**
+ * Level 8, option A: ask_jev_file_bool.
+ * One file, one yes or no question, flat parameters. The agent asks "does src/auth/session.ts validate tokens?" and gets a Noul back without the file ever entering its context.
+ */
+import { jev } from "../core/client.js";
+import { noul } from "../core/helpers.js";
+import { readFileState } from "./read-state.js";
+/** A: the question is written against `content`; the tool description says so. */
+export async function askFileBool(path, question, cwd, criteria = {}, decide = (s, q) => jev.systemOne(s, q)) {
+    const state = await readFileState(path, cwd);
+    const questions = { answer: noul(question, criteria.yes || criteria.no ? { true: criteria.yes, false: criteria.no } : undefined) };
+    const { answers, usage } = await decide(state, questions);
+    const a = answers.answer;
+    return { path, answer: a.noul > 0.5, noul: a.noul, usage };
+}

package/dist/files/ask-file-choice.d.ts

@@ -0,0 +1,10 @@
+import type { Decide } from "./decide.ts";
+export interface FileChoice {
+    path: string;
+    choice: string;
+    confidence: number;
+    probabilities: Record<string, number>;
+    usage?: unknown;
+}
+/** B: options are name to description. An `other` entry is added when the agent leaves none, so the model has an exit. */
+export declare function askFileChoice(path: string, question: string, options: Record<string, string>, cwd: string, decide?: Decide): Promise<FileChoice>;

package/dist/files/ask-file-choice.js

@@ -0,0 +1,17 @@
+/**
+ * Level 8, option B: ask_jev_file_choice.
+ * One file, one pick from options the agent names. "Which layer is this file?" comes back as one of the agent's own keys, with the whole distribution.
+ */
+import { jev } from "../core/client.js";
+import { choice } from "../core/helpers.js";
+import { readFileState } from "./read-state.js";
+/** B: options are name to description. An `other` entry is added when the agent leaves none, so the model has an exit. */
+export async function askFileChoice(path, question, options, cwd, decide = (s, q) => jev.systemOne(s, q)) {
+    const state = await readFileState(path, cwd);
+    const criteria = { ...options };
+    if (!("other" in criteria) && !("none" in criteria) && !("none_of_the_above" in criteria))
+        criteria.other = "None of the above";
+    const { answers, usage } = await decide(state, { answer: choice(question, criteria) });
+    const a = answers.answer;
+    return { path, choice: a.choice, confidence: a.confidence, probabilities: a.probabilities, usage };
+}

package/dist/files/ask-file-score.d.ts

@@ -0,0 +1,12 @@
+import type { Decide } from "./decide.ts";
+export interface FileScore {
+    path: string;
+    score: number;
+    top: number;
+    nearest: string;
+    confidence: number;
+    legend: Record<string, string>;
+    usage?: unknown;
+}
+/** C: levels are situations, not degrees. The nearest level's text comes back so the agent can quote it. */
+export declare function askFileScore(path: string, question: string, levels: string[], cwd: string, decide?: Decide): Promise<FileScore>;

package/dist/files/ask-file-score.js

@@ -0,0 +1,15 @@
+/**
+ * Level 8, option C: ask_jev_file_score.
+ * One file, one scale the agent writes, low to high. "How risky is a refactor of this file?" comes back as a position on the agent's own levels.
+ */
+import { jev } from "../core/client.js";
+import { score } from "../core/helpers.js";
+import { readFileState } from "./read-state.js";
+/** C: levels are situations, not degrees. The nearest level's text comes back so the agent can quote it. */
+export async function askFileScore(path, question, levels, cwd, decide = (s, q) => jev.systemOne(s, q)) {
+    const state = await readFileState(path, cwd);
+    const { answers, usage } = await decide(state, { answer: score(question, levels) });
+    const a = answers.answer;
+    const top = levels.length - 1;
+    return { path, score: a.score, top, nearest: a.legend[String(Math.round(a.score))] ?? "", confidence: a.confidence, legend: a.legend, usage };
+}

package/dist/files/ask-files.d.ts

@@ -0,0 +1,23 @@
+import { type Answer, type Questions } from "../core/types.ts";
+import type { Decide } from "./decide.ts";
+import { type Skipped } from "./prune.ts";
+export interface FileAnswers {
+    path: string;
+    answers: Record<string, Answer>;
+    usage?: unknown;
+}
+export interface AskFilesResult {
+    results: FileAnswers[];
+    skipped: Skipped[];
+    calls: number;
+}
+/** The agent writes Jev's question shape as JSON. Malformed blocks fail here, with the reason, before any file is read. */
+export declare function parseQuestions(questionsJson: string): Questions;
+/** Run `fn` over `items` with at most `limit` in flight. Results keep the input order. */
+export declare function parallel<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
+export declare function askFiles(patterns: string[], questionsJson: string, cwd: string, opts?: {
+    recursive?: boolean;
+    concurrency?: number;
+    decide?: Decide;
+    onResult?: (r: FileAnswers) => void;
+}): Promise<AskFilesResult>;

package/dist/files/ask-files.js

@@ -0,0 +1,56 @@
+/**
+ * Level 9, option A: ask_jev_files.
+ * The same questions, raw Jev question JSON, over many files. One call per file, every question in each, all in parallel with a cap. Answers come back per path. No file enters the agent's context.
+ */
+import { jev } from "../core/client.js";
+import { validateQuestions } from "../core/types.js";
+import { FileStateError, readFileState } from "./read-state.js";
+import { expandPatterns, pruneFiles } from "./prune.js";
+/** The agent writes Jev's question shape as JSON. Malformed blocks fail here, with the reason, before any file is read. */
+export function parseQuestions(questionsJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(questionsJson);
+    }
+    catch (err) {
+        throw new Error(`questions_json is not valid JSON: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("questions_json must be an object keyed by question id");
+    validateQuestions(parsed);
+    return parsed;
+}
+/** Run `fn` over `items` with at most `limit` in flight. Results keep the input order. */
+export async function parallel(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+export async function askFiles(patterns, questionsJson, cwd, opts = {}) {
+    const questions = parseQuestions(questionsJson);
+    const decide = opts.decide ?? ((s, q) => jev.systemOne(s, q));
+    const expanded = await expandPatterns(patterns, cwd, opts.recursive ?? false);
+    const { files, skipped } = await pruneFiles(expanded, cwd);
+    const results = [];
+    await parallel(files, opts.concurrency ?? 16, async (path) => {
+        try {
+            const state = await readFileState(path, cwd);
+            const { answers, usage } = await decide(state, questions);
+            const r = { path, answers, usage };
+            results.push(r);
+            opts.onResult?.(r);
+        }
+        catch (err) {
+            skipped.push({ path, reason: err instanceof FileStateError ? err.message : `call failed: ${err?.message ?? err}` });
+        }
+    });
+    results.sort((a, b) => a.path.localeCompare(b.path));
+    return { results, skipped, calls: results.length };
+}