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

package/dist/core/tools/shell-operations.d.ts

@@ -0,0 +1,53 @@
+import type { ExecShell } from "../../../vendor/senpi-machine-ops/index.js";
+import type { ToolMachine } from "./tool-machine.ts";
+/**
+ * Pluggable operations for the bash tool.
+ * Override these to delegate command execution to remote systems (for example SSH).
+ */
+export interface BashOperations {
+    /**
+     * Execute a command and stream output.
+     * @param command The command to execute
+     * @param cwd Working directory
+     * @param options Execution options
+     * @returns Promise resolving to the exit code. Report signal terminations as 128 + signal number;
+     * a null exit code is treated as a failed command.
+     */
+    exec: (command: string, cwd: string, options: {
+        onData: (data: Buffer, stream?: "stdout" | "stderr") => void;
+        signal?: AbortSignal;
+        timeout?: number;
+        env?: NodeJS.ProcessEnv;
+        redactSecretsInOutput?: boolean;
+    }) => Promise<{
+        exitCode: number | null;
+    }>;
+}
+/** What a shell run needs from the host it runs for: the shell, the cwd check, the environment and pid tracking. */
+export interface ShellExecHost {
+    /** The shell the command runs in; undefined lets the machine choose (`/bin/sh -c` on POSIX). */
+    resolveShell(): ExecShell | undefined;
+    /** Rejects when `cwd` does not exist where the command runs. */
+    checkCwd(cwd: string, signal: AbortSignal | undefined): Promise<void>;
+    /** "exact" runs with the tool's environment alone; "overlay" lays it over the machine's curated base. */
+    readonly envMode: "exact" | "overlay";
+    /** The environment when the caller passes none. */
+    defaultEnv(): NodeJS.ProcessEnv | undefined;
+    /** The number of a terminating signal, for the 128 + n exit code. */
+    signalNumber(signal: string): number | undefined;
+    onSpawn?(pid: number): void;
+    onExit?(pid: number): void;
+    /** Runs once the exec settles, success or not. */
+    afterExec?(): void;
+}
+/**
+ * A host that knows only the tool machine: the machine's shell and environment, the cwd checked there, and the signal
+ * numbers of the machine's own OS.
+ */
+export declare function machineShellExecHost(machine: ToolMachine, shell?: ExecShell): ShellExecHost;
+/**
+ * Shell execution used by the built-in shell tools: one `process.exec` of the operation layer (own process group,
+ * abort/timeout kill the group). The tool keeps its own output handling.
+ */
+export declare function createShellOperations(shellName: string, machine: ToolMachine, host: ShellExecHost): BashOperations;
+//# sourceMappingURL=shell-operations.d.ts.map

package/dist/core/tools/shell-operations.js

