apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/tools/path-utils.js

@@ -1,7 +1,209 @@
-import { accessSync, constants } from "node:fs";
+import { accessSync, closeSync, constants, existsSync, fstatSync, ftruncateSync, mkdirSync, openSync, readSync, realpathSync, statSync, writeSync, } from "node:fs";
 import { access } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, parse, sep } from "node:path";
 import { normalizePath, resolvePath } from "../../utils/paths.js";
 const NARROW_NO_BREAK_SPACE = "\u202F";
+export function preparePathOperation(filePath, cwd) {
+    const canonicalPath = resolveToCwd(filePath, cwd);
+    if (!isAbsolute(canonicalPath))
+        throw new Error("Canonical path must be absolute");
+    try {
+        const stats = statSync(canonicalPath);
+        return {
+            kind: "path-existing",
+            path: { kind: "canonical-path", value: canonicalPath },
+            identity: { device: stats.dev, inode: stats.ino },
+        };
+    }
+    catch {
+        return { kind: "path-new", path: { kind: "canonical-path", value: canonicalPath } };
+    }
+}
+/**
+ * Read the authorized target through a no-follow final-component open, verifying
+ * the descriptor identity captured at authorization before any byte is returned.
+ * A replaced alias or an injected symlink never matches and the read aborts.
+ */
+export function readPreparedPath(operation, maxBytes) {
+    if (operation.kind !== "path-existing") {
+        throw new PreparedTargetChangedError("Authorized read target did not exist when permission was checked");
+    }
+    return withTargetDirectory(operation, { createMissingDirectories: false }, (parent, name) => {
+        let fd;
+        try {
+            fd = openUnder(parent, name, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            throw new PreparedTargetChangedError("Authorized read target changed before execution", { cause: error });
+        }
+        try {
+            const stats = fstatSync(fd);
+            if (stats.dev !== operation.identity.device || stats.ino !== operation.identity.inode) {
+                throw new PreparedTargetChangedError("Authorized read target changed before execution");
+            }
+            const length = maxBytes === undefined ? stats.size : Math.min(stats.size, maxBytes);
+            const buffer = Buffer.alloc(length);
+            let offset = 0;
+            while (offset < buffer.length) {
+                const read = readSync(fd, buffer, offset, buffer.length - offset, null);
+                if (read === 0)
+                    break;
+                offset += read;
+            }
+            return offset === buffer.length ? buffer : buffer.subarray(0, offset);
+        }
+        finally {
+            closeSync(fd);
+        }
+    });
+}
+/** The authorized target changed between permission evaluation and execution. */
+export class PreparedTargetChangedError extends Error {
+}
+const PROC_FD = "/proc/self/fd";
+let procFdAvailable;
+/** /proc lets an already-open directory fd act as the parent of the next open, so a swapped intermediate directory cannot be traversed. */
+function useProcFd() {
+    if (procFdAvailable === undefined) {
+        try {
+            procFdAvailable = existsSync(`${PROC_FD}/self`);
+        }
+        catch {
+            procFdAvailable = false;
+        }
+    }
+    return procFdAvailable;
+}
+function openUnder(parent, name, flags, mode) {
+    if (useProcFd())
+        return openSync(`${PROC_FD}/${parent.fd}/${name}`, flags, mode);
+    return openSync(join(parent.path, name), flags, mode);
+}
+function mkdirUnder(parent, name) {
+    if (useProcFd())
+        mkdirSync(`${PROC_FD}/${parent.fd}/${name}`);
+    else
+        mkdirSync(join(parent.path, name));
+}
+function openChildDirectory(parent, name) {
+    const flags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+    const fd = openUnder(parent, name, flags);
+    closeSync(parent.fd);
+    return { fd, path: join(parent.path, name) };
+}
+function writeAll(fd, content) {
+    const buffer = typeof content === "string" ? Buffer.from(content, "utf-8") : content;
+    let written = 0;
+    while (written < buffer.length) {
+        written += writeSync(fd, buffer, written, buffer.length - written);
+    }
+}
+function isMissingEntryError(error) {
+    return (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT");
+}
+/**
+ * Walk every directory component of the authorized path no-follow, holding one
+ * directory fd across the walk, then run the caller's final-component step against
+ * that walked parent. Any intermediate that is not a real directory — a swapped
+ * symlink, a removed component — aborts before the target is touched.
+ */
+function withTargetDirectory(operation, options, run) {
+    const root = parse(operation.path.value).root;
+    const components = operation.path.value
+        .slice(root.length)
+        .split(sep)
+        .filter((component) => component.length > 0);
+    const name = components[components.length - 1];
+    if (name === undefined)
+        throw new PreparedTargetChangedError("Authorized path has no final component");
+    let parent = { fd: openSync(root, constants.O_RDONLY | constants.O_DIRECTORY), path: root };
+    const closeParent = () => {
+        try {
+            closeSync(parent.fd);
+        }
+        catch { }
+    };
+    for (const component of components.slice(0, -1)) {
+        try {
+            parent = openChildDirectory(parent, component);
+        }
+        catch (error) {
+            if (options.createMissingDirectories && isMissingEntryError(error)) {
+                try {
+                    mkdirUnder(parent, component);
+                    parent = openChildDirectory(parent, component);
+                    continue;
+                }
+                catch (mkdirError) {
+                    closeParent();
+                    throw new PreparedTargetChangedError(`Authorized write parent "${component}" changed before execution`, {
+                        cause: mkdirError,
+                    });
+                }
+            }
+            closeParent();
+            throw new PreparedTargetChangedError(`Authorized path component "${component}" changed before execution`, {
+                cause: error,
+            });
+        }
+    }
+    try {
+        return run(parent, name);
+    }
+    finally {
+        closeParent();
+    }
+}
+/**
+ * Execute an authorized write against the prepared target.
+ *
+ * - `path-existing`: the final component is opened `O_NOFOLLOW`, its descriptor
+ *   identity is compared with the identity captured at authorization, and only
+ *   then is the file truncated and written through that descriptor. A swapped
+ *   alias, an injected symlink, or a redirected parent never matches and the
+ *   write aborts before any byte changes.
+ * - `path-new`: missing parents are created no-follow under the walked directory
+ *   descriptor, and the file is created `O_CREAT | O_EXCL | O_NOFOLLOW`, so a
+ *   replaced parent or a pre-placed symlink is never followed.
+ */
+export function writePreparedPath(operation, content) {
+    withTargetDirectory(operation, { createMissingDirectories: operation.kind === "path-new" }, (parent, name) => {
+        if (operation.kind === "path-existing") {
+            let fd;
+            try {
+                fd = openUnder(parent, name, constants.O_WRONLY | constants.O_NOFOLLOW);
+            }
+            catch (error) {
+                throw new PreparedTargetChangedError("Authorized write target changed before execution", { cause: error });
+            }
+            try {
+                const stats = fstatSync(fd);
+                if (stats.dev !== operation.identity.device || stats.ino !== operation.identity.inode) {
+                    throw new PreparedTargetChangedError("Authorized write target changed before execution");
+                }
+                ftruncateSync(fd, 0);
+                writeAll(fd, content);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return;
+        }
+        let fd;
+        try {
+            fd = openUnder(parent, name, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        }
+        catch (error) {
+            throw new PreparedTargetChangedError("Authorized new-file target changed before execution", { cause: error });
+        }
+        try {
+            writeAll(fd, content);
+        }
+        finally {
+            closeSync(fd);
+        }
+    });
+}
 function tryMacOSScreenshotPath(filePath) {
     return filePath.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);
 }
@@ -36,11 +238,26 @@ export function expandPath(filePath) {
     return normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
 }
 /**
- * Resolve a path relative to the given cwd.
- * Handles ~ expansion and absolute paths.
+ * Resolve a path relative to the given cwd, handling ~ expansion and absolute
+ * paths. The result is the single target used by both permission matching and
+ * filesystem execution.
  */
 export function resolveToCwd(filePath, cwd) {
-    return resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+    const requested = resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+    try {
+        return realpathSync(requested);
+    }
+    catch {
+        try {
+            return joinCanonicalParent(requested);
+        }
+        catch {
+            return requested;
+        }
+    }
+}
+function joinCanonicalParent(requested) {
+    return join(realpathSync(dirname(requested)), basename(requested));
 }
 export function resolveReadPath(filePath, cwd) {
     const resolved = resolveToCwd(filePath, cwd);

package/dist/core/tools/path-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../../src/core/tools/path-utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { accessSync, constants } from \"node:fs\";\nimport { access } from \"node:fs/promises\";\nimport { normalizePath, resolvePath } from \"../../utils/paths.ts\";\n\nconst NARROW_NO_BREAK_SPACE = \"\\u202F\";\n\nfunction tryMacOSScreenshotPath(filePath: string): string {\n\treturn filePath.replace(/ (AM|PM)\\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);\n}\n\nfunction tryNFDVariant(filePath: string): string {\n\t// macOS stores filenames in NFD (decomposed) form, try converting user input to NFD\n\treturn filePath.normalize(\"NFD\");\n}\n\nfunction tryCurlyQuoteVariant(filePath: string): string {\n\t// macOS uses U+2019 (right single quotation mark) in screenshot names like \"Capture d'écran\"\n\t// Users typically type U+0027 (straight apostrophe)\n\treturn filePath.replace(/'/g, \"\\u2019\");\n}\n\nfunction fileExists(filePath: string): boolean {\n\ttry {\n\t\taccessSync(filePath, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport async function pathExists(filePath: string): Promise<boolean> {\n\ttry {\n\t\tawait access(filePath, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport function expandPath(filePath: string): string {\n\treturn normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });\n}\n\n/**\n * Resolve a path relative to the given cwd.\n * Handles ~ expansion and absolute paths.\n */\nexport function resolveToCwd(filePath: string, cwd: string): string {\n\treturn resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });\n}\n\nexport function resolveReadPath(filePath: string, cwd: string): string {\n\tconst resolved = resolveToCwd(filePath, cwd);\n\n\tif (fileExists(resolved)) {\n\t\treturn resolved;\n\t}\n\n\t// Try macOS AM/PM variant (narrow no-break space before AM/PM)\n\tconst amPmVariant = tryMacOSScreenshotPath(resolved);\n\tif (amPmVariant !== resolved && fileExists(amPmVariant)) {\n\t\treturn amPmVariant;\n\t}\n\n\t// Try NFD variant (macOS stores filenames in NFD form)\n\tconst nfdVariant = tryNFDVariant(resolved);\n\tif (nfdVariant !== resolved && fileExists(nfdVariant)) {\n\t\treturn nfdVariant;\n\t}\n\n\t// Try curly quote variant (macOS uses U+2019 in screenshot names)\n\tconst curlyVariant = tryCurlyQuoteVariant(resolved);\n\tif (curlyVariant !== resolved && fileExists(curlyVariant)) {\n\t\treturn curlyVariant;\n\t}\n\n\t// Try combined NFD + curly quote (for French macOS screenshots like \"Capture d'écran\")\n\tconst nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);\n\tif (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {\n\t\treturn nfdCurlyVariant;\n\t}\n\n\treturn resolved;\n}\n\nexport async function resolveReadPathAsync(filePath: string, cwd: string): Promise<string> {\n\tconst resolved = resolveToCwd(filePath, cwd);\n\n\tif (await pathExists(resolved)) {\n\t\treturn resolved;\n\t}\n\n\t// Try macOS AM/PM variant (narrow no-break space before AM/PM)\n\tconst amPmVariant = tryMacOSScreenshotPath(resolved);\n\tif (amPmVariant !== resolved && (await pathExists(amPmVariant))) {\n\t\treturn amPmVariant;\n\t}\n\n\t// Try NFD variant (macOS stores filenames in NFD form)\n\tconst nfdVariant = tryNFDVariant(resolved);\n\tif (nfdVariant !== resolved && (await pathExists(nfdVariant))) {\n\t\treturn nfdVariant;\n\t}\n\n\t// Try curly quote variant (macOS uses U+2019 in screenshot names)\n\tconst curlyVariant = tryCurlyQuoteVariant(resolved);\n\tif (curlyVariant !== resolved && (await pathExists(curlyVariant))) {\n\t\treturn curlyVariant;\n\t}\n\n\t// Try combined NFD + curly quote (for French macOS screenshots like \"Capture d'écran\")\n\tconst nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);\n\tif (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant))) {\n\t\treturn nfdCurlyVariant;\n\t}\n\n\treturn resolved;\n}\n"]}
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../../src/core/tools/path-utils.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\taccessSync,\n\tcloseSync,\n\tconstants,\n\texistsSync,\n\tfstatSync,\n\tftruncateSync,\n\tmkdirSync,\n\topenSync,\n\treadSync,\n\trealpathSync,\n\tstatSync,\n\twriteSync,\n} from \"node:fs\";\nimport { access } from \"node:fs/promises\";\nimport { basename, dirname, isAbsolute, join, parse, sep } from \"node:path\";\nimport { normalizePath, resolvePath } from \"../../utils/paths.ts\";\nimport type { PreparedPathOperation } from \"../permissions/operations.ts\";\n\nconst NARROW_NO_BREAK_SPACE = \"\\u202F\";\n\nexport function preparePathOperation(filePath: string, cwd: string): PreparedPathOperation {\n\tconst canonicalPath = resolveToCwd(filePath, cwd);\n\tif (!isAbsolute(canonicalPath)) throw new Error(\"Canonical path must be absolute\");\n\ttry {\n\t\tconst stats = statSync(canonicalPath);\n\t\treturn {\n\t\t\tkind: \"path-existing\",\n\t\t\tpath: { kind: \"canonical-path\", value: canonicalPath },\n\t\t\tidentity: { device: stats.dev, inode: stats.ino },\n\t\t};\n\t} catch {\n\t\treturn { kind: \"path-new\", path: { kind: \"canonical-path\", value: canonicalPath } };\n\t}\n}\n\n/**\n * Read the authorized target through a no-follow final-component open, verifying\n * the descriptor identity captured at authorization before any byte is returned.\n * A replaced alias or an injected symlink never matches and the read aborts.\n */\nexport function readPreparedPath(operation: PreparedPathOperation, maxBytes?: number): Buffer {\n\tif (operation.kind !== \"path-existing\") {\n\t\tthrow new PreparedTargetChangedError(\"Authorized read target did not exist when permission was checked\");\n\t}\n\treturn withTargetDirectory(operation, { createMissingDirectories: false }, (parent, name) => {\n\t\tlet fd: number;\n\t\ttry {\n\t\t\tfd = openUnder(parent, name, constants.O_RDONLY | constants.O_NOFOLLOW);\n\t\t} catch (error) {\n\t\t\tthrow new PreparedTargetChangedError(\"Authorized read target changed before execution\", { cause: error });\n\t\t}\n\t\ttry {\n\t\t\tconst stats = fstatSync(fd);\n\t\t\tif (stats.dev !== operation.identity.device || stats.ino !== operation.identity.inode) {\n\t\t\t\tthrow new PreparedTargetChangedError(\"Authorized read target changed before execution\");\n\t\t\t}\n\t\t\tconst length = maxBytes === undefined ? stats.size : Math.min(stats.size, maxBytes);\n\t\t\tconst buffer = Buffer.alloc(length);\n\t\t\tlet offset = 0;\n\t\t\twhile (offset < buffer.length) {\n\t\t\t\tconst read = readSync(fd, buffer, offset, buffer.length - offset, null);\n\t\t\t\tif (read === 0) break;\n\t\t\t\toffset += read;\n\t\t\t}\n\t\t\treturn offset === buffer.length ? buffer : buffer.subarray(0, offset);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t});\n}\n\n/** The authorized target changed between permission evaluation and execution. */\nexport class PreparedTargetChangedError extends Error {}\n\nconst PROC_FD = \"/proc/self/fd\";\nlet procFdAvailable: boolean | undefined;\n\n/** /proc lets an already-open directory fd act as the parent of the next open, so a swapped intermediate directory cannot be traversed. */\nfunction useProcFd(): boolean {\n\tif (procFdAvailable === undefined) {\n\t\ttry {\n\t\t\tprocFdAvailable = existsSync(`${PROC_FD}/self`);\n\t\t} catch {\n\t\t\tprocFdAvailable = false;\n\t\t}\n\t}\n\treturn procFdAvailable;\n}\n\ninterface OpenDirectory {\n\tfd: number;\n\t/** Fallback parent path for platforms without /proc/self/fd. */\n\tpath: string;\n}\n\nfunction openUnder(parent: OpenDirectory, name: string, flags: number, mode?: number): number {\n\tif (useProcFd()) return openSync(`${PROC_FD}/${parent.fd}/${name}`, flags, mode);\n\treturn openSync(join(parent.path, name), flags, mode);\n}\n\nfunction mkdirUnder(parent: OpenDirectory, name: string): void {\n\tif (useProcFd()) mkdirSync(`${PROC_FD}/${parent.fd}/${name}`);\n\telse mkdirSync(join(parent.path, name));\n}\n\nfunction openChildDirectory(parent: OpenDirectory, name: string): OpenDirectory {\n\tconst flags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;\n\tconst fd = openUnder(parent, name, flags);\n\tcloseSync(parent.fd);\n\treturn { fd, path: join(parent.path, name) };\n}\n\nfunction writeAll(fd: number, content: string | Buffer): void {\n\tconst buffer = typeof content === \"string\" ? Buffer.from(content, \"utf-8\") : content;\n\tlet written = 0;\n\twhile (written < buffer.length) {\n\t\twritten += writeSync(fd, buffer, written, buffer.length - written);\n\t}\n}\n\nfunction isMissingEntryError(error: unknown): boolean {\n\treturn (\n\t\ttypeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: unknown }).code === \"ENOENT\"\n\t);\n}\n\n/**\n * Walk every directory component of the authorized path no-follow, holding one\n * directory fd across the walk, then run the caller's final-component step against\n * that walked parent. Any intermediate that is not a real directory — a swapped\n * symlink, a removed component — aborts before the target is touched.\n */\nfunction withTargetDirectory<T>(\n\toperation: PreparedPathOperation,\n\toptions: { createMissingDirectories: boolean },\n\trun: (parent: OpenDirectory, name: string) => T,\n): T {\n\tconst root = parse(operation.path.value).root;\n\tconst components = operation.path.value\n\t\t.slice(root.length)\n\t\t.split(sep)\n\t\t.filter((component) => component.length > 0);\n\tconst name = components[components.length - 1];\n\tif (name === undefined) throw new PreparedTargetChangedError(\"Authorized path has no final component\");\n\tlet parent: OpenDirectory = { fd: openSync(root, constants.O_RDONLY | constants.O_DIRECTORY), path: root };\n\tconst closeParent = (): void => {\n\t\ttry {\n\t\t\tcloseSync(parent.fd);\n\t\t} catch {}\n\t};\n\tfor (const component of components.slice(0, -1)) {\n\t\ttry {\n\t\t\tparent = openChildDirectory(parent, component);\n\t\t} catch (error) {\n\t\t\tif (options.createMissingDirectories && isMissingEntryError(error)) {\n\t\t\t\ttry {\n\t\t\t\t\tmkdirUnder(parent, component);\n\t\t\t\t\tparent = openChildDirectory(parent, component);\n\t\t\t\t\tcontinue;\n\t\t\t\t} catch (mkdirError) {\n\t\t\t\t\tcloseParent();\n\t\t\t\t\tthrow new PreparedTargetChangedError(`Authorized write parent \"${component}\" changed before execution`, {\n\t\t\t\t\t\tcause: mkdirError,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t\tcloseParent();\n\t\t\tthrow new PreparedTargetChangedError(`Authorized path component \"${component}\" changed before execution`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\t}\n\ttry {\n\t\treturn run(parent, name);\n\t} finally {\n\t\tcloseParent();\n\t}\n}\n\n/**\n * Execute an authorized write against the prepared target.\n *\n * - `path-existing`: the final component is opened `O_NOFOLLOW`, its descriptor\n *   identity is compared with the identity captured at authorization, and only\n *   then is the file truncated and written through that descriptor. A swapped\n *   alias, an injected symlink, or a redirected parent never matches and the\n *   write aborts before any byte changes.\n * - `path-new`: missing parents are created no-follow under the walked directory\n *   descriptor, and the file is created `O_CREAT | O_EXCL | O_NOFOLLOW`, so a\n *   replaced parent or a pre-placed symlink is never followed.\n */\nexport function writePreparedPath(operation: PreparedPathOperation, content: string | Buffer): void {\n\twithTargetDirectory(operation, { createMissingDirectories: operation.kind === \"path-new\" }, (parent, name) => {\n\t\tif (operation.kind === \"path-existing\") {\n\t\t\tlet fd: number;\n\t\t\ttry {\n\t\t\t\tfd = openUnder(parent, name, constants.O_WRONLY | constants.O_NOFOLLOW);\n\t\t\t} catch (error) {\n\t\t\t\tthrow new PreparedTargetChangedError(\"Authorized write target changed before execution\", { cause: error });\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tconst stats = fstatSync(fd);\n\t\t\t\tif (stats.dev !== operation.identity.device || stats.ino !== operation.identity.inode) {\n\t\t\t\t\tthrow new PreparedTargetChangedError(\"Authorized write target changed before execution\");\n\t\t\t\t}\n\t\t\t\tftruncateSync(fd, 0);\n\t\t\t\twriteAll(fd, content);\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\t\tlet fd: number;\n\t\ttry {\n\t\t\tfd = openUnder(\n\t\t\t\tparent,\n\t\t\t\tname,\n\t\t\t\tconstants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,\n\t\t\t\t0o600,\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tthrow new PreparedTargetChangedError(\"Authorized new-file target changed before execution\", { cause: error });\n\t\t}\n\t\ttry {\n\t\t\twriteAll(fd, content);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t});\n}\n\nfunction tryMacOSScreenshotPath(filePath: string): string {\n\treturn filePath.replace(/ (AM|PM)\\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);\n}\n\nfunction tryNFDVariant(filePath: string): string {\n\t// macOS stores filenames in NFD (decomposed) form, try converting user input to NFD\n\treturn filePath.normalize(\"NFD\");\n}\n\nfunction tryCurlyQuoteVariant(filePath: string): string {\n\t// macOS uses U+2019 (right single quotation mark) in screenshot names like \"Capture d'écran\"\n\t// Users typically type U+0027 (straight apostrophe)\n\treturn filePath.replace(/'/g, \"\\u2019\");\n}\n\nfunction fileExists(filePath: string): boolean {\n\ttry {\n\t\taccessSync(filePath, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport async function pathExists(filePath: string): Promise<boolean> {\n\ttry {\n\t\tawait access(filePath, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport function expandPath(filePath: string): string {\n\treturn normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });\n}\n\n/**\n * Resolve a path relative to the given cwd, handling ~ expansion and absolute\n * paths. The result is the single target used by both permission matching and\n * filesystem execution.\n */\nexport function resolveToCwd(filePath: string, cwd: string): string {\n\tconst requested = resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });\n\ttry {\n\t\treturn realpathSync(requested);\n\t} catch {\n\t\ttry {\n\t\t\treturn joinCanonicalParent(requested);\n\t\t} catch {\n\t\t\treturn requested;\n\t\t}\n\t}\n}\n\nfunction joinCanonicalParent(requested: string): string {\n\treturn join(realpathSync(dirname(requested)), basename(requested));\n}\n\nexport function resolveReadPath(filePath: string, cwd: string): string {\n\tconst resolved = resolveToCwd(filePath, cwd);\n\n\tif (fileExists(resolved)) {\n\t\treturn resolved;\n\t}\n\n\t// Try macOS AM/PM variant (narrow no-break space before AM/PM)\n\tconst amPmVariant = tryMacOSScreenshotPath(resolved);\n\tif (amPmVariant !== resolved && fileExists(amPmVariant)) {\n\t\treturn amPmVariant;\n\t}\n\n\t// Try NFD variant (macOS stores filenames in NFD form)\n\tconst nfdVariant = tryNFDVariant(resolved);\n\tif (nfdVariant !== resolved && fileExists(nfdVariant)) {\n\t\treturn nfdVariant;\n\t}\n\n\t// Try curly quote variant (macOS uses U+2019 in screenshot names)\n\tconst curlyVariant = tryCurlyQuoteVariant(resolved);\n\tif (curlyVariant !== resolved && fileExists(curlyVariant)) {\n\t\treturn curlyVariant;\n\t}\n\n\t// Try combined NFD + curly quote (for French macOS screenshots like \"Capture d'écran\")\n\tconst nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);\n\tif (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {\n\t\treturn nfdCurlyVariant;\n\t}\n\n\treturn resolved;\n}\n\nexport async function resolveReadPathAsync(filePath: string, cwd: string): Promise<string> {\n\tconst resolved = resolveToCwd(filePath, cwd);\n\n\tif (await pathExists(resolved)) {\n\t\treturn resolved;\n\t}\n\n\t// Try macOS AM/PM variant (narrow no-break space before AM/PM)\n\tconst amPmVariant = tryMacOSScreenshotPath(resolved);\n\tif (amPmVariant !== resolved && (await pathExists(amPmVariant))) {\n\t\treturn amPmVariant;\n\t}\n\n\t// Try NFD variant (macOS stores filenames in NFD form)\n\tconst nfdVariant = tryNFDVariant(resolved);\n\tif (nfdVariant !== resolved && (await pathExists(nfdVariant))) {\n\t\treturn nfdVariant;\n\t}\n\n\t// Try curly quote variant (macOS uses U+2019 in screenshot names)\n\tconst curlyVariant = tryCurlyQuoteVariant(resolved);\n\tif (curlyVariant !== resolved && (await pathExists(curlyVariant))) {\n\t\treturn curlyVariant;\n\t}\n\n\t// Try combined NFD + curly quote (for French macOS screenshots like \"Capture d'écran\")\n\tconst nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);\n\tif (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant))) {\n\t\treturn nfdCurlyVariant;\n\t}\n\n\treturn resolved;\n}\n"]}

