@bastani/atomic 0.9.12 → 0.9.13-alpha.2

package/dist/core/tools/persisted-output-file.js

@@ -0,0 +1,284 @@
+/**
+ * Bounded writer for persisted tool-output files.
+ *
+ * Every temp file a tool spills to disk goes through here so no single file can
+ * exceed {@link MAX_PERSISTED_OUTPUT_BYTES}. Once the cap is reached the writer
+ * stops consuming input and appends {@link PERSISTED_OUTPUT_TRUNCATION_MARKER},
+ * so the file stays readable and its size stays bounded even when the producing
+ * command never stops.
+ */
+import { Buffer } from "node:buffer";
+import { closeSync, createWriteStream, fchmodSync, fstatSync, openSync } from "node:fs";
+import { SESSION_TEMP_FILE_MODE } from "./session-temp-dir.js";
+import { MAX_PERSISTED_OUTPUT_BYTES, PERSISTED_OUTPUT_TRUNCATION_MARKER } from "./tool-limits.js";
+/**
+ * Create a persisted-output file and prove it is owner-only before use.
+ *
+ * `wx` refuses to reuse anything already at the path, so a foreign file is never
+ * truncated or adopted; `fchmod` on the descriptor then removes whatever the
+ * umask took away, and the re-stat confirms it. Any failure throws, and every
+ * caller turns that into "no spill file, no advertised path".
+ */
+function openFileWithEnforcedMode(path) {
+    const fd = openSync(path, "wx", SESSION_TEMP_FILE_MODE);
+    if (process.platform === "win32") {
+        return fd;
+    }
+    try {
+        fchmodSync(fd, SESSION_TEMP_FILE_MODE);
+        const stat = fstatSync(fd);
+        if ((stat.mode & 0o777) !== SESSION_TEMP_FILE_MODE) {
+            throw new Error(`persisted output file ${path} could not be restricted to 0600`);
+        }
+        const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+        if (typeof uid === "number" && stat.uid !== uid) {
+            throw new Error(`persisted output file ${path} is owned by another account`);
+        }
+    }
+    catch (error) {
+        closeSync(fd);
+        throw error;
+    }
+    return fd;
+}
+/** Whether `byte` is a UTF-8 continuation byte (`10xxxxxx`). */
+function isUtf8Continuation(byte) {
+    return byte >= 0x80 && byte <= 0xbf;
+}
+/** Expected sequence length for a valid UTF-8 lead; zero for ASCII or an invalid lead. */
+function utf8SequenceLength(byte) {
+    if (byte >= 0xc2 && byte <= 0xdf)
+        return 2;
+    if (byte >= 0xe0 && byte <= 0xef)
+        return 3;
+    if (byte >= 0xf0 && byte <= 0xf4)
+        return 4;
+    return 0;
+}
+/**
+ * Validate a continuation byte, including UTF-8's strict second-byte ranges.
+ *
+ * Those ranges reject overlong encodings (`E0`, `F0`), UTF-16 surrogates
+ * (`ED`), and code points above U+10FFFF (`F4`).
+ */
+function isValidUtf8SequenceByte(buffer, leadIndex, index) {
+    const byte = buffer[index];
+    if (!isUtf8Continuation(byte))
+        return false;
+    if (index !== leadIndex + 1)
+        return true;
+    const lead = buffer[leadIndex];
+    if (lead === 0xe0)
+        return byte >= 0xa0;
+    if (lead === 0xed)
+        return byte <= 0x9f;
+    if (lead === 0xf0)
+        return byte >= 0x90;
+    if (lead === 0xf4)
+        return byte <= 0x8f;
+    return true;
+}
+/**
+ * Return `end` unless its prefix ends inside a valid UTF-8 sequence.
+ *
+ * At most three bytes before the cut can belong to an incomplete sequence. A
+ * run of raw continuation bytes, an invalid lead (`C0`, `C1`, `F5`-`F7`), or a
+ * sequence with an invalid continuation is binary data and stays untouched.
+ */
+function utf8SafePrefixLength(buffer, end) {
+    const cut = Math.max(0, Math.min(end, buffer.length));
+    if (cut === 0)
+        return 0;
+    let leadIndex = cut - 1;
+    let continuationCount = 0;
+    while (leadIndex >= 0 && continuationCount < 3 && isUtf8Continuation(buffer[leadIndex])) {
+        leadIndex--;
+        continuationCount++;
+    }
+    if (leadIndex < 0)
+        return cut;
+    const sequenceLength = utf8SequenceLength(buffer[leadIndex]);
+    if (sequenceLength === 0 || cut - leadIndex >= sequenceLength)
+        return cut;
+    const availableEnd = Math.min(buffer.length, leadIndex + sequenceLength);
+    for (let index = leadIndex + 1; index < availableEnd; index++) {
+        if (!isValidUtf8SequenceByte(buffer, leadIndex, index))
+            return cut;
+    }
+    return leadIndex;
+}
+/** Trim a buffer to at most `maxBytes` without splitting a valid UTF-8 sequence. */
+export function truncateBufferAtUtf8Boundary(buffer, maxBytes) {
+    if (buffer.length <= maxBytes)
+        return buffer;
+    return buffer.subarray(0, utf8SafePrefixLength(buffer, maxBytes));
+}
+/**
+ * Length of the longest prefix of `buffer` that does not end mid-character.
+ * Invalid UTF-8 remains complete raw binary; only a valid partial tail waits.
+ */
+export function completeUtf8PrefixLength(buffer) {
+    return utf8SafePrefixLength(buffer, buffer.length);
+}
+/**
+ * Cap an in-memory string destined for a persisted-output file.
+ *
+ * Returns the input unchanged when it already fits; otherwise the returned text
+ * is the leading portion plus {@link PERSISTED_OUTPUT_TRUNCATION_MARKER}, and the
+ * whole result stays within `maxBytes`.
+ */
+export function capPersistedText(text, maxBytes = MAX_PERSISTED_OUTPUT_BYTES) {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes) {
+        return text;
+    }
+    const markerBytes = Buffer.byteLength(PERSISTED_OUTPUT_TRUNCATION_MARKER, "utf8");
+    const budget = Math.max(0, maxBytes - markerBytes);
+    const head = truncateBufferAtUtf8Boundary(Buffer.from(text, "utf8"), budget).toString("utf8");
+    return `${head}${PERSISTED_OUTPUT_TRUNCATION_MARKER}`;
+}
+/**
+ * A write stream that refuses to grow past its byte cap.
+ *
+ * Marker space cannot simply be subtracted up front: input that lands *exactly*
+ * on the cap is not truncated and must be preserved whole. So the writer keeps a
+ * short trailing buffer — everything past `maxBytes - markerBytes` — unwritten
+ * until it knows which case it is in. Input that stays within the cap has that
+ * tail flushed on close; input that exceeds it gets the UTF-8-safe prefix plus
+ * the marker, and the file lands at the cap. Flushes are cut at character
+ * boundaries, so the file never ends mid-character.
+ *
+ * Mirrors the subset of `WriteStream` the spill-file call sites use: `write`, a
+ * fire-and-forget `end`, and an awaitable `close`. A stream error is captured by
+ * a listener installed at construction, so a spill file that fails to write can
+ * never surface as an uncaught exception on the fire-and-forget path.
+ */
+export class PersistedOutputFile {
+    constructor(path, options = {}) {
+        this.writtenBytes = 0;
+        this.pending = Buffer.alloc(0);
+        this.capReached = false;
+        this.path = path;
+        this.maxBytes = options.maxBytes ?? MAX_PERSISTED_OUTPUT_BYTES;
+        const markerBytes = Buffer.byteLength(PERSISTED_OUTPUT_TRUNCATION_MARKER, "utf8");
+        this.safeLimit = Math.max(0, this.maxBytes - markerBytes);
+        // Own the descriptor so the mode can be enforced before a single byte is
+        // written and before the path is handed to anyone: `mode` on open is only a
+        // request, which the process umask then narrows — a umask of 0o077 is
+        // harmless, but 0o777 leaves the file at 000 and the advertised path
+        // unreadable. Enforcing after close would be too late to fail closed.
+        const fd = openFileWithEnforcedMode(path);
+        const stream = createWriteStream(path, { fd, autoClose: true });
+        stream.on("error", (error) => {
+            this.failure ??= error;
+        });
+        this.stream = stream;
+    }
+    /** Whether the cap was reached and the marker written. */
+    get truncated() {
+        return this.capReached;
+    }
+    /** The write error this file failed with, if any. */
+    get error() {
+        return this.failure;
+    }
+    /** Total input bytes accepted so far, including the unflushed tail. */
+    get acceptedBytes() {
+        return this.writtenBytes + this.pending.length;
+    }
+    write(chunk) {
+        const stream = this.stream;
+        if (!stream || this.capReached) {
+            return;
+        }
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+        if (buffer.length === 0) {
+            return;
+        }
+        this.pending = this.pending.length === 0 ? buffer : Buffer.concat([this.pending, buffer]);
+        if (this.acceptedBytes > this.maxBytes) {
+            // Past the cap for certain: emit the safe prefix and the marker, then
+            // stop consuming input.
+            this.flushUpTo(stream, this.safeLimit - this.writtenBytes);
+            this.pending = Buffer.alloc(0);
+            this.capReached = true;
+            stream.write(PERSISTED_OUTPUT_TRUNCATION_MARKER);
+            return;
+        }
+        // Still within the cap: write everything except the marker-sized tail,
+        // which is only decidable once the input ends.
+        this.flushUpTo(stream, this.safeLimit - this.writtenBytes);
+    }
+    /**
+     * Write at most `room` pending bytes, never ending mid-character.
+     *
+     * Both cuts matter. Cutting at `room` uses the boundary walk; flushing the
+     * whole buffer still holds back an incomplete trailing sequence, because its
+     * continuation bytes arrive in the *next* chunk — and if the cap intervenes
+     * first, a lead byte already on disk would sit orphaned before the marker.
+     */
+    flushUpTo(stream, room) {
+        if (room <= 0 || this.pending.length === 0) {
+            return;
+        }
+        const head = this.pending.length <= room
+            ? this.pending.subarray(0, completeUtf8PrefixLength(this.pending))
+            : truncateBufferAtUtf8Boundary(this.pending, room);
+        if (head.length === 0) {
+            return;
+        }
+        this.writtenBytes += head.length;
+        this.pending = this.pending.subarray(head.length);
+        stream.write(head);
+    }
+    /** Release the trailing buffer once the input is known to fit within the cap. */
+    flushRemainder(stream) {
+        if (this.capReached || this.pending.length === 0) {
+            return;
+        }
+        const tail = this.pending;
+        this.pending = Buffer.alloc(0);
+        this.writtenBytes += tail.length;
+        stream.write(tail);
+    }
+    /** Close without waiting for the flush to complete. */
+    end() {
+        const stream = this.stream;
+        if (!stream) {
+            return;
+        }
+        this.stream = undefined;
+        this.flushRemainder(stream);
+        stream.end();
+    }
+    /** Close and wait for the flush, rejecting on a write error. */
+    async close() {
+        const stream = this.stream;
+        if (!stream) {
+            if (this.failure) {
+                throw this.failure;
+            }
+            return;
+        }
+        this.stream = undefined;
+        this.flushRemainder(stream);
+        if (this.failure) {
+            // The stream already failed and will not emit `finish`; do not wait for it.
+            stream.destroy();
+            throw this.failure;
+        }
+        await new Promise((resolve, reject) => {
+            const onError = (error) => {
+                stream.off("finish", onFinish);
+                reject(error);
+            };
+            const onFinish = () => {
+                stream.off("error", onError);
+                resolve();
+            };
+            stream.once("error", onError);
+            stream.once("finish", onFinish);
+            stream.end();
+        });
+    }
+}
+//# sourceMappingURL=persisted-output-file.js.map

