@praneeth_54/agentdoctor 3.0.2 → 3.0.3

package/dist/agent/context/brain-evidence.js

@@ -0,0 +1,296 @@
+import path from "node:path";
+import { loadLatestBrain, searchBrain } from "../../core/brain-cli/service.js";
+const QUERY_STOPWORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "is",
+    "are",
+    "was",
+    "were",
+    "what",
+    "which",
+    "who",
+    "whom",
+    "whose",
+    "where",
+    "when",
+    "why",
+    "how",
+    "does",
+    "do",
+    "did",
+    "can",
+    "could",
+    "should",
+    "would",
+    "will",
+    "of",
+    "to",
+    "for",
+    "in",
+    "on",
+    "at",
+    "by",
+    "with",
+    "from",
+    "about",
+    "into",
+    "this",
+    "that",
+    "these",
+    "those",
+    "my",
+    "our",
+    "your",
+    "its",
+    "project",
+    "projects",
+    "module",
+    "modules",
+    "component",
+    "components",
+    "belong",
+    "belongs",
+    "provide",
+    "provides",
+    "explain",
+    "architecture",
+    "structure",
+    "overview",
+    "system",
+    "please",
+    "tell",
+    "me",
+    "describe",
+]);
+const PATHISH = /(?:^|[\s(])((?:[\w.-]+\/)+[\w.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|php|go|rs|java|kt|dart|rb|cs|md|json|yml|yaml|toml))(?:$|[\s),:;])/i;
+function scoreBrainHitText(text, kind) {
+    let score = 0;
+    if (/PROVIDES|CONTAINS/i.test(text))
+        score += 0.45;
+    if (/\bmodule\b/i.test(text) || kind === "component")
+        score += 0.25;
+    if (/is-domain/i.test(text))
+        score += 0.1;
+    if (/has-risk/i.test(text))
+        score -= 0.35;
+    if (/unclear-ownership/i.test(text))
+        score -= 0.15;
+    return score;
+}
+/**
+ * AgentDoctor control-plane under `.agentdoctor/**` — usable internally,
+ * never as ordinary VERIFIED application source evidence.
+ */
+export function isControlPlaneRelativePath(relativePath) {
+    const norm = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    return norm === ".agentdoctor" || norm.startsWith(".agentdoctor/");
+}
+/** Significant tokens from a natural-language project question. */
+export function extractQueryTerms(query) {
+    const raw = query
+        .split(/[^a-zA-Z0-9_./-]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length >= 2 && !QUERY_STOPWORDS.has(t.toLowerCase()));
+    const seen = new Set();
+    const out = [];
+    for (const t of raw) {
+        const key = t.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(t);
+    }
+    return out;
+}
+function looksLikeRepoRelativePath(locator) {
+    const n = locator.replace(/\\/g, "/");
+    if (!n || n.includes("\0") || path.isAbsolute(n) || n.split("/").includes(".."))
+        return false;
+    if (isControlPlaneRelativePath(n))
+        return false;
+    if (n.includes(".private/") || n.startsWith("AgentDoctorOS/"))
+        return false;
+    // Prefer file-like or directory module paths (contain a slash or extension).
+    return n.includes("/") || /\.\w{1,8}$/.test(n);
+}
+function collectPathsFromHitText(text, into) {
+    let match;
+    const re = new RegExp(PATHISH.source, "gi");
+    while ((match = re.exec(text)) !== null) {
+        const p = match[1]?.replace(/\\/g, "/");
+        if (p && looksLikeRepoRelativePath(p))
+            into.add(p);
+    }
+}
+/**
+ * Search the latest usable Project Brain for query-relevant claims/components.
+ * Brain hits are INFERRED structural evidence — never auto-upgraded to VERIFIED.
+ * Stale ownership-boundary brains load as null (same as CLI brain status).
+ */
+export async function collectBrainEvidenceForQuery(root, query, options) {
+    const maxHits = options?.maxHits ?? 24;
+    const limitations = [];
+    const brain = await loadLatestBrain(root);
+    if (!brain) {
+        return {
+            brain: null,
+            hits: [],
+            citations: [],
+            candidateSourcePaths: [],
+            limitations: ["No usable project brain snapshot; brain evidence skipped."],
+        };
+    }
+    const terms = extractQueryTerms(query);
+    const hitMap = new Map();
+    const absorb = (hits, boost = 0) => {
+        for (const h of hits) {
+            const ranked = {
+                ...h,
+                score: h.score + boost + scoreBrainHitText(h.text, h.kind),
+            };
+            const prev = hitMap.get(h.id);
+            if (!prev || ranked.score > prev.score)
+                hitMap.set(h.id, ranked);
+        }
+    };
+    // Full query first (matches CLI `brain search`), then significant terms.
+    absorb(searchBrain(brain, query), 0.3);
+    for (const term of terms) {
+        absorb(searchBrain(brain, term), 0.2);
+    }
+    // Architecture / overview with weak terms: surface top modules + provides/contains claims.
+    if (terms.length === 0 || /architecture|structure|overview|explain (the )?project/i.test(query)) {
+        const seenNames = new Set();
+        for (const c of brain.components) {
+            if (c.type === "domain-surface") {
+                const key = c.name.toLowerCase();
+                if (seenNames.has(key))
+                    continue;
+                seenNames.add(key);
+            }
+            if (c.type !== "module" && c.type !== "domain-surface" && c.type !== "entrypoint")
+                continue;
+            const id = c.id;
+            const score = c.type === "module" ? 0.85 : c.type === "entrypoint" ? 0.75 : 0.55;
+            const prev = hitMap.get(id);
+            if (!prev || score > prev.score) {
+                hitMap.set(id, {
+                    kind: "component",
+                    id,
+                    text: `${c.name} (${c.type})`.slice(0, 240),
+                    score,
+                });
+            }
+            if (hitMap.size >= maxHits * 2)
+                break;
+        }
+        for (const claim of brain.claims) {
+            if (!/PROVIDES|CONTAINS|is-domain/i.test(claim.predicate))
+                continue;
+            const text = `${claim.subject} ${claim.predicate} ${claim.object}`;
+            const score = /PROVIDES|CONTAINS/i.test(claim.predicate) ? 0.9 : 0.6;
+            if (!hitMap.has(claim.id) || (hitMap.get(claim.id)?.score ?? 0) < score) {
+                hitMap.set(claim.id, {
+                    kind: "claim",
+                    id: claim.id,
+                    text: text.slice(0, 240),
+                    score,
+                });
+            }
+            if (hitMap.size >= maxHits * 3)
+                break;
+        }
+    }
+    const hitsRaw = [...hitMap.values()].sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+    // Collapse duplicate domain-surface/module labels (same name, many component ids).
+    const hits = [];
+    const seenLabels = new Set();
+    for (const h of hitsRaw) {
+        if (h.kind === "component") {
+            const labelKey = h.text.replace(/^comp_[a-f0-9]+\s+/i, "").toLowerCase();
+            if (seenLabels.has(labelKey))
+                continue;
+            seenLabels.add(labelKey);
+        }
+        hits.push(h);
+        if (hits.length >= maxHits)
+            break;
+    }
+    const candidateSourcePaths = new Set();
+    const evidenceById = new Map(brain.evidence.map((e) => [e.id, e]));
+    const componentById = new Map(brain.components.map((c) => [c.id, c]));
+    const claimById = new Map(brain.claims.map((c) => [c.id, c]));
+    for (const hit of hits) {
+        collectPathsFromHitText(hit.text, candidateSourcePaths);
+        if (hit.kind === "component") {
+            const comp = componentById.get(hit.id);
+            if (comp?.path && looksLikeRepoRelativePath(comp.path)) {
+                candidateSourcePaths.add(comp.path.replace(/\\/g, "/"));
+            }
+            for (const eid of comp?.evidenceIds ?? []) {
+                const ev = evidenceById.get(eid);
+                if (ev &&
+                    (ev.kind === "path" || ev.kind === "file-presence") &&
+                    looksLikeRepoRelativePath(ev.locator)) {
+                    candidateSourcePaths.add(ev.locator.replace(/\\/g, "/"));
+                }
+            }
+        }
+        if (hit.kind === "claim") {
+            const claim = claimById.get(hit.id);
+            for (const eid of claim?.evidenceIds ?? []) {
+                const ev = evidenceById.get(eid);
+                if (ev &&
+                    (ev.kind === "path" || ev.kind === "file-presence") &&
+                    looksLikeRepoRelativePath(ev.locator)) {
+                    candidateSourcePaths.add(ev.locator.replace(/\\/g, "/"));
+                }
+            }
+            // Subject/object may themselves be module directory paths.
+            if (claim && looksLikeRepoRelativePath(claim.subject)) {
+                candidateSourcePaths.add(claim.subject.replace(/\\/g, "/"));
+            }
+            if (claim && looksLikeRepoRelativePath(claim.object)) {
+                candidateSourcePaths.add(claim.object.replace(/\\/g, "/"));
+            }
+        }
+    }
+    // Prefer source paths that match query terms (e.g. Proxyshield → proxyshield/...).
+    // Deprioritize editor/control noise and has-risk-only paths when better options exist.
+    const termLower = terms.map((t) => t.toLowerCase());
+    const rankedPaths = [...candidateSourcePaths].sort((a, b) => {
+        const score = (p) => {
+            let s = 0;
+            const lower = p.toLowerCase();
+            if (termLower.some((t) => lower.includes(t)))
+                s += 5;
+            if (/\.(php|ts|tsx|js|py)$/i.test(p))
+                s += 2;
+            if (p.startsWith(".cursor/") || p.startsWith(".agentdoctor/"))
+                s -= 6;
+            if (/\.htaccess$/i.test(p))
+                s -= 1;
+            return s;
+        };
+        return score(b) - score(a) || a.localeCompare(b);
+    });
+    const citations = hits.map((h) => ({
+        source: "brain",
+        evidenceType: "project-brain",
+        confidence: "INFERRED",
+        excerpt: h.text,
+        note: `brain:${h.kind}:${h.id}`,
+    }));
+    if (hits.length === 0) {
+        limitations.push("Project brain loaded but no claims/components matched this query.");
+    }
+    return {
+        brain,
+        hits,
+        citations,
+        candidateSourcePaths: rankedPaths.slice(0, 20),
+        limitations,
+    };
+}

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

