@arnilo/prism-coding-agent 0.0.5 → 0.0.7

package/dist/output-accumulator.js

@@ -1,38 +1,25 @@
-/**
- * Streaming output accumulator with bounded memory.
- *
- * Behavioral port of pi's core/tools/output-accumulator for @arnilo/prism-coding-agent.
- * Appends raw chunks through a streaming UTF-8 decoder, keeps only a decoded tail
- * for display snapshots, and spills the full output to a temp file once limits are
- * exceeded. stdlib only (node:crypto/fs/os).
- *
- * Single deviation from pi: the default temp-file prefix is `prism-output`
- * (pi uses `pi-output`) — cosmetic, user-overridable via `tempFilePrefix`.
- */
+/** Streaming UTF-8 output retention with bounded memory and spill storage. */
 import { randomBytes } from "node:crypto";
-import { createWriteStream } from "node:fs";
+import { closeSync, openSync, writeSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateTail } from "./truncate.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_MAX_TOTAL_OUTPUT_BYTES, HARD_MAX_BYTES, HARD_MAX_LINES, HARD_MAX_TOTAL_OUTPUT_BYTES, validateCodingLimit, } from "./limits.js";
+import { truncateTail } from "./truncate.js";
 function defaultTempFilePath(prefix) {
-    const id = randomBytes(8).toString("hex");
-    return join(tmpdir(), `${prefix}-${id}.log`);
+    return join(tmpdir(), `${prefix}-${randomBytes(16).toString("hex")}.log`);
 }
 function byteLength(text) {
     return Buffer.byteLength(text, "utf-8");
 }
-/**
- * Incrementally tracks streaming output with bounded memory.
- *
- * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded
- * tail for display snapshots, and opens a temp file when the full output needs
- * to be preserved.
- */
 export class OutputAccumulator {
     maxLines;
     maxBytes;
+    maxTotalOutputBytes;
     maxRollingBytes;
     tempFilePrefix;
+    onLimit;
+    onStorageError;
     decoder = new TextDecoder();
     rawChunks = [];
     tailText = "";
@@ -45,99 +32,133 @@ export class OutputAccumulator {
     currentLineBytes = 0;
     hasOpenLine = false;
     finished = false;
+    exceeded = false;
     tempFilePath;
-    tempFileStream;
+    tempFileFd;
+    tempFileError;
     constructor(options = {}) {
-        this.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
-        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-        this.maxRollingBytes = Math.max(this.maxBytes * 2, 1);
+        this.maxLines = validateCodingLimit("maxLines", options.maxLines ?? DEFAULT_MAX_LINES, HARD_MAX_LINES);
+        this.maxBytes = validateCodingLimit("maxBytes", options.maxBytes ?? DEFAULT_MAX_BYTES, HARD_MAX_BYTES);
+        this.maxTotalOutputBytes = validateCodingLimit("maxTotalOutputBytes", options.maxTotalOutputBytes ?? DEFAULT_MAX_TOTAL_OUTPUT_BYTES, HARD_MAX_TOTAL_OUTPUT_BYTES);
+        if (this.maxTotalOutputBytes < this.maxBytes) {
+            throw new Error("maxTotalOutputBytes must be at least maxBytes");
+        }
+        this.maxRollingBytes = this.maxBytes * 2;
         this.tempFilePrefix = options.tempFilePrefix ?? "prism-output";
+        if (!/^[A-Za-z0-9._-]+$/.test(this.tempFilePrefix)) {
+            throw new Error("tempFilePrefix may contain only letters, numbers, dot, underscore, and hyphen");
+        }
+        this.onLimit = options.onLimit;
+        this.onStorageError = options.onStorageError;
     }
     append(data) {
-        if (this.finished) {
+        if (this.finished)
             throw new Error("Cannot append to a finished output accumulator");
-        }
-        this.totalRawBytes += data.length;
-        this.appendDecodedText(this.decoder.decode(data, { stream: true }));
-        if (this.tempFileStream || this.shouldUseTempFile()) {
-            this.ensureTempFile();
-            this.tempFileStream?.write(data);
-        }
-        else if (data.length > 0) {
-            this.rawChunks.push(data);
-        }
+        const remaining = this.maxTotalOutputBytes - this.totalRawBytes;
+        const accepted = remaining > 0 ? data.subarray(0, remaining) : data.subarray(0, 0);
+        if (accepted.length > 0) {
+            this.totalRawBytes += accepted.length;
+            this.appendDecodedText(this.decoder.decode(accepted, { stream: true }));
+            if (this.tempFileFd !== undefined || this.shouldUseTempFile()) {
+                this.ensureTempFile();
+                this.writeTemp(accepted);
+            }
+            else {
+                this.rawChunks.push(Buffer.from(accepted));
+            }
+        }
+        if (accepted.length !== data.length && !this.exceeded) {
+            this.exceeded = true;
+            this.onLimit?.();
+        }
+        return !this.exceeded;
     }
     finish() {
-        if (this.finished) {
+        if (this.finished)
             return;
-        }
         this.finished = true;
         this.appendDecodedText(this.decoder.decode());
-        if (this.shouldUseTempFile()) {
+        if (this.shouldUseTempFile())
             this.ensureTempFile();
-        }
     }
     snapshot(options = {}) {
         const tailTruncation = truncateTail(this.getSnapshotText(), {
             maxLines: this.maxLines,
             maxBytes: this.maxBytes,
         });
-        const truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes;
-        const truncatedBy = truncated
-            ? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes ? "bytes" : "lines"))
-            : null;
+        const truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes || this.exceeded;
         const truncation = {
             ...tailTruncation,
             truncated,
-            truncatedBy,
+            truncatedBy: truncated
+                ? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes || this.exceeded ? "bytes" : "lines"))
+                : null,
             totalLines: this.totalLines,
