@mandujs/mcp 0.36.2 → 0.37.0

package/src/tools/loop-close.ts

@@ -1,175 +1,175 @@
-/**
- * MCP tool — `mandu.loop.close`
- *
- * Thin, safe adapter over `@mandujs/skills/loop-closure`. Given agent
- * output (stdout, stderr, exitCode), runs the built-in loop-closure
- * detectors and returns a structured follow-up prompt:
- *
- *   {
- *     stallReason: string,
- *     nextPrompt: string,
- *     evidence: Array<{ kind, file?, line?, snippet, label? }>
- *   }
- *
- * SAFETY INVARIANTS — enforced by design:
- *   - `closeLoop()` is pure: no I/O, no spawn, no file writes.
- *   - This wrapper adds only input validation + field shaping.
- *   - The `nextPrompt` is ADVISORY text. It is never auto-executed.
- */
-
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { closeLoop, listDetectorIds } from "@mandujs/skills/loop-closure";
-
-interface LoopCloseInput {
-  stdout?: unknown;
-  stderr?: unknown;
-  exitCode?: unknown;
-  detectors?: unknown;
-}
-
-function validateInput(raw: Record<string, unknown>): {
-  ok: true;
-  value: {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-    detectors?: string[];
-  };
-} | { ok: false; error: string; field: string; hint: string } {
-  const stdout = raw.stdout ?? "";
-  if (typeof stdout !== "string") {
-    return {
-      ok: false,
-      error: "'stdout' must be a string",
-      field: "stdout",
-      hint: "Omit or pass '' for no stdout",
-    };
-  }
-
-  const stderr = raw.stderr ?? "";
-  if (typeof stderr !== "string") {
-    return {
-      ok: false,
-      error: "'stderr' must be a string",
-      field: "stderr",
-      hint: "Omit or pass '' for no stderr",
-    };
-  }
-
-  let exitCode = 0;
-  if (raw.exitCode !== undefined) {
-    if (typeof raw.exitCode !== "number" || !Number.isFinite(raw.exitCode)) {
-      return {
-        ok: false,
-        error: "'exitCode' must be a finite number",
-        field: "exitCode",
-        hint: "Pass the child-process exit code, typically 0 (success) or non-zero (failure)",
-      };
-    }
-    exitCode = Math.trunc(raw.exitCode);
-  }
-
-  let detectors: string[] | undefined;
-  if (raw.detectors !== undefined) {
-    if (!Array.isArray(raw.detectors) ||
-        !raw.detectors.every((d) => typeof d === "string")) {
-      return {
-        ok: false,
-        error: "'detectors' must be an array of detector IDs",
-        field: "detectors",
-        hint: `Valid IDs: ${listDetectorIds().join(", ")}`,
-      };
-    }
-    detectors = raw.detectors as string[];
-  }
-
-  return {
-    ok: true,
-    value: { stdout, stderr, exitCode, ...(detectors ? { detectors } : {}) },
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// Handler
-// ─────────────────────────────────────────────────────────────────────────
-
-async function runLoopClose(
-  input: LoopCloseInput,
-): Promise<
-  | {
-      stallReason: string;
-      nextPrompt: string;
-      evidence: Array<{
-        kind: string;
-        file?: string;
-        line?: number;
-        snippet: string;
-        label?: string;
-      }>;
-      detectors_run: string[];
-    }
-  | { error: string; field?: string; hint?: string }
-> {
-  const validated = validateInput(input as Record<string, unknown>);
-  if (!validated.ok) {
-    return {
-      error: validated.error,
-      field: validated.field,
-      hint: validated.hint,
-    };
-  }
-
-  const report = closeLoop(validated.value);
-  return {
-    stallReason: report.stallReason,
-    nextPrompt: report.nextPrompt,
-    evidence: report.evidence,
-    detectors_run: validated.value.detectors ?? listDetectorIds(),
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// Tool definition + handler map
-// ─────────────────────────────────────────────────────────────────────────
-
-export const loopCloseToolDefinitions: Tool[] = [
-  {
-    name: "mandu.loop.close",
-    description:
-      "Analyze agent output (stdout, stderr, exitCode) and return a structured `nextPrompt` that names the primary stall pattern, explains how to address it, and lists supporting evidence. This tool is pure — it never writes files, spawns processes, or auto-executes anything. The returned prompt is advisory text only.",
-    annotations: {
-      readOnlyHint: true,
-    },
-    inputSchema: {
-      type: "object",
-      properties: {
-        stdout: {
-          type: "string",
-          description: "Captured stdout from the most recent command/run.",
-        },
-        stderr: {
-          type: "string",
-          description: "Captured stderr from the most recent command/run.",
-        },
-        exitCode: {
-          type: "number",
-          description: "Child-process exit code. Defaults to 0 when omitted.",
-        },
-        detectors: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Optional detector-ID allow-list. Omit to run the full built-in set.",
-        },
-      },
-      required: [],
-    },
-  },
-];
-
-export function loopCloseTools(_projectRoot: string) {
-  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
-    "mandu.loop.close": async (args) => runLoopClose(args as LoopCloseInput),
-  };
-  return handlers;
-}
+/**
+ * MCP tool — `mandu.loop.close`
+ *
+ * Thin, safe adapter over `@mandujs/skills/loop-closure`. Given agent
+ * output (stdout, stderr, exitCode), runs the built-in loop-closure
+ * detectors and returns a structured follow-up prompt:
+ *
+ *   {
+ *     stallReason: string,
+ *     nextPrompt: string,
+ *     evidence: Array<{ kind, file?, line?, snippet, label? }>
+ *   }
+ *
+ * SAFETY INVARIANTS — enforced by design:
+ *   - `closeLoop()` is pure: no I/O, no spawn, no file writes.
+ *   - This wrapper adds only input validation + field shaping.
+ *   - The `nextPrompt` is ADVISORY text. It is never auto-executed.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { closeLoop, listDetectorIds } from "@mandujs/skills/loop-closure";
+
+interface LoopCloseInput {
+  stdout?: unknown;
+  stderr?: unknown;
+  exitCode?: unknown;
+  detectors?: unknown;
+}
+
+function validateInput(raw: Record<string, unknown>): {
+  ok: true;
+  value: {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    detectors?: string[];
+  };
+} | { ok: false; error: string; field: string; hint: string } {
+  const stdout = raw.stdout ?? "";
+  if (typeof stdout !== "string") {
+    return {
+      ok: false,
+      error: "'stdout' must be a string",
+      field: "stdout",
+      hint: "Omit or pass '' for no stdout",
+    };
+  }
+
+  const stderr = raw.stderr ?? "";
+  if (typeof stderr !== "string") {
+    return {
+      ok: false,
+      error: "'stderr' must be a string",
+      field: "stderr",
+      hint: "Omit or pass '' for no stderr",
+    };
+  }
+
+  let exitCode = 0;
+  if (raw.exitCode !== undefined) {
+    if (typeof raw.exitCode !== "number" || !Number.isFinite(raw.exitCode)) {
+      return {
+        ok: false,
+        error: "'exitCode' must be a finite number",
+        field: "exitCode",
+        hint: "Pass the child-process exit code, typically 0 (success) or non-zero (failure)",
+      };
+    }
+    exitCode = Math.trunc(raw.exitCode);
+  }
+
+  let detectors: string[] | undefined;
+  if (raw.detectors !== undefined) {
+    if (!Array.isArray(raw.detectors) ||
+        !raw.detectors.every((d) => typeof d === "string")) {
+      return {
+        ok: false,
+        error: "'detectors' must be an array of detector IDs",
+        field: "detectors",
+        hint: `Valid IDs: ${listDetectorIds().join(", ")}`,
+      };
+    }
+    detectors = raw.detectors as string[];
+  }
+
+  return {
+    ok: true,
+    value: { stdout, stderr, exitCode, ...(detectors ? { detectors } : {}) },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Handler
+// ─────────────────────────────────────────────────────────────────────────
+
+async function runLoopClose(
+  input: LoopCloseInput,
+): Promise<
+  | {
+      stallReason: string;
+      nextPrompt: string;
+      evidence: Array<{
+        kind: string;
+        file?: string;
+        line?: number;
+        snippet: string;
+        label?: string;
+      }>;
+      detectors_run: string[];
+    }
+  | { error: string; field?: string; hint?: string }
+> {
+  const validated = validateInput(input as Record<string, unknown>);
+  if (!validated.ok) {
+    return {
+      error: validated.error,
+      field: validated.field,
+      hint: validated.hint,
+    };
+  }
+
+  const report = closeLoop(validated.value);
+  return {
+    stallReason: report.stallReason,
+    nextPrompt: report.nextPrompt,
+    evidence: report.evidence,
+    detectors_run: validated.value.detectors ?? listDetectorIds(),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Tool definition + handler map
+// ─────────────────────────────────────────────────────────────────────────
+
+export const loopCloseToolDefinitions: Tool[] = [
+  {
+    name: "mandu.loop.close",
+    description:
+      "Analyze agent output (stdout, stderr, exitCode) and return a structured `nextPrompt` that names the primary stall pattern, explains how to address it, and lists supporting evidence. This tool is pure — it never writes files, spawns processes, or auto-executes anything. The returned prompt is advisory text only.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        stdout: {
+          type: "string",
+          description: "Captured stdout from the most recent command/run.",
+        },
+        stderr: {
+          type: "string",
+          description: "Captured stderr from the most recent command/run.",
+        },
+        exitCode: {
+          type: "number",
+          description: "Child-process exit code. Defaults to 0 when omitted.",
+        },
+        detectors: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional detector-ID allow-list. Omit to run the full built-in set.",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function loopCloseTools(_projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.loop.close": async (args) => runLoopClose(args as LoopCloseInput),
+  };
+  return handlers;
+}