@@ -1,5 +1,6 @@
 import type { ContextBundle } from "./types.js";
 import type { RepositoryGraph } from "../../platform/types.js";
+import { type AskProgressReporter } from "../progress.js";
 export interface RetrieveContextOptions {
     root: string;
     query: string;
@@ -12,11 +13,16 @@ export interface RetrieveContextOptions {
         builder?: string;
         astFilesParsed?: number;
     };
+    /** Max owned source files to excerpt (after brain + includePaths). */
+    maxSourceFiles?: number;
+    /** Optional progress reporter (real operation boundaries only). */
+    progress?: AskProgressReporter;
 }
 /**
  * Retrieve a budgeted project context pack for the agent.
- * Reuses graph + planContext. Does not invent facts.
+ * Pipeline: Brain claims → owned source paths → graph plan → ranked excerpts.
  * Hostile paths are rejected via resolveSafeRepoPath + project ownership
  * (containment alone must not promote .private / AgentDoctorOS / nested repos).
+ * `.agentdoctor/**` is control-plane and must not become VERIFIED application source evidence.
  */
 export declare function retrieveProjectContext(options: RetrieveContextOptions): Promise<ContextBundle>;

package/dist/agent/context/retrieve.js

@@ -5,22 +5,112 @@ import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
 import { assertProjectOwnedRepoPath, ProjectOwnershipError } from "../../project/ownership.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 import { resolveSafeRepoPath, PathEscapeError } from "../../security/paths.js";