package/dist/core/tools/powershell.d.ts

@@ -0,0 +1,16 @@
+import { type BashOperations, type BashSpawnContext, type BashSpawnHook, type BashToolDetails, type BashToolInput, type BashToolOptions, type createBashTool, createShellToolDefinition } from "./bash.ts";
+export declare const powershellToolSystemPromptContribution: {
+    readonly snippet: "Execute PowerShell commands";
+    readonly guidelines: readonly ["You can inspect PI_* environment variables for current model and session details."];
+};
+export type PowerShellOperations = BashOperations;
+export type PowerShellSpawnContext = BashSpawnContext;
+export type PowerShellSpawnHook = BashSpawnHook;
+export type PowerShellToolDetails = BashToolDetails;
+export type PowerShellToolInput = BashToolInput;
+export interface PowerShellToolOptions extends Pick<BashToolOptions, "operations" | "exposeSessionEnvironment" | "spawnHook"> {
+}
+export declare function createLocalPowerShellOperations(): PowerShellOperations;
+export declare function createPowerShellToolDefinition(cwd: string, options?: PowerShellToolOptions): ReturnType<typeof createShellToolDefinition>;
+export declare function createPowerShellTool(cwd: string, options?: PowerShellToolOptions): ReturnType<typeof createBashTool>;
+//# sourceMappingURL=powershell.d.ts.map

