jev-agent-tools 0.2.0 → 0.3.0

package/dist/core/result-report.js

@@ -0,0 +1,302 @@
+import { askBand } from "./output.js";
+export const known = (value) => ({
+    status: "known",
+    value,
+});
+export const unknown = (reason) => ({
+    status: "unknown",
+    reason,
+});
+export const notApplicable = (reason) => ({
+    status: "not_applicable",
+    reason,
+});
+export const notCollected = (reason) => ({
+    status: "not_collected",
+    reason,
+});
+export function uncollectedContext(input) {
+    return {
+        authority: input.authority,
+        requestedRoot: input.requestedRoot ?? notApplicable("no override requested"),
+        effectiveRoot: unknown("effective root not established"),
+        requestedBase: input.requestedBase ?? notApplicable("no base requested"),
+        resolvedBase: input.requestedBase
+            ? notCollected("base resolution not performed")
+            : notApplicable("no base requested"),
+        inventories: [],
+        command: input.command ?? {
+            execution: "not_requested",
+            cwd: notApplicable("no command"),
+            exitCode: notApplicable("no command"),
+            timedOut: notApplicable("no command"),
+        },
+    };
+}
+export function contextFromEvidence(evidence, options = {}) {
+    const context = uncollectedContext({
+        authority: evidence?.authorityReason
+            ? unknown(evidence.authorityReason)
+            : evidence?.authority
+                ? known(evidence.authority)
+                : unknown("canonical authority not established"),
+        ...(evidence?.requestedRoot !== undefined
+            ? { requestedRoot: known(evidence.requestedRoot) }
+            : {}),
+        ...(evidence?.requestedBase !== undefined
+            ? { requestedBase: known(evidence.requestedBase) }
+            : {}),
+        ...(options.command ? { command: options.command } : {}),
+    });
+    if (evidence?.effectiveRoot)
+        context.effectiveRoot = known({
+            path: evidence.effectiveRoot.path,
+            origin: evidence.effectiveRoot.origin,
+            commonDir: evidence.effectiveRoot.commonDir === undefined
+                ? unknown("Git common directory not collected")
+                : known(evidence.effectiveRoot.commonDir),
+        });
+    if (evidence?.resolvedBase !== undefined)
+        context.resolvedBase = known(evidence.resolvedBase);
+    else if (evidence?.requestedBase !== undefined)
+        context.resolvedBase = unknown("requested base not resolved");
+    context.inventories = options.inventories ?? [];
+    return context;
+}
+export function buildResultReport(input) {
+    const counts = { fresh: 0, cache: 0, notJudged: 0, static: 0 };
+    for (const item of input.items) {
+        if (item.treatment === "judged")
+            counts[item.source]++;
+        else if (item.treatment === "static")
+            counts.static++;
+        else
+            counts.notJudged++;
+    }
+    const admissible = counts.fresh + counts.cache + counts.static;
+    const usefulFallback = input.items.some((item) => item.treatment === "not_judged" && item.selection?.selected);
+    const missing = input.missingWork ||
+        counts.notJudged > 0 ||
+        input.diagnostics.some((d) => d.cause === "criteria_no_match" || d.effect === "blocking");
+    const report = {
+        schemaVersion: 1,
+        tool: input.tool,
+        execution: !admissible && !usefulFallback
+            ? input.refused
+                ? "refused"
+                : "not_judged"
+            : missing
+                ? "partial"
+                : "complete",
+        context: input.context,
+        items: input.items,
+        diagnostics: input.diagnostics,
+        actions: input.actions,
+        accounting: {
+            toolInvocations: 1,
+            httpAttempts: input.metrics.calls,
+            questionsSent: input.metrics.questions,
+            cacheHits: input.metrics.cacheHits,
+            cacheRequests: input.metrics.cacheRequests,
+            requestedResults: { total: input.total, ...counts },
+            auxiliary: input.auxiliary,
+            costUsd: input.metrics.costUsd === undefined
+                ? unknown("current request cost not reported")
+                : known(input.metrics.costUsd),
+            elapsedMs: input.metrics.elapsedMs,
+        },
+    };
+    const errors = validateResultReport(report);
+    if (errors.length)
+        throw new Error(`Invalid ResultReportV1: ${errors.join("; ")}`);
+    return report;
+}
+/** Semantic checks complement, rather than replace, the public JSON Schema. */
+export function validateResultReport(report) {
+    const errors = [];
+    const counter = (value, label) => {
+        if (!Number.isSafeInteger(value) || value < 0)
+            errors.push(`invalid counter ${label}`);
+    };
+    const measurement = (value, label, probability = false) => {
+        if (value.status === "known" &&
+            (!Number.isFinite(value.value) ||
+                value.value < 0 ||
+                (probability && value.value > 1)))
+            errors.push(`invalid measure ${label}`);
+    };
+    const accounting = report.accounting;
+    for (const key of [
+        "httpAttempts",
+        "questionsSent",
+        "cacheHits",
+        "cacheRequests",
+    ])
+        counter(accounting[key], key);
+    if (!Number.isFinite(accounting.elapsedMs) || accounting.elapsedMs < 0)
+        errors.push("invalid elapsedMs");
+    measurement(accounting.costUsd, "costUsd");
+    for (const [kind, values] of Object.entries(accounting.auxiliary))
+        for (const [source, value] of Object.entries(values))
+            counter(value, `${kind}.${source}`);
+    for (const inv of report.context.inventories) {
+        for (const [name, value] of [
+            ["discovered", inv.discovered],
+            ["considered", inv.considered],
+        ])
+            if (value.status === "known")
+                counter(value.value, `${inv.id}.${name}`);
+        for (const criterion of inv.criteria)
+            if (criterion.matches.status === "known")
+                counter(criterion.matches.value, `${inv.id}.matches`);
+    }
+    const ids = (values, label) => {
+        const set = new Set(values.map((v) => v.id));
+        if (set.size !== values.length)
+            errors.push(`duplicate ${label} IDs`);
+        return set;
+    };
+    const items = ids(report.items, "item");
+    const diagnostics = ids(report.diagnostics, "diagnostic");
+    const actions = ids(report.actions, "action");
+    const inventories = ids(report.context.inventories, "inventory");
+    const groups = new Set(report.items.map((i) => i.groupId));
+    const refs = (values, set, label) => {
+        for (const id of values)
+            if (!set.has(id))
+                errors.push(`unknown ${label} ID ${id}`);
+    };
+    const scope = (s) => {
+        if (s.kind === "item")
+            refs(s.itemIds, items, "item");
+        else if (s.kind === "group")
+            refs(s.groupIds, groups, "group");
+        else if (s.kind === "inventory")
+            refs(s.inventoryIds, inventories, "inventory");
+    };
+    for (const item of report.items) {
+        refs(item.diagnosticIds, diagnostics, "diagnostic");
+        refs(item.actionIds, actions, "action");
+        if (item.treatment === "judged") {
+            ids(item.judgment.controls, `control in ${item.id}`);
+            measurement(item.judgment.measure.value, `${item.id}.measure`, true);
+            for (const raw of [
+                ...item.judgment.rawValues,
+                ...item.judgment.controls.flatMap((c) => c.rawValues),
+            ])
+                measurement(raw.probability, `${item.id}.${raw.label}`, true);
+            if (typeof item.judgment.result === "number" &&
+                !Number.isFinite(item.judgment.result))
+                errors.push(`invalid result ${item.id}`);
+        }
+    }
+    for (const d of report.diagnostics) {
+        scope(d.scope);
+        refs(d.actionIds, actions, "action");
+    }
+    for (const a of report.actions)
+        scope(a.scope);
+    for (const inv of report.context.inventories)
+        for (const criterion of inv.criteria)
+            refs(criterion.diagnosticIds, diagnostics, "diagnostic");
+    const c = report.accounting.requestedResults;
+    for (const key of ["fresh", "cache", "static", "notJudged"])
+        counter(c[key], `requestedResults.${key}`);
+    if (c.total.status === "known")
+        counter(c.total.value, "requestedResults.total");
+    const actual = { fresh: 0, cache: 0, static: 0, notJudged: 0 };
+    for (const i of report.items) {
+        if (i.treatment === "judged")
+            actual[i.source]++;
+        else if (i.treatment === "static")
+            actual.static++;
+        else
+            actual.notJudged++;
+    }
+    for (const key of ["fresh", "cache", "static", "notJudged"])
+        if (c[key] !== actual[key])
+            errors.push(`requestedResults.${key} does not match items`);
+    if (c.total.status === "known" && c.total.value !== report.items.length)
+        errors.push("known requested total does not match items");
+    const admissible = actual.fresh + actual.cache + actual.static;
+    const usefulFallback = report.items.some((item) => item.treatment === "not_judged" && item.selection?.selected);
+    if ((report.execution === "refused" || report.execution === "not_judged") &&
+        (admissible || usefulFallback))
+        errors.push("non-result execution has admissible items or useful fallback");
+    if ((report.execution === "complete" || report.execution === "partial") &&
+        !admissible &&
+        !usefulFallback)
+        errors.push("result execution has no admissible items or useful fallback");
+    if (report.execution === "complete" &&
+        (actual.notJudged ||
+            report.diagnostics.some((d) => d.effect === "blocking" || d.cause === "criteria_no_match")))
+        errors.push("complete execution omits requested work");
+    if (!admissible && !report.diagnostics.length)
+        errors.push("absent judgment needs an explicit cause");
+    return errors;
+}
+export function resultIsError(report) {
+    if (report.execution === "refused")
+        return true;
+    if (report.items.some((i) => i.treatment !== "not_judged" || i.selection?.selected))
+        return false;
+    return report.diagnostics.some((d) => d.effect === "blocking" &&
+        [
+            "provider_context_refusal",
+            "not_configured",
+            "service_unavailable",
+            "transport_failure",
+            "invalid_response",
+            "internal_error",
+        ].includes(d.cause));
+}
+/** Source must be established by the client, never guessed from footer totals. */
+export function answerItemFromInput(common, input) {
+    if (input.unjudged)
+        return { ...common, treatment: "not_judged", source: "none" };
+    const source = input.source ?? input.answer?.source;
+    if (source !== "fresh" && source !== "cache")
+        throw new Error(`Answer source not established: ${common.id}`);
+    const value = input.value;
+    const answer = input.answer;
+    if (!value && !answer)
+        throw new Error(`Answer value not established: ${common.id}`);
+    const result = input.publicResult ??
+        (answer?.type === "bool"
+            ? answer.p >= 0.5
+            : (value?.head ??
+                (answer?.type === "choice" ? answer.choice : answer?.score)));
+    if (result === undefined)
+        throw new Error(`Answer result not established: ${common.id}`);
+    const p = value?.p ??
+        (answer?.type === "bool"
+            ? answer.p
+            : answer
+                ? Math.max(...Object.values(answer.probabilities))
+                : undefined);
+    return {
+        ...common,
+        treatment: "judged",
+        source,
+        judgment: {
+            band: input.band ??
+                (p === undefined
+                    ? "unsure"
+                    : askBand({
+                        head: typeof result === "boolean" ? String(result) : result,
+                        p,
+                    }, input)),
+            result,
+            measure: {
+                kind: "probability",
+                value: p === undefined
+                    ? unknown("leading probability not collected")
+                    : known(p),
+            },
+            reason: input.reason ?? "",
+            uncalibrated: input.uncalibrated ?? false,
+            rawValues: input.rawValues ?? [],
+            controls: input.reportControls ?? [],
+        },
+    };
+}

