scai 0.1.178 → 1.0.1

package/dist/agents/selectRelevantSourcesStep.js

@@ -3,7 +3,7 @@ import fs from "fs";
 import { logInputOutput } from "../utils/promptLogHelper.js";
 /**
  * Purpose:
- * Mirrors previously selected files into workingFiles.
+ * Mirrors resolver-selected execution files into workingFiles.
  * - Does NOT promote files based on evidence.
  * - Candidate files are left untouched.
  * - Rationale is preserved from preFileSearchCheckStep.
@@ -18,11 +18,17 @@ export const selectRelevantSourcesStep = {
         if (!context?.analysis?.focus) {
             throw new Error("[selectRelevantSources] context.analysis.focus is required.");
         }
-        const selectedFiles = context.analysis.focus.selectedFiles ?? [];
+        const executionPolicy = context.analysis.executionPolicy;
+        const useExecutionLane = Boolean(executionPolicy?.phaseAllowed?.transform) &&
+            Boolean(executionPolicy?.routeAllowed?.transform) &&
+            (executionPolicy?.executionRequired?.length ?? 0) > 0;
+        const selectedFiles = useExecutionLane
+            ? executionPolicy?.executionRequired ?? []
+            : context.analysis.focus.selectedFiles ?? [];
         const candidateFiles = context.analysis.focus.candidateFiles ?? [];
         const discardedFiles = []; // no reasoning done here
         // ---------------------------
-        // 1️⃣ Populate workingFiles from selectedFiles only
+        // 1️⃣ Populate workingFiles from execution lane first (fallback: selectedFiles)
         // ---------------------------
         const workingFiles = [];
         for (const path of selectedFiles) {
@@ -58,17 +64,19 @@ export const selectRelevantSourcesStep = {
             candidateFiles,
             discardedFiles,
             rationale: (context.analysis.focus.rationale ?? "") +
-                "\n[selectRelevantSources] Working files mirrored mechanically from previous selections.",
+                "\n[selectRelevantSources] Working files mirrored from execution lane snapshot.",
         };
         const output = {
             query,
             data: {
                 workingFiles: context.workingFiles.map(f => ({ path: f.path })),
                 selectedFiles,
-                candidateFiles
+                candidateFiles,
+                executionLock: executionPolicy?.executionLock ?? null,
             },
         };
         logInputOutput("selectRelevantSources", "output", output.data);
         return output;
     },
 };
+//# sourceMappingURL=selectRelevantSourcesStep.js.map

package/dist/agents/selectRelevantSourcesStep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectRelevantSourcesStep.js","sourceRoot":"","sources":["../../src/agents/selectRelevantSourcesStep.ts"],"names":[],"mappings":"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","sourcesContent":["// File: src/modules/selectRelevantSourcesStep.ts\nimport fs from \"fs\";\nimport { logInputOutput } from \"../utils/promptLogHelper.js\";\nimport type { Module, ModuleIO, StructuredFileCapsule } from \"../types.js\";\n\n/**\n * Purpose:\n * Mirrors resolver-selected execution files into workingFiles.\n * - Does NOT promote files based on evidence.\n * - Candidate files are left untouched.\n * - Rationale is preserved from preFileSearchCheckStep.\n */\nexport const selectRelevantSourcesStep: Module = {\n  name: \"selectRelevantSources\",\n  description:\n    \"Mirrors focus.selectedFiles into workingFiles without reasoning over evidence.\",\n  groups: [\"analysis\"],\n\n  run: async (input: ModuleIO): Promise<ModuleIO> => {\n    const query = input.query ?? \"\";\n    const context = input.context;\n\n    if (!context?.analysis?.focus) {\n      throw new Error(\"[selectRelevantSources] context.analysis.focus is required.\");\n    }\n\n    const executionPolicy = context.analysis.executionPolicy;\n    const useExecutionLane =\n      Boolean(executionPolicy?.phaseAllowed?.transform) &&\n      Boolean(executionPolicy?.routeAllowed?.transform) &&\n      (executionPolicy?.executionRequired?.length ?? 0) > 0;\n    const selectedFiles =\n      useExecutionLane\n        ? executionPolicy?.executionRequired ?? []\n        : context.analysis.focus.selectedFiles ?? [];\n    const candidateFiles = context.analysis.focus.candidateFiles ?? [];\n    const discardedFiles: string[] = []; // no reasoning done here\n\n    // ---------------------------\n    // 1️⃣ Populate workingFiles from execution lane first (fallback: selectedFiles)\n    // ---------------------------\n    const workingFiles: StructuredFileCapsule[] = [];\n\n    for (const path of selectedFiles) {\n      let code: string | undefined;\n      try {\n        code = fs.readFileSync(path, \"utf-8\");\n      } catch {\n        code = undefined;\n      }\n      workingFiles.push({\n        path,\n        code,\n        selectionReason: \"Selected by preFileSearchCheckStep\",\n      });\n    }\n\n    // Deduplicate if anything preexists\n    const seen = new Set<string>();\n    context.workingFiles = [\n      ...(context.workingFiles ?? []),\n      ...workingFiles.filter(f => {\n        if (!f.path || seen.has(f.path)) return false;\n        seen.add(f.path);\n        return true;\n      }),\n    ];\n\n    // ---------------------------\n    // 2️⃣ Preserve focus but update rationale\n    // ---------------------------\n    context.analysis.focus = {\n      selectedFiles,\n      candidateFiles,\n      discardedFiles,\n      rationale:\n        (context.analysis.focus.rationale ?? \"\") +\n        \"\\n[selectRelevantSources] Working files mirrored from execution lane snapshot.\",\n    };\n\n    const output: ModuleIO = {\n      query,\n      data: {\n        workingFiles: context.workingFiles.map(f => ({ path: f.path })),\n        selectedFiles,\n        candidateFiles,\n        executionLock: executionPolicy?.executionLock ?? null,\n      },\n    };\n\n    logInputOutput(\"selectRelevantSources\", \"output\", output.data);\n    return output;\n  },\n};\n"]}

