jev-agent-tools 0.1.4 → 0.2.0

package/dist/jev/client.js

@@ -0,0 +1,434 @@
+import { createHash } from "node:crypto";
+import { setTimeout as timerSleep } from "node:timers/promises";
+import { HTTP_ERROR_MAX_CHARS, REQUEST_ATTEMPTS, RETRY_BASE_MS, RETRY_MAX_MS, TIMEOUT_MS, } from "../constants.js";
+import { prepareBatches, splitGroups } from "../core/batches.js";
+import { truncate } from "../core/truncate.js";
+import { isRecord } from "../result.js";
+import { createPool } from "./pool.js";
+export function readConfig(env) {
+    return env.JEV_TOOLS_URL && env.JEV_TOOLS_API_KEY
+        ? {
+            url: env.JEV_TOOLS_URL,
+            apiKey: env.JEV_TOOLS_API_KEY,
+            model: env.JEV_TOOLS_MODEL || "openjev",
+        }
+        : undefined;
+}
+function httpError(body, text, apiKey) {
+    const error = isRecord(body) ? (body.error ?? body.message) : undefined;
+    const detail = typeof error === "string"
+        ? error
+        : isRecord(error) && typeof error.message === "string"
+            ? error.message
+            : body === undefined
+                ? text
+                : "No error message provided.";
+    const redacted = detail.replaceAll(apiKey, "[redacted]");
+    return redacted.length > HTTP_ERROR_MAX_CHARS
+        ? `${truncate(redacted, HTTP_ERROR_MAX_CHARS)}…`
+        : redacted;
+}
+function isJson(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)) ||
+        (Array.isArray(value)
+            ? value.every(isJson)
+            : isRecord(value) && Object.values(value).every(isJson)));
+}
+function probabilities(value) {
+    return (isRecord(value) &&
+        Object.keys(value).length > 0 &&
+        Object.values(value).every((p) => typeof p === "number" && Number.isFinite(p) && p >= 0 && p <= 1));
+}
+function normalize(value, question) {
+    const invalid = {
+        type: "unjudged",
+        reason: "Invalid or missing Jev answer.",
+    };
+    if (!isRecord(value))
+        return invalid;
+    if (question.type === "bool")
+        return typeof value.noul === "number" && value.noul >= 0 && value.noul <= 1
+            ? { type: "bool", p: value.noul }
+            : invalid;
+    if (typeof value.confidence !== "number" ||
+        !Number.isFinite(value.confidence) ||
+        !probabilities(value.probabilities))
+        return invalid;
+    if (question.type === "choice")
+        return typeof value.choice === "string" &&
+            Object.hasOwn(question.criteria, value.choice) &&
+            Object.hasOwn(value.probabilities, value.choice) &&
+            Object.keys(value.probabilities).every((key) => Object.hasOwn(question.criteria, key))
+            ? {
+                type: "choice",
+                choice: value.choice,
+                confidence: value.confidence,
+                probabilities: value.probabilities,
+            }
+            : invalid;
+    return typeof value.score === "number" &&
+        Number.isFinite(value.score) &&
+        value.score >= 0 &&
+        value.score <= question.criteria.length - 1 &&
+        isJson(value.legend)
+        ? {
+            type: "score",
+            score: value.score,
+            confidence: value.confidence,
+            legend: value.legend,
+            probabilities: value.probabilities,
+        }
+        : invalid;
+}
+function metadata(body) {
+    if (!isRecord(body))
+        return {};
+    const usage = body.usage;
+    return {
+        ...(typeof body.model === "string" ? { model: body.model } : {}),
+        ...(isRecord(usage) &&
+            typeof usage.input_tokens === "number" &&
+            Number.isFinite(usage.input_tokens) &&
+            usage.input_tokens >= 0 &&
+            typeof usage.cost === "number" &&
+            Number.isFinite(usage.cost) &&
+            usage.cost >= 0
+            ? { usage: { inputTokens: usage.input_tokens, costUsd: usage.cost } }
+            : {}),
+    };
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (isRecord(value))
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+            .join(",")}}`;
+    return JSON.stringify(value);
+}
+function hash(value) {
+    return createHash("sha256").update(canonical(value)).digest("hex");
+}
+function wireQuestions(questions) {
+    return Object.fromEntries(Object.entries(questions).map(([id, q]) => [
+        id,
+        {
+            ...q,
+            type: q.type === "bool" ? "noul" : q.type,
+            ...(q.type === "bool"
+                ? {
+                    criteria: {
+                        true: q.criteria?.true ?? "Yes",
+                        false: q.criteria?.false ?? "No",
+                    },
+                }
+                : {}),
+        },
+    ]));
+}
+export function createJevClient(config, injected) {
+    const clock = {
+        now: injected?.now ?? (() => performance.now()),
+        sleep: injected?.sleep ??
+            ((ms, signal) => timerSleep(ms, undefined, { signal })),
+    };
+    const processPoolKey = Symbol.for("jev-tools.request-pool");
+    const processPools = globalThis;
+    if (!injected)
+        processPools[processPoolKey] ??= createPool(clock);
+    const pool = injected?.pool ??
+        (injected ? createPool(clock) : processPools[processPoolKey]);
+    const request = injected?.fetch ?? fetch;
+    const timeoutMs = injected?.timeoutMs ?? TIMEOUT_MS;
+    const cache = new Map();
+    const witnessCache = new Map();
+    let generation = 0;
+    return {
+        clearCache() {
+            cache.clear();
+            witnessCache.clear();
+            generation++;
+        },
+        async judge(state, questions, options = {}) {
+            const planned = prepareBatches(state, questions, options);
+            if (!planned.ok)
+                return planned;
+            const answers = {};
+            const meta = {
+                calls: 0,
+                questions: 0,
+                cacheHits: 0,
+                cacheRequests: Object.keys(questions).length,
+                batches: [],
+            };
+            const epoch = generation;
+            const stateKey = hash(state);
+            const keys = new Map(Object.entries(questions).map(([id, q]) => [
+                id,
+                `${stateKey}:${hash(JSON.parse(JSON.stringify(q)))}:${config.model}`,
+            ]));
+            const witnesses = options.witnesses ?? [];
+            const witnessSet = new Set(witnesses);
+            const witnessKey = (group) => JSON.stringify([
+                group.map((id) => keys.get(id)),
+                witnesses.map((id) => keys.get(id)),
+            ]);
+            let stopped;
+            let stateChecked = false;
+            let failure;
+            const addMetadata = (body) => {
+                const next = metadata(body);
+                if (next.model)
+                    meta.model = next.model;
+                if (next.usage) {
+                    meta.usage ??= { inputTokens: 0, costUsd: 0 };
+                    meta.usage.inputTokens += next.usage.inputTokens;
+                    meta.usage.costUsd += next.usage.costUsd;
+                    options.onUsage?.(next.usage);
+                }
+            };
+            const missing = (ids, reason) => {
+                const batchAnswers = Object.fromEntries(ids.map((id) => [id, { type: "unjudged", reason }]));
+                for (const [id, answer] of Object.entries(batchAnswers))
+                    if (!witnessSet.has(id) || !answers[id])
+                        answers[id] = answer;
+                meta.batches?.push({ questionIds: [...ids], answers: batchAnswers });
+            };
+            const send = async (groups, diagnostic = false) => {
+                const ids = [...groups.flat(), ...(diagnostic ? [] : witnesses)];
+                if (stopped) {
+                    missing(ids, stopped);
+                    return;
+                }
+                const selected = Object.fromEntries(ids.map((id) => [id, questions[id]]));
+                const payload = JSON.stringify({
+                    model: config.model,
+                    state,
+                    questions: wireQuestions(selected),
+                });
+                for (let attempt = 0; attempt < REQUEST_ATTEMPTS; attempt++) {
+                    let release;
+                    let settle;
+                    const timeoutCancellation = new AbortController();
+                    let retryMs = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** attempt);
+                    try {
+                        release = await pool.acquire(options.signal);
+                        if (stopped) {
+                            missing(ids, stopped);
+                            return;
+                        }
+                        // The reservation is held from here on; `finally` releases it on
+                        // every exit path (stopped, refused, failed, aborted, answered).
+                        settle = await options.awaitAdmission?.(options.signal);
+                        if (stopped) {
+                            missing(ids, stopped);
+                            return;
+                        }
+                        const admission = options.beforeRequest?.(ids.length);
+                        if (admission && !admission.ok) {
+                            // A diagnostic denied admission supplies no judgment batch and
+                            // must not replace the token refusal with a budget reason.
+                            if (diagnostic)
+                                return;
+                            stopped = admission.error;
+                            missing(ids, stopped);
+                            return;
+                        }
+                        const timeout = new AbortController();
+                        void clock.sleep(timeoutMs, timeoutCancellation.signal).then(() => timeout.abort(new Error("Jev request timeout")), () => { });
+                        meta.calls = (meta.calls ?? 0) + 1;
+                        meta.questions = (meta.questions ?? 0) + ids.length;
+                        const response = await request(config.url, {
+                            method: "POST",
+                            headers: {
+                                "content-type": "application/json",
+                                Authorization: `Bearer ${config.apiKey}`,
+                            },
+                            body: payload,
+                            signal: options.signal
+                                ? AbortSignal.any([options.signal, timeout.signal])
+                                : timeout.signal,
+                        });
+                        const text = await response.text();
+                        let body;
+                        try {
+                            body = JSON.parse(text);
+                        }
+                        catch {
+                            body = undefined;
+                        }
+                        addMetadata(body);
+                        // Release the USD gate before any subdivision re-enters send().
+                        settle?.();
+                        settle = undefined;
+                        release();
+                        release = undefined;
+                        if (response.status === 400 &&
+                            text.includes("max_tokens_exceeded")) {
+                            if (diagnostic) {
+                                stopped =
+                                    "Jev max_tokens_exceeded: state too large for a single question; remaining questions not judged.";
+                                return;
+                            }
+                            if (ids.length === 1) {
+                                missing(ids, "Jev max_tokens_exceeded: state too large for a single question; question not judged.");
+                                return;
+                            }
+                            if (!stateChecked && groups.length > 1) {
+                                stateChecked = true;
+                                // Assume token cost grows with serialized question size on the
+                                // same state. This is not a tokenizer guarantee: non-monotone
+                                // cases are more conservative than main (unjudged), never
+                                // more optimistic. The probe answer is discarded, not cached.
+                                let probeId = ids[0];
+                                let probeSize = Infinity;
+                                for (const [id, question] of Object.entries(wireQuestions(questions))) {
+                                    const size = JSON.stringify(question).length;
+                                    if (size < probeSize) {
+                                        probeId = id;
+                                        probeSize = size;
+                                    }
+                                }
+                                await send([[probeId]], true);
+                                if (stopped) {
+                                    missing(ids, stopped);
+                                    return;
+                                }
+                            }
+                            const split = splitGroups(groups);
+                            if (split.ok)
+                                await Promise.all(split.halves.map((half) => send(half)));
+                            else
+                                missing(ids, split.error);
+                            return;
+                        }
+                        if (response.ok && isRecord(body)) {
+                            if (diagnostic)
+                                return;
+                            const raw = isRecord(body.answers) ? body.answers : {};
+                            const batchAnswers = Object.fromEntries(ids.map((id) => [
+                                id,
+                                normalize(raw[id], selected[id]),
+                            ]));
+                            meta.batches?.push({ questionIds: ids, answers: batchAnswers });
+                            for (const [id, answer] of Object.entries(batchAnswers)) {
+                                if (!witnessSet.has(id) || !answers[id])
+                                    answers[id] = answer;
+                                if (options.cache !== false &&
+                                    !witnessSet.has(id) &&
+                                    epoch === generation &&
+                                    answer.type !== "unjudged")
+                                    cache.set(keys.get(id), structuredClone(answer));
+                            }
+                            if (witnesses.length > 0 &&
+                                options.cache !== false &&
+                                epoch === generation &&
+                                witnesses.every((id) => batchAnswers[id]?.type !== "unjudged")) {
+                                for (const group of groups) {
+                                    if (group.every((id) => batchAnswers[id]?.type !== "unjudged"))
+                                        witnessCache.set(witnessKey(group), structuredClone(Object.fromEntries(witnesses.map((id) => [
+                                            id,
+                                            batchAnswers[id],
+                                        ]))));
+                                }
+                            }
+                            return;
+                        }
+                        if (diagnostic)
+                            return;
+                        const retryAfter = response.status === 429
+                            ? Number(response.headers.get("retry-after"))
+                            : 0;
+                        if (Number.isFinite(retryAfter) &&
+                            retryAfter * 1_000 > RETRY_MAX_MS) {
+                            const reason = `Jev HTTP 429, retry after ${retryAfter} s`;
+                            failure ??= reason;
+                            missing(ids, reason);
+                            return;
+                        }
+                        const reason = response.ok
+                            ? "Invalid Jev response: expected a JSON object."
+                            : `Jev HTTP ${response.status}: ${httpError(body, text, config.apiKey)}${response.status === 401 || response.status === 403 ? "; check JEV_TOOLS_API_KEY." : ""}`;
+                        if (!(response.status === 408 ||
+                            response.status === 429 ||
+                            response.status >= 500) ||
+                            attempt === REQUEST_ATTEMPTS - 1) {
+                            failure ??= reason;
+                            if (response.status === 401 || response.status === 403)
+                                stopped = reason;
+                            missing(ids, reason);
+                            return;
+                        }
+                        if (Number.isFinite(retryAfter) && retryAfter >= 0)
+                            retryMs = Math.max(retryMs, retryAfter * 1_000);
+                    }
+                    catch (error) {
+                        // A failed diagnostic is not evidence of a token limit. Continue
+                        // ordinary subdivision without delivering its answer or error.
+                        if (diagnostic)
+                            return;
+                        const reason = `Jev request failed: ${String(error).replaceAll(config.apiKey, "[redacted]")}`;
+                        if (options.signal?.aborted || attempt === REQUEST_ATTEMPTS - 1) {
+                            failure ??= reason;
+                            missing(ids, reason);
+                            return;
+                        }
+                    }
+                    finally {
+                        settle?.();
+                        release?.();
+                        timeoutCancellation.abort();
+                    }
+                    try {
+                        await clock.sleep(retryMs, options.signal);
+                    }
+                    catch (error) {
+                        const reason = `Jev request failed: ${String(error).replaceAll(config.apiKey, "[redacted]")}`;
+                        failure ??= reason;
+                        missing(ids, reason);
+                        return;
+                    }
+                }
+            };
+            const pending = planned.batches
+                .map((batch) => batch.filter((group) => {
+                if (options.cache === false ||
+                    !group.every((id) => cache.has(keys.get(id))) ||
+                    (witnesses.length > 0 && !witnessCache.has(witnessKey(group))))
+                    return true;
+                for (const id of group) {
+                    answers[id] = structuredClone(cache.get(keys.get(id)));
+                    meta.cacheHits = (meta.cacheHits ?? 0) + 1;
+                }
+                const observedWitnesses = structuredClone(witnessCache.get(witnessKey(group)) ?? {});
+                for (const [id, answer] of Object.entries(observedWitnesses)) {
+                    if (!answers[id]) {
+                        answers[id] = answer;
+                        meta.cacheHits = (meta.cacheHits ?? 0) + 1;
+                    }
+                }
+                const cachedIds = [...group, ...witnesses];
+                meta.batches?.push({
+                    questionIds: cachedIds,
+                    answers: Object.fromEntries(cachedIds.map((id) => [
+                        id,
+                        witnessSet.has(id)
+                            ? observedWitnesses[id]
+                            : structuredClone(cache.get(keys.get(id))),
+                    ])),
+                });
+                return false;
+            }))
+                .filter((batch) => batch.length);
+            await Promise.all(pending.map((batch) => send(batch)));
+            if (failure &&
+                !Object.values(answers).some((answer) => answer.type !== "unjudged"))
+                return { ok: false, error: failure, ...meta };
+            return { ok: true, answers, ...meta };
+        },
+    };
+}

package/dist/jev/pool.js

@@ -0,0 +1,54 @@
+import { CONCURRENCY, RATE_PER_SECOND } from "../constants.js";
+/** A fresh pool owns its sliding window; share it between clients in one process. */
+export function createPool(clock) {
+    let active = 0;
+    const starts = [];
+    let gate = Promise.resolve();
+    let released = Promise.withResolvers();
+    return {
+        async acquire(signal) {
+            const previous = gate;
+            const turn = Promise.withResolvers();
+            gate = turn.promise;
+            await previous;
+            try {
+                for (;;) {
+                    signal?.throwIfAborted();
+                    const now = clock.now();
+                    while (starts.length && now - (starts[0] ?? now) >= 1_000)
+                        starts.shift();
+                    if (active >= CONCURRENCY) {
+                        const cancelled = Promise.withResolvers();
+                        const abort = () => cancelled.reject(signal?.reason);
+                        signal?.addEventListener("abort", abort, { once: true });
+                        try {
+                            await Promise.race([released.promise, cancelled.promise]);
+                        }
+                        finally {
+                            signal?.removeEventListener("abort", abort);
+                        }
+                    }
+                    else if (starts.length >= RATE_PER_SECOND) {
+                        await clock.sleep(Math.max(1, 1_000 - (now - (starts[0] ?? now))), signal);
+                    }
+                    else
+                        break;
+                }
+                active++;
+                starts.push(clock.now());
+                let done = false;
+                return () => {
+                    if (done)
+                        return;
+                    done = true;
+                    active--;
+                    released.resolve();
+                    released = Promise.withResolvers();
+                };
+            }
+            finally {
+                turn.resolve();
+            }
+        },
+    };
+}

package/dist/jev/types.js

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

package/dist/mcp/main.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { canonicalPath } from "../adapters/canonical-path.js";
+import { MCP_SHUTDOWN_FLUSH_TIMEOUT_MS } from "../constants.js";
+import { McpServer, PARSE_ERROR } from "./protocol.js";
+import { createMcpTools } from "./tools.js";
+const usage = `jev-agent-tools-mcp - MCP stdio server for the six jev_* tools
+
+Usage: jev-agent-tools-mcp [--root <repository-directory>]
+
+The repository directory is --root, else JEV_TOOLS_ROOT, else the current
+directory. Configuration uses the same JEV_TOOLS_* environment variables as
+the pi and omp extension. Protocol messages use stdout; diagnostics stderr.`;
+function packageVersion() {
+    try {
+        // src/mcp/main.ts and dist/mcp/main.js both sit two levels below the root.
+        const text = readFileSync(new URL("../../package.json", import.meta.url), "utf8");
+        const parsed = JSON.parse(text);
+        return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function parseArgs(argv) {
+    let root;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--help" || arg === "-h")
+            return { exit: usage };
+        if (arg === "--version")
+            return { exit: packageVersion() };
+        if (arg === "--root") {
+            root = argv[++index];
+            if (!root)
+                throw new Error("--root requires a directory");
+        }
+        else if (arg?.startsWith("--root="))
+            root = arg.slice("--root=".length);
+        else
+            throw new Error(`Unknown argument: ${arg}\n\n${usage}`);
+    }
+    return { root };
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.exit !== undefined) {
+        process.stdout.write(`${parsed.exit}\n`);
+        return;
+    }
+    const root = await canonicalPath(resolve(parsed.root ?? process.env.JEV_TOOLS_ROOT ?? process.cwd()));
+    if (!statSync(root, { throwIfNoEntry: false })?.isDirectory())
+        throw new Error(`Repository directory not found: ${root}`);
+    const { tools, instructions, configured, warning } = await createMcpTools({
+        root,
+    });
+    const server = new McpServer({ name: "jev-agent-tools", version: packageVersion(), instructions }, tools);
+    if (warning)
+        process.stderr.write(`jev-agent-tools MCP: ${warning}\n`);
+    process.stderr.write(`jev-agent-tools MCP server ready (root ${root}; ${configured ? "endpoint configured" : "no endpoint: set JEV_TOOLS_URL and JEV_TOOLS_API_KEY, or save them with /jev-setup in pi or omp"})\n`);
+    let closing = false;
+    const send = (response) => {
+        if (closing ||
+            response === undefined ||
+            (Array.isArray(response) && !response.length))
+            return;
+        // Newline-delimited JSON; JSON.stringify never emits raw newlines.
+        process.stdout.write(`${JSON.stringify(response)}\n`);
+    };
+    const pending = new Set();
+    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    const shutdown = async (code) => {
+        if (closing)
+            return;
+        closing = true;
+        lines.close();
+        process.stdin.destroy();
+        server.abortAll();
+        // Tool promises include bounded process-tree escalation. Do not exit when
+        // only the direct shell has closed: descendants may still need SIGKILL.
+        await Promise.allSettled(pending);
+        if (process.stdout.destroyed)
+            process.exit(code);
+        // A client may leave its stdout pipe open without draining it. Cleanup
+        // is already complete; never let that client's backpressure hold us alive.
+        setTimeout(() => process.exit(code), MCP_SHUTDOWN_FLUSH_TIMEOUT_MS);
+        process.stdout.end(() => process.exit(code));
+    };
+    process.on("SIGTERM", () => void shutdown(143));
+    process.on("SIGINT", () => void shutdown(130));
+    process.stdout.on("error", () => void shutdown(1));
+    lines.on("line", (line) => {
+        if (closing || !line.trim())
+            return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            send(server.error(null, PARSE_ERROR, "Parse error: invalid JSON."));
+            return;
+        }
+        const work = (async () => {
+            if (Array.isArray(message)) {
+                // JSON-RPC batches (protocol 2025-03-26) answer as one array.
+                const responses = await Promise.all(message.map((item) => server.handle(item)));
+                send(responses.filter((item) => item !== undefined));
+            }
+            else
+                send(await server.handle(message));
+        })().catch((error) => {
+            process.stderr.write(`jev-agent-tools MCP: ${String(error)}\n`);
+        });
+        pending.add(work);
+        void work.finally(() => pending.delete(work));
+    });
+    lines.on("close", () => void shutdown(0));
+}
+main().catch((error) => {
+    process.stderr.write(`jev-agent-tools MCP: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});