scai 0.1.117 → 0.1.118

package/dist/agents/planGeneratorStep.js

@@ -0,0 +1,118 @@
+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;
+export const planGeneratorStep = {
+    name: 'planGenerator',
+    description: 'Converts a textual plan into structured JSON steps.',
+    requires: ['userQuery', 'intent', 'analysis.routingDecision'],
+    produces: ['analysis.planSuggestion.plan'],
+    async run(context) {
+        var _a, _b;
+        context.analysis || (context.analysis = {});
+        // We check for missing files detected in the preFileSearchCheckStep
+        // If none we filter out fileSearch actions.
+        const missingFiles = Array.isArray(context.analysis.focus?.missingFiles)
+            ? context.analysis.focus.missingFiles
+            : [];
+        const hasMissingFiles = missingFiles.length > 0;
+        const effectiveActions = PLAN_ACTIONS.filter(a => {
+            if (!hasMissingFiles && a.action === 'fileSearch') {
+                return false;
+            }
+            return true;
+        });
+        const actionsJson = JSON.stringify(effectiveActions, null, 2);
+        const intentText = context.analysis?.intent?.normalizedQuery ?? context.initContext?.userQuery;
+        const intentCategory = context.analysis?.intent?.intentCategory ?? '';
+        const suggestionText = context.analysis?.planSuggestion?.text ?? '';
+        const prompt = `
+You are an autonomous coding agent. Convert the following textual suggestion into a structured JSON plan.
+
+Intent / task description:
+${intentText}
+
+Suggest task type:
+${intentCategory};
+
+Suggested plan / guidance:
+${suggestionText}
+
+Folder info:
+${context.analysis?.folderCapsulesHuman}
+
+Allowed actions and their groups (JSON format):
+${actionsJson}
+
+Existing relevant files:
+${JSON.stringify(context.analysis?.focus?.relevantFiles ?? {}, null, 2)}
+
+Only implement search if there are missing files:
+${JSON.stringify(context.analysis?.focus?.missingFiles ?? {}, null, 2)}
+
+⚡ Phase guidance:
+- Actions are grouped into phases: info, transform, finalize.
+- Respect group boundaries: do all "info" steps first, then "transform", then "finalize".
+- Each step must include: "action", "targetFile" (optional), "description", "metadata"
+
+❌ IMPORTANT: Do NOT use "codeTransform" as an analysis step. All analysis tasks are already handled by semantic/structural analysis modules. Only use "codeTransform" if you are generating actual code changes in the transform phase.
+
+Rules:
+- Use only the actions listed above.
+- Limit to a maximum of ${MAX_STEPS} steps.
+- Return strictly valid JSON matching:
+
+{
+  "steps": [
+    { "action": "stepName", "targetFile": "optional/path.ts", "description": "explanation", "metadata": {} }
+  ]
+}
+    `.trim();
+        try {
+            console.dir("planGeneratorPrompt: ", prompt);
+            const genInput = { query: intentText ?? '', content: prompt };
+            const genOutput = await generate(genInput);
+            const llmOutput = typeof genOutput.data === 'string'
+                ? genOutput.data
+                : JSON.stringify(genOutput.data ?? '{}');
+            const cleaned = await cleanupModule.run({
+                query: intentText ?? '',
+                content: llmOutput,
+            });
+            const jsonString = typeof cleaned.content === 'string'
+                ? cleaned.content
+                : JSON.stringify(cleaned.content ?? '{}');
+            let plan = JSON.parse(jsonString);
+            if (!plan || typeof plan !== 'object' || !Array.isArray(plan.steps)) {
+                throw new Error('Invalid plan structure');
+            }
+            if (plan.steps.length > MAX_STEPS) {
+                console.warn(`⚠️ Truncating plan steps: got ${plan.steps.length}, limiting to ${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 ?? (context.analysis = {});
+            (_a = context.analysis).planSuggestion ?? (_a.planSuggestion = { text: '' });
+            context.analysis.planSuggestion.plan = plan;
+            logInputOutput('planGenerator', 'output', { generatedPlan: plan });
+        }
+        catch (err) {
+            console.warn('⚠️ Failed to parse plan JSON:', err);
+            context.analysis ?? (context.analysis = {});
+            (_b = context.analysis).planSuggestion ?? (_b.planSuggestion = { text: '' });
+            context.analysis.planSuggestion.plan = { steps: [] };
+            logInputOutput('planGenerator', 'output', { generatedPlan: { steps: [] } });
+        }
+    },
+};

package/dist/agents/planResolverStep.js

@@ -0,0 +1,95 @@
+import { generate } from '../lib/generate.js';
+import { logInputOutput } from '../utils/promptLogHelper.js';
+function logRoutingDecision(context) {
+    logInputOutput('planResolver', 'output', context.analysis?.routingDecision ?? {});
+}
+export const planResolverStep = {
+    name: 'planResolver',
+    // 🔒 Hard contract
+    requires: ['userQuery', 'intent'],
+    produces: [
+        'analysis.routingDecision',
+        'analysis.planSuggestion',
+    ],
+    async run(context) {
+        context.analysis || (context.analysis = {});
+        const prompt = `
+You are a routing classifier, not a problem solver.
+
+User query:
+${context.initContext?.userQuery}
+
+Repo section: 
+${context.initContext?.repoTree}
+
+${context.analysis?.folderCapsulesHuman}
+
+Decide ONE of the following:
+
+RESOLVED:
+- Only if the user can be answered immediately
+- The answer must be short (1–2 paragraphs)
+- No code blocks
+- No step-by-step instructions
+- No file-level documentation
+
+PLAN:
+- If the task requires reading, modifying, generating, or validating code
+- If the answer would be long, structured, or procedural
+- If files are mentioned or implied
+
+`.trim();
+        try {
+            const genInput = {
+                query: context.initContext?.userQuery ?? '',
+                content: prompt,
+            };
+            const genOutput = await generate(genInput);
+            console.log('PlanResolverOutput: ', genInput.data);
+            const raw = String(genOutput.data ?? '').trim();
+            logInputOutput('planResolver raw', 'output', raw);
+            const isResolved = raw.startsWith('RESOLVED:');
+            const isPlan = raw.startsWith('PLAN:');
+            const resolvedText = raw.replace(/^RESOLVED:\s*/i, '').trim();
+            const incompleteAnswerPatterns = [
+                /possible/i, /provide/i, /need/i, /cannot/i, /missing/i,
+                /unknown/i, /unspecified/i, /unavailable/i, /undefined/i,
+                /incomplete/i, /insufficient/i, /ambiguous/i, /unclear/i,
+                /requires/i, /lack/i, /omitted/i,
+            ];
+            const requiresMoreWork = incompleteAnswerPatterns.some(p => p.test(resolvedText));
+            if (isResolved && resolvedText && !requiresMoreWork) {
+                context.analysis.routingDecision = {
+                    decision: 'final-answer',
+                    answer: resolvedText,
+                    rationale: 'Request can be fully resolved immediately without further steps.',
+                    confidence: 0.8,
+                };
+            }
+            else {
+                const planText = isPlan
+                    ? raw.replace(/^PLAN:\s*/i, '').trim()
+                    : resolvedText;
+                context.analysis.planSuggestion = {
+                    text: planText,
+                };
+                context.analysis.routingDecision = {
+                    decision: 'needs-plan',
+                    rationale: isPlan
+                        ? 'Model explicitly indicated planning or execution is required.'
+                        : 'Request cannot be completed without further steps or execution.',
+                    confidence: isPlan ? 0.6 : 0.4,
+                };
+            }
+            logRoutingDecision(context);
+        }
+        catch (err) {
+            console.warn('⚠️ planResolver failed:', err);
+            context.analysis.routingDecision = {
+                decision: 'needs-plan',
+                rationale: 'planResolver encountered an internal error.',
+                confidence: 0.2,
+            };
+        }
+    },
+};

package/dist/agents/planTargetFilesStep.js

@@ -0,0 +1,48 @@
+import { logInputOutput } from "../utils/promptLogHelper.js";
+export const planTargetFilesStep = {
+    name: "planTargetFilesStep",
+    description: "Sync files from analysis.focus into plan.targetFiles. Ensures only workingFiles are moved and does not redo intent or risks.",
+    groups: ["analysis"],
+    run: async (input) => {
+        const context = input.context;
+        const query = input.query ?? "";
+        if (!context) {
+            const output = {
+                query,
+                data: { notes: "[planTargetFilesStep] No context provided; skipping." },
+            };
+            logInputOutput("planTargetFilesStep", "output", output.data);
+            return output;
+        }
+        // Ensure analysis.focus exists
+        const focusFiles = context.analysis?.focus?.relevantFiles ?? [];
+        if (!focusFiles.length) {
+            const output = {
+                query,
+                data: { notes: "[planTargetFilesStep] No relevant files in analysis.focus; nothing to move." },
+            };
+            logInputOutput("planTargetFilesStep", "output", output.data);
+            return output;
+        }
+        // Ensure plan exists
+        context.plan || (context.plan = {});
+        // Move relevant files to plan.targetFiles, only if they exist in workingFiles
+        const workingFilePaths = new Set(context.workingFiles?.map(f => f.path) ?? []);
+        const targetFiles = new Set(context.plan.targetFiles ?? []);
+        focusFiles.forEach(f => {
+            if (workingFilePaths.has(f)) {
+                targetFiles.add(f);
+            }
+        });
+        context.plan.targetFiles = Array.from(targetFiles);
+        const output = {
+            query,
+            data: {
+                movedFiles: Array.from(targetFiles),
+                notes: "Focus files successfully moved to plan.targetFiles.",
+            },
+        };
+        logInputOutput("planTargetFilesStep", "output", output.data);
+        return output;
+    },
+};

package/dist/agents/preFileSearchCheckStep.js

@@ -0,0 +1,95 @@
+// File: src/modules/preFileSearchCheckStep.ts
+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 = {};
+    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.`;
+    // 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.
+
+User intent:
+${JSON.stringify(intent ?? {}, null, 2)}
+
+Plan suggestion:
+${planSuggestion}
+
+Known files in context:
+${JSON.stringify([...knownFiles], null, 2)}
+
+Task:
+1. Confirm which files are already available to satisfy the intent.
+2. List missing files if any.
+3. Suggest any assumptions, constraints, or risks that may affect execution.
+4. Return STRICT JSON with shape:
+
+{
+  "relevantFiles": string[],
+  "missingFiles": string[],
+  "rationale": string,
+  "understanding": {
+    "assumptions"?: string[],
+    "constraints"?: string[],
+    "risks"?: string[]
+  }
+}
+`.trim();
+    const ai = await generate({
+        query: context.initContext?.userQuery ?? '',
+        content: prompt
+    });
+    try {
+        const cleaned = await cleanupModule.run({
+            query: context.initContext?.userQuery ?? '',
+            content: ai.data,
+        });
+        let parsed;
+        if (typeof cleaned.data === "object" && cleaned.data !== null) {
+            parsed = cleaned.data;
+        }
+        else if (typeof cleaned.content === "string") {
+            parsed = JSON.parse(cleaned.content);
+        }
+        else {
+            throw new Error("Cleanup output is neither object nor string");
+        }
+        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) {
+            context.analysis.understanding = {
+                ...context.analysis.understanding,
+                ...parsed.understanding,
+            };
+        }
+        logInputOutput("preFileSearchCheckStep", "output", parsed);
+    }
+    catch (err) {
+        console.warn("[preFileSearchCheckStep] Failed to parse AI output, using defaults", err);
+    }
+    // Simple regex-based extractor
+    function extractFilesFromAnalysis(analysis) {
+        const sources = [
+            analysis?.intent?.normalizedQuery ?? "",
+            analysis?.planSuggestion?.text ?? ""
+        ].join("\n");
+        const regex = /\b([\w\-\./]+\.js|[\w\-\./]+\.ts)\b/g;
+        const matches = sources.match(regex);
+        return matches ? Array.from(new Set(matches.map(m => m.trim()))) : [];
+    }
+}

package/dist/agents/selectRelevantSourcesStep.js

@@ -0,0 +1,100 @@
+// File: src/modules/selectRelevantSourcesStep.ts
+import fs from "fs";
+import chalk from "chalk";
+import { generate } from "../lib/generate.js";
+import { cleanupModule } from "../pipeline/modules/cleanupModule.js";
+import { logInputOutput } from "../utils/promptLogHelper.js";
+export const selectRelevantSourcesStep = {
+    name: "selectRelevantSources",
+    description: "Selects the most relevant files for the query from relatedFiles + workingFiles, loads their code, and updates context.workingFiles.",
+    groups: ["analysis"],
+    run: async (input) => {
+        const query = input.query ?? "";
+        const context = input.context;
+        if (!context) {
+            throw new Error("[selectRelevantSources] StructuredContext is required.");
+        }
+        console.log(chalk.blueBright(`📁 [selectRelevantSources] Selecting relevant files for query "${query}"...`));
+        // Merge candidate paths (relatedFiles + existing workingFiles)
+        // At this point in-depth context build or searchfiles may have placed files in 
+        // working files. 
+        const candidatePaths = [
+            ...(context.analysis?.focus?.relevantFiles ?? []),
+            ...(context.initContext?.relatedFiles ?? []),
+            ...(context.workingFiles?.map(f => f.path) ?? [])
+        ];
+        const uniquePaths = Array.from(new Set(candidatePaths));
+        // -----------------------------
+        // Prompt the LLM to rank files
+        // -----------------------------
+        const prompt = `
+You are given:
+
+Query:
+"${query}"
+
+Candidate file paths:
+${JSON.stringify(uniquePaths, null, 2)}
+
+Task:
+- Identify ONLY the files directly you find to be directly relevant to the query. 
+- Return ONLY a JSON array of objects.
+- Each object must have at least a "path" field.
+- Optional fields: "summary".
+- Do NOT include explanations.
+    `.trim();
+        let topFiles = [];
+        try {
+            const response = await generate({ content: prompt, query: "" });
+            const cleaned = await cleanupModule.run({
+                query,
+                content: response.data,
+            });
+            const rawFiles = Array.isArray(cleaned.data) ? cleaned.data : [];
+            // Load code for selected files
+            topFiles = rawFiles
+                .map((f) => {
+                if (typeof f?.path !== "string")
+                    return null;
+                let code;
+                try {
+                    code = fs.readFileSync(f.path, "utf-8");
+                }
+                catch (err) {
+                    console.warn(`⚠️ Failed to read file ${f.path}:`, err.message);
+                }
+                return { path: f.path, code };
+            })
+                .filter(Boolean);
+        }
+        catch (err) {
+            console.error("❌ [selectRelevantSources] Model selection failed:", err);
+            topFiles = [];
+        }
+        // -----------------------------
+        // Persist authoritative context (append, do not overwrite)
+        // -----------------------------
+        context.workingFiles = [
+            ...(context.workingFiles ?? []), // existing working files
+            ...topFiles, // new top files
+        ];
+        // Deduplicate by path
+        const seenPaths = new Set();
+        context.workingFiles = context.workingFiles.filter(f => {
+            if (!f.path)
+                return false; // safety check
+            if (seenPaths.has(f.path))
+                return false;
+            seenPaths.add(f.path);
+            return true;
+        });
+        const output = {
+            query,
+            data: {
+                workingFiles: topFiles.map(f => ({ path: f.path })),
+            },
+        };
+        logInputOutput("selectRelevantSources", "output", output.data);
+        return output;
+    },
+};

package/dist/agents/semanticAnalysisStep.js

@@ -0,0 +1,144 @@
+// File: src/modules/semanticAnalysisStep.ts
+import { logInputOutput } from "../utils/promptLogHelper.js";
+import { generate } from "../lib/generate.js";
+import { cleanupModule } from "../pipeline/modules/cleanupModule.js";
+export const semanticAnalysisStep = {
+    name: "semanticAnalysis",
+    description: "Query-centric semantic analysis: per-file relevance and optional combined insights.",
+    groups: ["analysis"],
+    run: async (input) => {
+        var _a, _b;
+        const context = input.context;
+        if (!context)
+            throw new Error("[semanticAnalysisStep] No context provided");
+        const workingFiles = context.workingFiles ?? [];
+        if (!workingFiles.length) {
+            const notes = "[semanticAnalysisStep] No working files loaded; skipping semantic analysis";
+            logInputOutput("semanticAnalysisStep", "output", { notes });
+            return { query: input.query, data: { notes }, context };
+        }
+        context.analysis || (context.analysis = {});
+        (_a = context.analysis).fileAnalysis || (_a.fileAnalysis = {});
+        (_b = context.analysis).combinedAnalysis || (_b.combinedAnalysis = {});
+        // Get the files relevant to this query
+        const focusFiles = new Set(context.analysis.focus?.relevantFiles ?? []);
+        const filesToAnalyze = workingFiles.filter(f => focusFiles.has(f.path) || focusFiles.size === 0);
+        // ----------------------------
+        // 1️⃣ Per-file relevance analysis
+        // ----------------------------
+        for (const file of filesToAnalyze) {
+            const filePath = file.path;
+            if (context.analysis.fileAnalysis[filePath])
+                continue;
+            const fileAnalysis = await analyzeFile(file, input.query);
+            context.analysis.fileAnalysis[filePath] = fileAnalysis;
+            logInputOutput("semanticAnalysisStep - per-file", "output", { file: filePath, analysis: fileAnalysis });
+        }
+        // ----------------------------
+        // 2️⃣ Cross-file combined analysis
+        // Only use files marked as relevant
+        // Skip if ≤ 2 relevant files
+        // ----------------------------
+        const relevantFileAnalysis = Object.fromEntries(Object.entries(context.analysis.fileAnalysis)
+            .filter(([_, fa]) => fa.intent && fa.intent !== "irrelevant"));
+        let combinedAnalysis = { sharedPatterns: [], architectureSummary: "[skipped]", hotspots: [] };
+        if (Object.keys(relevantFileAnalysis).length > 2) {
+            combinedAnalysis = await analyzeCombined(relevantFileAnalysis, input.query);
+            context.analysis.combinedAnalysis = combinedAnalysis;
+            logInputOutput("semanticAnalysisStep - combined", "output", combinedAnalysis);
+        }
+        else {
+            context.analysis.combinedAnalysis = combinedAnalysis;
+        }
+        return {
+            query: input.query,
+            data: { notes: "Query-centric semantic analysis completed" },
+            context,
+        };
+    },
+};
+async function analyzeFile(file, query) {
+    const prompt = `
+You are given a user query:
+"${query}"
+
+Task:
+- Determine if an analysis of this file is relevant to answering the query.
+- If relevant, describe in 1-2 sentences how it contributes to answering the query.
+- If irrelevant, set intent to "irrelevant".
+- Optionally, include any risks that may affect the query's outcome.
+
+Return STRICT JSON:
+{
+  "intent": string,
+  "risks"?: string[]
+}
+
+File path: ${file.path}
+Code snippet: ${file.code ?? "[no code]"}
+`;
+    try {
+        const ai = await generate({ query: file.path, content: prompt });
+        const cleaned = await cleanupModule.run({ query, content: ai.data });
+        let data;
+        // Attempt to use structured data if available
+        if (typeof cleaned.data === "object" && cleaned.data) {
+            data = cleaned.data;
+        }
+        else {
+            try {
+                data = JSON.parse(String(cleaned.content ?? "{}"));
+            }
+            catch {
+                console.warn(`[semanticAnalysisStep] Non-JSON output for ${file.path}, defaulting to irrelevant`);
+                data = { intent: "irrelevant", risks: [] };
+            }
+        }
+        return {
+            intent: data.intent ?? "irrelevant",
+            risks: Array.isArray(data.risks) ? data.risks : []
+        };
+    }
+    catch (err) {
+        console.warn(`[semanticAnalysisStep] Failed to analyze file ${file.path}:`, err);
+        return { intent: "irrelevant", risks: [] };
+    }
+}
+/* -----------------------------------------
+   Helper: analyzeCombined
+   Only for relevant files, concise
+-------------------------------------------- */
+async function analyzeCombined(fileAnalysis, query) {
+    const prompt = `
+You are given per-file analysis relevant to the query:
+${JSON.stringify(fileAnalysis, null, 2)}
+
+Task:
+- Identify shared patterns across these files in the context of the query
+- Summarize high-level architecture relevant to answering the query
+- List any hotspots or risks that could impact the query's outcome
+
+Return STRICT JSON:
+{
+  "sharedPatterns"?: string[],
+  "architectureSummary"?: string,
+  "hotspots"?: string[]
+}
+`;
+    try {
+        const ai = await generate({ query: "cross-file analysis", content: prompt });
+        const cleaned = await cleanupModule.run({ query, content: ai.data });
+        const data = typeof cleaned.data === "object" && cleaned.data
+            ? cleaned.data
+            : JSON.parse(String(cleaned.content ?? "{}"));
+        return {
+            sharedPatterns: data.sharedPatterns ?? [],
+            architectureSummary: data.architectureSummary ?? "[unparsed]",
+            hotspots: data.hotspots ?? []
+        };
+    }
+    catch (err) {
+        console.warn("[semanticAnalysisStep] Failed to parse combined analysis:", err);
+        return { sharedPatterns: [], architectureSummary: "[unparsed]", hotspots: [] };
+    }
+}

package/dist/agents/structuralAnalysisStep.js

@@ -0,0 +1,46 @@
+import { logInputOutput } from "../utils/promptLogHelper.js";
+export const structuralAnalysisStep = {
+    name: "structuralAnalysis",
+    description: "Derive structural characteristics from workingFiles using existing metadata only. " +
+        "Produces a durable, machine-usable summary of file shape and relationships.",
+    groups: ["analysis"],
+    run: async (input) => {
+        const ctx = input.context;
+        if (!ctx) {
+            throw new Error("[structuralAnalysis] StructuredContext is required but was not provided.");
+        }
+        const workingFiles = ctx.workingFiles;
+        if (!Array.isArray(workingFiles) || workingFiles.length === 0) {
+            const output = {
+                query: input.query,
+                data: {
+                    notes: "No workingFiles present; structural analysis skipped."
+                }
+            };
+            logInputOutput("structuralAnalysis", "output", output.data);
+            return output;
+        }
+        const files = workingFiles.map((file) => ({
+            path: file.path,
+            imports: file.imports ?? [],
+            exports: file.exports ?? [],
+            functions: file.functions?.length ?? 0,
+            classes: file.classes?.length ?? 0,
+        }));
+        // 🧠 Persist durable structural understanding
+        ctx.analysis ?? (ctx.analysis = {});
+        ctx.analysis.structure = {
+            files,
+        };
+        const output = {
+            query: input.query,
+            data: {
+                fileCount: files.length,
+                files,
+                notes: "Structural characteristics derived from loaded workingFiles.",
+            }
+        };
+        logInputOutput("structuralAnalysis", "output", output.data);
+        return output;
+    }
+};