@praneeth_54/agentdoctor 2.0.1 → 2.1.0

package/dist/agent/tools/execute.js

@@ -0,0 +1,355 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { handleArchitectureCheckTool, handleCallGraphLookup, handleCodebaseSearch, handleDependencyLookup, handleRefactorImpactTool, handleSymbolLookup, handleTestImpactTool, } from "../../mcp/intelligence/handlers.js";
+import { scan } from "../../core/scanner/scan.js";
+import { analyzeChanges } from "../../core/changes/analyze.js";
+import { discoverFiles } from "../../discovery/files.js";
+import { PathEscapeError, resolveSafeRepoPath } from "../../security/paths.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { redactSecrets } from "../../platform/security/redact.js";
+import { summarizeProjectForChat } from "../chat/project-summary.js";
+import { getToolSpec, riskForTool } from "./registry.js";
+import { createFileSafe, deleteFileSafe, editFileSafe } from "./write.js";
+import { inferTestArgv, runAgentCommand } from "./run.js";
+import { evaluateApproval } from "../approvals.js";
+import { modeBlocksToolCategory } from "../modes.js";
+import { assertWorkspacePathAccess } from "../../workspace/index.js";
+function asRecord(args) {
+    return args;
+}
+function str(args, key) {
+    const v = args[key];
+    return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+/**
+ * Execute an agent tool.
+ * Write/execute tools require explicit allowWrite/allowExecute (after human approval).
+ */
+export async function executeAgentTool(rootInput, call, options) {
+    const started = Date.now();
+    const root = resolveRepoRoot(rootInput);
+    const risk = riskForTool(call.name);
+    const spec = getToolSpec(call.name);
+    const fail = (code, message) => ({
+        callId: call.id,
+        name: call.name,
+        ok: false,
+        data: null,
+        error: { code, message },
+        risk,
+        durationMs: Date.now() - started,
+    });
+    const ok = (data) => ({
+        callId: call.id,
+        name: call.name,
+        ok: true,
+        data: redactDeep(data),
+        risk,
+        durationMs: Date.now() - started,
+    });
+    if (!spec)
+        return fail("unknown_tool", `Unknown tool: ${call.name}`);
+    if (modeBlocksToolCategory(options?.mode, spec.category)) {
+        return fail("mode_forbidden", `Mode ${options?.mode ?? "LEARN"} does not allow ${spec.category} tools (allowWrites=false). The model cannot override this.`);
+    }
+    if (spec.category === "write" || spec.category === "execute") {
+        const gate = evaluateApproval({ action: `tool:${call.name}`, risk: risk, toolName: call.name }, { approvedByHuman: options?.approvedByHuman === true });
+        if (gate.needsHumanApproval) {
+            return fail("approval_required", gate.reason);
+        }
+    }
+    if (spec.category === "write" && !options?.allowWrite) {
+        return fail("not_enabled", "Write tools require allowWrite after human approval.");
+    }
+    if (spec.category === "execute" && !options?.allowExecute) {
+        return fail("not_enabled", "Execute tools require allowExecute after human approval.");
+    }
+    const ensureWorkspace = (absPath) => {
+        // Repo-root isolation is already enforced by resolveSafeRepoPath.
+        // Workspace gate applies only when a multi-root WorkspaceModel is provided
+        // (avoids false denies from /var vs /private/var when workspace is null).
+        if (options?.workspace == null)
+            return null;
+        const access = assertWorkspacePathAccess({
+            workspace: options.workspace,
+            operationRoot: root,
+            targetPath: absPath,
+        });
+        if (!access.allowed) {
+            return fail("workspace_denied", access.reason);
+        }
+        return null;
+    };
+    try {
+        switch (call.name) {
+            case "read_file": {
+                const rel = str(call.arguments, "path");
+                if (!rel)
+                    return fail("invalid_argument", "path required");
+                let abs;
+                try {
+                    abs = resolveSafeRepoPath(root, rel);
+                }
+                catch (error) {
+                    if (error instanceof PathEscapeError) {
+                        return fail("path_escape", "path escapes repository root");
+                    }
+                    throw error;
+                }
+                const denied = ensureWorkspace(abs);
+                if (denied)
+                    return denied;
+                const maxBytes = typeof call.arguments.maxBytes === "number" ? call.arguments.maxBytes : 200_000;
+                const buf = await fs.readFile(abs);
+                if (buf.byteLength > maxBytes) {
+                    return fail("too_large", `File exceeds ${maxBytes} bytes`);
+                }
+                const text = buf.toString("utf8");
+                return ok({
+                    path: rel.split(path.sep).join("/"),
+                    bytes: buf.byteLength,
+                    content: redactSecrets(text).text,
+                    channel: "PROJECT_DATA",
+                });
+            }
+            case "list_files": {
+                const limit = typeof call.arguments.limit === "number" ? call.arguments.limit : 200;
+                const discovery = await discoverFiles({ root });
+                const files = discovery.files.slice(0, limit).map((f) => f.relativePath);
+                return ok({
+                    count: discovery.files.length,
+                    files,
+                    truncated: discovery.files.length > limit,
+                });
+            }
+            case "search_code":
+                return ok(await handleCodebaseSearch(root, asRecord(call.arguments)));
+            case "find_symbol":
+                return ok(await handleSymbolLookup(root, asRecord(call.arguments)));
+            case "find_references": {
+                const symbol = str(call.arguments, "symbol");
+                if (!symbol)
+                    return fail("invalid_argument", "symbol required");
+                return ok(await handleRefactorImpactTool(root, { symbol }));
+            }
+            case "find_callers": {
+                const target = str(call.arguments, "target");
+                if (!target)
+                    return fail("invalid_argument", "target required");
+                const raw = (await handleCallGraphLookup(root, { symbol: target }));
+                const edges = (raw.calls ?? []).filter((e) => e.to.includes(target));
+                return ok({ ok: raw.ok, direction: "callers", target, edges });
+            }
+            case "find_callees": {
+                const target = str(call.arguments, "target");
+                if (!target)
+                    return fail("invalid_argument", "target required");
+                const raw = (await handleCallGraphLookup(root, { symbol: target }));
+                const edges = (raw.calls ?? []).filter((e) => e.from.includes(target));
+                return ok({ ok: raw.ok, direction: "callees", target, edges });
+            }
+            case "inspect_project":
+                return ok(await summarizeProjectForChat(root));
+            case "inspect_architecture":
+                return ok(await handleArchitectureCheckTool(root));
+            case "inspect_dependencies": {
+                const target = str(call.arguments, "target");
+                if (!target)
+                    return fail("invalid_argument", "target required");
+                return ok(await handleDependencyLookup(root, { target }));
+            }
+            case "inspect_tests":
+                return ok(await handleTestImpactTool(root));
+            case "inspect_findings": {
+                const result = await scan({ cwd: root });
+                return ok({
+                    findings: result.findings.slice(0, 50),
+                    summary: result.summary,
+                    agents: result.agents.map((a) => ({
+                        id: a.id,
+                        detected: a.detected,
+                        configured: a.configured,
+                        status: a.status,
+                    })),
+                });
+            }
+            case "inspect_git_status": {
+                const report = await analyzeChanges({ root });
+                return ok({
+                    gitAvailable: report.gitAvailable,
+                    files: report.files.slice(0, 100),
+                    summary: report.summary,
+                });
+            }
+            case "inspect_git_diff": {
+                const since = str(call.arguments, "since") ?? undefined;
+                const report = await analyzeChanges({
+                    root,
+                    ...(since ? { since } : {}),
+                    impact: true,
+                });
+                return ok({
+                    gitAvailable: report.gitAvailable,
+                    files: report.files.slice(0, 100),
+                    summary: report.summary,
+                    impact: report.impact ?? null,
+                    note: "Full unified patch text is not dumped; use change analyze for evidence.",
+                });
+            }
+            case "create_file": {
+                const rel = str(call.arguments, "path");
+                const content = typeof call.arguments.content === "string" ? call.arguments.content : null;
+                if (!rel || content === null)
+                    return fail("invalid_argument", "path and content required");
+                let absCreate;
+                try {
+                    absCreate = resolveSafeRepoPath(root, rel);
+                }
+                catch (error) {
+                    if (error instanceof PathEscapeError) {
+                        return fail("path_escape", "path escapes repository root");
+                    }
+                    throw error;
+                }
+                const denyCreate = ensureWorkspace(absCreate);
+                if (denyCreate)
+                    return denyCreate;
+                return ok(await createFileSafe(root, rel, content));
+            }
+            case "edit_file": {
+                const rel = str(call.arguments, "path");
+                if (!rel)
+                    return fail("invalid_argument", "path required");
+                let absEdit;
+                try {
+                    absEdit = resolveSafeRepoPath(root, rel);
+                }
+                catch (error) {
+                    if (error instanceof PathEscapeError) {
+                        return fail("path_escape", "path escapes repository root");
+                    }
+                    throw error;
+                }
+                const denyEdit = ensureWorkspace(absEdit);
+                if (denyEdit)
+                    return denyEdit;
+                const editOpts = {};
+                if (typeof call.arguments.content === "string")
+                    editOpts.content = call.arguments.content;
+                if (typeof call.arguments.oldContent === "string") {
+                    editOpts.oldContent = call.arguments.oldContent;
+                }
+                if (typeof call.arguments.startLine === "number") {
+                    editOpts.startLine = call.arguments.startLine;
+                }
+                if (typeof call.arguments.endLine === "number")
+                    editOpts.endLine = call.arguments.endLine;
+                if (typeof call.arguments.replacement === "string") {
+                    editOpts.replacement = call.arguments.replacement;
+                }
+                return ok(await editFileSafe(root, rel, editOpts));
+            }
+            case "delete_file": {
+                const rel = str(call.arguments, "path");
+                if (!rel)
+                    return fail("invalid_argument", "path required");
+                let absDel;
+                try {
+                    absDel = resolveSafeRepoPath(root, rel);
+                }
+                catch (error) {
+                    if (error instanceof PathEscapeError) {
+                        return fail("path_escape", "path escapes repository root");
+                    }
+                    throw error;
+                }
+                const denyDel = ensureWorkspace(absDel);
+                if (denyDel)
+                    return denyDel;
+                return ok(await deleteFileSafe(root, rel));
+            }
+            case "run_command": {
+                const command = str(call.arguments, "command") ?? undefined;
+                const argv = Array.isArray(call.arguments.argv)
+                    ? call.arguments.argv.filter((x) => typeof x === "string")
+                    : undefined;
+                if (!command && (!argv || argv.length === 0)) {
+                    return fail("invalid_argument", "command or argv required");
+                }
+                const result = await runAgentCommand({
+                    root,
+                    ...(command ? { command } : {}),
+                    ...(argv ? { argv } : {}),
+                    execute: true,
+                });
+                if (result.blocked) {
+                    return fail("blocked", result.reason);
+                }
+                if (!result.ok) {
+                    return fail(result.decision === "require-approval" ? "policy_approval" : "command_failed", result.reason || result.notice);
+                }
+                return ok(result);
+            }
+            case "run_tests": {
+                const command = str(call.arguments, "command");
+                let argv;
+                if (command) {
+                    // fall through to runAgentCommand with command string
+                }
+                else {
+                    try {
+                        const pkgRaw = await fs.readFile(path.join(root, "package.json"), "utf8");
+                        argv = inferTestArgv(JSON.parse(pkgRaw)) ?? undefined;
+                    }
+                    catch {
+                        argv = undefined;
+                    }
+                }
+                if (!command && !argv) {
+                    return fail("no_test_runner", "Could not infer test command; pass command explicitly (e.g. npm test).");
+                }
+                const result = await runAgentCommand({
+                    root,
+                    ...(command ? { command } : {}),
+                    ...(argv ? { argv } : {}),
+                    execute: true,
+                    timeoutMs: 120_000,
+                });
+                if (result.blocked) {
+                    return fail("blocked", result.reason);
+                }
+                if (!result.ok) {
+                    return fail(result.decision === "require-approval" ? "policy_approval" : "command_failed", result.reason || result.notice);
+                }
+                return ok(result);
+            }
+            default: {
+                const _exhaustive = call.name;
+                return fail("unknown_tool", `Unhandled tool: ${_exhaustive}`);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            return fail("path_escape", "path escapes repository root");
+        }
+        return fail("tool_error", error instanceof Error ? error.message : String(error));
+    }
+}
+function redactDeep(value) {
+    if (typeof value === "string")
+        return redactSecrets(value).text;
+    if (Array.isArray(value))
+        return value.map(redactDeep);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = redactDeep(v);
+        }
+        return out;
+    }
+    return value;
+}
+export function isReadTool(name) {
+    return getToolSpec(name)?.category === "read";
+}