@@ -0,0 +1,115 @@
+import { posixSignalTable } from "./posix-signals.js";
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1000;
+function resolveTimeoutMs(timeout) {
+    if (timeout === undefined)
+        return undefined;
+    if (!Number.isFinite(timeout) || timeout <= 0) {
+        throw new Error("Invalid timeout: must be a finite number of seconds");
+    }
+    const timeoutMs = timeout * 1000;
+    if (timeoutMs > MAX_TIMEOUT_MS) {
+        throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
+    }
+    return timeoutMs;
+}
+/**
+ * A host that knows only the tool machine: the machine's shell and environment, the cwd checked there, and the signal
+ * numbers of the machine's own OS.
+ */
+export function machineShellExecHost(machine, shell) {
+    return {
+        resolveShell: () => shell,
+        checkCwd: async (cwd, signal) => {
+            await machine.ops.files.stat({ path: cwd }, machine.context(signal));
+        },
+        envMode: "overlay",
+        defaultEnv: () => undefined,
+        signalNumber: (signal) => posixSignalTable(machine.ops.info.host().os)[signal],
+    };
+}
+/**
+ * Shell execution used by the built-in shell tools: one `process.exec` of the operation layer (own process group,
+ * abort/timeout kill the group). The tool keeps its own output handling.
+ */
+export function createShellOperations(shellName, machine, host) {
+    return {
+        exec: async (command, cwd, { onData, signal, timeout, env }) => {
+            const timeoutMs = resolveTimeoutMs(timeout);
+            if (signal?.aborted) {
+                throw new Error("aborted");
+            }
+            const shell = host.resolveShell();
+            try {
+                await host.checkCwd(cwd, signal);
+            }
+            catch {
+                throw new Error(`Working directory does not exist: ${cwd}\nCannot execute ${shellName} commands.`);
+            }
+            let streamCallbackError;
+            let hasStreamCallbackError = false;
+            // A failing output callback stops the command the same way an abort does.
+            const callbackAbort = new AbortController();
+            const failStream = (error) => {
+                if (hasStreamCallbackError)
+                    return;
+                streamCallbackError = error;
+                hasStreamCallbackError = true;
+                callbackAbort.abort();
+            };
+            const handleData = (data, stream) => {
+                if (hasStreamCallbackError)
+                    return;
+                try {
+                    const callbackResult = onData(data, stream);
+                    if (callbackResult && typeof callbackResult.then === "function") {
+                        void Promise.resolve(callbackResult).catch(failStream);
+                    }
+                }
+                catch (error) {
+                    failStream(error);
+                }
+            };
+            const execSignal = signal ? AbortSignal.any([signal, callbackAbort.signal]) : callbackAbort.signal;
+            let result;
+            try {
+                result = await machine.ops.process.exec({
+                    command,
+                    cwd,
+                    env: env ?? host.defaultEnv(),
+                    envMode: host.envMode,
+                    ...(shell !== undefined ? { shell } : {}),
+                    timeoutMs: timeoutMs ?? Number.POSITIVE_INFINITY,
+                    onOutput: handleData,
+                    ...(host.onSpawn !== undefined ? { onSpawn: host.onSpawn } : {}),
+                    ...(host.onExit !== undefined ? { onExit: host.onExit } : {}),
+                }, machine.context(execSignal));
+            }
+            catch (error) {
+                if (hasStreamCallbackError)
+                    throw streamCallbackError;
+                if (signal?.aborted)
+                    throw new Error("aborted");
+                throw error;
+            }
+            finally {
+                host.afterExec?.();
+            }
+            if (hasStreamCallbackError) {
+                throw streamCallbackError;
+            }
+            if (signal?.aborted) {
+                throw new Error("aborted");
+            }
+            if (result.timedOut) {
+                throw new Error(`timeout:${timeout}`);
+            }
+            // A signal-killed shell has no exit code. Use the standard shell convention so
+            // callers do not mistake the termination for a successful command.
+            return {
+                exitCode: result.exitCode ?? (result.signal ? 128 + (host.signalNumber(result.signal) ?? 0) : 1),
+            };
+        },
+    };
+}
+//# sourceMappingURL=shell-operations.js.map

package/dist/core/tools/shell-output.d.ts

@@ -0,0 +1,20 @@
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
+import type { TextContent } from "@earendil-works/pi-ai";
+import type { BashToolDetails } from "./bash-schema.ts";
+import type { OutputAccumulator, OutputSnapshot } from "./output-accumulator-core.ts";
+export interface FormattedShellOutput {
+    text: string;
+    content: TextContent[];
+    details: BashToolDetails | undefined;
+}
+/**
+ * One shell run's output stream: optional secret redaction per stream, throttled partial updates, and the terminal
+ * flush that settles the spill before the result is built.
+ */
+export declare function createShellOutput(output: OutputAccumulator, onUpdate: AgentToolUpdateCallback<BashToolDetails | undefined> | undefined, redactSecretsInOutput: boolean): {
+    handleData: (data: Uint8Array, stream?: string) => void;
+    finishOutput: () => Promise<OutputSnapshot>;
+    formatOutput: (snapshot: OutputSnapshot, emptyText?: string) => FormattedShellOutput;
+    clearUpdateTimer: () => void;
+};
+//# sourceMappingURL=shell-output.d.ts.map

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

