@radix-ai/ai-memory 0.1.0

package/dist/mcp-server/tools.js

@@ -0,0 +1,928 @@
+import { readFile, writeFile, readdir, mkdir, unlink, open } from "fs/promises";
+import { join, dirname, resolve, relative } from "path";
+import { existsSync } from "fs";
+import { execFileSync } from "child_process";
+import { minimatch } from "minimatch";
+import matter from "gray-matter";
+import { ListToolsRequestSchema, CallToolRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { readP0Entries, compileHarnessRules, generateRuleTests, } from "./p0-parser.js";
+import { VALID_TYPES, VALID_STATUSES } from "../schema-constants.js";
+import { loadDocsSchema, getDocPath, validateDocPlacement, listDocTypes, } from "../docs-schema.js";
+import { hybridSearch, getSearchMode, } from "../hybrid-search/index.js";
+// Paths that are ALWAYS immutable (structural, not content)
+const ALWAYS_IMMUTABLE = ["toolbox/", "acp/", "rules/"];
+// Paths whose immutability is controlled by frontmatter `writable` field
+// IDENTITY.md: writable defaults to false (immutable unless opted in)
+// PROJECT_STATUS.md: writable defaults to true (the AI's evolving program)
+const FRONTMATTER_CONTROLLED = ["IDENTITY.md", "PROJECT_STATUS.md"];
+const WRITABLE_DEFAULTS = {
+    "IDENTITY.md": false,
+    "PROJECT_STATUS.md": true,
+};
+async function isImmutable(path, aiDir) {
+    // Structural paths are always immutable
+    if (ALWAYS_IMMUTABLE.some((p) => path === p || path.startsWith(p))) {
+        return true;
+    }
+    // Frontmatter-controlled files
+    for (const controlled of FRONTMATTER_CONTROLLED) {
+        if (path === controlled) {
+            const fullPath = join(aiDir, controlled);
+            try {
+                const content = await readFile(fullPath, "utf-8");
+                const { data } = matter(content);
+                // If frontmatter has `writable`, use that; otherwise use default
+                if (typeof data.writable === "boolean")
+                    return !data.writable;
+                return !WRITABLE_DEFAULTS[controlled];
+            }
+            catch {
+                return !WRITABLE_DEFAULTS[controlled];
+            }
+        }
+    }
+    return false;
+}
+// ─── Session-aware writes ─────────────────────────────────────────────────────
+// Returns git repo root (absolute path) or null if not in a git repo
+function getRepoRoot(cwd) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd,
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+// Shared path validation: ensures a relative path stays within aiDir
+function assertPathWithinAiDir(aiDir, relPath) {
+    const fullPath = resolve(aiDir, relPath);
+    const rel = relative(aiDir, fullPath);
+    if (rel.startsWith("..") || rel.startsWith("/") || /\.\.[\\/]/.test(rel)) {
+        throw new McpError(ErrorCode.InvalidRequest, "Path traversal not allowed.");
+    }
+    return fullPath;
+}
+function generateSessionId() {
+    return `s-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+// Claim system: prevents concurrent writes to the same path
+const CLAIM_TTL_MS = 5 * 60 * 1000; // 5 minutes
+async function acquireClaim(aiDir, path, sessionId) {
+    const locksDir = join(aiDir, "temp", "locks");
+    await mkdir(locksDir, { recursive: true });
+    const lockFile = join(locksDir, path.replace(/[/\\]/g, "_") + ".lock");
+    // Check for existing valid claim
+    if (existsSync(lockFile)) {
+        try {
+            const existing = JSON.parse(await readFile(lockFile, "utf-8"));
+            const age = Date.now() - existing.timestamp;
+            if (age < CLAIM_TTL_MS && existing.session_id !== sessionId) {
+                throw new McpError(ErrorCode.InvalidRequest, `Path "${path}" is claimed by another session (${existing.session_id}, ${Math.round(age / 1000)}s ago). ` +
+                    `Wait for the claim to expire (${Math.round(CLAIM_TTL_MS / 1000)}s TTL) or close the other session.`);
+            }
+            // Expired or same session — remove stale lock before re-creating
+            await unlink(lockFile).catch(() => { });
+        }
+        catch (err) {
+            if (err instanceof McpError)
+                throw err;
+            // Corrupt lock file — remove and re-create
+            await unlink(lockFile).catch(() => { });
+        }
+    }
+    // Atomic file creation with O_EXCL — prevents TOCTOU race
+    const claim = { session_id: sessionId, timestamp: Date.now(), pid: process.pid };
+    const data = JSON.stringify(claim);
+    try {
+        const fd = await open(lockFile, "wx"); // O_WRONLY | O_CREAT | O_EXCL
+        await fd.writeFile(data);
+        await fd.close();
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            // Another process created the lock between our check and creation
+            throw new McpError(ErrorCode.InvalidRequest, `Path "${path}" was just claimed by another session. Retry shortly.`);
+        }
+        throw err;
+    }
+}
+async function releaseClaim(aiDir, path) {
+    const lockFile = join(aiDir, "temp", "locks", path.replace(/[/\\]/g, "_") + ".lock");
+    try {
+        await unlink(lockFile);
+    }
+    catch { /* already gone */ }
+}
+// Parse diff into sections with file path (from b/ side) and content
+function parseDiffSections(diff) {
+    const sections = [];
+    const parts = diff.split(/^diff --git /m).slice(1);
+    for (const part of parts) {
+        const fileMatch = part.match(/^[^\n]*b\/(.+)$/m);
+        if (!fileMatch)
+            continue;
+        const path = fileMatch[1].trim();
+        const addedLines = part
+            .split("\n")
+            .filter((l) => l.startsWith("+") && !l.startsWith("+++"))
+            .map((l) => l.slice(1))
+            .join("\n");
+        const deletedLines = part
+            .split("\n")
+            .filter((l) => l.startsWith("-") && !l.startsWith("---"))
+            .map((l) => l.slice(1))
+            .join("\n");
+        sections.push({ path, addedLines, deletedLines });
+    }
+    return sections;
+}
+// Validate a git diff against harness rules using ast-grep and regex.
+// repoRoot: git root for path resolution; falls back to aiDir parent if null.
+// Rules are applied ONLY to diff files matching rule.path (minimatch). Default path: "**/*".
+async function validateDiff(diff, rules, aiDir, repoRoot) {
+    const sections = parseDiffSections(diff);
+    const violations = [];
+    const audit = [];
+    for (const rule of rules) {
+        const pathGlob = rule.path?.trim() || "**/*";
+        const matchingSections = sections.filter((s) => minimatch(s.path, pathGlob));
+        if (rule.type === "regex") {
+            const scope = rule.scope ?? "additions";
+            let content = "";
+            if (scope === "additions") {
+                content = matchingSections.map((s) => s.addedLines).join("\n");
+            }
+            else if (scope === "deletions") {
+                content = matchingSections.map((s) => s.deletedLines).join("\n");
+            }
+            else {
+                content = matchingSections.map((s) => s.addedLines + "\n" + s.deletedLines).join("\n");
+            }
+            if (matchingSections.length === 0) {
+                audit.push({ rule_id: rule.id, path: pathGlob, status: "skipped" });
+                continue;
+            }
+            let regex;
+            try {
+                regex = new RegExp(rule.pattern, "gm");
+            }
+            catch {
+                violations.push({ rule_id: rule.id, message: `Invalid regex pattern: ${rule.pattern}`, severity: rule.severity });
+                audit.push({ rule_id: rule.id, path: pathGlob, status: "failed" });
+                continue;
+            }
+            const triggered = content.trim() && regex.test(content);
+            if (triggered) {
+                violations.push({ rule_id: rule.id, message: rule.message, severity: rule.severity });
+                audit.push({ rule_id: rule.id, path: pathGlob, status: "failed" });
+            }
+            else {
+                audit.push({ rule_id: rule.id, path: pathGlob, status: "passed" });
+            }
+        }
+        else if (rule.type === "ast") {
+            if (matchingSections.length === 0) {
+                audit.push({ rule_id: rule.id, path: pathGlob, status: "skipped" });
+                continue;
+            }
+            try {
+                const { Lang, parse } = await import("@ast-grep/napi");
+                const langKey = (rule.language ?? "typescript").toLowerCase();
+                const langMap = {
+                    typescript: Lang.TypeScript,
+                    javascript: Lang.JavaScript,
+                    python: Lang.Python,
+                    go: Lang.Go,
+                    rust: Lang.Rust,
+                };
+                const lang = langMap[langKey] ?? Lang.TypeScript;
+                const matcher = rule.where && Object.keys(rule.where).length > 0
+                    ? { rule: { pattern: rule.pattern }, constraints: rule.where }
+                    : rule.pattern;
+                let found = false;
+                for (const section of matchingSections) {
+                    const addedCode = section.addedLines;
+                    if (!addedCode.trim())
+                        continue;
+                    const tree = parse(lang, addedCode);
+                    const sgRoot = tree.root();
+                    const matches = typeof matcher === "string"
+                        ? sgRoot.findAll(matcher)
+                        : sgRoot.findAll(matcher);
+                    if (matches.length > 0) {
+                        found = true;
+                        violations.push({ rule_id: rule.id, message: rule.message, severity: rule.severity });
+                        audit.push({ rule_id: rule.id, path: pathGlob, status: "failed" });
+                        break;
+                    }
+                }
+                if (!found) {
+                    audit.push({ rule_id: rule.id, path: pathGlob, status: "passed" });
+                }
+            }
+            catch {
+                violations.push({
+                    rule_id: rule.id,
+                    message: `${rule.message} (ast-grep unavailable — manual review required)`,
+                    severity: rule.severity,
+                });
+                audit.push({ rule_id: rule.id, path: pathGlob, status: "failed" });
+            }
+        }
+    }
+    return { violations, audit };
+}
+// Validate memory entry frontmatter against canonical schema
+function validateEntrySchema(entry) {
+    const errors = [];
+    const required = ["id", "type", "status"];
+    for (const field of required) {
+        if (!entry[field])
+            errors.push(`Missing required field: ${field}`);
+    }
+    if (entry.type && !VALID_TYPES.includes(entry.type)) {
+        errors.push(`Invalid type: ${entry.type}. Must be one of: ${VALID_TYPES.join(", ")}`);
+    }
+    if (entry.status && !VALID_STATUSES.includes(entry.status)) {
+        errors.push(`Invalid status: ${entry.status}. Must be one of: ${VALID_STATUSES.join(", ")}`);
+    }
+    return errors;
+}
+export function registerTools(server, aiDir) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "search_memory",
+                description: "Searches across .ai/ memory files (memory/, sessions/, agents/, skills/) and returns ranked results with excerpts. " +
+                    "Uses hybrid search (keyword + semantic + RRF) by default. AI_SEARCH=keyword|semantic|hybrid. " +
+                    "On Windows, onnxruntime-node may fail; set AI_SEARCH=keyword for keyword-only, or AI_SEARCH_WASM=1 to try WASM. " +
+                    "Semantic/hybrid requires Linux or macOS for native; Windows uses keyword-only or WASM. " +
+                    "Each result includes: file path (relative to .ai/), excerpt, and score. " +
+                    "For best results: use specific terms from the task (e.g. 'MCP launcher Windows', 'claim locking'); optionally filter by tags if the query mentions them.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string", description: "Search query — use specific terms relevant to the task" },
+                        tags: { type: "array", items: { type: "string" }, description: "Filter by tags (optional). Only files containing all tags are returned." },
+                        limit: { type: "number", description: "Max results to return (default 10, max 20). Use lower values for focused queries." },
+                        include_deprecated: { type: "boolean", description: "Include [DEPRECATED] entries in results (default false). Set true for auditing or history review." },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "get_repo_root",
+                description: "Returns the git repository root (absolute path) via `git rev-parse --show-toplevel`. " +
+                    "Use to resolve paths for validate_context, path traversal checks, or when the agent runs from a subdirectory. " +
+                    "Returns null if not in a git repo.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "validate_context",
+                description: "Validates a git diff against active [P0] constraint rules. Returns violations as errors — hard blocks if any P0 rule is triggered. " +
+                    "You MUST run generate_harness first (or use init --full) to create .ai/temp/harness.json. " +
+                    "Each violation includes: rule_id, message, severity (P0/P1/P2). P0 violations cause a hard block; P1/P2 return warnings. " +
+                    "For best results: pass the full output of `git diff` (staged or unstaged) before committing.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        git_diff: { type: "string", description: "Output of git diff (e.g. git diff or git diff --cached)" },
+                    },
+                    required: ["git_diff"],
+                },
+            },
+            {
+                name: "validate_schema",
+                description: "Validates a proposed memory entry's frontmatter against the canonical schema. Returns validation errors. " +
+                    "Required fields: id, type, status. Valid types: identity, project-status, decision, pattern, debugging, improvement, index, session, reference, agent, skill, rule, acp, toolbox, docs-schema. Valid statuses: active, deprecated, experimental. " +
+                    "Use before commit_memory when constructing entries programmatically to catch schema errors early.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entry: { type: "object", description: "Memory entry frontmatter fields to validate (id, type, status, etc.)" },
+                    },
+                    required: ["entry"],
+                },
+            },
+            {
+                name: "commit_memory",
+                description: "Writes a memory entry to .ai/. Enforces immutability: IDENTITY.md is immutable by default; PROJECT_STATUS.md is writable by default (configurable via frontmatter `writable`). Hard-blocks writes to toolbox/, acp/, rules/. Uses claim-based locking for multi-agent safety — if another session holds a claim on the path, wait for the 5-minute TTL or close the other session. " +
+                    "Each write appends a session header for traceability. Use append: false to overwrite (creates new file or replaces). " +
+                    "For best results: use validate_schema first when constructing entries; pass session_id when coordinating with claim_task or publish_result. When work is done: break down into atomic tasks that fit RALPH loops and avoid conflicts when agents work in parallel.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Relative path within .ai/ (e.g. memory/decisions.md, memory/patterns.md)" },
+                        content: { type: "string", description: "Content to append or write (include frontmatter for memory entries)" },
+                        append: { type: "boolean", description: "Append to existing file (true) or overwrite (false). Default: true." },
+                        session_id: { type: "string", description: "Optional session identifier for multi-agent tracking. Auto-generated if not provided." },
+                    },
+                    required: ["path", "content"],
+                },
+            },
+            {
+                name: "generate_harness",
+                description: "Compiles harness.json from current [P0] entries in memory/decisions.md. Writes .ai/temp/harness.json and rule tests to .ai/temp/rule-tests/tests.json. " +
+                    "Required before validate_context. Run after adding or changing [P0] entries to refresh the rule set.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "get_open_items",
+                description: "Returns the current open and closed items from sessions/open-items.md. " +
+                    "Use at session start to see pending tasks, or before claim_task to avoid duplicate work.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                name: "get_memory",
+                description: "Returns a summary of memory for a specific topic. Searches .ai/ and returns top 5 matches with file path and excerpt. " +
+                    "Use for quick lookups when you need a focused answer (e.g. 'authentication', 'MCP config'). " +
+                    "For broader exploration, use search_memory instead.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        topic: { type: "string", description: "Topic to summarize (e.g. 'authentication', 'database patterns', 'project status')" },
+                    },
+                    required: ["topic"],
+                },
+            },
+            {
+                name: "prune_memory",
+                description: "Identifies stale or deprecated memory entries for archiving. Scans memory/*.md for [DEPRECATED] entries. " +
+                    "Returns a list of candidates with file and entry count. Use dry_run: true (default) to report without modifying; dry_run: false to flag for manual archiving. " +
+                    "For best results: run periodically to keep memory lean; review candidates before archiving.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        dry_run: { type: "boolean", description: "If true, report candidates without modifying files. Default: true." },
+                    },
+                },
+            },
+            {
+                name: "get_evals",
+                description: "Returns the latest eval report from .ai/temp/eval-report.json. " +
+                    "Use to check memory health and governance metrics. Run `ai-memory eval` to generate the report.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            // ─── Autoresearch collaboration tools ────────────────────────────────
+            {
+                name: "claim_task",
+                description: "Claims a task before starting work. Searches the task source file (open-items.md by default, or a plan file, PROJECT_STATUS.md) for a matching unclaimed item and marks it [CLAIMED:session_id]. Prevents duplicate work across concurrent agents. Claims expire after 5 minutes. " +
+                    "If no match is found, creates a new claimed task in open-items.md. " +
+                    "For best results: use task_description that matches the wording in the source (e.g. 'Add Context7 MCP'); specify source when the task lives in a plan file or PROJECT_STATUS.md.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        task_description: { type: "string", description: "Description of the task to claim (match wording in source for best match)" },
+                        source: { type: "string", description: "Relative path to task source within .ai/ (default: sessions/open-items.md). Can be a plan file, PROJECT_STATUS.md, etc." },
+                        session_id: { type: "string", description: "Session identifier. Auto-generated if not provided. Use same ID for publish_result to link result to claim." },
+                    },
+                    required: ["task_description"],
+                },
+            },
+            {
+                name: "publish_result",
+                description: "Publishes an experiment or task result (success, failure, or partial) to sessions/archive/thread-archive.md. Every result is recorded for collective learning. " +
+                    "If the task was claimed via claim_task with the same session_id, marks the task complete (success) or reopened (failure) in open-items.md. " +
+                    "Each entry includes: date, outcome icon, summary, learnings (optional), session_id. " +
+                    "For best results: include learnings (patterns, anti-patterns, decisions) to enrich the archive.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        summary: { type: "string", description: "What was attempted and what happened" },
+                        outcome: { type: "string", enum: ["success", "failure", "partial"], description: "Outcome: success, failure, or partial" },
+                        learnings: { type: "string", description: "What was learned (patterns, anti-patterns, decisions). Optional but recommended." },
+                        session_id: { type: "string", description: "Session identifier. Auto-generated if not provided. Use same ID as claim_task to link." },
+                    },
+                    required: ["summary", "outcome"],
+                },
+            },
+            {
+                name: "sync_memory",
+                description: "Persists all .ai/ changes to git. Stages .ai/, commits with a message, and optionally pushes. Essential for ephemeral environments (worktrees, cloud agents, sandbox). " +
+                    "Requires a git repository. Returns the commit message and list of files committed. " +
+                    "For best results: run after commit_memory or other .ai/ writes; use push: true when in a cloud agent or worktree to persist to remote.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        message: { type: "string", description: "Commit message. Auto-generated if not provided." },
+                        push: { type: "boolean", description: "Push to remote after commit. Default: false." },
+                    },
+                },
+            },
+            // ─── Documentation management ───────────────────────────────────────────
+            {
+                name: "get_doc_path",
+                description: "Returns the canonical path for a documentation type from .ai/docs-schema.json. Use before creating or updating docs — do not infer paths. " +
+                    "Types: design-system, adr, api-spec, api-guide, model-card, prompts, backlog, decisions-archive, changelog. " +
+                    "Returns null if schema missing or type unknown. Pass slug for types with * in pattern (e.g. design-system slug=<Project>).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        type: { type: "string", description: "Doc type (e.g. design-system, backlog, changelog)" },
+                        slug: { type: "string", description: "Optional slug for parameterized types (e.g. project name for design-system)" },
+                    },
+                    required: ["type"],
+                },
+            },
+            {
+                name: "validate_doc_placement",
+                description: "Validates a file path against .ai/docs-schema.json. Checks naming convention (SCREAMING_SNAKE by default) and path. " +
+                    "Returns valid: boolean and errors: string[]. Use before writing docs; run in background during compound. " +
+                    "If schema missing, returns valid: true.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Relative path to validate (e.g. docs/BACKLOG.md)" },
+                        paths: { type: "array", items: { type: "string" }, description: "Multiple paths to validate" },
+                    },
+                },
+            },
+            {
+                name: "list_doc_types",
+                description: "Lists all doc types from .ai/docs-schema.json with their path and pattern. " +
+                    "Use to discover available types before get_doc_path. Returns empty if schema missing.",
+                inputSchema: { type: "object", properties: {} },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        switch (name) {
+            case "search_memory": {
+                const query = args.query;
+                if (typeof query !== "string" || !query.trim()) {
+                    throw new McpError(ErrorCode.InvalidParams, "query is required and must be a non-empty string.");
+                }
+                const tags = args.tags;
+                const userLimit = Math.min(Number(args.limit) || 10, 20);
+                const includeDeprecated = args.include_deprecated ?? false;
+                const mode = getSearchMode();
+                let resp;
+                let fallbackNote = "";
+                try {
+                    resp = await hybridSearch(aiDir, query, { mode, limit: userLimit, tags, includeDeprecated });
+                }
+                catch (err) {
+                    if (mode !== "keyword") {
+                        resp = await hybridSearch(aiDir, query, { mode: "keyword", limit: userLimit, tags, includeDeprecated });
+                        fallbackNote =
+                            "Note: Hybrid/semantic search failed (e.g. onnxruntime-node missing on Windows). Using keyword-only. Set AI_SEARCH=keyword to skip, or AI_SEARCH_WASM=1 to try WASM.\n\n";
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+                const { results, backend } = resp;
+                if (results.length === 0) {
+                    return { content: [{ type: "text", text: "No results found." }] };
+                }
+                const backendLabel = backend === "keyword" ? "Keyword-only" : backend === "native" ? "Hybrid (Native)" : "Hybrid (WASM)";
+                const text = fallbackNote + `Search backend: ${backendLabel}\n\n` +
+                    results
+                        .map((r, i) => {
+                        const excerpt = r.excerpt.length > 200 ? r.excerpt.slice(0, 200) + "…" : r.excerpt;
+                        return `${i + 1}. **${r.file}** (score: ${r.score})\n   ${excerpt}`;
+                    })
+                        .join("\n\n");
+                return { content: [{ type: "text", text }] };
+            }
+            case "get_repo_root": {
+                const cwd = resolve(aiDir, "..");
+                const root = getRepoRoot(cwd);
+                return {
+                    content: [{ type: "text", text: root ?? "null (not a git repository)" }],
+                };
+            }
+            case "validate_context": {
+                const gitDiff = args.git_diff;
+                if (typeof gitDiff !== "string" || !gitDiff.trim()) {
+                    throw new McpError(ErrorCode.InvalidParams, "git_diff is required and must be a non-empty string.");
+                }
+                const harnessPath = join(aiDir, "temp/harness.json");
+                if (!existsSync(harnessPath)) {
+                    return {
+                        content: [{ type: "text", text: "No harness.json found. Run generate_harness to create one, or initialize with --full." }],
+                    };
+                }
+                let rules;
+                try {
+                    const harnessRaw = await readFile(harnessPath, "utf-8");
+                    rules = JSON.parse(harnessRaw);
+                }
+                catch {
+                    throw new McpError(ErrorCode.InternalError, "Failed to parse harness.json. Run `ai-memory generate-harness` to regenerate.");
+                }
+                const repoRoot = getRepoRoot(resolve(aiDir, ".."));
+                const { violations, audit } = await validateDiff(gitDiff, rules, aiDir, repoRoot);
+                const timestamp = new Date().toISOString();
+                const harnessVersion = "1.0";
+                if (violations.length === 0) {
+                    const auditLines = audit.map((a) => {
+                        const icon = a.status === "passed" ? "✓" : a.status === "skipped" ? "○" : "✗";
+                        return `  ${icon} [P0] ${a.rule_id} (${a.path}) — ${a.status}`;
+                    });
+                    const cert = [
+                        "═══ Stability Certificate ═══",
+                        `Status: PASSED`,
+                        `Harness: ${harnessVersion} | ${timestamp}`,
+                        `repo_root: ${repoRoot ?? "null"}`,
+                        "",
+                        "Audit log:",
+                        ...auditLines,
+                        "",
+                        "Stability Surface is 100% compliant with active [P0] constraints.",
+                    ].join("\n");
+                    return { content: [{ type: "text", text: cert }] };
+                }
+                // Hard error on P0 violations
+                const p0Violations = violations.filter((v) => v.severity === "P0");
+                if (p0Violations.length > 0) {
+                    const report = [
+                        "═══ Constraint Violation Report ═══",
+                        `Status: FAILED`,
+                        `Harness: ${harnessVersion} | ${timestamp}`,
+                        `repo_root: ${repoRoot ?? "null"}`,
+                        "",
+                        `[HARD BLOCK] ${p0Violations.length} P0 constraint violation(s):`,
+                        "",
+                        ...p0Violations.map((v) => `• ${v.rule_id}: ${v.message}`),
+                    ].join("\n");
+                    throw new McpError(ErrorCode.InvalidRequest, report);
+                }
+                const text = violations
+                    .map((v) => `• [${v.severity}] ${v.rule_id}: ${v.message}`)
+                    .join("\n");
+                return { content: [{ type: "text", text: `Constraint warnings:\n\n${text}` }], isError: true };
+            }
+            case "validate_schema": {
+                const entry = args.entry;
+                if (!entry || typeof entry !== "object") {
+                    throw new McpError(ErrorCode.InvalidParams, "entry is required and must be an object.");
+                }
+                const errors = validateEntrySchema(entry);
+                if (errors.length === 0) {
+                    return { content: [{ type: "text", text: "✓ Schema valid." }] };
+                }
+                throw new McpError(ErrorCode.InvalidParams, `Schema validation failed:\n\n${errors.map((e) => `• ${e}`).join("\n")}`);
+            }
+            case "commit_memory": {
+                const memPath = args.path;
+                const memContent = args.content;
+                if (typeof memPath !== "string" || !memPath.trim()) {
+                    throw new McpError(ErrorCode.InvalidParams, "path is required and must be a non-empty string.");
+                }
+                if (typeof memContent !== "string") {
+                    throw new McpError(ErrorCode.InvalidParams, "content is required and must be a string.");
+                }
+                const append = args.append ?? true;
+                const sessionId = (typeof args.session_id === "string" && args.session_id) || generateSessionId();
+                // Check immutability (reads frontmatter for IDENTITY.md/PROJECT_STATUS.md)
+                if (await isImmutable(memPath, aiDir)) {
+                    const reason = FRONTMATTER_CONTROLLED.includes(memPath)
+                        ? `${memPath} is immutable (set \`writable: true\` in its frontmatter to allow AI writes).`
+                        : `${memPath} is in a structurally immutable path (${ALWAYS_IMMUTABLE.join(", ")}).`;
+                    throw new McpError(ErrorCode.InvalidRequest, reason);
+                }
+                const fullPath = assertPathWithinAiDir(aiDir, memPath);
+                // Claim-based locking for multi-agent safety
+                await acquireClaim(aiDir, memPath, sessionId);
+                try {
+                    await mkdir(dirname(fullPath), { recursive: true });
+                    // Session-attributed write header for traceability
+                    const header = `<!-- session:${sessionId} at:${new Date().toISOString()} -->`;
+                    if (append && existsSync(fullPath)) {
+                        const existing = await readFile(fullPath, "utf-8");
+                        await writeFile(fullPath, existing.trimEnd() + "\n\n" + header + "\n" + memContent);
+                    }
+                    else {
+                        await writeFile(fullPath, header + "\n" + memContent);
+                    }
+                }
+                finally {
+                    await releaseClaim(aiDir, memPath);
+                }
+                return { content: [{ type: "text", text: `✓ Written to ${memPath} (session: ${sessionId})` }] };
+            }
+            case "generate_harness": {
+                const entries = await readP0Entries(aiDir);
+                const rules = compileHarnessRules(entries);
+                const tests = generateRuleTests(entries);
+                const tempDir = join(aiDir, "temp");
+                await mkdir(tempDir, { recursive: true });
+                await writeFile(join(tempDir, "harness.json"), JSON.stringify(rules, null, 2));
+                if (tests.length > 0) {
+                    const testsDir = join(tempDir, "rule-tests");
+                    await mkdir(testsDir, { recursive: true });
+                    await writeFile(join(testsDir, "tests.json"), JSON.stringify(tests, null, 2));
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `✓ Harness generated: ${rules.length} rule(s) compiled from ${entries.length} [P0] entries.\n${tests.length > 0 ? `${tests.length} rule test(s) written to temp/rule-tests/tests.json` : "No rule tests found — add **Should trigger:** and **Should not trigger:** examples to [P0] entries."}`,
+                        },
+                    ],
+                };
+            }
+            case "get_open_items": {
+                const openItemsPath = join(aiDir, "sessions/open-items.md");
+                try {
+                    const content = await readFile(openItemsPath, "utf-8");
+                    return { content: [{ type: "text", text: content }] };
+                }
+                catch {
+                    return { content: [{ type: "text", text: "No open-items.md found. Initialize with `ai-memory init`." }] };
+                }
+            }
+            case "get_memory": {
+                const topic = args.topic;
+                if (typeof topic !== "string" || !topic.trim()) {
+                    throw new McpError(ErrorCode.InvalidParams, "topic is required and must be a non-empty string.");
+                }
+                const mode = getSearchMode();
+                let resp;
+                let fallbackNote = "";
+                try {
+                    resp = await hybridSearch(aiDir, topic, { mode, limit: 5 });
+                }
+                catch (err) {
+                    if (mode !== "keyword") {
+                        resp = await hybridSearch(aiDir, topic, { mode: "keyword", limit: 5 });
+                        fallbackNote =
+                            "Note: Hybrid/semantic search failed. Using keyword-only. Set AI_SEARCH=keyword or AI_SEARCH_WASM=1.\n\n";
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+                const { results, backend } = resp;
+                if (results.length === 0) {
+                    return { content: [{ type: "text", text: `No memory found for topic: ${topic}` }] };
+                }
+                const backendLabel = backend === "keyword" ? "Keyword-only" : backend === "native" ? "Hybrid (Native)" : "Hybrid (WASM)";
+                const text = fallbackNote + `Search backend: ${backendLabel}\n\nMemory for "${topic}":\n\n` +
+                    results
+                        .map((r) => `**${r.file}**: ${r.excerpt}`)
+                        .join("\n\n");
+                return { content: [{ type: "text", text }] };
+            }
+            case "prune_memory": {
+                const dryRun = args.dry_run ?? true;
+                const memDir = join(aiDir, "memory");
+                const candidates = [];
+                // Find [DEPRECATED] entries
+                if (existsSync(memDir)) {
+                    const files = await readdir(memDir);
+                    for (const file of files) {
+                        if (!file.endsWith(".md"))
+                            continue;
+                        const content = await readFile(join(memDir, file), "utf-8");
+                        const deprecatedMatches = content.match(/### \[P[0-2]\].+\[DEPRECATED\]/g);
+                        if (deprecatedMatches) {
+                            candidates.push(`${file}: ${deprecatedMatches.length} deprecated entry/entries`);
+                        }
+                    }
+                }
+                if (candidates.length === 0) {
+                    return { content: [{ type: "text", text: "No candidates for pruning found." }] };
+                }
+                const report = candidates.map((c) => `• ${c}`).join("\n");
+                if (dryRun) {
+                    return {
+                        content: [
+                            { type: "text", text: `Prune candidates (dry run — no changes made):\n\n${report}\n\nRun with dry_run: false to archive these entries.` },
+                        ],
+                    };
+                }
+                // Actual prune: move deprecated entries to sessions/archive
+                // (simplified: flag for manual review)
+                return {
+                    content: [
+                        { type: "text", text: `Flagged for archiving:\n\n${report}\n\nReview and move to sessions/archive/ manually, or run \`ai-memory prune\` from the CLI.` },
+                    ],
+                };
+            }
+            case "get_evals": {
+                const evalPath = join(aiDir, "temp/eval-report.json");
+                try {
+                    const content = await readFile(evalPath, "utf-8");
+                    return { content: [{ type: "text", text: content }] };
+                }
+                catch {
+                    return { content: [{ type: "text", text: "No eval report found. Run `ai-memory eval` to generate one." }] };
+                }
+            }
+            // ─── Autoresearch collaboration handlers ─────────────────────────────
+            case "claim_task": {
+                const taskDesc = args.task_description;
+                if (typeof taskDesc !== "string" || !taskDesc.trim()) {
+                    throw new McpError(ErrorCode.InvalidParams, "task_description is required.");
+                }
+                const sessionId = (typeof args.session_id === "string" && args.session_id) || generateSessionId();
+                let sourcePath = typeof args.source === "string" && args.source
+                    ? args.source
+                    : "sessions/open-items.md";
+                // Validate source path stays within aiDir
+                const sourceFullPath = assertPathWithinAiDir(aiDir, sourcePath);
+                let sourceContent = "";
+                try {
+                    sourceContent = await readFile(sourceFullPath, "utf-8");
+                }
+                catch { /* no file yet */ }
+                // Find matching unclaimed task line (supports: - [ ], - TODO, - task, numbered lists)
+                const taskTerms = taskDesc.toLowerCase().split(/\s+/).filter(Boolean);
+                const lines = sourceContent.split("\n");
+                let matchedLine = -1;
+                let bestScore = 0;
+                const taskLinePattern = /^(\s*[-*]\s*\[[ ]\]|\s*[-*]\s|\s*\d+\.\s)/;
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i];
+                    if (!taskLinePattern.test(line))
+                        continue;
+                    // Skip already claimed or completed tasks
+                    if (line.includes("[CLAIMED:") || line.match(/\[x\]/i))
+                        continue;
+                    const lower = line.toLowerCase();
+                    const score = taskTerms.filter((t) => lower.includes(t)).length;
+                    if (score > bestScore) {
+                        bestScore = score;
+                        matchedLine = i;
+                    }
+                }
+                // Claim the task: mark it in-progress with session_id
+                if (matchedLine >= 0 && bestScore >= Math.min(2, taskTerms.length)) {
+                    const original = lines[matchedLine];
+                    // Mark claimed — preserve original format, append claim marker
+                    lines[matchedLine] = original.replace("- [ ]", "- [~]") + ` [CLAIMED:${sessionId}]`;
+                    await writeFile(sourceFullPath, lines.join("\n"));
+                    return { content: [{ type: "text", text: `✓ Claimed task from ${sourcePath} (session ${sessionId}):\n${lines[matchedLine]}` }] };
+                }
+                // No match in source file — add as new claimed item to open-items.md
+                const openItemsPath = join(aiDir, "sessions/open-items.md");
+                let openItems = "";
+                try {
+                    openItems = await readFile(openItemsPath, "utf-8");
+                }
+                catch { }
+                const newItem = `- [~] ${taskDesc} [CLAIMED:${sessionId}]`;
+                const updated = openItems.includes("## Open")
+                    ? openItems.replace("## Open", `## Open\n\n${newItem}`)
+                    : openItems + `\n\n## Open\n\n${newItem}`;
+                await mkdir(dirname(openItemsPath), { recursive: true });
+                await writeFile(openItemsPath, updated);
+                return { content: [{ type: "text", text: `✓ No match in ${sourcePath}. Created and claimed new task in open-items.md (session ${sessionId}):\n${newItem}` }] };
+            }
+            case "publish_result": {
+                const summary = args.summary;
+                const outcome = args.outcome;
+                if (typeof summary !== "string" || !summary.trim()) {
+                    throw new McpError(ErrorCode.InvalidParams, "summary is required.");
+                }
+                if (typeof outcome !== "string" || !["success", "failure", "partial"].includes(outcome)) {
+                    throw new McpError(ErrorCode.InvalidParams, "outcome must be 'success', 'failure', or 'partial'.");
+                }
+                const learnings = typeof args.learnings === "string" ? args.learnings : "";
+                const sessionId = (typeof args.session_id === "string" && args.session_id) || generateSessionId();
+                const date = new Date().toISOString().slice(0, 10);
+                const icon = outcome === "success" ? "✓" : outcome === "failure" ? "✗" : "~";
+                // Write to thread-archive
+                const archivePath = join(aiDir, "sessions/archive/thread-archive.md");
+                const entry = `[${date}] [${icon} ${outcome}] ${summary}${learnings ? ` — Learnings: ${learnings}` : ""} (session:${sessionId})`;
+                try {
+                    const existing = await readFile(archivePath, "utf-8");
+                    await writeFile(archivePath, existing.trimEnd() + "\n" + entry + "\n");
+                }
+                catch {
+                    await mkdir(join(aiDir, "sessions/archive"), { recursive: true });
+                    await writeFile(archivePath, entry + "\n");
+                }
+                // If task was claimed, mark it done in open-items
+                const openItemsPath = join(aiDir, "sessions/open-items.md");
+                try {
+                    let openItems = await readFile(openItemsPath, "utf-8");
+                    // Find lines claimed by this session and mark complete/failed
+                    const marker = outcome === "success" ? "- [x]" : "- [ ]";
+                    openItems = openItems.replace(new RegExp(`^- \\[~\\] (.+?)\\[CLAIMED:${sessionId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\]`, "gm"), (_, task) => `${marker} ${task.trim()} [${outcome}:${date}]`);
+                    await writeFile(openItemsPath, openItems);
+                }
+                catch { /* no open-items yet */ }
+                return { content: [{ type: "text", text: `✓ Result published to thread-archive:\n${entry}` }] };
+            }
+            case "sync_memory": {
+                const commitMsg = typeof args.message === "string" && args.message
+                    ? args.message
+                    : `ai-memory: auto-sync ${new Date().toISOString().slice(0, 19)}`;
+                const shouldPush = args.push === true;
+                const { execFileSync } = await import("child_process");
+                const execOpts = { cwd: resolve(aiDir, ".."), encoding: "utf-8", timeout: 30000 };
+                try {
+                    execFileSync("git", ["rev-parse", "--git-dir"], execOpts);
+                }
+                catch {
+                    return { content: [{ type: "text", text: "Not a git repository. sync_memory requires git. Commit .ai/ manually." }] };
+                }
+                try {
+                    execFileSync("git", ["add", ".ai/"], execOpts);
+                    const status = execFileSync("git", ["diff", "--cached", "--name-only"], execOpts).trim();
+                    if (!status) {
+                        return { content: [{ type: "text", text: "No .ai/ changes to sync." }] };
+                    }
+                    execFileSync("git", ["commit", "-m", commitMsg], execOpts);
+                    let result = `✓ Committed .ai/ changes: ${commitMsg}\nFiles: ${status.split("\n").length} file(s)`;
+                    if (shouldPush) {
+                        try {
+                            execFileSync("git", ["push"], execOpts);
+                            result += "\n✓ Pushed to remote.";
+                        }
+                        catch (pushErr) {
+                            const msg = pushErr instanceof Error ? pushErr.message : String(pushErr);
+                            result += `\n⚠ Push failed: ${msg}\nChanges are committed locally. Push manually.`;
+                        }
+                    }
+                    return { content: [{ type: "text", text: result }] };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    throw new McpError(ErrorCode.InternalError, `sync_memory failed: ${msg}`);
+                }
+            }
+            case "get_doc_path": {
+                const docType = args.type;
+                if (typeof docType !== "string" || !docType.trim()) {
+                    throw new McpError(ErrorCode.InvalidParams, "type is required.");
+                }
+                const projectRoot = resolve(aiDir, "..");
+                const schema = await loadDocsSchema(projectRoot);
+                if (!schema) {
+                    return { content: [{ type: "text", text: "No .ai/docs-schema.json found. Run `ai-memory init --full` to create one." }] };
+                }
+                const slug = typeof args.slug === "string" ? args.slug : undefined;
+                let path;
+                try {
+                    path = getDocPath(schema, docType, slug);
+                }
+                catch (err) {
+                    if (err instanceof Error && err.message.includes("slug")) {
+                        throw new McpError(ErrorCode.InvalidParams, err.message);
+                    }
+                    throw err;
+                }
+                if (!path) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Unknown doc type "${docType}". Available: ${Object.keys(schema.docTypes).join(", ")}`,
+                            },
+                        ],
+                    };
+                }
+                return { content: [{ type: "text", text: path }] };
+            }
+            case "validate_doc_placement": {
+                const projectRoot = resolve(aiDir, "..");
+                const schema = await loadDocsSchema(projectRoot);
+                if (!schema) {
+                    return { content: [{ type: "text", text: "valid: true (no schema)" }] };
+                }
+                const pathsToCheck = [];
+                if (typeof args.path === "string" && args.path)
+                    pathsToCheck.push(args.path);
+                if (Array.isArray(args.paths))
+                    pathsToCheck.push(...args.paths.filter((p) => typeof p === "string"));
+                if (pathsToCheck.length === 0) {
+                    return { content: [{ type: "text", text: "Provide path or paths to validate." }] };
+                }
+                const allErrors = [];
+                for (const p of pathsToCheck) {
+                    const result = validateDocPlacement(schema, p, projectRoot);
+                    if (!result.valid)
+                        allErrors.push(...result.errors.map((e) => `${p}: ${e}`));
+                }
+                const valid = allErrors.length === 0;
+                const text = valid
+                    ? `valid: true (${pathsToCheck.length} path(s) OK)`
+                    : `valid: false\n${allErrors.join("\n")}`;
+                return { content: [{ type: "text", text }] };
+            }
+            case "list_doc_types": {
+                const projectRoot = resolve(aiDir, "..");
+                const schema = await loadDocsSchema(projectRoot);
+                if (!schema) {
+                    return { content: [{ type: "text", text: "No .ai/docs-schema.json found." }] };
+                }
+                const types = listDocTypes(schema);
+                const text = types.map((t) => `- ${t.type}: ${t.path}/${t.pattern}`).join("\n");
+                return { content: [{ type: "text", text: text || "No doc types defined." }] };
+            }
+            default:
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+    });
+}
+//# sourceMappingURL=tools.js.map