jev-agent-tools 0.2.0 → 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 });
@@ -281,6 +290,7 @@ export function createJevClient(
               // must not replace the token refusal with a budget reason.
               if (diagnostic) return;
               stopped = admission.error;
+              stoppedCause = options.admissionCause?.();
               missing(ids, stopped);
               return;
             }
@@ -322,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;
               }
@@ -357,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)) {
@@ -366,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 });
@@ -416,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
@@ -433,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)
@@ -445,7 +466,11 @@ 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 {
@@ -458,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;
           }
         }
@@ -473,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]) {
@@ -495,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,8 @@ 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

package/src/mcp/protocol.ts

@@ -24,6 +24,9 @@ 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;
@@ -31,12 +34,14 @@ export interface McpContent {
 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;
@@ -78,6 +83,7 @@ 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;
@@ -134,41 +140,60 @@ export class McpServer {
           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],
-            capabilities: { tools: { listChanged: false } },
-            _meta: {
-              "io.modelcontextprotocol/serverInfo": {
-                name: this.info.name,
-                version: this.info.version,
+          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",
             },
-            ...(this.info.instructions
-              ? { instructions: this.info.instructions }
-              : {}),
-            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",
-          });
+          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);
+          return await this.callTool(id, params, version);
         default:
           return this.error(
             id,
@@ -194,6 +219,7 @@ export class McpServer {
       (SUPPORTED_VERSIONS as readonly string[]).includes(requested)
         ? requested
         : LATEST_INITIALIZE_VERSION;
+    this.negotiatedVersion = protocolVersion;
     return {
       protocolVersion,
       capabilities: { tools: { listChanged: false } },
@@ -215,6 +241,7 @@ export class McpServer {
   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;
@@ -240,30 +267,45 @@ export class McpServer {
     try {
       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);
     }
   }
 
-  private result(id: Id, result: Record<string, unknown>): JsonRpcResponse {
-    // resultType is required from 2026-07-28 and ignored by earlier clients.
+  private result(
+    id: Id,
+    result: Record<string, unknown>,
+    version: string,
+  ): JsonRpcResponse {
     return {
       jsonrpc: "2.0",
       id,
-      result: { resultType: "complete", ...result },
+      result: {
+        ...(version === "2026-07-28" ? { resultType: "complete" } : {}),
+        ...result,
+      },
     };
   }
 
@@ -280,3 +322,11 @@ export class McpServer {
     };
   }
 }
+
+function supportsStructuredResults(version: string): boolean {
+  return (
+    version === "2025-06-18" ||
+    version === "2025-11-25" ||
+    version === "2026-07-28"
+  );
+}

package/src/mcp/tools.ts

@@ -4,18 +4,21 @@ 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 { type ResultReportV1, resultIsError } from "../core/result-report.ts";
 import { Guide } from "../guide.ts";
 import { mcpHost } from "../host.ts";
 import type { JevClient } from "../jev/types.ts";
+import { mcpStructuredResultSchema } from "../report-schema.ts";
 import type { ToolDependencies } from "../runtime.ts";
 import { readSessionLimits, Session } from "../session.ts";
+import { renderAgentInstructions } from "../texts/instructions.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";
+import { McpInvalidParams, type McpTool } from "./protocol.ts";
 
 /** The shape every tool factory already returns for pi/omp. */
 interface HarnessTool {
@@ -30,7 +33,10 @@ interface HarnessTool {
     signal: AbortSignal | undefined,
     update: unknown,
     ctx: { cwd: string },
-  ): Promise<{ content: { type: "text"; text: string }[] }>;
+  ): Promise<{
+    content: { type: "text"; text: string }[];
+    details: { result: ResultReportV1 };
+  }>;
 }
 
 export interface McpToolOptions {
@@ -63,22 +69,26 @@ function validationError(schema: TSchema, value: unknown): string | undefined {
 export async function loadMcpClient(
   env: NodeJS.ProcessEnv,
   configDirectory?: string,
-): Promise<{ client?: JevClient; warning?: string }> {
+): Promise<{ client?: JevClient; apiKey?: string; warning?: string }> {
   try {
     const controller = new ConfigController({
       env,
       ...(configDirectory ? { directory: configDirectory } : {}),
     });
+    const configured = () =>
+      controller.client
+        ? { client: controller.client, apiKey: controller.values().apiKey }
+        : {};
     try {
       await controller.initialize({});
     } catch (error) {
       // Saved storage unusable: environment configuration (if any) still applies.
       return {
-        ...(controller.client ? { client: controller.client } : {}),
+        ...configured(),
         warning: error instanceof Error ? error.message : String(error),
       };
     }
-    return controller.client ? { client: controller.client } : {};
+    return configured();
   } catch (error) {
     return { warning: error instanceof Error ? error.message : String(error) };
   }
@@ -97,12 +107,14 @@ export async function createMcpTools(options: McpToolOptions): Promise<{
   const env = options.env ?? process.env;
   const host = mcpHost();
   const loaded = options.client
-    ? { client: options.client }
+    ? { client: options.client, apiKey: env.JEV_TOOLS_API_KEY }
     : await loadMcpClient(env, options.configDirectory);
   const client = loaded.client;
   const dependencies: ToolDependencies = {
     client,
+    apiKey: loaded.apiKey,
     host,
+    evidenceOrigin: "server",
     runtime: {
       session: new Session(readSessionLimits(env)),
       guide: new Guide(host),
@@ -138,10 +150,10 @@ export async function createMcpTools(options: McpToolOptions): Promise<{
         // Evidence is sent to the configured judgment endpoint.
         openWorldHint: true,
       },
+      outputSchema: mcpStructuredResultSchema as McpTool["inputSchema"],
       async call(args, signal) {
         const invalid = validationError(tool.parameters, args);
-        if (invalid)
-          return { content: [{ type: "text", text: invalid }], isError: true };
+        if (invalid) throw new McpInvalidParams(invalid);
         const result = await tool.execute(
           `mcp-${++id}`,
           args as never,
@@ -149,14 +161,15 @@ export async function createMcpTools(options: McpToolOptions): Promise<{
           undefined,
           { cwd: options.root },
         );
-        return { content: result.content };
+        return {
+          content: result.content,
+          structuredContent: { result: result.details.result },
+          ...(resultIsError(result.details.result) ? { isError: true } : {}),
+        };
       },
     };
   });
-  const guidelines = harness.flatMap((tool) => tool.promptGuidelines ?? []);
-  const instructions = [dependencies.runtime.guide.text, ...guidelines].join(
-    "\n\n",
-  );
+  const instructions = renderAgentInstructions("mcp", host.names);
   return {
     tools,
     instructions,

package/src/render.ts

@@ -1,4 +1,5 @@
 import type { Envelope, OutputLine } from "./core/output.ts";
+import type { Knowledge, ResultReportV1, Scope } from "./core/result-report.ts";
 
 function renderLine(line: OutputLine): string {
   switch (line.type) {
@@ -43,3 +44,111 @@ function renderLine(line: OutputLine): string {
 export function renderEnvelope(envelope: Envelope): string {
   return envelope.lines.map(renderLine).join("\n");
 }
+
+function knowledge<T>(
+  value: Knowledge<T>,
+  format: (value: T) => string = String,
+): string {
+  return value.status === "known"
+    ? format(value.value)
+    : `${value.status} (${value.reason})`;
+}
+function scopeLabel(scope: Scope): string {
+  return scope.kind === "call"
+    ? "call"
+    : scope.kind === "item"
+      ? `items ${scope.itemIds.join(", ")}`
+      : scope.kind === "group"
+        ? `groups ${scope.groupIds.join(", ")}`
+        : `inventory ${scope.inventoryIds.join(", ")}`;
+}
+
+/** Human projection uses the same typed facts as structured transport, never prose inference. */
+export function renderResultReport(
+  report: ResultReportV1,
+  options: { details?: Envelope } = {},
+): string {
+  const { context: c, accounting: a } = report;
+  const counts = a.requestedResults;
+  const mode =
+    counts.fresh + counts.cache
+      ? `${counts.fresh} fresh / ${counts.cache} cache Jev results`
+      : counts.static
+        ? "static selection; no Jev judgment"
+        : report.items.some((item) => item.selection?.selected)
+          ? "conservative fallback selection; no Jev judgment"
+          : "no admissible judgment";
+  const lines = [
+    `${report.execution} — ${mode}${counts.notJudged ? `; ${counts.notJudged} not judged` : ""}`,
+    `context: authority ${knowledge(c.authority, (v) => `${v.path} (${v.origin})`)} · requested root ${knowledge(c.requestedRoot)} · effective root ${knowledge(c.effectiveRoot, (v) => `${v.path} (${v.origin}); common-dir ${knowledge(v.commonDir)}`)} · base ${knowledge(c.requestedBase)} → ${knowledge(c.resolvedBase)}`,
+  ];
+  for (const inv of c.inventories) {
+    lines.push(
+      `inventory ${inv.id} (${inv.kind}): discovered ${knowledge(inv.discovered)} · considered ${knowledge(inv.considered)} · scopeRestricted ${inv.scopeRestricted} · rules ${inv.rules.join("; ")} · restrictions ${inv.restrictions.join("; ") || "none"}`,
+    );
+    for (const criterion of inv.criteria)
+      lines.push(
+        `criterion ${JSON.stringify(criterion.criterion)}: ${criterion.outcome}; matches ${knowledge(criterion.matches)}`,
+      );
+  }
+  if (c.command.execution !== "not_requested")
+    lines.push(
+      `command: ${c.command.execution} · cwd ${knowledge(c.command.cwd)} · exit ${knowledge(c.command.exitCode)} · timedOut ${knowledge(c.command.timedOut)}`,
+    );
+  for (const item of report.items) {
+    if (item.treatment === "judged") {
+      const j = item.judgment;
+      lines.push(
+        `${j.band === "verdict" ? "" : `${j.band}  `}${j.uncalibrated ? "uncalibrated  " : ""}${item.label} = ${String(j.result)} (${j.measure.kind} ${knowledge(j.measure.value)}) [${item.source}]${j.reason ? ` — ${j.reason}` : ""}`,
+      );
+      for (const raw of j.rawValues)
+        lines.push(
+          `  raw ${raw.label} = ${String(raw.value)}; probability ${knowledge(raw.probability)}`,
+        );
+      for (const control of j.controls) {
+        lines.push(
+          `  control ${control.id} (${control.kind}, ${control.source}): ${control.outcome}`,
+        );
+        for (const raw of control.rawValues)
+          lines.push(
+            `    raw ${raw.label} = ${String(raw.value)}; probability ${knowledge(raw.probability)}`,
+          );
+      }
+    } else
+      lines.push(
+        `${item.treatment === "static" ? "static" : "unjudged"}  ${item.label}${item.treatment === "static" ? ` — ${item.staticReason}` : ""}`,
+      );
+    for (const evidence of item.evidence)
+      lines.push(
+        `  evidence ${evidence.target} (${evidence.side}): ${knowledge(evidence.canonicalPath)} · aliases ${evidence.aliases.join(", ") || "none"} · revision ${knowledge(evidence.revision)}`,
+      );
+    if (item.selection)
+      lines.push(
+        `  selection: ${item.selection.selected ? "selected" : "not selected"} — ${item.selection.reason}`,
+      );
+    if (item.diagnosticIds.length)
+      lines.push(`  diagnostics ${item.diagnosticIds.join(", ")}`);
+    if (item.actionIds.length)
+      lines.push(`  actions ${item.actionIds.join(", ")}`);
+  }
+  // Complete diagnostic lists keep legacy text-only clients self-contained.
+  for (const d of report.diagnostics)
+    lines.push(
+      `${d.material ? "material " : ""}${d.effect} ${d.id} — ${d.cause}: ${d.fact} · target ${knowledge(d.target)} · origin ${d.origin} · scope ${scopeLabel(d.scope)} · members ${knowledge(d.memberCount)}${d.omittedMembers.length ? ` · omitted ${d.omittedMembers.join(", ")}` : ""} · actions ${d.actionIds.join(", ") || "none"}`,
+    );
+  for (const action of report.actions)
+    lines.push(
+      `next ${action.id} (${action.code}; ${scopeLabel(action.scope)}; target ${knowledge(action.target)}): ${action.condition} — ${action.instruction}`,
+    );
+  if (options.details) {
+    const detailLines = options.details.lines.filter(
+      (line) => line.type === "command" || line.type === "list",
+    );
+    if (detailLines.length)
+      lines.push("details:", renderEnvelope({ lines: detailLines }));
+  }
+  lines.push(
+    `HTTP attempts ${a.httpAttempts} · questions sent ${a.questionsSent} · requested results total ${knowledge(counts.total)} / fresh ${counts.fresh} / cache ${counts.cache} / not judged ${counts.notJudged} / static ${counts.static} · cache probes ${a.cacheHits}/${a.cacheRequests} · auxiliary controls fresh ${a.auxiliary.controls.fresh} / cache ${a.auxiliary.controls.cache} / not judged ${a.auxiliary.controls.notJudged} / static ${a.auxiliary.controls.static} · passages fresh ${a.auxiliary.passages.fresh} / cache ${a.auxiliary.passages.cache} / not judged ${a.auxiliary.passages.notJudged} · current cost USD ${knowledge(a.costUsd)} · elapsed ${a.elapsedMs} ms`,
+  );
+  return lines.join("\n");
+}