package/dist/core/tools/powershell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"powershell.d.ts","sourceRoot":"","sources":["../../../src/core/tools/powershell.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EAEnB,yBAAyB,EAEzB,MAAM,WAAW,CAAC;AAKnB,eAAO,MAAM,sCAAsC;;;CAGzC,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAClD,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAChD,MAAM,MAAM,qBAAqB,GAAG,eAAe,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAEhD,MAAM,WAAW,qBAChB,SAAQ,IAAI,CAAC,eAAe,EAAE,YAAY,GAAG,0BAA0B,GAAG,WAAW,CAAC;CAAG;AAE1F,wBAAgB,+BAA+B,IAAI,oBAAoB,CAKtE;AAYD,wBAAgB,8BAA8B,CAC7C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,qBAAqB,GAC7B,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAK9C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAQpH","sourcesContent":["import { getPowerShellConfig } from \"../../utils/shell.ts\";\nimport {\n\ttype BashOperations,\n\ttype BashSpawnContext,\n\ttype BashSpawnHook,\n\ttype BashToolDetails,\n\ttype BashToolInput,\n\ttype BashToolOptions,\n\ttype createBashTool,\n\tcreateLocalShellOperations,\n\tcreateShellToolDefinition,\n\ttype ShellToolConfig,\n} from \"./bash.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst UTF8_OUTPUT_PREFIX = \"try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\\n\";\n\nexport const powershellToolSystemPromptContribution = {\n\tsnippet: \"Execute PowerShell commands\",\n\tguidelines: [\"You can inspect PI_* environment variables for current model and session details.\"],\n} as const;\n\nexport type PowerShellOperations = BashOperations;\nexport type PowerShellSpawnContext = BashSpawnContext;\nexport type PowerShellSpawnHook = BashSpawnHook;\nexport type PowerShellToolDetails = BashToolDetails;\nexport type PowerShellToolInput = BashToolInput;\n\nexport interface PowerShellToolOptions\n\textends Pick<BashToolOptions, \"operations\" | \"exposeSessionEnvironment\" | \"spawnHook\"> {}\n\nexport function createLocalPowerShellOperations(): PowerShellOperations {\n\tconst operations = createLocalShellOperations(\"PowerShell\", getPowerShellConfig);\n\treturn {\n\t\texec: (command, cwd, options) => operations.exec(`${UTF8_OUTPUT_PREFIX}${command}`, cwd, options),\n\t};\n}\n\nconst powershellToolConfig: ShellToolConfig = {\n\tname: \"powershell\",\n\tlabel: \"powershell\",\n\tshellName: \"PowerShell\",\n\tprompt: \"PS>\",\n\tpromptSnippet: powershellToolSystemPromptContribution.snippet,\n\tpromptGuidelines: powershellToolSystemPromptContribution.guidelines,\n\ttempFilePrefix: \"apex-code-powershell\",\n};\n\nexport function createPowerShellToolDefinition(\n\tcwd: string,\n\toptions?: PowerShellToolOptions,\n): ReturnType<typeof createShellToolDefinition> {\n\treturn createShellToolDefinition(cwd, powershellToolConfig, {\n\t\t...options,\n\t\toperations: options?.operations ?? createLocalPowerShellOperations(),\n\t});\n}\n\nexport function createPowerShellTool(cwd: string, options?: PowerShellToolOptions): ReturnType<typeof createBashTool> {\n\tconst definition = createPowerShellToolDefinition(cwd, options);\n\tconst tool = wrapToolDefinition(definition);\n\tObject.assign(tool, {\n\t\tpromptSnippet: definition.promptSnippet,\n\t\tpromptGuidelines: definition.promptGuidelines,\n\t});\n\treturn tool;\n}\n"]}

