@praneeth_54/agentdoctor 1.1.1 → 2.0.0

package/dist/intelligence/graph/build.js

@@ -0,0 +1,215 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import ts from "typescript";
+import { resolveRepoRoot, toPosixRelative } from "../../utils/path.js";
+import { buildRepositoryGraph } from "../../platform/graph/build.js";
+import { CONTRACTS_VERSION } from "../../contracts/index.js";
+function nodeId(kind, key) {
+    return `${kind}:${createHash("sha1").update(key).digest("hex").slice(0, 12)}`;
+}
+async function listTsFiles(root, limit = 400) {
+    const out = [];
+    const skip = new Set(["node_modules", ".git", "dist", "coverage", ".agentdoctor", "vendor"]);
+    async function walk(dir) {
+        if (out.length >= limit)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (skip.has(e.name))
+                continue;
+            const abs = path.join(dir, e.name);
+            if (e.isSymbolicLink())
+                continue;
+            if (e.isDirectory()) {
+                await walk(abs);
+                continue;
+            }
+            if (/\.(ts|tsx|mts|cts)$/i.test(e.name) && !e.name.endsWith(".d.ts")) {
+                out.push(abs);
+            }
+        }
+    }
+    await walk(root);
+    return out.sort();
+}
+/**
+ * TypeScript compiler API based graph enrichment.
+ * Falls back to regex graph when mode=regex or on failure.
+ */
+export async function buildIntelligenceGraph(options) {
+    const root = resolveRepoRoot(options.root);
+    const mode = options.mode ?? "auto";
+    if (mode === "regex") {
+        const g = await buildRepositoryGraph(root);
+        return { ...g, builder: "regex", astFilesParsed: 0 };
+    }
+    try {
+        const files = await listTsFiles(root);
+        if (files.length === 0) {
+            const g = await buildRepositoryGraph(root);
+            return {
+                ...g,
+                builder: "regex",
+                astFilesParsed: 0,
+                limitations: [
+                    ...g.limitations,
+                    "No TypeScript sources found for AST builder; used regex fallback",
+                ],
+            };
+        }
+        const program = ts.createProgram({
+            rootNames: files,
+            options: {
+                allowJs: false,
+                target: ts.ScriptTarget.ES2022,
+                module: ts.ModuleKind.ESNext,
+                moduleResolution: ts.ModuleResolutionKind.Bundler,
+                skipLibCheck: true,
+                noEmit: true,
+            },
+        });
+        const nodes = [];
+        const edges = [];
+        const seen = new Set();
+        const pushNode = (n) => {
+            if (seen.has(n.id))
+                return;
+            seen.add(n.id);
+            nodes.push(n);
+        };
+        for (const sf of program.getSourceFiles()) {
+            if (sf.isDeclarationFile)
+                continue;
+            if (!files.includes(sf.fileName))
+                continue;
+            const rel = toPosixRelative(root, sf.fileName);
+            const fileId = nodeId("file", rel);
+            pushNode({ id: fileId, kind: "file", label: path.basename(rel), path: rel });
+            const visit = (node) => {
+                if (ts.isFunctionDeclaration(node) && node.name) {
+                    const name = node.name.text;
+                    pushNode({
+                        id: nodeId("function", `${rel}:${name}`),
+                        kind: "function",
+                        label: name,
+                        path: rel,
+                        meta: { parser: "typescript-ast", analysisVersion: CONTRACTS_VERSION },
+                    });
+                }
+                if (ts.isClassDeclaration(node) && node.name) {
+                    const name = node.name.text;
+                    const classId = nodeId("class", `${rel}:${name}`);
+                    pushNode({
+                        id: classId,
+                        kind: "class",
+                        label: name,
+                        path: rel,
+                        meta: { parser: "typescript-ast" },
+                    });
+                    if (node.heritageClauses) {
+                        for (const h of node.heritageClauses) {
+                            for (const t of h.types) {
+                                const label = t.expression.getText(sf);
+                                const toId = nodeId("dependency", `${rel}->${label}`);
+                                pushNode({ id: toId, kind: "dependency", label, path: rel });
+                                edges.push({
+                                    id: nodeId("edge", `${classId}->${toId}:${h.token}`),
+                                    from: classId,
+                                    to: toId,
+                                    kind: h.token === ts.SyntaxKind.ExtendsKeyword ? "extends" : "implements",
+                                    evidence: "verified",
+                                });
+                            }
+                        }
+                    }
+                }
+                if (ts.isInterfaceDeclaration(node) && node.name) {
+                    pushNode({
+                        id: nodeId("interface", `${rel}:${node.name.text}`),
+                        kind: "module",
+                        label: node.name.text,
+                        path: rel,
+                        meta: { symbolKind: "interface", parser: "typescript-ast" },
+                    });
+                }
+                if (ts.isImportDeclaration(node) &&
+                    node.moduleSpecifier &&
+                    ts.isStringLiteral(node.moduleSpecifier)) {
+                    const spec = node.moduleSpecifier.text;
+                    const toId = nodeId("dependency", `${rel}->${spec}`);
+                    pushNode({
+                        id: toId,
+                        kind: "dependency",
+                        label: spec,
+                        path: rel,
+                        meta: { specifier: spec, parser: "typescript-ast" },
+                    });
+                    edges.push({
+                        id: nodeId("edge", `${fileId}->${toId}`),
+                        from: fileId,
+                        to: toId,
+                        kind: "imports",
+                        evidence: spec.startsWith(".") ? "verified" : "inferred",
+                    });
+                }
+                if (ts.isCallExpression(node) &&
+                    ts.isIdentifier(node.expression) &&
+                    node.expression.text.length > 1) {
+                    const callee = node.expression.text;
+                    const toId = nodeId("function", `call:${rel}:${callee}`);
+                    pushNode({
+                        id: toId,
+                        kind: "function",
+                        label: callee,
+                        path: rel,
+                        meta: { callSite: true, parser: "typescript-ast" },
+                    });
+                    edges.push({
+                        id: nodeId("edge", `${fileId}->call:${callee}:${node.getStart(sf)}`),
+                        from: fileId,
+                        to: toId,
+                        kind: "calls",
+                        evidence: "inferred",
+                    });
+                }
+                ts.forEachChild(node, visit);
+            };
+            visit(sf);
+        }
+        nodes.sort((a, b) => a.id.localeCompare(b.id));
+        edges.sort((a, b) => a.id.localeCompare(b.id));
+        return {
+            root,
+            generatedAt: new Date().toISOString(),
+            nodes,
+            edges,
+            builder: "typescript-ast",
+            astFilesParsed: files.length,
+            limitations: [
+                "TypeScript AST builder uses the TypeScript compiler API for .ts/.tsx only",
+                "Cross-file call resolution is identifier-based (not full type-checker binding)",
+                "Non-TypeScript languages fall back to regex graph when requested via auto+empty TS set",
+                `analysisVersion=${CONTRACTS_VERSION}`,
+            ],
+        };
+    }
+    catch (error) {
+        const g = await buildRepositoryGraph(root);
+        return {
+            ...g,
+            builder: "regex",
+            astFilesParsed: 0,
+            limitations: [
+                ...g.limitations,
+                `TypeScript AST builder failed; regex fallback used (${error instanceof Error ? error.message : String(error)})`,
+            ],
+        };
+    }
+}

