@praneeth_54/agentdoctor 2.0.0 → 2.1.0

package/dist/agent/chat/service.js

@@ -0,0 +1,252 @@
+import { randomUUID } from "node:crypto";
+import { AI_PROVIDER_REQUIRED_MESSAGE, createModelProvider, loadAiConfig, publicAiConfig, redactForModel, } from "../../ai/index.js";
+import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
+import { appendSessionEvent, createSession, endSession, } from "../../platform/sessions/store.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { retrieveProjectContext } from "../context/retrieve.js";
+import { ChatMemory } from "./memory.js";
+import { PROJECT_CHAT_SYSTEM_PROMPT, wrapProjectData } from "./prompts.js";
+import { formatProjectSummary, summarizeProjectForChat, } from "./project-summary.js";
+import { buildChatTurnResponse, formatChatResponseForCli } from "./response.js";
+export const CHAT_PROVIDER_NONE_MESSAGE = `AI chat is not configured.
+
+Configure an AI provider to use AgentDoctor Project Chat.
+
+Set AGENTDOCTOR_AI_PROVIDER (and AGENTDOCTOR_AI_API_KEY / AGENTDOCTOR_AI_BASE_URL as needed).
+
+AgentDoctor's non-AI project analysis remains available.`;
+/**
+ * Project Chat service (Milestone 2).
+ * Orchestrates memory → context → model → truth/citations.
+ * Does not edit files or execute commands.
+ */
+export class ChatService {
+    root;
+    memory;
+    provider;
+    budgetTokens;
+    persistAudit;
+    systemPrompt;
+    auditSession;
+    graphCache;
+    lastContext;
+    started = false;
+    constructor(options) {
+        this.root = resolveRepoRoot(options.root);
+        this.provider = options.provider ?? createModelProvider(loadAiConfig());
+        this.budgetTokens = options.budgetTokens ?? 6_000;
+        this.persistAudit = options.persistAudit !== false;
+        this.systemPrompt = options.systemPromptAddon
+            ? `${PROJECT_CHAT_SYSTEM_PROMPT}\n\n${options.systemPromptAddon}`
+            : PROJECT_CHAT_SYSTEM_PROMPT;
+        this.memory = new ChatMemory({
+            root: this.root,
+            ...(options.maxMemoryTurns ? { maxTurns: options.maxMemoryTurns } : {}),
+            ...(options.maxMemoryChars ? { maxChars: options.maxMemoryChars } : {}),
+        });
+    }
+    get sessionId() {
+        return this.memory.sessionId;
+    }
+    getProviderId() {
+        return this.provider.id;
+    }
+    getLastContextPaths() {
+        return (this.lastContext?.citations ?? [])
+            .map((c) => c.path)
+            .filter((p) => Boolean(p));
+    }
+    getLastContext() {
+        return this.lastContext;
+    }
+    async start() {
+        if (this.started) {
+            return {
+                summary: await summarizeProjectForChat(this.root),
+                providerLabel: this.providerLabel(),
+            };
+        }
+        this.started = true;
+        if (this.persistAudit) {
+            const cfg = publicAiConfig(loadAiConfig());
+            this.auditSession = await createSession({
+                root: this.root,
+                agentId: "project-chat",
+                model: `${this.provider.id}:${cfg.model}`,
+            });
+            await this.audit("prompt", "CHAT_STARTED", {
+                provider: this.provider.id,
+                sessionId: this.sessionId,
+            });
+        }
+        // Warm graph once per chat session
+        try {
+            this.graphCache = await buildIntelligenceGraph({ root: this.root, mode: "auto" });
+        }
+        catch {
+            this.graphCache = undefined;
+        }
+        return {
+            summary: await summarizeProjectForChat(this.root),
+            providerLabel: this.providerLabel(),
+        };
+    }
+    async ask(userMessage) {
+        await this.start();
+        const safeUser = redactForModel(userMessage);
+        this.memory.addUser(safeUser);
+        await this.audit("prompt", "CHAT_USER_MESSAGE", {
+            chars: String(safeUser.length),
+        });
+        if (this.provider.id === "none") {
+            const response = {
+                sessionId: this.sessionId,
+                message: CHAT_PROVIDER_NONE_MESSAGE,
+                truthClaims: [],
+                citations: [],
+                provider: "none",
+                model: "none",
+                status: "provider-none",
+                error: AI_PROVIDER_REQUIRED_MESSAGE,
+                contextPaths: [],
+                contextTruncated: false,
+                limitations: [],
+            };
+            await this.audit("error", "CHAT_FAILED", { reason: "provider-none" });
+            return response;
+        }
+        const query = this.memory.resolveQuery(safeUser);
+        const context = await retrieveProjectContext({
+            root: this.root,
+            query,
+            budgetTokens: this.budgetTokens,
+            includePaths: [
+                ...this.memory.getReferencedPaths().slice(-8),
+                ...this.memory.getLastContextPaths().slice(-8),
+            ],
+            ...(this.graphCache ? { graph: this.graphCache } : {}),
+        });
+        this.lastContext = context;
+        await this.audit("file-read", "CHAT_CONTEXT_RETRIEVED", {
+            citations: String(context.citations.length),
+            tokens: String(context.estimatedTokens),
+        });
+        const history = this.memory.historyForModel().slice(0, -1); // exclude current user (added separately)
+        const messages = [
+            { role: "system", content: this.systemPrompt },
+            { role: "system", content: wrapProjectData(context.rendered) },
+            ...history.map((m) => ({ role: m.role, content: redactForModel(m.content) })),
+            { role: "user", content: safeUser },
+        ];
+        await this.audit("prompt", "CHAT_MODEL_REQUESTED", {
+            provider: this.provider.id,
+            messages: String(messages.length),
+        });
+        const modelResult = await this.provider.chat({
+            messages,
+            temperature: 0.2,
+            maxTokens: 2048,
+        });
+        if (modelResult.error) {
+            const response = buildChatTurnResponse({
+                sessionId: this.sessionId,
+                modelText: `AgentDoctor could not reach the configured AI provider.\n\nProvider: ${modelResult.provider}\nModel: ${modelResult.model}\nError: ${sanitizeProviderError(modelResult.error)}`,
+                context,
+                provider: modelResult.provider,
+                model: modelResult.model,
+                status: "provider-error",
+                error: sanitizeProviderError(modelResult.error),
+                ...(modelResult.usage ? { usage: modelResult.usage } : {}),
+            });
+            await this.audit("error", "CHAT_FAILED", {
+                reason: "provider-error",
+                provider: modelResult.provider,
+            });
+            return response;
+        }
+        const text = redactForModel(modelResult.message.content || "");
+        const response = buildChatTurnResponse({
+            sessionId: this.sessionId,
+            modelText: text,
+            context,
+            provider: modelResult.provider,
+            model: modelResult.model,
+            status: "ok",
+            ...(modelResult.usage ? { usage: modelResult.usage } : {}),
+        });
+        this.memory.addAssistant(response.message, response.contextPaths);
+        await this.audit("prompt", "CHAT_MODEL_RESPONSE", {
+            status: response.status,
+            citations: String(response.citations.length),
+        });
+        await this.audit("prompt", "CHAT_COMPLETED", {
+            turn: String(this.memory.snapshot().turnCount),
+        });
+        return response;
+    }
+    clearMemory() {
+        this.memory.clear();
+        this.lastContext = undefined;
+    }
+    async end() {
+        if (this.auditSession) {
+            await endSession(this.auditSession);
+            this.auditSession = undefined;
+        }
+    }
+    formatResponse(response) {
+        return formatChatResponseForCli(response);
+    }
+    formatProject() {
+        return summarizeProjectForChat(this.root).then(formatProjectSummary);
+    }
+    formatContext() {
+        const paths = this.getLastContextPaths();
+        if (!paths.length) {
+            return "No context retrieved yet. Ask a project question first.\n";
+        }
+        const lines = ["Context used for the last answer:", ""];
+        for (const p of paths) {
+            lines.push(`  ✓ ${p}`);
+        }
+        if (this.lastContext?.limitations.length) {
+            lines.push("");
+            lines.push("Limitations:");
+            for (const l of this.lastContext.limitations.slice(0, 5)) {
+                lines.push(`  - ${l}`);
+            }
+        }
+        lines.push("");
+        return `${lines.join("\n")}\n`;
+    }
+    providerLabel() {
+        const cfg = publicAiConfig(loadAiConfig());
+        if (this.provider.id === "none")
+            return "none (AI chat disabled)";
+        if (this.provider.id === "mock")
+            return "mock (tests/demo)";
+        return `${this.provider.id} / ${cfg.model}`;
+    }
+    async audit(type, summary, detail) {
+        if (!this.persistAudit || !this.auditSession)
+            return;
+        await appendSessionEvent(this.auditSession, {
+            type,
+            summary,
+            risk: type === "error" ? "low" : "none",
+            ...(detail ? { detail } : {}),
+        });
+    }
+}
+function sanitizeProviderError(message) {
+    return redactForModel(message)
+        .replace(/Bearer\s+\S+/gi, "Bearer [REDACTED]")
+        .replace(/sk-[A-Za-z0-9]+/g, "[REDACTED]");
+}
+export function createChatService(options) {
+    return new ChatService(options);
+}
+/** Test helper: unique id without IO */
+export function newChatSessionId() {
+    return randomUUID();
+}

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

