@openclaw/mxc-sandbox 2026.9.7 → 2026.9.9

package/README.md

@@ -38,7 +38,9 @@ readiness behavior to change as MXC host support matures.
 
 - Plugin id: `mxc`
 - Package: `@openclaw/mxc-sandbox`
-- Minimum OpenClaw host: `2026.6.11`
+- Minimum OpenClaw install host: `2026.6.11`
+- Plugin API host requirement: `2026.9.6` or newer. An older host cannot run
+  the current plugin even if the MXC executor is updated.
 
 ## Plugin config
 
@@ -48,7 +50,7 @@ and out-of-range values fail plugin activation with an actionable error
 
 | Field            | Type                              | Default                                | Notes                                                                                                                                                         |
 | ---------------- | --------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mxcBinaryPath`  | `string`                          | unset                                  | Non-empty override for the `wxc-exec.exe` executor path; see [SDK-only executor discovery](#supported).                                                       |
+| `mxcBinaryPath`  | `string`                          | unset                                  | Non-empty override for a compatible `wxc-exec.exe` supporting `--probe`; see [Host readiness](#host-readiness).                                               |
 | `containment`    | `"process" \| "processcontainer"` | `"process"`                            | Both currently resolve to Windows ProcessContainer.                                                                                                           |
 | `network`        | `"none" \| "default"`             | `"none"`                               | `"default"` allows outbound network via the `internetClient` capability.                                                                                      |
 | `timeoutSeconds` | `number`                          | unset (baseline default `300` applies) | Must be `>= 1` and `<= 2147000` (the largest Node-safe `setTimeout` delay in whole seconds). Capped to the sandbox policy baseline timeout when both are set. |
@@ -86,7 +88,7 @@ help stay in sync with plugin runtime validation.
 - OpenClaw passes per-run command, environment, and filesystem config to the
   plugin's Node launcher through a short-lived local payload file, and deletes
   that file and its temp directory when the launcher or run finishes.
-- `@microsoft/mxc-sdk@0.7.0` then carries the full base64 request envelope on
+- `@microsoft/mxc-sdk@0.8.0` then carries the full base64 request envelope on
   the native `wxc-exec` process argv. A host user with process-inspection rights
   can observe that command, environment, and policy data while the process is
   running. Do not put secrets in MXC command arguments or environment values
@@ -257,8 +259,33 @@ agents may still use them.
 
 ## Host readiness
 
-IsoEnvBroker must be available on the host OS. The plugin checks this before
-registering the sandbox backend.
+Before registering the sandbox backend, the plugin runs the MXC executor's own
+host probe (`wxc-exec --probe`) and requires it to select an isolation tier
+(`base-container`, `appcontainer-bfs`, or `appcontainer-dacl`). It probes the
+same executor it launches, including an `mxcBinaryPath` override. MXC's tier
+degradation warnings are logged but do not block activation. To inspect a host,
+run the executor directly:
+
+```powershell
+& node_modules\@microsoft\mxc-sdk\bin\x64\wxc-exec.exe --probe
+```
+
+Use `bin\arm64` on Arm64 hosts.
+
+An existing `mxcBinaryPath` override must point to an MXC 0.8.0-compatible
+executor that supports `--probe`. An older executor stops plugin activation;
+the plugin cannot safely infer readiness from a Windows service name or probe a
+different binary. If the override fails, run that exact executable with
+`--probe` to see its error. Update the override to a compatible executor, or
+remove it to use the `@microsoft/mxc-sdk@0.8.0` executor installed with the
+plugin:
+
+```powershell
+openclaw config unset plugins.entries.mxc.config.mxcBinaryPath
+```
+
+Restart the Gateway after changing the override. If the SDK executor also
+fails `--probe`, address the reported host-readiness error before retrying.
 
 Host preparation is advisory. If directory listing inside the sandbox fails with
 `Access is denied`, run this once from an elevated prompt:

package/dist/index.js

@@ -509,7 +509,6 @@ function buildLauncherEnv(hostEnv = process.env) {
 //#endregion
 //#region extensions/mxc/src/mxc-container-config.ts
 const MXC_SCHEMA_VERSION = "0.7.0-alpha";
-const PROCESS_CONTAINER_NAME_MAX_LEN = 64;
 function resolveCurrentBaselineContext(projectDir) {
 	return {
 		projectDir: path.resolve(projectDir),
@@ -559,7 +558,10 @@ function buildMxcContainerConfig(params) {
 		version: MXC_SCHEMA_VERSION,
 		containerId: params.containerId,
 		containment: params.config.containment,
-		lifecycle: { destroyOnExit: true },
+		lifecycle: {
+			destroyOnExit: true,
+			preservePolicy: false
+		},
 		process: {
 			commandLine: buildCommandLine(params.command, params.args ?? []),
 			cwd: params.workdir,
@@ -577,7 +579,6 @@ function buildMxcContainerConfig(params) {
 			enforcementMode: "capabilities"
 		},
 		processContainer: {
-			name: processContainerName(params.runtimeId),
 			leastPrivilege: true,
 			capabilities: networkAllowed ? ["internetClient"] : [],
 			ui: {
@@ -617,8 +618,7 @@ function buildFilesystemConfig(params) {
 	return {
 		readonlyPaths,
 		deniedPaths: void 0,
-		readwritePaths,
-		clearPolicyOnExit: true
+		readwritePaths
 	};
 }
 function resolveWorkspaceReadwritePathSpecs(workspace) {
@@ -698,11 +698,6 @@ function buildMissingFilesystemPathMessage(pathValue, accessLabel, sources) {
 	if (sourceLabel) return `MXC sandbox ${accessLabel} path ${pathValue} configured by ${sourceLabel} is missing on the host. Recreate the path or update the policy file before launching the sandbox.`;
 	return `MXC sandbox ${accessLabel} path ${pathValue} does not exist on the host.`;
 }
-function processContainerName(runtimeId) {
-	if (runtimeId.length <= PROCESS_CONTAINER_NAME_MAX_LEN) return runtimeId;
-	const hash = createHash("sha256").update(runtimeId).digest("hex").slice(0, 8);
-	return `${runtimeId.slice(0, PROCESS_CONTAINER_NAME_MAX_LEN - hash.length - 1)}-${hash}`;
-}
 function resolveProcessTimeoutSeconds(config, baseline) {
 	if (config.timeoutSecondsConfigured === true) return Math.min(config.timeoutSeconds, baseline.process.timeoutSeconds);
 	return baseline.process.timeoutSeconds;
@@ -904,7 +899,7 @@ function isNodeError(err) {
 }
 //#endregion
 //#region extensions/mxc/src/mxc-backend.ts
-const CONTAINER_ID_MAX_LEN = 80;
+const CONTAINER_ID_MAX_LEN = 64;
 function uniqueContainerId(runtimeId) {
 	const suffix = randomBytes(4).toString("hex");
 	return `${runtimeId.length + suffix.length + 1 > CONTAINER_ID_MAX_LEN ? runtimeId.slice(0, CONTAINER_ID_MAX_LEN - suffix.length - 1) : runtimeId}-${suffix}`;
@@ -1028,7 +1023,6 @@ function createMxcSandboxBackendHandle(params) {
 					config: params.config,
 					baseline,
 					baselineContext,
-					runtimeId: params.runtimeId,
 					containerId: uniqueContainerId(params.runtimeId),
 					command,
 					sandboxTempDir,
@@ -1083,7 +1077,6 @@ function createMxcSandboxBackendHandle(params) {
 					config: restrictiveConfig,
 					baseline,
 					baselineContext,
-					runtimeId: params.runtimeId,
 					containerId: uniqueContainerId(params.runtimeId),
 					command: commandBridge.command,
 					args: cmdParams.args,
@@ -1173,22 +1166,46 @@ function createMxcSandboxBackendFactory(config) {
 //#endregion
 //#region extensions/mxc/src/readiness.ts
 const DEFAULT_DEPS = { execFileSync };
+const MxcProbeOutputSchema = z.object({
+	tier: z.enum([
+		"base-container",
+		"appcontainer-bfs",
+		"appcontainer-dacl"
+	]).optional(),
+	warnings: z.array(z.string()).default([]),
+	error: z.string().optional()
+});
 function resolveWindowsSystemExecutable(name) {
 	const systemRoot = process.env.SystemRoot || process.env.WINDIR;
 	return path.win32.join(systemRoot || "C:\\Windows", "System32", name);
 }
-function assertWindowsIsoEnvBrokerInstalled(deps) {
+function probeMxcIsolationTier(executablePath, deps) {
+	const notReady = (reason, cause) => new Error(`[mxc] MXC Windows ProcessContainer sandbox is not ready: ${reason}. Run "${executablePath}" --probe for host details. The selected executor must be compatible with MXC 0.8.0 and support --probe. If mxcBinaryPath points to an older executor, update it or unset plugins.entries.mxc.config.mxcBinaryPath and restart the Gateway to use the bundled SDK executor.`, cause === void 0 ? void 0 : { cause });
+	let output;
 	try {
-		deps.execFileSync(resolveWindowsSystemExecutable("sc.exe"), ["query", "IsoEnvBroker"], {
+		output = deps.execFileSync(executablePath, ["--probe"], {
 			encoding: "utf-8",
 			stdio: "pipe",
-			timeout: 5e3,
+			timeout: 15e3,
 			windowsHide: true
 		});
 	} catch (error) {
-		const detail = error instanceof Error && error.message ? `: ${error.message.trim()}` : "";
-		throw new Error(`[mxc] MXC Windows ProcessContainer sandbox is not ready: IsoEnvBroker service is not installed${detail}. Install the IsoEnvBroker service before enabling MXC sandbox execution.`, { cause: error });
+		throw notReady(`the MXC host probe failed${error instanceof Error && error.message ? `: ${error.message.trim()}` : ""}`, error);
 	}
+	let probe;
+	try {
+		probe = JSON.parse(output);
+	} catch (error) {
+		throw notReady("the MXC host probe did not return JSON", error);
+	}
+	const parsed = MxcProbeOutputSchema.safeParse(probe);
+	if (!parsed.success) throw notReady("the MXC host probe returned an unexpected result", parsed.error);
+	const { tier, warnings, error } = parsed.data;
+	if (!tier) throw notReady(`MXC cannot select an isolation tier on this host (${error || "the probe reported no isolation tier"})`);
+	return {
+		tier,
+		warnings
+	};
 }
 function isSystemDrivePrepared(deps) {
 	const systemDrive = process.env.SystemDrive || "C:";
@@ -1219,12 +1236,19 @@ function warnMxcHostPrepIfNeeded(params = {}) {
 		...params.deps
 	})) (params.warn ?? ((message) => console.warn(message)))(systemDrivePrepWarning(process.env.SystemDrive || "C:"));
 }
-function assertMxcReadiness(params = {}) {
+/**
+* Fails plugin activation unless MXC's host probe selects an isolation tier for
+* `executablePath`. Degradation warnings from the probe are reported but do not
+* block activation.
+*/
+function assertMxcReadiness(params) {
 	if ((params.platform ?? process.platform) !== "win32") return;
-	assertWindowsIsoEnvBrokerInstalled({
+	const deps = {
 		...DEFAULT_DEPS,
 		...params.deps
-	});
+	};
+	const probe = probeMxcIsolationTier(params.executablePath, deps);
+	if (probe.warnings.length > 0) (params.warn ?? ((message) => console.warn(message)))(`[mxc] MXC sandbox is using the ${probe.tier} isolation tier: ${probe.warnings.join("; ")}`);
 }
 //#endregion
 //#region extensions/mxc/src/plugin.ts
@@ -1235,13 +1259,14 @@ function registerMxcPlugin(api) {
 		console.warn(`[mxc] Sandbox backend is Windows-only and not available on ${process.platform}. Plugin will be dormant.`);
 		return;
 	}
+	let mxcBinaryPath;
 	try {
-		resolveMxcBinaryPath(config.mxcBinaryPath);
+		mxcBinaryPath = resolveMxcBinaryPath(config.mxcBinaryPath);
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
 		throw new Error(`[mxc] MXC sandbox backend cannot load: ${reason}. Install @microsoft/mxc-sdk or set mxcBinaryPath.`, { cause: err });
 	}
-	assertMxcReadiness();
+	assertMxcReadiness({ executablePath: mxcBinaryPath });
 	warnMxcHostPrepIfNeeded();
 	const unregister = registerSandboxBackend("mxc", {
 		factory: createMxcSandboxBackendFactory(config),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/mxc-sandbox",
-  "version": "2026.9.7",
+  "version": "2026.9.9",
   "description": "OpenClaw MXC sandbox execution plugin for MXC-capable hosts",
   "repository": {
     "type": "git",
@@ -22,10 +22,10 @@
       "minHostVersion": ">=2026.6.11"
     },
     "compat": {
-      "pluginApi": ">=2026.9.7"
+      "pluginApi": ">=2026.9.9"
     },
     "build": {
-      "openclawVersion": "2026.9.7",
+      "openclawVersion": "2026.9.9",
       "bundledDist": false,
       "staticAssets": [
         {
@@ -50,7 +50,7 @@
     "assets/activity.svg"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.9.7"
+    "openclaw": ">=2026.9.9"
   },
   "peerDependenciesMeta": {
     "openclaw": {