package/dist/agents/structuralPreloadStep.js

@@ -4,13 +4,13 @@ import { logInputOutput } from "../utils/promptLogHelper.js";
 /**
  * Structural preload:
  * - Calls buildInDepthContext for candidate files.
- * - Extracts structural facts only.
+ * - Extracts structural facts only, without requiring KG enrichment.
  * - 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.",
+    description: "Preloads structural file facts into fileAnalysis without performing reasoning.",
     groups: ["analysis"],
     run: async (input) => {
         const query = input.query ?? "";
@@ -39,8 +39,6 @@ export const structuralPreloadStep = {
         // ---- 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)) {
@@ -59,3 +57,4 @@ export const structuralPreloadStep = {
         return { query, data: {} };
     },
 };
+//# sourceMappingURL=structuralPreloadStep.js.map

package/dist/agents/structuralPreloadStep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuralPreloadStep.js","sourceRoot":"","sources":["../../src/agents/structuralPreloadStep.ts"],"names":[],"mappings":"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","sourcesContent":["// File: src/modules/structuralPreloadStep.ts\n\nimport { buildInDepthContext } from \"../utils/buildContextualPrompt.js\";\nimport { logInputOutput } from \"../utils/promptLogHelper.js\";\nimport type { Module, ModuleIO, StructuredContext } from \"../types.js\";\n\n/**\n * Structural preload:\n * - Calls buildInDepthContext for candidate files.\n * - Extracts structural facts only, without requiring KG enrichment.\n * - Populates analysis.fileAnalysis[path].structural.\n * - Does NOT reason or assign relevance.\n */\nexport const structuralPreloadStep: Module = {\n    name: \"structuralPreload\",\n    description:\n        \"Preloads structural file facts into fileAnalysis without performing reasoning.\",\n    groups: [\"analysis\"],\n\n    run: async (input: ModuleIO): Promise<ModuleIO> => {\n        const query = input.query ?? \"\";\n        const context = input.context as StructuredContext;\n\n        if (!context?.analysis) {\n            throw new Error(\"[structuralPreload] context.analysis is required.\");\n        }\n\n        // ---- Ensure fileAnalysis exists (type-safe) ----\n        if (!context.analysis.fileAnalysis) {\n            context.analysis.fileAnalysis = {};\n        }\n        const fileAnalysis = context.analysis.fileAnalysis;\n\n        // ---- Candidate files ----\n        const candidatePaths: string[] = [\n            ...(context.initContext?.relatedFiles ?? []),\n        ];\n        const uniquePaths = Array.from(new Set(candidatePaths));\n\n        if (!uniquePaths.length) {\n            console.warn(\"[structuralPreload] No candidate files to preload.\");\n            return { query, data: {} };\n        }\n\n        // ---- Only preload missing structural data ----\n        const pathsNeedingStructure = uniquePaths.filter(\n            (p) => !fileAnalysis[p]?.structural\n        );\n        if (!pathsNeedingStructure.length) return { query, data: {} };\n\n        // ---- Get structural data (path → structural object) ----\n        const structuralMap = await buildInDepthContext({\n            filenames: pathsNeedingStructure,\n        });\n\n        // ---- Merge into fileAnalysis ----\n        for (const [path, structural] of Object.entries(structuralMap)) {\n            fileAnalysis[path] ??= { semanticAnalyzed: false };\n            fileAnalysis[path].structural = structural;\n        }\n\n        // ---- Minimal structured log ----\n        const logSummary = Object.entries(fileAnalysis).map(([path, analysis]) => ({\n            file: path,\n            hasStructural: !!analysis.structural,\n            functions: analysis.structural?.functions?.length ?? 0,\n            classes: analysis.structural?.classes?.length ?? 0,\n            imports: analysis.structural?.imports?.length ?? 0,\n        }));\n\n        logInputOutput(\"structuralPreload\", \"output\", logSummary);\n\n        return { query, data: {} };\n    },\n};\n"]}

