@praneeth_54/agentdoctor 2.0.1 → 3.0.0

package/dist/agent/student.js

@@ -0,0 +1,230 @@
+import { retrieveProjectContext } from "./context/retrieve.js";
+import { summarizeProjectForChat } from "./chat/project-summary.js";
+import { wrapProjectData } from "./chat/prompts.js";
+import { createChatService } from "./chat/service.js";
+import { defaultStudentMode, getModeProfile, modeAllowsMutation } from "./modes.js";
+import { buildAgentPlan, formatAgentPlan } from "./plan.js";
+import { runCodingLoop } from "./loop.js";
+import { resolveRepoRoot } from "../utils/path.js";
+/**
+ * Student-oriented surface on the same AgentRuntime/ChatService (no separate engine).
+ */
+export class StudentService {
+    root;
+    mode;
+    chat;
+    provider;
+    constructor(options) {
+        this.root = resolveRepoRoot(options.root);
+        this.mode = options.mode ?? defaultStudentMode();
+        this.provider = options.provider;
+        const profile = getModeProfile(this.mode);
+        this.chat = createChatService({
+            root: this.root,
+            provider: this.provider,
+            systemPromptAddon: profile.systemPromptAddon,
+        });
+    }
+    async explainProject() {
+        const summary = await summarizeProjectForChat(this.root);
+        const context = await retrieveProjectContext({
+            root: this.root,
+            query: "project architecture modules technologies",
+            budgetTokens: 4_000,
+        });
+        const sections = [
+            {
+                id: "purpose",
+                title: "Project",
+                body: `${summary.name} at ${summary.root}`,
+                truth: "VERIFIED",
+            },
+            {
+                id: "technologies",
+                title: "Technologies",
+                body: [
+                    summary.languages.length ? `Languages: ${summary.languages.join(", ")}` : null,
+                    summary.frameworks.length ? `Frameworks: ${summary.frameworks.join(", ")}` : null,
+                    summary.packageManagers.length
+                        ? `Package managers: ${summary.packageManagers.join(", ")}`
+                        : null,
+                ]
+                    .filter(Boolean)
+                    .join("\n") || "UNKNOWN — limited detector signals",
+                truth: summary.languages.length ? "VERIFIED" : "UNKNOWN",
+            },
+            {
+                id: "testing",
+                title: "Testing",
+                body: summary.hasTests
+                    ? "Test-like paths were detected in the repository."
+                    : "UNKNOWN — no clear test layout detected.",
+                truth: summary.hasTests ? "VERIFIED" : "UNKNOWN",
+            },
+            {
+                id: "evidence",
+                title: "Evidence files",
+                body: context.citations
+                    .filter((c) => c.path)
+                    .slice(0, 8)
+                    .map((c) => `- ${c.path}`)
+                    .join("\n") || "UNKNOWN — no files retrieved",
+                truth: context.citations.some((c) => c.path) ? "VERIFIED" : "UNKNOWN",
+            },
+        ];
+        const text = [
+            "",
+            "LEARN — Project explanation (evidence-backed)",
+            "",
+            ...sections.flatMap((s) => [`[${s.truth}] ${s.title}`, s.body, ""]),
+            wrapProjectData(context.rendered).slice(0, 2_000),
+            "",
+            "Ask: How does X work? What should I learn next? Switch to Build With Me to implement a feature.",
+            "",
+        ].join("\n");
+        return { text, sections };
+    }
+    async generateVivaQuestions() {
+        const summary = await summarizeProjectForChat(this.root);
+        const questions = [];
+        if (summary.frameworks.length) {
+            questions.push(`Why did you choose ${summary.frameworks[0]} for this project?`);
+        }
+        if (summary.languages.length) {
+            questions.push(`Explain how ${summary.languages[0]} is used in your modules.`);
+        }
+        if (summary.hasTests) {
+            questions.push("How do you test the critical paths of this project?");
+        }
+        else {
+            questions.push("What testing strategy would fit this repository? (UNKNOWN today — propose based on stack only if evidenced.)");
+        }
+        questions.push("Explain the main data flow from user request to response.");
+        questions.push("What would break if you removed the authentication/authorization layer (if present)?");
+        questions.push("List security controls you implemented and where they live in the repo.");
+        // Only keep questions grounded — drop tech invention
+        return questions.slice(0, 8);
+    }
+    async generateProjectDocumentation() {
+        const { sections } = await this.explainProject();
+        const viva = await this.generateVivaQuestions();
+        return [
+            ...sections,
+            {
+                id: "abstract",
+                title: "Abstract",
+                body: `This document summarizes the ${sections[0]?.body ?? "project"} using AgentDoctor repository evidence. Claims without evidence are marked UNKNOWN.`,
+                truth: "INFERRED",
+            },
+            {
+                id: "objectives",
+                title: "Objectives",
+                body: "UNKNOWN — objectives are not stored as structured metadata; derive from README only when present in evidence.",
+                truth: "UNKNOWN",
+            },
+            {
+                id: "limitations",
+                title: "Limitations",
+                body: "Generated documentation may omit undocumented modules. External services are not verified.",
+                truth: "VERIFIED",
+            },
+            {
+                id: "viva",
+                title: "Viva questions",
+                body: viva.map((q, i) => `${i + 1}. ${q}`).join("\n"),
+                truth: "INFERRED",
+            },
+        ];
+    }
+    /**
+     * BUILD_WITH_ME / BUILD_FOR_ME: explain → plan → teach → approve → runCodingLoop → explain diffs.
+     * Reuses the shared coding engine; does not duplicate mutation logic.
+     */
+    async buildFeature(options) {
+        const mode = this.mode;
+        if (!modeAllowsMutation(mode)) {
+            return {
+                mode,
+                explanation: `Mode ${mode} forbids writes (allowWrites=false). Switch to BUILD_WITH_ME.`,
+                teachingNotes: [],
+                planText: "",
+                coding: null,
+                evidenceText: "",
+                status: "mode_forbidden",
+            };
+        }
+        const plan = await buildAgentPlan({ root: this.root, goal: options.goal });
+        const planText = formatAgentPlan(plan);
+        const teach = mode === "BUILD_WITH_ME"
+            ? [
+                "We will change only the files listed in the plan after your approval.",
+                "Each write goes through AgentDoctor tools (path-safe); the model cannot write files directly.",
+                "After edits we verify with change/evidence/proof signals — ENGINEERING_CORRECTNESS_NOT_CLAIMED.",
+            ]
+            : ["Efficient build after approval; brief diffs; same safety gates."];
+        const explanation = [
+            "",
+            `${mode} — what will be built`,
+            "",
+            `Goal: ${options.goal}`,
+            "",
+            "Relevant concepts:",
+            ...teach.map((t) => `- ${t}`),
+            "",
+            planText,
+            "",
+        ].join("\n");
+        if (!options.approvedByHuman) {
+            return {
+                mode,
+                explanation,
+                teachingNotes: teach,
+                planText,
+                coding: null,
+                evidenceText: "No files modified (approval required).",
+                status: "awaiting-approval",
+            };
+        }
+        const coding = await runCodingLoop({
+            root: this.root,
+            goal: options.goal,
+            provider: this.provider,
+            approvedByHuman: true,
+            mode,
+            plan,
+            ...(options.toolCalls ? { toolCalls: options.toolCalls } : {}),
+            ...(options.useModelLoop !== undefined ? { useModelLoop: options.useModelLoop } : {}),
+            verify: options.verify !== false,
+            runTests: options.runTests === true,
+        });
+        const evidenceText = [
+            coding.responseText,
+            "",
+            mode === "BUILD_WITH_ME"
+                ? "What changed: see files and diffs above. Why: to satisfy the approved plan. Concepts: controlled tools + verification."
+                : "Changes applied under approval; see verification summary.",
+            "",
+        ].join("\n");
+        const status = coding.stoppedReason === "completed"
+            ? "completed"
+            : coding.stoppedReason === "limit"
+                ? "limit"
+                : coding.stoppedReason === "awaiting-approval"
+                    ? "awaiting-approval"
+                    : coding.stoppedReason === "mode_forbidden"
+                        ? "mode_forbidden"
+                        : "failed";
+        return {
+            mode,
+            explanation,
+            teachingNotes: [...teach, ...(coding.teachingNotes ?? [])],
+            planText,
+            coding,
+            evidenceText,
+            status,
+        };
+    }
+    async end() {
+        await this.chat.end();
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { AgentToolCall, AgentToolName, AgentToolResult } from "./types.js";
+import { type AgentMode } from "../modes.js";
+import { type WorkspaceModel } from "../../workspace/index.js";
+/**
+ * Execute an agent tool.
+ * Write/execute tools require explicit allowWrite/allowExecute (after human approval).
+ */
+export declare function executeAgentTool(rootInput: string, call: AgentToolCall, options?: {
+    allowWrite?: boolean;
+    allowExecute?: boolean;
+    /** Human approval already obtained for this session/action */
+    approvedByHuman?: boolean;
+    /** Agent mode — LEARN hard-blocks write/execute regardless of approval */
+    mode?: AgentMode;
+    /** Optional multi-root workspace isolation context */
+    workspace?: WorkspaceModel | null;
+    /** Forensic mode — refuse all mutations */
+    forensicMode?: boolean;
+}): Promise<AgentToolResult>;
+export declare function isReadTool(name: AgentToolName): boolean;

package/dist/agent/tools/execute.js

@@ -0,0 +1,365 @@
+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";
+import { assertForensicReadOnly } from "../../product/forensic/mode.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}`);
+    const forensic = options?.forensicMode === true || process.env.AGENTDOCTOR_FORENSIC_MODE === "1";
+    if (forensic && (spec.category === "write" || spec.category === "execute")) {
+        try {
+            assertForensicReadOnly(true);
+        }
+        catch (error) {
+            return fail("forensic_read_only", error instanceof Error ? error.message : "Forensic mode refuses write operations");
+        }
+    }
+    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;