@praneeth_54/agentdoctor 2.0.0 → 2.1.0

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;

package/dist/agent/verify.js

@@ -0,0 +1,210 @@
+import { analyzeChange, verifyChange } from "../assurance/change.js";
+import { buildProofFromEvidence } from "../assurance/proof.js";
+import { checkArchitectureAtRoot } from "../architecture/contract.js";
+import { buildRepositoryGraph } from "../platform/graph/build.js";
+import { analyzeChanges } from "../core/changes/analyze.js";
+import { resolveRepoRoot } from "../utils/path.js";
+import { executeAgentTool, newToolCall } from "./tools/index.js";
+/**
+ * Post-change verification for the coding agent (M5).
+ * Reuses analyzeChange / verifyChange / proof / architecture — does not invent results.
+ */
+export async function verifyAgentWork(options) {
+    const root = resolveRepoRoot(options.root);
+    const checks = [];
+    const verified = [];
+    const notVerified = [
+        "production database",
+        "external deployment",
+        "external API behavior",
+        "full product correctness",
+    ];
+    const git = await analyzeChanges({ root, impact: true });
+    checks.push({
+        id: "git-status",
+        label: "Git status / change set",
+        status: git.gitAvailable ? "passed" : "skipped",
+        detail: git.gitAvailable
+            ? `${git.files.length} changed path(s); impact=${git.impact?.status ?? "n/a"}`
+            : "Git not available — change set UNKNOWN",
+    });
+    if (git.gitAvailable)
+        verified.push("Git change set inspected");
+    const filesChanged = options.filesChanged?.length
+        ? options.filesChanged
+        : git.files.map((f) => f.path).slice(0, 50);
+    let changeId = null;
+    let proofId = null;
+    try {
+        const assessment = await analyzeChange({ root });
+        changeId = assessment.changeId;
+        checks.push({
+            id: "change-analyze",
+            label: "Change impact analyzed",
+            status: "passed",
+            detail: `changeId=${assessment.changeId}; symbols=${assessment.changedSymbols.length}`,
+        });
+        verified.push("Change impact analyzed");
+        const { assessment: verifiedAssessment, manifest } = await verifyChange({
+            root,
+            changeId: assessment.changeId,
+        });
+        checks.push({
+            id: "change-verify",
+            label: "Evidence bundle produced",
+            status: verifiedAssessment.verificationStatus === "evidence-produced" ? "passed" : "failed",
+            detail: `status=${verifiedAssessment.verificationStatus}; evidence=${manifest.changeId}`,
+        });
+        if (verifiedAssessment.verificationStatus === "evidence-produced") {
+            verified.push("Evidence bundle produced");
+        }
+        try {
+            const proof = await buildProofFromEvidence(root, assessment.changeId);
+            proofId = proof.proofId;
+            checks.push({
+                id: "proof",
+                label: "Change proof",
+                status: "passed",
+                detail: `proofId=${proof.proofId}; integrity=${proof.integrityStatus}; correctness=${proof.correctnessStatus}`,
+            });
+            verified.push(`Proof built (${proof.integrityStatus})`);
+        }
+        catch (error) {
+            checks.push({
+                id: "proof",
+                label: "Change proof",
+                status: "failed",
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: "change-analyze",
+            label: "Change impact analyzed",
+            status: "failed",
+            detail: error instanceof Error ? error.message : String(error),
+        });
+    }
+    try {
+        const graph = await buildRepositoryGraph(root);
+        const arch = await checkArchitectureAtRoot(root, graph);
+        const hasContract = Boolean(arch.contractPath && arch.contract);
+        const ok = arch.violations.length === 0;
+        checks.push({
+            id: "architecture",
+            label: "Architecture check",
+            status: !hasContract ? "skipped" : ok ? "passed" : "failed",
+            detail: !hasContract
+                ? "No architecture contract present"
+                : `${arch.violations.length} violation(s); edges checked=${arch.importEdgesChecked}`,
+        });
+        if (hasContract) {
+            if (ok)
+                verified.push("Architecture check passed");
+            else
+                verified.push("Architecture check ran (violations found)");
+        }
+        else {
+            notVerified.push("architecture contract (none present)");
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: "architecture",
+            label: "Architecture check",
+            status: "failed",
+            detail: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (options.runTests && options.approvedByHuman) {
+        const testResult = await executeAgentTool(root, newToolCall("verify", "run_tests", {}), {
+            allowExecute: true,
+            approvedByHuman: true,
+        });
+        checks.push({
+            id: "tests",
+            label: "Controlled test run",
+            status: testResult.ok ? "passed" : "failed",
+            detail: testResult.ok
+                ? `exit=${testResult.data.exitCode ?? 0}`
+                : `${testResult.error?.code}: ${testResult.error?.message}`,
+        });
+        if (testResult.ok)
+            verified.push("Relevant tests executed (controlled runner)");
+        else
+            notVerified.push("test suite (execution failed or policy blocked)");
+    }
+    else {
+        checks.push({
+            id: "tests",
+            label: "Controlled test run",
+            status: "not-run",
+            detail: options.runTests
+                ? "Tests requested but human approval missing"
+                : "Tests not requested for this verification pass",
+        });
+        notVerified.push("test execution (not run in this pass)");
+    }
+    checks.push({
+        id: "workspace",
+        label: "Workspace boundary",
+        status: "passed",
+        detail: "All prior agent writes used path-safe resolveSafeRepoPath",
+    });
+    verified.push("Workspace boundary respected (write path)");
+    const summaryText = formatVerificationReport({
+        root,
+        changeId,
+        proofId,
+        filesChanged,
+        checks,
+        verified,
+        notVerified,
+        correctnessStatus: "ENGINEERING_CORRECTNESS_NOT_CLAIMED",
+        summaryText: "",
+    });
+    return {
+        root,
+        changeId,
+        proofId,
+        filesChanged,
+        checks,
+        verified,
+        notVerified,
+        correctnessStatus: "ENGINEERING_CORRECTNESS_NOT_CLAIMED",
+        summaryText,
+    };
+}
+export function formatVerificationReport(report) {
+    const lines = [
+        "",
+        "IMPLEMENTATION COMPLETE",
+        "",
+        report.filesChanged.length
+            ? `Changed:\n${report.filesChanged.map((f) => `  - ${f}`).join("\n")}`
+            : "Changed: (none recorded)",
+        "",
+        "Verification:",
+        ...report.checks.map((c) => {
+            const mark = c.status === "passed"
+                ? "✓"
+                : c.status === "failed"
+                    ? "✗"
+                    : c.status === "skipped"
+                        ? "○"
+                        : "·";
+            return `  ${mark} ${c.label} — ${c.detail}`;
+        }),
+        "",
+        "Verified:",
+        ...report.verified.map((v) => `  - ${v}`),
+        "",
+        "Not verified:",
+        ...report.notVerified.map((v) => `  - ${v}`),
+        "",
+        report.correctnessStatus,
+        "",
+    ];
+    return lines.join("\n");
+}

package/dist/ai/config.d.ts

@@ -0,0 +1,22 @@
+import type { AiProviderId } from "./types.js";
+/**
+ * AI provider configuration.
+ * Secrets come only from environment variables — never from Brain or committed files.
+ */
+export interface AiConfig {
+    provider: AiProviderId;
+    model: string;
+    baseUrl?: string;
+    /** Present only in memory from env — never serialized to Brain/evidence */
+    apiKey?: string;
+    configured: boolean;
+}
+/**
+ * Load AI config from environment.
+ * Does not read API keys from disk. Does not write secrets anywhere.
+ */
+export declare function loadAiConfig(env?: NodeJS.ProcessEnv): AiConfig;
+/** Safe view for logs / CLI — never includes apiKey. */
+export declare function publicAiConfig(config: AiConfig): Omit<AiConfig, "apiKey"> & {
+    apiKeySet: boolean;
+};

package/dist/ai/config.js

@@ -0,0 +1,68 @@
+const DEFAULT_MODELS = {
+    none: "none",
+    mock: "mock",
+    "openai-compatible": "gpt-4o-mini",
+    ollama: "llama3.2",
+    anthropic: "claude-sonnet-4-5",
+    gemini: "gemini-2.0-flash",
+};
+function normalizeProvider(raw) {
+    const v = (raw ?? "none").trim().toLowerCase();
+    switch (v) {
+        case "none":
+        case "":
+            return "none";
+        case "mock":
+            return "mock";
+        case "openai":
+        case "openai-compatible":
+        case "openrouter":
+            return "openai-compatible";
+        case "ollama":
+            return "ollama";
+        case "anthropic":
+            return "anthropic";
+        case "gemini":
+        case "google":
+            return "gemini";
+        default:
+            return "none";
+    }
+}
+/**
+ * Load AI config from environment.
+ * Does not read API keys from disk. Does not write secrets anywhere.
+ */
+export function loadAiConfig(env = process.env) {
+    const provider = normalizeProvider(env.AGENTDOCTOR_AI_PROVIDER);
+    const model = (env.AGENTDOCTOR_AI_MODEL ?? DEFAULT_MODELS[provider]).trim();
+    const baseUrl = env.AGENTDOCTOR_AI_BASE_URL?.trim() || undefined;
+    const apiKey = env.AGENTDOCTOR_AI_API_KEY?.trim() || undefined;
+    const configured = provider !== "none" &&
+        (provider === "mock" ||
+            provider === "ollama" ||
+            Boolean(apiKey) ||
+            (provider === "openai-compatible" && Boolean(baseUrl)));
+    const result = {
+        provider,
+        model,
+        configured: provider === "mock" ? true : configured,
+    };
+    if (baseUrl)
+        result.baseUrl = baseUrl;
+    if (apiKey)
+        result.apiKey = apiKey;
+    return result;
+}
+/** Safe view for logs / CLI — never includes apiKey. */
+export function publicAiConfig(config) {
+    const pub = {
+        provider: config.provider,
+        model: config.model,
+        configured: config.configured,
+        apiKeySet: Boolean(config.apiKey),
+    };
+    if (config.baseUrl)
+        pub.baseUrl = config.baseUrl;
+    return pub;
+}

package/dist/ai/index.d.ts

@@ -0,0 +1,17 @@
+import { type AiConfig } from "./config.js";
+import type { ModelProvider } from "./types.js";
+export type { AiConfig } from "./config.js";
+export { loadAiConfig, publicAiConfig } from "./config.js";
+export { redactForModel, redactMessages } from "./redact.js";
+export type { AiProviderId, ChatMessage, ChatRequest, ChatResponse, ModelMetadata, ModelProvider, ToolCallRequest, ToolSpec, TokenUsage, } from "./types.js";
+export { AI_PROVIDER_REQUIRED_MESSAGE } from "./types.js";
+export { NoneModelProvider } from "./providers/none.js";
+export { MockModelProvider } from "./providers/mock.js";
+export { OpenAiCompatibleProvider } from "./providers/openai-compatible.js";
+/**
+ * Create a ModelProvider from config / env.
+ * Unsupported providers (anthropic/gemini native) return none with a clear error path via none,
+ * unless mapped later — for M1 only none/mock/openai-compatible/ollama-via-compatible are live.
+ */
+export declare function createModelProvider(config?: AiConfig): ModelProvider;
+export declare function requireAiProviderMessage(provider: ModelProvider): string | null;

package/dist/ai/index.js

@@ -0,0 +1,52 @@
+import { loadAiConfig } from "./config.js";
+import { NoneModelProvider } from "./providers/none.js";
+import { MockModelProvider } from "./providers/mock.js";
+import { OpenAiCompatibleProvider } from "./providers/openai-compatible.js";
+import { AI_PROVIDER_REQUIRED_MESSAGE } from "./types.js";
+export { loadAiConfig, publicAiConfig } from "./config.js";
+export { redactForModel, redactMessages } from "./redact.js";
+export { AI_PROVIDER_REQUIRED_MESSAGE } from "./types.js";
+export { NoneModelProvider } from "./providers/none.js";
+export { MockModelProvider } from "./providers/mock.js";
+export { OpenAiCompatibleProvider } from "./providers/openai-compatible.js";
+/**
+ * Create a ModelProvider from config / env.
+ * Unsupported providers (anthropic/gemini native) return none with a clear error path via none,
+ * unless mapped later — for M1 only none/mock/openai-compatible/ollama-via-compatible are live.
+ */
+export function createModelProvider(config = loadAiConfig()) {
+    switch (config.provider) {
+        case "mock":
+            return new MockModelProvider();
+        case "openai-compatible": {
+            const opts = {
+                model: config.model,
+            };
+            if (config.apiKey)
+                opts.apiKey = config.apiKey;
+            if (config.baseUrl)
+                opts.baseUrl = config.baseUrl;
+            return new OpenAiCompatibleProvider(opts);
+        }
+        case "ollama":
+            // Ollama OpenAI-compatible endpoint when available; otherwise fail closed via HTTP errors.
+            return new OpenAiCompatibleProvider({
+                apiKey: config.apiKey ?? "ollama",
+                baseUrl: config.baseUrl ?? "http://127.0.0.1:11434/v1",
+                model: config.model,
+            });
+        case "anthropic":
+        case "gemini":
+            // Native SDKs are NOT IMPLEMENTED in M1 — fail closed via none message.
+            return new NoneModelProvider();
+        case "none":
+        default:
+            return new NoneModelProvider();
+    }
+}
+export function requireAiProviderMessage(provider) {
+    if (provider.id === "none") {
+        return AI_PROVIDER_REQUIRED_MESSAGE;
+    }
+    return null;
+}

package/dist/ai/providers/mock.d.ts

@@ -0,0 +1,20 @@
+import type { ChatRequest, ChatResponse, ModelMetadata, ModelProvider, ToolCallRequest } from "../types.js";
+export interface MockScriptStep {
+    content?: string;
+    toolCalls?: ToolCallRequest[];
+}
+/**
+ * Deterministic mock provider for tests and offline demos.
+ * Never calls the network.
+ * Optional `script` advances one step per chat() for coding-loop tests.
+ */
+export declare class MockModelProvider implements ModelProvider {
+    readonly id: "mock";
+    private turn;
+    private readonly script;
+    constructor(options?: {
+        script?: MockScriptStep[];
+    });
+    metadata(): ModelMetadata;
+    chat(request: ChatRequest): Promise<ChatResponse>;
+}