+            totalLinesKnown: true,
             totalBytes: this.totalDecodedBytes,
+            totalBytesKnown: !this.exceeded,
             maxLines: this.maxLines,
             maxBytes: this.maxBytes,
         };
-        if (options.persistIfTruncated && truncation.truncated) {
+        if (options.persistIfTruncated && truncation.truncated)
             this.ensureTempFile();
-        }
         return {
             content: truncation.content,
             truncation,
-            fullOutputPath: this.tempFilePath,
+            fullOutputPath: this.tempFileError ? undefined : this.tempFilePath,
         };
     }
     async closeTempFile() {
-        if (!this.tempFileStream) {
-            return;
-        }
-        const stream = this.tempFileStream;
-        this.tempFileStream = undefined;
-        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();
-        });
+        if (this.tempFileFd !== undefined) {
+            const fd = this.tempFileFd;
+            this.tempFileFd = undefined;
+            try {
+                closeSync(fd);
+            }
+            catch (error) {
+                this.recordTempError(error);
+            }
+        }
+        if (this.tempFileError)
+            throw this.tempFileError;
+    }
+    async cleanupTempFile() {
+        const path = this.tempFilePath;
+        let closeError;
+        try {
+            await this.closeTempFile();
+        }
+        catch (error) {
+            closeError = error;
+        }
+        this.tempFilePath = undefined;
+        this.tempFileError = undefined;
+        if (path)
+            await rm(path, { force: true });
+        if (closeError)
+            throw closeError;
     }
     getLastLineBytes() {
         return this.currentLineBytes;
     }
+    getTotalRawBytes() {
+        return this.totalRawBytes;
+    }
+    isOutputLimitExceeded() {
+        return this.exceeded;
+    }
+    hasStorageError() {
+        return this.tempFileError !== undefined;
+    }
     appendDecodedText(text) {
-        if (text.length === 0) {
+        if (text.length === 0)
             return;
-        }
         const bytes = byteLength(text);
         this.totalDecodedBytes += bytes;
         this.tailText += text;
         this.tailBytes += bytes;
-        if (this.tailBytes > this.maxRollingBytes * 2) {
+        if (this.tailBytes > this.maxRollingBytes * 2)
             this.trimTail();
-        }
         let newlines = 0;
         let lastNewline = -1;
         for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) {
@@ -163,36 +184,56 @@ export class OutputAccumulator {
             return;
         }
         let start = buffer.length - this.maxRollingBytes;
-        while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {
+        while (start < buffer.length && (buffer[start] & 0xc0) === 0x80)
             start++;
-        }
-        this.tailStartsAtLineBoundary =
-            start === 0 ? this.tailStartsAtLineBoundary : buffer[start - 1] === 0x0a;
+        this.tailStartsAtLineBoundary = start === 0 ? this.tailStartsAtLineBoundary : buffer[start - 1] === 0x0a;
         this.tailText = buffer.subarray(start).toString("utf-8");
         this.tailBytes = byteLength(this.tailText);
     }
     getSnapshotText() {
-        if (this.tailStartsAtLineBoundary) {
+        if (this.tailStartsAtLineBoundary)
             return this.tailText;
-        }
         const firstNewline = this.tailText.indexOf("\n");
         return firstNewline === -1 ? this.tailText : this.tailText.slice(firstNewline + 1);
     }
     shouldUseTempFile() {
-        return (this.totalRawBytes > this.maxBytes ||
-            this.totalDecodedBytes > this.maxBytes ||
-            this.totalLines > this.maxLines);
+        return this.totalRawBytes > this.maxBytes || this.totalDecodedBytes > this.maxBytes || this.totalLines > this.maxLines;
     }
     ensureTempFile() {
-        if (this.tempFilePath) {
+        if (this.tempFilePath || this.tempFileError)
             return;
+        const path = defaultTempFilePath(this.tempFilePrefix);
+        try {
+            this.tempFileFd = openSync(path, "wx", 0o600);
+            this.tempFilePath = path;
+            for (const chunk of this.rawChunks)
+                this.writeTemp(chunk);
+        }
+        catch (error) {
+            this.recordTempError(error);
         }
-        this.tempFilePath = defaultTempFilePath(this.tempFilePrefix);
-        this.tempFileStream = createWriteStream(this.tempFilePath);
-        for (const chunk of this.rawChunks) {
-            this.tempFileStream.write(chunk);
+        finally {
+            this.rawChunks = [];
         }
-        this.rawChunks = [];
+    }
+    writeTemp(data) {
+        // ponytail: synchronous spill is zero-queue backpressure; use a bounded async writer only if measured throughput requires it.
+        if (this.tempFileFd === undefined || this.tempFileError)
+            return;
+        try {
+            let offset = 0;
+            while (offset < data.length)
+                offset += writeSync(this.tempFileFd, data, offset);
+        }
+        catch (error) {
+            this.recordTempError(error);
+        }
+    }
+    recordTempError(error) {
+        if (this.tempFileError)
+            return;
+        this.tempFileError = error instanceof Error ? error : new Error(String(error));
+        this.onStorageError?.();
     }
 }
 //# sourceMappingURL=output-accumulator.js.map

package/dist/read.d.ts

@@ -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).
  *
