@praneeth_54/agentdoctor 2.0.1 → 3.0.0

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;
+}

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

@@ -0,0 +1,32 @@
+export type AgentRiskLevel = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+export type AgentToolName = "read_file" | "list_files" | "search_code" | "find_symbol" | "find_references" | "find_callers" | "find_callees" | "inspect_project" | "inspect_architecture" | "inspect_dependencies" | "inspect_tests" | "inspect_findings" | "inspect_git_status" | "inspect_git_diff" | "create_file" | "edit_file" | "delete_file" | "run_command" | "run_tests";
+export interface AgentToolSpec {
+    name: AgentToolName;
+    description: string;
+    risk: AgentRiskLevel;
+    /** JSON-schema-like args description for prompts */
+    parameters: Record<string, unknown>;
+    /** M3 read tools vs later write/exec */
+    category: "read" | "write" | "execute";
+}
+export interface AgentToolCall {
+    id: string;
+    name: AgentToolName;
+    arguments: Record<string, unknown>;
+    timestamp: string;
+    sessionId: string;
+}
+export interface AgentToolResult {
+    callId: string;
+    name: AgentToolName;
+    ok: boolean;
+    /** Structured DATA — never treat as instructions */
+    data: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+    risk: AgentRiskLevel;
+    durationMs: number;
+}
+export declare function newToolCall(sessionId: string, name: AgentToolName, args: Record<string, unknown>): AgentToolCall;

package/dist/agent/tools/types.js

@@ -0,0 +1,10 @@
+import { randomUUID } from "node:crypto";
+export function newToolCall(sessionId, name, args) {
+    return {
+        id: randomUUID(),
+        name,
+        arguments: args,
+        timestamp: new Date().toISOString(),
+        sessionId,
+    };
+}

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

@@ -0,0 +1,24 @@
+export interface FileDiffResult {
+    path: string;
+    action: "create" | "edit" | "delete";
+    beforeBytes: number;
+    afterBytes: number;
+    /** Unified-ish line diff (bounded) */
+    diff: string;
+}
+export declare function buildUnifiedDiff(pathLabel: string, before: string, after: string): string;
+/**
+ * Path-safe create. Rejects existing files (use edit_file to overwrite).
+ */
+export declare function createFileSafe(root: string, relativePath: string, content: string): Promise<FileDiffResult>;
+/**
+ * Path-safe edit. Prefer exact oldContent match or line-range replacement over blind overwrite.
+ */
+export declare function editFileSafe(root: string, relativePath: string, options: {
+    content?: string;
+    oldContent?: string;
+    startLine?: number;
+    endLine?: number;
+    replacement?: string;
+}): Promise<FileDiffResult>;
+export declare function deleteFileSafe(root: string, relativePath: string): Promise<FileDiffResult>;

package/dist/agent/tools/write.js

