scai 0.1.167 → 0.1.169

package/dist/agents/MainAgent.js

@@ -19,6 +19,7 @@ import { selectRelevantSourcesStep } from "./selectRelevantSourcesStep.js";
 import { iterationFileSelector } from "./iterationFileSelector.js";
 import { finalAnswerModule } from "../pipeline/modules/finalAnswerModule.js";
 import { reasonNextStep } from "./reasonNextStep.js";
+import { structuralPreloadStep } from "./structuralPreloadStep.js";
 import chalk from "chalk";
 /* ───────────────────────── registry ───────────────────────── */
 const MODULE_REGISTRY = Object.fromEntries(Object.entries(builtInModules).map(([name, mod]) => [name, mod]));
@@ -55,12 +56,17 @@ export class MainAgent {
     }
     /* ───────────── main run ───────────── */
     async run() {
-        this.runCount = 0;
-        await this.runBoot();
-        await this.runScope();
-        await this.runGrounding();
-        await this.runWorkLoop();
-        await this.runFinalize();
+        try {
+            this.runCount = 0;
+            await this.runBoot();
+            await this.runScope();
+            await this.runGrounding();
+            await this.runWorkLoop();
+            await this.runFinalize();
+        }
+        finally {
+            this.ui.stop(); // ← guaranteed cleanup
+        }
     }
     /* ───────────── boot ───────────── */
     async runBoot() {
@@ -86,31 +92,20 @@ export class MainAgent {
         await scopeClassificationStep.run(this.context);
         this.logLine("TASK", "Scope classification complete");
     }
-    /* ───────────── grounding / info acquisition loop ───────────── */
     async runGrounding() {
         let ready = false;
-        while (!ready && this.runCount < this.maxRuns) {
-            // ---------------- INFORMATION ACQUISITION ----------------
-            if (this.canExecutePhase("planning") &&
-                this.canExecuteScope("planning")) {
-                const t = this.startTimer();
-                await infoPlanGenStep.run(this.context);
-                const infoPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
-                for (const step of infoPlan.steps) {
-                    const stepIO = { query: this.query };
-                    await this.executeStep(step, stepIO);
-                }
-                this.logLine("PLAN", "infoPlanGen", t(), undefined, { highlight: false });
-            }
-            // ---------------- DETERMINISTIC EVIDENCE VERIFICATION ----------------
+        while (this.runCount < this.maxRuns) {
+            // ---------------- EVIDENCE PIPELINE ----------------
+            // -------- STRUCTURAL PRELOAD --------
+            const t0 = this.startTimer();
+            await structuralPreloadStep.run({ query: this.query, context: this.context });
+            this.logLine("ANALYSIS", "structuralPreload", t0());
             const t1 = this.startTimer();
             await evidenceVerifierStep.run({ query: this.query, context: this.context });
             this.logLine("ANALYSIS", "collectAnalysisEvidence", t1());
-            /* ───────────── precheck ───────────── */
             const t2 = this.startTimer();
             await fileCheckStep(this.context);
             this.logLine("ANALYSIS", "fileCheckStep", t2());
-            // Select grounded candidate files
             const t3 = this.startTimer();
             await selectRelevantSourcesStep.run({ query: this.query, context: this.context });
             this.logLine("ANALYSIS", "selectRelevantSources", t3());
@@ -119,12 +114,29 @@ export class MainAgent {
             await readinessGateStep.run(this.context);
             this.logLine("HASINFO", "readinessGate", t4());
             ready = this.context.analysis?.readiness?.decision === "ready";
-            if (!ready) {
-                this.runCount++;
-                if (this.context.analysis)
-                    this.context.analysis.planSuggestion = undefined;
-                this.logLine("HASINFO", "Not ready — looping back to information acquisition", undefined, undefined, { highlight: false });
+            if (ready) {
+                break;
             }
+            // ---------------- INFORMATION ACQUISITION ----------------
+            if (this.canExecutePhase("planning") &&
+                this.canExecuteScope("planning")) {
+                const t = this.startTimer();
+                await infoPlanGenStep.run(this.context);
+                const infoPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
+                // If we are about to execute a new info acquisition wave,
+                // wipe previous search results.
+                if (infoPlan.steps.length > 0 && this.context.initContext && this.context.analysis?.focus) {
+                    this.context.initContext.relatedFiles = [];
+                    this.context.analysis.focus.candidateFiles = [];
+                }
+                for (const step of infoPlan.steps) {
+                    const stepIO = { query: this.query };
+                    await this.executeStep(step, stepIO);
+                }
+                this.logLine("PLAN", "infoPlanGen", t(), undefined, { highlight: false });
+            }
+            this.runCount++;
+            this.logLine("HASINFO", "Not ready — looping back to evidence collection", undefined, undefined, { highlight: false });
         }
     }
     /* ───────────── finalize ───────────── */
@@ -135,17 +147,43 @@ export class MainAgent {
     }
     /* ───────────── work loop ───────────── */
     async runWorkLoop() {
+        const readinessDecision = this.context.analysis?.readiness?.decision;
+        const readinessConfidence = this.context.analysis?.readiness?.confidence ?? 0;
+        if (readinessDecision !== "ready") {
+            // ❌ Graceful fallback instead of throwing
+            this.context.task.status = "deferred";
+            this.context.task.reason = `Readiness not achieved (decision=${readinessDecision}, confidence=${readinessConfidence})`;
+            persistTaskData(this.context, this.taskId, getDbForRepo(), this.logLine.bind(this));
+            this.logLine("TASK", `Cannot start work loop — agent needs more evidence to safely proceed`, undefined, `Readiness: ${readinessDecision}, Confidence: ${readinessConfidence}`, { highlight: true });
+            return;
+        }
+        if (!this.context.task) {
+            throw new Error("runWorkLoop: missing task");
+        }
         const MAX_TASK_STEPS = 5;
         let stepCount = 0;
-        while (stepCount < MAX_TASK_STEPS) {
+        while (stepCount < MAX_TASK_STEPS &&
+            this.context.task.status === "active") {
             await reasonNextTaskStep.run(this.context);
             const nextAction = this.context.analysis?.iterationReasoning?.nextAction;
+            // 🟡 Pause for user clarification
+            if (nextAction === "request-feedback") {
+                this.context.task.status = "paused";
+                persistTaskData(this.context, this.taskId, getDbForRepo(), this.logLine.bind(this));
+                this.logLine("TASK", "Execution paused — awaiting user clarification", undefined, undefined, { highlight: false });
+                return;
+            }
+            // 🟢 Completed task
             if (nextAction === "complete") {
+                this.context.task.status = "completed";
+                persistTaskData(this.context, this.taskId, getDbForRepo(), this.logLine.bind(this));
                 this.logLine("TASK", "All selected files processed — task complete", undefined, undefined, { highlight: false });
                 return;
             }
             const taskStep = await iterationFileSelector.run(this.context);
             if (!taskStep) {
+                this.context.task.status = "completed";
+                persistTaskData(this.context, this.taskId, getDbForRepo(), this.logLine.bind(this));
                 this.logLine("TASK", "No eligible taskStep found — task complete", undefined, undefined, { highlight: false });
                 return;
             }
@@ -155,11 +193,11 @@ export class MainAgent {
             taskStep.stepIndex = stepCount;
             taskStep.status = "pending";
             persistTaskStepInsert(taskStep, getDbForRepo());
-            this.logLine("NEW STEP", `Processing taskStep ${stepCount}/${MAX_TASK_STEPS}`, undefined, taskStep.filePath, { highlight: true });
+            this.logLine("NEW STEP", `Processing taskStep ${stepCount}`, undefined, taskStep.filePath, { highlight: true });
             taskStep.startTime = Date.now();
             persistTaskStepStart(taskStep, getDbForRepo());
             // ---------------------------
-            // Step-level iterations: reason only about this file
+            // Step-level iterations
             // ---------------------------
             const stepAction = await this.runStepIterations(taskStep);
             if (stepAction === "complete") {

package/dist/agents/evidenceVerifierStep.js

@@ -7,6 +7,7 @@ import { logInputOutput } from "../utils/promptLogHelper.js";
  * - Filters stopwords and short tokens.
  * - Deduplicates symbol evidence per file.
  * - Removes low-signal keyword clustering.
+ * - Strictly leverages structural data (functions, classes, imports/exports) for additional evidence.
  */
 export const evidenceVerifierStep = {
     name: "evidenceVerifier",
@@ -111,7 +112,7 @@ export const evidenceVerifierStep = {
             const evidenceItems = [];
             const matchedLines = [];
             const addedSymbols = new Set();
-            // Sentence matches
+            // -------- Sentence matches --------
             lines.forEach((line, idx) => {
                 sentenceTargets.forEach(target => {
                     if (line.includes(target)) {
@@ -129,7 +130,7 @@ export const evidenceVerifierStep = {
                     }
                 });
             });
-            // Symbol matches (deduplicated per symbol)
+            // -------- Symbol matches --------
             uniqueSymbolTargets.forEach(sym => {
                 for (let idx = 0; idx < lines.length; idx++) {
                     const line = lines[idx];
@@ -150,11 +151,11 @@ export const evidenceVerifierStep = {
                             });
                             matchedLines.push(line);
                         }
-                        break; // stop after first meaningful match
+                        break;
                     }
                 }
             });
-            // Filename-level evidence
+            // -------- Filename-level evidence --------
             const fullFileName = path.split("/").pop() ?? "";
             const baseFileName = fullFileName.replace(/\.(ts|js|tsx|md)$/, "");
             if (filenameTargets.includes(fullFileName) ||
@@ -167,23 +168,122 @@ export const evidenceVerifierStep = {
                     confidence: 1,
                 });
             }
-            // ----------------- Compute file-level confidence -----------------
+            // -------- Structural evidence (strict) --------
+            const struct = context.analysis.fileAnalysis[path]?.structural;
+            const structuralEvidence = [];
+            if (struct) {
+                const queryTokens = query
+                    .toLowerCase()
+                    .match(/\b\w{3,}\b/g) ?? [];
+                const querySet = new Set(queryTokens);
+                (struct.functions ?? []).forEach(fn => {
+                    if (fn.name && querySet.has(fn.name.toLowerCase())) {
+                        const ev = {
+                            claim: `Function name matches query: "${fn.name}"`,
+                            type: "structural",
+                            excerpt: fn.name,
+                            span: { startLine: fn.start ?? 0, endLine: fn.end ?? 0 },
+                            confidence: 0.85,
+                        };
+                        evidenceItems.push(ev);
+                        structuralEvidence.push(ev);
+                    }
+                });
+                (struct.classes ?? []).forEach(cls => {
+                    if (cls.name && querySet.has(cls.name.toLowerCase())) {
+                        const ev = {
+                            claim: `Class name matches query: "${cls.name}"`,
+                            type: "structural",
+                            excerpt: cls.name,
+                            span: { startLine: cls.start ?? 0, endLine: cls.end ?? 0 },
+                            confidence: 0.85,
+                        };
+                        evidenceItems.push(ev);
+                        structuralEvidence.push(ev);
+                    }
+                });
+                [...(struct.imports ?? []), ...(struct.exports ?? [])].forEach(sym => {
+                    if (sym && querySet.has(sym.toLowerCase())) {
+                        const ev = {
+                            claim: `Import/Export matches query: "${sym}"`,
+                            type: "structural",
+                            excerpt: sym,
+                            span: { startLine: 0, endLine: 0 },
+                            confidence: 0.85,
+                        };
+                        evidenceItems.push(ev);
+                        structuralEvidence.push(ev);
+                    }
+                });
+                // -------- Log structural evidence per file --------
+                if (structuralEvidence.length > 0) {
+                    logInputOutput("evidenceVerifier", "output", {
+                        file: path,
+                        count: structuralEvidence.length,
+                        examples: structuralEvidence.slice(0, 5).map(ev => ({
+                            claim: ev.claim,
+                            excerpt: ev.excerpt,
+                            confidence: ev.confidence,
+                        })),
+                    });
+                }
+            }
+            // -------- Structural evidence (strict) --------
+            if (struct) {
+                const queryTokens = query
+                    .toLowerCase()
+                    .match(/\b\w{3,}\b/g) ?? [];
+                const querySet = new Set(queryTokens);
+                (struct.functions ?? []).forEach(fn => {
+                    if (fn.name && querySet.has(fn.name.toLowerCase())) {
+                        evidenceItems.push({
+                            claim: `Function name matches query: "${fn.name}"`,
+                            type: "structural",
+                            excerpt: fn.name,
+                            span: { startLine: fn.start ?? 0, endLine: fn.end ?? 0 },
+                            confidence: 0.85,
+                        });
+                    }
+                });
+                (struct.classes ?? []).forEach(cls => {
+                    if (cls.name && querySet.has(cls.name.toLowerCase())) {
+                        evidenceItems.push({
+                            claim: `Class name matches query: "${cls.name}"`,
+                            type: "structural",
+                            excerpt: cls.name,
+                            span: { startLine: cls.start ?? 0, endLine: cls.end ?? 0 },
+                            confidence: 0.85,
+                        });
+                    }
+                });
+                [...(struct.imports ?? []), ...(struct.exports ?? [])].forEach(sym => {
+                    if (sym && querySet.has(sym.toLowerCase())) {
+                        evidenceItems.push({
+                            claim: `Import/Export matches query: "${sym}"`,
+                            type: "structural",
+                            excerpt: sym,
+                            span: { startLine: 0, endLine: 0 },
+                            confidence: 0.85,
+                        });
+                    }
+                });
+            }
+            // -------- Compute file-level confidence --------
             let fileScore = 0;
             for (const ev of evidenceItems) {
                 if (ev.type === "sentence")
                     fileScore += 1.0;
                 else if (ev.type === "filename")
                     fileScore += 1.0;
-                else if (ev.type === "symbol")
+                else if (ev.type === "symbol" || ev.type === "structural")
                     fileScore += ev.confidence ?? 0.8;
             }
-            // Normalize to 0–1 range (soft cap)
             const fileConfidence = fileScore === 0
                 ? 0
-                : Math.min(1, fileScore / 3); // 3 strong signals = max confidence
+                : Math.min(1, fileScore / 3);
             const isFocusFile = context.analysis.focus?.selectedFiles?.includes(path) ?? false;
             const hasEvidence = evidenceItems.length > 0;
-            // ----------------- Merge into fileAnalysis -----------------
+            // -------- Merge into fileAnalysis --------
             if (isFocusFile || hasEvidence) {
                 const confidenceLabel = fileConfidence.toFixed(2);
                 context.analysis.fileAnalysis[path] = {
@@ -229,7 +329,18 @@ export const evidenceVerifierStep = {
             query,
             data: { fileAnalysis: context.analysis.fileAnalysis },
         };
-        logInputOutput("evidenceVerifier", "output", output.data);
+        const logSummary = Object.entries(context.analysis.fileAnalysis).map(([path, analysis]) => {
+            const evidenceCount = analysis.evidence?.length ?? 0;
+            const confidenceMatch = analysis.relevanceExplanation?.match(/\[confidence:(\d+\.\d+)\]/);
+            const confidence = confidenceMatch?.[1] ?? "0.00";
+            return {
+                file: path,
+                confidence,
+                evidenceCount,
+                isRelevant: analysis.action?.isRelevant ?? false,
+            };
+        });
+        logInputOutput("evidenceVerifier", "output", logSummary);
         return output;
     },
 };

package/dist/agents/infoPlanGenStep.js

@@ -5,40 +5,32 @@ import { logInputOutput } from '../utils/promptLogHelper.js';
 import { cleanupModule } from '../pipeline/modules/cleanupModule.js';
 /**
  * INFO PLAN GENERATOR
- * Generates a single information-gathering step.
+ * Generates a single information-acquisition step.
+ *
+ * NOTE:
+ * - This step only creates a plan; execution happens in the agent loop.
+ * - The agent controls when this step runs.
  */
 export const infoPlanGenStep = {
     name: 'infoPlanGen',
     description: 'Generates one information-acquisition step.',
-    requires: ['userQuery', 'analysis.intent', 'analysis.focus'],
+    requires: ['userQuery', 'analysis.intent'],
     produces: ['analysis.planSuggestion'],
     async run(context) {
         context.analysis || (context.analysis = {});
         // Clear any previous plan
         delete context.analysis.planSuggestion;
-        const missingFiles = Array.isArray(context.analysis.focus?.candidateFiles)
-            ? context.analysis.focus.candidateFiles
-            : [];
         const analysis = context.analysis;
-        const needsDiscovery = analysis?.routingDecision?.decision === "needs-info" ||
-            analysis?.scopeType === "repo-wide";
-        // Nothing to do? Save empty steps array
-        if (!needsDiscovery && missingFiles.length === 0) {
-            context.analysis.planSuggestion = { plan: { steps: [] } };
-            logInputOutput("infoPlanGen", "output", []);
-            return;
-        }
-        // Restrict actions to INFO only
+        const intentText = analysis.intent?.normalizedQuery ?? '';
+        const intentCategory = analysis.intent?.intentCategory ?? '';
+        // Only info-type actions
         const effectiveActions = PLAN_ACTIONS.filter(a => a.groups?.includes('info'));
-        // No actions available? Save empty steps array
         if (!effectiveActions.length) {
             context.analysis.planSuggestion = { plan: { steps: [] } };
             logInputOutput('infoPlanGen', 'output', []);
             return;
         }
         const actionsJson = JSON.stringify(effectiveActions, null, 2);
-        const intentText = analysis.intent?.normalizedQuery ?? '';
-        const intentCategory = analysis.intent?.intentCategory ?? '';
         const prompt = `
 You are an autonomous coding agent.
 
@@ -53,16 +45,10 @@ ${intentCategory}
 Allowed actions (info only):
 ${actionsJson}
 
-Existing relevant files:
-${JSON.stringify(analysis.focus?.selectedFiles ?? [], null, 2)}
-
-Missing files / candidates:
-${JSON.stringify(missingFiles, null, 2)}
-
 Rules:
 - Only produce a single info step.
 - Step must include: "action", "description", "subQuery" (array), "metadata".
-- Do NOT invent new files or actions.
+- Do NOT invent new actions or files.
 - Return strictly valid JSON representing one step.
 
 If no further information is required, return:
@@ -78,12 +64,14 @@ If no further information is required, return:
             const jsonString = typeof cleaned.content === 'string'
                 ? cleaned.content
                 : JSON.stringify(cleaned.content ?? '{}');
-            let step = JSON.parse(jsonString);
-            // Validate structure
+            // Unwrap the step from LLM output
+            const parsed = JSON.parse(jsonString);
+            let step = parsed?.step ?? null;
+            // Validate minimal structure
             if (!step || typeof step.action !== 'string') {
                 step = null;
             }
-            // Map groups & metadata
+            // Attach groups & routing confidence if available
             if (step) {
                 const actionDef = PLAN_ACTIONS.find(a => a.action === step.action);
                 step.groups = actionDef?.groups ?? ['info'];
@@ -95,10 +83,9 @@ If no further information is required, return:
                         : {})
                 };
             }
-            // Save single step to context as an array (empty if null)
-            const steps = step ? [step] : [];
-            context.analysis.planSuggestion = { plan: { steps } };
-            logInputOutput('infoPlanGen', 'output', steps);
+            // Save as array in planSuggestion
+            context.analysis.planSuggestion = { plan: { steps: step ? [step] : [] } };
+            logInputOutput('infoPlanGen', 'output', context.analysis.planSuggestion.plan?.steps ?? []);
         }
         catch (err) {
             console.warn('⚠️ Failed to generate info step:', err);

package/dist/agents/readinessGateStep.js

@@ -131,6 +131,5 @@ function logOutput(context) {
     logInputOutput('readinessGateStep', 'output', {
         readiness: context.analysis?.readiness,
         focus: context.analysis?.focus,
-        fileAnalysis: context.analysis?.fileAnalysis,
     });
 }

package/dist/agents/reasonNextTaskStep.js

@@ -1,6 +1,3 @@
-// File: src/agents/reasonNextTaskStep.ts
-import { generate } from "../lib/generate.js";
-import { cleanupModule } from "../pipeline/modules/cleanupModule.js";
 import { logInputOutput } from "../utils/promptLogHelper.js";
 /**
  * REASON NEXT TASK STEP
@@ -132,10 +129,11 @@ export const reasonNextTaskStep = {
             rationale = "All selected files have been analyzed, transformed, and validated successfully.";
             confidence = 0.98;
         }
-        // ---------------------------
+        /* // ---------------------------
         // 6.5️⃣ Optional: Reason over known risks
         // ---------------------------
         const knownRisks = context.analysis.understanding?.risks ?? [];
+
         if (knownRisks.length > 0) {
             // Optionally call the LLM with constrained instructions
             const riskPrompt = `
@@ -146,34 +144,39 @@ Task:
 - Decide whether it is reasonable to ask the user for clarification before proceeding.
 - Return STRICT JSON: { askUser: true|false, rationale: string }
 `;
+
             try {
                 const aiResponse = await generate({
                     query: context.initContext?.userQuery ?? "",
                     content: riskPrompt
                 });
+
                 const cleaned = await cleanupModule.run({
                     query: context.initContext?.userQuery ?? "",
                     content: aiResponse.data ?? ""
                 });
+
                 const parsed = cleaned.data;
+
                 // type guard
-                if (parsed &&
+                if (
+                    parsed &&
                     typeof parsed === "object" &&
                     "askUser" in parsed &&
                     "rationale" in parsed &&
-                    typeof parsed.rationale === "string") {
-                    if (parsed.askUser) {
+                    typeof (parsed as { rationale?: unknown }).rationale === "string"
+                ) {
+                    if ((parsed as { askUser: boolean }).askUser) {
                         nextAction = "request-feedback";
-                        rationale += `\nUser clarification recommended due to known risks: ${parsed.rationale}`;
+                        rationale += `\nUser clarification recommended due to known risks: ${(parsed as { rationale: string }).rationale}`;
                         confidence = Math.min(confidence, 0.8); // slightly lower because human needed
                     }
                 }
-            }
-            catch (err) {
+            } catch (err) {
                 console.warn("[reasonNextTaskStep] Risk reasoning failed", err);
                 // fallback: ignore, keep deterministic nextAction
             }
-        }
+        } */
         // ---------------------------
         // 7️⃣ Ensure a TaskStep exists for nextFile
         // ---------------------------

package/dist/agents/scopeClassificationStep.js

@@ -4,70 +4,81 @@ import { logInputOutput } from "../utils/promptLogHelper.js";
 export const scopeClassificationStep = {
     run: async (context) => {
         const query = context.initContext?.userQuery?.trim() ?? "";
-        const repoFiles = context.initContext?.relatedFiles?.join(", ") ?? "";
-        // ------------------------ LLM PROMPT ------------------------
+        context.analysis ?? (context.analysis = {});
+        // ------------------------------------------------------------
+        // 1️⃣ Prepare deterministic hints for the LLM
+        // ------------------------------------------------------------
+        const lower = query.toLowerCase();
+        const hints = [];
+        // Systemic/repo-wide hints
+        if (/\b(codebase|entire repo|whole repo|entire project|whole project|application|system)\b/i.test(lower)) {
+            hints.push("The query mentions the entire codebase or system; likely repo-wide scope.");
+        }
+        // Debugging or error hints
+        if (/\b(debug|issue|bug|memory leak|performance|error|crash|failure)\b/i.test(lower)) {
+            hints.push("The query mentions debugging, errors, or memory/performance issues; consider broad impact.");
+        }
+        // Explicit artifact references
+        if (/\b[\w-]+\.(ts|js|tsx|jsx|py|java|go|rs|cpp|c|cs)\b/i.test(lower) ||
+            /\b(class|function|method|module)\s+\w+/i.test(lower)) {
+            hints.push("The query references a specific file, class, function, or module; possibly single-file scope.");
+        }
+        // ------------------------------------------------------------
+        // 2️⃣ LLM classification
+        // ------------------------------------------------------------
         const prompt = `
-You are an assistant that classifies the "scope" of a user's request in a code repository.
+You classify the scope of a user's request in a software repository.
 
-Return STRICT JSON using this schema:
+Return STRICT JSON:
 {
   "scopeType": "none" | "single-file" | "multi-file" | "repo-wide"
 }
 
-Rules:
-- "none": request does not require touching any repository files.
-- "single-file": request likely affects only one file.
-- "multi-file": request affects several files or modules.
-- "repo-wide": request affects many files or the whole repo.
+Definitions:
+- "none": purely conceptual, no repository interaction required.
+- "single-file": clearly limited to one specific file or artifact.
+- "multi-file": involves several related files/modules.
+- "repo-wide": broad/systemic across the repository.
 
-User query: "${query}"
-Candidate files: [${repoFiles}]
-`.trim();
+User query:
+"${query}"
+
+Hints for classification:
+${hints.length ? "- " + hints.join("\n- ") : "None"}
+        `.trim();
         let llmScope = null;
         try {
-            // Step 1: ask LLM
             const genInput = { query, content: prompt };
             const genOutput = await generate(genInput);
             const raw = typeof genOutput.data === "string"
                 ? genOutput.data
                 : JSON.stringify(genOutput.data ?? "{}");
-            // Step 2: cleanup LLM output (remove extra text, comments, etc.)
             const cleaned = await cleanupModule.run({ query, content: raw });
             const jsonString = typeof cleaned.content === "string"
                 ? cleaned.content
                 : JSON.stringify(cleaned.content ?? "{}");
             const parsed = JSON.parse(jsonString);
-            if (parsed && ["none", "single-file", "multi-file", "repo-wide"].includes(parsed.scopeType)) {
+            if (parsed &&
+                ["none", "single-file", "multi-file", "repo-wide"].includes(parsed.scopeType)) {
                 llmScope = parsed.scopeType;
             }
         }
         catch (err) {
-            console.warn("LLM scope classification failed:", err);
-        }
-        // ------------------------ FALLBACK HEURISTICS ------------------------
-        let fallbackScope = "repo-wide";
-        if (!query || /\b(explain|what|who|define|describe|overview|summary)\b/i.test(query)) {
-            fallbackScope = "none";
+            console.warn("⚠️ LLM scope classification failed, falling back:", err);
         }
-        else if (/\b(file|module|class|function|cleanupModule\.ts|MainAgent\.ts|example\.ts)\b/i.test(query)) {
-            fallbackScope = "single-file";
+        // ------------------------------------------------------------
+        // 3️⃣ Safe fallback if LLM fails
+        // ------------------------------------------------------------
+        if (!llmScope) {
+            llmScope = "repo-wide";
         }
-        else if (/\b(across|multiple files|several files|refactor|update many|shared modules)\b/i.test(query)) {
-            fallbackScope = "multi-file";
-        }
-        // ------------------------ FINAL DECISION ------------------------
-        const finalScope = llmScope ?? fallbackScope;
-        // Save in context
-        context.analysis ?? (context.analysis = {});
-        context.analysis.scopeType = finalScope;
-        const scopeReasoning = llmScope ? "llm" : "heuristic-fallback";
-        // Log both for monitoring
+        context.analysis.scopeType = llmScope;
         logInputOutput("scopeClassificationStep", "output", {
             llmScope,
-            fallbackScope: fallbackScope,
-            finalScope,
-            reasoning: scopeReasoning,
+            fallbackScope: "repo-wide",
+            finalScope: llmScope,
+            reasoning: "llm-always",
         });
-        return { scopeType: finalScope };
-    }
+        return { scopeType: llmScope };
+    },
 };

package/dist/agents/structuralPreloadStep.js

@@ -0,0 +1,61 @@
+// File: src/modules/structuralPreloadStep.ts
+import { buildInDepthContext } from "../utils/buildContextualPrompt.js";
+import { logInputOutput } from "../utils/promptLogHelper.js";
+/**
+ * Structural preload:
+ * - Calls buildInDepthContext for candidate files.
+ * - Extracts structural facts only.
+ * - Populates analysis.fileAnalysis[path].structural.
+ * - Does NOT reason or assign relevance.
+ */
+export const structuralPreloadStep = {
+    name: "structuralPreload",
+    description: "Preloads structural KG and code metadata into fileAnalysis without performing reasoning.",
+    groups: ["analysis"],
+    run: async (input) => {
+        const query = input.query ?? "";
+        const context = input.context;
+        if (!context?.analysis) {
+            throw new Error("[structuralPreload] context.analysis is required.");
+        }
+        // ---- Ensure fileAnalysis exists (type-safe) ----
+        if (!context.analysis.fileAnalysis) {
+            context.analysis.fileAnalysis = {};
+        }
+        const fileAnalysis = context.analysis.fileAnalysis;
+        // ---- Candidate files ----
+        const candidatePaths = [
+            ...(context.initContext?.relatedFiles ?? []),
+        ];
+        const uniquePaths = Array.from(new Set(candidatePaths));
+        if (!uniquePaths.length) {
+            console.warn("[structuralPreload] No candidate files to preload.");
+            return { query, data: {} };
+        }
+        // ---- Only preload missing structural data ----
+        const pathsNeedingStructure = uniquePaths.filter((p) => !fileAnalysis[p]?.structural);
+        if (!pathsNeedingStructure.length)
+            return { query, data: {} };
+        // ---- Get structural data (path → structural object) ----
+        const structuralMap = await buildInDepthContext({
+            filenames: pathsNeedingStructure,
+            relatedFiles: context.initContext?.relatedFiles ?? [],
+            query,
+        });
+        // ---- Merge into fileAnalysis ----
+        for (const [path, structural] of Object.entries(structuralMap)) {
+            fileAnalysis[path] ?? (fileAnalysis[path] = { semanticAnalyzed: false });
+            fileAnalysis[path].structural = structural;
+        }
+        // ---- Minimal structured log ----
+        const logSummary = Object.entries(fileAnalysis).map(([path, analysis]) => ({
+            file: path,
+            hasStructural: !!analysis.structural,
+            functions: analysis.structural?.functions?.length ?? 0,
+            classes: analysis.structural?.classes?.length ?? 0,
+            imports: analysis.structural?.imports?.length ?? 0,
+        }));
+        logInputOutput("structuralPreload", "output", logSummary);
+        return { query, data: {} };
+    },
+};

package/dist/commands/AskCmd.js

@@ -65,16 +65,17 @@ export async function runAskCommand(query) {
         const ui = {
             update: text => spinner.update(text),
             pause: fn => {
-                spinner.stop();
+                spinner.stop(); // pause spinner
                 try {
                     fn();
                 }
                 finally {
-                    spinner.start();
+                    spinner.start(); // resume spinner
                 }
             },
             succeed: msg => spinner.succeed(msg),
-            fail: msg => spinner.fail(msg)
+            fail: msg => spinner.fail(msg),
+            stop: () => spinner.stop() // ✅ proper stop implementation
         };
         const agent = new MainAgent(context, ui);
         await agent.run();

package/dist/commands/TasksCmd.js

@@ -19,12 +19,18 @@ export async function runTasksCommand() {
             console.log(`${chalk.cyan(`[${t.id}]`)} ${chalk.yellow(t.status.padEnd(9))} ${oneLineTruncate(t.initial_query)}`);
         }
         await new Promise((resolve) => {
-            rl.question("\nSelect task id (enter to quit): ", answer => {
-                if (!answer.trim() || answer.trim().toLowerCase() === "q") {
+            rl.question("\nSelect task id (q to quit): ", answer => {
+                const trimmed = answer.trim();
+                if (trimmed.toLowerCase() === "q") {
                     resolve();
                     return;
                 }
-                const id = Number(answer);
+                if (!trimmed) {
+                    console.log(chalk.red("Please enter a task id or 'q' to quit."));
+                    resolve();
+                    return;
+                }
+                const id = Number(trimmed);
                 if (!Number.isInteger(id)) {
                     console.log(chalk.red("Invalid task id."));
                     resolve();

package/dist/db/fileIndex.js

@@ -130,21 +130,33 @@ export async function semanticSearchFiles(originalQuery, _query, topK = 5) {
     return [];
 }
 /* -------------------------------------------------- */
-/* LLM → FTS QUERY GENERATION (TAG-BASED)               */
+/* LLM → FTS QUERY GENERATION (TAG-BASED)             */
 /* -------------------------------------------------- */
 async function generatePrimaryFtsQuery(userQuery) {
     const prompt = `
-Generate a SQLite FTS query for searching a source code repository.
+You are generating a SQLite FTS query for searching a source code repository.
+
+The user query may refer to:
+- High-level intent
+- Domain terminology
+- Specific filenames, file types, or configuration files
 
 Input:
 "${userQuery}"
 
+Task:
+1. Extract high-level intent terms
+2. Expand to related domain-specific terminology
+3. Expand to likely filenames, config files, or structural artifacts if relevant
+4. Combine ALL useful terms into ONE OR-joined FTS query
+
 Rules:
-- Output ONLY the query terms
+- Output ONLY the OR-joined terms
+- Max 12 total terms
 - Use OR between terms
-- Max 10 terms
+- Include filenames when relevant
 - No explanations
-- No sentences
+- No natural language sentences
 
 Wrap the result in <FILE_CONTENT> tags.
 
@@ -164,7 +176,7 @@ term1 OR term2 OR term3
 }
 async function generateFallbackFtsQueries(userQuery, failedQuery) {
     const prompt = `
-You are generating fallback SQLite FTS queries for a source code search.
+You are generating fallback SQLite FTS queries for a source code repository search.
 
 Original user query:
 "${userQuery}"
@@ -173,18 +185,27 @@ Primary FTS query returned ZERO results:
 "${failedQuery}"
 
 Task:
-- Generate 2–3 independent FTS queries (MAX 3)
-- Each query must be a single OR-joined expression
-- Max 10 terms per query
-- Focus on filenames, symbols, module names
+Generate 3–5 independent FTS queries (MAX 5).
+
+For each query:
+1. Think at a different abstraction level (intent-level, domain-level, structural-level).
+2. Include filenames, file types, modules, config files, or symbols when relevant.
+3. Use a single OR-joined expression.
+4. Max 10 terms per query.
+
+Rules:
 - Avoid natural language sentences
-- Avoid explanations or commentary
+- No explanations
+- No commentary
+- Each line must be one complete OR expression
 
 Output format (STRICT):
 <FILE_CONTENT>
 query1
 query2
 query3
+query4
+query5
 </FILE_CONTENT>
 `.trim();
     try {
@@ -195,7 +216,7 @@ query3
             .split(/\r?\n/)
             .map(q => sanitizeQueryForFts(q.trim()))
             .filter(Boolean)
-            .slice(0, 3);
+            .slice(0, 5);
         if (!subQueries.length) {
             throw new Error("No fallback subqueries generated");
         }

package/dist/utils/buildContextualPrompt.js

@@ -218,44 +218,23 @@ function extractFileReferences(query) {
     return [...new Set(matches)];
 }
 /* ======================================================
-   IN-DEPTH CONTEXT
+   IN-DEPTH CONTEXT (Structural-Only)
    ====================================================== */
 export async function buildInDepthContext({ filenames, kgDepth = DEFAULT_KG_DEPTH, relatedFiles, query, }) {
     const db = getDbForRepo();
     const safeFilenames = Array.isArray(filenames) ? filenames : [];
-    const safeRelated = Array.isArray(relatedFiles) ? relatedFiles : [];
-    const initCtx = {
-        userQuery: query?.trim() || "",
-        repoTree: safeGenerateRepoTree(3),
-        relatedFiles: safeRelated,
-        folderCapsules: loadRelevantFolderCapsules(normalizeToFolders(safeRelated)),
-    };
-    const workingFiles = [];
-    const out = {
-        initContext: initCtx,
-        workingFiles,
-        task: {
-            id: 0,
-            projectId: 0,
-            status: "active",
-            initialQuery: query?.trim() ?? "",
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-            taskSteps: [],
-        },
-    };
-    /* -------- Working files (deep phase only) -------- */
+    const result = {};
     for (const p of safeFilenames) {
         const fileId = fileRowIdForPath(db, p);
-        const fileObj = { path: p };
+        const structural = {};
         if (typeof fileId === "number") {
-            fileObj.functions = loadFunctions(db, fileId, MAX_FUNCTIONS);
-            fileObj.classes = loadClasses(db, fileId, 200);
+            structural.functions = loadFunctions(db, fileId, MAX_FUNCTIONS);
+            structural.classes = loadClasses(db, fileId, 200);
         }
         const neighbors = loadKgNeighbors(db, p, MAX_KG_NEIGHBORS);
-        fileObj.kgTags = loadKgTags(db, p, MAX_KG_NEIGHBORS);
+        structural.kgTags = loadKgTags(db, p, MAX_KG_NEIGHBORS);
         if (neighbors.length) {
-            fileObj.kgNeighborhood = neighbors.map((e) => `${e.relation}:${e.target}`);
+            structural.kgNeighborhood = neighbors.map((e) => `${e.relation}:${e.target}`);
             const imports = neighbors
                 .filter((e) => e.relation === "imports")
                 .map((e) => e.target);
@@ -263,12 +242,12 @@ export async function buildInDepthContext({ filenames, kgDepth = DEFAULT_KG_DEPT
                 .filter((e) => e.relation === "exports")
                 .map((e) => e.target);
             if (imports.length)
-                fileObj.imports = imports.slice(0, 200);
+                structural.imports = imports.slice(0, 200);
             if (exports.length)
-                fileObj.exports = exports.slice(0, 200);
+                structural.exports = exports.slice(0, 200);
         }
-        fileObj.focusedTree = safeGenerateFocusedTree(p, 3);
-        workingFiles.push(fileObj);
+        structural.focusedTree = safeGenerateFocusedTree(p, 3);
+        result[p] = structural;
     }
-    return out;
+    return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scai",
-  "version": "0.1.167",
+  "version": "0.1.169",
   "type": "module",
   "bin": {
     "scai": "./dist/index.js"

package/dist/agents/routingDecisionStep.js

@@ -1,69 +0,0 @@
-import { logInputOutput } from "../utils/promptLogHelper.js";
-export const routingDecisionStep = {
-    run: async (context) => {
-        context.analysis ?? (context.analysis = {});
-        const scope = context.analysis.scopeType ?? "repo-wide";
-        // Default routing decision
-        let routing = {
-            decision: "has-info",
-            allowSearch: false,
-            allowInfoSteps: false,
-            allowTransform: false,
-            allowExplain: false,
-            scopeLocked: false,
-            rationale: ""
-        };
-        switch (scope) {
-            case "none":
-                routing = {
-                    decision: "has-info",
-                    allowSearch: false,
-                    allowInfoSteps: false,
-                    allowTransform: false,
-                    allowExplain: true,
-                    scopeLocked: true,
-                    rationale: "Query is not repo-related, early explain exit allowed"
-                };
-                break;
-            case "single-file":
-                routing = {
-                    decision: "has-info",
-                    allowSearch: true,
-                    allowInfoSteps: true,
-                    allowTransform: true,
-                    allowExplain: false,
-                    scopeLocked: true,
-                    rationale: "Query targets a single file; safe to execute info and transform steps"
-                };
-                break;
-            case "multi-file":
-                routing = {
-                    decision: "needs-info",
-                    allowSearch: true,
-                    allowInfoSteps: true,
-                    allowTransform: true,
-                    allowExplain: false,
-                    scopeLocked: false,
-                    rationale: "Query spans multiple files; controlled search and info acquisition needed"
-                };
-                break;
-            case "repo-wide":
-                routing = {
-                    decision: "needs-info",
-                    allowSearch: true,
-                    allowInfoSteps: true,
-                    allowTransform: true,
-                    allowExplain: false,
-                    scopeLocked: false,
-                    rationale: "Query is repo-wide; full search and sampling required"
-                };
-                break;
-        }
-        context.analysis.routingDecision = routing;
-        logInputOutput("routingDecisionStep", "output", {
-            routingDecision: routing,
-            scope,
-        });
-        return routing;
-    }
-};