jev-agent-tools 0.1.4 → 0.2.0

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 } : {}),
+  };
+}

package/src/session.ts

@@ -1,4 +1,5 @@
 import type { Envelope } from "./core/output.ts";
+import type { JudgmentOptions } from "./jev/types.ts";
 import type { Result } from "./result.ts";
 
 export interface SessionLimits {
@@ -53,6 +54,10 @@ export class Session {
     cacheHits: 0,
   };
   private readonly limits: SessionLimits;
+  // USD gate: at most one admitted request in flight under a USD limit.
+  private gateHeld = false;
+  private gateEpoch = 0;
+  private gateWaiters = new Set<() => void>();
   constructor(limits: SessionLimits) {
     this.limits = limits;
   }
@@ -75,6 +80,56 @@ export class Session {
     this.counters.questions += questions;
     return { ok: true };
   }
+  /**
+   * Under a USD limit, admit one request at a time so each admission sees the
+   * cost reported by every earlier request; without it, concurrent batches are
+   * all admitted before any cost arrives and overshoot the limit. Only the
+   * final admitted request can then exceed the limit, as documented.
+   *
+   * `awaitAdmission` reserves the gate atomically: the availability check and
+   * `gateHeld = true` run with no await between them, so two callers cannot
+   * both pass. It resolves to a release function that the client calls on
+   * every exit path (response, refusal, failure, abort); release is
+   * idempotent and ignores a gate that `reset()` already replaced.
+   */
+  requestGate(): Pick<JudgmentOptions, "awaitAdmission"> {
+    return {
+      awaitAdmission: async (signal) => {
+        if (this.limits.maxUsd === undefined) return undefined;
+        while (this.gateHeld) {
+          signal?.throwIfAborted();
+          await new Promise<void>((resolve, reject) => {
+            const onAbort = () => {
+              this.gateWaiters.delete(wake);
+              reject(signal?.reason);
+            };
+            const wake = () => {
+              signal?.removeEventListener("abort", onAbort);
+              resolve();
+            };
+            this.gateWaiters.add(wake);
+            signal?.addEventListener("abort", onAbort, { once: true });
+          });
+        }
+        signal?.throwIfAborted();
+        this.gateHeld = true;
+        const epoch = this.gateEpoch;
+        let released = false;
+        return () => {
+          if (released || epoch !== this.gateEpoch) return;
+          released = true;
+          this.gateHeld = false;
+          this.wakeGateWaiters();
+        };
+      },
+    };
+  }
+  // Every waiter rechecks; the first to run reserves, the rest wait again.
+  private wakeGateWaiters(): void {
+    const waiters = [...this.gateWaiters];
+    this.gateWaiters.clear();
+    for (const wake of waiters) wake();
+  }
   recordUsage(usage: { costUsd: number }): void {
     this.counters.costUsd += usage.costUsd;
   }
@@ -93,6 +148,10 @@ export class Session {
     return { ...this.counters };
   }
   reset(): void {
+    // A new session generation: outstanding release functions become no-ops.
+    this.gateEpoch++;
+    this.gateHeld = false;
+    this.wakeGateWaiters();
     this.counters = {
       calls: 0,
       questions: 0,

package/src/setup.ts

@@ -62,11 +62,11 @@ export class Setup {
         )
           return;
         this.offered = true;
-        const choice = await ctx.ui.select(
-          "Jev Tools needs an endpoint and API key",
-          ["Configure now", "Later"],
-        );
-        if (choice === "Configure now") await this.configure(ctx);
+        // Host event deadlines bound work, not the time needed to find credentials.
+        // Return before waiting for input so omp clears the handler's UI abort timer.
+        void this.offer(ctx).catch((error: unknown) => {
+          ctx.ui.notify(this.message(error), "error");
+        });
       } catch (error) {
         if (this.interactive(ctx)) ctx.ui.notify(this.message(error), "error");
       }
@@ -102,6 +102,14 @@ export class Setup {
       : "Jev configuration failed; the previous configuration was kept.";
   }
 
+  private async offer(ctx: SetupContext): Promise<void> {
+    const choice = await ctx.ui.select(
+      "Jev Tools needs an endpoint and API key",
+      ["Configure now", "Later"],
+    );
+    if (choice === "Configure now") await this.configure(ctx);
+  }
+
   private async configure(ctx: SetupContext): Promise<void> {
     if (this.busy) return;
     this.busy = true;

package/src/tools/ask-files.ts

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "@sinclair/typebox";
 import { collectAskFiles } from "../adapters/ask-files.ts";
+import { canonicalPath } from "../adapters/canonical-path.ts";
 import { shareGitInventory } from "../adapters/git-inventory.ts";
 import { hostUsage } from "../adapters/usage.ts";
 import { compileAsks, readAsks, reverseQuestions } from "../core/asks.ts";
@@ -67,6 +68,7 @@ export function createAskFilesTool(dependencies: ToolDependencies) {
       ctx: { cwd: string } & GuideContext,
     ) {
       const client = dependencies.client;
+      const cwd = await canonicalPath(ctx.cwd);
       const started = performance.now();
       const exec = shareGitInventory(execute);
       const totals = {
@@ -99,12 +101,7 @@ export function createAskFilesTool(dependencies: ToolDependencies) {
       if (!client) return finish({ refusal: NOT_CONFIGURED });
       const plan = compileAsks(args.asks, { surface: "files" });
       if (!plan.ok) return finish({ refusal: plan.error });
-      const collected = await collectAskFiles(
-        ctx.cwd,
-        args.paths,
-        signal,
-        exec,
-      );
+      const collected = await collectAskFiles(cwd, args.paths, signal, exec);
       if (!collected.ok) return finish({ refusal: collected.error });
       skipped = collected.skipped;
       if (!collected.files.length && skipped.length)
@@ -115,6 +112,7 @@ export function createAskFilesTool(dependencies: ToolDependencies) {
       let budget: BudgetRefusal | undefined;
       const options = {
         signal,
+        ...runtime.session.requestGate(),
         beforeRequest: (count: number) => {
           if (args.max_calls !== undefined && sent >= args.max_calls) {
             budget = {
@@ -148,7 +146,7 @@ export function createAskFilesTool(dependencies: ToolDependencies) {
           const integrity = checkIntegrity(state, plan.asks, [
             {
               ...file.identity,
-              insertedPath: resolve(ctx.cwd, state.path),
+              insertedPath: resolve(cwd, state.path),
               content: state.content,
               insertedSha256: createHash("sha256")
                 .update(state.content)