@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/bounded-read.js

@@ -2,50 +2,69 @@ import fs from "node:fs";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 const READ_CHUNK_BYTES = 64 * 1024;
-function createScratchBuffer(maxBytes) {
-    const initialReadBytes = Number.isFinite(maxBytes)
-        ? Math.min(READ_CHUNK_BYTES, maxBytes + 1)
-        : READ_CHUNK_BYTES;
-    return Buffer.allocUnsafe(Math.max(1, initialReadBytes));
+// Preserve one-read performance through the default Root byte budget.
+const MAX_INITIAL_READ_BYTES = 16 * 1024 * 1024;
+function createInitialBuffer(maxBytes, size, allocate = Buffer.allocUnsafe) {
+    // A size hint can describe a huge sparse file or an already exhausted fd.
+    return allocate(Math.min(maxBytes, size, MAX_INITIAL_READ_BYTES) + 1);
 }
-function nextReadLength(total, maxBytes, capacity) {
-    return Number.isFinite(maxBytes)
-        ? Math.min(capacity, maxBytes - total + 1)
-        : capacity;
+function createScratchBuffer(maxBytes, allocate = Buffer.allocUnsafe) {
+    return allocate(Math.min(READ_CHUNK_BYTES, maxBytes + 1));
 }
-function appendChunk(params) {
-    const total = params.total + params.bytesRead;
-    if (total > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got at least ${total})`);
+function growReadBuffer(buffer, maxBytes, allocate = Buffer.allocUnsafe) {
+    // Grow only after consuming the whole buffer, never from an unchecked size hint.
+    const capacity = Math.min(maxBytes + 1, Math.max(READ_CHUNK_BYTES, buffer.length * 2));
+    const grown = allocate(capacity);
+    buffer.copy(grown);
+    return grown;
+}
+function finishReadBuffer(buffer, total, allocate) {
+    if (total === 0)
+        return Buffer.alloc(0);
+    const result = buffer.subarray(0, total);
+    if (total >= buffer.length / 2)
+        return result;
+    if (!allocate)
+        return Buffer.from(result);
+    const compact = allocate(total);
+    result.copy(compact);
+    return compact;
+}
+function addReadBytes(total, bytesRead, maxBytes, createLimitError) {
+    const next = total + bytesRead;
+    if (next > maxBytes) {
+        if (createLimitError)
+            throw createLimitError();
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${next})`);
     }
-    params.chunks.push(Buffer.from(params.scratch.subarray(0, params.bytesRead)));
-    return total;
+    return next;
 }
