jev-agent-tools 0.1.4 → 0.3.0

package/src/mcp/tools.ts

@@ -0,0 +1,179 @@
+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 { 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 { McpInvalidParams, 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 }[];
+    details: { result: ResultReportV1 };
+  }>;
+}
+
+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; 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 {
+        ...configured(),
+        warning: error instanceof Error ? error.message : String(error),
+      };
+    }
+    return configured();
+  } 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, 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),
+    },
+    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,
+      },
+      outputSchema: mcpStructuredResultSchema as McpTool["inputSchema"],
+      async call(args, signal) {
+        const invalid = validationError(tool.parameters, args);
+        if (invalid) throw new McpInvalidParams(invalid);
+        const result = await tool.execute(
+          `mcp-${++id}`,
+          args as never,
+          signal,
+          undefined,
+          { cwd: options.root },
+        );
+        return {
+          content: result.content,
+          structuredContent: { result: result.details.result },
+          ...(resultIsError(result.details.result) ? { isError: true } : {}),
+        };
+      },
+    };
+  });
+  const instructions = renderAgentInstructions("mcp", host.names);
+  return {
+    tools,
+    instructions,
+    configured: client !== undefined,
+    ...(loaded.warning ? { warning: loaded.warning } : {}),
+  };
+}

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");
+}