@@ -27,7 +27,7 @@ export declare function detectSupportedImageMimeType(buffer: Buffer): string | n
 /** Sniff the leading bytes of a file and return its image MIME type (null if not a supported image). */
 export declare function detectSupportedImageMimeTypeFromFile(filePath: string): Promise<string | null>;
 /** Default maximum image file size before read/transform (10 MB). */
-export declare const DEFAULT_MAX_IMAGE_BYTES = 10000000;
+export { DEFAULT_MAX_IMAGE_BYTES } from "./limits.js";
 /** Input passed to an optional host-owned image transformer. */
 export interface TransformImageInput {
     readonly buffer: Buffer;
@@ -39,13 +39,42 @@ export type TransformImage = (input: TransformImageInput) => Promise<Buffer>;
  * Pluggable operations for the read tool. Override to delegate file reading to remote systems
  * (e.g. SSH) while keeping the tool's truncation/offset/limit behavior.
  */
+export interface ReadTextOptions {
+    readonly offset: number;
+    readonly limit?: number;
+    readonly maxLines: number;
+    readonly maxBytes: number;
+    readonly maxScanBytes: number;
+    readonly signal?: AbortSignal;
+}
+export interface ReadTextResult {
+    readonly content: string;
+    readonly startLine: number;
+    readonly outputLines: number;
+    readonly hasMore: boolean;
+    readonly nextOffset?: number;
+    readonly truncatedBy: "lines" | "bytes" | null;
+    readonly firstLineExceedsLimit: boolean;
+    readonly scannedBytes: number;
+    readonly totalLines?: number;
+    readonly totalBytes?: number;
+}
 export interface ReadOperations {
-    /** Read file contents as a Buffer. */
-    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Read a bounded binary file. Backends must honor `maxBytes` before retaining more data. */
+    readFile: (absolutePath: string, options: {
+        maxBytes: number;
+        signal?: AbortSignal;
+    }) => Promise<Buffer>;
+    /** Read one bounded text page. Required so remote backends cannot fall back to a full-file read. */
+    readText: (absolutePath: string, options: ReadTextOptions) => Promise<ReadTextResult>;
     /** Check the file is readable (throw if not). */
-    access: (absolutePath: string) => Promise<void>;
-    /** Return file size in bytes for image bound checks (default: local `fs.stat`). */
-    statFile?: (absolutePath: string) => Promise<{
+    access: (absolutePath: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    /** Return file size in bytes for image bound checks. */
+    statFile: (absolutePath: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
         size: number;
     }>;
     /** Detect image MIME type from the file; return null/undefined for non-images. */
@@ -61,6 +90,8 @@ export interface ReadToolOptions {
     autoResizeImages?: boolean;
     /** Reject image reads larger than this many bytes (default {@link DEFAULT_MAX_IMAGE_BYTES}). */
     maxImageBytes?: number;
+    /** Maximum raw bytes scanned to reach one text page (default 64 MiB). */
+    maxScanBytes?: number;
     /** Optional host callback to resize or re-encode images before base64 encoding. */
     transformImage?: TransformImage;
     /** Custom operations backend (default: local filesystem). */