package/dist/core/tools/persisted-output-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persisted-output-file.js","sourceRoot":"","sources":["../../../src/core/tools/persisted-output-file.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Bounded writer for persisted tool-output files.\n *\n * Every temp file a tool spills to disk goes through here so no single file can\n * exceed {@link MAX_PERSISTED_OUTPUT_BYTES}. Once the cap is reached the writer\n * stops consuming input and appends {@link PERSISTED_OUTPUT_TRUNCATION_MARKER},\n * so the file stays readable and its size stays bounded even when the producing\n * command never stops.\n */\nimport { Buffer } from \"node:buffer\";\nimport { closeSync, createWriteStream, fchmodSync, fstatSync, openSync, type WriteStream } from \"node:fs\";\nimport { SESSION_TEMP_FILE_MODE } from \"./session-temp-dir.ts\";\nimport { MAX_PERSISTED_OUTPUT_BYTES, PERSISTED_OUTPUT_TRUNCATION_MARKER } from \"./tool-limits.js\";\n\n/**\n * Create a persisted-output file and prove it is owner-only before use.\n *\n * `wx` refuses to reuse anything already at the path, so a foreign file is never\n * truncated or adopted; `fchmod` on the descriptor then removes whatever the\n * umask took away, and the re-stat confirms it. Any failure throws, and every\n * caller turns that into \"no spill file, no advertised path\".\n */\nfunction openFileWithEnforcedMode(path: string): number {\n\tconst fd = openSync(path, \"wx\", SESSION_TEMP_FILE_MODE);\n\tif (process.platform === \"win32\") {\n\t\treturn fd;\n\t}\n\ttry {\n\t\tfchmodSync(fd, SESSION_TEMP_FILE_MODE);\n\t\tconst stat = fstatSync(fd);\n\t\tif ((stat.mode & 0o777) !== SESSION_TEMP_FILE_MODE) {\n\t\t\tthrow new Error(`persisted output file ${path} could not be restricted to 0600`);\n\t\t}\n\t\tconst uid = typeof process.getuid === \"function\" ? process.getuid() : undefined;\n\t\tif (typeof uid === \"number\" && stat.uid !== uid) {\n\t\t\tthrow new Error(`persisted output file ${path} is owned by another account`);\n\t\t}\n\t} catch (error) {\n\t\tcloseSync(fd);\n\t\tthrow error;\n\t}\n\treturn fd;\n}\n\n/** Whether `byte` is a UTF-8 continuation byte (`10xxxxxx`). */\nfunction isUtf8Continuation(byte: number): boolean {\n\treturn byte >= 0x80 && byte <= 0xbf;\n}\n\n/** Expected sequence length for a valid UTF-8 lead; zero for ASCII or an invalid lead. */\nfunction utf8SequenceLength(byte: number): number {\n\tif (byte >= 0xc2 && byte <= 0xdf) return 2;\n\tif (byte >= 0xe0 && byte <= 0xef) return 3;\n\tif (byte >= 0xf0 && byte <= 0xf4) return 4;\n\treturn 0;\n}\n\n/**\n * Validate a continuation byte, including UTF-8's strict second-byte ranges.\n *\n * Those ranges reject overlong encodings (`E0`, `F0`), UTF-16 surrogates\n * (`ED`), and code points above U+10FFFF (`F4`).\n */\nfunction isValidUtf8SequenceByte(buffer: Buffer, leadIndex: number, index: number): boolean {\n\tconst byte = buffer[index]!;\n\tif (!isUtf8Continuation(byte)) return false;\n\tif (index !== leadIndex + 1) return true;\n\n\tconst lead = buffer[leadIndex]!;\n\tif (lead === 0xe0) return byte >= 0xa0;\n\tif (lead === 0xed) return byte <= 0x9f;\n\tif (lead === 0xf0) return byte >= 0x90;\n\tif (lead === 0xf4) return byte <= 0x8f;\n\treturn true;\n}\n\n/**\n * Return `end` unless its prefix ends inside a valid UTF-8 sequence.\n *\n * At most three bytes before the cut can belong to an incomplete sequence. A\n * run of raw continuation bytes, an invalid lead (`C0`, `C1`, `F5`-`F7`), or a\n * sequence with an invalid continuation is binary data and stays untouched.\n */\nfunction utf8SafePrefixLength(buffer: Buffer, end: number): number {\n\tconst cut = Math.max(0, Math.min(end, buffer.length));\n\tif (cut === 0) return 0;\n\n\tlet leadIndex = cut - 1;\n\tlet continuationCount = 0;\n\twhile (leadIndex >= 0 && continuationCount < 3 && isUtf8Continuation(buffer[leadIndex]!)) {\n\t\tleadIndex--;\n\t\tcontinuationCount++;\n\t}\n\tif (leadIndex < 0) return cut;\n\n\tconst sequenceLength = utf8SequenceLength(buffer[leadIndex]!);\n\tif (sequenceLength === 0 || cut - leadIndex >= sequenceLength) return cut;\n\n\tconst availableEnd = Math.min(buffer.length, leadIndex + sequenceLength);\n\tfor (let index = leadIndex + 1; index < availableEnd; index++) {\n\t\tif (!isValidUtf8SequenceByte(buffer, leadIndex, index)) return cut;\n\t}\n\treturn leadIndex;\n}\n\n/** Trim a buffer to at most `maxBytes` without splitting a valid UTF-8 sequence. */\nexport function truncateBufferAtUtf8Boundary(buffer: Buffer, maxBytes: number): Buffer {\n\tif (buffer.length <= maxBytes) return buffer;\n\treturn buffer.subarray(0, utf8SafePrefixLength(buffer, maxBytes));\n}\n\n/**\n * Length of the longest prefix of `buffer` that does not end mid-character.\n * Invalid UTF-8 remains complete raw binary; only a valid partial tail waits.\n */\nexport function completeUtf8PrefixLength(buffer: Buffer): number {\n\treturn utf8SafePrefixLength(buffer, buffer.length);\n}\n\n/**\n * Cap an in-memory string destined for a persisted-output file.\n *\n * Returns the input unchanged when it already fits; otherwise the returned text\n * is the leading portion plus {@link PERSISTED_OUTPUT_TRUNCATION_MARKER}, and the\n * whole result stays within `maxBytes`.\n */\nexport function capPersistedText(text: string, maxBytes: number = MAX_PERSISTED_OUTPUT_BYTES): string {\n\tif (Buffer.byteLength(text, \"utf8\") <= maxBytes) {\n\t\treturn text;\n\t}\n\tconst markerBytes = Buffer.byteLength(PERSISTED_OUTPUT_TRUNCATION_MARKER, \"utf8\");\n\tconst budget = Math.max(0, maxBytes - markerBytes);\n\tconst head = truncateBufferAtUtf8Boundary(Buffer.from(text, \"utf8\"), budget).toString(\"utf8\");\n\treturn `${head}${PERSISTED_OUTPUT_TRUNCATION_MARKER}`;\n}\n\nexport interface PersistedOutputFileOptions {\n\t/** Byte cap for this file. Defaults to {@link MAX_PERSISTED_OUTPUT_BYTES}. */\n\tmaxBytes?: number;\n}\n\n/**\n * A write stream that refuses to grow past its byte cap.\n *\n * Marker space cannot simply be subtracted up front: input that lands *exactly*\n * on the cap is not truncated and must be preserved whole. So the writer keeps a\n * short trailing buffer — everything past `maxBytes - markerBytes` — unwritten\n * until it knows which case it is in. Input that stays within the cap has that\n * tail flushed on close; input that exceeds it gets the UTF-8-safe prefix plus\n * the marker, and the file lands at the cap. Flushes are cut at character\n * boundaries, so the file never ends mid-character.\n *\n * Mirrors the subset of `WriteStream` the spill-file call sites use: `write`, a\n * fire-and-forget `end`, and an awaitable `close`. A stream error is captured by\n * a listener installed at construction, so a spill file that fails to write can\n * never surface as an uncaught exception on the fire-and-forget path.\n */\nexport class PersistedOutputFile {\n\treadonly path: string;\n\tprivate stream: WriteStream | undefined;\n\tprivate readonly maxBytes: number;\n\t/** Bytes that may be written before the marker's reserved space is needed. */\n\tprivate readonly safeLimit: number;\n\tprivate writtenBytes = 0;\n\tprivate pending: Buffer = Buffer.alloc(0);\n\tprivate capReached = false;\n\tprivate failure: Error | undefined;\n\n\tconstructor(path: string, options: PersistedOutputFileOptions = {}) {\n\t\tthis.path = path;\n\t\tthis.maxBytes = options.maxBytes ?? MAX_PERSISTED_OUTPUT_BYTES;\n\t\tconst markerBytes = Buffer.byteLength(PERSISTED_OUTPUT_TRUNCATION_MARKER, \"utf8\");\n\t\tthis.safeLimit = Math.max(0, this.maxBytes - markerBytes);\n\t\t// Own the descriptor so the mode can be enforced before a single byte is\n\t\t// written and before the path is handed to anyone: `mode` on open is only a\n\t\t// request, which the process umask then narrows — a umask of 0o077 is\n\t\t// harmless, but 0o777 leaves the file at 000 and the advertised path\n\t\t// unreadable. Enforcing after close would be too late to fail closed.\n\t\tconst fd = openFileWithEnforcedMode(path);\n\t\tconst stream = createWriteStream(path, { fd, autoClose: true });\n\t\tstream.on(\"error\", (error: Error) => {\n\t\t\tthis.failure ??= error;\n\t\t});\n\t\tthis.stream = stream;\n\t}\n\n\t/** Whether the cap was reached and the marker written. */\n\tget truncated(): boolean {\n\t\treturn this.capReached;\n\t}\n\n\t/** The write error this file failed with, if any. */\n\tget error(): Error | undefined {\n\t\treturn this.failure;\n\t}\n\n\t/** Total input bytes accepted so far, including the unflushed tail. */\n\tprivate get acceptedBytes(): number {\n\t\treturn this.writtenBytes + this.pending.length;\n\t}\n\n\twrite(chunk: Buffer | string): void {\n\t\tconst stream = this.stream;\n\t\tif (!stream || this.capReached) {\n\t\t\treturn;\n\t\t}\n\t\tconst buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, \"utf8\");\n\t\tif (buffer.length === 0) {\n\t\t\treturn;\n\t\t}\n\t\tthis.pending = this.pending.length === 0 ? buffer : Buffer.concat([this.pending, buffer]);\n\n\t\tif (this.acceptedBytes > this.maxBytes) {\n\t\t\t// Past the cap for certain: emit the safe prefix and the marker, then\n\t\t\t// stop consuming input.\n\t\t\tthis.flushUpTo(stream, this.safeLimit - this.writtenBytes);\n\t\t\tthis.pending = Buffer.alloc(0);\n\t\t\tthis.capReached = true;\n\t\t\tstream.write(PERSISTED_OUTPUT_TRUNCATION_MARKER);\n\t\t\treturn;\n\t\t}\n\t\t// Still within the cap: write everything except the marker-sized tail,\n\t\t// which is only decidable once the input ends.\n\t\tthis.flushUpTo(stream, this.safeLimit - this.writtenBytes);\n\t}\n\n\t/**\n\t * Write at most `room` pending bytes, never ending mid-character.\n\t *\n\t * Both cuts matter. Cutting at `room` uses the boundary walk; flushing the\n\t * whole buffer still holds back an incomplete trailing sequence, because its\n\t * continuation bytes arrive in the *next* chunk — and if the cap intervenes\n\t * first, a lead byte already on disk would sit orphaned before the marker.\n\t */\n\tprivate flushUpTo(stream: WriteStream, room: number): void {\n\t\tif (room <= 0 || this.pending.length === 0) {\n\t\t\treturn;\n\t\t}\n\t\tconst head =\n\t\t\tthis.pending.length <= room\n\t\t\t\t? this.pending.subarray(0, completeUtf8PrefixLength(this.pending))\n\t\t\t\t: truncateBufferAtUtf8Boundary(this.pending, room);\n\t\tif (head.length === 0) {\n\t\t\treturn;\n\t\t}\n\t\tthis.writtenBytes += head.length;\n\t\tthis.pending = this.pending.subarray(head.length);\n\t\tstream.write(head);\n\t}\n\n\t/** Release the trailing buffer once the input is known to fit within the cap. */\n\tprivate flushRemainder(stream: WriteStream): void {\n\t\tif (this.capReached || this.pending.length === 0) {\n\t\t\treturn;\n\t\t}\n\t\tconst tail = this.pending;\n\t\tthis.pending = Buffer.alloc(0);\n\t\tthis.writtenBytes += tail.length;\n\t\tstream.write(tail);\n\t}\n\n\t/** Close without waiting for the flush to complete. */\n\tend(): void {\n\t\tconst stream = this.stream;\n\t\tif (!stream) {\n\t\t\treturn;\n\t\t}\n\t\tthis.stream = undefined;\n\t\tthis.flushRemainder(stream);\n\t\tstream.end();\n\t}\n\n\t/** Close and wait for the flush, rejecting on a write error. */\n\tasync close(): Promise<void> {\n\t\tconst stream = this.stream;\n\t\tif (!stream) {\n\t\t\tif (this.failure) {\n\t\t\t\tthrow this.failure;\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\t\tthis.stream = undefined;\n\t\tthis.flushRemainder(stream);\n\t\tif (this.failure) {\n\t\t\t// The stream already failed and will not emit `finish`; do not wait for it.\n\t\t\tstream.destroy();\n\t\t\tthrow this.failure;\n\t\t}\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\tconst onError = (error: Error) => {\n\t\t\t\tstream.off(\"finish\", onFinish);\n\t\t\t\treject(error);\n\t\t\t};\n\t\t\tconst onFinish = () => {\n\t\t\t\tstream.off(\"error\", onError);\n\t\t\t\tresolve();\n\t\t\t};\n\t\t\tstream.once(\"error\", onError);\n\t\t\tstream.once(\"finish\", onFinish);\n\t\t\tstream.end();\n\t\t});\n\t}\n}\n"]}

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

