@arnilo/prism-coding-agent 0.0.5 → 0.0.6

package/dist/read.js

@@ -2,8 +2,8 @@
  * Read tool: read a file from the host filesystem.
  *
  * Behavioral port of pi's core/tools/read for @arnilo/prism-coding-agent, adapted to Prism's
- * `ToolDefinition` contract. Faithfully ports pi's text path (offset/limit → `truncateHead` →
- * continuation notices) and image path (magic-byte MIME → `ImageContent` with base64). Drops pi's
+ * `ToolDefinition` contract. Keeps pi's offset/limit continuation behavior while streaming one
+ * bounded text page; image path remains magic-byte MIME → bounded `ImageContent`. Drops pi's
  * TUI (`renderCall`/`renderResult`, theme/syntax-highlight, compact classifications, key hints) and
  * the model-aware non-vision note (Prism's `ToolExecutionContext` has no model field).
  *
@@ -21,10 +21,12 @@
  */
 import { Buffer } from "node:buffer";
 import { constants } from "node:fs";
-import { access as fsAccess, open, readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import { access as fsAccess, open, stat as fsStat } from "node:fs/promises";
+import { readFileBounded } from "./bounded-file.js";
 import { enforceExecutionPolicy } from "./execution-policy.js";
 import { resolveReadPathAsync } from "./path-utils.js";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, } from "./truncate.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_LINES, DEFAULT_MAX_TEXT_SCAN_BYTES, HARD_MAX_BYTES, HARD_MAX_IMAGE_BYTES, HARD_MAX_LINES, HARD_MAX_TEXT_SCAN_BYTES, validateCodingLimit, } from "./limits.js";
+import { formatSize } from "./truncate.js";
 // --- magic-byte image MIME detection (faithful port of pi utils/mime.js, pure JS, no deps) ---
 const IMAGE_TYPE_SNIFF_BYTES = 4100;
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
@@ -143,9 +145,119 @@ function startsWithAscii(buffer, offset, text) {
 }
 // --- read tool ---
 /** Default maximum image file size before read/transform (10 MB). */
-export const DEFAULT_MAX_IMAGE_BYTES = 10_000_000;
+export { DEFAULT_MAX_IMAGE_BYTES } from "./limits.js";
+async function readLocalTextPage(path, options) {
+    const handle = await open(path, "r");
+    let fileSize;
+    try {
+        fileSize = (await handle.stat()).size;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+    const chunks = [];
+    let retainedBytes = 0;
+    let outputLines = 0;
+    let lineNumber = 1;
+    let scannedBytes = 0;
+    let lineChunkStart = 0;
+    let lineByteStart = 0;
+    const targetLines = options.limit ?? options.maxLines;
+    const content = (trimFinalLf) => {
+        const buffer = Buffer.concat(chunks, retainedBytes);
+        const end = trimFinalLf && buffer[buffer.length - 1] === 0x0a ? buffer.length - 1 : buffer.length;
+        return buffer.subarray(0, end).toString("utf-8");
+    };
+    const partial = (truncatedBy, nextOffset, firstLineExceedsLimit = false, totalLines) => ({
+        content: firstLineExceedsLimit ? "" : content(true),
+        startLine: options.offset,
+        outputLines,
+        hasMore: true,
+        nextOffset,
+        truncatedBy,
+        firstLineExceedsLimit,
+        scannedBytes,
+        totalLines,
+        totalBytes: fileSize,
+    });
+    try {
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        while (true) {
+            if (options.signal?.aborted)
+                throw new Error("Operation aborted");
+            if (scannedBytes >= options.maxScanBytes) {
+                if (scannedBytes >= fileSize)
+                    break;
+                throw new Error(`Text read exceeded ${formatSize(options.maxScanBytes)} scan limit before reaching the requested page`);
+            }
+            const length = Math.min(buffer.length, options.maxScanBytes - scannedBytes);
+            const { bytesRead } = await handle.read(buffer, 0, length, null);
+            if (bytesRead === 0)
+                break;
+            scannedBytes += bytesRead;
+            let cursor = 0;
+            while (cursor < bytesRead) {
+                const newline = buffer.indexOf(0x0a, cursor);
+                const end = newline === -1 || newline >= bytesRead ? bytesRead : newline + 1;
+                const selected = lineNumber >= options.offset && outputLines < targetLines;
+                if (selected) {
+                    const piece = buffer.subarray(cursor, end);
+                    if (retainedBytes + piece.length > options.maxBytes) {
+                        chunks.length = lineChunkStart;
+                        retainedBytes = lineByteStart;
+                        return partial("bytes", lineNumber, outputLines === 0);
+                    }
+                    chunks.push(Buffer.from(piece));
+                    retainedBytes += piece.length;
+                }
+                cursor = end;
+                if (newline === -1 || newline >= bytesRead)
+                    break;
+                if (selected) {
+                    outputLines++;
+                    if (outputLines >= targetLines) {
+                        let totalLines;
+                        if (scannedBytes === fileSize) {
+                            let remainingNewlines = 0;
+                            for (let index = cursor; index < bytesRead; index++) {
+                                if (buffer[index] === 0x0a)
+                                    remainingNewlines++;
+                            }
+                            totalLines = lineNumber + remainingNewlines + 1;
+                        }
+                        return partial(options.limit === undefined ? "lines" : null, lineNumber + 1, false, totalLines);
+                    }
+                }
+                lineNumber++;
+                lineChunkStart = chunks.length;
+                lineByteStart = retainedBytes;
+            }
+        }
+        if (lineNumber < options.offset) {
+            throw new Error(`Offset ${options.offset} is beyond end of file (${lineNumber} lines total)`);
+        }
+        if (lineNumber >= options.offset && outputLines < targetLines)
+            outputLines++;
+        return {
+            content: content(false),
+            startLine: options.offset,
+            outputLines,
+            hasMore: false,
+            truncatedBy: null,
+            firstLineExceedsLimit: false,
+            scannedBytes,
+            totalLines: lineNumber,
+            totalBytes: scannedBytes,
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
 const defaultReadOperations = {
-    readFile: (path) => fsReadFile(path),
+    readFile: (path, options) => readFileBounded(path, options.maxBytes, options.signal),
+    readText: readLocalTextPage,
     access: (path) => fsAccess(path, constants.R_OK),
     statFile: async (path) => {
         const info = await fsStat(path);
@@ -160,13 +272,14 @@ async function loadImageBuffer(absolutePath, mimeType, ops, options) {
     if (options.signal?.aborted) {
         throw new Error("Operation aborted");
     }
-    if (ops.statFile) {
-        const { size } = await ops.statFile(absolutePath);
-        if (size > options.maxImageBytes) {
-            throw new Error(imageSizeError(size, options.maxImageBytes));
-        }
+    const { size } = await ops.statFile(absolutePath, { signal: options.signal });
+    if (size > options.maxImageBytes) {
+        throw new Error(imageSizeError(size, options.maxImageBytes));
     }
-    let buffer = await ops.readFile(absolutePath);
+    let buffer = await ops.readFile(absolutePath, {
+        maxBytes: options.maxImageBytes,
+        signal: options.signal,
+    });
     if (buffer.length > options.maxImageBytes) {
         throw new Error(imageSizeError(buffer.length, options.maxImageBytes));
     }
@@ -195,10 +308,11 @@ function errorResult(toolCallId, message) {
     };
 }
 export function createReadTool(cwd, options) {
-    const ops = { ...defaultReadOperations, ...options?.operations };
-    const maxLines = options?.maxLines ?? DEFAULT_MAX_LINES;
-    const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;
-    const maxImageBytes = options?.maxImageBytes ?? DEFAULT_MAX_IMAGE_BYTES;
+    const ops = options?.operations ?? defaultReadOperations;
+    const maxLines = validateCodingLimit("maxLines", options?.maxLines ?? DEFAULT_MAX_LINES, HARD_MAX_LINES);
+    const maxBytes = validateCodingLimit("maxBytes", options?.maxBytes ?? DEFAULT_MAX_BYTES, HARD_MAX_BYTES);
+    const maxImageBytes = validateCodingLimit("maxImageBytes", options?.maxImageBytes ?? DEFAULT_MAX_IMAGE_BYTES, HARD_MAX_IMAGE_BYTES);
+    const maxScanBytes = validateCodingLimit("maxScanBytes", options?.maxScanBytes ?? DEFAULT_MAX_TEXT_SCAN_BYTES, HARD_MAX_TEXT_SCAN_BYTES);
     return {
         name: "read",
         description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp); images are returned as image content. For text files, output is truncated to ${maxLines} lines or ${maxBytes / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,
@@ -224,6 +338,10 @@ export function createReadTool(cwd, options) {
                 return errorResult(toolCallId, "path is required and must be a non-empty string.");
             }
             try {
+                const startLine = validateCodingLimit("offset", offset ?? 1, Number.MAX_SAFE_INTEGER);
+                const requestedLines = limit === undefined
+                    ? undefined
+                    : validateCodingLimit("limit", limit, HARD_MAX_LINES);
                 const absolutePath = await resolveReadPathAsync(path, cwd);
                 const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
                     kind: "read",
@@ -235,7 +353,7 @@ export function createReadTool(cwd, options) {
                 if (!policyCheck.allowed)
                     return policyCheck.result;
                 const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
-                await ops.access(allowedPath);
+                await ops.access(allowedPath, { signal: context.signal });
                 const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(allowedPath) : undefined;
                 if (mimeType) {
                     const { buffer, resized } = await loadImageBuffer(allowedPath, mimeType, ops, {
@@ -254,59 +372,55 @@ export function createReadTool(cwd, options) {
                         metadata: { image: { mimeType, resized, bytes: buffer.length } },
                     };
                 }
-                // Text path: faithful port of pi's offset/limit → truncateHead → continuation logic.
-                const buffer = await ops.readFile(allowedPath);
-                const textContent = buffer.toString("utf-8");
-                const allLines = textContent.split("\n");
-                const totalFileLines = allLines.length;
-                // 1-indexed offset → 0-indexed array access.
-                const startLine = offset ? Math.max(0, offset - 1) : 0;
-                const startLineDisplay = startLine + 1;
-                if (startLine >= allLines.length) {
-                    throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+                const page = await ops.readText(allowedPath, {
+                    offset: startLine,
+                    limit: requestedLines,
+                    maxLines,
+                    maxBytes,
+                    maxScanBytes,
+                    signal: context.signal,
+                });
+                const contentBytes = Buffer.byteLength(page.content, "utf-8");
+                if (contentBytes > maxBytes || page.outputLines > (requestedLines ?? maxLines)) {
+                    throw new Error("ReadOperations.readText returned data beyond the requested bounds");
                 }
-                let selectedContent;
-                let userLimitedLines;
-                if (limit !== undefined) {
-                    const endLine = Math.min(startLine + limit, allLines.length);
-                    selectedContent = allLines.slice(startLine, endLine).join("\n");
-                    userLimitedLines = endLine - startLine;
-                }
-                else {
-                    selectedContent = allLines.slice(startLine).join("\n");
-                }
-                const truncation = truncateHead(selectedContent, { maxLines, maxBytes });
-                let outputText;
-                if (truncation.firstLineExceedsLimit) {
-                    // First line alone exceeds the byte limit — point at a shell fallback.
-                    const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
-                    outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(maxBytes)} limit. Use the shell tool: sed -n '${startLineDisplay}p' ${path} | head -c ${maxBytes}]`;
+                const totalLines = page.totalLines ?? page.startLine + page.outputLines + (page.hasMore ? 1 : 0) - 1;
+                const truncation = {
+                    content: page.content,
+                    truncated: page.truncatedBy !== null,
+                    truncatedBy: page.truncatedBy,
+                    totalLines,
+                    totalBytes: page.totalBytes ?? page.scannedBytes,
+                    outputLines: page.outputLines,
+                    outputBytes: contentBytes,
+                    lastLinePartial: false,
+                    firstLineExceedsLimit: page.firstLineExceedsLimit,
+                    maxLines,
+                    maxBytes,
+                    totalLinesKnown: page.totalLines !== undefined,
+                    totalBytesKnown: page.totalBytes !== undefined,
+                };
+                let outputText = page.content;
+                if (page.firstLineExceedsLimit) {
+                    outputText = `[Line ${page.startLine} exceeds ${formatSize(maxBytes)} limit. Use the shell tool: sed -n '${page.startLine}p' ${path} | head -c ${maxBytes}]`;
                 }
-                else if (truncation.truncated) {
-                    const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
-                    const nextOffset = endLineDisplay + 1;
-                    outputText = truncation.content;
-                    if (truncation.truncatedBy === "lines") {
-                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
+                else if (page.hasMore && page.nextOffset !== undefined) {
+                    const endLine = page.startLine + page.outputLines - 1;
+                    if (page.totalLines !== undefined) {
+                        const remaining = page.totalLines - endLine;
+                        outputText += page.truncatedBy
+                            ? `\n\n[Showing lines ${page.startLine}-${endLine} of ${page.totalLines}${page.truncatedBy === "bytes" ? ` (${formatSize(maxBytes)} limit)` : ""}. Use offset=${page.nextOffset} to continue.]`
+                            : `\n\n[${remaining} more lines in file. Use offset=${page.nextOffset} to continue.]`;
                     }
                     else {
-                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
+                        outputText += `\n\n[Showing lines ${page.startLine}-${endLine}${page.truncatedBy === "bytes" ? ` (${formatSize(maxBytes)} limit)` : ""}. Use offset=${page.nextOffset} to continue.]`;
                     }
                 }
-                else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
-                    // User limit stopped early but the file has more content.
-                    const remaining = allLines.length - (startLine + userLimitedLines);
-                    const nextOffset = startLine + userLimitedLines + 1;
-                    outputText = `${truncation.content}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
-                }
-                else {
-                    outputText = truncation.content;
-                }
                 return {
                     toolCallId,
                     name: "read",
                     content: [{ type: "text", text: outputText }],
-                    metadata: { truncation },
+                    metadata: { truncation, scannedBytes: page.scannedBytes },
                 };
             }
             catch (error) {

package/dist/shell.d.ts

@@ -59,6 +59,10 @@ export interface ShellToolOptions {
     maxLines?: number;
     /** Max bytes kept in the tail snapshot (default 50KB). */
     maxBytes?: number;
+    /** Default wall timeout in seconds (default 600, hard cap 3600). */
+    timeout?: number;
+    /** Maximum combined raw stdout/stderr retained or spilled (default 64 MiB). */
+    maxTotalOutputBytes?: number;
     /** Temp-file prefix for spilled full output (default "prism-shell"). */
     tempFilePrefix?: string;
 }

package/dist/shell.js

@@ -25,7 +25,8 @@ import { constants, existsSync } from "node:fs";
 import { access as fsAccess } from "node:fs/promises";
 import { enforceExecutionPolicy } from "./execution-policy.js";
 import { OutputAccumulator } from "./output-accumulator.js";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "./truncate.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_MAX_TOTAL_OUTPUT_BYTES, DEFAULT_SHELL_TIMEOUT_SECONDS, HARD_MAX_BYTES, HARD_MAX_LINES, HARD_MAX_TOTAL_OUTPUT_BYTES, HARD_SHELL_TIMEOUT_SECONDS, validateCodingLimit, } from "./limits.js";
+import { formatSize } from "./truncate.js";
 const EXIT_STDIO_GRACE_MS = 100;
 // --- spawn internals (re-ported from pi utils/shell.js + utils/child-process.js) ---
 /** Resolve the shell binary + args. shellPath → SHELL env → /bin/bash → sh. */
@@ -160,6 +161,7 @@ export function waitForChildProcess(child) {
 export function createLocalBashOperations(options) {
     return {
         exec: async (command, cwd, { onData, signal, timeout, env }) => {
+            const timeoutSeconds = validateCodingLimit("timeout", timeout ?? DEFAULT_SHELL_TIMEOUT_SECONDS, HARD_SHELL_TIMEOUT_SECONDS);
             const shellConfig = getShellConfig(options?.shellPath);
             try {
                 await fsAccess(cwd, constants.F_OK);
@@ -184,13 +186,11 @@ export function createLocalBashOperations(options) {
                     killProcessTree(child.pid);
             };
             try {
-                if (timeout !== undefined && timeout > 0) {
-                    timeoutHandle = setTimeout(() => {
-                        timedOut = true;
-                        if (child.pid)
-                            killProcessTree(child.pid);
-                    }, timeout * 1000);
-                }
+                timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    if (child.pid)
+                        killProcessTree(child.pid);
+                }, timeoutSeconds * 1000);
                 child.stdout?.on("data", onData);
                 child.stderr?.on("data", onData);
                 if (signal) {
@@ -203,7 +203,7 @@ export function createLocalBashOperations(options) {
                 if (signal?.aborted)
                     throw new Error("aborted");
                 if (timedOut)
-                    throw new Error(`timeout:${timeout}`);
+                    throw new Error(`timeout:${timeoutSeconds}`);
                 return { exitCode };
             }
             finally {
@@ -224,13 +224,13 @@ function formatOutput(snapshot, lastLineBytes, emptyText = "(no output)") {
         const endLine = truncation.totalLines;
         if (truncation.lastLinePartial) {
             const lastLineSize = formatSize(lastLineBytes);
-            text += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). Full output: ${snapshot.fullOutputPath}]`;
+            text += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}).${snapshot.fullOutputPath ? ` Full output: ${snapshot.fullOutputPath}` : ""}]`;
         }
         else if (truncation.truncatedBy === "lines") {
-            text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${snapshot.fullOutputPath}]`;
+            text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}.${snapshot.fullOutputPath ? ` Full output: ${snapshot.fullOutputPath}` : ""}]`;
         }
         else {
-            text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(truncation.maxBytes)} limit). Full output: ${snapshot.fullOutputPath}]`;
+            text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(truncation.maxBytes)} limit).${snapshot.fullOutputPath ? ` Full output: ${snapshot.fullOutputPath}` : ""}]`;
         }
     }
     return { text, truncation, fullOutputPath: snapshot.fullOutputPath };
@@ -243,18 +243,22 @@ export function createShellTool(cwd, options) {
     const ops = options?.operations ?? createLocalBashOperations({ shellPath: options?.shellPath });
     const commandPrefix = options?.commandPrefix;
     const spawnHook = options?.spawnHook;
-    const maxLines = options?.maxLines ?? DEFAULT_MAX_LINES;
-    const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxLines = validateCodingLimit("maxLines", options?.maxLines ?? DEFAULT_MAX_LINES, HARD_MAX_LINES);
+    const maxBytes = validateCodingLimit("maxBytes", options?.maxBytes ?? DEFAULT_MAX_BYTES, HARD_MAX_BYTES);
+    const defaultTimeout = validateCodingLimit("timeout", options?.timeout ?? DEFAULT_SHELL_TIMEOUT_SECONDS, HARD_SHELL_TIMEOUT_SECONDS);
+    const maxTotalOutputBytes = validateCodingLimit("maxTotalOutputBytes", options?.maxTotalOutputBytes ?? DEFAULT_MAX_TOTAL_OUTPUT_BYTES, HARD_MAX_TOTAL_OUTPUT_BYTES);
+    if (maxTotalOutputBytes < maxBytes)
+        throw new Error("maxTotalOutputBytes must be at least maxBytes");
     const tempFilePrefix = options?.tempFilePrefix ?? "prism-shell";
     return {
         name: "shell",
         exclusive: true,
-        description: `Execute a shell command in the current working directory. Returns combined stdout and stderr. Output is truncated to the last ${maxLines} lines or ${maxBytes / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,
+        description: `Execute a shell command in the current working directory. Returns combined stdout and stderr. Output is truncated to the last ${maxLines} lines or ${maxBytes / 1024}KB and capped at ${formatSize(maxTotalOutputBytes)} total. Truncated successful output is saved to a temp file. Timeout defaults to ${defaultTimeout} seconds.`,
         parameters: {
             type: "object",
             properties: {
                 command: { type: "string", description: "Shell command to execute" },
-                timeout: { type: "number", description: "Timeout in seconds (optional, no default timeout)" },
+                timeout: { type: "number", description: `Timeout in seconds (default ${defaultTimeout}, max ${HARD_SHELL_TIMEOUT_SECONDS})` },
             },
             required: ["command"],
             additionalProperties: false,
@@ -262,7 +266,7 @@ export function createShellTool(cwd, options) {
         async execute(args, context) {
             const toolCallId = context.toolCallId;
             const command = typeof args.command === "string" ? args.command : "";
-            const timeout = typeof args.timeout === "number" ? args.timeout : undefined;
+            const timeoutInput = typeof args.timeout === "number" ? args.timeout : undefined;
             if (command.length === 0) {
                 return {
                     toolCallId,
@@ -271,6 +275,14 @@ export function createShellTool(cwd, options) {
                     error: { message: "command is required and must be a non-empty string." },
                 };
             }
+            let timeout;
+            try {
+                timeout = validateCodingLimit("timeout", timeoutInput ?? defaultTimeout, HARD_SHELL_TIMEOUT_SECONDS);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { toolCallId, name: "shell", content: [{ type: "text", text: message }], error: { message } };
+            }
             const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
             let spawnContext = spawnHook
                 ? spawnHook({ command: resolvedCommand, cwd, env: { ...process.env } })
@@ -288,77 +300,88 @@ export function createShellTool(cwd, options) {
             if (policyCheck.action.command) {
                 spawnContext = { ...spawnContext, command: policyCheck.action.command };
             }
-            const output = new OutputAccumulator({ maxLines, maxBytes, tempFilePrefix });
+            const outputAbort = new AbortController();
+            const output = new OutputAccumulator({
+                maxLines,
+                maxBytes,
+                maxTotalOutputBytes,
+                tempFilePrefix,
+                onLimit: () => outputAbort.abort("output-limit"),
+                onStorageError: () => outputAbort.abort("output-storage-error"),
+            });
+            const signal = context.signal
+                ? AbortSignal.any([context.signal, outputAbort.signal])
+                : outputAbort.signal;
             let acceptingOutput = true;
             const handleData = (data) => {
-                if (!acceptingOutput)
-                    return;
-                output.append(data);
+                if (acceptingOutput)
+                    output.append(data);
             };
-            const finishOutput = async () => {
+            const finishOutput = async (retainSpill) => {
                 acceptingOutput = false;
                 output.finish();
                 const snapshot = output.snapshot({ persistIfTruncated: true });
-                await output.closeTempFile();
-                return snapshot;
+                if (retainSpill) {
+                    await output.closeTempFile();
+                    return snapshot;
+                }
+                const hadStorageError = output.hasStorageError();
+                try {
+                    await output.cleanupTempFile();
+                }
+                catch (error) {
+                    if (!hadStorageError)
+                        throw error;
+                }
+                return { ...snapshot, fullOutputPath: undefined };
             };
-            // Safety net: never leak an unhandled throw to the host runtime.
             try {
-                let exitCode;
+                let exitCode = null;
+                let executionError;
                 try {
-                    const result = await ops.exec(spawnContext.command, spawnContext.cwd, {
+                    exitCode = (await ops.exec(spawnContext.command, spawnContext.cwd, {
                         onData: handleData,
-                        signal: context.signal,
+                        signal,
                         timeout,
                         env: spawnContext.env,
-                    });
-                    exitCode = result.exitCode;
+                    })).exitCode;
+                }
+                catch (error) {
+                    executionError = error;
                 }
-                catch (err) {
-                    const snapshot = await finishOutput();
+                if (executionError !== undefined || output.isOutputLimitExceeded() || output.hasStorageError() || context.signal?.aborted) {
+                    const outputLimitExceeded = output.isOutputLimitExceeded();
+                    const outputStorageFailed = output.hasStorageError();
+                    const snapshot = await finishOutput(false);
                     const { text } = formatOutput(snapshot, output.getLastLineBytes(), "");
-                    const message = err instanceof Error ? err.message : String(err);
-                    const meta = {
-                        exitCode: null,
-                        truncation: snapshot.truncation,
-                        fullOutputPath: snapshot.fullOutputPath,
-                    };
-                    if (message === "aborted") {
-                        return {
-                            toolCallId,
-                            name: "shell",
-                            content: [{ type: "text", text: appendStatus(text, "[Command aborted]") }],
-                            error: { message: "Command aborted" },
-                            metadata: meta,
-                        };
-                    }
-                    if (message.startsWith("timeout:")) {
-                        const timeoutSecs = message.split(":")[1];
-                        const status = `Command timed out after ${timeoutSecs} seconds`;
-                        return {
-                            toolCallId,
-                            name: "shell",
-                            content: [{ type: "text", text: appendStatus(text, `[${status}]`) }],
-                            error: { message: status },
-                            metadata: meta,
-                        };
-                    }
-                    // Spawn error (missing cwd, shell ENOENT, …): message is already host-friendly.
+                    const rawMessage = executionError instanceof Error ? executionError.message : String(executionError ?? "");
+                    const status = outputLimitExceeded
+                        ? `Command output exceeded ${formatSize(maxTotalOutputBytes)} limit`
+                        : outputStorageFailed
+                            ? "Command output spill failed"
+                            : rawMessage.startsWith("timeout:")
+                                ? `Command timed out after ${rawMessage.split(":")[1]} seconds`
+                                : context.signal?.aborted
+                                    ? "Command aborted"
+                                    : rawMessage || "Command failed";
                     return {
                         toolCallId,
                         name: "shell",
-                        content: [{ type: "text", text: appendStatus(text, message) }],
-                        error: { message },
-                        metadata: meta,
+                        content: [{ type: "text", text: appendStatus(text, `[${status}]`) }],
+                        error: { message: status },
+                        metadata: {
+                            exitCode: null,
+                            truncation: snapshot.truncation,
+                            totalOutputBytes: output.getTotalRawBytes(),
+                            outputLimitExceeded,
+                            outputStorageFailed,
+                        },
                     };
                 }
-                const snapshot = await finishOutput();
-                const formatted = formatOutput(snapshot, output.getLastLineBytes());
-                let text = formatted.text;
-                // Non-zero exit is not a tool error: surface exit code in a footer + metadata.
-                if (exitCode !== 0 && exitCode !== null) {
+                const snapshot = await finishOutput(true);
+                let text = formatOutput(snapshot, output.getLastLineBytes()).text;
+                if (exitCode !== 0 && exitCode !== null)
                     text = appendStatus(text, `[Command exited with code ${exitCode}]`);
-                }
                 return {
                     toolCallId,
                     name: "shell",
@@ -367,17 +390,18 @@ export function createShellTool(cwd, options) {
                         exitCode,
                         truncation: snapshot.truncation,
                         fullOutputPath: snapshot.fullOutputPath,
+                        totalOutputBytes: output.getTotalRawBytes(),
+                        outputLimitExceeded: false,
                     },
                 };
             }
             catch (err) {
+                try {
+                    await output.cleanupTempFile();
+                }
+                catch { /* retain primary error */ }
                 const message = err instanceof Error ? err.message : String(err);
-                return {
-                    toolCallId,
-                    name: "shell",
-                    content: [{ type: "text", text: message }],
-                    error: { message },
-                };
+                return { toolCallId, name: "shell", content: [{ type: "text", text: message }], error: { message } };
             }
         },
     };

package/dist/truncate.d.ts

@@ -9,8 +9,7 @@
  *
  * Never returns partial lines (except the documented tail single-line edge case).
  */
-export declare const DEFAULT_MAX_LINES = 2000;
-export declare const DEFAULT_MAX_BYTES: number;
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "./limits.js";
 export interface TruncationOptions {
     /** Maximum number of lines (default: 2000) */
     maxLines?: number;
@@ -24,10 +23,14 @@ export interface TruncationResult {
     truncated: boolean;
     /** Which limit was hit: "lines", "bytes", or null if not truncated */
     truncatedBy: "lines" | "bytes" | null;
-    /** Total number of lines in the original content */
+    /** Total lines when known; otherwise a scanned lower bound. */
     totalLines: number;
-    /** Total number of bytes in the original content */
+    /** Whether `totalLines` is exact (streamed text pages may stop early). */
+    totalLinesKnown?: boolean;
+    /** Total bytes when known; otherwise scanned bytes. */
     totalBytes: number;
+    /** Whether `totalBytes` is exact (streamed text pages may stop early). */
+    totalBytesKnown?: boolean;
     /** Number of complete lines in the truncated output */
     outputLines: number;
     /** Number of bytes in the truncated output */