package/dist/agent/tools/index.d.ts

@@ -0,0 +1,6 @@
+export type { AgentToolName, AgentToolSpec, AgentToolCall, AgentToolResult, AgentRiskLevel, } from "./types.js";
+export { newToolCall } from "./types.js";
+export { listAgentToolSpecs, getToolSpec, riskForTool } from "./registry.js";
+export { executeAgentTool, isReadTool } from "./execute.js";
+export { createFileSafe, editFileSafe, deleteFileSafe, buildUnifiedDiff } from "./write.js";
+export { runAgentCommand, inferTestArgv } from "./run.js";

package/dist/agent/tools/index.js

@@ -0,0 +1,5 @@
+export { newToolCall } from "./types.js";
+export { listAgentToolSpecs, getToolSpec, riskForTool } from "./registry.js";
+export { executeAgentTool, isReadTool } from "./execute.js";
+export { createFileSafe, editFileSafe, deleteFileSafe, buildUnifiedDiff } from "./write.js";
+export { runAgentCommand, inferTestArgv } from "./run.js";

package/dist/agent/tools/registry.d.ts

@@ -0,0 +1,7 @@
+import type { AgentRiskLevel, AgentToolName, AgentToolSpec } from "./types.js";
+export declare function listAgentToolSpecs(options?: {
+    includeWrite?: boolean;
+    includeExecute?: boolean;
+}): AgentToolSpec[];
+export declare function getToolSpec(name: AgentToolName): AgentToolSpec | undefined;
+export declare function riskForTool(name: AgentToolName): AgentRiskLevel;

