scai 0.1.117 → 0.1.119

package/dist/agents/MainAgent.js

@@ -0,0 +1,255 @@
+import { builtInModules } from "../pipeline/registry/moduleRegistry.js";
+import { logInputOutput } from "../utils/promptLogHelper.js";
+import { planResolverStep } from "./planResolverStep.js";
+import { infoPlanGen } from "./infoPlanGenStep.js";
+import { understandIntentStep } from "./understandIntentStep.js";
+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";
+import { finalPlanGenStep } from "./finalPlanGenStep.js";
+/** Build a registry of all built-in modules */
+const MODULE_REGISTRY = Object.fromEntries(Object.entries(builtInModules).map(([name, mod]) => [name, mod]));
+/** Resolve a module from the registry */
+function resolveModuleForAction(action) {
+    const mod = MODULE_REGISTRY[action];
+    if (!mod)
+        console.warn(`⚠️ Missing module for action "${action}" — skipping`);
+    return mod;
+}
+export class MainAgent {
+    constructor(context) {
+        this.runCount = 0;
+        this.maxRuns = 2;
+        this.context = context;
+        this.query = context.initContext?.userQuery ?? '';
+    }
+    /** Generic step executor */
+    async executeStep(step, input) {
+        console.log(`\n`);
+        console.log(`\n =====================================================================================`);
+        console.log(`\n⚡ Executing step: ${step.action}`);
+        if (step.description)
+            console.log(`\n   --> Description: ${step.description}`);
+        console.log(`\n =====================================================================================`);
+        // attach the current step to the context
+        if (input.context) {
+            input.context.currentStep = step; // <-- new property
+        }
+        const mod = resolveModuleForAction(step.action);
+        if (!mod) {
+            return { query: input.query, content: input.content, data: { skipped: true }, context: input.context };
+        }
+        const moduleInput = {
+            query: step.description ?? input.query,
+            content: input.data ?? input.content,
+            context: input.context // shared reference
+        };
+        try {
+            console.log(`   ▶ Running module: ${mod.name}`);
+            const output = await mod.run(moduleInput);
+            if (!output)
+                throw new Error(`Module '${mod.name}' returned empty output`);
+            // Return only what matters — context is always the same reference
+            return {
+                query: step.description ?? input.query,
+                data: output.data,
+                context: input.context
+            };
+        }
+        catch (err) {
+            console.error(`   ❌ Module "${mod?.name}" failed:`, err);
+            return {
+                query: input.query,
+                content: input.content,
+                data: { error: String(err) },
+                context: input.context
+            };
+        }
+    }
+    /** Main run sequence */
+    async run() {
+        var _a;
+        this.runCount++;
+        console.log(`\n =====================================================================================`);
+        console.log(`🚀 ================= [AutonomousAgent] Starting run #${this.runCount} =================`);
+        logInputOutput("GlobalContext (structured)", "input", this.context);
+        // ---------------------------------------------------------------------
+        // GENERATE FOLDER-CAPSULE SUMMARIES
+        // ---------------------------------------------------------------------
+        if (this.context.initContext?.folderCapsules?.length) {
+            const capsulesSummary = this.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 ?? []
+            }));
+            // Add a human-readable summary for the LLM
+            (_a = this.context).analysis ?? (_a.analysis = {});
+            this.context.analysis.folderCapsulesSummary = capsulesSummary;
+            const humanReadable = capsulesSummary.map(fc => `- ${fc.path}: ${fc.fileCount} files, depth ${fc.depth}, confidence ${fc.confidence}`).join('\n');
+            this.context.analysis.folderCapsulesHuman = humanReadable;
+            console.log('\n📂 Folder Capsules Summary (for agent steps):\n', humanReadable);
+        }
+        // ---------------------------------------------------------------------
+        // 0️⃣ UNDERSTAND INTENT — First-pass interpretation of query
+        // ---------------------------------------------------------------------
+        console.log("\n🧠 Running understandIntentStep (pre-analysis fixture)\n");
+        await understandIntentStep.run({
+            context: this.context
+        });
+        // ---------------------------------------------------------------------
+        // 1️⃣ PLAN RESOLVER — Fast path (context-driven routing)
+        // ---------------------------------------------------------------------
+        await planResolverStep.run(this.context);
+        // --------------------------------------------------
+        // 🚦 ROUTING DECISION
+        // --------------------------------------------------
+        const routing = this.context.analysis?.routingDecision;
+        // ✅ FAST PATH: if planResolver thinks we have a final answer, wrap it in ModuleIO and return
+        if (routing?.decision === 'final-answer' && routing.answer) {
+            console.log("⚡ Fast path hit — returning final answer directly");
+            return {
+                query: this.query,
+                data: {
+                    finalAnswer: routing.answer,
+                    source: "planResolver",
+                },
+                context: this.context
+            };
+        }
+        // --------------------------------------------------
+        // ⏩ FALL THROUGH: continue with plan generation
+        // --------------------------------------------------
+        let textPlan;
+        // Use rationale from routing if available (temporary compatibility)
+        if (typeof routing?.rationale === 'string' && routing.rationale.trim()) {
+            textPlan = routing.rationale;
+        }
+        // Fallback: use the original query if no plan/rationale is available
+        if (!textPlan || textPlan.trim().length === 0) {
+            textPlan = this.query;
+        }
+        // textPlan can now be passed to planGeneratorStep
+        // ---------------------------------------------------------------------
+        // PRE-FILE-SEARCH CHECK (do we have the files required to continue )
+        // ---------------------------------------------------------------------
+        await preFileSearchCheckStep(this.context);
+        // ---------------------------------------------------------------------
+        // 2️⃣ INFO PLAN GENERATION (information-only steps)
+        // ---------------------------------------------------------------------
+        await infoPlanGen.run(this.context);
+        const infoPlan = this.context?.analysis?.planSuggestion?.plan ?? { steps: [] };
+        const infoSteps = infoPlan.steps.filter(s => s.groups?.includes("info"));
+        console.log("information gathering steps:\n");
+        console.dir(infoSteps);
+        let stepIO = {
+            query: this.query,
+            context: this.context
+        };
+        // =====================================================
+        // INFORMATION ACQUISITION PHASE
+        // Purpose: gather raw information, no interpretation
+        // =====================================================
+        //let count = 0;
+        for (const step of infoSteps) {
+            //count++;
+            stepIO = await this.executeStep(step, stepIO);
+            /* if (count === 4) {
+                debugContext(this.context, {
+                    step: "first step",
+                    note: "searchFiles?"
+                });
+            } */
+        }
+        // =====================================================
+        // ANALYSIS PHASE
+        // Purpose: understand what we have and what is being asked
+        // =====================================================
+        // 🎯 RELEVANT SOURCE SELECTION (authoritative narrowing)
+        console.log("\n📁 Selecting relevant source files\n");
+        await selectRelevantSourcesStep.run({ query: this.query, context: this.context });
+        // ANALYSIS PHASE (deterministic, durable)
+        console.log("\n🏗️ Running structural analysis\n");
+        await structuralAnalysisStep.run({ query: this.query, context: this.context });
+        // SEMANTIC ANALYSIS PHASE (LLM-driven)
+        console.log("\n🧠 Running semantic analysis\n");
+        await semanticAnalysisStep.run({ query: this.query, context: this.context });
+        // SEMANTIC PLAN TARGET FILES (moves focus -> plan.targetFiles)
+        console.log("\n🧠 Running plan target files\n");
+        await planTargetFilesStep.run({ query: this.query, context: this.context });
+        /* debugContext(this.context, {
+            step: "Semantic analysis step",
+            note: "semantic meaning?"
+        }); */
+        // VALIDATION PHASE
+        console.log("\n🧠 Running validation analysis\n");
+        await validationAnalysisStep.run({ query: this.query, context: this.context });
+        // =====================================================
+        // ROUTING / PLANNING PHASE
+        // =====================================================
+        const review = await contextReviewStep(this.context);
+        if (review.decision === "loopAgain" && this.runCount < this.maxRuns) {
+            console.log("🔄 Looping for additional context");
+            // Clear noisy bootstrap artifacts before looping
+            this.resetInitContextForLoop();
+            return this.run();
+        }
+        // =====================================================
+        // TRANSFORM PLAN GENERATION (after context review)
+        // Purpose: produce actionable transform steps
+        // =====================================================
+        console.log("\n🛠️ Generating transform plan\n");
+        await transformPlanGenStep.run(this.context);
+        // Filter transform steps
+        const transformPlan = this.context?.analysis?.planSuggestion?.plan ?? { steps: [] };
+        const transformSteps = transformPlan.steps.filter(s => s.groups?.includes("transform"));
+        console.log("transform steps:\n");
+        console.dir(transformSteps);
+        // =====================================================
+        // TRANSFORM PHASE
+        // Purpose: produce concrete changes or artifacts
+        // =====================================================
+        console.log("\n⚡ Running transform steps\n");
+        for (const step of transformSteps) {
+            stepIO = await this.executeStep(step, stepIO);
+        }
+        // =====================================================
+        // FINAL PLAN GENERATION
+        // Purpose: produce finalize / commit steps
+        // =====================================================
+        console.log("\n✅ Generating final plan\n");
+        await finalPlanGenStep.run(this.context);
+        // Filter finalize steps
+        const finalPlan = this.context?.analysis?.planSuggestion?.plan ?? { steps: [] };
+        const finalizeSteps = finalPlan.steps.filter(s => s.groups?.includes("finalize"));
+        console.log("finalize steps:\n");
+        console.dir(finalizeSteps);
+        // =====================================================
+        // FINALIZE PHASE
+        // Purpose: commit results and respond to the user
+        // =====================================================
+        for (const step of finalizeSteps) {
+            stepIO = await this.executeStep(step, stepIO);
+        }
+        console.log("🏁 Agent completed.");
+        console.log("---------------------------------------------\n");
+        console.log("Show final context\n", this.context);
+        return stepIO;
+    }
+    // =====================================================
+    // Helper: reset initContext for clean loop
+    // =====================================================
+    resetInitContextForLoop() {
+        if (this.context.initContext) {
+            this.context.initContext.relatedFiles = [];
+            console.log("   🧹 Cleared initContext.relatedFiles for clean loop");
+        }
+    }
+}