@@ -1,11 +1,16 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { type Static, Type } from "typebox";
 import type { ToolDefinition } from "../extensions/types.ts";
+import { type DirectoryTreeEntry } from "./directory-tree.ts";
 import { type HashlineSnapshotStore } from "./hashline.ts";
 import { type TruncationResult } from "./truncate.ts";
 declare const readSchema: Type.TObject<{
     path: Type.TString;
 }>;
+export declare const readToolSystemPromptContribution: Readonly<{
+    readonly snippet: "Read a path selector.";
+    readonly guidelines: readonly ["Use read to inspect file and resource contents; use path selectors for line ranges, raw output, and conflict views."];
+}>;
 export type ReadToolInput = Static<typeof readSchema>;
 export interface OversizedReadDetails {
     blocked: true;
@@ -34,6 +39,11 @@ export interface ReadToolDetails {
 export interface ReadOperations {
     readFile: (absolutePath: string) => Promise<Buffer>;
     access: (absolutePath: string) => Promise<void>;
+    stat?: (absolutePath: string) => Promise<{
+        isFile: boolean;
+        isDirectory: boolean;
+    } | undefined>;
+    listDir?: (absolutePath: string) => Promise<DirectoryTreeEntry[] | undefined>;
     detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
 }
 export interface ReadToolOptions {

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":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAK/D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAO5C,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,wBAAwB,CAAC;AAItF,OAAO,EAGN,KAAK,qBAAqB,EAE1B,MAAM,eAAe,CAAC;AAyBvB,OAAO,EAAoD,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAEtH,QAAA,MAAM,UAAU;;EAQf,CAAC;AACF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;CACtB;AACD,MAAM,WAAW,eAAe;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,IAAI,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,gBAAgB,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAAC;CACF;AAMD,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACnF;AAMD,MAAM,WAAW,eAAe;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACtC;AA4LD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAsjBhE;AACD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/tools/read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAK/D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAO5C,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,wBAAwB,CAAC;AAEtF,OAAO,EAGN,KAAK,kBAAkB,EAEvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAGN,KAAK,qBAAqB,EAE1B,MAAM,eAAe,CAAC;AAyBvB,OAAO,EAAoD,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAEtH,QAAA,MAAM,UAAU;;EAQf,CAAC;AACF,eAAO,MAAM,gCAAgC;sBACnC,uBAAuB;;EAItB,CAAC;AACZ,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;CACtB;AACD,MAAM,WAAW,eAAe;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,IAAI,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,gBAAgB,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAAC;CACF;AAMD,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAChG,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,EAAE,GAAG,SAAS,CAAC,CAAC;IAC9E,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACnF;AAMD,MAAM,WAAW,eAAe;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACtC;AA4LD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CA+jBhE;AACD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}

package/dist/core/tools/read.js

@@ -10,7 +10,7 @@ import { processImage } from "../../utils/image-process.js";
 import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
 import { formatPathRelativeToCwdOrAbsolute } from "../../utils/paths.js";
 import { parseConflictBlocks, registerConflictBlocks } from "./conflict-registry.js";
-import { buildDirectoryTree } from "./directory-tree.js";
+import { buildDirectoryTree, buildDirectoryTreeFromOperations, } from "./directory-tree.js";
 import { isReadableUrlPath } from "./fetch-url.js";
 import { createHashlineSnapshotStore, formatHashlineContent, recordHashlineSnapshot, } from "./hashline.js";
 import { isNotebookPath, readEditableNotebookText } from "./notebook.js";
@@ -27,8 +27,14 @@ const readSchema = Type.Object({
         description: "File, directory, archive member, SQLite selector, internal resource, image, document, or URL to read. Append selectors such as :raw, :conflicts, :N, :A-B, :A+C, or :A-B,C-D to scope output.",
     }),
 }, { additionalProperties: false });
+export const readToolSystemPromptContribution = Object.freeze({
+    snippet: "Read a path selector.",
+    guidelines: Object.freeze([
+        "Use read to inspect file and resource contents; use path selectors for line ranges, raw output, and conflict views.",
+    ]),
+});
 const READ_TOOL_MAX_RESULT_CHARS = 50_000;
-const COMPACT_RESOURCE_FILE_NAMES = new Set(["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
+const COMPACT_RESOURCE_FILE_NAMES = new Set(["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
 const defaultReadOperations = {
     readFile: (path) => fsReadFile(path),
     access: (path) => fsAccess(path, constants.R_OK),
@@ -212,10 +218,8 @@ export function createReadToolDefinition(cwd, options) {
         name: "read",
         label: "read",
         description: "Read files, directories, archives, SQLite databases, internal resources, images, documents, and URLs through one path string.",
-        promptSnippet: "Read a path selector.",
-        promptGuidelines: [
-            "Use read to inspect file and resource contents; use path selectors for line ranges, raw output, and conflict views.",
-        ],
+        promptSnippet: readToolSystemPromptContribution.snippet,
+        promptGuidelines: [...readToolSystemPromptContribution.guidelines],
         parameters: readSchema,
         maxResultSizeChars: Infinity,
         async execute(_toolCallId, { path }, signal, _onUpdate, ctx) {
@@ -470,12 +474,20 @@ export function createReadToolDefinition(cwd, options) {
                             resolve({ content, details: readSourceMeta(absolutePath) });
                             return;
                         }
-                        if (!options?.operations && (await fsStat(absolutePath)).isDirectory()) {
-                            const tree = await buildDirectoryTree(absolutePath, {
+                        let tree;
+                        if (ops.stat && ops.listDir) {
+                            const stat = await ops.stat(absolutePath);
+                            if (stat?.isDirectory)
+                                tree = await buildDirectoryTreeFromOperations(absolutePath, { listDir: ops.listDir }, { maxDepth: 2, perDirLimit: 12, rootLimit: null });
+                        }
+                        else if (!options?.operations && (await fsStat(absolutePath)).isDirectory()) {
+                            tree = await buildDirectoryTree(absolutePath, {
                                 maxDepth: 2,
                                 perDirLimit: 12,
                                 rootLimit: null,
                             });
+                        }
+                        if (tree) {
                             const allLines = tree.rendered.split("\n"), rangeSelection = (rawOutput ? selectExactReadRanges : selectReadRanges)(allLines, effectiveRanges), startLine = rangeSelection
                                 ? rangeSelection.firstLine - 1
                                 : effectiveOffset