package/dist/agent/tools/registry.js

@@ -0,0 +1,212 @@
+const READ_SPECS = [
+    {
+        name: "read_file",
+        description: "READ: Read a UTF-8 text file inside the workspace (path-safe).",
+        risk: "LOW",
+        category: "read",
+        parameters: {
+            type: "object",
+            properties: { path: { type: "string" }, maxBytes: { type: "number" } },
+            required: ["path"],
+        },
+    },
+    {
+        name: "list_files",
+        description: "READ: List repository files (bounded discovery).",
+        risk: "LOW",
+        category: "read",
+        parameters: {
+            type: "object",
+            properties: { limit: { type: "number" } },
+        },
+    },
+    {
+        name: "search_code",
+        description: "READ: Search graph nodes by label/path substring.",
+        risk: "LOW",
+        category: "read",
+        parameters: {
+            type: "object",
+            properties: { query: { type: "string" } },
+            required: ["query"],
+        },
+    },
+    {
+        name: "find_symbol",
+        description: "READ: Lookup symbols by name.",
+        risk: "LOW",
+        category: "read",
+        parameters: {
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"],
+        },
+    },
+    {
+        name: "find_references",
+        description: "READ: Refactor/rename impact for a symbol (best-effort references).",
+        risk: "LOW",
+        category: "read",
+        parameters: {
+            type: "object",
+            properties: { symbol: { type: "string" } },
+            required: ["symbol"],
+        },
+    },
+    {
+        name: "find_callers",
+        description: "READ: Call-graph callers for a symbol/path.",
+        risk: "LOW",
+        category: "read",
+        parameters: {
+            type: "object",
+            properties: { target: { type: "string" } },
+            required: ["target"],
+        },
+    },
+    {
+        name: "find_callees",
+        description: "READ: Call-graph callees for a symbol/path.",
+        risk: "LOW",
+        category: "read",
+        parameters: {
+            type: "object",
+            properties: { target: { type: "string" } },
+            required: ["target"],
+        },
+    },
+    {
+        name: "inspect_project",
+        description: "READ: Project fingerprint summary.",
+        risk: "LOW",
+        category: "read",
+        parameters: { type: "object", properties: {} },
+    },
+    {
+        name: "inspect_architecture",
+        description: "READ: Architecture contract check + C4 overview.",
+        risk: "LOW",
+        category: "read",
+        parameters: { type: "object", properties: {} },
+    },
+    {
+        name: "inspect_dependencies",
+        description: "READ: Dependency edges for a target path/symbol.",
+        risk: "LOW",
+        category: "read",
+        parameters: {
+            type: "object",
+            properties: { target: { type: "string" } },
+            required: ["target"],
+        },
+    },
+    {
+        name: "inspect_tests",
+        description: "READ: Test-impact analysis for current changes (heuristic).",
+        risk: "LOW",
+        category: "read",
+        parameters: { type: "object", properties: {} },
+    },
+    {
+        name: "inspect_findings",
+        description: "READ: AgentDoctor safety scan findings.",
+        risk: "LOW",
+        category: "read",
+        parameters: { type: "object", properties: {} },
+    },
+    {
+        name: "inspect_git_status",
+        description: "READ: Git change status (staged/unstaged/untracked).",
+        risk: "LOW",
+        category: "read",
+        parameters: { type: "object", properties: {} },
+    },
+    {
+        name: "inspect_git_diff",
+        description: "READ: Change set summary (not full patch dump).",
+        risk: "LOW",
+        category: "read",
+        parameters: { type: "object", properties: { since: { type: "string" } } },
+    },
+];
+const WRITE_SPECS = [
+    {
+        name: "create_file",
+        description: "WRITE: Create a new file inside the workspace (requires approval).",
+        risk: "MEDIUM",
+        category: "write",
+        parameters: {
+            type: "object",
+            properties: { path: { type: "string" }, content: { type: "string" } },
+            required: ["path", "content"],
+        },
+    },
+    {
+        name: "edit_file",
+        description: "WRITE: Edit a file (exact replace, line range, or full content) with diff.",
+        risk: "MEDIUM",
+        category: "write",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string" },
+                content: { type: "string" },
+                oldContent: { type: "string" },
+                startLine: { type: "number" },
+                endLine: { type: "number" },
+                replacement: { type: "string" },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "delete_file",
+        description: "WRITE: Delete a file inside the workspace (HIGH risk).",
+        risk: "HIGH",
+        category: "write",
+        parameters: {
+            type: "object",
+            properties: { path: { type: "string" } },
+            required: ["path"],
+        },
+    },
+];
+const EXEC_SPECS = [
+    {
+        name: "run_command",
+        description: "EXECUTE: Run a controlled argv command (policy + shell=false).",
+        risk: "MEDIUM",
+        category: "execute",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string" },
+                argv: { type: "array", items: { type: "string" } },
+            },
+        },
+    },
+    {
+        name: "run_tests",
+        description: "EXECUTE: Run project tests via controlled runner.",
+        risk: "MEDIUM",
+        category: "execute",
+        parameters: {
+            type: "object",
+            properties: { command: { type: "string" } },
+        },
+    },
+];
+export function listAgentToolSpecs(options) {
+    const out = [...READ_SPECS];
+    if (options?.includeWrite)
+        out.push(...WRITE_SPECS);
+    if (options?.includeExecute)
+        out.push(...EXEC_SPECS);
+    return out;
+}
+export function getToolSpec(name) {
+    return listAgentToolSpecs({ includeWrite: true, includeExecute: true }).find((t) => t.name === name);
+}
+export function riskForTool(name) {
+    return getToolSpec(name)?.risk ?? "CRITICAL";
+}