package/dist/agents/contextReviewStep.js

@@ -0,0 +1,104 @@
+// File: src/modules/contextReviewStep.ts
+import { generate } from "../lib/generate.js";
+import { logInputOutput } from "../utils/promptLogHelper.js";
+export async function contextReviewStep(context) {
+    if (!context.plan?.targetFiles || context.plan.targetFiles.length === 0) {
+        throw new Error("[contextReviewStep] No targetFiles defined in plan.");
+    }
+    // ------------------------------
+    // Authoritative view: only target files
+    // ------------------------------
+    const authoritativeFiles = (context.workingFiles ?? [])
+        .filter(f => context.plan.targetFiles.includes(f.path))
+        .map((f) => ({
+        path: f.path,
+        hasCode: Boolean(f.code),
+        code: f.code ?? null,
+        summary: f.summary ?? null,
+    }));
+    // ------------------------------
+    // Structural verification: only target files
+    // ------------------------------
+    const structuralProof = context.analysis?.structure
+        ? {
+            fileCount: context.analysis.structure.files.filter(f => context.plan.targetFiles.includes(f.path)).length,
+            files: context.analysis.structure.files
+                .filter(f => context.plan.targetFiles.includes(f.path))
+                .map(f => ({
+                path: f.path,
+                hasCode: Boolean(authoritativeFiles.find(af => af.path === f.path)?.code),
+            })),
+        }
+        : null;
+    // ------------------------------
+    // Include combined architecture analysis
+    // ------------------------------
+    const combinedAnalysis = context.analysis?.combinedAnalysis ?? {};
+    const architectureSummary = combinedAnalysis.architectureSummary ?? "";
+    const hotspots = combinedAnalysis.hotspots ?? [];
+    // ------------------------------
+    // Build prompt
+    // ------------------------------
+    const prompt = `
+You are a meta-reasoning agent responsible for determining whether the agent
+has sufficient information to proceed.
+
+IMPORTANT CONTRACT:
+- Any file listed below with a non-null "code" field MUST be treated as the
+  complete and authoritative source code for that file.
+- Do NOT request file contents again if "code" is present.
+
+User intent:
+${JSON.stringify(context.analysis?.intent ?? {}, null, 2)}
+
+Authoritative source files:
+${JSON.stringify(authoritativeFiles, null, 2)}
+
+Structural verification:
+${JSON.stringify(structuralProof, null, 2)}
+
+Combined architecture analysis:
+{
+  "architectureSummary": ${JSON.stringify(architectureSummary, null, 2)}
+}
+
+Your task:
+1. Determine whether the available information is sufficient to fulfill the user intent.
+2. If NOT sufficient, explicitly list what is missing.
+3. Output STRICT JSON with the following shape:
+
+{
+  "decision": "loopAgain" | "stop",
+  "reason": "string",
+  "missing": string[]
+}
+
+Rules:
+- If the intent involves modifying, commenting, refactoring, or analyzing code,
+  and at least one relevant file includes full source code, the context SHOULD
+  be considered sufficient.
+- Do NOT request information that is already present in the authoritative files.
+`.trim();
+    // ------------------------------
+    // Call LLM
+    // ------------------------------
+    const ai = await generate({
+        query: context.initContext?.userQuery ?? '',
+        content: prompt,
+    });
+    const text = typeof ai.data === "string" ? ai.data : JSON.stringify(ai.data);
+    logInputOutput("contextReviewHelper", "output", text);
+    // ------------------------------
+    // Parse JSON or fallback
+    // ------------------------------
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {
+            decision: text.toLowerCase().includes("loop") ? "loopAgain" : "stop",
+            reason: text,
+            missing: [],
+        };
+    }
+}

