@openclaw/openshell-sandbox 2026.9.2 → 2026.9.3

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.js

@@ -0,0 +1,292 @@
+import { randomUUID } from "node:crypto";
+import { withSidecarLock } from "./sidecar-lock.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+import { serializePathWrite } from "./write-queue.js";
+export function durableQueueProcessingPath(paths) {
+    if (paths.processingPath)
+        return paths.processingPath;
+    return paths.jsonPath.endsWith(".json")
+        ? `${paths.jsonPath.slice(0, -".json".length)}.processing`
+        : `${paths.jsonPath}.processing`;
+}
+async function regularQueueFileIdentity(filePath) {
+    const identity = await lstatOrNull(filePath);
+    if (!identity)
+        return null;
+    if (identity.isSymbolicLink() || !identity.isFile()) {
+        throw new Error(`queue entry is not a regular file: ${filePath}`);
+    }
+    return identity;
+}
+async function withQueueEntryLock(paths, run) {
+    return await serializePathWrite(paths.jsonPath, async () => await withQueueTransferLock(path.resolve(paths.jsonPath), run));
+}
+async function claimDurableQueueEntryUnlocked(paths, options = {}) {
+    const processingPath = durableQueueProcessingPath(paths);
+    await recoverDurableQueueRetirement({ jsonPath: paths.jsonPath, processingPath });
+    const existingProcessing = await regularQueueFileIdentity(processingPath);
+    if (existingProcessing) {
+        const pending = await lstatOrNull(paths.jsonPath);
+        if (pending &&
+            !pending.isSymbolicLink() &&
+            pending.isFile() &&
+            sameFileIdentityForCleanup(pending, existingProcessing)) {
+            await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
+        }
+        return processingPath;
+    }
+    const pending = await lstatOrNull(paths.jsonPath);
+    if (!pending || pending.isSymbolicLink() || !pending.isFile())
+        return null;
+    if (pending.nlink > 1n || !sameFileIdentityForCleanup(pending, pending)) {
+        // Batch admission may skip unowned input, never a failed owned transition.
+        if (options.skipUnowned)
+            return null;
+        throw new FsSafeError("path-mismatch", "queue entry is not exclusively owned");
+    }
+    try {
+        await fs.link(paths.jsonPath, processingPath);
+    }
+    catch (error) {
+        if (getErrorCode(error) === "EEXIST") {
+            return (await regularQueueFileIdentity(processingPath)) ? processingPath : null;
+        }
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    await syncDirectory(path.dirname(processingPath));
+    const claimed = await regularQueueFileIdentity(processingPath);
+    if (!claimed || claimed.nlink > 2n) {
+        throw new FsSafeError("path-mismatch", "queue claim is not an owned regular file");
+    }
+    await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
+    return processingPath;
+}
+export async function claimDurableQueueEntry(paths, options = {}) {
+    if (!(await lstatOrNull(path.dirname(paths.jsonPath))))
+        return null;
+    return await withQueueEntryLock(paths, async () => await claimDurableQueueEntryUnlocked(paths, options));
+}
+export async function completeDeliveredQueueEntry(paths) {
+    if (!(await lstatOrNull(path.dirname(paths.deliveredPath))))
+        return false;
+    return await withQueueEntryLock(paths, async () => {
+        if (!(await regularQueueFileIdentity(paths.deliveredPath)))
+            return false;
+        if (await regularQueueFileIdentity(durableQueueProcessingPath(paths))) {
+            await fs.unlink(paths.deliveredPath);
+            await syncDirectory(path.dirname(paths.deliveredPath));
+            return false;
+        }
+        await fs.unlink(paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+        return true;
+    });
+}
+export async function acknowledgeDurableQueueEntry(paths) {
+    if (!(await lstatOrNull(path.dirname(paths.jsonPath))))
+        return;
+    await withQueueEntryLock(paths, async () => {
+        const processingPath = durableQueueProcessingPath(paths);
+        const processing = await regularQueueFileIdentity(processingPath);
+        const delivered = await regularQueueFileIdentity(paths.deliveredPath);
+        if (!processing) {
+            if (delivered) {
+                await fs.unlink(paths.deliveredPath);
+            }
+            await syncDirectory(path.dirname(paths.deliveredPath));
+            if (await regularQueueFileIdentity(paths.jsonPath)) {
+                throw new FsSafeError("path-mismatch", "queue acknowledgement requires a processing claim");
+            }
+            return;
+        }
+        if (delivered)
+            await fs.unlink(paths.deliveredPath);
+        await fs.rename(processingPath, paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+        await fs.unlink(paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+    });
+}
+export async function moveDurableQueueEntryToFailed(params) {
+    await withQueueEntryLock(params.paths, async () => {
+        const processingPath = durableQueueProcessingPath(params.paths);
+        const processing = await regularQueueFileIdentity(processingPath);
+        const existingFailed = await regularQueueFileIdentity(params.failedPath);
+        if (!processing && existingFailed) {
+            await syncDirectory(path.dirname(params.failedPath));
+            await syncDirectory(path.dirname(processingPath));
+            const recoveredFailed = await regularQueueFileIdentity(params.failedPath);
+            if (!recoveredFailed ||
+                !sameFileIdentityForCleanup(existingFailed, recoveredFailed)) {
+                throw new FsSafeError("path-mismatch", "failed queue destination changed during recovery");
+            }
+            if (await regularQueueFileIdentity(params.paths.jsonPath)) {
+                throw new FsSafeError("already-exists", "failed queue destination already exists");
+            }
+            return;
+        }
+        const sourcePath = processing
+            ? processingPath
+            : await claimDurableQueueEntryUnlocked(params.paths);
+        if (!sourcePath) {
+            throw Object.assign(new Error("queue entry does not exist"), { code: "ENOENT" });
+        }
+        const source = await regularQueueFileIdentity(sourcePath);
+        const failed = await regularQueueFileIdentity(params.failedPath);
+        if (failed) {
+            if (source && sameFileIdentityForCleanup(source, failed)) {
+                await syncDirectory(path.dirname(params.failedPath));
+                await fs.unlink(sourcePath);
+                await syncDirectory(path.dirname(sourcePath));
+                return;
+            }
+            throw new FsSafeError("already-exists", "failed queue destination already exists");
+        }
+        await fs.link(sourcePath, params.failedPath);
+        await syncDirectory(path.dirname(params.failedPath));
+        await fs.unlink(sourcePath);
+        await syncDirectory(path.dirname(sourcePath));
+    });
+}
+const RETIREMENT_ROOT_NAME = ".fs-safe-retirements";
+const RETIREMENT_ENTRY_NAME = "entry";
+export function getErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+async function lstatOrNull(filePath) {
+    try {
+        return await fs.lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function assertDirectory(identity, label) {
+    if (identity.isSymbolicLink() || !identity.isDirectory()) {
+        throw new FsSafeError("path-mismatch", `${label} is not an owned directory`);
+    }
+}
+async function regularFileIdentity(filePath) {
+    const identity = await lstatOrNull(filePath);
+    if (!identity)
+        return null;
+    if (identity.isSymbolicLink() || !identity.isFile()) {
+        throw new FsSafeError("path-mismatch", "queue retirement path is not a regular file");
+    }
+    return identity;
+}
+function retirementPaths(jsonPath) {
+    const rootPath = path.join(path.dirname(jsonPath), RETIREMENT_ROOT_NAME);
+    const dirPath = path.join(rootPath, path.basename(jsonPath));
+    return { dirPath, entryPath: path.join(dirPath, RETIREMENT_ENTRY_NAME), rootPath };
+}
+async function inspectRetirementRoot(jsonPath) {
+    const rootPath = retirementPaths(jsonPath).rootPath;
+    const root = await lstatOrNull(rootPath);
+    if (!root)
+        return null;
+    assertDirectory(root, "queue retirement root");
+    return rootPath;
+}
+async function ensureRetirementRoot(jsonPath) {
+    const parentPath = path.dirname(jsonPath);
+    const rootPath = retirementPaths(jsonPath).rootPath;
+    await fs.mkdir(rootPath, { mode: 0o700 }).catch((error) => {
+        if (getErrorCode(error) !== "EEXIST")
+            throw error;
+    });
+    const root = await fs.lstat(rootPath, { bigint: true });
+    assertDirectory(root, "queue retirement root");
+    await syncDirectory(parentPath);
+    return rootPath;
+}
+async function removeRetirementRecord(params) {
+    await fs.rmdir(params.dirPath).catch((error) => {
+        if (getErrorCode(error) !== "ENOENT")
+            throw error;
+    });
+    await syncDirectory(params.rootPath);
+}
+async function recoverDurableQueueRetirement(params) {
+    const rootPath = await inspectRetirementRoot(params.jsonPath);
+    if (!rootPath)
+        return;
+    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
+    const dir = await lstatOrNull(dirPath);
+    if (!dir)
+        return;
+    assertDirectory(dir, "queue retirement record");
+    const names = await fs.readdir(dirPath);
+    if (names.length === 0) {
+        await removeRetirementRecord({ dirPath, rootPath });
+        return;
+    }
+    if (names.length !== 1 || names[0] !== RETIREMENT_ENTRY_NAME) {
+        throw new FsSafeError("path-mismatch", "queue retirement record is ambiguous");
+    }
+    const entry = await regularFileIdentity(entryPath);
+    const processing = await regularFileIdentity(params.processingPath);
+    if (!entry || !processing) {
+        throw new FsSafeError("path-mismatch", "queue retirement ownership is incomplete");
+    }
+    if (!sameFileIdentityForCleanup(entry, processing)) {
+        const pending = await regularFileIdentity(params.jsonPath);
+        if (!pending) {
+            await fs.link(entryPath, params.jsonPath);
+            await syncDirectory(path.dirname(params.jsonPath));
+        }
+        else if (sameFileIdentityForCleanup(pending, entry)) {
+            await syncDirectory(path.dirname(params.jsonPath));
+        }
+        else if (pending.nlink > 1n) {
+            throw new FsSafeError("path-mismatch", "queue replacement identity is ambiguous");
+        }
+    }
+    await fs.unlink(entryPath);
+    await syncDirectory(dirPath);
+    await removeRetirementRecord({ dirPath, rootPath });
+}
+async function retireDurableQueueSource(params) {
+    await recoverDurableQueueRetirement(params);
+    const rootPath = await ensureRetirementRoot(params.jsonPath);
+    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
+    await fs.mkdir(dirPath, { mode: 0o700 });
+    await syncDirectory(rootPath);
+    try {
+        await fs.rename(params.jsonPath, entryPath);
+    }
+    catch (error) {
+        if (getErrorCode(error) !== "ENOENT")
+            throw error;
+        await removeRetirementRecord({ dirPath, rootPath });
+        return;
+    }
+    await syncDirectory(dirPath);
+    await syncDirectory(path.dirname(params.jsonPath));
+    await recoverDurableQueueRetirement(params);
+}
+async function withQueueTransferLock(filePath, run) {
+    const lockPath = path.join(path.dirname(filePath), `.fs-safe-transfer-${sha256Hex(path.basename(filePath)).slice(0, 32)}.lock`);
+    return await withSidecarLock(filePath, {
+        managerKey: "fs-safe.queue-transfer",
+        lockPath,
+        staleMs: 30_000,
+        staleRecovery: "fail-closed",
+        timeoutMs: 45_000,
+        payload: () => ({
+            ownerToken: randomUUID(),
+            createdAt: new Date().toISOString(),
+        }),
+        retry: { retries: 180, minTimeout: 25, maxTimeout: 250, factor: 1.1 },
+    }, run);
+}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue.d.ts

@@ -0,0 +1,46 @@
+export type JsonDurableQueueEntryPaths = {
+    jsonPath: string;
+    deliveredPath: string;
+    processingPath?: string;
+};
+export type JsonDurableQueueReadResult<T> = {
+    entry: T;
+    migrated?: boolean;
+};
+export type JsonDurableQueueLoadOptions<T> = {
+    queueDir: string;
+    tempPrefix: string;
+    read?: (entry: T, filePath: string) => Promise<JsonDurableQueueReadResult<T>>;
+    cleanupTmpMaxAgeMs?: number;
+    maxBytes?: number;
+};
+export declare const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES: number;
+export declare function unlinkBestEffort(filePath: string): Promise<void>;
+export declare function jsonDurableQueueEntryExists(filePath: string): Promise<boolean>;
+export declare function resolveJsonDurableQueueEntryPaths(queueDir: string, id: string): JsonDurableQueueEntryPaths;
+export declare function ensureJsonDurableQueueDirs(params: {
+    queueDir: string;
+    failedDir: string;
+}): Promise<void>;
+export declare function writeJsonDurableQueueEntry(params: {
+    filePath: string;
+    entry: unknown;
+    tempPrefix: string;
+}): Promise<void>;
+export declare function readJsonDurableQueueEntry<T>(filePath: string, options?: {
+    maxBytes?: number;
+}): Promise<T>;
+export declare function ackJsonDurableQueueEntry(paths: JsonDurableQueueEntryPaths): Promise<void>;
+export declare function loadJsonDurableQueueEntry<T>(params: {
+    paths: JsonDurableQueueEntryPaths;
+    tempPrefix: string;
+    read?: (entry: T, filePath: string) => Promise<JsonDurableQueueReadResult<T>>;
+    maxBytes?: number;
+}): Promise<T | null>;
+export declare function loadPendingJsonDurableQueueEntries<T>(options: JsonDurableQueueLoadOptions<T>): Promise<T[]>;
+export declare function moveJsonDurableQueueEntryToFailed(params: {
+    queueDir: string;
+    failedDir: string;
+    id: string;
+}): Promise<void>;
+//# sourceMappingURL=json-durable-queue.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAM3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAO5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAgLD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhB;AA6DD,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CASZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CA8Dd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}