@openclaw/mxc-sandbox 2026.7.2-beta.5 → 2026.8.1-beta.2

package/dist/index.js

@@ -12,8 +12,9 @@ import fs, { lstatSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSyn
 import { createHash, randomBytes } from "node:crypto";
 import { runCommandBuffered } from "openclaw/plugin-sdk/process-runtime";
 import { removePathWithinRoot, root } from "openclaw/plugin-sdk/file-access-runtime";
-import { isPathInside } from "openclaw/plugin-sdk/security-runtime";
+import { FsSafeError, isPathInside } from "openclaw/plugin-sdk/security-runtime";
 import { fileURLToPath } from "node:url";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { execFileSync } from "node:child_process";
 //#region extensions/mxc/src/config.ts
 const MXC_CONTAINMENTS = ["process", "processcontainer"];
@@ -183,10 +184,10 @@ function createMxcFsBridge(params) {
 var MxcFsBridge = class {
 	constructor(sandbox) {
 		this.sandbox = sandbox;
-		this.defaultContainerRoot = path.resolve(this.sandbox.containerWorkdir);
-		this.protectedSkillMounts = resolveMxcProtectedSkillMounts$1(this.sandbox);
-		this.workspaceMounts = resolveWorkspaceMounts(this.sandbox);
 		this.resolveRenameTargets = createWritableRenameTargetResolver((target) => this.resolveTarget(target), (target, action) => this.ensureWritable(target, action));
+		this.defaultContainerRoot = path.resolve(sandbox.containerWorkdir);
+		this.protectedSkillMounts = resolveMxcProtectedSkillMounts$1(sandbox);
+		this.workspaceMounts = resolveWorkspaceMounts(sandbox);
 	}
 	resolvePath(params) {
 		const target = this.resolveTarget(params);
@@ -198,7 +199,10 @@ var MxcFsBridge = class {
 	}
 	async readFile(params) {
 		const target = this.resolveTarget(params);
-		return await (await root(target.mount.hostRoot)).readBytes(target.mountRelativePath, { hardlinks: "reject" });
+		return await (await root(target.mount.hostRoot)).readBytes(target.mountRelativePath, {
+			hardlinks: "reject",
+			...params.maxBytes === void 0 ? {} : { maxBytes: params.maxBytes }
+		});
 	}
 	async writeFile(params) {
 		const target = this.resolveTarget(params);
@@ -206,6 +210,18 @@ var MxcFsBridge = class {
 		const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.from(params.data, params.encoding ?? "utf8");
 		await (await root(target.mount.hostRoot)).write(target.mountRelativePath, buffer, { mkdir: params.mkdir !== false });
 	}
+	async createFileExclusive(params) {
+		const target = this.resolveTarget(params);
+		this.ensureWritable(target, "create files");
+		const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.from(params.data, params.encoding ?? "utf8");
+		try {
+			await (await root(target.mount.hostRoot)).create(target.mountRelativePath, buffer, { mkdir: params.mkdir !== false });
+			return "created";
+		} catch (error) {
+			if (error instanceof FsSafeError && error.code === "already-exists") return "exists";
+			throw error;
+		}
+	}
 	async mkdirp(params) {
 		const target = this.resolveTarget(params);
 		this.ensureWritable(target, "create directories");
@@ -914,7 +930,7 @@ function assertConfiguredPathExists(pathValue, source) {
 	} catch (err) {
 		if (isNodeError$1(err)) {
 			if (err.code === "ENOENT") throw new Error(`Sandbox policy path ${pathValue} configured by ${source} does not exist on the host. Create the path or update the policy file.`, { cause: err });
-			throw new Error(`Sandbox policy path ${pathValue} configured by ${source} is not accessible on the host: ${formatError(err)}`, { cause: err });
+			throw new Error(`Sandbox policy path ${pathValue} configured by ${source} is not accessible on the host: ${formatErrorMessage(err)}`, { cause: err });
 		}
 		throw err;
 	}
@@ -927,7 +943,7 @@ function assertPositiveFiniteNumber(value, label) {
 }
 function policyFileError(policyPath, err) {
 	if (isNodeError$1(err) && err.code === "ENOENT") return new Error(`Configured sandbox policy file ${policyPath} does not exist. Remove it from mxcPolicyPaths or create the file.`, { cause: err });
-	return new Error(`Failed to load sandbox policy file at ${policyPath}: ${formatError(err)}`, { cause: err instanceof Error ? err : void 0 });
+	return new Error(`Failed to load sandbox policy file at ${policyPath}: ${formatErrorMessage(err)}`, { cause: err instanceof Error ? err : void 0 });
 }
 function formatSandboxPolicyIssue(sourceLabel, issue) {
 	if (!issue) return `Sandbox policy at ${sourceLabel} is invalid.`;
@@ -950,10 +966,6 @@ function formatIssuePath(pathSegments) {
 	}
 	return label;
 }
-function formatError(err) {
-	if (err instanceof Error && err.message) return err.message;
-	return String(err);
-}
 function isNodeError$1(err) {
 	return err instanceof Error && "code" in err;
 }
@@ -1011,7 +1023,7 @@ function resolveWorkdirInsideWorkspace(workspaceDir, workdir) {
 	try {
 		if (statSync(candidate).isDirectory()) return candidate;
 	} catch (err) {
-		if (isNodeError(err) && err.code === "ENOENT") throw new Error(`MXC sandbox workdir ${workdir} does not exist.`, { cause: err });
+		if (isMissingPathError(err)) throw new Error(`MXC sandbox workdir ${workdir} does not exist.`, { cause: err });
 		throw err;
 	}
 	throw new Error(`MXC sandbox workdir ${workdir} is not a directory.`);
@@ -1020,7 +1032,7 @@ function realpathForExistingPath(value, label) {
 	try {
 		return realpathSync(path.resolve(value));
 	} catch (err) {
-		if (isNodeError(err) && err.code === "ENOENT") throw new Error(`MXC ${label} ${value} does not exist.`, { cause: err });
+		if (isMissingPathError(err)) throw new Error(`MXC ${label} ${value} does not exist.`, { cause: err });
 		throw err;
 	}
 }
@@ -1029,7 +1041,7 @@ function realpathForPotentialPath(value) {
 	try {
 		return realpathSync(resolved);
 	} catch (err) {
-		if (!isNodeError(err) || err.code !== "ENOENT") throw err;
+		if (!isMissingPathError(err)) throw err;
 		const parent = path.dirname(resolved);
 		if (parent === resolved) throw new Error(`MXC sandbox workdir ${value} does not exist.`, { cause: err });
 		return path.join(realpathForPotentialPath(parent), path.basename(resolved));
@@ -1038,6 +1050,9 @@ function realpathForPotentialPath(value) {
 function isNodeError(err) {
 	return err instanceof Error && "code" in err;
 }
+function isMissingPathError(err) {
+	return isNodeError(err) && (err.code === "ENOENT" || err.code === "ENOTDIR");
+}
 function buildMxcLauncherOptions(config, usePty) {
 	const options = {
 		debug: config.debug ?? false,
@@ -1072,6 +1087,15 @@ function createMxcSandboxBackendHandle(params) {
 		runtimeId: params.runtimeId,
 		runtimeLabel: params.runtimeId,
 		workdir: params.workdir,
+		workdirValidation: "backend",
+		async validateWorkdir(workdir) {
+			try {
+				return resolveWorkdirInsideWorkspace(params.workdir, workdir);
+			} catch (err) {
+				if (err instanceof Error && err.message.startsWith("MXC sandbox workdir")) return null;
+				throw err;
+			}
+		},
 		capabilities: {},
 		async buildExecSpec({ command, workdir, env, usePty }) {
 			const effectiveWorkdir = resolveWorkdirInsideWorkspace(params.workdir, workdir ?? params.workdir);
@@ -1210,6 +1234,7 @@ const mxcSandboxBackendManager = {
 //#endregion
 //#region extensions/mxc/src/mxc-backend-factory.ts
 function sanitizeRuntimeId(value) {
+	if (/:workspace:[a-f0-9]{32}$/i.test(value.trim())) return `openclaw-mxc-workspace-${createHash("sha256").update(value).digest("hex").slice(0, 32)}`;
 	const slug = value.toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
 	const hash = createHash("sha256").update(value).digest("hex").slice(0, 8);
 	return `openclaw-mxc-${slug || "sandbox"}-${hash}`;

package/dist/mxc-spawn-launcher.mjs

@@ -35,9 +35,9 @@ export function forwardSignals(spawned, options = {}) {
     if (exitTimer) {
       return;
     }
-    const setTimeoutFn = options.setTimeout ?? setTimeout;
+    const setTimeoutFn = options.setTimeout?.bind(undefined) ?? setTimeout;
     exitTimer = setTimeoutFn(() => {
-      const exit = options.exit ?? process.exit;
+      const exit = options.exit?.bind(undefined) ?? ((code) => process.exit(code));
       exit(signalExitCode(signal));
     }, exitGraceMs);
     exitTimer?.unref?.();
@@ -86,11 +86,37 @@ function bridgeChildProcess(child) {
 
 export function exitOnChildProcessClose(child, options = {}) {
   child.on("close", (exitCode, signal) => {
-    const exit = options.exit ?? process.exit;
+    const exit = options.exit?.bind(undefined) ?? ((code) => process.exit(code));
     exit(typeof exitCode === "number" ? exitCode : signalExitCode(signal));
   });
 }
 
+function attachPtyProcess(spawned) {
+  bridgeStdio(spawned);
+  forwardSignals(spawned);
+  spawned.onExit(({ exitCode, signal }) => {
+    process.exit(typeof exitCode === "number" ? exitCode : signalExitCode(signal));
+  });
+}
+
+function attachChildProcess(spawned) {
+  bridgeChildProcess(spawned);
+  forwardSignals(spawned);
+  exitOnChildProcessClose(spawned);
+}
+
+export async function launchSandbox(spawnSandboxFromConfig, config, options, bridges = {}) {
+  // Normalize sync and Promise-returning SDK implementations before selecting an I/O bridge.
+  const spawned = await spawnSandboxFromConfig(config, options ?? {});
+
+  if (typeof spawned.onData === "function") {
+    (bridges.pty ?? attachPtyProcess)(spawned);
+    return;
+  }
+
+  (bridges.child ?? attachChildProcess)(spawned);
+}
+
 const SIGNAL_NUMBERS = new Map([
   ["SIGHUP", 1],
   ["SIGINT", 2],
@@ -123,20 +149,7 @@ export async function main() {
   try {
     const { config, options } = decodePayload(process.argv.slice(2));
     const { spawnSandboxFromConfig } = await import("@microsoft/mxc-sdk");
-    const spawned = await spawnSandboxFromConfig(config, options ?? {});
-
-    if (typeof spawned.onData === "function") {
-      bridgeStdio(spawned);
-      forwardSignals(spawned);
-      spawned.onExit(({ exitCode, signal }) => {
-        process.exit(typeof exitCode === "number" ? exitCode : signalExitCode(signal));
-      });
-      return;
-    }
-
-    bridgeChildProcess(spawned);
-    forwardSignals(spawned);
-    exitOnChildProcessClose(spawned);
+    await launchSandbox(spawnSandboxFromConfig, config, options);
   } catch (error) {
     process.stderr.write(`${formatErrorStack(error)}\n`);
     process.exit(127);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/mxc-sandbox",
-  "version": "2026.7.2-beta.5",
+  "version": "2026.8.1-beta.2",
   "description": "OpenClaw MXC sandbox execution plugin for MXC-capable hosts",
   "repository": {
     "type": "git",
@@ -21,10 +21,10 @@
       "minHostVersion": ">=2026.6.11"
     },
     "compat": {
-      "pluginApi": ">=2026.7.2-beta.5"
+      "pluginApi": ">=2026.8.1-beta.2"
     },
     "build": {
-      "openclawVersion": "2026.7.2-beta.5",
+      "openclawVersion": "2026.8.1-beta.2",
       "bundledDist": false,
       "staticAssets": [
         {
@@ -47,7 +47,7 @@
     "README.md"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.7.2-beta.5"
+    "openclaw": ">=2026.8.1-beta.2"
   },
   "peerDependenciesMeta": {
     "openclaw": {