package/dist/agents/finalPlanGenStep.js

@@ -0,0 +1,123 @@
+// File: src/agents/finalPlanGenStep.ts
+import { generate } from '../lib/generate.js';
+import { PLAN_ACTIONS } from '../utils/planActions.js';
+import { logInputOutput } from '../utils/promptLogHelper.js';
+import { cleanupModule } from '../pipeline/modules/cleanupModule.js';
+const MAX_STEPS = 100;
+/**
+ * FINAL PLAN GENERATOR
+ * Generates steps that finalize results, commit changes, or prepare outputs.
+ */
+export const finalPlanGenStep = {
+    name: 'finalPlanGen',
+    description: 'Generates finalization steps to wrap up and commit results.',
+    requires: ['analysis.intent', 'analysis.focus'],
+    produces: ['analysis.planSuggestion'],
+    async run(context) {
+        var _a, _b;
+        context.analysis || (context.analysis = {});
+        (_a = context.analysis).planSuggestion || (_a.planSuggestion = {});
+        (_b = context.analysis.planSuggestion).plan || (_b.plan = { steps: [] });
+        // Restrict actions to FINALIZE group only
+        const effectiveActions = PLAN_ACTIONS.filter(a => a.groups?.includes('finalize'));
+        const actionsJson = JSON.stringify(effectiveActions, null, 2);
+        const intentText = context.analysis.intent?.normalizedQuery ?? '';
+        const intentCategory = context.analysis.intent?.intentCategory ?? '';
+        const prompt = `
+You are an autonomous coding agent.
+Your task is to produce a structured plan describing finalization steps
+to wrap up work, commit changes, or produce outputs safely.
+
+Intent / task description:
+${intentText}
+
+If the intent indicates that no finalization is required, return an empty plan object with an empty "steps" array:
+{ "steps": [] }
+
+Allowed actions (finalize only):
+${actionsJson}
+
+Task category:
+${intentCategory}
+
+Folder structure:
+${context.analysis.folderCapsulesHuman ?? ''}
+
+Existing relevant files:
+${JSON.stringify(context.analysis.focus?.relevantFiles ?? {}, null, 2)}
+
+⚡ Phase guidance:
+- Actions are grouped into phases: info, transform, finalize.
+- Only include finalize steps in this phase.
+- Each step must include: "action", "targetFile" (optional), "description", "metadata"
+
+Return a strictly valid JSON plan:
+
+{
+  "steps": [
+    { "action": "stepName", "targetFile": "optional/path.ts", "description": "explanation", "metadata": {} }
+  ]
+}
+        `.trim();
+        try {
+            console.log('FinalPlanGenStep prompt', prompt);
+            const genInput = { query: intentText, content: prompt };
+            const genOutput = await generate(genInput);
+            const raw = typeof genOutput.data === 'string'
+                ? genOutput.data
+                : JSON.stringify(genOutput.data ?? '{}');
+            const cleaned = await cleanupModule.run({ query: intentText, content: raw });
+            const jsonString = typeof cleaned.content === 'string'
+                ? cleaned.content
+                : JSON.stringify(cleaned.content ?? '{}');
+            let plan = JSON.parse(jsonString);
+            if (!plan || !Array.isArray(plan.steps))
+                throw new Error('Invalid final plan structure');
+            if (plan.steps.length > MAX_STEPS)
+                plan.steps = plan.steps.slice(0, MAX_STEPS);
+            // Map groups & metadata
+            plan.steps = plan.steps.map(step => {
+                const actionDef = PLAN_ACTIONS.find(a => a.action === step.action);
+                return {
+                    ...step,
+                    metadata: {
+                        ...step.metadata,
+                        routingConfidence: context.analysis?.routingDecision?.confidence ?? 0
+                    },
+                    groups: actionDef?.groups ?? ['finalize']
+                };
+            });
+            // Ensure at least one summary step if plan is empty
+            if (plan.steps.length === 0) {
+                plan.steps.push({
+                    action: 'finalizeSummary',
+                    description: 'Summarize what actions were taken and provide a response to the user.',
+                    metadata: {
+                        routingConfidence: context.analysis?.routingDecision?.confidence ?? 0
+                    },
+                    groups: ['finalize']
+                });
+            }
+            // Replace existing finalize steps in planSuggestion
+            context.analysis.planSuggestion.plan.steps = [
+                ...context.analysis.planSuggestion.plan.steps.filter(s => !s.groups?.includes('finalize')),
+                ...plan.steps
+            ];
+            logInputOutput('finalPlanGen', 'output', plan);
+        }
+        catch (err) {
+            console.warn('⚠️ Failed to generate final plan:', err);
+            context.analysis.planSuggestion.plan.steps = [
+                {
+                    action: 'finalizeSummary',
+                    description: 'Summarize what actions were taken and provide a response to the user.',
+                    metadata: {
+                        routingConfidence: context.analysis?.routingDecision?.confidence ?? 0
+                    },
+                    groups: ['finalize']
+                }
+            ];
+            logInputOutput('finalPlanGen', 'output', context.analysis.planSuggestion.plan);
+        }
+    }
+};