package/dist/core/secret-path.js

@@ -0,0 +1,34 @@
+/** Base-name globs of likely secret files, matched case-insensitively. */
+export const SECRET_NAME_GLOBS = [
+    ".env",
+    ".env.*",
+    "*.pem",
+    "id_rsa*",
+    "*.p12",
+    "credentials*",
+    "secrets*",
+];
+/** Value-free templates that stay admitted despite the `.env.*` rule. */
+const templates = [".env.example", ".env.sample", ".env.template"];
+/**
+ * True when a path's base name matches SECRET_NAME_GLOBS (any depth,
+ * case-insensitive) and is not a value-free `.env` template. Such files are
+ * refused before their content is read, on every evidence admission path;
+ * there is no per-call override.
+ */
+export function isSecretPath(path) {
+    const name = (path.split(/[\\/]/).pop() ?? "").toLowerCase();
+    if (templates.includes(name))
+        return false;
+    return (name === ".env" ||
+        name.startsWith(".env.") ||
+        name.endsWith(".pem") ||
+        name.startsWith("id_rsa") ||
+        name.endsWith(".p12") ||
+        name.startsWith("credentials") ||
+        name.startsWith("secrets"));
+}
+/** Refusal text for a secret-named path: names the path, never its content. */
+export function secretRefusal(path) {
+    return `${path}: secret file name (secret_pattern): content not read, not sent to Jev`;
+}

