@bastani/atomic 0.9.13-alpha.1 → 0.9.13-alpha.3

package/dist/core/tools/oversized-tool-result.js

@@ -1,8 +1,10 @@
 import { Buffer } from "node:buffer";
-import { mkdir, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open } from "node:fs/promises";
 import { join } from "node:path";
-import { APP_NAME } from "../../config.js";
+import { getErrnoCode } from "./errno.js";
+import { capPersistedText } from "./persisted-output-file.js";
+import { ensureTempDir, resolveSessionTempDirPath, SESSION_TEMP_DIR_MODE, SESSION_TEMP_FILE_MODE, } from "./session-temp-dir.js";
 import { DEFAULT_MAX_RESULT_SIZE_CHARS, PERSISTED_OUTPUT_CLOSING_TAG, PERSISTED_OUTPUT_TAG, PREVIEW_SIZE_BYTES, TOOL_RESULTS_SUBDIR, } from "./tool-limits.js";
 /**
  * Resolve the effective persistence threshold (in characters) for a tool.
@@ -112,22 +114,113 @@ function sanitizePathComponent(value, fallback) {
     const sanitized = trimUnderscores(value.replace(/[^a-zA-Z0-9._-]+/g, "_")).slice(0, 64);
     return sanitized.length > 0 ? sanitized : fallback;
 }
-/** Session-scoped directory for persisted tool results: `<sessionDir>/tool-results`. */
-function getToolResultsDir(input) {
+/**
+ * Session-scoped directory for persisted tool results.
+ *
+ * A disk-backed session owns `<sessionDir>/tool-results`. It is created here and
+ * then chmodded, because `mode` on mkdir is only a request the process umask
+ * narrows — a umask of 0o777 otherwise leaves a directory at 000 that nothing,
+ * this process included, can write into.
+ *
+ * An in-memory session falls back to the owner- and session-scoped temp tree, so
+ * the sweeper can reap it once the session is gone — and that path goes through
+ * {@link ensureTempDir}, which validates every component below the system temp
+ * directory instead of letting `mkdir -p` follow a planted link.
+ */
+async function ensureToolResultsDir(input) {
     if (input.sessionDir?.trim()) {
-        return join(input.sessionDir, TOOL_RESULTS_SUBDIR);
+        const dir = join(input.sessionDir, TOOL_RESULTS_SUBDIR);
+        await mkdir(dir, { recursive: true, mode: SESSION_TEMP_DIR_MODE });
+        if (process.platform !== "win32") {
+            await chmod(dir, SESSION_TEMP_DIR_MODE);
+        }
+        return dir;
+    }
+    return ensureTempDir(join(resolveSessionTempDirPath(input.sessionId), TOOL_RESULTS_SUBDIR));
+}
+function isOwnedByCurrentUser(uid) {
+    const currentUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (typeof currentUid !== "number") {
+        return true;
+    }
+    return typeof uid === "bigint" ? uid === BigInt(currentUid) : uid === currentUid;
+}
+function sameFileIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+ * Force an open persisted file to owner-only and prove it.
+ *
+ * `mode` on open is a request the process umask narrows, so a hostile or merely
+ * odd umask can leave the file at 000 — advertised but unreadable. Throws when
+ * the mode cannot be reached or the file belongs to another account.
+ */
+async function enforceOwnerOnlyMode(handle, filepath) {
+    if (process.platform === "win32") {
+        return;
+    }
+    const before = await handle.stat();
+    if (!isOwnedByCurrentUser(before.uid)) {
+        throw new Error(`persisted tool result ${filepath} is owned by another account`);
+    }
+    await handle.chmod(SESSION_TEMP_FILE_MODE);
+    const after = await handle.stat();
+    if ((after.mode & 0o777) !== SESSION_TEMP_FILE_MODE) {
+        throw new Error(`persisted tool result ${filepath} could not be restricted to 0600`);
+    }
+    if (!isOwnedByCurrentUser(after.uid)) {
+        throw new Error(`persisted tool result ${filepath} is owned by another account`);
     }
-    // Fall back to a stable session-scoped temp directory for in-memory sessions.
-    const safeApp = sanitizePathComponent(APP_NAME || "atomic", "atomic");
-    const safeSessionId = sanitizePathComponent(input.sessionId || "session", "session");
-    return join(tmpdir(), `${safeApp}-${TOOL_RESULTS_SUBDIR}`, safeSessionId);
 }
-function getErrnoCode(error) {
-    if (error && typeof error === "object" && "code" in error) {
-        const code = error.code;
-        return typeof code === "string" ? code : undefined;
+/**
+ * Validate a file left by a previous turn before advertising it again.
+ *
+ * The replay path is what makes repeated calls idempotent, but a file that is no
+ * longer ours, or is no longer owner-only, must not be handed back. It is never
+ * deleted either: refusing costs a preview, deleting could destroy someone
+ * else's data.
+ */
+async function adoptExistingResultFile(filepath) {
+    try {
+        const initialPathStat = await lstat(filepath, { bigint: true });
+        if (initialPathStat.isSymbolicLink() || !initialPathStat.isFile() || !isOwnedByCurrentUser(initialPathStat.uid)) {
+            return false;
+        }
+        const noFollow = process.platform !== "win32" && typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+        const handle = await open(filepath, constants.O_RDONLY | noFollow);
+        try {
+            const handleStat = await handle.stat({ bigint: true });
+            if (!handleStat.isFile() || !sameFileIdentity(initialPathStat, handleStat)) {
+                return false;
+            }
+            const pathBeforeChmod = await lstat(filepath, { bigint: true });
+            if (pathBeforeChmod.isSymbolicLink() ||
+                !pathBeforeChmod.isFile() ||
+                !sameFileIdentity(initialPathStat, pathBeforeChmod) ||
+                !sameFileIdentity(handleStat, pathBeforeChmod) ||
+                !isOwnedByCurrentUser(pathBeforeChmod.uid)) {
+                return false;
+            }
+            await enforceOwnerOnlyMode(handle, filepath);
+            // Do not advertise a path replaced while the descriptor was open.
+            const [finalPathStat, finalHandleStat] = await Promise.all([
+                lstat(filepath, { bigint: true }),
+                handle.stat({ bigint: true }),
+            ]);
+            return (!finalPathStat.isSymbolicLink() &&
+                finalPathStat.isFile() &&
+                finalHandleStat.isFile() &&
+                sameFileIdentity(finalPathStat, finalHandleStat) &&
+                isOwnedByCurrentUser(finalPathStat.uid) &&
+                isOwnedByCurrentUser(finalHandleStat.uid));
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return false;
     }
-    return undefined;
 }
 /**
  * Persist the full tool output to a session-scoped file and return its path.
@@ -139,17 +232,31 @@ function getErrnoCode(error) {
  * returning the original result unchanged.
  */
 async function persistToolOutput(input) {
-    const dir = getToolResultsDir({ sessionDir: input.sessionDir, sessionId: input.sessionId });
-    const fileName = `${sanitizePathComponent(input.toolCallId, "tool-result")}.txt`;
-    const filepath = join(dir, fileName);
+    let dir;
     try {
-        await mkdir(dir, { recursive: true, mode: 0o700 });
-        await writeFile(filepath, input.text, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        dir = await ensureToolResultsDir({ sessionDir: input.sessionDir, sessionId: input.sessionId });
+    }
+    catch {
+        // Refused (see TempDirRefusedError) or unwritable: leave the result unchanged
+        // rather than pointing the model at a directory we do not own.
+        return undefined;
+    }
+    const filepath = join(dir, `${sanitizePathComponent(input.toolCallId, "tool-result")}.txt`);
+    try {
+        const handle = await open(filepath, "wx", SESSION_TEMP_FILE_MODE);
+        try {
+            await handle.writeFile(capPersistedText(input.text), "utf8");
+            await enforceOwnerOnlyMode(handle, filepath);
+        }
+        finally {
+            await handle.close();
+        }
     }
     catch (error) {
         if (getErrnoCode(error) === "EEXIST") {
-            // Already persisted on a prior turn — reuse the existing file.
-            return filepath;
+            // Already persisted on a prior turn — reuse the existing file, but only
+            // after confirming it is still ours and still owner-only.
+            return (await adoptExistingResultFile(filepath)) ? filepath : undefined;
         }
         return undefined;
     }

package/dist/core/tools/oversized-tool-result.js.map

@@ -1 +1 @@
-{"version":3,"file":"oversized-tool-result.js","sourceRoot":"","sources":["../../../src/core/tools/oversized-tool-result.ts"],"names":[],"mappings":"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","sourcesContent":["import { Buffer } from \"node:buffer\";\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { AgentToolResult } from \"@earendil-works/pi-agent-core\";\nimport type { ImageContent, TextContent } from \"@earendil-works/pi-ai/compat\";\nimport { APP_NAME } from \"../../config.ts\";\nimport {\n\tDEFAULT_MAX_RESULT_SIZE_CHARS,\n\tPERSISTED_OUTPUT_CLOSING_TAG,\n\tPERSISTED_OUTPUT_TAG,\n\tPREVIEW_SIZE_BYTES,\n\tTOOL_RESULTS_SUBDIR,\n} from \"./tool-limits.js\";\n\n/**\n * Resolve the effective persistence threshold (in characters) for a tool.\n *\n * Mirrors the upstream `getPersistenceThreshold` convention: a tool may declare a\n * lower per-tool cap, but the global {@link DEFAULT_MAX_RESULT_SIZE_CHARS} acts as\n * a system-wide ceiling. `Infinity` is a hard opt-out for self-bounded tools whose\n * output is already a file the model reads back, where persisting would be circular.\n */\nexport function getPersistenceThreshold(declaredMaxResultSizeChars?: number): number {\n\tif (declaredMaxResultSizeChars === undefined) {\n\t\treturn DEFAULT_MAX_RESULT_SIZE_CHARS;\n\t}\n\tif (!Number.isFinite(declaredMaxResultSizeChars)) {\n\t\treturn declaredMaxResultSizeChars;\n\t}\n\treturn Math.min(declaredMaxResultSizeChars, DEFAULT_MAX_RESULT_SIZE_CHARS);\n}\n\nexport interface RedirectOversizedToolResultInput<TDetails = unknown> {\n\ttoolName: string;\n\ttoolCallId: string;\n\tresult: Pick<AgentToolResult<TDetails>, \"content\" | \"details\">;\n\tisError: boolean;\n\tsessionId: string;\n\tsessionDir?: string;\n\t/** Optional per-tool character cap; clamped by {@link DEFAULT_MAX_RESULT_SIZE_CHARS}. */\n\tmaxResultSizeChars?: number;\n}\n\nexport interface OversizedToolResultReplacement {\n\tcontent: TextContent[];\n\tdetails: unknown;\n\tisError: boolean;\n}\n\n/**\n * Human-readable byte size, e.g. `1536` → \"1.5KB\". Intentionally mirrors\n * upstream Claude Code `formatFileSize` wording instead of using tools/truncate.ts.\n */\nexport function formatFileSize(sizeInBytes: number): string {\n\tconst kb = sizeInBytes / 1024;\n\tif (kb < 1) {\n\t\treturn `${sizeInBytes} bytes`;\n\t}\n\tif (kb < 1024) {\n\t\treturn `${kb.toFixed(1).replace(/\\.0$/, \"\")}KB`;\n\t}\n\tconst mb = kb / 1024;\n\tif (mb < 1024) {\n\t\treturn `${mb.toFixed(1).replace(/\\.0$/, \"\")}MB`;\n\t}\n\tconst gb = mb / 1024;\n\treturn `${gb.toFixed(1).replace(/\\.0$/, \"\")}GB`;\n}\n\nfunction hasImageBlock(content: readonly (TextContent | ImageContent)[]): boolean {\n\treturn content.some((block) => block.type === \"image\");\n}\n\n/** Concatenate the text blocks of a tool result into a single string. */\nfunction collectText(content: readonly (TextContent | ImageContent)[]): string {\n\treturn content\n\t\t.filter((block): block is TextContent => block.type === \"text\")\n\t\t.map((block) => block.text)\n\t\t.join(\"\");\n}\n\n/**\n * Generate a preview of content, truncating at a newline boundary when possible.\n * Ported from the reference `generatePreview`.\n */\nexport function generatePreview(content: string, maxBytes: number): { preview: string; hasMore: boolean } {\n\tif (Buffer.byteLength(content, \"utf8\") <= maxBytes) {\n\t\treturn { preview: content, hasMore: false };\n\t}\n\n\tlet bytes = 0;\n\tlet hardCutIndex = 0;\n\tlet lastNewlineIndex = -1;\n\tlet lastNewlineBytes = 0;\n\n\tfor (const character of content) {\n\t\tconst characterBytes = Buffer.byteLength(character, \"utf8\");\n\t\tif (bytes + characterBytes > maxBytes) {\n\t\t\tbreak;\n\t\t}\n\t\tconst characterStartIndex = hardCutIndex;\n\t\tbytes += characterBytes;\n\t\thardCutIndex += character.length;\n\t\tif (character === \"\\n\") {\n\t\t\tlastNewlineIndex = characterStartIndex;\n\t\t\tlastNewlineBytes = bytes - characterBytes;\n\t\t}\n\t}\n\n\t// Find the last newline within the byte limit to avoid cutting mid-line;\n\t// fall back to the hard byte limit when the newline is too close to the start.\n\tconst cutPoint = lastNewlineBytes > maxBytes * 0.5 ? lastNewlineIndex : hardCutIndex;\n\treturn { preview: content.slice(0, cutPoint), hasMore: true };\n}\n\n/**\n * Build the `<persisted-output>` preview message shown to the model in place of\n * the oversized content. Ported from the reference `buildLargeToolResultMessage`.\n */\nfunction buildPersistedOutputMessage(input: {\n\toriginalSizeBytes: number;\n\tfilepath: string;\n\tpreview: string;\n\thasMore: boolean;\n}): string {\n\tlet message = `${PERSISTED_OUTPUT_TAG}\\n`;\n\tmessage += `Output too large (${formatFileSize(input.originalSizeBytes)}). Full output saved to: ${input.filepath}\\n\\n`;\n\tmessage += `Preview (first ${formatFileSize(PREVIEW_SIZE_BYTES)}):\\n`;\n\tmessage += input.preview;\n\tmessage += input.hasMore ? \"\\n...\\n\" : \"\\n\";\n\tmessage += PERSISTED_OUTPUT_CLOSING_TAG;\n\treturn message;\n}\n\n/** Strip leading/trailing underscores with a linear scan (no backtracking regex). */\nfunction trimUnderscores(value: string): string {\n\tlet start = 0;\n\tlet end = value.length;\n\twhile (start < end && value[start] === \"_\") {\n\t\tstart++;\n\t}\n\twhile (end > start && value[end - 1] === \"_\") {\n\t\tend--;\n\t}\n\treturn value.slice(start, end);\n}\n\nfunction sanitizePathComponent(value: string, fallback: string): string {\n\t// Collapse disallowed characters to \"_\", then strip leading/trailing \"_\". The trim uses\n\t// a manual linear scan instead of a /^_+|_+$/ regex to avoid a polynomial-time ReDoS on\n\t// tool-call ids containing long runs of underscores (CodeQL js/polynomial-redos).\n\tconst sanitized = trimUnderscores(value.replace(/[^a-zA-Z0-9._-]+/g, \"_\")).slice(0, 64);\n\treturn sanitized.length > 0 ? sanitized : fallback;\n}\n\n/** Session-scoped directory for persisted tool results: `<sessionDir>/tool-results`. */\nfunction getToolResultsDir(input: { sessionDir?: string; sessionId: string }): string {\n\tif (input.sessionDir?.trim()) {\n\t\treturn join(input.sessionDir, TOOL_RESULTS_SUBDIR);\n\t}\n\t// Fall back to a stable session-scoped temp directory for in-memory sessions.\n\tconst safeApp = sanitizePathComponent(APP_NAME || \"atomic\", \"atomic\");\n\tconst safeSessionId = sanitizePathComponent(input.sessionId || \"session\", \"session\");\n\treturn join(tmpdir(), `${safeApp}-${TOOL_RESULTS_SUBDIR}`, safeSessionId);\n}\n\nfunction getErrnoCode(error: unknown): string | undefined {\n\tif (error && typeof error === \"object\" && \"code\" in error) {\n\t\tconst code = (error as { code?: unknown }).code;\n\t\treturn typeof code === \"string\" ? code : undefined;\n\t}\n\treturn undefined;\n}\n\n/**\n * Persist the full tool output to a session-scoped file and return its path.\n *\n * The tool_use_id is unique per invocation and the content is deterministic for a\n * given id, so we write with the `wx` flag and treat `EEXIST` as success — this\n * makes repeated calls (e.g. replay/compaction) idempotent without rewriting.\n * Returns `undefined` on any other write failure so the caller can fall back to\n * returning the original result unchanged.\n */\nasync function persistToolOutput(input: {\n\ttext: string;\n\tsessionDir?: string;\n\tsessionId: string;\n\ttoolCallId: string;\n}): Promise<string | undefined> {\n\tconst dir = getToolResultsDir({ sessionDir: input.sessionDir, sessionId: input.sessionId });\n\tconst fileName = `${sanitizePathComponent(input.toolCallId, \"tool-result\")}.txt`;\n\tconst filepath = join(dir, fileName);\n\ttry {\n\t\tawait mkdir(dir, { recursive: true, mode: 0o700 });\n\t\tawait writeFile(filepath, input.text, { encoding: \"utf8\", mode: 0o600, flag: \"wx\" });\n\t} catch (error) {\n\t\tif (getErrnoCode(error) === \"EEXIST\") {\n\t\t\t// Already persisted on a prior turn — reuse the existing file.\n\t\t\treturn filepath;\n\t\t}\n\t\treturn undefined;\n\t}\n\treturn filepath;\n}\n\n/**\n * When a tool result's text content exceeds the persistence threshold (default\n * 50,000 chars — {@link DEFAULT_MAX_RESULT_SIZE_CHARS}), persist the full output\n * to a session-scoped file and replace the model-visible content with a\n * `<persisted-output>` preview that references the saved file.\n *\n * Returns `undefined` (leave the result untouched) when the result is within the\n * threshold, contains image blocks, or cannot be persisted to disk.\n *\n * Convention ported from the upstream `maybePersistLargeToolResult`\n * (mehmoodosman/claude-code, `src/utils/toolResultStorage.ts`).\n */\nexport async function redirectOversizedToolResult<TDetails = unknown>(\n\tinput: RedirectOversizedToolResultInput<TDetails>,\n): Promise<OversizedToolResultReplacement | undefined> {\n\tconst content = input.result.content;\n\n\t// Image content must be sent to the model as-is; never persist.\n\tif (hasImageBlock(content)) {\n\t\treturn undefined;\n\t}\n\n\tconst text = collectText(content);\n\tconst threshold = getPersistenceThreshold(input.maxResultSizeChars);\n\tif (text.length <= threshold) {\n\t\treturn undefined;\n\t}\n\n\tconst filepath = await persistToolOutput({\n\t\ttext,\n\t\tsessionDir: input.sessionDir,\n\t\tsessionId: input.sessionId,\n\t\ttoolCallId: input.toolCallId,\n\t});\n\t// Graceful degradation: if persistence failed, leave the original result unchanged.\n\tif (filepath === undefined) {\n\t\treturn undefined;\n\t}\n\n\tconst { preview, hasMore } = generatePreview(text, PREVIEW_SIZE_BYTES);\n\tconst message = buildPersistedOutputMessage({\n\t\toriginalSizeBytes: Buffer.byteLength(text, \"utf8\"),\n\t\tfilepath,\n\t\tpreview,\n\t\thasMore,\n\t});\n\n\treturn {\n\t\tcontent: [{ type: \"text\", text: message }],\n\t\t// Details (tool metadata) are passed through untouched, matching the reference\n\t\t// convention which only replaces the model-visible content block.\n\t\tdetails: input.result.details,\n\t\tisError: input.isError,\n\t};\n}\n"]}
+{"version":3,"file":"oversized-tool-result.js","sourceRoot":"","sources":["../../../src/core/tools/oversized-tool-result.ts"],"names":[],"mappings":"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","sourcesContent":["import { Buffer } from \"node:buffer\";\nimport { constants } from \"node:fs\";\nimport type { FileHandle } from \"node:fs/promises\";\nimport { chmod, lstat, mkdir, open } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { AgentToolResult } from \"@earendil-works/pi-agent-core\";\nimport type { ImageContent, TextContent } from \"@earendil-works/pi-ai/compat\";\nimport { getErrnoCode } from \"./errno.ts\";\nimport { capPersistedText } from \"./persisted-output-file.ts\";\nimport {\n\tensureTempDir,\n\tresolveSessionTempDirPath,\n\tSESSION_TEMP_DIR_MODE,\n\tSESSION_TEMP_FILE_MODE,\n} from \"./session-temp-dir.ts\";\nimport {\n\tDEFAULT_MAX_RESULT_SIZE_CHARS,\n\tPERSISTED_OUTPUT_CLOSING_TAG,\n\tPERSISTED_OUTPUT_TAG,\n\tPREVIEW_SIZE_BYTES,\n\tTOOL_RESULTS_SUBDIR,\n} from \"./tool-limits.js\";\n\n/**\n * Resolve the effective persistence threshold (in characters) for a tool.\n *\n * Mirrors the upstream `getPersistenceThreshold` convention: a tool may declare a\n * lower per-tool cap, but the global {@link DEFAULT_MAX_RESULT_SIZE_CHARS} acts as\n * a system-wide ceiling. `Infinity` is a hard opt-out for self-bounded tools whose\n * output is already a file the model reads back, where persisting would be circular.\n */\nexport function getPersistenceThreshold(declaredMaxResultSizeChars?: number): number {\n\tif (declaredMaxResultSizeChars === undefined) {\n\t\treturn DEFAULT_MAX_RESULT_SIZE_CHARS;\n\t}\n\tif (!Number.isFinite(declaredMaxResultSizeChars)) {\n\t\treturn declaredMaxResultSizeChars;\n\t}\n\treturn Math.min(declaredMaxResultSizeChars, DEFAULT_MAX_RESULT_SIZE_CHARS);\n}\n\nexport interface RedirectOversizedToolResultInput<TDetails = unknown> {\n\ttoolName: string;\n\ttoolCallId: string;\n\tresult: Pick<AgentToolResult<TDetails>, \"content\" | \"details\">;\n\tisError: boolean;\n\tsessionId: string;\n\tsessionDir?: string;\n\t/** Optional per-tool character cap; clamped by {@link DEFAULT_MAX_RESULT_SIZE_CHARS}. */\n\tmaxResultSizeChars?: number;\n}\n\nexport interface OversizedToolResultReplacement {\n\tcontent: TextContent[];\n\tdetails: unknown;\n\tisError: boolean;\n}\n\n/**\n * Human-readable byte size, e.g. `1536` → \"1.5KB\". Intentionally mirrors\n * upstream Claude Code `formatFileSize` wording instead of using tools/truncate.ts.\n */\nexport function formatFileSize(sizeInBytes: number): string {\n\tconst kb = sizeInBytes / 1024;\n\tif (kb < 1) {\n\t\treturn `${sizeInBytes} bytes`;\n\t}\n\tif (kb < 1024) {\n\t\treturn `${kb.toFixed(1).replace(/\\.0$/, \"\")}KB`;\n\t}\n\tconst mb = kb / 1024;\n\tif (mb < 1024) {\n\t\treturn `${mb.toFixed(1).replace(/\\.0$/, \"\")}MB`;\n\t}\n\tconst gb = mb / 1024;\n\treturn `${gb.toFixed(1).replace(/\\.0$/, \"\")}GB`;\n}\n\nfunction hasImageBlock(content: readonly (TextContent | ImageContent)[]): boolean {\n\treturn content.some((block) => block.type === \"image\");\n}\n\n/** Concatenate the text blocks of a tool result into a single string. */\nfunction collectText(content: readonly (TextContent | ImageContent)[]): string {\n\treturn content\n\t\t.filter((block): block is TextContent => block.type === \"text\")\n\t\t.map((block) => block.text)\n\t\t.join(\"\");\n}\n\n/**\n * Generate a preview of content, truncating at a newline boundary when possible.\n * Ported from the reference `generatePreview`.\n */\nexport function generatePreview(content: string, maxBytes: number): { preview: string; hasMore: boolean } {\n\tif (Buffer.byteLength(content, \"utf8\") <= maxBytes) {\n\t\treturn { preview: content, hasMore: false };\n\t}\n\n\tlet bytes = 0;\n\tlet hardCutIndex = 0;\n\tlet lastNewlineIndex = -1;\n\tlet lastNewlineBytes = 0;\n\n\tfor (const character of content) {\n\t\tconst characterBytes = Buffer.byteLength(character, \"utf8\");\n\t\tif (bytes + characterBytes > maxBytes) {\n\t\t\tbreak;\n\t\t}\n\t\tconst characterStartIndex = hardCutIndex;\n\t\tbytes += characterBytes;\n\t\thardCutIndex += character.length;\n\t\tif (character === \"\\n\") {\n\t\t\tlastNewlineIndex = characterStartIndex;\n\t\t\tlastNewlineBytes = bytes - characterBytes;\n\t\t}\n\t}\n\n\t// Find the last newline within the byte limit to avoid cutting mid-line;\n\t// fall back to the hard byte limit when the newline is too close to the start.\n\tconst cutPoint = lastNewlineBytes > maxBytes * 0.5 ? lastNewlineIndex : hardCutIndex;\n\treturn { preview: content.slice(0, cutPoint), hasMore: true };\n}\n\n/**\n * Build the `<persisted-output>` preview message shown to the model in place of\n * the oversized content. Ported from the reference `buildLargeToolResultMessage`.\n */\nfunction buildPersistedOutputMessage(input: {\n\toriginalSizeBytes: number;\n\tfilepath: string;\n\tpreview: string;\n\thasMore: boolean;\n}): string {\n\tlet message = `${PERSISTED_OUTPUT_TAG}\\n`;\n\tmessage += `Output too large (${formatFileSize(input.originalSizeBytes)}). Full output saved to: ${input.filepath}\\n\\n`;\n\tmessage += `Preview (first ${formatFileSize(PREVIEW_SIZE_BYTES)}):\\n`;\n\tmessage += input.preview;\n\tmessage += input.hasMore ? \"\\n...\\n\" : \"\\n\";\n\tmessage += PERSISTED_OUTPUT_CLOSING_TAG;\n\treturn message;\n}\n\n/** Strip leading/trailing underscores with a linear scan (no backtracking regex). */\nfunction trimUnderscores(value: string): string {\n\tlet start = 0;\n\tlet end = value.length;\n\twhile (start < end && value[start] === \"_\") {\n\t\tstart++;\n\t}\n\twhile (end > start && value[end - 1] === \"_\") {\n\t\tend--;\n\t}\n\treturn value.slice(start, end);\n}\n\nfunction sanitizePathComponent(value: string, fallback: string): string {\n\t// Collapse disallowed characters to \"_\", then strip leading/trailing \"_\". The trim uses\n\t// a manual linear scan instead of a /^_+|_+$/ regex to avoid a polynomial-time ReDoS on\n\t// tool-call ids containing long runs of underscores (CodeQL js/polynomial-redos).\n\tconst sanitized = trimUnderscores(value.replace(/[^a-zA-Z0-9._-]+/g, \"_\")).slice(0, 64);\n\treturn sanitized.length > 0 ? sanitized : fallback;\n}\n\n/**\n * Session-scoped directory for persisted tool results.\n *\n * A disk-backed session owns `<sessionDir>/tool-results`. It is created here and\n * then chmodded, because `mode` on mkdir is only a request the process umask\n * narrows — a umask of 0o777 otherwise leaves a directory at 000 that nothing,\n * this process included, can write into.\n *\n * An in-memory session falls back to the owner- and session-scoped temp tree, so\n * the sweeper can reap it once the session is gone — and that path goes through\n * {@link ensureTempDir}, which validates every component below the system temp\n * directory instead of letting `mkdir -p` follow a planted link.\n */\nasync function ensureToolResultsDir(input: { sessionDir?: string; sessionId: string }): Promise<string> {\n\tif (input.sessionDir?.trim()) {\n\t\tconst dir = join(input.sessionDir, TOOL_RESULTS_SUBDIR);\n\t\tawait mkdir(dir, { recursive: true, mode: SESSION_TEMP_DIR_MODE });\n\t\tif (process.platform !== \"win32\") {\n\t\t\tawait chmod(dir, SESSION_TEMP_DIR_MODE);\n\t\t}\n\t\treturn dir;\n\t}\n\treturn ensureTempDir(join(resolveSessionTempDirPath(input.sessionId), TOOL_RESULTS_SUBDIR));\n}\n\nfunction isOwnedByCurrentUser(uid: number | bigint): boolean {\n\tconst currentUid = typeof process.getuid === \"function\" ? process.getuid() : undefined;\n\tif (typeof currentUid !== \"number\") {\n\t\treturn true;\n\t}\n\treturn typeof uid === \"bigint\" ? uid === BigInt(currentUid) : uid === currentUid;\n}\n\nfunction sameFileIdentity(left: { dev: bigint; ino: bigint }, right: { dev: bigint; ino: bigint }): boolean {\n\treturn left.dev === right.dev && left.ino === right.ino;\n}\n\n/**\n * Force an open persisted file to owner-only and prove it.\n *\n * `mode` on open is a request the process umask narrows, so a hostile or merely\n * odd umask can leave the file at 000 — advertised but unreadable. Throws when\n * the mode cannot be reached or the file belongs to another account.\n */\nasync function enforceOwnerOnlyMode(handle: FileHandle, filepath: string): Promise<void> {\n\tif (process.platform === \"win32\") {\n\t\treturn;\n\t}\n\tconst before = await handle.stat();\n\tif (!isOwnedByCurrentUser(before.uid)) {\n\t\tthrow new Error(`persisted tool result ${filepath} is owned by another account`);\n\t}\n\tawait handle.chmod(SESSION_TEMP_FILE_MODE);\n\tconst after = await handle.stat();\n\tif ((after.mode & 0o777) !== SESSION_TEMP_FILE_MODE) {\n\t\tthrow new Error(`persisted tool result ${filepath} could not be restricted to 0600`);\n\t}\n\tif (!isOwnedByCurrentUser(after.uid)) {\n\t\tthrow new Error(`persisted tool result ${filepath} is owned by another account`);\n\t}\n}\n\n/**\n * Validate a file left by a previous turn before advertising it again.\n *\n * The replay path is what makes repeated calls idempotent, but a file that is no\n * longer ours, or is no longer owner-only, must not be handed back. It is never\n * deleted either: refusing costs a preview, deleting could destroy someone\n * else's data.\n */\nasync function adoptExistingResultFile(filepath: string): Promise<boolean> {\n\ttry {\n\t\tconst initialPathStat = await lstat(filepath, { bigint: true });\n\t\tif (initialPathStat.isSymbolicLink() || !initialPathStat.isFile() || !isOwnedByCurrentUser(initialPathStat.uid)) {\n\t\t\treturn false;\n\t\t}\n\t\tconst noFollow =\n\t\t\tprocess.platform !== \"win32\" && typeof constants.O_NOFOLLOW === \"number\" ? constants.O_NOFOLLOW : 0;\n\t\tconst handle = await open(filepath, constants.O_RDONLY | noFollow);\n\t\ttry {\n\t\t\tconst handleStat = await handle.stat({ bigint: true });\n\t\t\tif (!handleStat.isFile() || !sameFileIdentity(initialPathStat, handleStat)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tconst pathBeforeChmod = await lstat(filepath, { bigint: true });\n\t\t\tif (\n\t\t\t\tpathBeforeChmod.isSymbolicLink() ||\n\t\t\t\t!pathBeforeChmod.isFile() ||\n\t\t\t\t!sameFileIdentity(initialPathStat, pathBeforeChmod) ||\n\t\t\t\t!sameFileIdentity(handleStat, pathBeforeChmod) ||\n\t\t\t\t!isOwnedByCurrentUser(pathBeforeChmod.uid)\n\t\t\t) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tawait enforceOwnerOnlyMode(handle, filepath);\n\n\t\t\t// Do not advertise a path replaced while the descriptor was open.\n\t\t\tconst [finalPathStat, finalHandleStat] = await Promise.all([\n\t\t\t\tlstat(filepath, { bigint: true }),\n\t\t\t\thandle.stat({ bigint: true }),\n\t\t\t]);\n\t\t\treturn (\n\t\t\t\t!finalPathStat.isSymbolicLink() &&\n\t\t\t\tfinalPathStat.isFile() &&\n\t\t\t\tfinalHandleStat.isFile() &&\n\t\t\t\tsameFileIdentity(finalPathStat, finalHandleStat) &&\n\t\t\t\tisOwnedByCurrentUser(finalPathStat.uid) &&\n\t\t\t\tisOwnedByCurrentUser(finalHandleStat.uid)\n\t\t\t);\n\t\t} finally {\n\t\t\tawait handle.close();\n\t\t}\n\t} catch {\n\t\treturn false;\n\t}\n}\n/**\n * Persist the full tool output to a session-scoped file and return its path.\n *\n * The tool_use_id is unique per invocation and the content is deterministic for a\n * given id, so we write with the `wx` flag and treat `EEXIST` as success — this\n * makes repeated calls (e.g. replay/compaction) idempotent without rewriting.\n * Returns `undefined` on any other write failure so the caller can fall back to\n * returning the original result unchanged.\n */\nasync function persistToolOutput(input: {\n\ttext: string;\n\tsessionDir?: string;\n\tsessionId: string;\n\ttoolCallId: string;\n}): Promise<string | undefined> {\n\tlet dir: string;\n\ttry {\n\t\tdir = await ensureToolResultsDir({ sessionDir: input.sessionDir, sessionId: input.sessionId });\n\t} catch {\n\t\t// Refused (see TempDirRefusedError) or unwritable: leave the result unchanged\n\t\t// rather than pointing the model at a directory we do not own.\n\t\treturn undefined;\n\t}\n\tconst filepath = join(dir, `${sanitizePathComponent(input.toolCallId, \"tool-result\")}.txt`);\n\ttry {\n\t\tconst handle = await open(filepath, \"wx\", SESSION_TEMP_FILE_MODE);\n\t\ttry {\n\t\t\tawait handle.writeFile(capPersistedText(input.text), \"utf8\");\n\t\t\tawait enforceOwnerOnlyMode(handle, filepath);\n\t\t} finally {\n\t\t\tawait handle.close();\n\t\t}\n\t} catch (error) {\n\t\tif (getErrnoCode(error) === \"EEXIST\") {\n\t\t\t// Already persisted on a prior turn — reuse the existing file, but only\n\t\t\t// after confirming it is still ours and still owner-only.\n\t\t\treturn (await adoptExistingResultFile(filepath)) ? filepath : undefined;\n\t\t}\n\t\treturn undefined;\n\t}\n\treturn filepath;\n}\n\n/**\n * When a tool result's text content exceeds the persistence threshold (default\n * 50,000 chars — {@link DEFAULT_MAX_RESULT_SIZE_CHARS}), persist the full output\n * to a session-scoped file and replace the model-visible content with a\n * `<persisted-output>` preview that references the saved file.\n *\n * Returns `undefined` (leave the result untouched) when the result is within the\n * threshold, contains image blocks, or cannot be persisted to disk.\n *\n * Convention ported from the upstream `maybePersistLargeToolResult`\n * (mehmoodosman/claude-code, `src/utils/toolResultStorage.ts`).\n */\nexport async function redirectOversizedToolResult<TDetails = unknown>(\n\tinput: RedirectOversizedToolResultInput<TDetails>,\n): Promise<OversizedToolResultReplacement | undefined> {\n\tconst content = input.result.content;\n\n\t// Image content must be sent to the model as-is; never persist.\n\tif (hasImageBlock(content)) {\n\t\treturn undefined;\n\t}\n\n\tconst text = collectText(content);\n\tconst threshold = getPersistenceThreshold(input.maxResultSizeChars);\n\tif (text.length <= threshold) {\n\t\treturn undefined;\n\t}\n\n\tconst filepath = await persistToolOutput({\n\t\ttext,\n\t\tsessionDir: input.sessionDir,\n\t\tsessionId: input.sessionId,\n\t\ttoolCallId: input.toolCallId,\n\t});\n\t// Graceful degradation: if persistence failed, leave the original result unchanged.\n\tif (filepath === undefined) {\n\t\treturn undefined;\n\t}\n\n\tconst { preview, hasMore } = generatePreview(text, PREVIEW_SIZE_BYTES);\n\tconst message = buildPersistedOutputMessage({\n\t\toriginalSizeBytes: Buffer.byteLength(text, \"utf8\"),\n\t\tfilepath,\n\t\tpreview,\n\t\thasMore,\n\t});\n\n\treturn {\n\t\tcontent: [{ type: \"text\", text: message }],\n\t\t// Details (tool metadata) are passed through untouched, matching the reference\n\t\t// convention which only replaces the model-visible content block.\n\t\tdetails: input.result.details,\n\t\tisError: input.isError,\n\t};\n}\n"]}

package/dist/core/tools/persisted-output-file.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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";
+/** Trim a buffer to at most `maxBytes` without splitting a valid UTF-8 sequence. */
+export declare function truncateBufferAtUtf8Boundary(buffer: Buffer, maxBytes: number): Buffer;
+/**
+ * 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 declare function completeUtf8PrefixLength(buffer: Buffer): number;
+/**
+ * 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 declare function capPersistedText(text: string, maxBytes?: number): string;
+export interface PersistedOutputFileOptions {
+    /** Byte cap for this file. Defaults to {@link MAX_PERSISTED_OUTPUT_BYTES}. */
+    maxBytes?: number;
+}
+/**
+ * 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 declare class PersistedOutputFile {
+    readonly path: string;
+    private stream;
+    private readonly maxBytes;
+    /** Bytes that may be written before the marker's reserved space is needed. */
+    private readonly safeLimit;
+    private writtenBytes;
+    private pending;
+    private capReached;
+    private failure;
+    constructor(path: string, options?: PersistedOutputFileOptions);
+    /** Whether the cap was reached and the marker written. */
+    get truncated(): boolean;
+    /** The write error this file failed with, if any. */
+    get error(): Error | undefined;
+    /** Total input bytes accepted so far, including the unflushed tail. */
+    private get acceptedBytes();
+    write(chunk: Buffer | string): void;
+    /**
+     * 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.
+     */
+    private flushUpTo;
+    /** Release the trailing buffer once the input is known to fit within the cap. */
+    private flushRemainder;
+    /** Close without waiting for the flush to complete. */
+    end(): void;
+    /** Close and wait for the flush, rejecting on a write error. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=persisted-output-file.d.ts.map

package/dist/core/tools/persisted-output-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persisted-output-file.d.ts","sourceRoot":"","sources":["../../../src/core/tools/persisted-output-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAgGrC,oFAAoF;AACpF,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAmC,GAAG,MAAM,CAQpG;AAED,MAAM,WAAW,0BAA0B;IAC1C,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAmB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAoB;IAEnC,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B,EAgBjE;IAED,0DAA0D;IAC1D,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,qDAAqD;IACrD,IAAI,KAAK,IAAI,KAAK,GAAG,SAAS,CAE7B;IAED,uEAAuE;IACvE,OAAO,KAAK,aAAa,GAExB;IAED,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuBlC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAgBjB,iFAAiF;IACjF,OAAO,CAAC,cAAc;IAUtB,uDAAuD;IACvD,GAAG,IAAI,IAAI,CAQV;IAED,gEAAgE;IAC1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA4B3B;CACD"}

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