@@ -0,0 +1,48 @@
+import type { TruthLabel, ContextCitation } from "../context/types.js";
+import type { AiProviderId, ModelProvider, TokenUsage } from "../../ai/types.js";
+export type ChatRole = "system" | "user" | "assistant";
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+    at: string;
+}
+export interface TruthClaim {
+    text: string;
+    label: TruthLabel;
+    citationPaths: string[];
+}
+export interface ChatTurnResponse {
+    sessionId: string;
+    message: string;
+    truthClaims: TruthClaim[];
+    citations: ContextCitation[];
+    provider: AiProviderId;
+    model: string;
+    status: "ok" | "provider-none" | "provider-error" | "failed";
+    error?: string;
+    usage?: TokenUsage;
+    contextPaths: string[];
+    contextTruncated: boolean;
+    limitations: string[];
+}
+export interface ChatMemorySnapshot {
+    sessionId: string;
+    root: string;
+    topic?: string;
+    messages: ChatMessage[];
+    referencedPaths: string[];
+    lastContextPaths: string[];
+    turnCount: number;
+}
+export interface ChatServiceOptions {
+    root: string;
+    /** Inject provider for tests; otherwise load from env */
+    provider?: ModelProvider;
+    budgetTokens?: number;
+    maxMemoryTurns?: number;
+    maxMemoryChars?: number;
+    /** Persist audit via platform sessions (default true) */
+    persistAudit?: boolean;
+    /** Appended to PROJECT_CHAT_SYSTEM_PROMPT (modes) */
+    systemPromptAddon?: string;
+}

