@aexol/spectral 0.9.129 → 0.9.130

package/dist/extensions/code-order/index.js

@@ -0,0 +1,76 @@
+/**
+ * Code Order — native spectral extension.
+ *
+ * Registers a single tool, `code_order_report`, that scans the current
+ * project's directory tree and returns a Markdown cleanup report: oversized
+ * files, deep nesting, empty folders/files, duplicate sibling names and
+ * single-child folders. Language-agnostic, read-only, zero configuration.
+ *
+ * The report is input for the agent — it deduces what to split or flatten
+ * outside of this extension. Tree-like structure is enforced separately via
+ * the system prompt guidelines (see system-prompt.ts).
+ */
+import { resolve } from "node:path";
+import { walkTree, computeMetrics } from "./analyzer.js";
+import { runAllHeuristics } from "./heuristics.js";
+import { renderReport } from "./report.js";
+export default async function codeOrderExtension(ext) {
+    const tool = {
+        name: "code_order_report",
+        label: "Code Order Report",
+        description: "Analyze the current project's folder structure and file sizes, " +
+            "then generate a cleanup report with actionable findings: " +
+            "oversized files, deep nesting, empty folders, duplicate sibling names, single-child folders. " +
+            "Read-only, zero config. Use this to get input data before reorganizing code.",
+        promptSnippet: "`code_order_report` — analyze folder structure & sizes, generate cleanup report",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Directory to analyze. Default: current working directory.",
+                },
+            },
+        },
+        async execute(_toolCallId, params) {
+            const rawPath = params.path ?? process.cwd();
+            const root = resolve(rawPath);
+            try {
+                const { tree, allFiles, allFolders, maxDepth, fileCount } = await walkTree(root);
+                const metrics = computeMetrics(allFiles, allFolders, maxDepth);
+                const issues = runAllHeuristics(tree, allFiles, allFolders, metrics);
+                const result = {
+                    root,
+                    generatedAt: new Date().toISOString(),
+                    metrics,
+                    issues,
+                };
+                const report = renderReport(result);
+                const summary = `Analyzed ${fileCount.toLocaleString()} files across ` +
+                    `${metrics.totalFolders.toLocaleString()} folders ` +
+                    `(${(metrics.totalSize / (1024 * 1024)).toFixed(1)} MB). ` +
+                    `Found ${issues.length} structural issue(s).`;
+                return {
+                    content: [{ type: "text", text: report }],
+                    details: {
+                        summary,
+                        fileCount,
+                        folderCount: metrics.totalFolders,
+                        totalSize: metrics.totalSize,
+                        issueCount: issues.length,
+                        root,
+                    },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `❌ Code Order analysis failed: ${msg}` }],
+                    details: { isError: true, error: msg, root },
+                };
+            }
+        },
+    };
+    ext.registerTool(tool);
+    process.stderr.write("[code-order] Registered code_order_report tool.\n");
+}

package/dist/extensions/code-order/report.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Code Order — Markdown report generator.
+ *
+ * Turns an {@link AnalysisResult} into a human/agent-readable Markdown report
+ * with a summary, prioritized issues, top largest files, and the extension
+ * distribution. The report is returned to the session so the LLM can deduce
+ * what to reorganize next.
+ */
+import type { AnalysisResult } from "./types.js";
+/**
+ * Render the full cleanup report as Markdown.
+ */
+export declare function renderReport(result: AnalysisResult): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/extensions/code-order/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/extensions/code-order/report.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyB,MAAM,YAAY,CAAC;AAgDxE;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA0F3D"}

package/dist/extensions/code-order/report.js

