@mandujs/mcp 0.24.0 → 0.27.0

package/src/tools/ate-oracle-pending.ts

@@ -0,0 +1,49 @@
+/**
+ * `mandu_ate_oracle_pending` — Phase C.4.
+ *
+ * List pending semantic oracle entries for agent judgment.
+ * Read-only.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { findOraclePending } from "@mandujs/ate";
+
+export const ateOraclePendingToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_oracle_pending",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase C.4 — list pending semantic oracle entries. Returns the most recent " +
+      "`status=pending` entries from `.mandu/ate-oracle-queue.jsonl`. Each entry " +
+      "carries an assertionId, the spec path, the claim text, and an artifactPath " +
+      "pointing to screenshot / DOM captures. The agent reviews these and issues a " +
+      "verdict via `mandu_ate_oracle_verdict`. CI never blocks on these — " +
+      "expectSemantic is deterministic-non-blocking by default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root." },
+        limit: { type: "number", description: "Maximum entries to return. Default 20." },
+        specPath: { type: "string", description: "Filter to a specific spec file." },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateOraclePendingTools(_projectRoot: string) {
+  return {
+    mandu_ate_oracle_pending: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      const entries = findOraclePending(repoRoot, {
+        ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+        ...(typeof args.specPath === "string" ? { specPath: args.specPath } : {}),
+      });
+      return { ok: true, count: entries.length, entries };
+    },
+  };
+}

package/src/tools/ate-oracle-replay.ts

@@ -0,0 +1,44 @@
+/**
+ * `mandu_ate_oracle_replay` — Phase C.4.
+ *
+ * Read-only. Return every oracle entry (pending + judged) for a spec
+ * path — lets agents review the history of semantic claims for a file
+ * before re-issuing similar assertions.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { findOracleEntriesForSpec } from "@mandujs/ate";
+
+export const ateOracleReplayToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_oracle_replay",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase C.4 — replay every oracle verdict (pending + passed + failed) for a " +
+      "given spec. Returns the full audit trail sorted newest → oldest. Useful for " +
+      "agents reviewing past `failed` verdicts before re-issuing similar semantic " +
+      "claims, or for human auditors walking the queue history.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root." },
+        specPath: { type: "string", description: "Spec file path to replay." },
+      },
+      required: ["repoRoot", "specPath"],
+    },
+  },
+];
+
+export function ateOracleReplayTools(_projectRoot: string) {
+  return {
+    mandu_ate_oracle_replay: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const specPath = args.specPath as string | undefined;
+      if (!repoRoot) return { ok: false, error: "repoRoot is required" };
+      if (!specPath) return { ok: false, error: "specPath is required" };
+      const entries = findOracleEntriesForSpec(repoRoot, specPath);
+      return { ok: true, count: entries.length, entries };
+    },
+  };
+}

package/src/tools/ate-oracle-verdict.ts

@@ -0,0 +1,70 @@
+/**
+ * `mandu_ate_oracle_verdict` — Phase C.4.
+ *
+ * Apply an agent / human verdict to a pending oracle entry. Rewrites
+ * matching pending rows with `status = passed|failed` + verdict metadata.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { setOracleVerdict } from "@mandujs/ate";
+
+export const ateOracleVerdictToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_oracle_verdict",
+    annotations: {
+      readOnlyHint: false,
+    },
+    description:
+      "Phase C.4 — record an oracle verdict for a pending semantic assertion. " +
+      "`verdict: 'pass' | 'fail'`. `judgedBy`: 'agent' (default) or 'human'. " +
+      "`reason` is the short free-form justification the agent (or human) provides. " +
+      "Every pending queue entry with the matching assertionId transitions to the " +
+      "given verdict — subsequent `promoteVerdicts: true` expectSemantic calls will " +
+      "see past `failed` verdicts and throw deterministically.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Absolute path to the Mandu project root." },
+        assertionId: { type: "string", description: "Stable assertion id returned by expectSemantic." },
+        verdict: {
+          type: "string",
+          enum: ["pass", "fail"],
+          description: "Whether the agent judges the claim satisfied.",
+        },
+        reason: { type: "string", description: "Free-form justification." },
+        judgedBy: {
+          type: "string",
+          enum: ["agent", "human"],
+          description: "Source of the verdict. Defaults to 'agent'.",
+        },
+      },
+      required: ["repoRoot", "assertionId", "verdict", "reason"],
+    },
+  },
+];
+
+export function ateOracleVerdictTools(_projectRoot: string) {
+  return {
+    mandu_ate_oracle_verdict: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const assertionId = args.assertionId as string | undefined;
+      const verdict = args.verdict as string | undefined;
+      const reason = args.reason as string | undefined;
+      const judgedBy = args.judgedBy as string | undefined;
+      if (!repoRoot) return { ok: false, error: "repoRoot is required" };
+      if (!assertionId) return { ok: false, error: "assertionId is required" };
+      if (verdict !== "pass" && verdict !== "fail") {
+        return { ok: false, error: "verdict must be 'pass' or 'fail'" };
+      }
+      if (!reason || typeof reason !== "string") {
+        return { ok: false, error: "reason is required" };
+      }
+      const res = setOracleVerdict(repoRoot, {
+        assertionId,
+        verdict,
+        reason,
+        ...(judgedBy === "agent" || judgedBy === "human" ? { judgedBy } : {}),
+      });
+      return { ok: true, updated: res.updated, entries: res.entries };
+    },
+  };
+}

package/src/tools/ate-recall.ts

@@ -0,0 +1,85 @@
+/**
+ * `mandu_ate_recall` — Phase B.2 memory read tool.
+ *
+ * See docs/ate/phase-b-spec.md §B.2. Agents call this BEFORE generating
+ * a spec so they can reference prior intent / rejected healing history.
+ *
+ * Snake_case (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { recallMemory, type MemoryEventKind } from "@mandujs/ate";
+
+export const ateRecallToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_recall",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase B.2 memory recall. Queries the project-local " +
+      ".mandu/ate-memory.jsonl append-only log with substring + token-" +
+      "overlap scoring (no embeddings). Useful BEFORE generation to see " +
+      "previously rejected specs, accepted heals, or intent history for " +
+      "the same route. Returns { events, totalMatching }. Default limit 10, " +
+      "default sinceDays 90. Filter by kind: intent_history | rejected_spec " +
+      "| accepted_healing | rejected_healing | prompt_version_drift | " +
+      "boundary_gap_filled | coverage_snapshot.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        intent: {
+          type: "string",
+          description: "Natural-language intent to search (substring + token overlap).",
+        },
+        route: {
+          type: "string",
+          description: "Route id or pattern ('api-signup' or '/api/signup').",
+        },
+        kind: {
+          type: "string",
+          description: "Filter by event kind.",
+        },
+        limit: {
+          type: "number",
+          description: "Max events to return. Default 10.",
+        },
+        sinceDays: {
+          type: "number",
+          description: "Drop events older than N days. Default 90.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateRecallTools(_projectRoot: string) {
+  return {
+    mandu_ate_recall: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      try {
+        const result = recallMemory(repoRoot, {
+          intent: typeof args.intent === "string" ? args.intent : undefined,
+          route: typeof args.route === "string" ? args.route : undefined,
+          kind:
+            typeof args.kind === "string"
+              ? (args.kind as MemoryEventKind)
+              : undefined,
+          limit: typeof args.limit === "number" ? args.limit : undefined,
+          sinceDays: typeof args.sinceDays === "number" ? args.sinceDays : undefined,
+        });
+        return { ok: true, ...result };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+}

package/src/tools/ate-remember.ts

@@ -0,0 +1,79 @@
+/**
+ * `mandu_ate_remember` — Phase B.2 memory write tool.
+ *
+ * Snake_case (§11 decision #4). Idempotent append.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  appendMemoryEvent,
+  parseMemoryEvent,
+  type MemoryEvent,
+} from "@mandujs/ate";
+
+export const ateRememberToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_remember",
+    description:
+      "Phase B.2 memory write. Appends one event to the project-local " +
+      ".mandu/ate-memory.jsonl. File auto-rotates to .bak when it crosses " +
+      "10 MB. Supported event kinds (discriminated union by `kind`): " +
+      "intent_history | rejected_spec | accepted_healing | rejected_healing " +
+      "| prompt_version_drift | boundary_gap_filled | coverage_snapshot. " +
+      "Timestamp defaults to now (ISO-8601 UTC) if omitted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        event: {
+          type: "object",
+          description:
+            "MemoryEvent object. Must carry a `kind` discriminator plus the " +
+            "event-kind-specific required fields (see @mandujs/ate memory/schema.ts).",
+          additionalProperties: true,
+        },
+      },
+      required: ["repoRoot", "event"],
+    },
+  },
+];
+
+export function ateRememberTools(_projectRoot: string) {
+  return {
+    mandu_ate_remember: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const eventRaw = args.event;
+
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!eventRaw || typeof eventRaw !== "object") {
+        return { ok: false, error: "event is required" };
+      }
+
+      // Default the timestamp if the caller omitted it (agents do).
+      const draft = { ...(eventRaw as Record<string, unknown>) };
+      if (typeof draft.timestamp !== "string") {
+        draft.timestamp = new Date().toISOString();
+      }
+      const parsed = parseMemoryEvent(draft);
+      if (!parsed) {
+        return {
+          ok: false,
+          error:
+            "Event failed validation. Check that `kind` and the kind-specific required fields are present.",
+        };
+      }
+
+      try {
+        const result = appendMemoryEvent(repoRoot, parsed as MemoryEvent);
+        return { ok: true, written: result.written, rotation: result.rotation ?? null };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+}

package/src/tools/ate-save.ts

@@ -1,139 +1,160 @@
-/**
- * `mandu_ate_save` — Phase A.3 spec persistence with lint-before-write.
- *
- * See `docs/ate/roadmap-v2-agent-native.md` §4.7 and the §7 extension
- * ("mandu_ate_save lint-before-write").
- *
- * Semantics:
- *   1. Run `lintSpecContent` (from @mandujs/ate) which:
- *        - parses with ts-morph (syntax errors block),
- *        - walks import declarations (banned typos, unknown @mandujs/* barrels),
- *        - detects anti-patterns (bare localhost, hand-rolled CSRF, DB mocks).
- *   2. If any *blocking* diagnostic fires, return { saved: false, ... } WITHOUT
- *      writing. Otherwise write and return { saved: true, path }.
- *
- * Snake_case tool name (§11 decision #4).
- */
-
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
-import { dirname, isAbsolute } from "node:path";
-import { lintSpecContent, type LintDiagnostic } from "@mandujs/ate";
-
-// Re-export the diagnostic shape so callers can type-check against it without
-// pulling @mandujs/ate directly.
-export type { LintDiagnostic, LintSeverity } from "@mandujs/ate";
-
-export const ateSaveToolDefinitions: Tool[] = [
-  {
-    name: "mandu_ate_save",
-    description:
-      "Phase A.3 persist-with-lint. Writes an agent-generated test file to " +
-      "disk, but first runs a small lint pass that blocks common LLM mistakes: " +
-      "ts-morph syntax errors, unresolved / banned import paths, hand-rolled " +
-      "CSRF cookies, DB mocks when createTestDb is available, and bare " +
-      "`localhost:<port>` URLs (prefer 127.0.0.1 per roadmap §9.2). Returns " +
-      "{ saved: true, path, lintDiagnostics: [warnings...] } on success or " +
-      "{ saved: false, blockingErrors: [...], lintDiagnostics: [...] } when " +
-      "a blocker fires (in which case no file is written).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        path: {
-          type: "string",
-          description:
-            "Absolute path where the spec will be written. Parent directories are created if needed.",
-        },
-        content: {
-          type: "string",
-          description: "The full TypeScript test source to write.",
-        },
-        intent: {
-          type: "string",
-          description:
-            "Optional short description of what the test is verifying (logged to ATE memory).",
-        },
-        kind: {
-          type: "string",
-          description:
-            "Optional prompt kind this spec was generated for (filling_unit, filling_integration, e2e_playwright).",
-        },
-        sourcePrompt: {
-          type: "object",
-          description:
-            "Optional { kind, version } back-reference to the prompt that produced this spec (used by future memory queries).",
-          additionalProperties: true,
-        },
-        allowWarnings: {
-          type: "boolean",
-          description:
-            "When true, non-blocking warnings still allow the write (default true). When false, even warnings block.",
-        },
-      },
-      required: ["path", "content"],
-    },
-  },
-];
-
-export function ateSaveTools(_projectRoot: string) {
-  return {
-    mandu_ate_save: async (args: Record<string, unknown>) => {
-      const path = args.path as string | undefined;
-      const content = args.content as string | undefined;
-      const allowWarnings = args.allowWarnings !== false;
-
-      if (!path || typeof path !== "string") {
-        return { saved: false, error: "'path' is required" };
-      }
-      if (!isAbsolute(path)) {
-        return {
-          saved: false,
-          error: "'path' must be absolute — relative paths are rejected to prevent cwd drift.",
-        };
-      }
-      if (typeof content !== "string") {
-        return { saved: false, error: "'content' is required and must be a string" };
-      }
-
-      const diagnostics = await lintSpecContent(path, content);
-
-      const blocking = diagnostics.filter((d) => d.blocking);
-      const warnings = diagnostics.filter((d) => !d.blocking);
-
-      if (blocking.length > 0 || (!allowWarnings && warnings.length > 0)) {
-        return {
-          saved: false,
-          path,
-          blockingErrors: blocking,
-          lintDiagnostics: diagnostics,
-        };
-      }
-
-      const parent = dirname(path);
-      if (!existsSync(parent)) {
-        mkdirSync(parent, { recursive: true });
-      }
-      if (!statSync(parent).isDirectory()) {
-        return { saved: false, path, error: `Parent path is not a directory: ${parent}` };
-      }
-
-      writeFileSync(path, content, "utf8");
-
-      return {
-        saved: true,
-        path,
-        bytes: Buffer.byteLength(content, "utf8"),
-        lintDiagnostics: diagnostics,
-      };
-    },
-  };
-}
-
-// Re-export for tests that need direct access (package.json test patterns
-// already reach here).
-export async function lintContent(
-  path: string,
-  content: string,
-): Promise<LintDiagnostic[]> {
-  return lintSpecContent(path, content);
-}
+/**
+ * `mandu_ate_save` — Phase A.3 spec persistence with lint-before-write.
+ *
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.7 and the §7 extension
+ * ("mandu_ate_save lint-before-write").
+ *
+ * Semantics:
+ *   1. Run `lintSpecContent` (from @mandujs/ate) which:
+ *        - parses with ts-morph (syntax errors block),
+ *        - walks import declarations (banned typos, unknown @mandujs/* barrels),
+ *        - detects anti-patterns (bare localhost, hand-rolled CSRF, DB mocks).
+ *   2. If any *blocking* diagnostic fires, return { saved: false, ... } WITHOUT
+ *      writing. Otherwise write and return { saved: true, path }.
+ *
+ * Snake_case tool name (§11 decision #4).
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute } from "node:path";
+import {
+  lintSpecContent,
+  appendMemoryEvent,
+  nowTimestamp,
+  type LintDiagnostic,
+} from "@mandujs/ate";
+
+// Re-export the diagnostic shape so callers can type-check against it without
+// pulling @mandujs/ate directly.
+export type { LintDiagnostic, LintSeverity } from "@mandujs/ate";
+
+export const ateSaveToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_save",
+    description:
+      "Phase A.3 persist-with-lint. Writes an agent-generated test file to " +
+      "disk, but first runs a small lint pass that blocks common LLM mistakes: " +
+      "ts-morph syntax errors, unresolved / banned import paths, hand-rolled " +
+      "CSRF cookies, DB mocks when createTestDb is available, and bare " +
+      "`localhost:<port>` URLs (prefer 127.0.0.1 per roadmap §9.2). Returns " +
+      "{ saved: true, path, lintDiagnostics: [warnings...] } on success or " +
+      "{ saved: false, blockingErrors: [...], lintDiagnostics: [...] } when " +
+      "a blocker fires (in which case no file is written).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description:
+            "Absolute path where the spec will be written. Parent directories are created if needed.",
+        },
+        content: {
+          type: "string",
+          description: "The full TypeScript test source to write.",
+        },
+        intent: {
+          type: "string",
+          description:
+            "Optional short description of what the test is verifying (logged to ATE memory).",
+        },
+        kind: {
+          type: "string",
+          description:
+            "Optional prompt kind this spec was generated for (filling_unit, filling_integration, e2e_playwright).",
+        },
+        sourcePrompt: {
+          type: "object",
+          description:
+            "Optional { kind, version } back-reference to the prompt that produced this spec (used by future memory queries).",
+          additionalProperties: true,
+        },
+        allowWarnings: {
+          type: "boolean",
+          description:
+            "When true, non-blocking warnings still allow the write (default true). When false, even warnings block.",
+        },
+      },
+      required: ["path", "content"],
+    },
+  },
+];
+
+export function ateSaveTools(projectRoot: string) {
+  return {
+    mandu_ate_save: async (args: Record<string, unknown>) => {
+      const path = args.path as string | undefined;
+      const content = args.content as string | undefined;
+      const intent = typeof args.intent === "string" ? args.intent : undefined;
+      const kind = typeof args.kind === "string" ? args.kind : undefined;
+      const allowWarnings = args.allowWarnings !== false;
+
+      if (!path || typeof path !== "string") {
+        return { saved: false, error: "'path' is required" };
+      }
+      if (!isAbsolute(path)) {
+        return {
+          saved: false,
+          error: "'path' must be absolute — relative paths are rejected to prevent cwd drift.",
+        };
+      }
+      if (typeof content !== "string") {
+        return { saved: false, error: "'content' is required and must be a string" };
+      }
+
+      const diagnostics = await lintSpecContent(path, content);
+
+      const blocking = diagnostics.filter((d) => d.blocking);
+      const warnings = diagnostics.filter((d) => !d.blocking);
+
+      if (blocking.length > 0 || (!allowWarnings && warnings.length > 0)) {
+        return {
+          saved: false,
+          path,
+          blockingErrors: blocking,
+          lintDiagnostics: diagnostics,
+        };
+      }
+
+      const parent = dirname(path);
+      if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+      }
+      if (!statSync(parent).isDirectory()) {
+        return { saved: false, path, error: `Parent path is not a directory: ${parent}` };
+      }
+
+      writeFileSync(path, content, "utf8");
+
+      // Phase B.2 — auto-record intent_history event. Non-fatal on failure.
+      try {
+        appendMemoryEvent(projectRoot, {
+          kind: "intent_history",
+          timestamp: nowTimestamp(),
+          intent: intent ?? "(no intent supplied)",
+          agent: typeof args.agent === "string" ? (args.agent as string) : "unknown",
+          resulting: { saved: [path] },
+          ...(kind ? { routeId: kind } : {}),
+        });
+      } catch {
+        // swallow
+      }
+
+      return {
+        saved: true,
+        path,
+        bytes: Buffer.byteLength(content, "utf8"),
+        lintDiagnostics: diagnostics,
+      };
+    },
+  };
+}
+
+// Re-export for tests that need direct access (package.json test patterns
+// already reach here).
+export async function lintContent(
+  path: string,
+  content: string,
+): Promise<LintDiagnostic[]> {
+  return lintSpecContent(path, content);
+}