package/dist/agents/transformPlanGenStep.js

@@ -1,12 +1,23 @@
-// File: src/agents/transformPlanGenStep.ts
+/**
+ * Builds one-file transform plans from user intent and local file evidence.
+ *
+ * Why this file exists:
+ * - the agent needs typed transform steps before it can call the runtime action router
+ * - plan generation stays narrow so single-file edits do not spill into unrelated files
+ */
 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';
+/**
+ * Refactor note:
+ * - Transform planner emits typed actions and optional doneWhenRegex hints.
+ * - Why it exists: deterministic completion checks should be planner-assisted.
+ */
 /**
  * TRANSFORM PLAN GENERATOR
  * Generates one or more code transformation steps per iteration,
- * strictly scoped to the current TaskStep file.
+ * strictly scoped to the current durable Step file.
  */
 export const transformPlanGenStep = {
     name: 'transformPlanGen',
@@ -37,9 +48,11 @@ export const transformPlanGenStep = {
         const actionsJson = JSON.stringify(effectiveActions, null, 2);
         const intentText = context.analysis.intent?.normalizedQuery ?? '';
         const intentCategory = context.analysis.intent?.intentCategory ?? '';
+        const orderedQuestions = context.analysis.intent?.questions ?? [];
         const fileAnalysis = context.analysis.fileAnalysis ?? {};
         // ✅ Use currentStep file
         const targetFile = currentStep.filePath;
+        const currentQuestionId = currentStep.questionId ?? (orderedQuestions.length === 1 ? orderedQuestions[0].id : undefined);
         // Guard: nothing to transform
         if (!targetFile || !fileAnalysis[targetFile]) {
             context.analysis.planSuggestion = { plan: { steps: [] } };
@@ -82,6 +95,8 @@ ${actionsJson}
 Excerpts (localized hints):
 ${JSON.stringify(excerpts, null, 2)}
 
+${orderedQuestions.length > 0 ? `Ordered question parts:\n${JSON.stringify(orderedQuestions, null, 2)}\n` : ""}
+
 Rules:
 - Use excerpts ONLY to infer WHERE changes occur
 - You MAY reference startLine/endLine ONLY if they are present
@@ -90,11 +105,12 @@ Rules:
 - If the intent implies multiple operations (e.g. move = remove + append),
   generate multiple steps in logical order
 - Only include transform steps
-- Each step must include: action, targetFile, description, metadata
+- Each step must include: action, actionId, actionArgs, targetFile, description, metadata
+- If possible include metadata.doneWhenRegex = { filePath, pattern, flags } for deterministic completion checks.
 
 Return strictly valid JSON:
 
-{ "steps": [ { "action": "stepName", "targetFile": "${targetFile}", "description": "what to do and where (using excerpt hints)", "metadata": {} } ] }
+{ "steps": [ { "action": "stepName", "actionId": "stepName", "actionArgs": {}, "targetFile": "${targetFile}", "description": "what to do and where (using excerpt hints)", "metadata": { "doneWhenRegex": { "filePath": "${targetFile}", "pattern": "...", "flags": "m" } } } ] }
 `.trim()
             : `
 You are an autonomous coding agent.
@@ -115,40 +131,64 @@ ${intentCategory}
 Allowed actions (transform only):
 ${actionsJson}
 
+${orderedQuestions.length > 0 ? `Ordered question parts:\n${JSON.stringify(orderedQuestions, null, 2)}\n` : ""}
+
 Rules:
 - Plan purely from intent
 - If the intent implies multiple operations (e.g. move = remove + append),
   generate multiple steps in logical order
 - Do NOT include any location hints or references
 - Only include transform steps
-- Each step must include: action, targetFile, description, metadata
+- Each step must include: action, actionId, actionArgs, targetFile, description, metadata
+- If possible include metadata.doneWhenRegex = { filePath, pattern, flags } for deterministic completion checks.
 
 Return strictly valid JSON:
 
-{ "steps": [ { "action": "stepName", "targetFile": "${targetFile}", "description": "what to do (no location hints)", "metadata": {} } ] }
+{ "steps": [ { "action": "stepName", "actionId": "stepName", "actionArgs": {}, "targetFile": "${targetFile}", "description": "what to do (no location hints)", "metadata": { "doneWhenRegex": { "filePath": "${targetFile}", "pattern": "...", "flags": "m" } } } ] }
 `.trim();
         try {
             const genInput = { query: intentText, content: prompt };
-            const genOutput = await generate(genInput);
+            const genOutput = await generate(genInput, {
+                caller: "transformPlanGenStep",
+                inputContext: {
+                    intentText,
+                    intentCategory,
+                    targetFile,
+                    orderedQuestions,
+                    currentQuestionId,
+                    hasExcerpts,
+                    excerpts,
+                    allowedActions: effectiveActions,
+                },
+            });
             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 parsed = null;
-            try {
-                parsed = JSON.parse(jsonString);
+            if (typeof cleaned.data === 'object' && cleaned.data !== null) {
+                parsed = cleaned.data;
             }
-            catch {
-                parsed = null;
+            else if (typeof cleaned.content === 'string') {
+                try {
+                    parsed = JSON.parse(cleaned.content);
+                }
+                catch {
+                    parsed = null;
+                }
             }
-            const steps = Array.isArray(parsed?.steps) ? parsed.steps : [];
+            const parsedSteps = Array.isArray(parsed?.steps) ? parsed.steps : null;
+            const fallbackStep = buildFallbackTransformStep(targetFile, fa, context.analysis?.routingDecision?.confidence, currentQuestionId);
+            // Keep an explicit empty planner result as a real no-op.
+            const effectiveSteps = parsedSteps ?? (fallbackStep ? [fallbackStep] : []);
             // Normalize steps: enforce targetFile, groups, metadata
-            const normalizedSteps = steps.map((step, index) => {
+            const normalizedSteps = effectiveSteps.map((step, index) => {
                 step.id = `transform:${targetFile}:${index + 1}`;
                 step.targetFile = targetFile;
+                // ActionRouter consumes actionId/actionArgs; action is kept for backward compatibility.
+                step.actionId = step.actionId ?? step.action;
+                step.actionArgs = step.actionArgs ?? {};
+                step.questionId = step.questionId ?? currentQuestionId;
                 const actionDef = PLAN_ACTIONS.find(a => a.action === step.action);
                 step.groups = actionDef?.groups ?? ['transform'];
                 const confidence = context.analysis?.routingDecision?.confidence;
@@ -161,11 +201,58 @@ Return strictly valid JSON:
                 return step;
             });
             context.analysis.planSuggestion = { plan: { steps: normalizedSteps } };
-            logInputOutput('transformPlanGen', 'output', normalizedSteps);
+            logInputOutput('transformPlanGen', 'output', {
+                callId: genOutput.trace?.callId,
+                source: parsedSteps
+                    ? 'model'
+                    : (fallbackStep ? 'fallback' : 'empty'),
+                steps: normalizedSteps,
+            });
         }
         catch (err) {
             console.warn('⚠️ Failed to generate transform plan:', err);
-            context.analysis.planSuggestion = { plan: { steps: [] } };
+            const fallbackStep = buildFallbackTransformStep(targetFile, fa, context.analysis?.routingDecision?.confidence, currentQuestionId);
+            const fallbackSteps = fallbackStep ? [fallbackStep] : [];
+            context.analysis.planSuggestion = { plan: { steps: fallbackSteps } };
+            logInputOutput('transformPlanGen', 'output', {
+                source: fallbackStep ? 'fallback-after-error' : 'empty-after-error',
+                steps: fallbackSteps,
+            });
         }
     }
 };
+/**
+ * Builds a safe one-step transform fallback from semantic analysis when plan JSON is missing.
+ *
+ * Example:
+ * - summary "Add a hello world comment near the imports" -> one `codeTransform` step with that description
+ * - shouldModify false -> no fallback step
+ */
+function buildFallbackTransformStep(targetFile, fileAnalysis, routingConfidence, currentQuestionId) {
+    if (!fileAnalysis?.action?.shouldModify) {
+        return null;
+    }
+    const summary = fileAnalysis.proposedChanges?.summary?.trim();
+    const rationale = fileAnalysis.proposedChanges?.rationale?.trim();
+    const description = [summary, rationale].filter(Boolean).join(" ");
+    if (!description) {
+        return null;
+    }
+    return {
+        id: `transform:${targetFile}:fallback`,
+        action: "codeTransform",
+        actionId: "codeTransform",
+        actionArgs: {},
+        targetFile,
+        questionId: currentQuestionId,
+        description,
+        groups: ["transform"],
+        metadata: {
+            source: "semantic-fallback",
+            ...(typeof routingConfidence === "number" && routingConfidence > 0
+                ? { routingConfidence }
+                : {}),
+        },
+    };
+}
+//# sourceMappingURL=transformPlanGenStep.js.map

package/dist/agents/transformPlanGenStep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformPlanGenStep.js","sourceRoot":"","sources":["../../src/agents/transformPlanGenStep.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Builds one-file transform plans from user intent and local file evidence.\n *\n * Why this file exists:\n * - the agent needs typed transform steps before it can call the runtime action router\n * - plan generation stays narrow so single-file edits do not spill into unrelated files\n */\nimport { generate } from '../lib/generate.js';\nimport { PLAN_ACTIONS } from '../utils/planActions.js';\nimport { logInputOutput } from '../utils/promptLogHelper.js';\nimport { cleanupModule } from '../pipeline/modules/cleanupModule.js';\nimport type { ModuleIO, StructuredContext, AgentPlanStep, FileAnalysis } from '../types.js';\n\n/**\n * Refactor note:\n * - Transform planner emits typed actions and optional doneWhenRegex hints.\n * - Why it exists: deterministic completion checks should be planner-assisted.\n */\n/**\n * TRANSFORM PLAN GENERATOR\n * Generates one or more code transformation steps per iteration,\n * strictly scoped to the current durable Step file.\n */\nexport const transformPlanGenStep = {\n    name: 'transformPlanGen',\n    description: 'Generates code transformation steps for a single target file.',\n\n    requires: ['analysis.intent', 'analysis.focus', 'analysis.fileAnalysis', 'task.currentStep'],\n    produces: ['analysis.planSuggestion'],\n\n    async run(context: StructuredContext): Promise<void> {\n        // ✅ Fail early if no task\n        if (!context.task) {\n            throw new Error(\"transformPlanGen: missing context.task\");\n        }\n\n        // ✅ Fail early if no current step\n        const currentStep = context.task.currentStep;\n        if (!currentStep) {\n            throw new Error(\"transformPlanGen: missing context.task.currentStep\");\n        }\n\n        context.analysis ||= {};\n        context.execution ||= {};\n\n        // Always clear previous transform plan\n        delete context.analysis.planSuggestion;\n\n        // Restrict actions to TRANSFORM only\n        const effectiveActions = PLAN_ACTIONS.filter(a => a.groups?.includes('transform'));\n        if (!effectiveActions.length) {\n            context.analysis.planSuggestion = { plan: { steps: [] } };\n            logInputOutput('transformPlanGen', 'output', { steps: [] });\n            return;\n        }\n\n        const actionsJson = JSON.stringify(effectiveActions, null, 2);\n        const intentText = context.analysis.intent?.normalizedQuery ?? '';\n        const intentCategory = context.analysis.intent?.intentCategory ?? '';\n        const orderedQuestions = context.analysis.intent?.questions ?? [];\n\n        const fileAnalysis: Record<string, FileAnalysis> = context.analysis.fileAnalysis ?? {};\n\n        // ✅ Use currentStep file\n        const targetFile = currentStep.filePath;\n        const currentQuestionId = currentStep.questionId ?? (orderedQuestions.length === 1 ? orderedQuestions[0].id : undefined);\n\n        // Guard: nothing to transform\n        if (!targetFile || !fileAnalysis[targetFile]) {\n            context.analysis.planSuggestion = { plan: { steps: [] } };\n            logInputOutput('transformPlanGen', 'output', { steps: [] });\n            return;\n        }\n\n        const fa = fileAnalysis[targetFile];\n\n        const excerpts = fa.excerpts?.map(e => ({\n            description: e.description,\n            startLine: e.startLine,\n            endLine: e.endLine,\n            symbols: e.symbols,\n            code: e.code\n        })) ?? [];\n\n        const hasExcerpts = excerpts.length > 0;\n\n        // Build prompt\n        const prompt = hasExcerpts\n            ? `\nYou are an autonomous coding agent.\n\nYour task is to generate a transform plan using ONLY:\n- the user intent\n- the provided excerpts as localized hints\n\nIMPORTANT CONSTRAINTS:\n- All steps MUST target the same file: ${targetFile}\n- Do NOT reference or modify any other file\n- Do NOT invent file structure beyond what excerpts explicitly show\n- Do NOT infer missing excerpt fields\n\nIntent:\n${intentText}\n\nTask category:\n${intentCategory}\n\nAllowed actions (transform only):\n${actionsJson}\n\nExcerpts (localized hints):\n${JSON.stringify(excerpts, null, 2)}\n\n${orderedQuestions.length > 0 ? `Ordered question parts:\\n${JSON.stringify(orderedQuestions, null, 2)}\\n` : \"\"}\n\nRules:\n- Use excerpts ONLY to infer WHERE changes occur\n- You MAY reference startLine/endLine ONLY if they are present\n- You MAY reference description or symbols if useful\n- Treat code snippets as context, not as the full file\n- If the intent implies multiple operations (e.g. move = remove + append),\n  generate multiple steps in logical order\n- Only include transform steps\n- Each step must include: action, actionId, actionArgs, targetFile, description, metadata\n- If possible include metadata.doneWhenRegex = { filePath, pattern, flags } for deterministic completion checks.\n\nReturn strictly valid JSON:\n\n{ \"steps\": [ { \"action\": \"stepName\", \"actionId\": \"stepName\", \"actionArgs\": {}, \"targetFile\": \"${targetFile}\", \"description\": \"what to do and where (using excerpt hints)\", \"metadata\": { \"doneWhenRegex\": { \"filePath\": \"${targetFile}\", \"pattern\": \"...\", \"flags\": \"m\" } } } ] }\n`.trim()\n            : `\nYou are an autonomous coding agent.\n\nYour task is to generate a transform plan using ONLY the user intent.\n\nIMPORTANT CONSTRAINTS:\n- All steps MUST target the same file: ${targetFile}\n- Do NOT reference or modify any other file\n- Do NOT invent line numbers, sections, symbols, or file structure\n\nIntent:\n${intentText}\n\nTask category:\n${intentCategory}\n\nAllowed actions (transform only):\n${actionsJson}\n\n${orderedQuestions.length > 0 ? `Ordered question parts:\\n${JSON.stringify(orderedQuestions, null, 2)}\\n` : \"\"}\n\nRules:\n- Plan purely from intent\n- If the intent implies multiple operations (e.g. move = remove + append),\n  generate multiple steps in logical order\n- Do NOT include any location hints or references\n- Only include transform steps\n- Each step must include: action, actionId, actionArgs, targetFile, description, metadata\n- If possible include metadata.doneWhenRegex = { filePath, pattern, flags } for deterministic completion checks.\n\nReturn strictly valid JSON:\n\n{ \"steps\": [ { \"action\": \"stepName\", \"actionId\": \"stepName\", \"actionArgs\": {}, \"targetFile\": \"${targetFile}\", \"description\": \"what to do (no location hints)\", \"metadata\": { \"doneWhenRegex\": { \"filePath\": \"${targetFile}\", \"pattern\": \"...\", \"flags\": \"m\" } } } ] }\n`.trim();\n\n        try {\n            const genInput: ModuleIO = { query: intentText, content: prompt };\n            const genOutput = await generate(genInput, {\n                caller: \"transformPlanGenStep\",\n                inputContext: {\n                    intentText,\n                    intentCategory,\n                    targetFile,\n                    orderedQuestions,\n                    currentQuestionId,\n                    hasExcerpts,\n                    excerpts,\n                    allowedActions: effectiveActions,\n                },\n            });\n\n            const raw = typeof genOutput.data === 'string'\n                ? genOutput.data\n                : JSON.stringify(genOutput.data ?? '{}');\n\n            const cleaned = await cleanupModule.run({ query: intentText, content: raw });\n\n            let parsed: { steps?: AgentPlanStep[] } | null = null;\n            if (typeof cleaned.data === 'object' && cleaned.data !== null) {\n                parsed = cleaned.data as { steps?: AgentPlanStep[] };\n            } else if (typeof cleaned.content === 'string') {\n                try {\n                    parsed = JSON.parse(cleaned.content);\n                } catch {\n                    parsed = null;\n                }\n            }\n\n            const parsedSteps = Array.isArray(parsed?.steps) ? parsed.steps : null;\n            const fallbackStep = buildFallbackTransformStep(targetFile, fa, context.analysis?.routingDecision?.confidence, currentQuestionId);\n            // Keep an explicit empty planner result as a real no-op.\n            const effectiveSteps = parsedSteps ?? (fallbackStep ? [fallbackStep] : []);\n\n            // Normalize steps: enforce targetFile, groups, metadata\n            const normalizedSteps: AgentPlanStep[] = effectiveSteps.map((step, index) => {\n                step.id = `transform:${targetFile}:${index + 1}`;\n                step.targetFile = targetFile;\n                // ActionRouter consumes actionId/actionArgs; action is kept for backward compatibility.\n                step.actionId = step.actionId ?? step.action;\n                step.actionArgs = step.actionArgs ?? {};\n                step.questionId = step.questionId ?? currentQuestionId;\n\n                const actionDef = PLAN_ACTIONS.find(a => a.action === step.action);\n                step.groups = actionDef?.groups ?? ['transform'];\n\n                const confidence = context.analysis?.routingDecision?.confidence;\n                step.metadata = {\n                    ...step.metadata,\n                    ...(typeof confidence === 'number' && confidence > 0\n                        ? { routingConfidence: confidence }\n                        : {})\n                };\n\n                return step;\n            });\n\n            context.analysis.planSuggestion = { plan: { steps: normalizedSteps } };\n            logInputOutput('transformPlanGen', 'output', {\n                callId: genOutput.trace?.callId,\n                source: parsedSteps\n                    ? 'model'\n                    : (fallbackStep ? 'fallback' : 'empty'),\n                steps: normalizedSteps,\n            });\n\n        } catch (err) {\n            console.warn('⚠️ Failed to generate transform plan:', err);\n            const fallbackStep = buildFallbackTransformStep(targetFile, fa, context.analysis?.routingDecision?.confidence, currentQuestionId);\n            const fallbackSteps = fallbackStep ? [fallbackStep] : [];\n            context.analysis.planSuggestion = { plan: { steps: fallbackSteps } };\n            logInputOutput('transformPlanGen', 'output', {\n                source: fallbackStep ? 'fallback-after-error' : 'empty-after-error',\n                steps: fallbackSteps,\n            });\n        }\n    }\n};\n\n/**\n * Builds a safe one-step transform fallback from semantic analysis when plan JSON is missing.\n *\n * Example:\n * - summary \"Add a hello world comment near the imports\" -> one `codeTransform` step with that description\n * - shouldModify false -> no fallback step\n */\nfunction buildFallbackTransformStep(\n    targetFile: string,\n    fileAnalysis: FileAnalysis | undefined,\n    routingConfidence: number | undefined,\n    currentQuestionId?: string,\n): AgentPlanStep | null {\n    if (!fileAnalysis?.action?.shouldModify) {\n        return null;\n    }\n\n    const summary = fileAnalysis.proposedChanges?.summary?.trim();\n    const rationale = fileAnalysis.proposedChanges?.rationale?.trim();\n    const description = [summary, rationale].filter(Boolean).join(\" \");\n    if (!description) {\n        return null;\n    }\n\n    return {\n        id: `transform:${targetFile}:fallback`,\n        action: \"codeTransform\",\n        actionId: \"codeTransform\",\n        actionArgs: {},\n        targetFile,\n        questionId: currentQuestionId,\n        description,\n        groups: [\"transform\"],\n        metadata: {\n            source: \"semantic-fallback\",\n            ...(typeof routingConfidence === \"number\" && routingConfidence > 0\n                ? { routingConfidence }\n                : {}),\n        },\n    };\n}\n"]}