package/dist/agent/chat/types.js

@@ -0,0 +1 @@
+export {};

package/dist/agent/context/retrieve.d.ts

@@ -0,0 +1,21 @@
+import type { ContextBundle } from "./types.js";
+import type { RepositoryGraph } from "../../platform/types.js";
+export interface RetrieveContextOptions {
+    root: string;
+    query: string;
+    budgetTokens?: number;
+    /** Optional relative paths the caller already wants included */
+    includePaths?: string[];
+    maxExcerptChars?: number;
+    /** Reuse a previously built graph (session cache) */
+    graph?: RepositoryGraph & {
+        builder?: string;
+        astFilesParsed?: number;
+    };
+}
+/**
+ * Retrieve a budgeted project context pack for the agent.
+ * Reuses graph + planContext. Does not invent facts.
+ * Hostile paths are rejected via resolveSafeRepoPath.
+ */
+export declare function retrieveProjectContext(options: RetrieveContextOptions): Promise<ContextBundle>;

package/dist/agent/context/retrieve.js

@@ -0,0 +1,117 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { planContext } from "../../platform/tokens/plan.js";
+import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveSafeRepoPath, PathEscapeError } from "../../security/paths.js";
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Retrieve a budgeted project context pack for the agent.
+ * Reuses graph + planContext. Does not invent facts.
+ * Hostile paths are rejected via resolveSafeRepoPath.
+ */
+export async function retrieveProjectContext(options) {
+    const root = resolveRepoRoot(options.root);
+    const query = options.query.trim() || "project overview";
+    const maxExcerpt = options.maxExcerptChars ?? 1_200;
+    const citations = [];
+    const limitations = [];
+    const chunks = [];
+    let graph = options.graph;
+    try {
+        if (!graph) {
+            graph = await buildIntelligenceGraph({ root, mode: "auto" });
+        }
+    }
+    catch (error) {
+        limitations.push(`Graph unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        return {
+            root,
+            query,
+            citations: [
+                {
+                    source: "repository",
+                    evidenceType: "metadata",
+                    confidence: "UNKNOWN",
+                    note: "Repository graph could not be built for this query.",
+                },
+            ],
+            rendered: `Query: ${query}\n(No graph context available.)`,
+            estimatedTokens: 32,
+            limitations,
+        };
+    }
+    const plan = await planContext({
+        root,
+        graph,
+        query,
+        budgetTokens: options.budgetTokens ?? 6_000,
+    });
+    limitations.push(...plan.limitations);
+    const paths = new Set(plan.selected.map((s) => s.path));
+    for (const p of options.includePaths ?? []) {
+        paths.add(p);
+    }
+    for (const rel of paths) {
+        try {
+            const abs = resolveSafeRepoPath(root, rel);
+            const text = await fs.readFile(abs, "utf8");
+            const excerpt = text.slice(0, maxExcerpt);
+            const citation = {
+                source: "repository",
+                path: rel.split(path.sep).join("/"),
+                evidenceType: "source-code",
+                confidence: "VERIFIED",
+                excerpt,
+            };
+            citations.push(citation);
+            chunks.push(`--- FILE ${citation.path} (VERIFIED excerpt) ---\n${excerpt}`);
+        }
+        catch (error) {
+            if (error instanceof PathEscapeError) {
+                citations.push({
+                    source: "repository",
+                    path: rel,
+                    evidenceType: "metadata",
+                    confidence: "UNKNOWN",
+                    note: "path_escape: rejected",
+                });
+                continue;
+            }
+            citations.push({
+                source: "repository",
+                path: rel,
+                evidenceType: "metadata",
+                confidence: "UNKNOWN",
+                note: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    if (citations.length === 0) {
+        citations.push({
+            source: "repository",
+            evidenceType: "metadata",
+            confidence: "UNKNOWN",
+            note: "No files selected for this query within the token budget.",
+        });
+        limitations.push("No file excerpts retrieved — answer must use UNKNOWN where evidence is missing.");
+    }
+    const rendered = [
+        `Project root: ${root}`,
+        `Query: ${query}`,
+        `Selected files: ${plan.selected.length}`,
+        `Budget tokens: ${plan.budgetTokens} (est. used ${plan.estimatedTokens})`,
+        "",
+        ...chunks,
+    ].join("\n");
+    return {
+        root,
+        query,
+        citations,
+        rendered,
+        estimatedTokens: estimateTokens(rendered),
+        limitations,
+    };
+}

package/dist/agent/context/truth.d.ts

@@ -0,0 +1,6 @@
+import type { TruthLabel } from "./types.js";
+export declare function truthLabelHelp(label: TruthLabel): string;
+/**
+ * Downgrade helper: never promote INFERRED/UNKNOWN to VERIFIED accidentally.
+ */
+export declare function minTruth(a: TruthLabel, b: TruthLabel): TruthLabel;

package/dist/agent/context/truth.js

@@ -0,0 +1,19 @@
+export function truthLabelHelp(label) {
+    switch (label) {
+        case "VERIFIED":
+            return "Directly supported by repository/project evidence.";
+        case "INFERRED":
+            return "Reasonable conclusion from available evidence but not directly established.";
+        case "UNKNOWN":
+            return "Cannot be determined from current project evidence.";
+        case "EXTERNAL":
+            return "Requires information outside the repository.";
+    }
+}
+/**
+ * Downgrade helper: never promote INFERRED/UNKNOWN to VERIFIED accidentally.
+ */
+export function minTruth(a, b) {
+    const order = ["VERIFIED", "INFERRED", "UNKNOWN", "EXTERNAL"];
+    return order[Math.max(order.indexOf(a), order.indexOf(b))];
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Context citation and truth labels for evidence-backed agent answers.
+ */
+export type TruthLabel = "VERIFIED" | "INFERRED" | "UNKNOWN" | "EXTERNAL";
+export type EvidenceType = "source-code" | "project-brain" | "graph" | "architecture" | "test" | "git" | "finding" | "documentation" | "metadata";
+export interface ContextCitation {
+    source: "repository" | "brain" | "graph" | "session" | "external";
+    path?: string;
+    range?: string;
+    evidenceType: EvidenceType;
+    confidence: TruthLabel;
+    excerpt?: string;
+    note?: string;
+}
+export interface ContextBundle {
+    root: string;
+    query: string;
+    citations: ContextCitation[];
+    /** Rendered text for model (DATA channel — untrusted) */
+    rendered: string;
+    estimatedTokens: number;
+    limitations: string[];
+}

package/dist/agent/context/types.js

@@ -0,0 +1,4 @@
+/**
+ * Context citation and truth labels for evidence-backed agent answers.
+ */
+export {};

package/dist/agent/index.d.ts

@@ -0,0 +1,26 @@
+export { AgentState, AgentStateMachine } from "./state.js";
+export type { AgentStateTransition } from "./state.js";
+export { AgentRuntime, DEFAULT_AGENT_LIMITS } from "./runtime.js";
+export type { AgentLimits, AgentAuditEvent, AgentRuntimeOptions, AgentTurnResult, } from "./runtime.js";
+export { retrieveProjectContext } from "./context/retrieve.js";
+export type { RetrieveContextOptions } from "./context/retrieve.js";
+export type { ContextBundle, ContextCitation, EvidenceType, TruthLabel } from "./context/types.js";
+export { truthLabelHelp, minTruth } from "./context/truth.js";
+/** Project Chat (2.1 Milestone 2) */
+export { ChatService, createChatService, ChatMemory, CHAT_PROVIDER_NONE_MESSAGE, buildChatTurnResponse, formatChatResponseForCli, describeTruthLabels, PROJECT_CHAT_SYSTEM_PROMPT, wrapProjectData, summarizeProjectForChat, formatProjectSummary, } from "./chat/index.js";
+export type { ChatTurnResponse, ChatMemorySnapshot, ChatMessage as ProjectChatMessage, TruthClaim, ChatServiceOptions, ProjectChatSummary, } from "./chat/index.js";
+/** Agent tools + plan/approval (2.1 Milestone 3) */
+export { listAgentToolSpecs, getToolSpec, riskForTool, executeAgentTool, isReadTool, newToolCall, } from "./tools/index.js";
+export type { AgentToolName, AgentToolSpec, AgentToolCall, AgentToolResult, AgentRiskLevel, } from "./tools/index.js";
+export { evaluateApproval, formatApprovalPrompt } from "./approvals.js";
+export type { ApprovalRequest, ApprovalResult, ApprovalDecision } from "./approvals.js";
+export { buildAgentPlan, formatAgentPlan, approvePlan } from "./plan.js";
+export type { AgentPlan, AgentPlanStep } from "./plan.js";
+export { runCodingLoop } from "./loop.js";
+export type { CodingLoopOptions, CodingLoopResult } from "./loop.js";
+export { verifyAgentWork, formatVerificationReport } from "./verify.js";
+export type { AgentVerificationReport, VerificationCheck } from "./verify.js";
+export { getModeProfile, defaultStudentMode, parseAgentMode, modeAllowsMutation, modeBlocksToolCategory, } from "./modes.js";
+export type { AgentMode, ModeProfile } from "./modes.js";
+export { StudentService } from "./student.js";
+export type { StudentDocSection, BuildWithMeResult } from "./student.js";

package/dist/agent/index.js

@@ -0,0 +1,14 @@
+export { AgentState, AgentStateMachine } from "./state.js";
+export { AgentRuntime, DEFAULT_AGENT_LIMITS } from "./runtime.js";
+export { retrieveProjectContext } from "./context/retrieve.js";
+export { truthLabelHelp, minTruth } from "./context/truth.js";
+/** Project Chat (2.1 Milestone 2) */
+export { ChatService, createChatService, ChatMemory, CHAT_PROVIDER_NONE_MESSAGE, buildChatTurnResponse, formatChatResponseForCli, describeTruthLabels, PROJECT_CHAT_SYSTEM_PROMPT, wrapProjectData, summarizeProjectForChat, formatProjectSummary, } from "./chat/index.js";
+/** Agent tools + plan/approval (2.1 Milestone 3) */
+export { listAgentToolSpecs, getToolSpec, riskForTool, executeAgentTool, isReadTool, newToolCall, } from "./tools/index.js";
+export { evaluateApproval, formatApprovalPrompt } from "./approvals.js";
+export { buildAgentPlan, formatAgentPlan, approvePlan } from "./plan.js";
+export { runCodingLoop } from "./loop.js";
+export { verifyAgentWork, formatVerificationReport } from "./verify.js";
+export { getModeProfile, defaultStudentMode, parseAgentMode, modeAllowsMutation, modeBlocksToolCategory, } from "./modes.js";
+export { StudentService } from "./student.js";

package/dist/agent/loop.d.ts

@@ -0,0 +1,51 @@
+import type { ModelProvider } from "../ai/index.js";
+import { AgentState } from "./state.js";
+import { type AgentLimits } from "./runtime.js";
+import { type AgentPlan } from "./plan.js";
+import type { AgentToolName, AgentToolResult } from "./tools/types.js";
+import { type AgentVerificationReport } from "./verify.js";
+import { type AgentMode } from "./modes.js";
+import type { WorkspaceModel } from "../workspace/index.js";
+export interface CodingLoopOptions {
+    root: string;
+    goal: string;
+    provider?: ModelProvider;
+    limits?: Partial<AgentLimits>;
+    /** Required for any write/execute */
+    approvedByHuman: boolean;
+    /** Optional pre-built plan */
+    plan?: AgentPlan;
+    /** Deterministic tool calls (tests / CLI apply) — preferred when provided */
+    toolCalls?: Array<{
+        name: AgentToolName;
+        arguments: Record<string, unknown>;
+    }>;
+    /** When true and provider present, run model tool-call loop after plan */
+    useModelLoop?: boolean;
+    /** M5: run post-change verification (default true after writes) */
+    verify?: boolean;
+    /** M5: also run controlled tests during verification */
+    runTests?: boolean;
+    /** Agent mode — LEARN hard-blocks mutations */
+    mode?: AgentMode;
+    /** Optional workspace isolation context */
+    workspace?: WorkspaceModel | null;
+}
+export interface CodingLoopResult {
+    state: AgentState;
+    plan: AgentPlan;
+    toolResults: AgentToolResult[];
+    filesChanged: string[];
+    diffs: string[];
+    responseText: string;
+    stoppedReason: "completed" | "awaiting-approval" | "limit" | "failed" | "cancelled" | "mode_forbidden";
+    iterations: number;
+    toolCalls: number;
+    verification?: AgentVerificationReport;
+    teachingNotes?: string[];
+}
+/**
+ * PLAN → APPROVAL → READ/EDIT/RUN → OBSERVE → (optional model loop) → STOP.
+ * Hard limits enforced. Model cannot approve itself. Mode allowWrites is enforced.
+ */
+export declare function runCodingLoop(options: CodingLoopOptions): Promise<CodingLoopResult>;