package/dist/core/tools/powershell.js

@@ -0,0 +1,39 @@
+import { getPowerShellConfig } from "../../utils/shell.js";
+import { createLocalShellOperations, createShellToolDefinition, } from "./bash.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+const UTF8_OUTPUT_PREFIX = "try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n";
+export const powershellToolSystemPromptContribution = {
+    snippet: "Execute PowerShell commands",
+    guidelines: ["You can inspect PI_* environment variables for current model and session details."],
+};
+export function createLocalPowerShellOperations() {
+    const operations = createLocalShellOperations("PowerShell", getPowerShellConfig);
+    return {
+        exec: (command, cwd, options) => operations.exec(`${UTF8_OUTPUT_PREFIX}${command}`, cwd, options),
+    };
+}
+const powershellToolConfig = {
+    name: "powershell",
+    label: "powershell",
+    shellName: "PowerShell",
+    prompt: "PS>",
+    promptSnippet: powershellToolSystemPromptContribution.snippet,
+    promptGuidelines: powershellToolSystemPromptContribution.guidelines,
+    tempFilePrefix: "apex-code-powershell",
+};
+export function createPowerShellToolDefinition(cwd, options) {
+    return createShellToolDefinition(cwd, powershellToolConfig, {
+        ...options,
+        operations: options?.operations ?? createLocalPowerShellOperations(),
+    });
+}
+export function createPowerShellTool(cwd, options) {
+    const definition = createPowerShellToolDefinition(cwd, options);
+    const tool = wrapToolDefinition(definition);
+    Object.assign(tool, {
+        promptSnippet: definition.promptSnippet,
+        promptGuidelines: definition.promptGuidelines,
+    });
+    return tool;
+}
+//# sourceMappingURL=powershell.js.map

package/dist/core/tools/powershell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"powershell.js","sourceRoot":"","sources":["../../../src/core/tools/powershell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAQN,0BAA0B,EAC1B,yBAAyB,GAEzB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,kBAAkB,GAAG,2EAA2E,CAAC;AAEvG,MAAM,CAAC,MAAM,sCAAsC,GAAG;IACrD,OAAO,EAAE,6BAA6B;IACtC,UAAU,EAAE,CAAC,mFAAmF,CAAC;CACxF,CAAC;AAWX,MAAM,UAAU,+BAA+B,GAAyB;IACvE,MAAM,UAAU,GAAG,0BAA0B,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;IACjF,OAAO;QACN,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,kBAAkB,GAAG,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC;KACjG,CAAC;AAAA,CACF;AAED,MAAM,oBAAoB,GAAoB;IAC7C,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,YAAY;IACnB,SAAS,EAAE,YAAY;IACvB,MAAM,EAAE,KAAK;IACb,aAAa,EAAE,sCAAsC,CAAC,OAAO;IAC7D,gBAAgB,EAAE,sCAAsC,CAAC,UAAU;IACnE,cAAc,EAAE,sBAAsB;CACtC,CAAC;AAEF,MAAM,UAAU,8BAA8B,CAC7C,GAAW,EACX,OAA+B,EACgB;IAC/C,OAAO,yBAAyB,CAAC,GAAG,EAAE,oBAAoB,EAAE;QAC3D,GAAG,OAAO;QACV,UAAU,EAAE,OAAO,EAAE,UAAU,IAAI,+BAA+B,EAAE;KACpE,CAAC,CAAC;AAAA,CACH;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,OAA+B,EAAqC;IACrH,MAAM,UAAU,GAAG,8BAA8B,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC5C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;QACnB,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;KAC7C,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AAAA,CACZ","sourcesContent":["import { getPowerShellConfig } from \"../../utils/shell.ts\";\nimport {\n\ttype BashOperations,\n\ttype BashSpawnContext,\n\ttype BashSpawnHook,\n\ttype BashToolDetails,\n\ttype BashToolInput,\n\ttype BashToolOptions,\n\ttype createBashTool,\n\tcreateLocalShellOperations,\n\tcreateShellToolDefinition,\n\ttype ShellToolConfig,\n} from \"./bash.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst UTF8_OUTPUT_PREFIX = \"try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\\n\";\n\nexport const powershellToolSystemPromptContribution = {\n\tsnippet: \"Execute PowerShell commands\",\n\tguidelines: [\"You can inspect PI_* environment variables for current model and session details.\"],\n} as const;\n\nexport type PowerShellOperations = BashOperations;\nexport type PowerShellSpawnContext = BashSpawnContext;\nexport type PowerShellSpawnHook = BashSpawnHook;\nexport type PowerShellToolDetails = BashToolDetails;\nexport type PowerShellToolInput = BashToolInput;\n\nexport interface PowerShellToolOptions\n\textends Pick<BashToolOptions, \"operations\" | \"exposeSessionEnvironment\" | \"spawnHook\"> {}\n\nexport function createLocalPowerShellOperations(): PowerShellOperations {\n\tconst operations = createLocalShellOperations(\"PowerShell\", getPowerShellConfig);\n\treturn {\n\t\texec: (command, cwd, options) => operations.exec(`${UTF8_OUTPUT_PREFIX}${command}`, cwd, options),\n\t};\n}\n\nconst powershellToolConfig: ShellToolConfig = {\n\tname: \"powershell\",\n\tlabel: \"powershell\",\n\tshellName: \"PowerShell\",\n\tprompt: \"PS>\",\n\tpromptSnippet: powershellToolSystemPromptContribution.snippet,\n\tpromptGuidelines: powershellToolSystemPromptContribution.guidelines,\n\ttempFilePrefix: \"apex-code-powershell\",\n};\n\nexport function createPowerShellToolDefinition(\n\tcwd: string,\n\toptions?: PowerShellToolOptions,\n): ReturnType<typeof createShellToolDefinition> {\n\treturn createShellToolDefinition(cwd, powershellToolConfig, {\n\t\t...options,\n\t\toperations: options?.operations ?? createLocalPowerShellOperations(),\n\t});\n}\n\nexport function createPowerShellTool(cwd: string, options?: PowerShellToolOptions): ReturnType<typeof createBashTool> {\n\tconst definition = createPowerShellToolDefinition(cwd, options);\n\tconst tool = wrapToolDefinition(definition);\n\tObject.assign(tool, {\n\t\tpromptSnippet: definition.promptSnippet,\n\t\tpromptGuidelines: definition.promptGuidelines,\n\t});\n\treturn tool;\n}\n"]}

