@bubblebrain-ai/bubble 0.0.58 → 0.0.60

package/dist/tools/edit-apply.js

@@ -21,38 +21,36 @@ function stripBom(content) {
 function normalizeToLF(text) {
     return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 }
-function unescapeOverEscaped(text) {
-    return text
-        .replace(/\\u([0-9a-fA-F]{4})/g, (_match, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
-        .replace(/\\n/g, "\n")
-        .replace(/\\t/g, "\t")
-        .replace(/\\r/g, "\r")
-        .replace(/\\f/g, "\f")
-        .replace(/\\b/g, "\b")
-        .replace(/\\v/g, "\v")
-        .replace(/\\"/g, '"')
-        .replace(/\\\\/g, "\\");
-}
-function addTextCandidate(candidates, seen, text, mode) {
-    if (text.length === 0 || seen.has(text))
-        return;
-    seen.add(text);
-    candidates.push({ text, mode });
-}
-function generateTextCandidates(oldText) {
-    const candidates = [];
-    const seen = new Set();
-    const trimmed = oldText.trim();
-    const unescaped = normalizeToLF(unescapeOverEscaped(oldText));
-    const unescapedTrimmed = normalizeToLF(unescapeOverEscaped(trimmed));
-    addTextCandidate(candidates, seen, oldText, "exact");
-    addTextCandidate(candidates, seen, trimmed, "trimmed");
-    addTextCandidate(candidates, seen, unescaped, "unescaped");
-    addTextCandidate(candidates, seen, unescapedTrimmed, "unescaped");
-    return candidates;
-}
-function restoreLineEndings(text, lineEnding) {
-    return lineEnding === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+function buildOriginalOffsets(text) {
+    const offsets = [];
+    for (let i = 0; i < text.length; i++) {
+        offsets.push(i);
+        if (text[i] === "\r" && text[i + 1] === "\n")
+            i++;
+    }
+    offsets.push(text.length);
+    return offsets;
+}
+function lineEndingAt(text, offset, fallback) {
+    const after = text.slice(offset).match(/\r\n|\r|\n/);
+    if (after)
+        return after[0];
+    const before = text.slice(0, offset).match(/(\r\n|\r|\n)[^\r\n]*$/);
+    return before ? before[1] : fallback;
+}
+// Splices replacements into the original text so untouched lines keep their own
+// terminators; inserted text uses the terminator of the line being edited.
+function spliceOriginal(text, matches, edits, fallbackEnding) {
+    const offsets = buildOriginalOffsets(text);
+    let out = "";
+    let cursor = 0;
+    for (const match of [...matches].sort((a, b) => a.start - b.start)) {
+        const start = offsets[match.start];
+        const ending = lineEndingAt(text, start, fallbackEnding);
+        out += text.slice(cursor, start) + edits[match.editIndex].newText.replace(/\n/g, ending);
+        cursor = offsets[match.end];
+    }
+    return out + text.slice(cursor);
 }
 function normalizeLineForMatch(line) {
     return line
@@ -63,9 +61,6 @@ function normalizeLineForMatch(line) {
         .replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
         .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
 }
-function normalizeLeadingWhitespaceForMatch(line) {
-    return normalizeLineForMatch(line).replace(/^\s+/, " ");
-}
 function findAllOccurrences(content, needle) {
     const indexes = [];
     if (needle.length === 0)
@@ -104,130 +99,6 @@ function normalizedOldNonBlankLines(oldText) {
         .map((line) => normalizeLineForMatch(line.text))
         .filter((line) => line.trim().length > 0);
 }
-function singleNonBlankOldLine(oldText) {
-    const lines = normalizedOldNonBlankLines(oldText);
-    return lines.length === 1 ? lines[0] : undefined;
-}
-function findNormalizedLineMatches(content, oldText) {
-    const contentLines = splitLines(content);
-    const searchable = nonBlankLines(contentLines);
-    const oldLines = normalizedOldNonBlankLines(oldText);
-    if (oldLines.length === 0)
-        return [];
-    const matches = [];
-    for (let i = 0; i <= searchable.length - oldLines.length; i++) {
-        let matched = true;
-        for (let j = 0; j < oldLines.length; j++) {
-            if (searchable[i + j].normalized !== oldLines[j]) {
-                matched = false;
-                break;
-            }
-        }
-        if (matched) {
-            const first = contentLines[searchable[i].lineIndex];
-            const last = contentLines[searchable[i + oldLines.length - 1].lineIndex];
-            matches.push({ start: first.start, end: last.endNoNewline });
-        }
-    }
-    return matches;
-}
-function findSmartLineMatches(content, oldText) {
-    const contentLines = splitLines(content);
-    const oldLines = splitLines(oldText).map((line) => normalizeLeadingWhitespaceForMatch(line.text));
-    if (oldLines.length === 0 || oldLines.every((line) => line.length === 0))
-        return [];
-    const matches = [];
-    for (let i = 0; i <= contentLines.length - oldLines.length; i++) {
-        let matched = true;
-        for (let j = 0; j < oldLines.length; j++) {
-            const actual = normalizeLeadingWhitespaceForMatch(contentLines[i + j].text);
-            if (actual !== oldLines[j]) {
-                matched = false;
-                break;
-            }
-        }
-        if (matched) {
-            const first = contentLines[i];
-            const last = contentLines[i + oldLines.length - 1];
-            matches.push({ start: first.start, end: last.endNoNewline });
-        }
-    }
-    return matches;
-}
-function splitMarkdownTableCells(line) {
-    const normalized = normalizeLineForMatch(line).trim();
-    if (!normalized.startsWith("|") || !normalized.endsWith("|"))
-        return undefined;
-    const parts = [];
-    let current = "";
-    let escaped = false;
-    for (const char of normalized) {
-        if (escaped) {
-            current += char;
-            escaped = false;
-            continue;
-        }
-        if (char === "\\") {
-            current += char;
-            escaped = true;
-            continue;
-        }
-        if (char === "|") {
-            parts.push(current);
-            current = "";
-            continue;
-        }
-        current += char;
-    }
-    parts.push(current);
-    if (parts.length < 4 || parts[0] !== "" || parts[parts.length - 1] !== "")
-        return undefined;
-    const cells = parts.slice(1, -1).map((cell) => cell.trim());
-    return cells.length >= 2 ? cells : undefined;
-}
-function sameCells(a, b) {
-    return a.length === b.length && a.every((cell, index) => cell === b[index]);
-}
-function findMarkdownTableMatches(content, oldText) {
-    const oldLine = singleNonBlankOldLine(oldText);
-    if (!oldLine)
-        return [];
-    const oldCells = splitMarkdownTableCells(oldLine);
-    if (!oldCells)
-        return [];
-    const matches = [];
-    for (const line of splitLines(content)) {
-        const cells = splitMarkdownTableCells(line.text);
-        if (cells && sameCells(cells, oldCells)) {
-            matches.push({ start: line.start, end: line.endNoNewline });
-        }
-    }
-    return matches;
-}
-function collapseInlineWhitespace(text) {
-    return normalizeLineForMatch(text).trim().replace(/[ \t]+/g, " ");
-}
-function isDocumentLikePath(path) {
-    return !!path && /\.(?:md|mdx|markdown|txt|rst|adoc)$/i.test(path);
-}
-function findSingleLineWhitespaceMatches(content, oldText, options) {
-    if (!isDocumentLikePath(options?.path))
-        return [];
-    const oldLine = singleNonBlankOldLine(oldText);
-    if (!oldLine)
-        return [];
-    const normalizedOld = collapseInlineWhitespace(oldLine);
-    if (normalizedOld.length === 0)
-        return [];
-    const matches = [];
-    for (const line of splitLines(content)) {
-        const collapsed = collapseInlineWhitespace(line.text);
-        if (collapsed === normalizedOld && line.text !== oldLine) {
-            matches.push({ start: line.start, end: line.endNoNewline });
-        }
-    }
-    return matches;
-}
 function summarizeOldText(oldText) {
     const firstLine = normalizeToLF(oldText).split("\n").find((line) => line.trim().length > 0) ?? oldText;
     return firstLine.length > 80 ? `${firstLine.slice(0, 80)}...` : firstLine;
@@ -326,88 +197,18 @@ function matchEdit(content, edit, index, total, options) {
         ].join("\n"));
     }
     const oldText = normalizeToLF(edit.oldText);
-    const candidates = generateTextCandidates(oldText);
-    for (const candidate of candidates) {
-        const exact = findAllOccurrences(content, candidate.text);
-        if (exact.length === 1) {
-            return { editIndex: index, mode: candidate.mode, start: exact[0], end: exact[0] + candidate.text.length };
-        }
-        if (exact.length > 1) {
-            const recovery = [
-                "",
-                "Extend oldText with more surrounding context (the lines immediately before/after) until it uniquely identifies the intended span.",
-            ].join("\n");
-            const duplicateReason = candidate.mode === "exact"
-                ? `appears ${exact.length} times in file`
-                : `matched ${exact.length} times after ${candidate.mode} matching`;
-            throw new EditApplyError(total === 1
-                ? `Error: oldText ${duplicateReason}. Must be unique: "${summarizeOldText(oldText)}"${recovery}`
-                : `Error: edits[${index}].oldText ${duplicateReason}. Must be unique: "${summarizeOldText(oldText)}"${recovery}`);
-        }
-    }
-    for (const candidate of candidates) {
-        const normalizedLineMatches = findNormalizedLineMatches(content, candidate.text);
-        if (normalizedLineMatches.length === 1) {
-            return {
-                editIndex: index,
-                mode: candidate.mode === "exact" ? "normalized-line" : candidate.mode,
-                start: normalizedLineMatches[0].start,
-                end: normalizedLineMatches[0].end,
-            };
-        }
-        if (normalizedLineMatches.length > 1) {
-            throw new EditApplyError(total === 1
-                ? `Error: oldText matched ${normalizedLineMatches.length} normalized line blocks in file. Provide more surrounding context.`
-                : `Error: edits[${index}].oldText matched ${normalizedLineMatches.length} normalized line blocks in file. Provide more surrounding context.`);
-        }
-    }
-    for (const candidate of candidates) {
-        const markdownTableMatches = findMarkdownTableMatches(content, candidate.text);
-        if (markdownTableMatches.length === 1) {
-            return {
-                editIndex: index,
-                mode: "markdown-table",
-                start: markdownTableMatches[0].start,
-                end: markdownTableMatches[0].end,
-            };
-        }
-        if (markdownTableMatches.length > 1) {
-            throw new EditApplyError(total === 1
-                ? `Error: oldText matched ${markdownTableMatches.length} markdown table rows in file. Provide more surrounding context.`
-                : `Error: edits[${index}].oldText matched ${markdownTableMatches.length} markdown table rows in file. Provide more surrounding context.`);
-        }
-    }
-    for (const candidate of candidates) {
-        const whitespaceMatches = findSingleLineWhitespaceMatches(content, candidate.text, options);
-        if (whitespaceMatches.length === 1) {
-            return {
-                editIndex: index,
-                mode: "single-line-whitespace",
-                start: whitespaceMatches[0].start,
-                end: whitespaceMatches[0].end,
-            };
-        }
-        if (whitespaceMatches.length > 1) {
-            throw new EditApplyError(total === 1
-                ? `Error: oldText matched ${whitespaceMatches.length} whitespace-normalized lines in file. Provide more surrounding context.`
-                : `Error: edits[${index}].oldText matched ${whitespaceMatches.length} whitespace-normalized lines in file. Provide more surrounding context.`);
-        }
+    const occurrences = findAllOccurrences(content, oldText);
+    if (occurrences.length === 1) {
+        return { editIndex: index, start: occurrences[0], end: occurrences[0] + oldText.length };
     }
-    for (const candidate of candidates) {
-        const smartLineMatches = findSmartLineMatches(content, candidate.text);
-        if (smartLineMatches.length === 1) {
-            return {
-                editIndex: index,
-                mode: "smart-line",
-                start: smartLineMatches[0].start,
-                end: smartLineMatches[0].end,
-            };
-        }
-        if (smartLineMatches.length > 1) {
-            throw new EditApplyError(total === 1
-                ? `Error: oldText matched ${smartLineMatches.length} indentation-normalized line blocks in file. Provide more surrounding context.`
-                : `Error: edits[${index}].oldText matched ${smartLineMatches.length} indentation-normalized line blocks in file. Provide more surrounding context.`);
-        }
+    if (occurrences.length > 1) {
+        const recovery = [
+            "",
+            "Extend oldText with more surrounding context (the lines immediately before/after) until it uniquely identifies the intended span.",
+        ].join("\n");
+        throw new EditApplyError(total === 1
+            ? `Error: oldText appears ${occurrences.length} times in file. Must be unique: "${summarizeOldText(oldText)}"${recovery}`
+            : `Error: edits[${index}].oldText appears ${occurrences.length} times in file. Must be unique: "${summarizeOldText(oldText)}"${recovery}`);
     }
     const hint = findBestLineHint(content, oldText);
     const hintSuffix = hint ? `\n${formatBestLineHint(content, hint, options)}` : "";
@@ -439,9 +240,10 @@ export function applyEditsToContent(rawContent, edits, options) {
     const { bom, text } = stripBom(rawContent);
     const lineEnding = detectLineEnding(text);
     const normalizedOriginal = normalizeToLF(text);
+    const dropCopiedBom = (value) => (bom ? stripBom(value).text : value);
     const normalizedEdits = edits.map((edit) => ({
-        oldText: normalizeToLF(edit.oldText),
-        newText: normalizeToLF(edit.newText),
+        oldText: normalizeToLF(dropCopiedBom(edit.oldText)),
+        newText: normalizeToLF(dropCopiedBom(edit.newText)),
     }));
     const matches = normalizedEdits.map((edit, index) => matchEdit(normalizedOriginal, edit, index, normalizedEdits.length, options));
     assertNoOverlaps(matches);
@@ -462,7 +264,7 @@ export function applyEditsToContent(rawContent, edits, options) {
         ].join("\n"));
     }
     return {
-        content: bom + restoreLineEndings(normalizedNext, lineEnding),
+        content: bom + spliceOriginal(text, matches, normalizedEdits, lineEnding),
         normalizedOriginal,
         normalizedNext,
         bom,
@@ -470,9 +272,3 @@ export function applyEditsToContent(rawContent, edits, options) {
         matches,
     };
 }
-export function formatEditMatchNotes(matches) {
-    const normalizedCount = matches.filter((match) => match.mode !== "exact").length;
-    if (normalizedCount === 0)
-        return "";
-    return `\n\nNote: ${normalizedCount} edit${normalizedCount === 1 ? "" : "s"} applied using normalized line matching for whitespace/formatting differences.`;
-}

package/dist/tools/edit.js

@@ -9,7 +9,7 @@ import { createTwoFilesPatch } from "diff";
 import { gateToolAction } from "../approval/tool-helper.js";
 import { countUnifiedDiffChanges } from "../diff-stats.js";
 import { formatDiagnosticBlocks } from "../lsp/index.js";
-import { applyEditsToContent, EditApplyError, formatEditMatchNotes } from "./edit-apply.js";
+import { applyEditsToContent, EditApplyError } from "./edit-apply.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { isWithinWorkspace } from "./file-state.js";
 import { resolveToolPath } from "./path-utils.js";
@@ -65,7 +65,7 @@ export function createEditTool(cwd, approval, lsp, fileState, checkpoints) {
         name: "edit",
         effect: "write_direct",
         requiresApproval: true,
-        description: "Edit a single file using targeted text replacements. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes overlap or one replacement is nested inside another, merge them into one edit. Do not include large unchanged regions just to connect distant changes.",
+        description: "Edit a single file using targeted text replacements. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes overlap or one replacement is nested inside another, merge them into one edit. Do not include large unchanged regions just to connect distant changes. Matching is exact; a UTF-8 BOM and CRLF line endings are handled automatically and preserved, so write oldText/newText with plain \\n line breaks.",
         promptSnippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call",
         promptGuidelines: [
             "Use edit for precise changes; each edits[].oldText must be copied verbatim from a fresh read of the current exact target block and must identify a unique target. Do not reconstruct oldText from memory, stale reads, or similar code elsewhere.",
@@ -173,7 +173,7 @@ export function createEditTool(cwd, approval, lsp, fileState, checkpoints) {
                 await checkpoints?.()?.captureBefore(filePath, original);
                 await writeFile(filePath, applied.content, "utf-8");
                 await fileState?.observe(filePath, "edit", applied.content).catch(() => undefined);
-                let output = `Edited ${filePath}${formatEditMatchNotes(applied.matches)}\n\nDiff:\n${diff}`;
+                let output = `Edited ${filePath}\n\nDiff:\n${diff}`;
                 if (lsp) {
                     try {
                         await lsp.touchFile(filePath, "document");

package/dist/tools/exit-plan-mode.d.ts

@@ -13,5 +13,10 @@ export interface PlanController {
     requestApproval(plan: string): Promise<PlanDecision>;
     /** Switch the agent's mode. Called after an approval so the next turn runs unconstrained. */
     setMode(mode: PermissionMode): void;
+    /**
+     * Mode to switch to once the plan is approved — the mode the user was in
+     * before entering plan mode. Defaults to "default" when omitted.
+     */
+    getExitMode?: () => Exclude<PermissionMode, "plan">;
 }
 export declare function createExitPlanModeTool(controller: PlanController): ToolRegistryEntry;

package/dist/tools/exit-plan-mode.js

@@ -59,12 +59,13 @@ export function createExitPlanModeTool(controller) {
                 };
             }
             if (decision.action === "approve") {
-                controller.setMode("default");
+                const exitMode = controller.getExitMode?.() ?? "default";
+                controller.setMode(exitMode);
                 const finalPlan = decision.plan.trim() || plan;
                 const edited = finalPlan !== plan;
                 return {
                     content: `User approved the plan${edited ? " (with edits)" : ""}. ` +
-                        `Agent mode has been switched to default — you may now execute the plan using any tools. ` +
+                        `Agent mode has been switched to ${exitMode} — you may now execute the plan using any tools. ` +
                         `Approved plan:\n\n${finalPlan}`,
                 };
             }

package/dist/tools/file-state.d.ts

@@ -41,4 +41,8 @@ export declare class FileStateTracker {
     private resolvePath;
     private computeVersion;
 }
+/**
+ * Inside the workspace both as written and where symlinks actually lead, so
+ * a link inside the repository cannot carry an auto-approved write outside.
+ */
 export declare function isWithinWorkspace(cwd: string, filePath: string): boolean;

package/dist/tools/file-state.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { stat, readFile } from "node:fs/promises";
-import { isAbsolute, relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { resolveThroughLinks } from "./path-utils.js";
 export class FileStateTracker {
     cwd;
     observed = new Map();
@@ -61,7 +62,15 @@ export class FileStateTracker {
         };
     }
 }
+/**
+ * Inside the workspace both as written and where symlinks actually lead, so
+ * a link inside the repository cannot carry an auto-approved write outside.
+ */
 export function isWithinWorkspace(cwd, filePath) {
-    const rel = relative(resolve(cwd), filePath);
-    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+    return isInside(resolve(cwd), resolve(filePath))
+        && isInside(resolveThroughLinks(cwd), resolveThroughLinks(filePath));
+}
+function isInside(root, path) {
+    const rel = relative(root, path);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
 }

package/dist/tools/grep.js

@@ -113,6 +113,18 @@ function executeBoundedGrep(options) {
         });
         const decoder = new StringDecoder("utf8");
         const matches = [];
+        // The root check alone is not enough: ripgrep searches inside an explicit
+        // hidden root, so `path: ~/.aws` would reach ~/.aws/credentials. Every
+        // matched file gets the same check the read tool applies (cached per file).
+        const sensitiveByPath = new Map();
+        const isSensitiveMatch = (absolutePath) => {
+            let sensitive = sensitiveByPath.get(absolutePath);
+            if (sensitive === undefined) {
+                sensitive = isSensitivePath(absolutePath);
+                sensitiveByPath.set(absolutePath, sensitive);
+            }
+            return sensitive;
+        };
         let stdoutBuffer = "";
         let stdoutBytes = 0;
         let stderrBytes = 0;
@@ -142,6 +154,13 @@ function executeBoundedGrep(options) {
                 if (event.type !== "match")
                     return;
                 const rawPath = decodeRgField(event.data?.path);
+                // A path that is not valid UTF-8 cannot be checked (or read back by
+                // the model), so its matches are dropped rather than shown unchecked.
+                if (event.data?.path && !rawPath)
+                    return;
+                const absolutePath = rawPath ? resolvePath(options.cwd, rawPath) : undefined;
+                if (absolutePath && isSensitiveMatch(absolutePath))
+                    return;
                 const lineNumber = event.data?.line_number;
                 const rawText = decodeRgField(event.data?.lines, "[non-UTF-8 match bytes omitted]") ?? "";
                 const displayPath = rawPath || "<non-UTF-8 path>";
@@ -149,7 +168,7 @@ function executeBoundedGrep(options) {
                 const rendered = truncateCodePoints(`${displayPath}:${typeof lineNumber === "number" ? lineNumber : "?"}: ${normalizedText}`, MAX_RENDERED_LINE_CODE_POINTS);
                 matches.push({
                     rendered,
-                    ...(rawPath ? { absolutePath: resolvePath(options.cwd, rawPath) } : {}),
+                    ...(absolutePath ? { absolutePath } : {}),
                 });
                 // We stop at N rather than pretending we proved there are N+1 matches.
                 // The notice says "limit reached / may be incomplete", which is honest

package/dist/tools/index.d.ts

@@ -7,7 +7,7 @@ export { createManagedServerTools } from "./server.js";
 export { createWriteTool } from "./write.js";
 export { createEditTool } from "./edit.js";
 export { buildToolPromptOptions } from "./prompt-metadata.js";
-export { createGlobTool } from "./glob.js";
+export { createLsTool } from "./ls.js";
 export { createGrepTool } from "./grep.js";
 export { createLspTool } from "./lsp.js";
 export { createWebFetchTool } from "./web-fetch.js";

package/dist/tools/index.js

@@ -7,7 +7,7 @@ export { createManagedServerTools } from "./server.js";
 export { createWriteTool } from "./write.js";
 export { createEditTool } from "./edit.js";
 export { buildToolPromptOptions } from "./prompt-metadata.js";
-export { createGlobTool } from "./glob.js";
+export { createLsTool } from "./ls.js";
 export { createGrepTool } from "./grep.js";
 export { createLspTool } from "./lsp.js";
 export { createWebFetchTool } from "./web-fetch.js";
@@ -23,7 +23,7 @@ import { createBashTool } from "./bash.js";
 import { createManagedServerTools } from "./server.js";
 import { createEditTool } from "./edit.js";
 import { createExitPlanModeTool } from "./exit-plan-mode.js";
-import { createGlobTool } from "./glob.js";
+import { createLsTool } from "./ls.js";
 import { createGrepTool } from "./grep.js";
 import { getLspService } from "../lsp/index.js";
 import { createLspTool } from "./lsp.js";
@@ -57,7 +57,7 @@ export function createAllTools(cwd, skillRegistry, options = {}) {
         ...createManagedServerTools(cwd, approval),
         createWriteTool(cwd, {}, approval, lsp, fileState, options.checkpoints),
         createEditTool(cwd, approval, lsp, fileState, options.checkpoints),
-        createGlobTool(cwd),
+        createLsTool(cwd),
         createGrepTool(cwd),
         createLspTool(cwd, lsp, approval),
         createWebSearchTool(),

package/dist/tools/ls.d.ts

@@ -0,0 +1,3 @@
+import type { ToolRegistryEntry } from "../types.js";
+/** A shallow directory listing: nested files never crowd out sibling directories. */
+export declare function createLsTool(cwd: string): ToolRegistryEntry;

package/dist/tools/ls.js

@@ -0,0 +1,85 @@
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { resolveToolPath } from "./path-utils.js";
+import { isSensitivePath } from "./sensitive-paths.js";
+const DEFAULT_LIMIT = 500;
+const MAX_BYTES = 50 * 1024;
+/** A shallow directory listing: nested files never crowd out sibling directories. */
+export function createLsTool(cwd) {
+    return {
+        name: "ls",
+        readOnly: true,
+        effect: "read",
+        promptSnippet: "List directory contents, including hidden files and subdirectories",
+        description: `List one directory, sorted alphabetically, including hidden entries. Directories end in '/', symbolic links in '@' (not followed). Defaults to ${DEFAULT_LIMIT} entries; increase limit for more. Output is capped at 50 KiB. Does not recurse.`,
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Directory to list (default: cwd)" },
+                limit: { type: "integer", description: "Positive maximum entries to return (default: 500)" },
+            },
+        },
+        async execute(args, ctx) {
+            const cancelled = () => ({ content: "Directory listing cancelled.", isError: true, status: "cancelled" });
+            if (ctx.abortSignal?.aborted)
+                return cancelled();
+            const limit = args.limit ?? DEFAULT_LIMIT;
+            if (!Number.isSafeInteger(limit) || limit < 1) {
+                return { content: "Error: limit must be a positive integer", isError: true, status: "command_error" };
+            }
+            if (args.path !== undefined && typeof args.path !== "string") {
+                return { content: "Error: path must be a string", isError: true, status: "command_error" };
+            }
+            const root = resolveToolPath(cwd, args.path?.trim() ? args.path : ".");
+            if (isSensitivePath(root)) {
+                return { content: `Error: Listing blocked for sensitive credential storage: ${root}`, isError: true, status: "blocked" };
+            }
+            try {
+                const entries = await readdir(root, { withFileTypes: true });
+                if (ctx.abortSignal?.aborted)
+                    return cancelled();
+                entries.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()) || a.name.localeCompare(b.name));
+                const lines = [];
+                const paths = [];
+                let bytes = 0;
+                let byteLimitReached = false;
+                for (const entry of entries) {
+                    if (ctx.abortSignal?.aborted)
+                        return cancelled();
+                    if (lines.length >= limit)
+                        break;
+                    // Quote control characters so one entry always occupies one output line.
+                    const name = /[\u0000-\u001f\u007f]/.test(entry.name) ? JSON.stringify(entry.name) : entry.name;
+                    const suffix = entry.isDirectory() ? "/" : entry.isSymbolicLink() ? "@" : "";
+                    const line = name + suffix;
+                    const size = Buffer.byteLength(line, "utf8") + (lines.length ? 1 : 0);
+                    if (bytes + size > MAX_BYTES) {
+                        byteLimitReached = true;
+                        break;
+                    }
+                    lines.push(line);
+                    paths.push(resolve(root, entry.name) + (entry.isDirectory() ? "/" : ""));
+                    bytes += size;
+                }
+                const truncated = lines.length < entries.length;
+                const notice = !truncated ? "" : byteLimitReached
+                    ? `\n\n[Output truncated at 50 KiB: showing ${lines.length} of ${entries.length} entries. Use bash with ls/find to filter or page the listing.]`
+                    : `\n\n[Output truncated: showing ${lines.length} of ${entries.length} entries. Increase limit to see more.]`;
+                return {
+                    content: (entries.length === 0 ? "(empty directory)" : lines.join("\n")) + notice,
+                    status: truncated ? "partial" : "success",
+                    metadata: { kind: "search", path: root, matches: lines.length, totalEntries: entries.length, truncated, paths },
+                };
+            }
+            catch (error) {
+                if (ctx.abortSignal?.aborted)
+                    return cancelled();
+                return {
+                    content: `Error: Cannot list directory: ${root} (${error instanceof Error ? error.message : String(error)})`,
+                    isError: true,
+                    status: "command_error",
+                };
+            }
+        },
+    };
+}

package/dist/tools/path-utils.d.ts

@@ -1,2 +1,8 @@
 export declare function expandHomePath(value: unknown): string;
 export declare function resolveToolPath(cwd: string, value: unknown, fallback?: string): string;
+/**
+ * Where a path really leads once symlinks are followed — including links in
+ * its parent directories and dangling links (writing through a dangling link
+ * creates its target). Parts that do not exist yet are kept as written.
+ */
+export declare function resolveThroughLinks(path: string): string;