@@ -0,0 +1,152 @@
+import { modelOnlyText } from "./model-only-text.js";
+import { SecretOutputRedactor } from "./secret-output-redactor.js";
+import { DEFAULT_MAX_BYTES, formatSize } from "./truncate.js";
+const BASH_UPDATE_THROTTLE_MS = 100;
+/**
+ * One shell run's output stream: optional secret redaction per stream, throttled partial updates, and the terminal
+ * flush that settles the spill before the result is built.
+ */
+export function createShellOutput(output, onUpdate, redactSecretsInOutput) {
+    const streams = redactSecretsInOutput
+        ? new Map()
+        : undefined;
+    let acceptingOutput = true;
+    let updateTimer;
+    let updateDirty = false;
+    let lastUpdateAt = 0;
+    let outputUpdateError;
+    let hasOutputUpdateError = false;
+    const emitOutputUpdate = () => {
+        if (!onUpdate || !updateDirty || hasOutputUpdateError)
+            return;
+        updateDirty = false;
+        lastUpdateAt = Date.now();
+        const snapshot = output.snapshot({ persistIfTruncated: true });
+        try {
+            onUpdate({
+                content: [{ type: "text", text: snapshot.content || "" }],
+                details: {
+                    truncation: snapshot.truncation.truncated ? snapshot.truncation : undefined,
+                    fullOutputPath: snapshot.fullOutputPath,
+                },
+            });
+        }
+        catch (error) {
+            outputUpdateError = error;
+            hasOutputUpdateError = true;
+        }
+    };
+    const clearUpdateTimer = () => {
+        if (updateTimer) {
+            clearTimeout(updateTimer);
+            updateTimer = undefined;
+        }
+    };
+    const scheduleOutputUpdate = () => {
+        if (!onUpdate)
+            return;
+        updateDirty = true;
+        const delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);
+        if (delay <= 0) {
+            clearUpdateTimer();
+            emitOutputUpdate();
+            return;
+        }
+        updateTimer ??= setTimeout(() => {
+            updateTimer = undefined;
+            emitOutputUpdate();
+        }, delay);
+    };
+    const handleData = (data, stream = "stdout") => {
+        if (!acceptingOutput)
+            return;
+        if (streams) {
+            let state = streams.get(stream);
+            if (!state) {
+                state = { redactor: new SecretOutputRedactor(), decoder: new TextDecoder() };
+                streams.set(stream, state);
+            }
+            output.appendText(state.redactor.push(state.decoder.decode(data, { stream: true })));
+        }
+        else
+            output.append(data);
+        scheduleOutputUpdate();
+    };
+    const finishOutput = async () => {
+        acceptingOutput = false;
+        clearUpdateTimer();
+        let primaryError;
+        let hasPrimaryError = false;
+        let snapshot;
+        try {
+            if (streams) {
+                for (const { redactor, decoder } of streams.values()) {
+                    output.appendText(redactor.push(decoder.decode()) + redactor.finish());
+                }
+                updateDirty = true;
+            }
+            output.finish();
+            emitOutputUpdate();
+            snapshot = output.snapshot({ persistIfTruncated: true });
+            if (hasOutputUpdateError) {
+                primaryError = outputUpdateError;
+                hasPrimaryError = true;
+            }
+        }
+        catch (error) {
+            primaryError = error;
+            hasPrimaryError = true;
+        }
+        try {
+            await output.closeTempFile();
+        }
+        catch (closeError) {
+            if (hasPrimaryError) {
+                throw new AggregateError([primaryError, closeError], "Bash output finalization and spill cleanup failed");
+            }
+            throw closeError;
+        }
+        if (hasPrimaryError) {
+            try {
+                await output.removeTempFile();
+            }
+            catch (unlinkError) {
+                if (!(unlinkError instanceof Error))
+                    throw unlinkError;
+                throw new AggregateError([primaryError, unlinkError], "Bash output finalization and spill cleanup failed");
+            }
+            throw primaryError;
+        }
+        if (snapshot === undefined) {
+            throw new Error("Bash output finalization produced no snapshot");
+        }
+        return snapshot;
+    };
+    const formatOutput = (snapshot, emptyText = "(no output)") => {
+        const truncation = snapshot.truncation;
+        const text = snapshot.content || emptyText;
+        let notice;
+        let details;
+        if (truncation.truncated) {
+            details = { truncation, fullOutputPath: snapshot.fullOutputPath };
+            const startLine = truncation.totalLines - truncation.outputLines + 1;
+            const endLine = truncation.totalLines;
+            if (truncation.lastLinePartial) {
+                const lastLineSize = formatSize(output.getLastLineBytes());
+                notice = `[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). Full output: ${snapshot.fullOutputPath}]`;
+            }
+            else if (truncation.truncatedBy === "lines") {
+                notice = `[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${snapshot.fullOutputPath}]`;
+            }
+            else {
+                notice = `[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${snapshot.fullOutputPath}]`;
+            }
+        }
+        const content = [{ type: "text", text: notice === undefined ? text : `${text}\n` }];
+        if (notice !== undefined)
+            content.push(modelOnlyText(notice));
+        return { text: notice === undefined ? text : `${text}\n\n${notice}`, content, details };
+    };
+    return { handleData, finishOutput, formatOutput, clearUpdateTimer };
+}
+//# sourceMappingURL=shell-output.js.map