package/dist/agent/tools/run.d.ts

@@ -0,0 +1,24 @@
+export interface AgentCommandResult {
+    ok: boolean;
+    blocked: boolean;
+    command: string;
+    notice: string;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    durationMs?: number;
+    decision: string;
+    reason: string;
+}
+/**
+ * Execute a project command only via the existing controlled runner (shell=false by default).
+ */
+export declare function runAgentCommand(options: {
+    root: string;
+    command?: string;
+    argv?: string[];
+    execute?: boolean;
+    timeoutMs?: number;
+}): Promise<AgentCommandResult>;
+/** Detect common project test runners from package manifests / markers (best-effort). */
+export declare function inferTestArgv(packageJson: unknown): string[] | null;

package/dist/agent/tools/run.js

@@ -0,0 +1,44 @@
+import { runControlledCommand } from "../../enforcement/runner.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+/**
+ * Execute a project command only via the existing controlled runner (shell=false by default).
+ */
+export async function runAgentCommand(options) {
+    const root = resolveRepoRoot(options.root);
+    const result = await runControlledCommand({
+        root,
+        ...(options.command !== undefined ? { command: options.command } : {}),
+        ...(options.argv !== undefined ? { argv: options.argv } : {}),
+        executeIfAllowed: options.execute !== false,
+        useShell: false,
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    });
+    const decision = result.decision.decision;
+    const blocked = decision === "block" || decision === "deny-network";
+    const exitOk = result.exitCode === 0;
+    const executed = result.decision.executionStatus === "executed";
+    const allowed = decision === "allow";
+    return {
+        ok: allowed && executed && exitOk,
+        blocked,
+        command: options.command ?? (options.argv ?? []).join(" "),
+        notice: result.notice,
+        ...(result.stdout !== undefined ? { stdout: result.stdout } : {}),
+        ...(result.stderr !== undefined ? { stderr: result.stderr } : {}),
+        ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {}),
+        ...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}),
+        decision,
+        reason: result.decision.reason,
+    };
+}
+/** Detect common project test runners from package manifests / markers (best-effort). */
+export function inferTestArgv(packageJson) {
+    if (!packageJson || typeof packageJson !== "object")
+        return null;
+    const scripts = packageJson.scripts;
+    if (scripts?.test) {
+        // Prefer npm test when package.json present — argv form for shell=false
+        return ["npm", "test"];
+    }
+    return null;
+}