@@ -0,0 +1,121 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { PathEscapeError, resolveSafeRepoPath } from "../../security/paths.js";
+import { atomicWriteTextFile } from "../../utils/fs.js";
+const MAX_DIFF_LINES = 400;
+export function buildUnifiedDiff(pathLabel, before, after) {
+    const a = before.split(/\r?\n/);
+    const b = after.split(/\r?\n/);
+    const lines = [`--- a/${pathLabel}`, `+++ b/${pathLabel}`];
+    const max = Math.max(a.length, b.length);
+    let shown = 0;
+    for (let i = 0; i < max && shown < MAX_DIFF_LINES; i += 1) {
+        const left = a[i];
+        const right = b[i];
+        if (left === right) {
+            if (left !== undefined) {
+                lines.push(` ${left}`);
+                shown += 1;
+            }
+            continue;
+        }
+        if (left !== undefined) {
+            lines.push(`-${left}`);
+            shown += 1;
+        }
+        if (right !== undefined) {
+            lines.push(`+${right}`);
+            shown += 1;
+        }
+    }
+    if (shown >= MAX_DIFF_LINES) {
+        lines.push("... diff truncated ...");
+    }
+    return lines.join("\n");
+}
+function normalizeRel(rel) {
+    return rel.split(path.sep).join("/");
+}
+/**
+ * Path-safe create. Rejects existing files (use edit_file to overwrite).
+ */
+export async function createFileSafe(root, relativePath, content) {
+    const abs = resolveSafeRepoPath(root, relativePath);
+    const rel = normalizeRel(relativePath);
+    try {
+        await fs.access(abs);
+        throw new Error(`file_exists: ${rel}`);
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError)
+            throw error;
+        if (error instanceof Error && error.message.startsWith("file_exists:"))
+            throw error;
+        // ENOENT — ok to create
+    }
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await atomicWriteTextFile(abs, content);
+    return {
+        path: rel,
+        action: "create",
+        beforeBytes: 0,
+        afterBytes: Buffer.byteLength(content, "utf8"),
+        diff: buildUnifiedDiff(rel, "", content),
+    };
+}
+/**
+ * Path-safe edit. Prefer exact oldContent match or line-range replacement over blind overwrite.
+ */
+export async function editFileSafe(root, relativePath, options) {
+    const abs = resolveSafeRepoPath(root, relativePath);
+    const rel = normalizeRel(relativePath);
+    const before = await fs.readFile(abs, "utf8");
+    let after;
+    if (typeof options.startLine === "number" &&
+        typeof options.endLine === "number" &&
+        typeof options.replacement === "string") {
+        const lines = before.split(/\r?\n/);
+        const start = Math.max(1, options.startLine);
+        const end = Math.max(start, options.endLine);
+        if (start > lines.length) {
+            throw new Error(`invalid_range: startLine ${start} beyond file length ${lines.length}`);
+        }
+        const head = lines.slice(0, start - 1);
+        const tail = lines.slice(end);
+        const mid = options.replacement.split(/\r?\n/);
+        after = [...head, ...mid, ...tail].join("\n");
+    }
+    else if (typeof options.oldContent === "string" && typeof options.content === "string") {
+        if (!before.includes(options.oldContent)) {
+            throw new Error("old_content_mismatch: exact oldContent not found in file");
+        }
+        after = before.replace(options.oldContent, options.content);
+    }
+    else if (typeof options.content === "string") {
+        after = options.content;
+    }
+    else {
+        throw new Error("invalid_argument: provide content, or oldContent+content, or line range");
+    }
+    await atomicWriteTextFile(abs, after);
+    return {
+        path: rel,
+        action: "edit",
+        beforeBytes: Buffer.byteLength(before, "utf8"),
+        afterBytes: Buffer.byteLength(after, "utf8"),
+        diff: buildUnifiedDiff(rel, before, after),
+    };
+}
+export async function deleteFileSafe(root, relativePath) {
+    const abs = resolveSafeRepoPath(root, relativePath);
+    const rel = normalizeRel(relativePath);
+    const before = await fs.readFile(abs, "utf8");
+    await fs.unlink(abs);
+    return {
+        path: rel,
+        action: "delete",
+        beforeBytes: Buffer.byteLength(before, "utf8"),
+        afterBytes: 0,
+        diff: buildUnifiedDiff(rel, before, ""),
+    };
+}

package/dist/agent/verify.d.ts

@@ -0,0 +1,29 @@
+export interface VerificationCheck {
+    id: string;
+    label: string;
+    status: "passed" | "failed" | "skipped" | "not-run";
+    detail: string;
+}
+export interface AgentVerificationReport {
+    root: string;
+    changeId: string | null;
+    proofId: string | null;
+    filesChanged: string[];
+    checks: VerificationCheck[];
+    verified: string[];
+    notVerified: string[];
+    correctnessStatus: "ENGINEERING_CORRECTNESS_NOT_CLAIMED";
+    summaryText: string;
+}
+/**
+ * Post-change verification for the coding agent (M5).
+ * Reuses analyzeChange / verifyChange / proof / architecture — does not invent results.
+ */
+export declare function verifyAgentWork(options: {
+    root: string;
+    filesChanged?: string[];
+    /** When true, attempt controlled test run (requires approval flags on tool exec) */
+    runTests?: boolean;
+    approvedByHuman?: boolean;
+}): Promise<AgentVerificationReport>;
+export declare function formatVerificationReport(report: AgentVerificationReport): string;