package/dist/core/state.js

@@ -1,6 +1,13 @@
 import { ASK_NOTE_MAX_CHARS, STATE_MAX_CHARS } from "../constants.js";
 import { isRecord } from "../result.js";
-const reservedKeys = ["files", "files_before", "base_sha", "closure"];
+const reservedKeys = [
+    "files",
+    "files_before",
+    "base_sha",
+    "closure",
+    "evidence",
+    "output",
+];
 export function assembleState(note, files) {
     if (note !== undefined && note.length > ASK_NOTE_MAX_CHARS)
         return {

package/dist/core/units.js

@@ -75,7 +75,7 @@ export function buildUnits(files, parser) {
     const units = [];
     const limits = [];
     for (const file of files) {
-        if (isTestFile(file.path))
+        if (isTestFile(file.path) && file.limitation !== "secret_pattern")
             continue;
         if (file.binary) {
             limits.push({ kind: "binary_ignored", file: file.path });

package/dist/jev/client.js

@@ -191,8 +191,14 @@ export function createJevClient(config, injected) {
                     options.onUsage?.(next.usage);
                 }
             };
-            const missing = (ids, reason) => {
-                const batchAnswers = Object.fromEntries(ids.map((id) => [id, { type: "unjudged", reason }]));
+            let stoppedCause;
+            const missing = (ids, reason, cause = stoppedCause) => {
+                const batchAnswers = Object.fromEntries(ids.map((id) => [
+                    id,
+                    { type: "unjudged", reason, ...(cause ? { cause } : {}) },
+                ]));
+                if (cause)
+                    meta.failureCause ??= cause;
                 for (const [id, answer] of Object.entries(batchAnswers))
                     if (!witnessSet.has(id) || !answers[id])
                         answers[id] = answer;
@@ -235,6 +241,7 @@ export function createJevClient(config, injected) {
                             if (diagnostic)
                                 return;
                             stopped = admission.error;
+                            stoppedCause = options.admissionCause?.();
                             missing(ids, stopped);
                             return;
                         }
@@ -272,10 +279,11 @@ export function createJevClient(config, injected) {
                             if (diagnostic) {
                                 stopped =
                                     "Jev max_tokens_exceeded: state too large for a single question; remaining questions not judged.";
+                                stoppedCause = "provider_context_refusal";
                                 return;
                             }
                             if (ids.length === 1) {
-                                missing(ids, "Jev max_tokens_exceeded: state too large for a single question; question not judged.");
+                                missing(ids, "Jev max_tokens_exceeded: state too large for a single question; question not judged.", "provider_context_refusal");
                                 return;
                             }
                             if (!stateChecked && groups.length > 1) {
@@ -303,7 +311,7 @@ export function createJevClient(config, injected) {
                             if (split.ok)
                                 await Promise.all(split.halves.map((half) => send(half)));
                             else
-                                missing(ids, split.error);
+                                missing(ids, split.error, "provider_context_refusal");
                             return;
                         }
                         if (response.ok && isRecord(body)) {
@@ -312,7 +320,12 @@ export function createJevClient(config, injected) {
                             const raw = isRecord(body.answers) ? body.answers : {};
                             const batchAnswers = Object.fromEntries(ids.map((id) => [
                                 id,
-                                normalize(raw[id], selected[id]),
+                                (() => {
+                                    const answer = normalize(raw[id], selected[id]);
+                                    return answer.type === "unjudged"
+                                        ? { ...answer, cause: "invalid_response" }
+                                        : { ...answer, source: "fresh" };
+                                })(),
                             ]));
                             meta.batches?.push({ questionIds: ids, answers: batchAnswers });
                             for (const [id, answer] of Object.entries(batchAnswers)) {
@@ -347,7 +360,7 @@ export function createJevClient(config, injected) {
                             retryAfter * 1_000 > RETRY_MAX_MS) {
                             const reason = `Jev HTTP 429, retry after ${retryAfter} s`;
                             failure ??= reason;
-                            missing(ids, reason);
+                            missing(ids, reason, "service_unavailable");
                             return;
                         }
                         const reason = response.ok
@@ -360,7 +373,7 @@ export function createJevClient(config, injected) {
                             failure ??= reason;
                             if (response.status === 401 || response.status === 403)
                                 stopped = reason;
-                            missing(ids, reason);
+                            missing(ids, reason, response.ok ? "invalid_response" : "service_unavailable");
                             return;
                         }
                         if (Number.isFinite(retryAfter) && retryAfter >= 0)
@@ -374,7 +387,7 @@ export function createJevClient(config, injected) {
                         const reason = `Jev request failed: ${String(error).replaceAll(config.apiKey, "[redacted]")}`;
                         if (options.signal?.aborted || attempt === REQUEST_ATTEMPTS - 1) {
                             failure ??= reason;
-                            missing(ids, reason);
+                            missing(ids, reason, options.signal?.aborted ? "cancelled" : "transport_failure");
                             return;
                         }
                     }
@@ -389,7 +402,7 @@ export function createJevClient(config, injected) {
                     catch (error) {
                         const reason = `Jev request failed: ${String(error).replaceAll(config.apiKey, "[redacted]")}`;
                         failure ??= reason;
-                        missing(ids, reason);
+                        missing(ids, reason, options.signal?.aborted ? "cancelled" : "transport_failure");
                         return;
                     }
                 }
@@ -401,10 +414,16 @@ export function createJevClient(config, injected) {
                     (witnesses.length > 0 && !witnessCache.has(witnessKey(group))))
                     return true;
                 for (const id of group) {
-                    answers[id] = structuredClone(cache.get(keys.get(id)));
+                    answers[id] = {
+                        ...structuredClone(cache.get(keys.get(id))),
+                        source: "cache",
+                    };
                     meta.cacheHits = (meta.cacheHits ?? 0) + 1;
                 }
-                const observedWitnesses = structuredClone(witnessCache.get(witnessKey(group)) ?? {});
+                const observedWitnesses = Object.fromEntries(Object.entries(structuredClone(witnessCache.get(witnessKey(group)) ?? {})).map(([id, answer]) => [
+                    id,
+                    { ...answer, source: "cache" },
+                ]));
                 for (const [id, answer] of Object.entries(observedWitnesses)) {
                     if (!answers[id]) {
                         answers[id] = answer;
@@ -418,7 +437,10 @@ export function createJevClient(config, injected) {
                         id,
                         witnessSet.has(id)
                             ? observedWitnesses[id]
-                            : structuredClone(cache.get(keys.get(id))),
+                            : {
+                                ...structuredClone(cache.get(keys.get(id))),
+                                source: "cache",
+                            },
                     ])),
                 });
                 return false;

package/dist/mcp/protocol.js

@@ -21,6 +21,9 @@ export const METHOD_NOT_FOUND = -32601;
 export const INVALID_PARAMS = -32602;
 export const INTERNAL_ERROR = -32603;
 export const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/** Input-schema failure, distinct from semantic tool refusals and server faults. */
+export class McpInvalidParams extends Error {
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -32,6 +35,7 @@ export class McpServer {
     tools;
     info;
     inFlight = new Map();
+    negotiatedVersion = LATEST_INITIALIZE_VERSION;
     constructor(info, tools) {
         this.info = info;
         this.tools = new Map(tools.map((tool) => [tool.name, tool]));
@@ -67,10 +71,17 @@ export class McpServer {
                 supported: [...SUPPORTED_VERSIONS],
                 requested,
             });
+        const version = typeof requested === "string"
+            ? requested
+            : method === "server/discover"
+                ? "2026-07-28"
+                : this.negotiatedVersion;
         try {
             switch (method) {
-                case "initialize":
-                    return this.result(id, this.initialize(params));
+                case "initialize": {
+                    const initialized = this.initialize(params);
+                    return this.result(id, initialized, this.negotiatedVersion);
+                }
                 case "server/discover":
                     return this.result(id, {
                         supportedVersions: [...SUPPORTED_VERSIONS],
@@ -86,20 +97,23 @@ export class McpServer {
                             : {}),
                         ttlMs: 0,
                         cacheScope: "private",
-                    });
+                    }, version);
                 case "ping":
-                    return this.result(id, {});
+                    return this.result(id, {}, version);
                 case "tools/list":
                     return this.result(id, {
-                        tools: [...this.tools.values()].map(({ call: _call, ...tool }) => tool),
-                        // CacheableResult requires these from 2026-07-28; 0/private is
-                        // conservative (immediately stale, same authorization context)
-                        // and ignored by earlier clients via the open result shape.
-                        ttlMs: 0,
-                        cacheScope: "private",
-                    });
+                        tools: [...this.tools.values()].map(({ call: _call, outputSchema, ...tool }) => ({
+                            ...tool,
+                            ...(supportsStructuredResults(version) && outputSchema
+                                ? { outputSchema }
+                                : {}),
+                        })),
+                        ...(version === "2026-07-28"
+                            ? { ttlMs: 0, cacheScope: "private" }
+                            : {}),
+                    }, version);
                 case "tools/call":
-                    return await this.callTool(id, params);
+                    return await this.callTool(id, params, version);
                 default:
                     return this.error(id, METHOD_NOT_FOUND, `Method not found: ${method}`);
             }
@@ -116,6 +130,7 @@ export class McpServer {
             SUPPORTED_VERSIONS.includes(requested)
             ? requested
             : LATEST_INITIALIZE_VERSION;
+        this.negotiatedVersion = protocolVersion;
         return {
             protocolVersion,
             capabilities: { tools: { listChanged: false } },
@@ -132,7 +147,7 @@ export class McpServer {
         }
         // notifications/initialized and unknown notifications need no action.
     }
-    async callTool(id, params) {
+    async callTool(id, params, version) {
         const tool = typeof params.name === "string" ? this.tools.get(params.name) : undefined;
         if (!tool)
             return this.error(id, INVALID_PARAMS, `Unknown tool: ${String(params.name)}`);
@@ -149,32 +164,35 @@ export class McpServer {
             const result = await tool.call(params.arguments ?? {}, controller.signal);
             if (cancelled())
                 return undefined;
-            return this.result(id, { ...result });
+            const { structuredContent, ...content } = result;
+            return this.result(id, {
+                ...content,
+                ...(supportsStructuredResults(version) && structuredContent
+                    ? { structuredContent }
+                    : {}),
+            }, version);
         }
         catch (error) {
             if (cancelled())
                 return undefined;
-            // Tool execution failures are results the model can read, not protocol errors.
-            return this.result(id, {
-                content: [
-                    {
-                        type: "text",
-                        text: `${tool.name} failed: ${error instanceof Error ? error.message : String(error)}`,
-                    },
-                ],
-                isError: true,
-            });
+            if (error instanceof McpInvalidParams)
+                return this.error(id, INVALID_PARAMS, error.message);
+            // Expected tool refusals already carry a report. An unexpected server
+            // fault has no trustworthy report/accounting; do not fabricate one.
+            return this.error(id, INTERNAL_ERROR, `${tool.name} failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         finally {
             this.inFlight.delete(id);
         }
     }
-    result(id, result) {
-        // resultType is required from 2026-07-28 and ignored by earlier clients.
+    result(id, result, version) {
         return {
             jsonrpc: "2.0",
             id,
-            result: { resultType: "complete", ...result },
+            result: {
+                ...(version === "2026-07-28" ? { resultType: "complete" } : {}),
+                ...result,
+            },
         };
     }
     error(id, code, message, data) {
@@ -185,3 +203,8 @@ export class McpServer {
         };
     }
 }
+function supportsStructuredResults(version) {
+    return (version === "2025-06-18" ||
+        version === "2025-11-25" ||
+        version === "2026-07-28");
+}