@code-yeongyu/senpi 2026.11.15-2 → 2026.11.15-3

package/dist/core/tools/output-accumulator.js

@@ -1,286 +1,111 @@
-// allow: SIZE_OK - one cohesive streaming-output state machine owns decoding, truncation, spill, and terminal cleanup.
 import { randomBytes } from "node:crypto";
 import { createWriteStream } from "node:fs";
 import { open, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { TailWindow } from "./tail-window.js";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateTail } from "./truncate.js";
+import { OutputAccumulator as CoreOutputAccumulator, joinHeadAndTail, } from "./output-accumulator-core.js";
 function defaultTempFilePath(prefix) {
     const id = randomBytes(8).toString("hex");
     return join(tmpdir(), `${prefix}-${id}.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 {
-    constructor(options = {}) {
-        this.decoder = new TextDecoder();
-        this.rawChunks = [];
-        this.totalRawBytes = 0;
-        this.totalDecodedBytes = 0;
-        this.completedLines = 0;
-        this.totalLines = 0;
-        this.currentLineBytes = 0;
-        this.hasOpenLine = false;
-        this.finished = false;
-        this.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
-        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-        this.tempFilePrefix = options.tempFilePrefix ?? "pi-output";
-        this.tail = new TailWindow(Math.max(this.maxBytes * 2, 1));
-    }
-    append(data) {
-        if (this.finished) {
-            throw new Error("Cannot append to a finished output accumulator");
-        }
-        const text = this.decoder.decode(data, { stream: true });
-        this.totalRawBytes += data.length;
-        this.appendDecodedText(text, byteLength(text));
-        if (this.tempFileStream || this.shouldUseTempFile()) {
-            this.ensureTempFile();
-            this.tempFileStream?.write(data);
-        }
-        else if (data.length > 0) {
-            this.rawChunks.push(data);
-        }
-    }
-    appendText(text) {
-        if (this.finished) {
-            throw new Error("Cannot append to a finished output accumulator");
-        }
-        if (text.length === 0) {
-            return;
-        }
-        const bytes = byteLength(text);
-        this.totalRawBytes += bytes;
-        this.appendDecodedText(text, bytes);
-        if (this.tempFileStream || this.shouldUseTempFile()) {
-            this.ensureTempFile();
-            this.tempFileStream?.write(text);
-        }
-        else {
-            this.rawChunks.push(text);
-        }
-    }
-    finish() {
-        if (this.finished) {
-            return;
-        }
-        this.finished = true;
-        const finalText = this.decoder.decode();
-        this.appendDecodedText(finalText, byteLength(finalText));
-        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 truncation = {
-            ...tailTruncation,
-            truncated,
-            truncatedBy,
-            totalLines: this.totalLines,
-            totalBytes: this.totalDecodedBytes,
-            maxLines: this.maxLines,
-            maxBytes: this.maxBytes,
-        };
-        if (options.persistIfTruncated && truncation.truncated) {
-            this.ensureTempFile();
-        }
-        return {
-            content: truncation.content,
-            truncation,
-            fullOutputPath: this.tempFilePath,
-        };
-    }
-    async closeTempFile() {
-        const stream = this.takeTempFileStream();
-        if (!stream) {
+function destroyStream(stream) {
+    return new Promise((resolve) => {
+        if (stream.closed) {
+            resolve();
             return;
         }
-        if (this.tempFileError) {
-            await new Promise((resolve) => {
-                if (stream.closed) {
-                    resolve();
-                    return;
-                }
-                stream.once("close", resolve);
-                stream.destroy();
-            });
-            try {
-                await this.removeTempFile();
+        stream.once("close", resolve);
+        stream.destroy();
+    });
+}
+function endStream(stream) {
+    return new Promise((resolve, reject) => {
+        let finished = false;
+        let closed = false;
+        let streamError;
+        const settle = () => {
+            if (!closed) {
+                return;
             }
-            catch (unlinkError) {
-                throw new AggregateError([this.tempFileError, unlinkError], "Output spill cleanup failed");
+            stream.off("finish", onFinish);
+            stream.off("error", onError);
+            stream.off("close", onClose);
+            if (streamError) {
+                reject(streamError);
             }
-            throw this.tempFileError;
-        }
-        try {
-            await new Promise((resolve, reject) => {
-                let finished = false;
-                let closed = false;
-                let streamError;
-                const settle = () => {
-                    if (!closed) {
-                        return;
-                    }
-                    stream.off("finish", onFinish);
-                    stream.off("error", onError);
-                    stream.off("close", onClose);
-                    if (streamError) {
-                        reject(streamError);
-                    }
-                    else if (finished) {
-                        resolve();
-                    }
-                    else {
-                        reject(new Error("Output spill stream closed before finish"));
-                    }
-                };
-                const onError = (error) => {
-                    streamError ??= error;
-                };
-                const onFinish = () => {
-                    finished = true;
-                };
-                const onClose = () => {
-                    closed = true;
-                    if (!finished && !stream.destroyed) {
-                        stream.destroy();
-                    }
-                    settle();
-                };
-                stream.once("error", onError);
-                stream.once("finish", onFinish);
-                stream.once("close", onClose);
-                stream.end();
-            });
-        }
-        catch (error) {
-            try {
-                await this.removeTempFile();
+            else if (finished) {
+                resolve();
             }
-            catch (unlinkError) {
-                throw new AggregateError([error, unlinkError], "Output spill cleanup failed");
+            else {
+                reject(new Error("Output spill stream closed before finish"));
             }
-            throw error;
-        }
-    }
-    /**
-     * The complete output, for callers that can take more than the display snapshot. Call after
-     * `finish()` and `closeTempFile()`. Output longer than `maxBytes` raw bytes keeps its first and
-     * last `maxBytes / 2` bytes around an omission marker.
-     */
-    async readFullOutput(maxBytes) {
-        if (!this.tempFilePath) {
-            // Fork `appendText()` buffers strings beside raw chunks; encode them back before decoding the whole.
-            const chunks = this.rawChunks.map((chunk) => typeof chunk === "string" ? Buffer.from(chunk, "utf-8") : chunk);
-            return { content: new TextDecoder().decode(Buffer.concat(chunks)), truncated: false };
-        }
-        const file = await open(this.tempFilePath, "r");
-        try {
-            const size = (await file.stat()).size;
-            if (size <= maxBytes) {
-                return { content: new TextDecoder().decode(await file.readFile()), truncated: false };
+        };
+        const onError = (error) => {
+            streamError ??= error;
+        };
+        const onFinish = () => {
+            finished = true;
+        };
+        const onClose = () => {
+            closed = true;
+            if (!finished && !stream.destroyed) {
+                stream.destroy();
             }
-            const headBytes = Math.floor(maxBytes / 2);
-            const tailBytes = maxBytes - headBytes;
-            const head = Buffer.alloc(headBytes);
-            const tail = Buffer.alloc(tailBytes);
-            await file.read(head, 0, headBytes, 0);
-            await file.read(tail, 0, tailBytes, size - tailBytes);
-            // Cut at character boundaries: streaming decode holds back an incomplete trailing sequence,
-            // and the tail skips leading continuation bytes.
-            const headText = new TextDecoder().decode(head, { stream: true });
-            let tailStart = 0;
-            while (tailStart < tail.length && (tail[tailStart] & 0xc0) === 0x80)
-                tailStart++;
-            const tailText = new TextDecoder().decode(tail.subarray(tailStart));
-            const omitted = size - headBytes - tailBytes;
-            return { content: `${headText}\n\n[... ${omitted} bytes omitted ...]\n\n${tailText}`, truncated: true };
-        }
-        finally {
-            await file.close();
-        }
-    }
-    getLastLineBytes() {
-        return this.currentLineBytes;
-    }
-    appendDecodedText(text, bytes) {
-        if (text.length === 0) {
-            return;
-        }
-        this.totalDecodedBytes += bytes;
-        this.tail.append(text, bytes, !this.hasOpenLine);
-        let newlines = 0;
-        let lastNewline = -1;
-        for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) {
-            newlines++;
-            lastNewline = i;
-        }
-        if (newlines === 0) {
-            this.currentLineBytes += bytes;
-            this.hasOpenLine = true;
-        }
-        else {
-            this.completedLines += newlines;
-            const tail = text.slice(lastNewline + 1);
-            this.currentLineBytes = byteLength(tail);
-            this.hasOpenLine = tail.length > 0;
-        }
-        this.totalLines = this.completedLines + (this.hasOpenLine ? 1 : 0);
-    }
-    getSnapshotText() {
-        const text = this.tail.text();
-        if (this.tail.startsAtLineBoundary) {
-            return text;
-        }
-        const firstNewline = text.indexOf("\n");
-        return firstNewline === -1 ? text : text.slice(firstNewline + 1);
-    }
-    shouldUseTempFile() {
-        return (this.totalRawBytes > this.maxBytes || this.totalDecodedBytes > this.maxBytes || this.totalLines > this.maxLines);
-    }
-    ensureTempFile() {
-        if (this.tempFilePath) {
-            return;
-        }
-        this.tempFilePath = defaultTempFilePath(this.tempFilePrefix);
-        this.tempFileStream = createWriteStream(this.tempFilePath);
-        this.tempFileStream.on("error", (error) => {
-            this.tempFileError ??= error;
-        });
-        for (const chunk of this.rawChunks) {
-            this.tempFileStream.write(chunk);
-        }
-        this.rawChunks = [];
+            settle();
+        };
+        stream.once("error", onError);
+        stream.once("finish", onFinish);
+        stream.once("close", onClose);
+        stream.end();
+    });
+}
+async function readTempFile(path, maxBytes) {
+    const file = await open(path, "r");
+    try {
+        const size = (await file.stat()).size;
+        if (size <= maxBytes) {
+            return { content: new TextDecoder().decode(await file.readFile()), truncated: false };
+        }
+        const headBytes = Math.floor(maxBytes / 2);
+        const tailBytes = maxBytes - headBytes;
+        const head = Buffer.alloc(headBytes);
+        const tail = Buffer.alloc(tailBytes);
+        await file.read(head, 0, headBytes, 0);
+        await file.read(tail, 0, tailBytes, size - tailBytes);
+        return { content: joinHeadAndTail(head, tail, size - headBytes - tailBytes), truncated: true };
     }
-    async removeTempFile() {
-        if (!this.tempFilePath) {
-            return;
-        }
-        const path = this.tempFilePath;
-        await rm(path, { force: true });
-        this.tempFilePath = undefined;
+    finally {
+        await file.close();
     }
-    takeTempFileStream() {
-        const stream = this.tempFileStream;
-        this.tempFileStream = undefined;
-        return stream;
+}
+/** The local spill: a temp file under the OS temp directory, streamed as output arrives. */
+export const createTempFileSpill = (prefix) => {
+    const path = defaultTempFilePath(prefix);
+    const stream = createWriteStream(path);
+    let writeError;
+    stream.on("error", (error) => {
+        writeError ??= error;
+    });
+    return {
+        path,
+        write: (chunk) => {
+            stream.write(chunk);
+        },
+        close: async () => {
+            if (writeError) {
+                await destroyStream(stream);
+                throw writeError;
+            }
+            await endStream(stream);
+        },
+        remove: () => rm(path, { force: true }),
+        readFull: (maxBytes) => readTempFile(path, maxBytes),
+    };
+};
+/** The output accumulator of the local tools: it spills to a temp file unless the caller supplies a spill. */
+export class OutputAccumulator extends CoreOutputAccumulator {
+    constructor(options = {}) {
+        super({ ...options, spill: options.spill ?? createTempFileSpill });
     }
 }
 //# sourceMappingURL=output-accumulator.js.map

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

@@ -1,24 +1,7 @@
 import { accessSync, constants } from "node:fs";
 import { access } from "node:fs/promises";
 import { normalizePath, resolvePath } from "../../utils/paths.js";
-const NARROW_NO_BREAK_SPACE = "\u202F";
-function tryMacOSScreenshotPath(filePath) {
-    return filePath.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);
-}
-function tryNFDVariant(filePath) {
-    // macOS stores filenames in NFD (decomposed) form, try converting user input to NFD
-    return filePath.normalize("NFD");
-}
-function tryCurlyQuoteVariant(filePath) {
-    // macOS uses U+2019 (right single quotation mark) in screenshot names like "Capture d'écran"
-    // Users typically type U+0027 (straight apostrophe)
-    return filePath.replace(/'/g, "\u2019");
-}
-// Windows Explorer "Copy as path" wraps the path in double quotes (senpi#2170).
-function unquotedPath(filePath) {
-    const match = /^@?(["'])(.+)\1$/.exec(filePath.trim());
-    return match?.[2];
-}
+import { resolveReadPathVariants, tryCurlyQuoteVariant, tryMacOSScreenshotPath, tryNFDVariant, unquotedPath, } from "./file-tool-host.js";
 function fileExists(filePath) {
     try {
         accessSync(filePath, constants.F_OK);
@@ -78,35 +61,7 @@ export function resolveReadPath(filePath, cwd) {
     }
     return resolved;
 }
-export async function resolveReadPathAsync(filePath, cwd) {
-    const resolved = resolveToCwd(filePath, cwd);
-    if (await pathExists(resolved)) {
-        return resolved;
-    }
-    const unquoted = unquotedPath(filePath);
-    if (unquoted !== undefined) {
-        return resolveReadPathAsync(unquoted, cwd);
-    }
-    // Try macOS AM/PM variant (narrow no-break space before AM/PM)
-    const amPmVariant = tryMacOSScreenshotPath(resolved);
-    if (amPmVariant !== resolved && (await pathExists(amPmVariant))) {
-        return amPmVariant;
-    }
-    // Try NFD variant (macOS stores filenames in NFD form)
-    const nfdVariant = tryNFDVariant(resolved);
-    if (nfdVariant !== resolved && (await pathExists(nfdVariant))) {
-        return nfdVariant;
-    }
-    // Try curly quote variant (macOS uses U+2019 in screenshot names)
-    const curlyVariant = tryCurlyQuoteVariant(resolved);
-    if (curlyVariant !== resolved && (await pathExists(curlyVariant))) {
-        return curlyVariant;
-    }
-    // Try combined NFD + curly quote (for French macOS screenshots like "Capture d'écran")
-    const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
-    if (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant))) {
-        return nfdCurlyVariant;
-    }
-    return resolved;
+export function resolveReadPathAsync(filePath, cwd) {
+    return resolveReadPathVariants(filePath, cwd, resolveToCwd, pathExists);
 }
 //# sourceMappingURL=path-utils.js.map

package/dist/core/tools/posix-signals.d.ts

@@ -0,0 +1,3 @@
+/** The signal table of a machine's OS; an OS without its own table gets the common POSIX numbers. */
+export declare function posixSignalTable(os: string): Readonly<Record<string, number>>;
+//# sourceMappingURL=posix-signals.d.ts.map

package/dist/core/tools/posix-signals.js

@@ -0,0 +1,113 @@
+// Signal numbers by machine OS, for the 128 + n exit code of a signal-killed shell on a machine this process cannot
+// ask `os.constants.signals` about (test/tools-core/posix-signals.test.ts checks the host's table against Node's).
+// The table every OS got before the tables were split by OS; no OS may number fewer of these.
+const COMMON = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGILL: 4,
+    SIGTRAP: 5,
+    SIGABRT: 6,
+    SIGFPE: 8,
+    SIGKILL: 9,
+    SIGSEGV: 11,
+    SIGPIPE: 13,
+    SIGALRM: 14,
+    SIGTERM: 15,
+};
+const LINUX = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGILL: 4,
+    SIGTRAP: 5,
+    SIGABRT: 6,
+    SIGIOT: 6,
+    SIGBUS: 7,
+    SIGFPE: 8,
+    SIGKILL: 9,
+    SIGUSR1: 10,
+    SIGSEGV: 11,
+    SIGUSR2: 12,
+    SIGPIPE: 13,
+    SIGALRM: 14,
+    SIGTERM: 15,
+    SIGSTKFLT: 16,
+    SIGCHLD: 17,
+    SIGCONT: 18,
+    SIGSTOP: 19,
+    SIGTSTP: 20,
+    SIGTTIN: 21,
+    SIGTTOU: 22,
+    SIGURG: 23,
+    SIGXCPU: 24,
+    SIGXFSZ: 25,
+    SIGVTALRM: 26,
+    SIGPROF: 27,
+    SIGWINCH: 28,
+    SIGIO: 29,
+    SIGPOLL: 29,
+    SIGPWR: 30,
+    SIGSYS: 31,
+};
+// Darwin and the BSDs share this numbering.
+const BSD = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGILL: 4,
+    SIGTRAP: 5,
+    SIGABRT: 6,
+    SIGIOT: 6,
+    SIGEMT: 7,
+    SIGFPE: 8,
+    SIGKILL: 9,
+    SIGBUS: 10,
+    SIGSEGV: 11,
+    SIGSYS: 12,
+    SIGPIPE: 13,
+    SIGALRM: 14,
+    SIGTERM: 15,
+    SIGURG: 16,
+    SIGSTOP: 17,
+    SIGTSTP: 18,
+    SIGCONT: 19,
+    SIGCHLD: 20,
+    SIGTTIN: 21,
+    SIGTTOU: 22,
+    SIGIO: 23,
+    SIGXCPU: 24,
+    SIGXFSZ: 25,
+    SIGVTALRM: 26,
+    SIGPROF: 27,
+    SIGWINCH: 28,
+    SIGINFO: 29,
+    SIGUSR1: 30,
+    SIGUSR2: 31,
+};
+// Node's win32 numbers (libuv), over COMMON for the names Node does not define there.
+const WIN32 = {
+    ...COMMON,
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGILL: 4,
+    SIGABRT: 22,
+    SIGFPE: 8,
+    SIGKILL: 9,
+    SIGSEGV: 11,
+    SIGTERM: 15,
+    SIGBREAK: 21,
+    SIGWINCH: 28,
+};
+const BSD_FAMILY = new Set(["darwin", "freebsd", "openbsd", "netbsd", "dragonfly"]);
+/** The signal table of a machine's OS; an OS without its own table gets the common POSIX numbers. */
+export function posixSignalTable(os) {
+    if (os === "linux" || os === "android")
+        return LINUX;
+    if (BSD_FAMILY.has(os))
+        return BSD;
+    if (os === "win32")
+        return WIN32;
+    return COMMON;
+}
+//# sourceMappingURL=posix-signals.js.map

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

@@ -0,0 +1,64 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type ReadFolder } from "@earendil-works/pi-agent-core/read-folders";
+import type { ModelImageResizeOptions } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+import type { ProcessImageOptions, ProcessImageResult } from "../../utils/image-process.ts";
+import type { FilesystemPolicyChecker, ToolDefinition } from "../extensions/types.ts";
+import { type ToolPathCanonicalizer } from "./file-tool-host.ts";
+import type { ToolMachine } from "./tool-machine.ts";
+import { type ReadToolDetails } from "./read-text.ts";
+declare const readSchema: Type.TObject<{
+    path: Type.TString;
+    offset: Type.TOptional<Type.TNumber>;
+    limit: Type.TOptional<Type.TNumber>;
+}>;
+export declare const readToolSystemPromptContribution: {
+    readonly snippet: "Read file contents";
+    readonly guidelines: readonly ["Files: read, not cat/sed."];
+    readonly fullGuidelines: readonly ["Use read to examine files instead of cat or sed."];
+};
+export type ReadToolInput = Static<typeof readSchema>;
+export type { ReadToolDetails } from "./read-text.ts";
+/**
+ * Pluggable operations for the read tool.
+ * Override these to delegate file reading to remote systems (for example SSH).
+ */
+export interface ReadOperations {
+    /** Read file contents */
+    readFile: (absolutePath: string) => Promise<Uint8Array>;
+    /** Check if file is readable (throw if not) */
+    access: (absolutePath: string) => Promise<void>;
+    /** Detect image MIME type, return null or undefined for non-images */
+    detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+}
+/** Turns an image file's bytes into the inline image the model receives, or a note why it cannot. */
+export type ReadImageProcessor = (bytes: Uint8Array, mimeType: string, options: ProcessImageOptions) => Promise<ProcessImageResult>;
+export interface CoreReadToolOptions {
+    /** Operation layer and policy gate. */
+    machine: ToolMachine;
+    /** Structural folder. Default options select the measured folder; omit here for verbatim reads. */
+    folder?: ReadFolder;
+    /** Whether to auto-resize images. Default: true */
+    autoResizeImages?: boolean;
+    /** Fallback resize profile when the execution context has no model metadata. */
+    resizeOptions?: ModelImageResizeOptions;
+    /** Read the model from the execution context. False for a runtime without a session, whose context refuses `model` (senpi#5223). Default: true */
+    contextModel?: boolean;
+    /** Custom operations for file reading. Default: reads through `machine` */
+    operations?: ReadOperations;
+    /** Extension-registered filesystem policy checker. */
+    filesystemPolicy?: FilesystemPolicyChecker;
+    /** Resolves the model's path, trying spelling variants. Default: POSIX resolution, variants probed on `machine`. */
+    resolveReadPath?: (path: string, cwd: string) => Promise<string>;
+    /** The path `filesystemPolicy` judges. Default: the resolved path as is. */
+    canonicalizePath?: ToolPathCanonicalizer;
+    /** Image detection for the default operations. Default: the file's leading bytes read on `machine`. */
+    detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+    /** Default: inline PNG, JPEG, GIF and WebP as they are; other formats are omitted with a note. */
+    processImage?: ReadImageProcessor;
+}
+export declare function createCoreReadToolDefinition(cwd: string, options: CoreReadToolOptions): ToolDefinition<typeof readSchema, ReadToolDetails | undefined>;
+/** The read tool for a host whose only effect channel is `machine`; reads fold like the local tool's by default. */
+export declare function createCoreReadTool(cwd: string, options: CoreReadToolOptions): AgentTool<typeof readSchema>;
+export { readSchema };
+//# sourceMappingURL=read-core.d.ts.map