+import { collectBrainEvidenceForQuery, extractQueryTerms, isControlPlaneRelativePath, } from "./brain-evidence.js";
+import { noopAskProgress } from "../progress.js";
 function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
+async function tryReadOwnedExcerpt(root, rel, maxExcerpt) {
+    const norm = rel.split(path.sep).join("/");
+    if (isControlPlaneRelativePath(norm)) {
+        return {
+            source: "repository",
+            path: norm,
+            evidenceType: "metadata",
+            confidence: "UNKNOWN",
+            note: "control_plane: not application source evidence",
+        };
+    }
+    try {
+        const abs = resolveSafeRepoPath(root, rel);
+        await assertProjectOwnedRepoPath(root, abs, rel);
+        // Directories (module roots) are not source excerpts.
+        const st = await fs.stat(abs);
+        if (st.isDirectory()) {
+            return {
+                source: "repository",
+                path: norm,
+                evidenceType: "metadata",
+                confidence: "INFERRED",
+                note: "brain-referenced directory (no file excerpt)",
+            };
+        }
+        const text = await fs.readFile(abs, "utf8");
+        const excerpt = text.slice(0, maxExcerpt);
+        return {
+            source: "repository",
+            path: norm,
+            evidenceType: "source-code",
+            confidence: "VERIFIED",
+            excerpt,
+        };
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            return {
+                source: "repository",
+                path: norm,
+                evidenceType: "metadata",
+                confidence: "UNKNOWN",
+                note: "path_escape: rejected",
+            };
+        }
+        if (error instanceof ProjectOwnershipError) {
+            return {
+                source: "repository",
+                path: norm,
+                evidenceType: "metadata",
+                confidence: "UNKNOWN",
+                note: `ownership_denied: ${error.ownership}`,
+            };
+        }
+        return {
+            source: "repository",
+            path: norm,
+            evidenceType: "metadata",
+            confidence: "UNKNOWN",
+            note: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 /**
  * Retrieve a budgeted project context pack for the agent.
- * Reuses graph + planContext. Does not invent facts.
+ * Pipeline: Brain claims → owned source paths → graph plan → ranked excerpts.
  * Hostile paths are rejected via resolveSafeRepoPath + project ownership
  * (containment alone must not promote .private / AgentDoctorOS / nested repos).
+ * `.agentdoctor/**` is control-plane and must not become VERIFIED application source evidence.
  */
 export async function retrieveProjectContext(options) {
     const root = resolveRepoRoot(options.root);
     const query = options.query.trim() || "project overview";
     const maxExcerpt = options.maxExcerptChars ?? 1_200;
+    const maxSourceFiles = options.maxSourceFiles ?? 10;
     const citations = [];
     const limitations = [];
     const chunks = [];
+    const terms = extractQueryTerms(query);
+    const progress = options.progress ?? noopAskProgress;
+    progress.stage("search", "start");
+    let brainPack;
+    try {
+        brainPack = await collectBrainEvidenceForQuery(root, query);
+    }
+    catch (error) {
+        progress.stage("search", "fail", error instanceof Error ? error.message : String(error));
+        throw error;
+    }
+    const brainDetail = brainPack.hits.length > 0
+        ? `${brainPack.hits.length} relevant claim${brainPack.hits.length === 1 ? "" : "s"}`
+        : "no matching claims";
+    progress.stage("search", "ok", brainDetail);
+    limitations.push(...brainPack.limitations);
+    for (const c of brainPack.citations) {
+        citations.push(c);
+        if (c.excerpt) {
+            chunks.push(`--- BRAIN (${c.confidence}) ---\n${c.excerpt}`);
+        }
+    }
+    progress.stage("retrieve", "start");
     let graph = options.graph;
     try {
         if (!graph) {
@@ -28,94 +118,145 @@ export async function retrieveProjectContext(options) {
         }
     }
     catch (error) {
+        progress.stage("retrieve", "fail", error instanceof Error ? error.message : String(error));
         limitations.push(`Graph unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        if (citations.length === 0) {
+            citations.push({
+                source: "repository",
+                evidenceType: "metadata",
+                confidence: "UNKNOWN",
+                note: "Repository graph could not be built and no brain evidence matched.",
+            });
+        }
+        const rendered = [
+            `Project root: ${root}`,
+            `Query: ${query}`,
+            `Brain hits: ${brainPack.hits.length}`,
+            "",
+            ...chunks,
+        ].join("\n");
         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,
+            citations,
+            rendered,
+            estimatedTokens: estimateTokens(rendered),
             limitations,
         };
     }
+    // Prefer graph nodes that match query terms; deprioritize vendor/minified noise.
     const plan = await planContext({
         root,
         graph,
-        query,
-        budgetTokens: options.budgetTokens ?? 6_000,
+        query: terms.length ? terms.join(" ") : query,
+        budgetTokens: Math.min(options.budgetTokens ?? 6_000, 4_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);
-            await assertProjectOwnedRepoPath(root, abs, 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;
-            }
-            if (error instanceof ProjectOwnershipError) {
-                citations.push({
-                    source: "repository",
-                    path: rel,
-                    evidenceType: "metadata",
-                    confidence: "UNKNOWN",
-                    note: `ownership_denied: ${error.ownership}`,
-                });
+    const orderedPaths = [];
+    const seenPaths = new Set();
+    const pushPath = (p) => {
+        const norm = p.replace(/\\/g, "/");
+        if (!norm || seenPaths.has(norm) || isControlPlaneRelativePath(norm))
+            return;
+        seenPaths.add(norm);
+        orderedPaths.push(norm);
+    };
+    // 1) Brain-derived source paths (highest priority for module questions)
+    for (const p of brainPack.candidateSourcePaths)
+        pushPath(p);
+    // 2) Caller include paths
+    for (const p of options.includePaths ?? [])
+        pushPath(p);
+    // 3) Graph plan — prefer term matches, skip minified/vendor-ish
+    const planSorted = [...plan.selected].sort((a, b) => {
+        const score = (p) => {
+            let s = 0;
+            const lower = p.toLowerCase();
+            if (terms.some((t) => lower.includes(t.toLowerCase())))
+                s += 5;
+            if (/\.min\.js$/i.test(p) || /node_modules|vendor|assets\/.*\.umd/i.test(p))
+                s -= 4;
+            if (/\.(ts|tsx|js|jsx|py|php|go|rs)$/i.test(p))
+                s += 1;
+            return s;
+        };
+        return score(b.path) - score(a.path) || b.relevance - a.relevance;
+    });
+    for (const s of planSorted)
+        pushPath(s.path);
+    progress.stage("retrieve", "ok", `${Math.min(orderedPaths.length, maxSourceFiles)} candidate source${orderedPaths.length === 1 ? "" : "s"}`);
+    progress.stage("verify", "start");
+    let sourceExcerpts = 0;
+    let ownedVerified = 0;
+    try {
+        for (const rel of orderedPaths) {
+            if (sourceExcerpts >= maxSourceFiles)
+                break;
+            const citation = await tryReadOwnedExcerpt(root, rel, maxExcerpt);
+            if (!citation)
                 continue;
+            citations.push(citation);
+            if (citation.confidence === "VERIFIED" && citation.excerpt && citation.path) {
+                chunks.push(`--- FILE ${citation.path} (VERIFIED excerpt) ---\n${citation.excerpt}`);
+                sourceExcerpts += 1;
+                ownedVerified += 1;
             }
-            citations.push({
-                source: "repository",
-                path: rel,
-                evidenceType: "metadata",
-                confidence: "UNKNOWN",
-                note: error instanceof Error ? error.message : String(error),
-            });
         }
     }
-    if (citations.length === 0) {
+    catch (error) {
+        progress.stage("verify", "fail", error instanceof Error ? error.message : String(error));
+        throw error;
+    }
+    progress.stage("verify", "ok", ownedVerified > 0
+        ? `${ownedVerified} owned source${ownedVerified === 1 ? "" : "s"}`
+        : "no owned source excerpts");
+    const hasBrain = brainPack.citations.length > 0;
+    const hasVerifiedSource = citations.some((c) => c.confidence === "VERIFIED" && c.evidenceType === "source-code");
+    if (!hasBrain && !hasVerifiedSource) {
         citations.push({
             source: "repository",
             evidenceType: "metadata",
             confidence: "UNKNOWN",
-            note: "No files selected for this query within the token budget.",
+            note: "No brain claims or owned source excerpts matched this query within the context budget.",
         });
         limitations.push("No file excerpts retrieved — answer must use UNKNOWN where evidence is missing.");
     }
+    else if (hasBrain && !hasVerifiedSource) {
+        limitations.push("Brain structural evidence available; no owned source excerpts resolved for this query.");
+    }
+    // Compact graph hint: only term-matching nodes (not raw first-N noise).
+    const graphHints = [];
+    if (terms.length > 0) {
+        const termLower = terms.map((t) => t.toLowerCase());
+        for (const n of graph.nodes) {
+            if (!n.path || !n.label)
+                continue;
+            const blob = `${n.label} ${n.path}`.toLowerCase();
+            if (!termLower.some((t) => blob.includes(t)))
+                continue;
+            if (/\.min\.js$/i.test(n.path) || /chart\.umd|node_modules/i.test(n.path))
+                continue;
+            graphHints.push(`${n.kind}: ${n.label} @ ${n.path}`);
+            if (graphHints.length >= 6)
+                break;
+        }
+    }
+    if (graphHints.length) {
+        chunks.push(`--- GRAPH (INFERRED, query-filtered) ---\n${graphHints.join("\n")}`);
+        citations.push({
+            source: "graph",
+            evidenceType: "graph",
+            confidence: "INFERRED",
+            excerpt: graphHints.join("\n"),
+            note: "query-filtered graph nodes",
+        });
+    }
     const rendered = [
         `Project root: ${root}`,
         `Query: ${query}`,
-        `Selected files: ${plan.selected.length}`,
-        `Budget tokens: ${plan.budgetTokens} (est. used ${plan.estimatedTokens})`,
+        `Brain hits: ${brainPack.hits.length}`,
+        `Selected source files: ${sourceExcerpts}`,
+        `Budget tokens: ${plan.budgetTokens} (plan est. ${plan.estimatedTokens})`,
         "",
         ...chunks,
     ].join("\n");

package/dist/agent/progress.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Progress hooks for ask/context retrieval.
+ * Presentation lives in CLI; agent code only reports real operation boundaries.
+ */
+export type AskProgressStageId = "understand" | "search" | "retrieve" | "verify" | "prepare";
+export interface AskProgressReporter {
+    stage(id: AskProgressStageId, state: "start" | "ok" | "fail", detail?: string): void;
+    stop(): void;
+}
+export declare const noopAskProgress: AskProgressReporter;

package/dist/agent/progress.js

@@ -0,0 +1,4 @@
+export const noopAskProgress = {
+    stage() { },
+    stop() { },
+};

package/dist/cli/ask-progress.d.ts

@@ -0,0 +1,17 @@
+import type { AskProgressReporter, AskProgressStageId } from "../agent/progress.js";
+export type { AskProgressReporter, AskProgressStageId };
+export interface CreateAskProgressOptions {
+    /** When false, all methods are no-ops (JSON / quiet / tests). */
+    enabled?: boolean;
+    /** Defaults to stderr — keeps stdout free for answers / JSON. */
+    stream?: NodeJS.WritableStream;
+    /** Override TTY detection (tests). Defaults to stream.isTTY. */
+    isTTY?: boolean;
+}
+/**
+ * Human-readable ask progress. Stages must be driven by real operations.
+ * Animation uses setInterval only for frame updates while work is in flight —
+ * never to invent delay.
+ */
+export declare function createAskProgress(options?: CreateAskProgressOptions): AskProgressReporter;
+export declare function silentAskProgress(): AskProgressReporter;