jev-agent-tools 0.1.3 → 0.2.0

package/src/jev/client.ts

@@ -259,6 +259,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,6 +268,13 @@ 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
@@ -302,6 +310,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 (
@@ -438,6 +449,7 @@ export function createJevClient(
               return;
             }
           } finally {
+            settle?.();
             release?.();
             timeoutCancellation.abort();
           }

package/src/jev/types.ts

@@ -48,6 +48,12 @@ export interface JudgmentOptions {
   witnesses?: readonly string[];
   cache?: boolean;
   beforeRequest?: (questionCount: number) => Result<object>;
+  /**
+   * 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,282 @@
+/**
+ * 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;
+
+export interface McpContent {
+  type: "text";
+  text: string;
+}
+export interface McpCallResult {
+  content: McpContent[];
+  isError?: boolean;
+}
+export interface McpTool {
+  name: string;
+  title?: string;
+  description: string;
+  inputSchema: { 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>();
+
+  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,
+        },
+      );
+    try {
+      switch (method) {
+        case "initialize":
+          return this.result(id, this.initialize(params));
+        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",
+          });
+        case "ping":
+          return this.result(id, {});
+        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",
+          });
+        case "tools/call":
+          return await this.callTool(id, params);
+        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;
+    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>,
+  ): 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;
+      return this.result(id, { ...result });
+    } 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,
+      });
+    } finally {
+      this.inFlight.delete(id);
+    }
+  }
+
+  private result(id: Id, result: Record<string, unknown>): JsonRpcResponse {
+    // resultType is required from 2026-07-28 and ignored by earlier clients.
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { 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 }) },
+    };
+  }
+}

package/src/mcp/tools.ts

@@ -0,0 +1,166 @@
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { spawnExec } from "../adapters/exec.ts";
+import { ConfigController } from "../configuration.ts";
+import { MCP_VALIDATION_MAX_ERRORS } from "../constants.ts";
+import type { GitExec } from "../core/git.ts";
+import { Guide } from "../guide.ts";
+import { mcpHost } from "../host.ts";
+import type { JevClient } from "../jev/types.ts";
+import type { ToolDependencies } from "../runtime.ts";
+import { readSessionLimits, Session } from "../session.ts";
+import { createAskTool } from "../tools/ask.ts";
+import { createAskFilesTool } from "../tools/ask-files.ts";
+import { createCheckDiffTool } from "../tools/check-diff.ts";
+import { createFindFilesTool } from "../tools/find.ts";
+import { createLocateTool } from "../tools/locate.ts";
+import { createSelectTestsTool } from "../tools/select-tests.ts";
+import type { McpTool } from "./protocol.ts";
+
+/** The shape every tool factory already returns for pi/omp. */
+interface HarnessTool {
+  name: string;
+  label: string;
+  description: string;
+  parameters: TSchema;
+  promptGuidelines?: string[];
+  execute(
+    id: string,
+    args: never,
+    signal: AbortSignal | undefined,
+    update: unknown,
+    ctx: { cwd: string },
+  ): Promise<{ content: { type: "text"; text: string }[] }>;
+}
+
+export interface McpToolOptions {
+  /** Repository directory the tools operate in. */
+  root: string;
+  env?: NodeJS.ProcessEnv;
+  /** Test seams; production uses the configured HTTP client and spawn. */
+  client?: JevClient;
+  exec?: GitExec;
+  /** Saved-configuration directory; defaults to the pi/omp setup location. */
+  configDirectory?: string;
+}
+
+function validationError(schema: TSchema, value: unknown): string | undefined {
+  if (Value.Check(schema, value)) return undefined;
+  const problems: string[] = [];
+  for (const error of Value.Errors(schema, value)) {
+    problems.push(`${error.path || "/"}: ${error.message}`);
+    if (problems.length === MCP_VALIDATION_MAX_ERRORS) break;
+  }
+  return `Invalid arguments. ${problems.join("; ")}`;
+}
+
+/**
+ * Effective Jev client for MCP, with the same precedence as pi/omp minus the
+ * interactive layers: environment variables, then the configuration saved by
+ * `/jev-setup` in pi or omp. Storage problems never stop the server; the tools
+ * then explain the missing configuration and `warning` says why.
+ */
+export async function loadMcpClient(
+  env: NodeJS.ProcessEnv,
+  configDirectory?: string,
+): Promise<{ client?: JevClient; warning?: string }> {
+  try {
+    const controller = new ConfigController({
+      env,
+      ...(configDirectory ? { directory: configDirectory } : {}),
+    });
+    try {
+      await controller.initialize({});
+    } catch (error) {
+      // Saved storage unusable: environment configuration (if any) still applies.
+      return {
+        ...(controller.client ? { client: controller.client } : {}),
+        warning: error instanceof Error ? error.message : String(error),
+      };
+    }
+    return controller.client ? { client: controller.client } : {};
+  } catch (error) {
+    return { warning: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * Reuse the six harness tool factories unchanged. One MCP server process is
+ * one session: limits, cache and counters live as long as the connection.
+ */
+export async function createMcpTools(options: McpToolOptions): Promise<{
+  tools: McpTool[];
+  instructions: string;
+  configured: boolean;
+  warning?: string;
+}> {
+  const env = options.env ?? process.env;
+  const host = mcpHost();
+  const loaded = options.client
+    ? { client: options.client }
+    : await loadMcpClient(env, options.configDirectory);
+  const client = loaded.client;
+  const dependencies: ToolDependencies = {
+    client,
+    host,
+    runtime: {
+      session: new Session(readSessionLimits(env)),
+      guide: new Guide(host),
+    },
+    exec: options.exec ?? spawnExec,
+  };
+  const harness = [
+    createAskTool(dependencies),
+    createAskFilesTool(dependencies),
+    createFindFilesTool(dependencies),
+    createLocateTool(dependencies),
+    createCheckDiffTool(dependencies),
+    createSelectTestsTool(dependencies),
+  ] as unknown as HarnessTool[];
+  let id = 0;
+  const tools = harness.map((tool): McpTool => {
+    const runsCommands =
+      tool.name === "jev_ask" &&
+      JSON.stringify(tool.parameters).includes('"command"');
+    return {
+      name: tool.name,
+      title: tool.label,
+      description: tool.description,
+      inputSchema: JSON.parse(
+        JSON.stringify(tool.parameters),
+      ) as McpTool["inputSchema"],
+      annotations: {
+        title: tool.label,
+        // Evidence is read-only unless jev_ask may run a shell command.
+        readOnlyHint: !runsCommands,
+        destructiveHint: runsCommands,
+        idempotentHint: false,
+        // Evidence is sent to the configured judgment endpoint.
+        openWorldHint: true,
+      },
+      async call(args, signal) {
+        const invalid = validationError(tool.parameters, args);
+        if (invalid)
+          return { content: [{ type: "text", text: invalid }], isError: true };
+        const result = await tool.execute(
+          `mcp-${++id}`,
+          args as never,
+          signal,
+          undefined,
+          { cwd: options.root },
+        );
+        return { content: result.content };
+      },
+    };
+  });
+  const guidelines = harness.flatMap((tool) => tool.promptGuidelines ?? []);
+  const instructions = [dependencies.runtime.guide.text, ...guidelines].join(
+    "\n\n",
+  );
+  return {
+    tools,
+    instructions,
+    configured: client !== undefined,
+    ...(loaded.warning ? { warning: loaded.warning } : {}),
+  };
+}