-async function readBoundedAsync(maxBytes, readChunk, observeRegularFileSize) {
+export async function readBoundedAsync(maxBytes, readChunk, options = {}) {
     normalizeMaxBytes(maxBytes);
-    const chunks = [];
     let total = 0;
-    const size = observeRegularFileSize?.();
+    const { observeRegularFileSize, createLimitError } = options;
+    const allocate = options.unpooled ? Buffer.allocUnsafeSlow : undefined;
+    const size = options.initialSize ?? observeRegularFileSize?.();
+    let buffer = size === undefined ? createScratchBuffer(maxBytes, allocate) : createInitialBuffer(maxBytes, size, allocate);
     if (size !== undefined) {
-        const first = Buffer.allocUnsafe(Math.min(maxBytes, size) + 1);
-        const bytesRead = await readChunk(first, first.length);
+        const bytesRead = await readChunk(buffer, buffer.length);
         if (bytesRead === 0)
-            return first.subarray(0, 0);
-        // Short reads can occur before EOF. Only accept one when a fresh fd size
-        // observation proves we consumed at least the entire current file size.
-        const currentSize = bytesRead < first.length ? observeRegularFileSize?.() : undefined;
-        if (currentSize !== undefined && bytesRead >= currentSize)
-            return first.subarray(0, bytesRead);
-        total = appendChunk({ chunks, scratch: first, bytesRead, total, maxBytes });
+            return finishReadBuffer(buffer, 0, allocate);
+        // Short reads can occur before EOF. Only use the size shortcut on this
+        // initial read; virtual files can report zero or stale sizes thereafter.
+        const currentSize = bytesRead < buffer.length ? observeRegularFileSize?.() : undefined;
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
+        if (currentSize !== undefined && currentSize > 0 && bytesRead >= currentSize)
+            return finishReadBuffer(buffer, total, allocate);
     }
-    const scratch = createScratchBuffer(maxBytes);
     while (true) {
-        const length = nextReadLength(total, maxBytes, scratch.length);
-        const bytesRead = await readChunk(scratch, length);
-        if (bytesRead === 0) {
-            return Buffer.concat(chunks, total);
-        }
-        total = appendChunk({ chunks, scratch, bytesRead, total, maxBytes });
+        if (total === buffer.length)
+            buffer = growReadBuffer(buffer, maxBytes, allocate);
+        const remaining = buffer.subarray(total);
+        const bytesRead = await readChunk(remaining, remaining.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, total, allocate);
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
     }
 }
 /**
@@ -58,7 +77,7 @@ export async function readFileHandleBounded(handle, maxBytes) {
     const fd = "fd" in handle && typeof handle.fd === "number" ? handle.fd : undefined;
     return await readBoundedAsync(maxBytes, async (scratch, length) => {
         return (await handle.read(scratch, 0, length, null)).bytesRead;
-    }, fd === undefined ? undefined : () => regularFileSize(fd));
+    }, { observeRegularFileSize: fd === undefined ? undefined : () => regularFileSize(fd) });
 }
 function regularFileSize(fd) {
     try {
@@ -87,20 +106,38 @@ export async function readFileDescriptorBounded(fd, maxBytes) {
     normalizeMaxBytes(maxBytes);
     return await readBoundedAsync(maxBytes, async (scratch, length) => {
         return await readDescriptorChunk(fd, scratch, length);
-    }, () => regularFileSize(fd));
+    }, { observeRegularFileSize: () => regularFileSize(fd) });
 }
-/** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
-export function readFileDescriptorBoundedSync(fd, maxBytes) {
+export function readBoundedSync(maxBytes, readChunk, options = {}) {
     normalizeMaxBytes(maxBytes);
-    const chunks = [];
-    const scratch = createScratchBuffer(maxBytes);
     let total = 0;
+    const { observeRegularFileSize, createLimitError } = options;
+    const size = options.initialSize ?? observeRegularFileSize?.();
+    let buffer = size === undefined ? createScratchBuffer(maxBytes) : createInitialBuffer(maxBytes, size);
+    if (size !== undefined) {
+        const bytesRead = readChunk(buffer, buffer.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, 0);
+        const currentSize = bytesRead < buffer.length ? observeRegularFileSize?.() : undefined;
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
+        if (currentSize !== undefined && currentSize > 0 && bytesRead >= currentSize)
+            return finishReadBuffer(buffer, total);
+    }
     while (true) {
-        const length = nextReadLength(total, maxBytes, scratch.length);
-        const bytesRead = fs.readSync(fd, scratch, 0, length, null);
-        if (bytesRead === 0) {
-            return Buffer.concat(chunks, total);
-        }
-        total = appendChunk({ chunks, scratch, bytesRead, total, maxBytes });
+        if (total === buffer.length)
+            buffer = growReadBuffer(buffer, maxBytes);
+        const remaining = buffer.subarray(total);
+        const bytesRead = readChunk(remaining, remaining.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, total);
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
     }
 }
+/** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
+export function readFileDescriptorBoundedSync(fd, maxBytes) {
+    return readBoundedSync(maxBytes, (buffer, length) => fs.readSync(fd, buffer, 0, length, null), {
+        // Small budgets already bound the first allocation without a size lookup.
+        initialSize: maxBytes <= READ_CHUNK_BYTES ? maxBytes : undefined,
+        observeRegularFileSize: () => regularFileSize(fd),
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/byte-budget.d.ts

@@ -1,4 +1,3 @@
 export declare function normalizeMaxBytes(value: number | undefined, options?: {
     defaultValue?: number;
 }): number | undefined;
-//# sourceMappingURL=byte-budget.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/byte-view.d.ts

@@ -0,0 +1,2 @@
+/** Snapshot intrinsic view bounds without copying the borrowed payload. */
+export declare function snapshotByteView(bytes: Uint8Array): Uint8Array;

package/node_modules/@openclaw/fs-safe/dist/byte-view.js

@@ -0,0 +1,13 @@
+const ByteView = Uint8Array;
+const typedArray = Object.getPrototypeOf(ByteView.prototype);
+const viewLength = Object.getOwnPropertyDescriptor(typedArray, "byteLength").get;
+const viewOffset = Object.getOwnPropertyDescriptor(typedArray, "byteOffset").get;
+const viewBuffer = Object.getOwnPropertyDescriptor(typedArray, "buffer").get;
+/** Snapshot intrinsic view bounds without copying the borrowed payload. */
+export function snapshotByteView(bytes) {
+    const length = Reflect.apply(viewLength, bytes, []);
+    // Preserve empty, detached, and out-of-bounds views as zero-byte inputs.
+    if (length === 0)
+        return new ByteView(0);
+    return new ByteView(Reflect.apply(viewBuffer, bytes, []), Reflect.apply(viewOffset, bytes, []), length);
+}

package/node_modules/@openclaw/fs-safe/dist/clone-metadata.d.ts

@@ -0,0 +1,19 @@
+export type CloneFileMetadata = {
+    dev: number;
+    type: number;
+    mtimeSec: number;
+    mtimeNs: number;
+    ctimeSec: number;
+    ctimeNs: number;
+    uid: number;
+    gid: number;
+    mode: number;
+    ino: bigint;
+    size: bigint;
+    cloneId: bigint;
+};
+/** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * On macOS, these snapshots require the native helper.
+ * These are point-in-time facts, not authorization or a guarantee against later edits.
+ */
+export declare function readCloneFileMetadata(files: readonly string[]): Promise<(CloneFileMetadata | undefined)[]>;

package/node_modules/@openclaw/fs-safe/dist/clone-metadata.js

@@ -0,0 +1,36 @@
+import { assertAbsolutePathInput } from "./absolute-path.js";
+import { getNativeBinding, requireNativeBinding } from "./native.js";
+/** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * On macOS, these snapshots require the native helper.
+ * These are point-in-time facts, not authorization or a guarantee against later edits.
+ */
+export async function readCloneFileMetadata(files) {
+    const paths = files.map(assertAbsolutePathInput);
+    const native = process.platform === "darwin" ? requireNativeBinding() : getNativeBinding();
+    if (!native)
+        return paths.map(() => undefined);
+    const results = await native.readCloneFileMetadata(paths);
+    return results.map((result) => {
+        if (!result ||
+            result.length !== 100 ||
+            result.readUInt32LE(0) !== 100 ||
+            result.readUInt32LE(4) !== 0x82038c0a ||
+            result.readUInt32LE(16) !== 0x200 ||
+            result.readUInt32LE(20) !== 0x100)
+            return undefined;
+        return {
+            dev: result.readUInt32LE(24),
+            type: result.readUInt32LE(28),
+            mtimeSec: Number(result.readBigInt64LE(32)),
+            mtimeNs: Number(result.readBigInt64LE(40)),
+            ctimeSec: Number(result.readBigInt64LE(48)),
+            ctimeNs: Number(result.readBigInt64LE(56)),
+            uid: result.readUInt32LE(64),
+            gid: result.readUInt32LE(68),
+            mode: result.readUInt32LE(72),
+            ino: result.readBigUInt64LE(76),
+            size: result.readBigUInt64LE(84),
+            cloneId: result.readBigUInt64LE(92),
+        };
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/config.d.ts

@@ -1,3 +1,2 @@
 export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
-//# sourceMappingURL=config.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/containment.d.ts

@@ -1,2 +1 @@
 export type ContainmentGuarantee = "kernel-atomic" | "best-effort";
-//# sourceMappingURL=containment.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/copy-file-input.d.ts

@@ -0,0 +1,21 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { type CopyCloneMode } from "./copy-policy.js";
+import { type NativeBinding } from "./native.js";
+import { type NativeFileCopyResult } from "./native-binding.js";
+export type CopyFileInput = {
+    kind: "file";
+    handle: FileHandle;
+    size: number;
+    clone: CopyCloneMode;
+    signal?: AbortSignal;
+    verifySource(): Promise<void>;
+};
+export declare function resolveFileCopyCloneMode(mode?: CopyCloneMode): CopyCloneMode;
+export declare function assertCopySourceCurrent(source: {
+    handle: FileHandle;
+    realPath: string;
+}, identity: BigIntStats): Promise<void>;
+export declare function writeCopyFileToFd(fd: number, input: CopyFileInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;
+export declare function createNativeCopyFile(native: NativeBinding, input: CopyFileInput, parentFd: number, basename: string, maxBytes: number | undefined, sync: boolean): Promise<NativeFileCopyResult | undefined>;
+export declare function assertNativeCopyCompleted(input: CopyFileInput, copied?: NativeFileCopyResult): void;

package/node_modules/@openclaw/fs-safe/dist/copy-file-input.js

@@ -0,0 +1,71 @@
+import fs, {} from "node:fs";
+import { resolveCopyCloneMode } from "./copy-policy.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { transferFileHandle } from "./file-handle-transfer.js";
+export function resolveFileCopyCloneMode(mode) {
+    const clone = resolveCopyCloneMode(mode, "never");
+    if (clone === "always" && !getNativeBinding()?.copyFileExclusive) {
+        throw new FsSafeError("helper-unavailable", "native file cloning is unavailable");
+    }
+    return clone;
+}
+export async function assertCopySourceCurrent(source, identity) {
+    await inspectFileIdentity(() => fs.fstatSync(source.handle.fd, { bigint: true }), identity);
+    await inspectFileIdentity(() => {
+        const current = fs.lstatSync(source.realPath, { bigint: true });
+        if (current.isSymbolicLink() || !current.isFile()) {
+            throw new FsSafeError("path-mismatch", "copy source path changed");
+        }
+        return current;
+    }, identity);
+}
+export async function writeCopyFileToFd(fd, input, maxBytes, assertBeforeMutation) {
+    await transferFileHandle(input.handle, fd, {
+        maxBytes, sizeHint: input.size, signal: input.signal, assertBeforeMutation,
+    });
+}
+export async function createNativeCopyFile(native, input, parentFd, basename, maxBytes, sync) {
+    input.signal?.throwIfAborted();
+    if (!native.copyFileExclusive) {
+        if (input.clone === "always") {
+            throw new FsSafeError("helper-unavailable", "native file cloning is unavailable");
+        }
+        return undefined;
+    }
+    captureNativeFdClose(native);
+    const nativeSignal = input.signal ? AbortSignal.any([input.signal]) : undefined;
+    try {
+        // The caller adopts this descriptor before observing a later cancellation.
+        return await native.copyFileExclusive(input.handle.fd, parentFd, basename, input.clone, maxBytes !== undefined && Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal, sync);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "Cancelled" || code === "ABORT_ERR")
+            input.signal?.throwIfAborted();
+        if (code === "too-large") {
+            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`, { cause: error });
+        }
+        if (code === "ENOTSUP" && input.clone !== "always")
+            return undefined;
+        if (code === "ENOTSUP") {
+            throw new FsSafeError("unsupported-platform", "native file cloning is unsupported", { cause: error });
+        }
+        throw new FsSafeError("helper-failed", "native file copy failed", { cause: error });
+    }
+    finally {
+        if (nativeSignal)
+            nativeSignal.onabort = null;
+    }
+}
+export function assertNativeCopyCompleted(input, copied) {
+    if (copied?.errorCode) {
+        if (copied.errorCode === "Cancelled" || copied.errorCode === "ABORT_ERR")
+            input.signal?.throwIfAborted();
+        const unsupported = ["ENOTSUP", "EOPNOTSUPP", "ENOSYS", "EXDEV", "EINVAL"].includes(copied.errorCode);
+        throw new FsSafeError(copied.errorCode === "too-large" ? "too-large" : unsupported ? "unsupported-platform" : "helper-failed", copied.errorMessage ?? "native file copy failed", { cause: Object.assign(new Error(copied.errorMessage ?? "native file copy failed"), { code: copied.errorCode }) });
+    }
+    input.signal?.throwIfAborted();
+}

package/node_modules/@openclaw/fs-safe/dist/copy-policy.d.ts

@@ -0,0 +1,2 @@
+export type CopyCloneMode = "auto" | "always" | "never";
+export declare function resolveCopyCloneMode(mode: CopyCloneMode | undefined, defaultMode: CopyCloneMode): CopyCloneMode;

package/node_modules/@openclaw/fs-safe/dist/copy-policy.js

@@ -0,0 +1,8 @@
+import { FsSafeError } from "./errors.js";
+export function resolveCopyCloneMode(mode, defaultMode) {
+    const policy = mode === undefined ? defaultMode : mode;
+    if (policy !== "auto" && policy !== "always" && policy !== "never") {
+        throw new FsSafeError("invalid-path", "copy clone policy must be auto, always, or never");
+    }
+    return policy;
+}

package/node_modules/@openclaw/fs-safe/dist/copy-publication.d.ts

@@ -0,0 +1,20 @@
+import type { BigIntStats } from "node:fs";
+import type { PinnedWriteParams, PublishedWriteIdentity } from "./pinned-write-types.js";
+export type RootCopyPublicationReceipt = Readonly<{
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
+export declare function createCopyPublicationObserver(path: string, notify?: (receipt: RootCopyPublicationReceipt) => void): {
+    onPublished(identity: PublishedWriteIdentity): void;
+    rethrowObserverFailure(error: unknown): void;
+};
+export declare const onCopyPublication: unique symbol;
+export declare const onCopySourceAdmission: unique symbol;
+export type CopyPublicationOptions = {
+    [onCopyPublication]?: PinnedWriteParams["verifyPublished"];
+    [onCopySourceAdmission]?: (identity: BigIntStats, realPath: string) => {
+        mode: number;
+        verify(): void;
+    };
+};

package/node_modules/@openclaw/fs-safe/dist/copy-publication.js

@@ -0,0 +1,33 @@
+import { FsSafeError } from "./errors.js";
+export function createCopyPublicationObserver(path, notify) {
+    let rejected;
+    return {
+        onPublished(identity) {
+            const receipt = Object.freeze({ path, dev: identity.dev, ino: identity.ino });
+            try {
+                const result = notify?.(receipt);
+                if (result !== null && (typeof result === "object" || typeof result === "function") &&
+                    "then" in result && typeof result.then === "function") {
+                    void Promise.resolve(result).catch(() => undefined);
+                    throw new TypeError("onDestinationPublished must be synchronous");
+                }
+            }
+            catch (error) {
+                rejected = { error };
+                throw error;
+            }
+        },
+        rethrowObserverFailure(error) {
+            if (rejected && (error === rejected.error ||
+                (error instanceof FsSafeError && error.cause === rejected.error && error.details?.phase === "publish"))) {
+                throw rejected.error;
+            }
+        },
+    };
+}
+// Internal composition hook; the descriptor is borrowed until the callback returns.
+// Kept off RootCopyOptions and all public package exports.
+export const onCopyPublication = Symbol("onCopyPublication");
+// Reuse the copy's admitted descriptor identity before any bytes are staged.
+// Internal callers can bind prior observations and select its publication mode.
+export const onCopySourceAdmission = Symbol("onCopySourceAdmission");

package/node_modules/@openclaw/fs-safe/dist/copy-tree-portable.d.ts

@@ -0,0 +1,8 @@
+import type { NativeBinding } from "./native-binding.js";
+import { openStagedDirectory } from "./staged-directory.js";
+/** Byte-copy adapter for the shared immutable-source, caller-owned namespace contract. */
+export declare function copyOwnedTree(source: ReturnType<typeof openStagedDirectory>, destination: string, options: {
+    signal?: AbortSignal;
+    concurrency: number;
+    copyFileContents?: NativeBinding["copyFileContents"];
+}): Promise<void>;