scai 0.1.140 → 0.1.142

package/dist/agents/MainAgent.js

@@ -7,7 +7,6 @@ import { structuralAnalysisStep } from "./structuralAnalysisStep.js";
 import { contextReviewStep } from "./contextReviewStep.js";
 import { planTargetFilesStep } from "./planTargetFilesStep.js";
 import { validationAnalysisStep } from "./validationAnalysisStep.js";
-import { preFileSearchCheckStep } from "./preFileSearchCheckStep.js";
 import { semanticAnalysisStep } from "./semanticAnalysisStep.js";
 import { selectRelevantSourcesStep } from "./selectRelevantSourcesStep.js";
 import { transformPlanGenStep } from "./transformPlanGenStep.js";
@@ -15,6 +14,8 @@ import { finalPlanGenStep } from "./finalPlanGenStep.js";
 import { Spinner } from "../lib/spinner.js";
 import { getDbForRepo } from "../db/client.js";
 import { writeFileStep } from "./writeFileStep.js";
+import { resolveExecutionModeStep } from "./resolveExecutionModeStep.js";
+import { preFileSearchCheckStep } from "./preFileSearchCheckStep.js";
 /* ───────────────────────── helpers ───────────────────────── */
 let activeSpinner = null;
 /**
@@ -85,11 +86,7 @@ export class MainAgent {
         const mod = resolveModuleForAction(step.action);
         if (!mod) {
             logLine("EXECUTE", step.action, stop(), "skipped (missing module)");
-            return {
-                query: input.query,
-                content: input.content,
-                data: { skipped: true }
-            };
+            return { query: input.query, content: input.content, data: { skipped: true } };
         }
         try {
             this.spinner.update(`Running step: ${step.action}`);
@@ -98,22 +95,36 @@ export class MainAgent {
                 content: input.data ?? input.content,
                 context: this.context
             });
-            if (!output) {
+            if (!output)
                 throw new Error(`Module "${mod.name}" returned empty output`);
-            }
             logLine("EXECUTE", step.action, stop());
-            return {
-                query: step.description ?? input.query,
-                data: output.data
-            };
+            return { query: step.description ?? input.query, data: output.data };
         }
         catch (err) {
             logLine("EXECUTE", step.action, stop(), "failed");
             throw err;
         }
     }
+    /* ───────────────────────── execution gates ───────────────────────── */
+    canExecutePhase(phase) {
+        const mode = this.context.executionControl?.mode ?? "transform";
+        switch (phase) {
+            case "analysis":
+                return mode !== "explain"; // only analyze if not explain
+            case "planning":
+                return mode === "transform"; // planning only in transform
+            case "transform":
+            case "write":
+                return mode === "transform"; // write only in transform
+            case "explain":
+                return mode === "explain"; // only explain mode runs explain
+            default:
+                return false;
+        }
+    }
     /* ───────────── main run ───────────── */
     async run() {
+        var _a, _b;
         this.runCount++;
         const stopRun = startTimer();
         logLine("RUN", `start #${this.runCount}`);
@@ -121,9 +132,54 @@ export class MainAgent {
         this.spinner.start();
         /* ================= BOOT ================= */
         {
-            const t = startTimer();
+            const t1 = startTimer();
             await understandIntentStep.run({ context: this.context });
-            logLine("BOOT", "understandIntent", t());
+            logLine("BOOT", "understandIntent", t1());
+            const t2 = startTimer();
+            await resolveExecutionModeStep.run(this.context);
+            logLine("BOOT", "resolveExecutionMode", t2(), `mode=${this.context.executionControl?.mode}`);
+            // Ensure executionControl exists first
+            (_a = this.context).executionControl ?? (_a.executionControl = {
+                mode: "transform", // default mode if missing
+                rationale: "Default execution mode",
+                confidence: 1,
+                constraints: {
+                    allowAnalysis: true,
+                    allowPlanning: true,
+                    allowFileWrites: false
+                }
+            });
+            // Ensure constraints are set for consistency
+            switch (this.context.executionControl?.mode) {
+                case "explain":
+                    this.context.executionControl.constraints = {
+                        allowAnalysis: false,
+                        allowPlanning: false,
+                        allowFileWrites: false
+                    };
+                    break;
+                case "analyze":
+                    this.context.executionControl.constraints = {
+                        allowAnalysis: true,
+                        allowPlanning: true,
+                        allowFileWrites: false
+                    };
+                    break;
+                case "transform":
+                    this.context.executionControl.constraints = {
+                        allowAnalysis: true,
+                        allowPlanning: true,
+                        allowFileWrites: true
+                    };
+                    break;
+                default:
+                    (_b = this.context.executionControl).constraints ?? (_b.constraints = {
+                        allowAnalysis: true,
+                        allowPlanning: true,
+                        allowFileWrites: false
+                    });
+            }
+            // Task tracking
             const db = getDbForRepo();
             const now = new Date().toISOString();
             const userQuery = this.context.initContext?.userQuery ?? "unknown query";
@@ -133,36 +189,48 @@ export class MainAgent {
             `).run(userQuery, now, now);
             this.taskId = result.lastInsertRowid;
             logLine("TASK", `created task id=${this.taskId}"`);
-            logFolderCapsulesSummary(this.context);
         }
+        /* ================= INFORMATION ACQUISITION ================= */
+        let t = startTimer();
+        await preFileSearchCheckStep(this.context);
+        logLine("PRECHECK", "preFileSearch", t());
+        // -------------------- EXPLAIN MODE HANDLING --------------------
+        if (this.canExecutePhase("explain")) {
+            const explainMod = resolveModuleForAction("explain");
+            if (!explainMod)
+                throw new Error("Explain module not found");
+            const explainOutput = await explainMod.run({
+                query: this.query,
+                context: this.context
+            });
+            logLine("MODE", "explain", undefined, "returning AI-generated explanation after preFileSearchCheck");
+            this.spinner.stop();
+            return explainOutput;
+        }
+        // -------------------- SUMMARIZE FOLDERCAPSULES FOR PLANNING --------------------
+        logFolderCapsulesSummary(this.context);
         /* ================= FAST-PATH CHECK ================= */
         {
             await planResolverStep.run(this.context);
             const routing = this.context.analysis?.routingDecision;
             if (routing?.decision === "final-answer" && routing.answer) {
                 logLine("ROUTING", "fastPathHit", undefined, "returning final answer early");
-                return {
-                    query: this.query,
-                    data: { finalAnswer: routing.answer, source: "planResolver" }
-                };
+                return { query: this.query, data: { finalAnswer: routing.answer, source: "planResolver" } };
             }
         }
-        /* ================= INFORMATION ACQUISITION ================= */
-        {
-            let t = startTimer();
-            await preFileSearchCheckStep(this.context);
-            logLine("PRECHECK", "preFileSearch", t());
+        // -------------------- PLANNING --------------------
+        if (this.canExecutePhase("planning")) {
             t = startTimer();
             await infoPlanGen.run(this.context);
             logLine("PLAN", "infoPlanGen", t());
-        }
-        const infoPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
-        let stepIO = { query: this.query };
-        for (const step of infoPlan.steps.filter(s => s.groups?.includes("info"))) {
-            stepIO = await this.executeStep(step, stepIO);
+            const infoPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
+            let stepIO = { query: this.query };
+            for (const step of infoPlan.steps.filter(s => s.groups?.includes("info"))) {
+                stepIO = await this.executeStep(step, stepIO);
+            }
         }
         /* ================= ANALYSIS PHASE ================= */
-        {
+        if (this.canExecutePhase("analysis")) {
             let t = startTimer();
             await selectRelevantSourcesStep.run({ query: this.query, context: this.context });
             logLine("ANALYSIS", "selectRelevantSources", t());
@@ -192,70 +260,78 @@ export class MainAgent {
             }
         }
         /* ================= TRANSFORM PHASE ================= */
-        {
-            const t = startTimer();
+        if (this.canExecutePhase("transform")) {
+            let t = startTimer();
             await transformPlanGenStep.run(this.context);
             logLine("PLAN", "transformPlanGen", t());
+            const transformSteps = (this.context.analysis?.planSuggestion?.plan?.steps ?? [])
+                .filter(s => s.groups?.includes("transform"));
+            let stepIO = { query: this.query };
+            for (const step of transformSteps) {
+                stepIO = await this.executeStep(step, stepIO);
+            }
+            /* ================= WRITE FILES ================= */
+            if (this.canExecutePhase("write")) {
+                const tWrite = startTimer();
+                stepIO = await writeFileStep.run({
+                    query: this.query,
+                    context: this.context,
+                    data: stepIO.data
+                });
+                logLine("EXECUTE", "writeFile", tWrite());
+            }
         }
-        const transformSteps = [
-            ...(this.context.analysis?.planSuggestion?.plan?.steps ?? [])
-        ].filter(s => s.groups?.includes("transform"));
-        for (const step of transformSteps) {
-            stepIO = await this.executeStep(step, stepIO);
-        }
-        /* ================= WRITE FILES (SIDE-EFFECT) ================= */
-        const t = startTimer();
-        stepIO = await writeFileStep.run({
-            query: this.query,
-            context: this.context,
-            data: stepIO.data
-        });
-        logLine("EXECUTE", "writeFile", t());
-        /* // ── OPTIONAL DEBUGGING ──
-        debugContext(this.context, {
-            step: "After writefile ",
-            note: "Does transform exist?"
-        }); */
         /* ================= FINALIZE PHASE ================= */
         {
             const t = startTimer();
             await finalPlanGenStep.run(this.context);
             logLine("PLAN", "finalPlanGen", t());
-        }
-        const finalPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
-        for (const step of finalPlan.steps.filter(s => s.groups?.includes("finalize"))) {
-            stepIO = await this.executeStep(step, stepIO);
+            const finalPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
+            let stepIO = { query: this.query };
+            for (const step of finalPlan.steps.filter(s => s.groups?.includes("finalize"))) {
+                stepIO = await this.executeStep(step, stepIO);
+            }
         }
         this.spinner.stop();
         userOutput("All input/output logs can be found at ~/.scai/input_output.log");
         logLine("RUN", "complete", stopRun());
-        // ───────────── LOG FINAL CONTEXT ─────────────
-        console.log("\n[DEBUG] Final MainAgent context:");
-        console.dir(this.context, { depth: null, colors: true });
-        return stepIO;
+        /*  console.log("\n[DEBUG] Final MainAgent context:");
+         console.dir(this.context, { depth: null, colors: true }); */
+        return { query: this.query, data: {} };
     }
-    /* ───────────── helpers ───────────── */
     resetInitContextForLoop() {
-        if (this.context.initContext) {
+        if (this.context.initContext)
             this.context.initContext.relatedFiles = [];
-        }
     }
 }
 /* ───────────── FOLDER CAPSULES SUMMARY HELPER ───────────── */
-function logFolderCapsulesSummary(context) {
-    if (!context.initContext?.folderCapsules?.length)
+export function logFolderCapsulesSummary(context) {
+    const capsules = context.initContext?.folderCapsules;
+    if (!capsules?.length)
         return;
-    const capsulesSummary = context.initContext.folderCapsules.map(fc => ({
-        path: fc.path,
-        fileCount: fc.stats?.fileCount ?? 0,
-        depth: fc.depth ?? 0,
-        confidence: fc.confidence ?? 0,
-        roles: fc.roles ?? [],
-        concerns: fc.concerns ?? []
-    }));
+    // Ensure analysis exists
     context.analysis ?? (context.analysis = {});
-    context.analysis.folderCapsulesSummary = capsulesSummary;
-    const humanReadable = capsulesSummary.map(fc => `- ${fc.path}: ${fc.fileCount} files, depth ${fc.depth}, confidence ${fc.confidence}`).join("\n");
-    context.analysis.folderCapsulesHuman = humanReadable;
-    logLine("BOOT", "folderCapsulesSummary", undefined, `📂 ${capsulesSummary.length} capsules summarized`);
+    // Helper: truncate text to max length
+    const truncate = (text, max = 120) => text.length > max ? text.slice(0, max - 1) + "…" : text;
+    // Build human-readable summary (1–2 lines per folder)
+    const humanReadable = capsules.map(fc => {
+        const conf = Math.round((fc.confidence ?? 0) * 100) / 100; // round to 2 decimals
+        const header = `- ${fc.path} (${fc.stats?.fileCount ?? 0} files, conf ${conf})`;
+        // Line 2: summary + optional first key file reason
+        const summaryText = fc.summary ? truncate(fc.summary.trim()) : "";
+        const key = fc.keyFiles?.[0];
+        let body = "";
+        if (summaryText || key) {
+            body += "  ";
+            if (summaryText)
+                body += summaryText;
+            if (key) {
+                const keyHint = `Key: ${key.path.split("/").pop()} — ${truncate(key.reason)}`;
+                body += summaryText ? ` [${keyHint}]` : keyHint;
+            }
+        }
+        return body ? `${header}\n${body}` : header;
+    }).join("\n\n"); // extra newline for readability
+    logInputOutput('FolderCapsule summarized', 'output', context.analysis.folderCapsulesHuman = humanReadable);
+    logLine("BOOT", "folderCapsulesSummary", undefined, `📂 ${capsules.length} folders summarized`);
 }

package/dist/agents/preFileSearchCheckStep.js

@@ -3,19 +3,21 @@ import { generate } from "../lib/generate.js";
 import { logInputOutput } from "../utils/promptLogHelper.js";
 import { cleanupModule } from "../pipeline/modules/cleanupModule.js";
 export async function preFileSearchCheckStep(context) {
-    if (!context.analysis)
-        context.analysis = {};
+    var _a;
+    context.analysis ?? (context.analysis = {});
+    (_a = context.analysis).focus ?? (_a.focus = { relevantFiles: [], missingFiles: [], rationale: "" });
     const intent = context.analysis.intent;
     const planSuggestion = context.analysis.planSuggestion?.text ?? "";
     // Step 1: gather known files from initContext only
     const knownFiles = new Set(context.initContext?.relatedFiles ?? []);
     // Step 2: extract file names from normalizedQuery or planSuggestion
     const extractedFiles = extractFilesFromAnalysis(context.analysis);
-    // Step 3: populate focus
-    context.analysis.focus = context.analysis.focus || { relevantFiles: [] };
-    context.analysis.focus.relevantFiles = extractedFiles.filter(f => knownFiles.has(f));
-    context.analysis.focus.missingFiles = extractedFiles.filter(f => !knownFiles.has(f));
-    context.analysis.focus.rationale = `Pre-check: ${context.analysis.focus.relevantFiles.length} files already available, ${context.analysis.focus.missingFiles.length} missing.`;
+    // Step 3: populate focus with safe defaults
+    const relevantFiles = extractedFiles.filter(f => knownFiles.has(f));
+    const missingFiles = extractedFiles.filter(f => !knownFiles.has(f));
+    context.analysis.focus.relevantFiles = relevantFiles;
+    context.analysis.focus.missingFiles = missingFiles;
+    context.analysis.focus.rationale = `Pre-check: ${relevantFiles.length} files already available, ${missingFiles.length} missing.`;
     // Optional: LLM call for semantic understanding (assumptions, constraints, risks)
     const prompt = `
 You are an AI meta-agent assisting with context verification. The user intent and plan suggestion are below.
@@ -46,32 +48,45 @@ Task:
   }
 }
 `.trim();
-    const ai = await generate({
-        query: context.initContext?.userQuery ?? '',
-        content: prompt
-    });
     try {
-        const cleaned = await cleanupModule.run({
+        const ai = await generate({
             query: context.initContext?.userQuery ?? '',
-            content: ai.data,
+            content: prompt
         });
-        let parsed;
-        if (typeof cleaned.data === "object" && cleaned.data !== null) {
-            parsed = cleaned.data;
+        let cleaned;
+        try {
+            cleaned = await cleanupModule.run({
+                query: context.initContext?.userQuery ?? '',
+                content: ai.data,
+            });
         }
-        else if (typeof cleaned.content === "string") {
-            parsed = JSON.parse(cleaned.content);
+        catch (cleanupErr) {
+            console.warn("[preFileSearchCheckStep] cleanupModule failed, using raw AI output", cleanupErr);
+            cleaned = { data: ai.data, content: ai.data };
         }
-        else {
-            throw new Error("Cleanup output is neither object nor string");
+        let parsed = {};
+        try {
+            if (typeof cleaned.data === "object" && cleaned.data !== null) {
+                parsed = cleaned.data;
+            }
+            else if (typeof cleaned.content === "string") {
+                parsed = JSON.parse(cleaned.content);
+            }
         }
-        context.analysis.focus.relevantFiles =
-            parsed.relevantFiles ?? context.analysis.focus.relevantFiles;
-        context.analysis.focus.missingFiles =
-            parsed.missingFiles ?? context.analysis.focus.missingFiles;
-        context.analysis.focus.rationale =
-            parsed.rationale ?? context.analysis.focus.rationale;
-        if (parsed.understanding) {
+        catch (parseErr) {
+            console.warn("[preFileSearchCheckStep] Failed to parse cleanup output, using defaults", parseErr);
+        }
+        // Merge parsed output safely
+        context.analysis.focus.relevantFiles = Array.isArray(parsed.relevantFiles)
+            ? parsed.relevantFiles
+            : context.analysis.focus.relevantFiles;
+        context.analysis.focus.missingFiles = Array.isArray(parsed.missingFiles)
+            ? parsed.missingFiles
+            : context.analysis.focus.missingFiles;
+        context.analysis.focus.rationale = typeof parsed.rationale === "string"
+            ? parsed.rationale
+            : context.analysis.focus.rationale;
+        if (parsed.understanding && typeof parsed.understanding === "object") {
             context.analysis.understanding = {
                 ...context.analysis.understanding,
                 ...parsed.understanding,
@@ -80,9 +95,9 @@ Task:
         logInputOutput("preFileSearchCheckStep", "output", parsed);
     }
     catch (err) {
-        console.warn("[preFileSearchCheckStep] Failed to parse AI output, using defaults", err);
+        console.warn("[preFileSearchCheckStep] AI pre-check failed, using defaults", err);
     }
-    // Simple regex-based extractor
+    // Simple regex-based extractor (always returns array)
     function extractFilesFromAnalysis(analysis) {
         const sources = [
             analysis?.intent?.normalizedQuery ?? "",

package/dist/agents/resolveExecutionModeStep.js

@@ -0,0 +1,47 @@
+export const resolveExecutionModeStep = {
+    name: "resolveExecutionMode",
+    description: "Derive a hard execution mode from the interpreted user intent. " +
+        "This decision is authoritative and must not be changed later.",
+    run: async (context) => {
+        const intent = context.analysis?.intent;
+        if (!intent) {
+            throw new Error("resolveExecutionMode: missing analysis.intent");
+        }
+        let mode;
+        let rationale = "";
+        switch (intent.intentCategory) {
+            case "codingTask":
+            case "refactorTask":
+                mode = "transform";
+                rationale = "User intent implies code modification.";
+                break;
+            case "debugging":
+            case "planning":
+                mode = "analyze";
+                rationale = "User intent implies investigation or reasoning.";
+                break;
+            case "question":
+                mode = "analyze"; // <-- run analysis for factual/code questions
+                rationale = "User intent requests factual/code analysis.";
+                break;
+            case "explanation":
+            case "writing":
+                mode = "explain";
+                rationale = "User intent requests text explanation only.";
+                break;
+            default:
+                mode = "explain";
+                rationale = "Defaulted to explanation due to unclear intent.";
+        }
+        context.executionControl = {
+            mode,
+            rationale,
+            confidence: intent.confidence,
+            constraints: {
+                allowAnalysis: mode !== "explain",
+                allowPlanning: mode === "transform",
+                allowFileWrites: mode === "transform"
+            }
+        };
+    }
+};

package/dist/index.js

@@ -118,18 +118,17 @@ function editInEditorAsync(initialContent = '') {
 async function startShell() {
     console.log(chalk.yellow("Welcome to SCAI shell!") + "\n" +
         chalk.blueBright(`- Type your query directly for short commands or questions.
+- Use !command to run terminal commands.
 - Use /command for built-in or custom commands.
   - /help
-  - /edit for pasting long queries, multi-line code, or anything complex, 
-    to open your configured editor (from $EDITOR) where you can freely paste,
-    edit, and save your input before executing.
-- Use !command to run terminal commands.`));
+  - /edit for pasting long queries & multi-line input
+  - /git commit\n`));
     while (true) {
         try {
             const { line } = (await prompt({
                 type: 'input',
                 name: 'line',
-                message: '\nWrite your query:\n',
+                message: 'Write your query:',
                 validate: (input) => !!input.trim() || 'Please enter something',
             }));
             const trimmed = line.trim();

package/dist/pipeline/modules/explainModule.js

@@ -0,0 +1,68 @@
+// File: src/pipeline/modules/explainModule.ts
+import { logInputOutput } from "../../utils/promptLogHelper.js";
+import { generate } from "../../lib/generate.js";
+export const explainModule = {
+    name: "explainModule",
+    description: "Generates a textual explanation for explain mode based on query and pre-file check context",
+    groups: ["finalize"],
+    run: async (input) => {
+        const query = input.query;
+        const context = input.context;
+        if (!context) {
+            throw new Error("[explainModule] No context provided");
+        }
+        // ---------------------------
+        // Gather preFileSearchCheck output
+        // ---------------------------
+        const focus = context.analysis?.focus ?? {};
+        const intent = context.analysis?.intent ?? {};
+        const rationale = context.analysis?.focus?.rationale ?? "No rationale available";
+        // ---------------------------
+        // Build prompt for the model
+        // ---------------------------
+        const prompt = `
+You are an AI assistant tasked with explaining the requested work.
+
+User query:
+${query}
+
+Intent (user goal):
+${JSON.stringify(intent, null, 2)}
+
+Relevant files:
+${JSON.stringify(focus.relevantFiles ?? [], null, 2)}
+
+Rationale for selected files:
+${rationale}
+
+INSTRUCTIONS:
+- Provide a concise explanation answering the user query based primarily on the query itself.
+- Use the intent and file rationale to support your explanation.
+- Do NOT suggest code changes.
+- Do NOT include unrelated folder summaries or analysis not yet performed.
+- Keep answer clear, factual, and direct.
+`.trim();
+        // ---------------------------
+        // Generate explanation
+        // ---------------------------
+        const aiResponse = await generate({
+            query,
+            content: prompt,
+        });
+        const explanationText = typeof aiResponse.data === "string" ? aiResponse.data : JSON.stringify(aiResponse.data, null, 2);
+        // ---------------------------
+        // Show explanation to user
+        // ---------------------------
+        console.log(`\n[EXPLAIN OUTPUT]\n${explanationText}\n`);
+        // ---------------------------
+        // Keep input/output logging
+        // ---------------------------
+        logInputOutput("explainModule", "output", aiResponse.data);
+        const output = {
+            query,
+            content: explanationText,
+            data: aiResponse.data,
+        };
+        return output;
+    },
+};

package/dist/pipeline/registry/moduleRegistry.js

@@ -5,11 +5,13 @@ import { cleanupModule } from "../modules/cleanupModule.js";
 import { summaryModule } from "../modules/summaryModule.js";
 import { addCommentsModule } from "../modules/commentModule.js";
 import { codeTransformModule } from "../modules/codeTransformModule.js";
+import { explainModule } from "../modules/explainModule.js";
 /**
  * Active built-in modules — all use ModuleIO for input/output.
  */
 export const builtInModules = {
     fileSearch: fileSearchModule,
+    explain: explainModule,
     summary: summaryModule,
     contextReview: contextReviewModule,
     // analysis (as agent options?)

package/package.json

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