jev-agent-tools 0.1.4 → 0.3.0

package/src/jev/client.ts

@@ -232,10 +232,19 @@ export function createJevClient(
           options.onUsage?.(next.usage);
         }
       };
-      const missing = (ids: readonly string[], reason: string) => {
+      let stoppedCause: Extract<Answer, { type: "unjudged" }>["cause"];
+      const missing = (
+        ids: readonly string[],
+        reason: string,
+        cause: Extract<Answer, { type: "unjudged" }>["cause"] = stoppedCause,
+      ) => {
         const batchAnswers = Object.fromEntries(
-          ids.map((id) => [id, { type: "unjudged" as const, reason }]),
+          ids.map((id) => [
+            id,
+            { type: "unjudged" as const, 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;
         meta.batches?.push({ questionIds: [...ids], answers: batchAnswers });
@@ -259,6 +268,7 @@ export function createJevClient(
         });
         for (let attempt = 0; attempt < REQUEST_ATTEMPTS; attempt++) {
           let release: (() => void) | undefined;
+          let settle: (() => void) | undefined;
           const timeoutCancellation = new AbortController();
           let retryMs = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** attempt);
           try {
@@ -267,12 +277,20 @@ export function createJevClient(
               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;
+              stoppedCause = options.admissionCause?.();
               missing(ids, stopped);
               return;
             }
@@ -302,6 +320,9 @@ export function createJevClient(
               body = undefined;
             }
             addMetadata(body);
+            // Release the USD gate before any subdivision re-enters send().
+            settle?.();
+            settle = undefined;
             release();
             release = undefined;
             if (
@@ -311,12 +332,14 @@ export function createJevClient(
               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.",
+                  "provider_context_refusal",
                 );
                 return;
               }
@@ -346,7 +369,7 @@ export function createJevClient(
               const split = splitGroups(groups);
               if (split.ok)
                 await Promise.all(split.halves.map((half) => send(half)));
-              else missing(ids, split.error);
+              else missing(ids, split.error, "provider_context_refusal");
               return;
             }
             if (response.ok && isRecord(body)) {
@@ -355,7 +378,12 @@ export function createJevClient(
               const batchAnswers = Object.fromEntries(
                 ids.map((id) => [
                   id,
-                  normalize(raw[id], selected[id] as Question),
+                  (() => {
+                    const answer = normalize(raw[id], selected[id] as Question);
+                    return answer.type === "unjudged"
+                      ? { ...answer, cause: "invalid_response" as const }
+                      : { ...answer, source: "fresh" as const };
+                  })(),
                 ]),
               );
               meta.batches?.push({ questionIds: ids, answers: batchAnswers });
@@ -405,7 +433,7 @@ export function createJevClient(
             ) {
               const reason = `Jev HTTP 429, retry after ${retryAfter} s`;
               failure ??= reason;
-              missing(ids, reason);
+              missing(ids, reason, "service_unavailable");
               return;
             }
             const reason = response.ok
@@ -422,7 +450,11 @@ export function createJevClient(
               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)
@@ -434,10 +466,15 @@ export function createJevClient(
             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;
             }
           } finally {
+            settle?.();
             release?.();
             timeoutCancellation.abort();
           }
@@ -446,7 +483,11 @@ export function createJevClient(
           } 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;
           }
         }
@@ -461,13 +502,19 @@ export function createJevClient(
             )
               return true;
             for (const id of group) {
-              answers[id] = structuredClone(
-                cache.get(keys.get(id) as string) as Answer,
-              );
+              answers[id] = {
+                ...structuredClone(cache.get(keys.get(id) as string) as Answer),
+                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" as const },
+              ]),
             );
             for (const [id, answer] of Object.entries(observedWitnesses)) {
               if (!answers[id]) {
@@ -483,9 +530,12 @@ export function createJevClient(
                   id,
                   witnessSet.has(id)
                     ? (observedWitnesses[id] as Answer)
-                    : structuredClone(
-                        cache.get(keys.get(id) as string) as Answer,
-                      ),
+                    : {
+                        ...structuredClone(
+                          cache.get(keys.get(id) as string) as Answer,
+                        ),
+                        source: "cache" as const,
+                      },
                 ]),
               ),
             });

package/src/jev/types.ts

@@ -15,8 +15,19 @@ export type Question =
     }
   | { type: "choice"; instructions: string; criteria: Record<string, string> }
   | { type: "score"; instructions: string; criteria: string[] };
-export type Answer =
-  | { type: "unjudged"; reason: string }
+export type Answer = { source?: "fresh" | "cache" } & (
+  | {
+      type: "unjudged";
+      reason: string;
+      cause?:
+        | "call_budget"
+        | "session_budget"
+        | "provider_context_refusal"
+        | "invalid_response"
+        | "service_unavailable"
+        | "transport_failure"
+        | "cancelled";
+    }
   | { type: "bool"; p: number }
   | {
       type: "choice";
@@ -30,8 +41,10 @@ export type Answer =
       confidence: number;
       legend: Json;
       probabilities: Record<string, number>;
-    };
+    }
+);
 export interface JudgmentMetadata {
+  failureCause?: Extract<Answer, { type: "unjudged" }>["cause"];
   usage?: { inputTokens: number; costUsd: number };
   model?: string;
   calls?: number;
@@ -48,6 +61,14 @@ export interface JudgmentOptions {
   witnesses?: readonly string[];
   cache?: boolean;
   beforeRequest?: (questionCount: number) => Result<object>;
+  /** Structured cause of a denied beforeRequest admission, when established. */
+  admissionCause?: () => "call_budget" | "session_budget";
+  /**
+   * Awaited before each admission check. Resolves to a release function when
+   * it reserved a slot (a session under a USD limit), which the client calls
+   * exactly once on every exit path; rejects if `signal` aborts while waiting.
+   */
+  awaitAdmission?: (signal?: AbortSignal) => Promise<(() => void) | undefined>;
   onUsage?: (usage: { inputTokens: number; costUsd: number }) => void;
 }
 export interface JevClient {

package/src/mcp/main.ts

@@ -0,0 +1,135 @@
+#!/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.ts";
+import { MCP_SHUTDOWN_FLUSH_TIMEOUT_MS } from "../constants.ts";
+import { type JsonRpcResponse, McpServer, PARSE_ERROR } from "./protocol.ts";
+import { createMcpTools } from "./tools.ts";
+
+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(): string {
+  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) as { version?: unknown };
+    return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function parseArgs(argv: readonly string[]): { root?: string; exit?: string } {
+  let root: string | undefined;
+  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(): Promise<void> {
+  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: JsonRpcResponse | JsonRpcResponse[] | undefined) => {
+    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<Promise<void>>();
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  const shutdown = async (code: number) => {
+    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: unknown;
+    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 is JsonRpcResponse => item !== undefined,
+          ),
+        );
+      } else send(await server.handle(message));
+    })().catch((error: unknown) => {
+      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: unknown) => {
+  process.stderr.write(
+    `jev-agent-tools MCP: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exit(1);
+});

package/src/mcp/protocol.ts

@@ -0,0 +1,332 @@
+/**
+ * Minimal MCP (Model Context Protocol) server core: JSON-RPC 2.0 dispatch for
+ * the tools capability only. No I/O here; the stdio transport feeds it parsed
+ * messages and writes back whatever it returns.
+ *
+ * Supports the initialize-based protocol versions and the 2026-07-28
+ * `server/discover` entry point with per-request version metadata.
+ */
+
+export const SUPPORTED_VERSIONS = [
+  "2026-07-28",
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+] as const;
+const LATEST_INITIALIZE_VERSION = "2025-11-25";
+const VERSION_META = "io.modelcontextprotocol/protocolVersion";
+
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+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 {}
+
+export interface McpContent {
+  type: "text";
+  text: string;
+}
+export interface McpCallResult {
+  content: McpContent[];
+  isError?: boolean;
+  structuredContent?: Record<string, unknown>;
+}
+export interface McpTool {
+  name: string;
+  title?: string;
+  description: string;
+  inputSchema: { type: "object"; [key: string]: unknown };
+  outputSchema?: { type: "object"; [key: string]: unknown };
+  annotations?: {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  };
+  call(
+    args: Record<string, unknown>,
+    signal: AbortSignal,
+  ): Promise<McpCallResult>;
+}
+export interface McpServerInfo {
+  name: string;
+  version: string;
+  instructions?: string;
+}
+
+type Id = string | number;
+export type JsonRpcResponse =
+  | { jsonrpc: "2.0"; id: Id | null; result: Record<string, unknown> }
+  | {
+      jsonrpc: "2.0";
+      id: Id | null;
+      error: { code: number; message: string; data?: unknown };
+    };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isId(value: unknown): value is Id {
+  return (
+    typeof value === "string" ||
+    (typeof value === "number" && Number.isFinite(value))
+  );
+}
+
+export class McpServer {
+  private readonly tools: Map<string, McpTool>;
+  private readonly info: McpServerInfo;
+  private readonly inFlight = new Map<Id, AbortController>();
+  private negotiatedVersion: string = LATEST_INITIALIZE_VERSION;
+
+  constructor(info: McpServerInfo, tools: readonly McpTool[]) {
+    this.info = info;
+    this.tools = new Map(tools.map((tool) => [tool.name, tool]));
+  }
+
+  /** Abort every running tool call, e.g. when stdin closes. */
+  abortAll(): void {
+    for (const controller of this.inFlight.values()) controller.abort();
+    this.inFlight.clear();
+  }
+
+  /** Handle one decoded JSON-RPC message; notifications return undefined. */
+  async handle(message: unknown): Promise<JsonRpcResponse | undefined> {
+    if (!isRecord(message) || message.jsonrpc !== "2.0")
+      return this.error(
+        isRecord(message) && isId(message.id) ? message.id : null,
+        INVALID_REQUEST,
+        "Invalid JSON-RPC 2.0 message.",
+      );
+    const { method, id } = message;
+    const params = isRecord(message.params) ? message.params : {};
+    // Responses to server-initiated requests: this server sends none.
+    if (method === undefined && ("result" in message || "error" in message))
+      return undefined;
+    if (typeof method !== "string")
+      return this.error(
+        isId(id) ? id : null,
+        INVALID_REQUEST,
+        "Missing method.",
+      );
+    if (id === undefined) {
+      this.notify(method, params);
+      return undefined;
+    }
+    if (!isId(id))
+      return this.error(
+        null,
+        INVALID_REQUEST,
+        "Request id must be a string or number.",
+      );
+    const meta = isRecord(params._meta) ? params._meta : {};
+    const requested = meta[VERSION_META];
+    if (
+      typeof requested === "string" &&
+      !(SUPPORTED_VERSIONS as readonly string[]).includes(requested)
+    )
+      return this.error(
+        id,
+        UNSUPPORTED_PROTOCOL_VERSION,
+        "Unsupported protocol version.",
+        {
+          supported: [...SUPPORTED_VERSIONS],
+          requested,
+        },
+      );
+    const version =
+      typeof requested === "string"
+        ? requested
+        : method === "server/discover"
+          ? "2026-07-28"
+          : this.negotiatedVersion;
+    try {
+      switch (method) {
+        case "initialize": {
+          const initialized = this.initialize(params);
+          return this.result(id, initialized, this.negotiatedVersion);
+        }
+        case "server/discover":
+          return this.result(
+            id,
+            {
+              supportedVersions: [...SUPPORTED_VERSIONS],
+              capabilities: { tools: { listChanged: false } },
+              _meta: {
+                "io.modelcontextprotocol/serverInfo": {
+                  name: this.info.name,
+                  version: this.info.version,
+                },
+              },
+              ...(this.info.instructions
+                ? { instructions: this.info.instructions }
+                : {}),
+              ttlMs: 0,
+              cacheScope: "private",
+            },
+            version,
+          );
+        case "ping":
+          return this.result(id, {}, version);
+        case "tools/list":
+          return this.result(
+            id,
+            {
+              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, version);
+        default:
+          return this.error(
+            id,
+            METHOD_NOT_FOUND,
+            `Method not found: ${method}`,
+          );
+      }
+    } catch (error) {
+      return this.error(
+        id,
+        INTERNAL_ERROR,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
+  private initialize(params: Record<string, unknown>): Record<string, unknown> {
+    const requested = params.protocolVersion;
+    // Echo a supported initialize-era version, else offer our latest one.
+    const protocolVersion =
+      typeof requested === "string" &&
+      requested !== "2026-07-28" &&
+      (SUPPORTED_VERSIONS as readonly string[]).includes(requested)
+        ? requested
+        : LATEST_INITIALIZE_VERSION;
+    this.negotiatedVersion = protocolVersion;
+    return {
+      protocolVersion,
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: this.info.name, version: this.info.version },
+      ...(this.info.instructions
+        ? { instructions: this.info.instructions }
+        : {}),
+    };
+  }
+
+  private notify(method: string, params: Record<string, unknown>): void {
+    if (method === "notifications/cancelled" && isId(params.requestId)) {
+      this.inFlight.get(params.requestId)?.abort();
+      this.inFlight.delete(params.requestId);
+    }
+    // notifications/initialized and unknown notifications need no action.
+  }
+
+  private async callTool(
+    id: Id,
+    params: Record<string, unknown>,
+    version: string,
+  ): Promise<JsonRpcResponse | undefined> {
+    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)}`,
+      );
+    if (params.arguments !== undefined && !isRecord(params.arguments))
+      return this.error(
+        id,
+        INVALID_PARAMS,
+        "Tool arguments must be an object.",
+      );
+    const controller = new AbortController();
+    this.inFlight.set(id, controller);
+    // A cancelled request gets no response on any path: 2025-11-25 says
+    // receivers SHOULD NOT respond, and the 2026-07-28 stdio transport says
+    // servers MUST NOT send further messages for it. The signal stays aborted
+    // after the notification removes the entry, so the check is race-free.
+    const cancelled = () => controller.signal.aborted;
+    try {
+      const result = await tool.call(params.arguments ?? {}, controller.signal);
+      if (cancelled()) return undefined;
+      const { structuredContent, ...content } = result;
+      return this.result(
+        id,
+        {
+          ...content,
+          ...(supportsStructuredResults(version) && structuredContent
+            ? { structuredContent }
+            : {}),
+        },
+        version,
+      );
+    } catch (error) {
+      if (cancelled()) return undefined;
+      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);
+    }
+  }
+
+  private result(
+    id: Id,
+    result: Record<string, unknown>,
+    version: string,
+  ): JsonRpcResponse {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        ...(version === "2026-07-28" ? { resultType: "complete" } : {}),
+        ...result,
+      },
+    };
+  }
+
+  error(
+    id: Id | null,
+    code: number,
+    message: string,
+    data?: unknown,
+  ): JsonRpcResponse {
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: { code, message, ...(data === undefined ? {} : { data }) },
+    };
+  }
+}
+
+function supportsStructuredResults(version: string): boolean {
+  return (
+    version === "2025-06-18" ||
+    version === "2025-11-25" ||
+    version === "2026-07-28"
+  );
+}