package/dist/knowledge/store.d.ts

@@ -0,0 +1,25 @@
+import type { KnowledgeRecordContract, KnowledgeStatus } from "../contracts/index.js";
+import type { StorageProvider } from "../contracts/index.js";
+export declare function createKnowledgeRecord(options: {
+    root: string;
+    title: string;
+    content: string;
+    status?: KnowledgeStatus;
+    owner?: string;
+    storage?: StorageProvider;
+}): Promise<KnowledgeRecordContract>;
+export declare function transitionKnowledge(options: {
+    root: string;
+    id: string;
+    to: KnowledgeStatus;
+    by?: string;
+    note?: string;
+    storage?: StorageProvider;
+}): Promise<KnowledgeRecordContract>;
+export declare function listKnowledge(root: string, storage?: StorageProvider): Promise<KnowledgeRecordContract[]>;
+/** Authoritative retrieval abstains when no approved record matches. */
+export declare function retrieveAuthoritative(records: KnowledgeRecordContract[], query: string): {
+    record: KnowledgeRecordContract | null;
+    abstain: boolean;
+    reason: string;
+};

package/dist/knowledge/store.js

@@ -0,0 +1,91 @@
+import { createHash, randomUUID } from "node:crypto";
+import { FilesystemStorageProvider } from "../storage/provider.js";
+import { resolveRepoRoot } from "../utils/path.js";
+function kid(title) {
+    return `know_${createHash("sha1").update(title).digest("hex").slice(0, 12)}`;
+}
+export async function createKnowledgeRecord(options) {
+    const storage = options.storage ?? new FilesystemStorageProvider(options.root, ".agentdoctor/knowledge");
+    const record = {
+        id: kid(`${options.title}:${randomUUID()}`),
+        title: options.title,
+        content: options.content,
+        status: options.status ?? "draft",
+        owner: options.owner ?? null,
+        approver: null,
+        version: "1",
+        evidence: [
+            {
+                id: "ev_create",
+                kind: "proposed",
+                detail: "Created via knowledge governance API",
+            },
+        ],
+        relatedRepositoryId: resolveRepoRoot(options.root),
+        changeHistory: [
+            {
+                at: new Date().toISOString(),
+                note: "created",
+                to: options.status ?? "draft",
+                ...(options.owner ? { by: options.owner } : {}),
+            },
+        ],
+    };
+    await storage.set(`records/${record.id}.json`, `${JSON.stringify(record, null, 2)}\n`);
+    return record;
+}
+export async function transitionKnowledge(options) {
+    const storage = options.storage ?? new FilesystemStorageProvider(options.root, ".agentdoctor/knowledge");
+    const raw = await storage.get(`records/${options.id}.json`);
+    if (!raw)
+        throw new Error(`knowledge record not found: ${options.id}`);
+    const record = JSON.parse(raw);
+    const from = record.status;
+    // Authority: only pending-review/draft/proposed can become approved via explicit transition
+    if (options.to === "approved" && !["draft", "proposed", "pending-review"].includes(from)) {
+        throw new Error(`cannot approve from status ${from}`);
+    }
+    record.status = options.to;
+    if (options.to === "approved") {
+        record.approver = options.by ?? "local-approver";
+        record.effectiveAt = new Date().toISOString();
+    }
+    record.changeHistory.push({
+        at: new Date().toISOString(),
+        note: options.note ?? `transition ${from} -> ${options.to}`,
+        from,
+        to: options.to,
+        ...(options.by ? { by: options.by } : {}),
+    });
+    record.version = String(Number(record.version || "1") + 1);
+    await storage.set(`records/${record.id}.json`, `${JSON.stringify(record, null, 2)}\n`);
+    return record;
+}
+export async function listKnowledge(root, storage) {
+    const store = storage ?? new FilesystemStorageProvider(root, ".agentdoctor/knowledge");
+    const keys = await store.list("records");
+    const out = [];
+    for (const key of keys) {
+        if (!key.endsWith(".json"))
+            continue;
+        const raw = await store.get(key.startsWith("records/") ? key : `records/${key}`);
+        if (!raw)
+            continue;
+        out.push(JSON.parse(raw));
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Authoritative retrieval abstains when no approved record matches. */
+export function retrieveAuthoritative(records, query) {
+    const q = query.toLowerCase();
+    const approved = records.filter((r) => r.status === "approved" &&
+        (r.title.toLowerCase().includes(q) || r.content.toLowerCase().includes(q)));
+    if (approved.length === 0) {
+        return {
+            record: null,
+            abstain: true,
+            reason: "No approved authoritative knowledge matched the query",
+        };
+    }
+    return { record: approved[0], abstain: false, reason: "approved match" };
+}

package/dist/mcp/agentdoctor/server.d.ts

@@ -0,0 +1,16 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { BrainMcpSession } from "../brain/session.js";
+export interface StartAgentDoctorMcpOptions {
+    root: string;
+    buildIfMissing?: boolean;
+}
+/**
+ * Combined AgentDoctor MCP server: preserves all Brain tool names and adds
+ * intelligence tools. No arbitrary shell execution; policy_evaluate is evaluate-only.
+ */
+export declare function startAgentDoctorMcpServer(options: StartAgentDoctorMcpOptions): Promise<{
+    server: Server;
+    session: BrainMcpSession;
+    root: string;
+}>;
+export declare function runAgentDoctorMcpStdio(options: StartAgentDoctorMcpOptions): Promise<void>;

package/dist/mcp/agentdoctor/server.js

@@ -0,0 +1,67 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { PACKAGE_VERSION } from "../../constants.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { BrainMcpSession } from "../brain/session.js";
+import { BRAIN_MCP_TOOL_NAMES, invokeBrainMcpTool, listBrainMcpTools, } from "../brain/tools/registry.js";
+import { INTELLIGENCE_MCP_TOOL_NAMES, invokeIntelligenceMcpTool, listIntelligenceMcpTools, } from "../intelligence/registry.js";
+/**
+ * Combined AgentDoctor MCP server: preserves all Brain tool names and adds
+ * intelligence tools. No arbitrary shell execution; policy_evaluate is evaluate-only.
+ */
+export async function startAgentDoctorMcpServer(options) {
+    const root = resolveRepoRoot(options.root);
+    const session = new BrainMcpSession({
+        root,
+        buildIfMissing: options.buildIfMissing !== false,
+    });
+    await session.initialize();
+    const brainNames = new Set(BRAIN_MCP_TOOL_NAMES);
+    const intelNames = new Set(INTELLIGENCE_MCP_TOOL_NAMES);
+    const server = new Server({
+        name: "agentdoctor",
+        version: PACKAGE_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [...listBrainMcpTools(), ...listIntelligenceMcpTools()],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const args = (request.params.arguments ?? {});
+        let structured;
+        let isError = false;
+        if (brainNames.has(name)) {
+            const result = await invokeBrainMcpTool(session, name, args);
+            structured = result.structured;
+            isError = result.isError;
+        }
+        else if (intelNames.has(name)) {
+            const result = await invokeIntelligenceMcpTool(root, name, args);
+            structured = result.structured;
+            isError = result.isError;
+        }
+        else {
+            structured = {
+                ok: false,
+                error: { code: "invalid_argument", message: `unknown tool: ${name}` },
+            };
+            isError = true;
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(structured) }],
+            structuredContent: structured,
+            isError,
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    return { server, session, root };
+}
+export async function runAgentDoctorMcpStdio(options) {
+    await startAgentDoctorMcpServer(options);
+}

package/dist/mcp/brain/session.js

@@ -1,4 +1,4 @@
-import { LocalBrainStore, } from "../../core/understanding/brain/index.js";
+import { LocalBrainStore, redactBrainForStorage, } from "../../core/understanding/brain/index.js";
 import { compileProjectBrain } from "./compile.js";
 import { BrainMcpError } from "./errors.js";
 import { resolveProjectRoot } from "./security/root.js";
@@ -32,8 +32,8 @@ export class BrainMcpSession {
             throw new BrainMcpError("brain_corrupt", message);
         }
         if (loaded) {
-            this.brain = loaded;
-            this.log(`agentdoctor brain-mcp: loaded snapshot ${loaded.snapshot.id} from ${this.root}`);
+            this.brain = redactBrainForStorage(loaded);
+            this.log(`agentdoctor brain-mcp: loaded snapshot ${this.brain.snapshot.id} from ${this.root}`);
             return;
         }
         if (!this.buildIfMissing) {
@@ -84,15 +84,15 @@ export class BrainMcpSession {
                     : new BrainMcpError("brain_corrupt", message || "failed to save snapshot");
             }
         }
-        this.brain = brain;
-        return brain;
+        this.brain = redactBrainForStorage(brain);
+        return this.brain;
     }
     async loadSnapshot(snapshotId) {
         const store = this.getStore();
         try {
             const brain = await store.loadSnapshot(snapshotId);
-            this.brain = brain;
-            return brain;
+            this.brain = redactBrainForStorage(brain);
+            return this.brain;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "failed to load snapshot";

package/dist/mcp/intelligence/handlers.d.ts

@@ -0,0 +1,11 @@
+export declare function handleRepoOverview(rootInput: string): Promise<unknown>;
+export declare function handleCodebaseSearch(rootInput: string, args: Record<string, unknown>): Promise<unknown>;
+export declare function handleSymbolLookup(rootInput: string, args: Record<string, unknown>): Promise<unknown>;
+export declare function handleDependencyLookup(rootInput: string, args: Record<string, unknown>): Promise<unknown>;
+export declare function handleCallGraphLookup(rootInput: string, args: Record<string, unknown>): Promise<unknown>;
+export declare function handleTestImpactTool(rootInput: string): Promise<unknown>;
+export declare function handleRefactorImpactTool(rootInput: string, args: Record<string, unknown>): Promise<unknown>;
+export declare function handleCodeHealthTool(rootInput: string): Promise<unknown>;
+export declare function handleArchitectureTool(rootInput: string): Promise<unknown>;
+export declare function handleKnowledgeTool(rootInput: string, args: Record<string, unknown>): Promise<unknown>;
+export declare function handlePolicyEvalTool(rootInput: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/intelligence/handlers.js

@@ -0,0 +1,175 @@
+import { buildC4Views } from "../../architecture/c4.js";
+import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
+import { analyzeGitIntelligence } from "../../intelligence/git/analyze.js";
+import { listKnowledge, retrieveAuthoritative } from "../../knowledge/store.js";
+import { analyzeRenameImpact, analyzeTestImpact, buildRepositoryGraph, evaluateAgentAction, } from "../../platform/index.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { CONTRACTS_VERSION } from "../../contracts/index.js";
+import { assertSafeRepoTarget } from "./path-safety.js";
+export async function handleRepoOverview(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const graph = await buildIntelligenceGraph({ root, mode: "auto" });
+    return {
+        ok: true,
+        contractsVersion: CONTRACTS_VERSION,
+        root,
+        builder: graph.builder,
+        nodeCount: graph.nodes.length,
+        edgeCount: graph.edges.length,
+        limitations: graph.limitations,
+    };
+}
+export async function handleCodebaseSearch(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const query = String(args.query ?? "")
+        .toLowerCase()
+        .trim();
+    if (!query) {
+        return { ok: false, error: { code: "invalid_argument", message: "query required" } };
+    }
+    const graph = await buildIntelligenceGraph({ root, mode: "auto" });
+    const hits = graph.nodes
+        .filter((n) => n.label.toLowerCase().includes(query) ||
+        n.id.toLowerCase().includes(query) ||
+        (n.path ?? "").toLowerCase().includes(query))
+        .slice(0, 50);
+    return {
+        ok: true,
+        query,
+        hits,
+        confidence: graph.builder === "typescript-ast" ? 0.85 : 0.55,
+        evidenceKind: graph.builder === "typescript-ast" ? "observed" : "inferred",
+        limitations: graph.limitations,
+    };
+}
+export async function handleSymbolLookup(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const name = String(args.name ?? "").trim();
+    if (!name) {
+        return { ok: false, error: { code: "invalid_argument", message: "name required" } };
+    }
+    const graph = await buildIntelligenceGraph({ root, mode: "auto" });
+    const matches = graph.nodes.filter((n) => (n.kind === "function" || n.kind === "class" || n.kind === "module") &&
+        (n.label === name || n.label.endsWith(`.${name}`)));
+    return {
+        ok: true,
+        name,
+        matches,
+        confidence: matches.length > 0 ? 0.8 : 0.2,
+        limitations: ["Import/call resolution is best-effort; unsupported languages omitted."],
+    };
+}
+export async function handleDependencyLookup(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const target = String(args.target ?? "").trim();
+    if (!target) {
+        return { ok: false, error: { code: "invalid_argument", message: "target required" } };
+    }
+    let safeRelative = null;
+    try {
+        safeRelative = assertSafeRepoTarget(root, target);
+    }
+    catch {
+        return {
+            ok: false,
+            error: { code: "path_escape", message: "path escapes repository root" },
+        };
+    }
+    const graph = await buildIntelligenceGraph({ root, mode: "auto" });
+    const lookupKeys = [target, safeRelative].filter((v) => Boolean(v));
+    const node = graph.nodes.find((n) => lookupKeys.includes(n.id) ||
+        (n.path !== undefined && lookupKeys.includes(n.path)) ||
+        lookupKeys.includes(n.label));
+    if (!node) {
+        return { ok: true, target, edges: [], limitations: ["Target not found in graph"] };
+    }
+    const edges = graph.edges.filter((e) => e.from === node.id || e.to === node.id);
+    return { ok: true, target: node, edges, confidence: 0.75 };
+}
+export async function handleCallGraphLookup(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const symbol = String(args.symbol ?? "").trim();
+    if (!symbol) {
+        return { ok: false, error: { code: "invalid_argument", message: "symbol required" } };
+    }
+    const graph = await buildIntelligenceGraph({ root, mode: "auto" });
+    const calls = graph.edges.filter((e) => e.kind === "calls" && (e.from.includes(symbol) || e.to.includes(symbol)));
+    return {
+        ok: true,
+        symbol,
+        calls,
+        confidence: graph.builder === "typescript-ast" ? 0.7 : 0.4,
+        limitations: ["Call edges may be incomplete for dynamic/dispatch patterns."],
+    };
+}
+export async function handleTestImpactTool(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const impact = await analyzeTestImpact(root);
+    return {
+        ok: true,
+        impact,
+        resultKind: impact.gitAvailable ? "graph-inferred" : "unknown",
+        limitations: ["Coverage-backed mapping requires external coverage data (not bundled)."],
+    };
+}
+export async function handleRefactorImpactTool(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const symbol = String(args.symbol ?? "").trim();
+    if (!symbol) {
+        return { ok: false, error: { code: "invalid_argument", message: "symbol required" } };
+    }
+    const graph = await buildRepositoryGraph(root);
+    const impact = await analyzeRenameImpact({ root, symbol, graph });
+    return { ok: true, impact };
+}
+export async function handleCodeHealthTool(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const report = await analyzeGitIntelligence(root);
+    return {
+        ok: true,
+        report,
+        methodDisclosure: report.hotspots[0]?.method ?? "see per-metric method fields",
+        limitations: report.limitations,
+    };
+}
+export async function handleArchitectureTool(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const graph = await buildIntelligenceGraph({ root, mode: "auto" });
+    const views = buildC4Views(graph);
+    return {
+        ok: true,
+        views,
+        label: "Inferred/proposed from graph evidence — not approved architecture facts",
+    };
+}
+export async function handleKnowledgeTool(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const list = await listKnowledge(root);
+    const query = String(args.query ?? "").trim();
+    if (!query) {
+        return { ok: true, records: list.filter((r) => r.status === "approved").slice(0, 50) };
+    }
+    const result = retrieveAuthoritative(list, query);
+    return { ok: true, ...result };
+}
+export async function handlePolicyEvalTool(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const command = String(args.command ?? "").trim();
+    if (!command) {
+        return { ok: false, error: { code: "invalid_argument", message: "command required" } };
+    }
+    const verdict = await evaluateAgentAction(root, {
+        actionId: `mcp_${Date.now()}`,
+        agentId: "agentdoctor-mcp",
+        timestamp: new Date().toISOString(),
+        type: "shell",
+        params: { command },
+        repositoryRoot: root,
+    });
+    return {
+        ok: true,
+        verdict,
+        executionResult: "not-executed",
+        notice: "Evaluate-only: AgentDoctor MCP does not execute shell commands.",
+    };
+}

package/dist/mcp/intelligence/path-safety.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Decode a single layer of URI encoding. Rejects malformed sequences by returning null.
+ */
+export declare function tryDecodeUriComponent(value: string): string | null;
+/**
+ * Validate a user-supplied repository-relative or in-repo target.
+ * Returns a normalized path relative to root (POSIX) when the target is path-like and safe,
+ * or null when the target is treated as a non-path identifier (graph id / label).
+ * Throws a safe Error (no outside path leakage) when a path-like target escapes the root.
+ */
+export declare function assertSafeRepoTarget(root: string, rawTarget: string): string | null;