package/dist/core/tools/read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/tools/read.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAS5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAKxD,OAAO,EAAoD,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAEtH,QAAA,MAAM,UAAU;;;;EAId,CAAC;AAEH,eAAO,MAAM,gCAAgC;;;CAGnC,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AASD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,qCAAqC;IACrC,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,+CAA+C;IAC/C,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACnF;AAQD,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AA4ID,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,kBAAkB,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAyJpE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG","sourcesContent":["import { basename, dirname, isAbsolute, relative, resolve as resolvePath, sep } from \"node:path\";\nimport type { Api, ImageContent, Model, TextContent } from \"@earendil-works/pi-ai\";\nimport { Text } from \"@earendil-works/pi-tui\";\nimport type { AgentTool } from \"apex-code-agent-core\";\nimport { constants } from \"fs\";\nimport { access as fsAccess, readFile as fsReadFile } from \"fs/promises\";\nimport { type Static, Type } from \"typebox\";\nimport { getReadmePath } from \"../../config.ts\";\nimport { keyHint, keyText } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport { getLanguageFromPath, highlightCode, type Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { processImage } from \"../../utils/image-process.ts\";\nimport { detectSupportedImageMimeTypeFromFile } from \"../../utils/mime.ts\";\nimport { formatPathRelativeToCwdOrAbsolute } from \"../../utils/paths.ts\";\nimport { getExperimentalToolSampling } from \"../experimental.ts\";\nimport type { ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { createPathPermissionSpec } from \"./path-permission.ts\";\nimport { resolveReadPathAsync, resolveToCwd } from \"./path-utils.ts\";\nimport { getTextOutput, renderToolPath, replaceTabs, str } from \"./render-utils.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from \"./truncate.ts\";\n\nconst readSchema = Type.Object({\n\tpath: Type.String({ description: \"Path to the file to read (relative or absolute)\" }),\n\toffset: Type.Optional(Type.Number({ description: \"Line number to start reading from (1-indexed)\" })),\n\tlimit: Type.Optional(Type.Number({ description: \"Maximum number of lines to read\" })),\n});\n\nexport const readToolSystemPromptContribution = {\n\tsnippet: \"Read file contents\",\n\tguidelines: [\"Use read to examine files instead of cat or sed.\"],\n} as const;\n\nexport type ReadToolInput = Static<typeof readSchema>;\n\nexport interface ReadToolDetails {\n\ttruncation?: TruncationResult;\n}\n\ninterface CompactReadClassification {\n\tkind: \"docs\" | \"resource\" | \"skill\";\n\tlabel: string;\n}\n\nconst COMPACT_RESOURCE_FILE_NAMES = new Set([\"AGENTS.override.md\", \"AGENTS.md\", \"AGENTS.MD\", \"CLAUDE.md\", \"CLAUDE.MD\"]);\n\n/**\n * Pluggable operations for the read tool.\n * Override these to delegate file reading to remote systems (for example SSH).\n */\nexport interface ReadOperations {\n\t/** Read file contents as a Buffer */\n\treadFile: (absolutePath: string) => Promise<Buffer>;\n\t/** Check if file is readable (throw if not) */\n\taccess: (absolutePath: string) => Promise<void>;\n\t/** Detect image MIME type, return null or undefined for non-images */\n\tdetectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;\n}\n\nconst defaultReadOperations: ReadOperations = {\n\treadFile: (path) => fsReadFile(path),\n\taccess: (path) => fsAccess(path, constants.R_OK),\n\tdetectImageMimeType: detectSupportedImageMimeTypeFromFile,\n};\n\nexport interface ReadToolOptions {\n\t/** Whether to auto-resize images to 2000x2000 max. Default: true */\n\tautoResizeImages?: boolean;\n\t/** Custom operations for file reading. Default: local filesystem */\n\toperations?: ReadOperations;\n}\n\ntype ReadRenderArgs = { path?: string; file_path?: string; offset?: number; limit?: number };\n\nfunction formatReadLineRange(args: ReadRenderArgs | undefined, theme: Theme): string {\n\tif (args?.offset === undefined && args?.limit === undefined) return \"\";\n\tconst startLine = args.offset ?? 1;\n\tconst endLine = args.limit !== undefined ? startLine + args.limit - 1 : \"\";\n\treturn theme.fg(\"warning\", `:${startLine}${endLine ? `-${endLine}` : \"\"}`);\n}\n\nfunction formatReadCall(args: ReadRenderArgs | undefined, theme: Theme, cwd: string): string {\n\tconst pathDisplay = renderToolPath(str(args?.file_path ?? args?.path), theme, cwd);\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"read\"))} ${pathDisplay}${formatReadLineRange(args, theme)}`;\n}\n\nfunction trimTrailingEmptyLines(lines: string[]): string[] {\n\tlet end = lines.length;\n\twhile (end > 0 && lines[end - 1] === \"\") {\n\t\tend--;\n\t}\n\treturn lines.slice(0, end);\n}\n\nfunction getNonVisionImageNote(model: Model<Api> | undefined): string | undefined {\n\tif (!model || model.input.includes(\"image\")) {\n\t\treturn undefined;\n\t}\n\treturn \"[Current model does not support images. The image will be omitted from this request.]\";\n}\n\nfunction toPosixPath(filePath: string): string {\n\treturn filePath.split(sep).join(\"/\");\n}\n\nfunction getPiDocsClassification(absolutePath: string): CompactReadClassification | undefined {\n\tconst packageRoot = dirname(getReadmePath());\n\tconst relativePath = relative(resolvePath(packageRoot), resolvePath(absolutePath));\n\tif (\n\t\trelativePath === \"\" ||\n\t\trelativePath === \"..\" ||\n\t\trelativePath.startsWith(`..${sep}`) ||\n\t\tisAbsolute(relativePath)\n\t) {\n\t\treturn undefined;\n\t}\n\n\tconst label = toPosixPath(relativePath);\n\tif (label === \"README.md\" || label.startsWith(\"docs/\") || label.startsWith(\"examples/\")) {\n\t\treturn { kind: \"docs\", label };\n\t}\n\treturn undefined;\n}\n\nfunction getCompactReadClassification(\n\targs: ReadRenderArgs | undefined,\n\tcwd: string,\n): CompactReadClassification | undefined {\n\tconst rawPath = str(args?.file_path ?? args?.path);\n\tif (!rawPath) return undefined;\n\n\tconst absolutePath = resolveToCwd(rawPath, cwd);\n\tconst fileName = basename(absolutePath);\n\tif (fileName === \"SKILL.md\") {\n\t\treturn { kind: \"skill\", label: basename(dirname(absolutePath)) || fileName };\n\t}\n\n\tconst docsClassification = getPiDocsClassification(absolutePath);\n\tif (docsClassification) return docsClassification;\n\n\tif (COMPACT_RESOURCE_FILE_NAMES.has(fileName)) {\n\t\treturn { kind: \"resource\", label: formatPathRelativeToCwdOrAbsolute(absolutePath, cwd) };\n\t}\n\n\treturn undefined;\n}\n\nfunction formatCompactReadCall(\n\tclassification: CompactReadClassification,\n\targs: ReadRenderArgs | undefined,\n\ttheme: Theme,\n): string {\n\tconst expandHint = theme.fg(\"dim\", ` (${keyText(\"app.tools.expand\")} to expand)`);\n\tif (classification.kind === \"skill\") {\n\t\treturn (\n\t\t\ttheme.fg(\"customMessageLabel\", `\\x1b[1m[skill]\\x1b[22m `) +\n\t\t\ttheme.fg(\"customMessageText\", classification.label) +\n\t\t\tformatReadLineRange(args, theme) +\n\t\t\texpandHint\n\t\t);\n\t}\n\n\treturn (\n\t\ttheme.fg(\"toolTitle\", theme.bold(`read ${classification.kind}`)) +\n\t\t\" \" +\n\t\ttheme.fg(\"accent\", classification.label) +\n\t\tformatReadLineRange(args, theme) +\n\t\texpandHint\n\t);\n}\n\nfunction formatReadResult(\n\targs: ReadRenderArgs | undefined,\n\tresult: { content: (TextContent | ImageContent)[]; details?: ReadToolDetails },\n\toptions: ToolRenderResultOptions,\n\ttheme: Theme,\n\tshowImages: boolean,\n\t_cwd: string,\n\tisError: boolean,\n): string {\n\tif (!options.expanded && !isError) {\n\t\treturn \"\";\n\t}\n\n\tconst rawPath = str(args?.file_path ?? args?.path);\n\tconst output = getTextOutput(result, showImages);\n\tconst lang = !isError && rawPath ? getLanguageFromPath(rawPath) : undefined;\n\tconst renderedLines = lang ? highlightCode(replaceTabs(output), lang) : output.split(\"\\n\");\n\tconst lines = trimTrailingEmptyLines(renderedLines);\n\tconst maxLines = options.expanded ? lines.length : 10;\n\tconst displayLines = lines.slice(0, maxLines);\n\tconst remaining = lines.length - maxLines;\n\tlet text = `\\n${displayLines.map((line) => (lang ? replaceTabs(line) : theme.fg(\"toolOutput\", replaceTabs(line)))).join(\"\\n\")}`;\n\tif (remaining > 0) {\n\t\ttext += `${theme.fg(\"muted\", `\\n... (${remaining} more lines,`)} ${keyHint(\"app.tools.expand\", \"to expand\")}${theme.fg(\"muted\", \")\")}`;\n\t}\n\n\tconst truncation = result.details?.truncation;\n\tif (truncation?.truncated) {\n\t\tif (truncation.firstLineExceedsLimit) {\n\t\t\ttext += `\\n${theme.fg(\"warning\", `[First line exceeds ${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit]`)}`;\n\t\t} else if (truncation.truncatedBy === \"lines\") {\n\t\t\ttext += `\\n${theme.fg(\"warning\", `[Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${truncation.maxLines ?? DEFAULT_MAX_LINES} line limit)]`)}`;\n\t\t} else {\n\t\t\ttext += `\\n${theme.fg(\"warning\", `[Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)]`)}`;\n\t\t}\n\t}\n\treturn text;\n}\n\nexport function createReadToolDefinition(\n\tcwd: string,\n\toptions?: ReadToolOptions,\n): ApexToolDefinition<typeof readSchema, ReadToolDetails | undefined> {\n\tconst autoResizeImages = options?.autoResizeImages ?? true;\n\tconst ops = options?.operations ?? defaultReadOperations;\n\treturn {\n\t\tname: \"read\",\n\t\tlabel: \"read\",\n\t\tdescription: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,\n\t\tpromptSnippet: readToolSystemPromptContribution.snippet,\n\t\tpromptGuidelines: [...readToolSystemPromptContribution.guidelines],\n\t\tparameters: readSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"fs.read\"]),\n\t\t\tpermission: createPathPermissionSpec({\n\t\t\t\tcwd,\n\t\t\t\tdefaultBehavior: \"allow\",\n\t\t\t\tverb: \"Read\",\n\t\t\t\tgetPath: (params) => params.path,\n\t\t\t}),\n\t\t\tcontext: { resultRecoverable: true, deferSchema: false },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tconstrainedSampling: getExperimentalToolSampling(),\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ path, offset, limit }: { path: string; offset?: number; limit?: number },\n\t\t\tsignal?: AbortSignal,\n\t\t\t_onUpdate?,\n\t\t\tctx?,\n\t\t) {\n\t\t\treturn new Promise<{ content: (TextContent | ImageContent)[]; details: ReadToolDetails | undefined }>(\n\t\t\t\t(resolve, reject) => {\n\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\treject(new Error(\"Operation aborted\"));\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tlet aborted = false;\n\t\t\t\t\tconst onAbort = () => {\n\t\t\t\t\t\taborted = true;\n\t\t\t\t\t\treject(new Error(\"Operation aborted\"));\n\t\t\t\t\t};\n\t\t\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\n\t\t\t\t\t(async () => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tconst absolutePath = await resolveReadPathAsync(path, cwd);\n\t\t\t\t\t\t\tif (aborted) return;\n\t\t\t\t\t\t\t// Check if file exists and is readable.\n\t\t\t\t\t\t\tawait ops.access(absolutePath);\n\t\t\t\t\t\t\tif (aborted) return;\n\t\t\t\t\t\t\tconst mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(absolutePath) : undefined;\n\t\t\t\t\t\t\tlet content: (TextContent | ImageContent)[];\n\t\t\t\t\t\t\tlet details: ReadToolDetails | undefined;\n\t\t\t\t\t\t\tconst nonVisionImageNote = getNonVisionImageNote(ctx?.model);\n\t\t\t\t\t\t\tif (mimeType) {\n\t\t\t\t\t\t\t\t// Read image as binary.\n\t\t\t\t\t\t\t\tconst buffer = await ops.readFile(absolutePath);\n\t\t\t\t\t\t\t\tconst processed = await processImage(buffer, mimeType, { autoResizeImages });\n\t\t\t\t\t\t\t\tif (!processed.ok) {\n\t\t\t\t\t\t\t\t\tlet textNote = `Read image file [${mimeType}]\\n${processed.message}`;\n\t\t\t\t\t\t\t\t\tif (nonVisionImageNote) textNote += `\\n${nonVisionImageNote}`;\n\t\t\t\t\t\t\t\t\tcontent = [{ type: \"text\", text: textNote }];\n\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\tlet textNote = `Read image file [${processed.mimeType}]`;\n\t\t\t\t\t\t\t\t\tif (processed.hints.length > 0) textNote += `\\n${processed.hints.join(\"\\n\")}`;\n\t\t\t\t\t\t\t\t\tif (nonVisionImageNote) textNote += `\\n${nonVisionImageNote}`;\n\t\t\t\t\t\t\t\t\tcontent = [\n\t\t\t\t\t\t\t\t\t\t{ type: \"text\", text: textNote },\n\t\t\t\t\t\t\t\t\t\t{ type: \"image\", data: processed.data, mimeType: processed.mimeType },\n\t\t\t\t\t\t\t\t\t];\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t// Read text content.\n\t\t\t\t\t\t\t\tconst buffer = await ops.readFile(absolutePath);\n\t\t\t\t\t\t\t\tconst textContent = buffer.toString(\"utf-8\");\n\t\t\t\t\t\t\t\tconst allLines = textContent.split(\"\\n\");\n\t\t\t\t\t\t\t\tconst totalFileLines = allLines.length;\n\t\t\t\t\t\t\t\t// Apply offset if specified. Convert from 1-indexed input to 0-indexed array access.\n\t\t\t\t\t\t\t\tconst startLine = offset ? Math.max(0, offset - 1) : 0;\n\t\t\t\t\t\t\t\tconst startLineDisplay = startLine + 1;\n\t\t\t\t\t\t\t\t// Check if offset is out of bounds.\n\t\t\t\t\t\t\t\tif (startLine >= allLines.length) {\n\t\t\t\t\t\t\t\t\tthrow new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tlet selectedContent: string;\n\t\t\t\t\t\t\t\tlet userLimitedLines: number | undefined;\n\t\t\t\t\t\t\t\t// If limit is specified by the user, honor it first. Otherwise truncateHead decides.\n\t\t\t\t\t\t\t\tif (limit !== undefined) {\n\t\t\t\t\t\t\t\t\tconst endLine = Math.min(startLine + limit, allLines.length);\n\t\t\t\t\t\t\t\t\tselectedContent = allLines.slice(startLine, endLine).join(\"\\n\");\n\t\t\t\t\t\t\t\t\tuserLimitedLines = endLine - startLine;\n\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\tselectedContent = allLines.slice(startLine).join(\"\\n\");\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t// Apply truncation, respecting both line and byte limits.\n\t\t\t\t\t\t\t\tconst truncation = truncateHead(selectedContent);\n\t\t\t\t\t\t\t\tlet outputText: string;\n\t\t\t\t\t\t\t\tif (truncation.firstLineExceedsLimit) {\n\t\t\t\t\t\t\t\t\t// First line alone exceeds the byte limit. Point the model at a bash fallback.\n\t\t\t\t\t\t\t\t\tconst firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], \"utf-8\"));\n\t\t\t\t\t\t\t\t\toutputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;\n\t\t\t\t\t\t\t\t\tdetails = { truncation };\n\t\t\t\t\t\t\t\t} else if (truncation.truncated) {\n\t\t\t\t\t\t\t\t\t// Truncation occurred. Build an actionable continuation notice.\n\t\t\t\t\t\t\t\t\tconst endLineDisplay = startLineDisplay + truncation.outputLines - 1;\n\t\t\t\t\t\t\t\t\tconst nextOffset = endLineDisplay + 1;\n\t\t\t\t\t\t\t\t\toutputText = truncation.content;\n\t\t\t\t\t\t\t\t\tif (truncation.truncatedBy === \"lines\") {\n\t\t\t\t\t\t\t\t\t\toutputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;\n\t\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\t\toutputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\tdetails = { truncation };\n\t\t\t\t\t\t\t\t} else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {\n\t\t\t\t\t\t\t\t\t// User-specified limit stopped early, but the file still has more content.\n\t\t\t\t\t\t\t\t\tconst remaining = allLines.length - (startLine + userLimitedLines);\n\t\t\t\t\t\t\t\t\tconst nextOffset = startLine + userLimitedLines + 1;\n\t\t\t\t\t\t\t\t\toutputText = `${truncation.content}\\n\\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;\n\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\t// No truncation and no remaining user-limited content.\n\t\t\t\t\t\t\t\t\toutputText = truncation.content;\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tcontent = [{ type: \"text\", text: outputText }];\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tif (aborted) return;\n\t\t\t\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t\t\t\t\tresolve({ content, details });\n\t\t\t\t\t\t} catch (error: any) {\n\t\t\t\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t\t\t\t\tif (!aborted) reject(error);\n\t\t\t\t\t\t}\n\t\t\t\t\t})();\n\t\t\t\t},\n\t\t\t);\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tconst classification = !context.expanded ? getCompactReadClassification(args, context.cwd) : undefined;\n\t\t\ttext.setText(\n\t\t\t\tclassification\n\t\t\t\t\t? formatCompactReadCall(classification, args, theme)\n\t\t\t\t\t: formatReadCall(args, theme, context.cwd),\n\t\t\t);\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(\n\t\t\t\tformatReadResult(context.args, result, options, theme, context.showImages, context.cwd, context.isError),\n\t\t\t);\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema> {\n\treturn wrapToolDefinition(createReadToolDefinition(cwd, options));\n}\n"]}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/tools/read.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAU5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAKxD,OAAO,EAAoD,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAEtH,QAAA,MAAM,UAAU;;;;EAId,CAAC;AAEH,eAAO,MAAM,gCAAgC;;;CAGnC,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AASD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,qCAAqC;IACrC,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,+CAA+C;IAC/C,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACnF;AAQD,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AA4ID,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,kBAAkB,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAgKpE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG","sourcesContent":["import { basename, dirname, isAbsolute, relative, resolve as resolvePath, sep } from \"node:path\";\nimport type { Api, ImageContent, Model, TextContent } from \"@earendil-works/pi-ai\";\nimport { Text } from \"@earendil-works/pi-tui\";\nimport type { AgentTool } from \"apex-code-agent-core\";\nimport { constants } from \"fs\";\nimport { access as fsAccess, readFile as fsReadFile } from \"fs/promises\";\nimport { type Static, Type } from \"typebox\";\nimport { getReadmePath } from \"../../config.ts\";\nimport { keyHint, keyText } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport { getLanguageFromPath, highlightCode, type Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { processImage } from \"../../utils/image-process.ts\";\nimport { detectSupportedImageMimeType, detectSupportedImageMimeTypeFromFile } from \"../../utils/mime.ts\";\nimport { formatPathRelativeToCwdOrAbsolute } from \"../../utils/paths.ts\";\nimport { getExperimentalToolSampling } from \"../experimental.ts\";\nimport type { ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport { getPreparedPathOperation } from \"../permissions/operations.ts\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { createPathPermissionSpec } from \"./path-permission.ts\";\nimport { readPreparedPath, resolveReadPathAsync, resolveToCwd } from \"./path-utils.ts\";\nimport { getTextOutput, renderToolPath, replaceTabs, str } from \"./render-utils.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from \"./truncate.ts\";\n\nconst readSchema = Type.Object({\n\tpath: Type.String({ description: \"Path to the file to read (relative or absolute)\" }),\n\toffset: Type.Optional(Type.Number({ description: \"Line number to start reading from (1-indexed)\" })),\n\tlimit: Type.Optional(Type.Number({ description: \"Maximum number of lines to read\" })),\n});\n\nexport const readToolSystemPromptContribution = {\n\tsnippet: \"Read file contents\",\n\tguidelines: [\"Use read to examine files instead of cat or sed.\"],\n} as const;\n\nexport type ReadToolInput = Static<typeof readSchema>;\n\nexport interface ReadToolDetails {\n\ttruncation?: TruncationResult;\n}\n\ninterface CompactReadClassification {\n\tkind: \"docs\" | \"resource\" | \"skill\";\n\tlabel: string;\n}\n\nconst COMPACT_RESOURCE_FILE_NAMES = new Set([\"AGENTS.override.md\", \"AGENTS.md\", \"AGENTS.MD\", \"CLAUDE.md\", \"CLAUDE.MD\"]);\n\n/**\n * Pluggable operations for the read tool.\n * Override these to delegate file reading to remote systems (for example SSH).\n */\nexport interface ReadOperations {\n\t/** Read file contents as a Buffer */\n\treadFile: (absolutePath: string) => Promise<Buffer>;\n\t/** Check if file is readable (throw if not) */\n\taccess: (absolutePath: string) => Promise<void>;\n\t/** Detect image MIME type, return null or undefined for non-images */\n\tdetectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;\n}\n\nconst defaultReadOperations: ReadOperations = {\n\treadFile: (path) => fsReadFile(path),\n\taccess: (path) => fsAccess(path, constants.R_OK),\n\tdetectImageMimeType: detectSupportedImageMimeTypeFromFile,\n};\n\nexport interface ReadToolOptions {\n\t/** Whether to auto-resize images to 2000x2000 max. Default: true */\n\tautoResizeImages?: boolean;\n\t/** Custom operations for file reading. Default: local filesystem */\n\toperations?: ReadOperations;\n}\n\ntype ReadRenderArgs = { path?: string; file_path?: string; offset?: number; limit?: number };\n\nfunction formatReadLineRange(args: ReadRenderArgs | undefined, theme: Theme): string {\n\tif (args?.offset === undefined && args?.limit === undefined) return \"\";\n\tconst startLine = args.offset ?? 1;\n\tconst endLine = args.limit !== undefined ? startLine + args.limit - 1 : \"\";\n\treturn theme.fg(\"warning\", `:${startLine}${endLine ? `-${endLine}` : \"\"}`);\n}\n\nfunction formatReadCall(args: ReadRenderArgs | undefined, theme: Theme, cwd: string): string {\n\tconst pathDisplay = renderToolPath(str(args?.file_path ?? args?.path), theme, cwd);\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"read\"))} ${pathDisplay}${formatReadLineRange(args, theme)}`;\n}\n\nfunction trimTrailingEmptyLines(lines: string[]): string[] {\n\tlet end = lines.length;\n\twhile (end > 0 && lines[end - 1] === \"\") {\n\t\tend--;\n\t}\n\treturn lines.slice(0, end);\n}\n\nfunction getNonVisionImageNote(model: Model<Api> | undefined): string | undefined {\n\tif (!model || model.input.includes(\"image\")) {\n\t\treturn undefined;\n\t}\n\treturn \"[Current model does not support images. The image will be omitted from this request.]\";\n}\n\nfunction toPosixPath(filePath: string): string {\n\treturn filePath.split(sep).join(\"/\");\n}\n\nfunction getPiDocsClassification(absolutePath: string): CompactReadClassification | undefined {\n\tconst packageRoot = dirname(getReadmePath());\n\tconst relativePath = relative(resolvePath(packageRoot), resolvePath(absolutePath));\n\tif (\n\t\trelativePath === \"\" ||\n\t\trelativePath === \"..\" ||\n\t\trelativePath.startsWith(`..${sep}`) ||\n\t\tisAbsolute(relativePath)\n\t) {\n\t\treturn undefined;\n\t}\n\n\tconst label = toPosixPath(relativePath);\n\tif (label === \"README.md\" || label.startsWith(\"docs/\") || label.startsWith(\"examples/\")) {\n\t\treturn { kind: \"docs\", label };\n\t}\n\treturn undefined;\n}\n\nfunction getCompactReadClassification(\n\targs: ReadRenderArgs | undefined,\n\tcwd: string,\n): CompactReadClassification | undefined {\n\tconst rawPath = str(args?.file_path ?? args?.path);\n\tif (!rawPath) return undefined;\n\n\tconst absolutePath = resolveToCwd(rawPath, cwd);\n\tconst fileName = basename(absolutePath);\n\tif (fileName === \"SKILL.md\") {\n\t\treturn { kind: \"skill\", label: basename(dirname(absolutePath)) || fileName };\n\t}\n\n\tconst docsClassification = getPiDocsClassification(absolutePath);\n\tif (docsClassification) return docsClassification;\n\n\tif (COMPACT_RESOURCE_FILE_NAMES.has(fileName)) {\n\t\treturn { kind: \"resource\", label: formatPathRelativeToCwdOrAbsolute(absolutePath, cwd) };\n\t}\n\n\treturn undefined;\n}\n\nfunction formatCompactReadCall(\n\tclassification: CompactReadClassification,\n\targs: ReadRenderArgs | undefined,\n\ttheme: Theme,\n): string {\n\tconst expandHint = theme.fg(\"dim\", ` (${keyText(\"app.tools.expand\")} to expand)`);\n\tif (classification.kind === \"skill\") {\n\t\treturn (\n\t\t\ttheme.fg(\"customMessageLabel\", `\\x1b[1m[skill]\\x1b[22m `) +\n\t\t\ttheme.fg(\"customMessageText\", classification.label) +\n\t\t\tformatReadLineRange(args, theme) +\n\t\t\texpandHint\n\t\t);\n\t}\n\n\treturn (\n\t\ttheme.fg(\"toolTitle\", theme.bold(`read ${classification.kind}`)) +\n\t\t\" \" +\n\t\ttheme.fg(\"accent\", classification.label) +\n\t\tformatReadLineRange(args, theme) +\n\t\texpandHint\n\t);\n}\n\nfunction formatReadResult(\n\targs: ReadRenderArgs | undefined,\n\tresult: { content: (TextContent | ImageContent)[]; details?: ReadToolDetails },\n\toptions: ToolRenderResultOptions,\n\ttheme: Theme,\n\tshowImages: boolean,\n\t_cwd: string,\n\tisError: boolean,\n): string {\n\tif (!options.expanded && !isError) {\n\t\treturn \"\";\n\t}\n\n\tconst rawPath = str(args?.file_path ?? args?.path);\n\tconst output = getTextOutput(result, showImages);\n\tconst lang = !isError && rawPath ? getLanguageFromPath(rawPath) : undefined;\n\tconst renderedLines = lang ? highlightCode(replaceTabs(output), lang) : output.split(\"\\n\");\n\tconst lines = trimTrailingEmptyLines(renderedLines);\n\tconst maxLines = options.expanded ? lines.length : 10;\n\tconst displayLines = lines.slice(0, maxLines);\n\tconst remaining = lines.length - maxLines;\n\tlet text = `\\n${displayLines.map((line) => (lang ? replaceTabs(line) : theme.fg(\"toolOutput\", replaceTabs(line)))).join(\"\\n\")}`;\n\tif (remaining > 0) {\n\t\ttext += `${theme.fg(\"muted\", `\\n... (${remaining} more lines,`)} ${keyHint(\"app.tools.expand\", \"to expand\")}${theme.fg(\"muted\", \")\")}`;\n\t}\n\n\tconst truncation = result.details?.truncation;\n\tif (truncation?.truncated) {\n\t\tif (truncation.firstLineExceedsLimit) {\n\t\t\ttext += `\\n${theme.fg(\"warning\", `[First line exceeds ${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit]`)}`;\n\t\t} else if (truncation.truncatedBy === \"lines\") {\n\t\t\ttext += `\\n${theme.fg(\"warning\", `[Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${truncation.maxLines ?? DEFAULT_MAX_LINES} line limit)]`)}`;\n\t\t} else {\n\t\t\ttext += `\\n${theme.fg(\"warning\", `[Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)]`)}`;\n\t\t}\n\t}\n\treturn text;\n}\n\nexport function createReadToolDefinition(\n\tcwd: string,\n\toptions?: ReadToolOptions,\n): ApexToolDefinition<typeof readSchema, ReadToolDetails | undefined> {\n\tconst autoResizeImages = options?.autoResizeImages ?? true;\n\tconst ops = options?.operations ?? defaultReadOperations;\n\treturn {\n\t\tname: \"read\",\n\t\tlabel: \"read\",\n\t\tdescription: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,\n\t\tpromptSnippet: readToolSystemPromptContribution.snippet,\n\t\tpromptGuidelines: [...readToolSystemPromptContribution.guidelines],\n\t\tparameters: readSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"fs.read\"]),\n\t\t\tpermission: createPathPermissionSpec({\n\t\t\t\tcwd,\n\t\t\t\tdefaultBehavior: \"allow\",\n\t\t\t\tverb: \"Read\",\n\t\t\t\tgetPath: (params) => params.path,\n\t\t\t}),\n\t\t\tcontext: { resultRecoverable: true, deferSchema: false },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tconstrainedSampling: getExperimentalToolSampling(),\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\tinput: { path: string; offset?: number; limit?: number },\n\t\t\tsignal?: AbortSignal,\n\t\t\t_onUpdate?,\n\t\t\tctx?,\n\t\t) {\n\t\t\treturn new Promise<{ content: (TextContent | ImageContent)[]; details: ReadToolDetails | undefined }>(\n\t\t\t\t(resolve, reject) => {\n\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\treject(new Error(\"Operation aborted\"));\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tlet aborted = false;\n\t\t\t\t\tconst onAbort = () => {\n\t\t\t\t\t\taborted = true;\n\t\t\t\t\t\treject(new Error(\"Operation aborted\"));\n\t\t\t\t\t};\n\t\t\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\n\t\t\t\t\t(async () => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tconst { path, offset, limit } = input;\n\t\t\t\t\t\t\tconst prepared = getPreparedPathOperation(input);\n\t\t\t\t\t\t\tconst absolutePath = prepared?.path.value ?? (await resolveReadPathAsync(path, cwd));\n\t\t\t\t\t\t\tif (aborted) return;\n\t\t\t\t\t\t\tif (!prepared) await ops.access(absolutePath);\n\t\t\t\t\t\t\tif (aborted) return;\n\t\t\t\t\t\t\tconst buffer = prepared ? await readPreparedPath(prepared) : undefined;\n\t\t\t\t\t\t\t// A gated read detects the MIME type from the already-verified bytes,\n\t\t\t\t\t\t\t// so no secondary unverified pathname open happens after authorization.\n\t\t\t\t\t\t\tconst mimeType = prepared\n\t\t\t\t\t\t\t\t? detectSupportedImageMimeType(buffer!)\n\t\t\t\t\t\t\t\t: ops.detectImageMimeType\n\t\t\t\t\t\t\t\t\t? await ops.detectImageMimeType(absolutePath)\n\t\t\t\t\t\t\t\t\t: undefined;\n\t\t\t\t\t\t\tlet content: (TextContent | ImageContent)[];\n\t\t\t\t\t\t\tlet details: ReadToolDetails | undefined;\n\t\t\t\t\t\t\tconst nonVisionImageNote = getNonVisionImageNote(ctx?.model);\n\t\t\t\t\t\t\tif (mimeType) {\n\t\t\t\t\t\t\t\t// Read image as binary.\n\t\t\t\t\t\t\t\tconst imageBuffer = buffer ?? (await ops.readFile(absolutePath));\n\t\t\t\t\t\t\t\tconst processed = await processImage(imageBuffer, mimeType, { autoResizeImages });\n\t\t\t\t\t\t\t\tif (!processed.ok) {\n\t\t\t\t\t\t\t\t\tlet textNote = `Read image file [${mimeType}]\\n${processed.message}`;\n\t\t\t\t\t\t\t\t\tif (nonVisionImageNote) textNote += `\\n${nonVisionImageNote}`;\n\t\t\t\t\t\t\t\t\tcontent = [{ type: \"text\", text: textNote }];\n\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\tlet textNote = `Read image file [${processed.mimeType}]`;\n\t\t\t\t\t\t\t\t\tif (processed.hints.length > 0) textNote += `\\n${processed.hints.join(\"\\n\")}`;\n\t\t\t\t\t\t\t\t\tif (nonVisionImageNote) textNote += `\\n${nonVisionImageNote}`;\n\t\t\t\t\t\t\t\t\tcontent = [\n\t\t\t\t\t\t\t\t\t\t{ type: \"text\", text: textNote },\n\t\t\t\t\t\t\t\t\t\t{ type: \"image\", data: processed.data, mimeType: processed.mimeType },\n\t\t\t\t\t\t\t\t\t];\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t// Read text content.\n\t\t\t\t\t\t\t\tconst textContent = (buffer ?? (await ops.readFile(absolutePath))).toString(\"utf-8\");\n\t\t\t\t\t\t\t\tconst allLines = textContent.split(\"\\n\");\n\t\t\t\t\t\t\t\tconst totalFileLines = allLines.length;\n\t\t\t\t\t\t\t\t// Apply offset if specified. Convert from 1-indexed input to 0-indexed array access.\n\t\t\t\t\t\t\t\tconst startLine = offset ? Math.max(0, offset - 1) : 0;\n\t\t\t\t\t\t\t\tconst startLineDisplay = startLine + 1;\n\t\t\t\t\t\t\t\t// Check if offset is out of bounds.\n\t\t\t\t\t\t\t\tif (startLine >= allLines.length) {\n\t\t\t\t\t\t\t\t\tthrow new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tlet selectedContent: string;\n\t\t\t\t\t\t\t\tlet userLimitedLines: number | undefined;\n\t\t\t\t\t\t\t\t// If limit is specified by the user, honor it first. Otherwise truncateHead decides.\n\t\t\t\t\t\t\t\tif (limit !== undefined) {\n\t\t\t\t\t\t\t\t\tconst endLine = Math.min(startLine + limit, allLines.length);\n\t\t\t\t\t\t\t\t\tselectedContent = allLines.slice(startLine, endLine).join(\"\\n\");\n\t\t\t\t\t\t\t\t\tuserLimitedLines = endLine - startLine;\n\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\tselectedContent = allLines.slice(startLine).join(\"\\n\");\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t// Apply truncation, respecting both line and byte limits.\n\t\t\t\t\t\t\t\tconst truncation = truncateHead(selectedContent);\n\t\t\t\t\t\t\t\tlet outputText: string;\n\t\t\t\t\t\t\t\tif (truncation.firstLineExceedsLimit) {\n\t\t\t\t\t\t\t\t\t// First line alone exceeds the byte limit. Point the model at a bash fallback.\n\t\t\t\t\t\t\t\t\tconst firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], \"utf-8\"));\n\t\t\t\t\t\t\t\t\toutputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;\n\t\t\t\t\t\t\t\t\tdetails = { truncation };\n\t\t\t\t\t\t\t\t} else if (truncation.truncated) {\n\t\t\t\t\t\t\t\t\t// Truncation occurred. Build an actionable continuation notice.\n\t\t\t\t\t\t\t\t\tconst endLineDisplay = startLineDisplay + truncation.outputLines - 1;\n\t\t\t\t\t\t\t\t\tconst nextOffset = endLineDisplay + 1;\n\t\t\t\t\t\t\t\t\toutputText = truncation.content;\n\t\t\t\t\t\t\t\t\tif (truncation.truncatedBy === \"lines\") {\n\t\t\t\t\t\t\t\t\t\toutputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;\n\t\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\t\toutputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\tdetails = { truncation };\n\t\t\t\t\t\t\t\t} else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {\n\t\t\t\t\t\t\t\t\t// User-specified limit stopped early, but the file still has more content.\n\t\t\t\t\t\t\t\t\tconst remaining = allLines.length - (startLine + userLimitedLines);\n\t\t\t\t\t\t\t\t\tconst nextOffset = startLine + userLimitedLines + 1;\n\t\t\t\t\t\t\t\t\toutputText = `${truncation.content}\\n\\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;\n\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\t// No truncation and no remaining user-limited content.\n\t\t\t\t\t\t\t\t\toutputText = truncation.content;\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tcontent = [{ type: \"text\", text: outputText }];\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tif (aborted) return;\n\t\t\t\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t\t\t\t\tresolve({ content, details });\n\t\t\t\t\t\t} catch (error: any) {\n\t\t\t\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t\t\t\t\tif (!aborted) reject(error);\n\t\t\t\t\t\t}\n\t\t\t\t\t})();\n\t\t\t\t},\n\t\t\t);\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tconst classification = !context.expanded ? getCompactReadClassification(args, context.cwd) : undefined;\n\t\t\ttext.setText(\n\t\t\t\tclassification\n\t\t\t\t\t? formatCompactReadCall(classification, args, theme)\n\t\t\t\t\t: formatReadCall(args, theme, context.cwd),\n\t\t\t);\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(\n\t\t\t\tformatReadResult(context.args, result, options, theme, context.showImages, context.cwd, context.isError),\n\t\t\t);\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema> {\n\treturn wrapToolDefinition(createReadToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/read.js