package/dist/core/tools/tail-window.js

@@ -1,7 +1,5 @@
+import { decodeUtf8, encodeUtf8, utf8ByteLength as byteLength } from "./encoding.js";
 const MAX_PENDING_TAIL_CHUNKS = 10;
-function byteLength(text) {
-    return Buffer.byteLength(text, "utf-8");
-}
 export class TailWindow {
     constructor(maxBytes) {
         this.chunks = [];
@@ -34,13 +32,13 @@ export class TailWindow {
         return this.startsAtBoundary;
     }
     replaceWithTail(text, startsAtLineBoundary) {
-        const buffer = Buffer.from(text, "utf-8");
+        const buffer = encodeUtf8(text);
         let start = Math.max(0, buffer.length - this.maxBytes);
         while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {
             start++;
         }
         this.startsAtBoundary = start === 0 ? startsAtLineBoundary : buffer[start - 1] === 0x0a;
-        const tail = buffer.subarray(start).toString("utf-8");
+        const tail = decodeUtf8(buffer.subarray(start));
         this.chunks = tail.length > 0 ? [tail] : [];
         this.bytes = byteLength(tail);
     }
@@ -61,13 +59,13 @@ export class TailWindow {
         if (this.bytes <= this.maxBytes) {
             return;
         }
-        const buffer = Buffer.from(this.joined(), "utf-8");
+        const buffer = encodeUtf8(this.joined());
         let start = Math.max(0, buffer.length - this.maxBytes);
         while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {
             start++;
         }
         this.startsAtBoundary = start === 0 ? this.startsAtBoundary : buffer[start - 1] === 0x0a;
-        const tail = buffer.subarray(start).toString("utf-8");
+        const tail = decodeUtf8(buffer.subarray(start));
         this.chunks = tail.length > 0 ? [tail] : [];
         this.bytes = byteLength(tail);
     }

package/dist/core/tools/tool-machine.d.ts

@@ -0,0 +1,30 @@
+import type { MachineOps, OpContext, OpName, PolicyHooks } from "../../../vendor/senpi-machine-ops/index.js";
+/**
+ * The hooks the tool path honours: only `beforeOp`, once per tool call. The tools run the extension filesystem policy
+ * themselves and sub-operations carry no hooks, so `filesystem` and `afterOp` are rejected at compile time instead of
+ * being silently ignored.
+ */
+export type ToolPathPolicy = Pick<PolicyHooks, "beforeOp"> & {
+    readonly filesystem?: never;
+    readonly afterOp?: never;
+};
+/** One MachineOps bound to the tool path: principal `local-session`, no scope root (the tools resolve paths). */
+export interface ToolMachine {
+    readonly ops: MachineOps;
+    /**
+     * Runs `PolicyHooks.beforeOp` once for one tool call; a denial rejects with `Error(reason)` before any effect.
+     * Without a `beforeOp` it returns undefined synchronously, so a tool that awaits only a returned promise keeps
+     * its exact pre-layer timing (bash emits its first partial update before any await).
+     */
+    begin(op: OpName, args: unknown, signal: AbortSignal | undefined): Promise<void> | undefined;
+    /** Context for a sub-operation inside a call `begin` already admitted. */
+    context(signal: AbortSignal | undefined, pathLock?: "caller"): OpContext;
+}
+/** Binds the tool path to the MachineOps `resolveOps` returns, read on every use. */
+export declare function bindToolMachine(resolveOps: () => MachineOps, policy?: ToolPathPolicy): ToolMachine;
+/** A ToolMachine over a host-supplied MachineOps (a remote device, a sandbox): the tools' only effect channel. */
+export declare function createToolMachine(options: {
+    ops: MachineOps;
+    policy?: ToolPathPolicy;
+}): ToolMachine;
+//# sourceMappingURL=tool-machine.d.ts.map

package/dist/core/tools/tool-machine.js

@@ -0,0 +1,47 @@
+/**
+ * Tool-path limits over the machine's own defaults. The tools keep their own truncation (truncate.ts, the output
+ * accumulator), so the operation layer reads files whole and streams exec output uncaptured.
+ */
+function toolPathLimits(machineLimits) {
+    return {
+        ...machineLimits,
+        readMaxBytes: Number.POSITIVE_INFINITY,
+        execStdoutMaxBytes: 0,
+        execStderrMaxBytes: 0,
+        execTimeoutDefaultMs: Number.POSITIVE_INFINITY,
+    };
+}
+const NEVER_ABORTED = new AbortController().signal;
+/** Binds the tool path to the MachineOps `resolveOps` returns, read on every use. */
+export function bindToolMachine(resolveOps, policy) {
+    const context = (signal, pathLock) => ({
+        scope: { id: "local-session" },
+        principal: { kind: "local-session", id: "local-session" },
+        signal: signal ?? NEVER_ABORTED,
+        limits: toolPathLimits(resolveOps().limits),
+        // The tools run the extension filesystem policy themselves (with their own error text) and the gate below
+        // already ran once for the call, so sub-operations carry no hooks.
+        policy: {},
+        ...(pathLock !== undefined ? { pathLock } : {}),
+    });
+    return {
+        get ops() {
+            return resolveOps();
+        },
+        begin(op, args, signal) {
+            const beforeOp = policy?.beforeOp;
+            if (beforeOp === undefined)
+                return undefined;
+            return beforeOp(op, args, { ...context(signal), policy: policy ?? {} }).then((decision) => {
+                if (!decision.allow)
+                    throw new Error(decision.reason);
+            });
+        },
+        context,
+    };
+}
+/** A ToolMachine over a host-supplied MachineOps (a remote device, a sandbox): the tools' only effect channel. */
+export function createToolMachine(options) {
+    return bindToolMachine(() => options.ops, options.policy);
+}
+//# sourceMappingURL=tool-machine.js.map

package/dist/core/tools/truncate.js

@@ -7,6 +7,7 @@
  *
  * Never returns partial lines (except bash tail truncation edge case).
  */
+import { decodeUtf8, encodeUtf8, utf8ByteLength } from "./encoding.js";
 export const DEFAULT_MAX_LINES = 2000;
 export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
 export const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line
@@ -44,7 +45,7 @@ export function formatSize(bytes) {
 export function truncateHead(content, options = {}) {
     const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
     const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-    const totalBytes = Buffer.byteLength(content, "utf-8");
+    const totalBytes = utf8ByteLength(content);
     const lines = splitLinesForCounting(content);
     const totalLines = lines.length;
     // Check if no truncation needed
@@ -64,7 +65,7 @@ export function truncateHead(content, options = {}) {
         };
     }
     // Check if first line alone exceeds byte limit
-    const firstLineBytes = Buffer.byteLength(lines[0], "utf-8");
+    const firstLineBytes = utf8ByteLength(lines[0]);
     if (firstLineBytes > maxBytes) {
         return {
             content: "",
@@ -86,7 +87,7 @@ export function truncateHead(content, options = {}) {
     let truncatedBy = "lines";
     for (let i = 0; i < lines.length && i < maxLines; i++) {
         const line = lines[i];
-        const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0); // +1 for newline
+        const lineBytes = utf8ByteLength(line) + (i > 0 ? 1 : 0); // +1 for newline
         if (outputBytesCount + lineBytes > maxBytes) {
             truncatedBy = "bytes";
             break;
@@ -99,7 +100,7 @@ export function truncateHead(content, options = {}) {
         truncatedBy = "lines";
     }
     const outputContent = outputLinesArr.join("\n");
-    const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+    const finalOutputBytes = utf8ByteLength(outputContent);
     return {
         content: outputContent,
         truncated: true,
@@ -123,7 +124,7 @@ export function truncateHead(content, options = {}) {
 export function truncateTail(content, options = {}) {
     const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
     const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-    const totalBytes = Buffer.byteLength(content, "utf-8");
+    const totalBytes = utf8ByteLength(content);
     const lines = splitLinesForCounting(content);
     const totalLines = lines.length;
     // Check if no truncation needed
@@ -149,7 +150,7 @@ export function truncateTail(content, options = {}) {
     let lastLinePartial = false;
     for (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {
         const line = lines[i];
-        const lineBytes = Buffer.byteLength(line, "utf-8") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline
+        const lineBytes = utf8ByteLength(line) + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline
         if (outputBytesCount + lineBytes > maxBytes) {
             truncatedBy = "bytes";
             // Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,
@@ -157,7 +158,7 @@ export function truncateTail(content, options = {}) {
             if (outputLinesArr.length === 0) {
                 const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);
                 outputLinesArr.unshift(truncatedLine);
-                outputBytesCount = Buffer.byteLength(truncatedLine, "utf-8");
+                outputBytesCount = utf8ByteLength(truncatedLine);
                 lastLinePartial = true;
             }
             break;
@@ -170,7 +171,7 @@ export function truncateTail(content, options = {}) {
         truncatedBy = "lines";
     }
     const outputContent = outputLinesArr.join("\n");
-    const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+    const finalOutputBytes = utf8ByteLength(outputContent);
     return {
         content: outputContent,
         truncated: true,
@@ -190,7 +191,7 @@ export function truncateTail(content, options = {}) {
  * Handles multi-byte UTF-8 characters correctly.
  */
 function truncateStringToBytesFromEnd(str, maxBytes) {
-    const buf = Buffer.from(str, "utf-8");
+    const buf = encodeUtf8(str);
     if (buf.length <= maxBytes) {
         return str;
     }
@@ -200,7 +201,7 @@ function truncateStringToBytesFromEnd(str, maxBytes) {
     while (start < buf.length && (buf[start] & 0xc0) === 0x80) {
         start++;
     }
-    return buf.slice(start).toString("utf-8");
+    return decodeUtf8(buf.slice(start));
 }
 /**
  * Truncate a single line to max characters, adding [truncated] suffix.
@@ -217,7 +218,7 @@ export function truncateLine(line, maxChars = GREP_MAX_LINE_LENGTH) {
  * `…N chars truncated…` marker, like Codex does for tool output. Cuts only at character boundaries.
  */
 export function truncateMiddle(content, maxBytes) {
-    const buf = Buffer.from(content, "utf-8");
+    const buf = encodeUtf8(content);
     const totalLines = splitLinesForCounting(content).length;
     if (buf.length <= maxBytes) {
         return { content, truncated: false, removedChars: 0, totalBytes: buf.length, totalLines };
@@ -230,9 +231,9 @@ export function truncateMiddle(content, maxBytes) {
     let tailStart = buf.length - (maxBytes - Math.floor(maxBytes / 2));
     while (tailStart < buf.length && !isBoundary(tailStart))
         tailStart++;
-    const head = buf.subarray(0, headEnd).toString("utf-8");
-    const tail = buf.subarray(tailStart).toString("utf-8");
-    const removedChars = Array.from(buf.subarray(headEnd, tailStart).toString("utf-8")).length;
+    const head = decodeUtf8(buf.subarray(0, headEnd));
+    const tail = decodeUtf8(buf.subarray(tailStart));
+    const removedChars = Array.from(decodeUtf8(buf.subarray(headEnd, tailStart))).length;
     return {
         content: `${head}…${removedChars} chars truncated…${tail}`,
         truncated: true,

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

@@ -0,0 +1,47 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type Static, Type } from "typebox";
+import type { FilesystemPolicyChecker, ToolDefinition } from "../extensions/types.ts";
+import { type FileMutationQueue, type ToolPathCanonicalizer, type ToolPathResolver } from "./file-tool-host.ts";
+import type { ToolMachine } from "./tool-machine.ts";
+import { type WriteBaseline, type WriteToolDetails } from "./write-result.ts";
+export declare const writeSchema: Type.TObject<{
+    path: Type.TString;
+    content: Type.TString;
+}>;
+export declare const writeToolSystemPromptContribution: {
+    readonly snippet: "Create or overwrite files";
+    readonly guidelines: readonly ["write only for new files or full rewrites."];
+    readonly fullGuidelines: readonly ["Use write only for new files or complete rewrites."];
+};
+export type WriteToolInput = Static<typeof writeSchema>;
+/**
+ * Pluggable operations for the write tool.
+ * Override these to delegate file writing to remote systems (for example SSH).
+ */
+export interface WriteOperations {
+    /** Write content to a file */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Create directory recursively */
+    mkdir: (dir: string) => Promise<void>;
+}
+export interface CoreWriteToolOptions {
+    /** Operation layer and policy gate. */
+    machine: ToolMachine;
+    /** Custom operations for file writing. Default: writes through `machine` */
+    operations?: WriteOperations;
+    /** Extension-registered filesystem policy checker. */
+    filesystemPolicy?: FilesystemPolicyChecker;
+    /** Default: POSIX resolution against the cwd. */
+    resolvePath?: ToolPathResolver;
+    /** The directory handed to `operations.mkdir`. Default: POSIX dirname. */
+    dirname?: (absolutePath: string) => string;
+    /** Default: one queue per path string in this isolate, shared with the core edit tool. */
+    withMutationQueue?: FileMutationQueue;
+    /** The path `filesystemPolicy` judges. Default: the resolved path as is. */
+    canonicalizePath?: ToolPathCanonicalizer;
+    /** The content before the write, for the result's patch. Default: read on `machine`; none with custom operations. */
+    readBaseline?: (absolutePath: string) => Promise<WriteBaseline>;
+}
+export declare function createCoreWriteToolDefinition(cwd: string, options: CoreWriteToolOptions): ToolDefinition<typeof writeSchema, WriteToolDetails | undefined>;
+export declare function createCoreWriteTool(cwd: string, options: CoreWriteToolOptions): AgentTool<typeof writeSchema>;
+//# sourceMappingURL=write-core.d.ts.map