scai 0.1.117 → 0.1.118

package/dist/utils/buildContextualPrompt.js

@@ -1,183 +1,256 @@
 // src/utils/buildContextualPrompt.ts
+import path from "path";
+import fs from "fs";
 import { getDbForRepo } from "../db/client.js";
-import { generateFocusedFileTree } from "./fileTree.js";
-export async function buildContextualPrompt({ topFile, query, kgDepth = 3, }) {
+import { generateFileTree, generateFocusedFileTree } from "./fileTree.js";
+import { RELATED_FILES_LIMIT } from "../constants.js";
+import { loadRelevantFolderCapsules } from "./loadRelevantFolderCapsules.js";
+/* --- Constants --- */
+const MAX_FUNCTIONS = 50;
+const MAX_KG_NEIGHBORS = 50;
+const DEFAULT_KG_DEPTH = 3;
+/* --- Helpers --- */
+function fileRowIdForPath(db, filePath) {
+    try {
+        const row = db
+            .prepare(`SELECT id FROM files WHERE path = ?`)
+            .get(filePath);
+        return row?.id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ---------------- KG helpers ---------------- */
+function loadKgTags(db, entityUniqueId, limit = MAX_KG_NEIGHBORS) {
+    try {
+        const rows = db
+            .prepare(`
+        SELECT tm.name as tag
+        FROM graph_entity_tags et
+        JOIN graph_tags_master tm ON tm.id = et.tag_id
+        WHERE et.entity_unique_id = ?
+        LIMIT ?
+      `)
+            .all(entityUniqueId, limit);
+        return rows.map((r) => r.tag);
+    }
+    catch {
+        return [];
+    }
+}
+function loadKgNeighbors(db, sourceUniqueId, limit = MAX_KG_NEIGHBORS) {
+    try {
+        const rows = db
+            .prepare(`
+        SELECT relation, target_unique_id as target
+        FROM graph_edges
+        WHERE source_unique_id = ?
+        LIMIT ?
+      `)
+            .all(sourceUniqueId, limit);
+        return rows.map((r) => ({ relation: r.relation, target: r.target }));
+    }
+    catch {
+        return [];
+    }
+}
+/* ---------------- Functions / classes ---------------- */
+function loadFunctions(db, fileId, limit = MAX_FUNCTIONS) {
+    if (!fileId)
+        return [];
+    try {
+        const rows = db
+            .prepare(`SELECT name, start_line, end_line
+         FROM functions
+         WHERE file_id = ?
+         ORDER BY start_line
+         LIMIT ?`)
+            .all(fileId, limit);
+        return rows.map((r) => ({
+            name: r.name ?? undefined,
+            start: r.start_line,
+            end: r.end_line,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function loadClasses(db, fileId, limit = 50) {
+    if (!fileId)
+        return [];
+    try {
+        const rows = db
+            .prepare(`SELECT name, start_line, end_line
+         FROM graph_classes
+         WHERE file_id = ?
+         ORDER BY start_line
+         LIMIT ?`)
+            .all(fileId, limit);
+        return rows.map((r) => ({
+            name: r.name ?? undefined,
+            start: r.start_line,
+            end: r.end_line,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/* ---------------- Trees ---------------- */
+function safeGenerateFocusedTree(filePath, depth = 2) {
+    try {
+        return generateFocusedFileTree(filePath, depth) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeGenerateRepoTree(depth = 2) {
+    try {
+        const root = process.cwd();
+        return generateFileTree(root, depth) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ======================================================
+   LIGHT CONTEXT
+   ====================================================== */
+export async function buildLightContext(args) {
     const db = getDbForRepo();
-    const log = (...args) => console.log("[buildContextualPrompt]", ...args);
-    const promptSections = [];
-    const seenPaths = new Set();
-    function summarizeForPrompt(summary, maxWords = 30) {
-        if (!summary)
-            return undefined;
-        const words = summary.split(/\s+/);
-        return words.length <= maxWords ? summary.trim() : words.slice(0, maxWords).join(" ") + " …";
-    }
-    // --- Top file summary ---
-    if (topFile.summary) {
-        promptSections.push(`**Top file:** ${topFile.path}\n${topFile.summary}`);
-        seenPaths.add(topFile.path);
-    }
-    // --- Knowledge Graph tags ---
-    const topEntitiesRows = db.prepare(`
-    SELECT et.entity_type, et.entity_unique_id, tm.name AS tag
-    FROM graph_entity_tags et
-    JOIN graph_tags_master tm ON et.tag_id = tm.id
-    WHERE et.entity_unique_id = ?
-  `).all(topFile.path);
-    if (topEntitiesRows.length > 0) {
-        const tags = topEntitiesRows.map(r => `- **${r.entity_type}**: ${r.tag}`);
-        promptSections.push(`**Knowledge Graph context for ${topFile.path}:**\n${tags.join("\n")}`);
-    }
-    // --- Imports / Exports ---
-    const imports = db.prepare(`
-    SELECT e.target_unique_id AS imported
-    FROM graph_edges e
-    WHERE e.source_type = 'file'
-      AND e.relation = 'imports'
-      AND e.source_unique_id = ?
-  `).all(topFile.path);
-    if (imports.length) {
-        promptSections.push(`**Imports from ${topFile.path}:**\n` + imports.map(i => `- ${i.imported}`).join("\n"));
-    }
-    const exports = db.prepare(`
-    SELECT e.target_unique_id AS exported
-    FROM graph_edges e
-    WHERE e.source_type = 'file'
-      AND e.relation = 'exports'
-      AND e.source_unique_id = ?
-  `).all(topFile.path);
-    if (exports.length) {
-        promptSections.push(`**Exports from ${topFile.path}:**\n` + exports.map(e => `- ${e.exported}`).join("\n"));
-    }
-    // --- Functions in file ---
-    const functionRows = db
-        .prepare(`SELECT unique_id, name, start_line, end_line, content FROM functions WHERE file_id = ? ORDER BY start_line`)
-        .all(topFile.id);
-    const FUNCTION_LIMIT = 5;
-    const hasMoreFunctions = functionRows.length > FUNCTION_LIMIT;
-    const functionsSummary = functionRows.slice(0, FUNCTION_LIMIT).map(f => {
-        const lines = f.content?.split("\n").map(l => l.trim()).filter(Boolean) || ["[no content]"];
-        const preview = lines.slice(0, 3).map(l => l.slice(0, 200) + (l.length > 200 ? "…" : "")).join(" | ");
-        return `- ${f.name || "[anonymous]"} (lines ${f.start_line}-${f.end_line}) — ${preview}`;
-    });
-    if (functionsSummary.length) {
-        promptSections.push(`**Functions in ${topFile.path} (showing ${functionsSummary.length}${hasMoreFunctions ? ` of ${functionRows.length}` : ""}):**\n${functionsSummary.join("\n")}`);
-    }
-    // ===============================
-    // Graph / KG traversal
-    // ===============================
-    function getRelatedKGFiles(fileUniqueId, visited = new Set()) {
-        if (visited.has(fileUniqueId))
-            return [];
-        visited.add(fileUniqueId);
-        const rows = db.prepare(`
-      SELECT DISTINCT f.id, f.path, f.summary
-      FROM graph_edges e
-      JOIN files f ON e.target_unique_id = f.path
-      WHERE e.source_type = 'file'
-        AND e.target_type = 'file'
-        AND e.source_unique_id = ?
-    `).all(fileUniqueId);
-        let results = [];
-        for (const row of rows) {
-            results.push(row);
-            results.push(...getRelatedKGFiles(row.path, visited));
-        }
-        return results;
-    }
-    function buildFileTree(file, depth, visited = new Set()) {
-        if (visited.has(file.path))
-            return { id: file.id.toString(), path: file.path };
-        visited.add(file.path);
-        const maxWordsByDepth = depth >= 3 ? 30 : depth === 2 ? 15 : 0;
-        const node = {
-            id: file.id.toString(),
-            path: file.path,
-            summary: maxWordsByDepth > 0 ? summarizeForPrompt(file.summary, maxWordsByDepth) : undefined,
-        };
-        if (depth > 1) {
-            const relatedFiles = getRelatedKGFiles(file.path).map(f => ({ id: f.id, path: f.path, summary: f.summary })).slice(0, 5);
-            const relatedNodes = relatedFiles.map(f => buildFileTree(f, depth - 1, visited));
-            if (relatedNodes.length)
-                node.related = relatedNodes;
+    const safeTopFiles = Array.isArray(args.topFiles) ? args.topFiles : [];
+    const safeRelated = Array.isArray(args.relatedFiles)
+        ? args.relatedFiles
+        : [];
+    const ctx = {
+        initContext: {
+            userQuery: (args.query || "").trim(),
+            repoTree: safeGenerateRepoTree(2),
+            relatedFiles: [],
+            folderCapsules: [],
+        },
+    };
+    /* -------- Collect related file paths -------- */
+    const relatedPaths = [];
+    for (const tf of safeTopFiles) {
+        if (!relatedPaths.includes(tf.path))
+            relatedPaths.push(tf.path);
+    }
+    for (let i = 0; i < Math.min(RELATED_FILES_LIMIT, safeRelated.length); i++) {
+        const p = safeRelated[i].path;
+        if (!relatedPaths.includes(p))
+            relatedPaths.push(p);
+    }
+    /* -------- Add file references from user query -------- */
+    const referencedFiles = extractFileReferences(ctx.initContext.userQuery);
+    const topFilePaths = [];
+    for (const ref of referencedFiles) {
+        const found = safeTopFiles.find(f => f.path.toLowerCase().includes(ref));
+        if (found && !topFilePaths.includes(found.path)) {
+            topFilePaths.push(found.path);
         }
-        return node;
-    }
-    const kgTree = buildFileTree({ id: topFile.id, path: topFile.path, summary: topFile.summary }, kgDepth);
-    promptSections.push(`**KG-Related Files (JSON tree, depth ${kgDepth}):**\n\`\`\`json\n${JSON.stringify(kgTree, null, 2)}\n\`\`\``);
-    const functionCallsAll = db.prepare(`
-  SELECT source_unique_id, target_unique_id
-  FROM graph_edges
-  WHERE source_type = 'function' AND relation = 'calls'
-    AND source_unique_id IN (
-      SELECT unique_id FROM functions WHERE file_id = ?
-    )
-`).all(topFile.id);
-    const callsByFunction = {};
-    for (const fn of functionRows) {
-        const rows = functionCallsAll
-            .filter(r => r.source_unique_id === fn.unique_id)
-            .slice(0, FUNCTION_LIMIT);
-        // Truncate function content for preview
-        const lines = fn.content?.split("\n").map(l => l.trim()).filter(Boolean) || ["[no content]"];
-        const preview = lines.slice(0, 3).map(l => l.slice(0, 200) + (l.length > 200 ? "…" : "")).join(" | ");
-        callsByFunction[fn.name || fn.unique_id] = {
-            calls: rows.map(r => ({ unique_id: r.target_unique_id })),
-            preview,
-        };
     }
-    if (Object.keys(callsByFunction).length > 0) {
-        promptSections.push(`**Function-level calls (limited, JSON):**\n\`\`\`json\n${JSON.stringify(callsByFunction, null, 2)}\n\`\`\``);
-    }
-    // --- Function-level "called by" overview (limited) ---
-    const calledByAll = db.prepare(`
-  SELECT source_unique_id, target_unique_id
-  FROM graph_edges
-  WHERE target_type = 'function' AND relation = 'calls'
-    AND target_unique_id IN (
-      SELECT unique_id FROM functions WHERE file_id = ?
-    )
-`).all(topFile.id);
-    const calledByByFunction = {};
-    for (const fn of functionRows) {
-        const rows = calledByAll
-            .filter(r => r.target_unique_id === fn.unique_id)
-            .slice(0, FUNCTION_LIMIT);
-        // Reuse truncated preview
-        const lines = fn.content?.split("\n").map(l => l.trim()).filter(Boolean) || ["[no content]"];
-        const preview = lines.slice(0, 3).map(l => l.slice(0, 200) + (l.length > 200 ? "…" : "")).join(" | ");
-        calledByByFunction[fn.name || fn.unique_id] = {
-            calledBy: rows.map(r => ({ unique_id: r.source_unique_id })),
-            preview,
+    // Merge query references into relatedPaths
+    for (const tf of topFilePaths) {
+        if (!relatedPaths.includes(tf))
+            relatedPaths.push(tf);
+    }
+    ctx.initContext.relatedFiles = relatedPaths;
+    /* -------- Folder capsules (orientation layer) -------- */
+    const folderPaths = normalizeToFolders(relatedPaths);
+    let folderCapsules = loadRelevantFolderCapsules(folderPaths);
+    // Ensure root capsule exists
+    const rootExists = folderCapsules.some(c => c.path === '/');
+    if (!rootExists) {
+        const rootCapsule = {
+            path: '/',
+            depth: 1,
+            stats: { fileCount: 0, byType: {} },
+            roles: [],
+            concerns: [],
+            keyFiles: [],
+            dependencies: { importsFrom: [], usedBy: [] },
+            confidence: 0.5,
         };
+        folderCapsules.unshift(rootCapsule);
     }
-    if (Object.keys(calledByByFunction).length > 0) {
-        promptSections.push(`**Function-level called-by (limited, JSON):**\n\`\`\`json\n${JSON.stringify(calledByByFunction, null, 2)}\n\`\`\``);
+    ctx.initContext.folderCapsules = folderCapsules;
+    return ctx;
+}
+/* -------- Helper: get folders from filepaths -------- */
+function normalizeToFolders(paths) {
+    const out = new Set();
+    for (const p of paths) {
+        try {
+            const stat = fs.statSync(p);
+            if (stat.isDirectory()) {
+                out.add(p);
+            }
+            else if (stat.isFile()) {
+                out.add(path.dirname(p));
+            }
+        }
+        catch {
+            // ignore invalid paths
+        }
     }
-    // --- Focused file tree (shallow) ---
-    try {
-        const fileTree = generateFocusedFileTree(topFile.path, 2);
-        if (fileTree) {
-            promptSections.push(`**Focused File Tree (depth 2):**\n\`\`\`\n${fileTree}\n\`\`\``);
+    return [...out];
+}
+/* -------- Helper: extract file references from query -------- */
+function extractFileReferences(query) {
+    const matches = [];
+    const filenameRegex = /[\w\-\/]+\.\w{1,6}/gi;
+    const explicit = query.match(filenameRegex);
+    if (explicit)
+        matches.push(...explicit.map(s => s.toLowerCase()));
+    return [...new Set(matches)];
+}
+/* ======================================================
+   IN-DEPTH CONTEXT
+   ====================================================== */
+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,
+    };
+    /* -------- Working files (deep phase only) -------- */
+    for (const p of safeFilenames) {
+        const fileId = fileRowIdForPath(db, p);
+        const fileObj = { path: p };
+        if (typeof fileId === "number") {
+            fileObj.functions = loadFunctions(db, fileId, MAX_FUNCTIONS);
+            fileObj.classes = loadClasses(db, fileId, 200);
+        }
+        const neighbors = loadKgNeighbors(db, p, MAX_KG_NEIGHBORS);
+        fileObj.kgTags = loadKgTags(db, p, MAX_KG_NEIGHBORS);
+        if (neighbors.length) {
+            fileObj.kgNeighborhood = neighbors.map((e) => `${e.relation}:${e.target}`);
+            const imports = neighbors
+                .filter((e) => e.relation === "imports")
+                .map((e) => e.target);
+            const exports = neighbors
+                .filter((e) => e.relation === "exports")
+                .map((e) => e.target);
+            if (imports.length)
+                fileObj.imports = imports.slice(0, 200);
+            if (exports.length)
+                fileObj.exports = exports.slice(0, 200);
         }
+        fileObj.focusedTree = safeGenerateFocusedTree(p, 3);
+        workingFiles.push(fileObj);
     }
-    catch (e) {
-        console.warn("⚠️ Could not generate file tree:", e);
-    }
-    // --- Optional code snippet ---
-    const MAX_LINES = 50;
-    const queryNeedsCode = /\b(code|implementation|function|snippet)\b/i.test(query);
-    if ((!topFile.summary || queryNeedsCode) && topFile.code) {
-        const lines = topFile.code.split("\n").slice(0, MAX_LINES);
-        let snippet = lines.join("\n");
-        if (topFile.code.split("\n").length > MAX_LINES)
-            snippet += "\n... [truncated]";
-        promptSections.push(`**Code Context (first ${MAX_LINES} lines):**\n\`\`\`\n${snippet}\n\`\`\``);
-    }
-    // --- User query ---
-    promptSections.push(`**Query:** ${query}`);
-    const promptText = promptSections.join("\n\n---\n\n");
-    log("✅ Contextual prompt built for:", topFile.path);
-    log("📄 Prompt preview:\n", promptText + "\n");
-    return promptText;
+    return out;
 }

package/dist/utils/debugContext.js

@@ -0,0 +1,24 @@
+// File: src/utils/debugContext.ts
+import util from "util";
+import chalk from "chalk";
+export function debugContext(context, options = {}) {
+    const { step = "unknown-step", note, exit = true, depth = 6 } = options;
+    console.log("\n");
+    console.log(chalk.bgYellow.black(" 🛑 AGENT DEBUG BREAKPOINT "));
+    console.log(chalk.yellow(`Step: ${step}`));
+    if (note)
+        console.log(chalk.gray(`Note: ${note}`));
+    console.log("\n📦 StructuredContext snapshot:\n");
+    console.log(util.inspect(context, {
+        depth,
+        colors: true,
+        compact: false,
+        maxArrayLength: 20,
+        breakLength: 120
+    }));
+    console.log("\n---------------------------------------------");
+    if (exit) {
+        console.log(chalk.red("🚨 Exiting process after debug breakpoint\n"));
+        process.exit(0);
+    }
+}

package/dist/utils/fileTree.js

@@ -1,20 +1,29 @@
 import fs from 'fs';
 import path from 'path';
 import { getIndexDir } from '../constants.js';
+import { IGNORED_FOLDER_GLOBS } from '../fileRules/ignoredPaths.js';
+/** Utility to check if a file/folder should be ignored */
+/** Utility to check if a file/folder should be ignored */
+function isIgnored(fullPath) {
+    const normalizedPath = fullPath.replace(/\\/g, '/');
+    return IGNORED_FOLDER_GLOBS.some(pattern => {
+        // remove leading/trailing **
+        const cleanPattern = pattern.replace(/^\*\*\/?/, '').replace(/\/\*\*$/, '');
+        return normalizedPath.includes(cleanPattern);
+    });
+}
 /**
  * Generate a reduced file tree centered around the focus path, including nearby sibling folders.
  */
 export function generateFocusedFileTree(focusPath, maxDepth = 2, siblingWindow = 2) {
     const absoluteFocus = path.resolve(focusPath);
     const fileOrDir = fs.statSync(absoluteFocus);
-    const targetDir = fileOrDir.isDirectory()
-        ? absoluteFocus
-        : path.dirname(absoluteFocus);
+    const targetDir = fileOrDir.isDirectory() ? absoluteFocus : path.dirname(absoluteFocus);
     const parentDir = path.dirname(targetDir);
     const indexDir = getIndexDir();
     const siblings = fs
         .readdirSync(parentDir, { withFileTypes: true })
-        .filter(entry => entry.isDirectory())
+        .filter(entry => entry.isDirectory() && !isIgnored(path.join(parentDir, entry.name)))
         .sort((a, b) => a.name.localeCompare(b.name));
     const focusIndex = siblings.findIndex(entry => path.resolve(path.join(parentDir, entry.name)) === path.resolve(targetDir));
     const start = Math.max(0, focusIndex - siblingWindow);
@@ -30,11 +39,12 @@ export function generateFocusedFileTree(focusPath, maxDepth = 2, siblingWindow =
     });
     return output;
 }
-function generateFileTree(dir, depth, highlightPath, prefix = '') {
+export function generateFileTree(dir, depth, highlightPath, prefix = '') {
     if (depth < 0)
         return '';
     let output = '';
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+        .filter(entry => !isIgnored(path.join(dir, entry.name)));
     const sorted = entries.sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()));
     sorted.forEach((entry, index) => {
         const isLast = index === sorted.length - 1;

package/dist/utils/loadRelevantFolderCapsules.js

@@ -0,0 +1,64 @@
+// src/utils/loadRelevantFolderCapsules.ts
+import { getDbForRepo } from '../db/client.js';
+import path from 'path';
+import fs from 'fs';
+export function loadRelevantFolderCapsules(paths) {
+    const db = getDbForRepo();
+    const capsules = [];
+    // 1️⃣ Query DB first
+    const placeholders = paths.map(() => '?').join(',');
+    const stmt = db.prepare(`SELECT capsule_json FROM folder_capsules WHERE path IN (${placeholders})`);
+    const dbRows = stmt.all(...paths);
+    for (const row of dbRows) {
+        try {
+            const c = JSON.parse(row.capsule_json);
+            capsules.push(c);
+        }
+        catch {
+            // skip malformed JSON
+        }
+    }
+    // 2️⃣ Generate ephemeral capsules for missing paths
+    const existingPaths = new Set(capsules.map(c => c.path));
+    for (const p of paths) {
+        if (existingPaths.has(p))
+            continue;
+        if (!fs.existsSync(p))
+            continue;
+        const files = fs.readdirSync(p, { withFileTypes: true })
+            .filter(f => f.isFile())
+            .map(f => f.name);
+        const byType = {};
+        for (const f of files) {
+            const ext = path.extname(f).replace('.', '') || 'unknown';
+            byType[ext] = (byType[ext] || 0) + 1;
+        }
+        capsules.push({
+            path: p,
+            depth: p.split('/').length,
+            stats: { fileCount: files.length, byType },
+            roles: [],
+            concerns: [],
+            keyFiles: files
+                .filter(f => /index|main|cli|app|server|config/i.test(f))
+                .slice(0, 5)
+                .map(f => ({ path: path.join(p, f), reason: 'heuristic key file' })),
+            dependencies: { importsFrom: [], usedBy: [] },
+            confidence: 0.35,
+        });
+    }
+    // 3️⃣ Always add root capsule
+    if (!capsules.some(c => c.path === '/')) {
+        capsules.push({
+            path: '/',
+            depth: 1,
+            stats: { fileCount: 0, byType: {} },
+            roles: [],
+            concerns: [],
+            keyFiles: [],
+            dependencies: { importsFrom: [], usedBy: [] },
+            confidence: 0.5,
+        });
+    }
+    return capsules;
+}

package/dist/utils/log.js

@@ -1,5 +1,7 @@
 import { LOG_PATH } from "../constants.js";
 import fs from 'fs';
+export const DEBUG = false;
+export const SUMMARY_LENGTH = 120;
 export function log(...args) {
     const timestamp = new Date().toISOString();
     const message = args.map(arg => typeof arg === 'string' ? arg : JSON.stringify(arg, null, 2)).join(' ');

package/dist/utils/normalizeData.js

@@ -0,0 +1,23 @@
+/**
+ * normalizeData ensures that ModuleIO.data is always returned as a usable object.
+ *
+ * Modules may output either a JSON string or a structured object. This helper
+ * converts JSON strings into objects, passes objects through unchanged, and
+ * provides a safe fallback for null/undefined. It centralizes the parsing logic
+ * so individual modules don’t need to guess the data format.
+ */
+export function normalizeData(data) {
+    if (data == null)
+        return {};
+    if (typeof data === "object")
+        return data;
+    if (typeof data === "string") {
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            throw new Error("Invalid JSON string in ModuleIO.data");
+        }
+    }
+    return {};
+}

package/dist/utils/planActions.js

@@ -0,0 +1,60 @@
+// src/utils/planActions.ts
+export const PLAN_ACTIONS = [
+    // =====================================================
+    // INFORMATION ACQUISITION PHASE
+    // Purpose: gather raw information, no interpretation
+    // =====================================================
+    {
+        action: "fileSearch",
+        groups: ["info"],
+        description: "Search the repository for files matching a query, filename, extension, or pattern. " +
+            "Use when the user references files or concepts not already present in context."
+    },
+    // =====================================================
+    // ROUTING / PLANNING PHASE
+    // Purpose: decide how execution should proceed
+    // =====================================================
+    /* {
+      action: "routeTask",
+      groups: ["routing"],
+      description:
+        "Decide execution strategy based on semantic intent and scope. " +
+        "Determines whether to proceed with direct execution, recursive planning, or plan-only output. " +
+        "Produces executionMode and optional subtask definitions."
+    }, */
+    // =====================================================
+    // TRANSFORM PHASE
+    // Purpose: produce concrete changes or artifacts
+    // =====================================================
+    {
+        action: "codeTransform",
+        groups: ["transform"],
+        description: "Generate concrete code changes according to the execution plan and selected source files. " +
+            "This produces structured patches or full file rewrites, but does NOT write anything to disk. " +
+            "It should only be planned when actual code modifications are required, never for analysis purposes. " +
+            "Must complete successfully before any 'writeFile' steps are executed."
+    },
+    {
+        action: "writeFile",
+        groups: ["transform"],
+        description: "Persist file changes to disk. " +
+            "This action MUST ONLY be planned if codeTransform has already produced output, " +
+            "and MUST come after codeTransform in the plan."
+    },
+    {
+        action: "cleanup",
+        groups: ["transform"],
+        description: "Normalize or post-process generated output into valid, machine-consumable structures. " +
+            "Used when strict JSON or schema adherence is required."
+    },
+    // =====================================================
+    // FINALIZE PHASE
+    // Purpose: commit results and respond to the user
+    // =====================================================
+    {
+        action: "finalAnswer",
+        groups: ["finalize"],
+        description: "Produce the final user-facing response, explanation, or report. " +
+            "Summarizes actions taken and results produced."
+    },
+];