@@ -7,11 +7,12 @@ import { getReadmePath } from "../../config.js";
 import { keyHint, keyText } from "../../modes/interactive/components/keybinding-hints.js";
 import { getLanguageFromPath, highlightCode } from "../../modes/interactive/theme/theme.js";
 import { processImage } from "../../utils/image-process.js";
-import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
+import { detectSupportedImageMimeType, detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
 import { formatPathRelativeToCwdOrAbsolute } from "../../utils/paths.js";
 import { getExperimentalToolSampling } from "../experimental.js";
+import { getPreparedPathOperation } from "../permissions/operations.js";
 import { createPathPermissionSpec } from "./path-permission.js";
-import { resolveReadPathAsync, resolveToCwd } from "./path-utils.js";
+import { readPreparedPath, resolveReadPathAsync, resolveToCwd } from "./path-utils.js";
 import { getTextOutput, renderToolPath, replaceTabs, str } from "./render-utils.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "./truncate.js";
@@ -155,7 +156,7 @@ export function createReadToolDefinition(cwd, options) {
             evidence: { emits: new Set(), capture: () => [] },
         },
         constrainedSampling: getExperimentalToolSampling(),
-        async execute(_toolCallId, { path, offset, limit }, signal, _onUpdate, ctx) {
+        async execute(_toolCallId, input, signal, _onUpdate, ctx) {
             return new Promise((resolve, reject) => {
                 if (signal?.aborted) {
                     reject(new Error("Operation aborted"));
@@ -169,21 +170,30 @@ export function createReadToolDefinition(cwd, options) {
                 signal?.addEventListener("abort", onAbort, { once: true });
                 (async () => {
                     try {
-                        const absolutePath = await resolveReadPathAsync(path, cwd);
+                        const { path, offset, limit } = input;
+                        const prepared = getPreparedPathOperation(input);
+                        const absolutePath = prepared?.path.value ?? (await resolveReadPathAsync(path, cwd));
                         if (aborted)
                             return;
-                        // Check if file exists and is readable.
-                        await ops.access(absolutePath);
+                        if (!prepared)
+                            await ops.access(absolutePath);
                         if (aborted)
                             return;
-                        const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(absolutePath) : undefined;
+                        const buffer = prepared ? await readPreparedPath(prepared) : undefined;
+                        // A gated read detects the MIME type from the already-verified bytes,
+                        // so no secondary unverified pathname open happens after authorization.
+                        const mimeType = prepared
+                            ? detectSupportedImageMimeType(buffer)
+                            : ops.detectImageMimeType
+                                ? await ops.detectImageMimeType(absolutePath)
+                                : undefined;
                         let content;
                         let details;
                         const nonVisionImageNote = getNonVisionImageNote(ctx?.model);
                         if (mimeType) {
                             // Read image as binary.
-                            const buffer = await ops.readFile(absolutePath);
-                            const processed = await processImage(buffer, mimeType, { autoResizeImages });
+                            const imageBuffer = buffer ?? (await ops.readFile(absolutePath));
+                            const processed = await processImage(imageBuffer, mimeType, { autoResizeImages });
                             if (!processed.ok) {
                                 let textNote = `Read image file [${mimeType}]\n${processed.message}`;
                                 if (nonVisionImageNote)
@@ -204,8 +214,7 @@ export function createReadToolDefinition(cwd, options) {
                         }
                         else {
                             // Read text content.
-                            const buffer = await ops.readFile(absolutePath);
-                            const textContent = buffer.toString("utf-8");
+                            const textContent = (buffer ?? (await ops.readFile(absolutePath))).toString("utf-8");
                             const allLines = textContent.split("\n");
                             const totalFileLines = allLines.length;
                             // Apply offset if specified. Convert from 1-indexed input to 0-indexed array access.