package/dist/agents/infoPlanGenStep.js

@@ -0,0 +1,126 @@
+import { generate } from '../lib/generate.js';
+import { PLAN_ACTIONS } from '../utils/planActions.js';
+import { logInputOutput } from '../utils/promptLogHelper.js';
+import { cleanupModule } from '../pipeline/modules/cleanupModule.js';
+const MAX_STEPS = 100;
+/**
+ * INFO PLAN GENERATOR
+ * Generates information-gathering steps only.
+ */
+export const infoPlanGen = {
+    name: 'infoPlanGen',
+    description: 'Generates an information-acquisition plan.',
+    requires: ['userQuery', 'analysis.intent'],
+    produces: ['analysis.planSuggestion'],
+    async run(context) {
+        context.analysis || (context.analysis = {});
+        // --------------------------------------------------
+        // Always discard any existing info plan
+        // (planner may loop; old plans must not survive)
+        // --------------------------------------------------
+        delete context.analysis.planSuggestion?.plan;
+        // --------------------------------------------------
+        // Check for missing files
+        // --------------------------------------------------
+        const missingFiles = Array.isArray(context.analysis.focus?.missingFiles)
+            ? context.analysis.focus.missingFiles
+            : [];
+        if (missingFiles.length === 0) {
+            console.log('ℹ️ No missing files — returning empty info plan.');
+            context.analysis.planSuggestion = { plan: { steps: [] } };
+            logInputOutput('infoPlanGen', 'output', { steps: [] });
+            return;
+        }
+        // --------------------------------------------------
+        // Restrict actions to INFO phase only
+        // --------------------------------------------------
+        const effectiveActions = PLAN_ACTIONS.filter(a => a.groups?.includes('info'));
+        const actionsJson = JSON.stringify(effectiveActions, null, 2);
+        console.log('Actions: ', actionsJson);
+        const intentText = context.analysis.intent?.normalizedQuery ??
+            context.initContext?.userQuery ??
+            '';
+        const intentCategory = context.analysis.intent?.intentCategory ?? '';
+        const prompt = `
+You are an autonomous coding agent.
+Based on the allowed actions you task is to produce a structured plan describing what information should be gathered
+in order to understand and solve the task.
+
+Allowed actions (information acquisition only):
+${actionsJson}
+
+Intent / task description:
+${intentText}
+
+Below is gathered information about the repository:
+
+Task category:
+${intentCategory}
+
+Folder structure:
+${context.analysis.folderCapsulesHuman ?? ''}
+
+Existing relevant files:
+${JSON.stringify(context.analysis.focus?.relevantFiles ?? {}, null, 2)}
+
+Missing files:
+${JSON.stringify(missingFiles, null, 2)}
+
+Return a structured JSON plan describing which information to gather.
+
+JSON schema:
+{
+  "steps": [
+    {
+      "action": "stepName",
+      "targetFile": "optional/path.ts",
+      "description": "explanation",
+      "metadata": {}
+    }
+  ]
+}
+        `.trim();
+        try {
+            const genInput = {
+                query: intentText,
+                content: prompt
+            };
+            const genOutput = await generate(genInput);
+            const raw = typeof genOutput.data === 'string'
+                ? genOutput.data
+                : JSON.stringify(genOutput.data ?? '{}');
+            const cleaned = await cleanupModule.run({
+                query: intentText,
+                content: raw
+            });
+            const jsonString = typeof cleaned.content === 'string'
+                ? cleaned.content
+                : JSON.stringify(cleaned.content ?? '{}');
+            let plan = JSON.parse(jsonString);
+            if (!plan || !Array.isArray(plan.steps)) {
+                throw new Error('Invalid info plan structure');
+            }
+            if (plan.steps.length > MAX_STEPS) {
+                plan.steps = plan.steps.slice(0, MAX_STEPS);
+            }
+            plan.steps = plan.steps.map((step) => {
+                const actionDef = PLAN_ACTIONS.find(a => a.action === step.action);
+                return {
+                    ...step,
+                    metadata: {
+                        ...step.metadata,
+                        routingConfidence: context.analysis?.routingDecision?.confidence ?? 0
+                    },
+                    groups: actionDef?.groups ?? []
+                };
+            });
+            context.analysis.planSuggestion = { plan };
+            logInputOutput('infoPlanGen', 'output', plan);
+        }
+        catch (err) {
+            console.warn('⚠️ Failed to generate info plan:', err);
+            context.analysis.planSuggestion = { plan: { steps: [] } };
+            logInputOutput('infoPlanGen', 'output', { steps: [] });
+        }
+    }
+};