@@ -0,0 +1,140 @@
+/**
+ * Code Order — Markdown report generator.
+ *
+ * Turns an {@link AnalysisResult} into a human/agent-readable Markdown report
+ * with a summary, prioritized issues, top largest files, and the extension
+ * distribution. The report is returned to the session so the LLM can deduce
+ * what to reorganize next.
+ */
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function severityEmoji(sev) {
+    switch (sev) {
+        case "critical":
+            return "🔴";
+        case "warning":
+            return "🟡";
+        default:
+            return "ℹ️";
+    }
+}
+function groupByType(issues) {
+    const out = new Map();
+    for (const i of issues) {
+        const arr = out.get(i.type) ?? [];
+        arr.push(i);
+        out.set(i.type, arr);
+    }
+    return out;
+}
+const ISSUE_TITLES = {
+    oversized_file: "Oversized files",
+    deep_nesting: "Deep nesting",
+    empty_folder: "Empty folders",
+    empty_file: "Empty files",
+    duplicate_names: "Duplicate sibling folder names",
+    single_child_folder: "Single-child folders",
+};
+const ISSUE_ORDER = [
+    "oversized_file",
+    "deep_nesting",
+    "duplicate_names",
+    "empty_folder",
+    "empty_file",
+    "single_child_folder",
+];
+/**
+ * Render the full cleanup report as Markdown.
+ */
+export function renderReport(result) {
+    const { root, generatedAt, metrics, issues } = result;
+    const lines = [];
+    lines.push(`# Code Order Report — ${root}`);
+    lines.push("");
+    lines.push(`_Generated: ${generatedAt}_`);
+    lines.push("");
+    // Summary
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`**${metrics.totalFiles.toLocaleString()} files** | ` +
+        `**${metrics.totalFolders.toLocaleString()} folders** | ` +
+        `**${formatBytes(metrics.totalSize)} total** | ` +
+        `max depth ${metrics.maxDepth}`);
+    lines.push("");
+    // Issues
+    if (issues.length === 0) {
+        lines.push("## Issues");
+        lines.push("");
+        lines.push("✅ No structural issues detected. The project looks tidy.");
+        lines.push("");
+    }
+    else {
+        const grouped = groupByType(issues);
+        const counts = { critical: 0, warning: 0, info: 0 };
+        for (const i of issues)
+            counts[i.severity]++;
+        lines.push(`## Issues (${issues.length})`);
+        lines.push("");
+        lines.push(`**${counts.critical} critical** · **${counts.warning} warnings** · **${counts.info} info**`);
+        lines.push("");
+        for (const type of ISSUE_ORDER) {
+            const group = grouped.get(type);
+            if (!group || group.length === 0)
+                continue;
+            const sev = group[0].severity;
+            lines.push(`### ${severityEmoji(sev)} ${ISSUE_TITLES[type]} (${group.length})`);
+            lines.push("");
+            if (type === "oversized_file") {
+                lines.push("| Size | Path | Suggestion |");
+                lines.push("|------|------|------------|");
+                for (const i of group) {
+                    const size = i.message.match(/is ([\d.]+ [KMG]?B)/)?.[1] ?? "?";
+                    lines.push(`| ${size} | \`${i.path}\` | ${i.suggestion ?? ""} |`);
+                }
+                lines.push("");
+            }
+            else {
+                for (const i of group) {
+                    lines.push(`- \`${i.path}\` — ${i.message}`);
+                    if (i.suggestion)
+                        lines.push(`  - ${i.suggestion}`);
+                }
+                lines.push("");
+            }
+        }
+    }
+    // Top largest files
+    if (metrics.topLargestFiles.length > 0) {
+        lines.push(`## Top ${metrics.topLargestFiles.length} largest files`);
+        lines.push("");
+        lines.push("| Size | Path |");
+        lines.push("|------|------|");
+        for (const f of metrics.topLargestFiles) {
+            lines.push(`| ${formatBytes(f.size)} | \`${f.path}\` |`);
+        }
+        lines.push("");
+    }
+    // Extension distribution
+    if (metrics.extensions.length > 0) {
+        lines.push("## Extension distribution");
+        lines.push("");
+        lines.push("| Extension | Files | Total size |");
+        lines.push("|-----------|-------|------------|");
+        for (const e of metrics.extensions.slice(0, 20)) {
+            lines.push(`| .${e.extension} | ${e.count} | ${formatBytes(e.size)} |`);
+        }
+        if (metrics.extensions.length > 20) {
+            lines.push(`| … | … | … |`);
+            lines.push(`| _total_ | ${metrics.totalFiles} | ${formatBytes(metrics.totalSize)} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/extensions/code-order/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Code Order — shared types.
+ *
+ * Tree-like representation of a scanned directory. Every node is either a file
+ * or a folder; folders aggregate size/file/folder counts from their children.
+ */
+export interface FileNode {
+    readonly path: string;
+    readonly name: string;
+    readonly size: number;
+    /** Lowercase extension without the leading dot. Empty string when none. */
+    readonly extension: string;
+    readonly isFile: true;
+    readonly mtime: number;
+}
+export interface FolderNode {
+    path: string;
+    name: string;
+    isFile: false;
+    totalSize: number;
+    fileCount: number;
+    folderCount: number;
+    maxDepth: number;
+    children: TreeNode[];
+}
+export type TreeNode = FileNode | FolderNode;
+export type IssueType = "oversized_file" | "deep_nesting" | "empty_folder" | "empty_file" | "duplicate_names" | "single_child_folder";
+export type IssueSeverity = "info" | "warning" | "critical";
+export interface Issue {
+    type: IssueType;
+    severity: IssueSeverity;
+    path: string;
+    message: string;
+    suggestion?: string;
+}
+export interface ExtensionEntry {
+    extension: string;
+    count: number;
+    size: number;
+}
+export interface ProjectMetrics {
+    totalFiles: number;
+    totalFolders: number;
+    totalSize: number;
+    maxDepth: number;
+    avgFileSize: number;
+    medianFileSize: number;
+    extensions: ExtensionEntry[];
+    topLargestFiles: FileNode[];
+    emptyFolders: string[];
+    emptyFiles: string[];
+}
+export interface AnalysisResult {
+    root: string;
+    generatedAt: string;
+    metrics: ProjectMetrics;
+    issues: Issue[];
+}
+export interface AnalysisOptions {
+    /** Absolute directory to analyze. Defaults to process.cwd(). */
+    root: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/extensions/code-order/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/extensions/code-order/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE7C,MAAM,MAAM,SAAS,GAClB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,YAAY,GACZ,iBAAiB,GACjB,qBAAqB,CAAC;AAEzB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAE5D,MAAM,WAAW,KAAK;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,eAAe,EAAE,QAAQ,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,KAAK,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC/B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACb"}

package/dist/extensions/code-order/types.js

@@ -0,0 +1,7 @@
+/**
+ * Code Order — shared types.
+ *
+ * Tree-like representation of a scanned directory. Every node is either a file
+ * or a folder; folders aggregate size/file/folder counts from their children.
+ */
+export {};

package/dist/mcp/ui-stream-types.d.ts

@@ -43,7 +43,7 @@ export declare const visualizationStreamEnvelopeSchema: z.ZodObject<{
     streamId: string;
     sequence: number;
     frameType: "patch" | "checkpoint" | "final";
-    phase: "settled" | "shell" | "narrative" | "structure" | "detail";
+    phase: "structure" | "settled" | "shell" | "narrative" | "detail";
     message?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     checkpoint?: Record<string, unknown> | undefined;
@@ -52,7 +52,7 @@ export declare const visualizationStreamEnvelopeSchema: z.ZodObject<{
     streamId: string;
     sequence: number;
     frameType: "patch" | "checkpoint" | "final";
-    phase: "settled" | "shell" | "narrative" | "structure" | "detail";
+    phase: "structure" | "settled" | "shell" | "narrative" | "detail";
     message?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     checkpoint?: Record<string, unknown> | undefined;

package/dist/relay/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/relay/dispatcher.js

@@ -58,6 +58,7 @@ import { handleGetAgentSettings, handleListAgents, handlePutAgentSettings, } fro
 import { handleGetSettings, handlePutSettings, } from "../server/handlers/settings.js";
 import { handleGetPromptMutationSettings, handlePutPromptMutationSettings, } from "../server/handlers/prompt-mutation-settings.js";
 import { shutdownState } from "../server/shutdown.js";
+import { humanizeProviderError } from "../server/error-humanizer.js";
 import { handleAutoResearch } from "./auto-research.js";
 import { handleAutoOptimize } from "./auto-optimizer.js";
 /**
@@ -1212,7 +1213,7 @@ export function handleClientMessage(frame, deps) {
             relay.send({
                 kind: "ws_event",
                 sessionId,
-                event: { type: "error", message: msg },
+                event: { type: "error", message: humanizeProviderError(err) },
             });
             return;
         }
@@ -1250,7 +1251,7 @@ export function handleClientMessage(frame, deps) {
             relay.send({
                 kind: "ws_event",
                 sessionId,
-                event: { type: "error", message: msg },
+                event: { type: "error", message: humanizeProviderError(err) },
             });
         });
     }
@@ -1311,7 +1312,7 @@ export function handleSubscribe(frame, deps) {
         relay.send({
             kind: "ws_event",
             sessionId,
-            event: { type: "error", message: msg },
+            event: { type: "error", message: humanizeProviderError(err) },
         });
         return;
     }
@@ -1342,7 +1343,7 @@ export function handleSubscribe(frame, deps) {
             relay.send({
                 kind: "ws_event",
                 sessionId,
-                event: { type: "error", message: msg },
+                event: { type: "error", message: humanizeProviderError(err) },
             });
         });
     }

package/dist/sdk/coding-agent/core/extensions/native-extensions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-extensions.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/extensions/native-extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;IAChD;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;IACxB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,uBAAuB,EA0HtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAElF;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAI1G;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IAClG,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC,CAUD"}
+{"version":3,"file":"native-extensions.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/extensions/native-extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;IAChD;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;IACxB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,uBAAuB,EAsItD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAElF;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAI1G;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IAClG,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC,CAUD"}

package/dist/sdk/coding-agent/core/extensions/native-extensions.js

@@ -129,6 +129,17 @@ export const NATIVE_EXTENSIONS = [
         defaultEnabled: true,
         tags: ["screenshot", "desktop", "vision", "screen"],
     },
+    {
+        id: "code-order",
+        label: "Code Order",
+        description: "Analyzes folder structure and file sizes, then generates a cleanup report " +
+            "(oversized files, deep nesting, empty folders, duplicates, single-child folders). " +
+            "Language-agnostic, read-only, zero config. Input for reorganizing code.",
+        category: "automation",
+        entryPath: "src/extensions/code-order/index.ts",
+        defaultEnabled: true,
+        tags: ["structure", "analysis", "cleanup", "tree", "audit"],
+    },
 ];
 /**
  * Look up a native extension by id. Returns undefined for unknown ids.

package/dist/sdk/coding-agent/core/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/core/system-prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACxC,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,yBAAyB;IACzB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAwK3E"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/core/system-prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACxC,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,yBAAyB;IACzB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CA4K3E"}

package/dist/sdk/coding-agent/core/system-prompt.js

@@ -86,6 +86,8 @@ export function buildSystemPrompt(options) {
             addGuideline(normalized);
         }
     }
+    addGuideline("When creating new files, maintain a tree-like directory structure. Place files in semantically meaningful subdirectories (e.g. `handlers/auth/`, `utils/string/`) rather than dumping them at the project root or in shallow flat folders. Group related files into dedicated folders, prefer `feature/module/file.ts` over `feature-file.ts` at root. Avoid creating files directly in root unless they are truly project-wide (e.g. config, package.json). Keep folder depth reasonable (max 5–6 levels) but prefer nesting over flattening — tree-like structure improves LLM navigability and agentic coding efficiency.");
+    addGuideline("When editing code, first inspect nearby files and existing patterns; follow the codebase’s conventions and libraries");
     addGuideline("When editing code, first inspect nearby files and existing patterns; follow the codebase’s conventions and libraries");
     // Always include these
     if (hasSubagent) {

package/dist/sdk/coding-agent/core/tools/bash-blocklist.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Bash command blocklist for filesystem-wide scans.
+ *
+ * Blocks recursive scans originating from the filesystem root `/` or other
+ * system directories (e.g. `/etc`, `/home`, `/usr`, `/var`) because they can
+ * take a very long time and are almost never the intended action inside a
+ * workspace-scoped bash tool. Scoped scans (e.g. `find .`, `grep -r src/`,
+ * `ls -R src/`) remain allowed.
+ *
+ * This is intentionally a regex-based heuristic, not a full shell parser. It
+ * targets the common scan shapes; exotic obfuscation is out of scope.
+ */
+/** Result of a blocklist check. */
+export interface BashBlocklistResult {
+    /** Whether the command should be blocked. */
+    blocked: boolean;
+    /** Human-readable reason (empty when not blocked). */
+    reason: string;
+}
+/**
+ * Default, reusable explanation returned to the LLM when a command is blocked.
+ * Phrased to steer the model toward a scoped alternative.
+ */
+export declare const BASH_BLOCKLIST_REASON: string;
+/**
+ * Check a bash command against the filesystem-scan blocklist.
+ *
+ * @param command The raw command string passed to the bash tool (after any
+ *   command prefix has been applied).
+ * @returns `{ blocked: true, reason }` when the command matches a blocked
+ *   pattern, otherwise `{ blocked: false, reason: "" }`.
+ *
+ * @example
+ * checkBashBlocklist("find /")            // { blocked: true, ... }
+ * checkBashBlocklist("find / -name foo")  // { blocked: true, ... }
+ * checkBashBlocklist("find .")            // { blocked: false, reason: "" }
+ * checkBashBlocklist("grep -r /")         // { blocked: true, ... }
+ * checkBashBlocklist("grep -r src/")      // { blocked: false, reason: "" }
+ * checkBashBlocklist("cat /etc/hosts")    // { blocked: false, reason: "" }
+ */
+export declare function checkBashBlocklist(command: string): BashBlocklistResult;
+//# sourceMappingURL=bash-blocklist.d.ts.map

package/dist/sdk/coding-agent/core/tools/bash-blocklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-blocklist.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/bash-blocklist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IACnC,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CACf;AA0GD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAGgD,CAAC;AAEnF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAevE"}

package/dist/sdk/coding-agent/core/tools/bash-blocklist.js

@@ -0,0 +1,141 @@
+/**
+ * Bash command blocklist for filesystem-wide scans.
+ *
+ * Blocks recursive scans originating from the filesystem root `/` or other
+ * system directories (e.g. `/etc`, `/home`, `/usr`, `/var`) because they can
+ * take a very long time and are almost never the intended action inside a
+ * workspace-scoped bash tool. Scoped scans (e.g. `find .`, `grep -r src/`,
+ * `ls -R src/`) remain allowed.
+ *
+ * This is intentionally a regex-based heuristic, not a full shell parser. It
+ * targets the common scan shapes; exotic obfuscation is out of scope.
+ */
+/**
+ * Absolute system paths that a workspace bash tool should never recursively
+ * scan. Each entry is matched as a literal path token (anchored or
+ * space/quote-delimited) and is also the prefix of a directory subtree.
+ *
+ * Notes:
+ * - `/` is the root.
+ * - We deliberately exclude `/tmp` and `/Users` style home roots here; they
+ *   are handled by the recursive-root rules where relevant, but blocking every
+ *   `/Users/...` access would also block legitimate `cat /Users/.../file`
+ *   reads. We only block *recursive scans* against `/`, not arbitrary reads.
+ */
+const SYSTEM_SCAN_ROOTS = [
+    "/",
+    "/etc",
+    "/home",
+    "/usr",
+    "/var",
+    "/bin",
+    "/sbin",
+    "/lib",
+    "/lib64",
+    "/opt",
+    "/root",
+    "/sys",
+    "/proc",
+    "/dev",
+    "/boot",
+    "/srv",
+    "/mnt",
+    "/media",
+];
+/**
+ * Build an alternation of system roots, escaping regex metacharacters. `/` has
+ * no special regex meaning so it does not need escaping, but we escape it for
+ * safety/generality. Longest entries first so `/etc` matches before `/`.
+ */
+const ROOTS_ALT = SYSTEM_SCAN_ROOTS.slice()
+    .sort((a, b) => b.length - a.length)
+    .map((r) => r.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|");
+/**
+ * Match a command token that starts with one of the system roots.
+ *
+ * The token is anchored by start-of-string, a preceding space, or an opening
+ * quote, and extends to the next whitespace or end-of-string. This prevents
+ * false positives like `cat /etc/hosts` being treated as a scan of `/etc`,
+ * because we only apply this pattern to recursive-scan commands (find/grep -r
+ * / ls -R) below.
+ *
+ * Captured group 1 is the matched root path token.
+ */
+const SYSTEM_ROOT_TOKEN = new RegExp(`(?:^|\\s|['"])(?<root>${ROOTS_ALT})[^\\s'"]*(?=\\s|$|['"])`);
+/**
+ * `find <root>` — `find` invoked with a system root as one of its path
+ * arguments. We match `find` followed by optional flags/options and then a
+ * system-root token anywhere in the argument list.
+ *
+ * `find` is inherently recursive, so any `find /` (or `find /etc ...`) is a
+ * filesystem scan. Scoped forms (`find .`, `find src/`, `find ./packages`)
+ * are not matched because their path tokens are not system roots.
+ */
+const FIND_SYSTEM_ROOT = new RegExp(
+// `find` as its own token, followed by anything, then a system-root token.
+`(?:^|[\\s;&|]+)(?:sudo\\s+)?find\\b.*${SYSTEM_ROOT_TOKEN.source}`);
+/**
+ * Recursive grep targeting a system root. Requires a recursive flag
+ * (`-r`, `-R`, `--recursive`, or a combined short flag containing `r`/`R`
+ * such as `-rn`, `-RI`, `-rnI`) and a system-root path token.
+ *
+ * Supports `grep`, `ggrep`, `egrep`, `fgrep`, `rg` (ripgrep), and `ack`.
+ */
+const GREP_SYSTEM_ROOT = new RegExp(`(?:^|[\\s;&|]+)(?:sudo\\s+)?(?:g?grep|egrep|fgrep)\\b` +
+    // require a recursive flag somewhere before/after — combined short flags
+    // like -rn, -RI are covered by [-][A-Za-z]*[rR][A-Za-z]*
+    `.*(?:-r\\b|-R\\b|--recursive\\b|-[A-Za-z]*[rR][A-Za-z]*)` +
+    `.*${SYSTEM_ROOT_TOKEN.source}`);
+/**
+ * Recursive `ls` targeting a system root. `ls` is only a scan when `-R`
+ * (or a combined short flag containing `R`, e.g. `-laR`, `-AR`) is present
+ * AND the target is a system root.
+ */
+const LS_SYSTEM_ROOT = new RegExp(`(?:^|[\\s;&|]+)(?:sudo\\s+)?ls\\b` +
+    `.*(?:-R\\b|--recursive\\b|-[A-Za-z]*R[A-Za-z]*)` +
+    `.*${SYSTEM_ROOT_TOKEN.source}`);
+const BLOCKED_PATTERNS = [
+    { name: "find on system root", pattern: FIND_SYSTEM_ROOT },
+    { name: "recursive grep on system root", pattern: GREP_SYSTEM_ROOT },
+    { name: "recursive ls on system root", pattern: LS_SYSTEM_ROOT },
+];
+/**
+ * Default, reusable explanation returned to the LLM when a command is blocked.
+ * Phrased to steer the model toward a scoped alternative.
+ */
+export const BASH_BLOCKLIST_REASON = "Command blocked: a filesystem-wide scan starting from a system root ('/' or a system directory such as /etc, /usr, /home) was detected. " +
+    "Such scans can take a very long time. Use the find/grep/ls tools with a scoped path within the workspace " +
+    "(e.g. '.', 'src/', './packages') instead of scanning '/' or system directories.";
+/**
+ * Check a bash command against the filesystem-scan blocklist.
+ *
+ * @param command The raw command string passed to the bash tool (after any
+ *   command prefix has been applied).
+ * @returns `{ blocked: true, reason }` when the command matches a blocked
+ *   pattern, otherwise `{ blocked: false, reason: "" }`.
+ *
+ * @example
+ * checkBashBlocklist("find /")            // { blocked: true, ... }
+ * checkBashBlocklist("find / -name foo")  // { blocked: true, ... }
+ * checkBashBlocklist("find .")            // { blocked: false, reason: "" }
+ * checkBashBlocklist("grep -r /")         // { blocked: true, ... }
+ * checkBashBlocklist("grep -r src/")      // { blocked: false, reason: "" }
+ * checkBashBlocklist("cat /etc/hosts")    // { blocked: false, reason: "" }
+ */
+export function checkBashBlocklist(command) {
+    if (typeof command !== "string" || command.length === 0) {
+        return { blocked: false, reason: "" };
+    }
+    // Strip quoted substrings before matching so that system-root tokens that
+    // appear only inside a quoted option value (e.g. `find . -name '/etc/hosts'`)
+    // do not false-positive. A real scan target like `find /` or `grep -r /etc`
+    // is an unquoted path token and survives this stripping.
+    const normalized = command.replace(/'[^']*'|"[^"]*"/g, "");
+    for (const { pattern } of BLOCKED_PATTERNS) {
+        if (pattern.test(normalized)) {
+            return { blocked: true, reason: BASH_BLOCKLIST_REASON };
+        }
+    }
+    return { blocked: false, reason: "" };
+}

package/dist/sdk/coding-agent/core/tools/bash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/bash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAU5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,OAAO,EAAoD,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAExG,QAAA,MAAM,UAAU;;;EAGd,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,IAAI,EAAE,CACL,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QACR,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;KACxB,KACG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAkF1F;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;AAO5E,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,aAAa,CAAC;CAC1B;AAyFD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAsIhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/bash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAU5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAK7D,OAAO,EAAoD,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAExG,QAAA,MAAM,UAAU;;;EAGd,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,IAAI,EAAE,CACL,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QACR,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;KACxB,KACG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAkF1F;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;AAO5E,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,aAAa,CAAC;CAC1B;AAyFD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CA0IhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}