@openclaw/mxc-sandbox 2026.9.1-beta.1 → 2026.9.2

package/README.md

@@ -101,44 +101,36 @@ help stay in sync with plugin runtime validation.
 - Windows filesystem-deny and host-list network policy knobs are not exposed by
   this plugin until MXC can enforce them on ProcessContainer.
 
-## Test setup with `openclaw config`
+## Test setup
 
-This patch creates a default `main` agent, then adds a dedicated `mxc-test`
-agent so MXC testing does not change the default agent. It uses
+Use an already configured OpenClaw installation with MXC installed and enabled
+on a supported Windows host. These commands create a uniquely named test agent
+and a new temporary workspace, leaving existing agents and workspaces alone.
 [`openclaw config patch --stdin`](https://docs.openclaw.ai/cli/config#config-patch)
-so setup is one validated config write instead of several path-based
-`config set` commands.
+applies sandbox settings only to that agent. Installation-wide MXC settings
+and policy files remain unchanged; review them before testing because they
+apply to the test agent too.
 
-If you already have `agents.list` entries, copy them into the patch before
-`mxc-test` instead of replacing the list.
+Run setup, testing, and cleanup in the same PowerShell session. Finish cleanup
+before running setup again. Stop if any command fails.
 
 ```powershell
-$mxcPolicyPath = Join-Path $env:TEMP "openclaw-mxc-policy.json"
-@'
-{
-  "filesystem": {
-    "restrictToProjectDir": true,
-    "additionalReadonlyPaths": [],
-    "additionalReadwritePaths": []
-  },
-  "process": {
-    "timeoutSeconds": 120
-  }
-}
-'@ | Set-Content -Path $mxcPolicyPath -Encoding utf8
+$mxcAgentCreated = $false
+$mxcAgent = "mxc-test-" + [guid]::NewGuid().ToString("N")
+$mxcWorkspace = Join-Path ([System.IO.Path]::GetTempPath()) $mxcAgent
+New-Item -ItemType Directory -Path $mxcWorkspace -ErrorAction Stop | Out-Null
+
+openclaw agents add $mxcAgent `
+  --workspace $mxcWorkspace `
+  --non-interactive
+if ($LASTEXITCODE -ne 0) { throw "Agent creation failed; stop without patching or deleting an existing agent." }
+$mxcAgentCreated = $true
 
-$mxcPolicyPathLiteral = ConvertTo-Json $mxcPolicyPath -Compress
 $mxcConfigPatch = @"
 {
   agents: {
-    list: [
-      {
-        id: "main",
-        workspace: "~/.openclaw/workspace",
-      },
-      {
-        id: "mxc-test",
-        workspace: "~/.openclaw/workspace-mxc-test",
+    entries: {
+      "$mxcAgent": {
         sandbox: {
           mode: "all",
           backend: "mxc",
@@ -146,62 +138,15 @@ $mxcConfigPatch = @"
           workspaceAccess: "none",
         },
       },
-    ],
-  },
-  plugins: {
-    entries: {
-      mxc: {
-        enabled: true,
-        config: {
-          containment: "process",
-          network: "none",
-          mxcPolicyPaths: [$mxcPolicyPathLiteral],
-        },
-      },
     },
   },
 }
 "@
 
 $mxcConfigPatch | openclaw config patch --stdin --dry-run
+if ($LASTEXITCODE -ne 0) { throw "Sandbox validation failed; use Cleanup to remove the new test agent." }
 $mxcConfigPatch | openclaw config patch --stdin
-```
-
-Resulting config shape:
-
-```jsonc
-{
-  "agents": {
-    "list": [
-      {
-        "id": "main",
-        "workspace": "~/.openclaw/workspace",
-      },
-      {
-        "id": "mxc-test",
-        "workspace": "~/.openclaw/workspace-mxc-test",
-        "sandbox": {
-          "mode": "all",
-          "backend": "mxc",
-          "scope": "agent",
-          "workspaceAccess": "none",
-        },
-      },
-    ],
-  },
-  "plugins": {
-    "entries": {
-      "mxc": {
-        "enabled": true,
-        "config": {
-          "containment": "process",
-          "network": "none",
-          "mxcPolicyPaths": ["C:\\Users\\you\\AppData\\Local\\Temp\\openclaw-mxc-policy.json"],
-        },
-      },
-    },
-  },
-}
+if ($LASTEXITCODE -ne 0) { throw "Sandbox setup failed; use Cleanup to remove the new test agent." }
 ```
 
 ## Sandbox policy files
@@ -283,44 +228,33 @@ ProcessContainer cannot safely enforce the nested read-only grant.
 Run the TUI as that agent:
 
 ```powershell
-openclaw tui --session agent:mxc-test:main
+openclaw tui --session "agent:${mxcAgent}:main"
 ```
 
 For local embedded testing without a Gateway:
 
 ```powershell
-openclaw tui --local --session agent:mxc-test:main
+openclaw tui --local --session "agent:${mxcAgent}:main"
 ```
 
 ## Cleanup
 
-If you used the exact sample above, remove the test agent and MXC plugin
-configuration by patching the config back to the default-only shape:
+In the same PowerShell session, remove only the agent created by setup:
 
 ```powershell
-$mxcCleanupPatch = @'
-{
-  agents: {
-    list: [
-      {
-        id: "main",
-        workspace: "~/.openclaw/workspace",
-      },
-    ],
-  },
-  plugins: {
-    entries: {
-      mxc: null,
-    },
-  },
+if (-not $mxcAgentCreated) {
+  throw "No successfully created test agent in this session; do not delete an existing agent."
 }
-'@
-
-$mxcCleanupPatch | openclaw config patch --stdin --dry-run
-$mxcCleanupPatch | openclaw config patch --stdin
-Remove-Item -Path $mxcPolicyPath -ErrorAction SilentlyContinue
+openclaw agents delete $mxcAgent --force
+if ($LASTEXITCODE -ne 0) { throw "Agent cleanup failed; inspect the error before retrying." }
+$mxcAgentCreated = $false
 ```
 
+The delete command removes the test agent's configuration and attempts to move
+its workspace and state to Trash. Check its output for any manual-cleanup
+warning. Do not remove the MXC plugin entry or shared policy files: other
+agents may still use them.
+
 ## Host readiness
 
 IsoEnvBroker must be available on the host OS. The plugin checks this before
@@ -342,7 +276,7 @@ wxc-host-prep prepare-system-drive
 pnpm test:extension mxc
 ```
 
-`pnpm test extensions/mxc` is equivalent and also works.
+`pnpm test extensions/mxc` is also supported for the bundled extension test lane.
 
 For policy-only edits, the focused coverage is in:
 

package/dist/index.js

@@ -131,6 +131,12 @@ function resolveMxcBinaryPath(configOverride) {
 	return found;
 }
 //#endregion
+//#region extensions/mxc/src/path-comparison.ts
+function normalizeMxcPathForComparison(value) {
+	const resolved = path.resolve(value);
+	return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+//#endregion
 //#region extensions/mxc/src/workspace-skill-mounts.ts
 const MATERIALIZED_SANDBOX_SKILLS_WORKSPACE_PARTS = [".openclaw", "sandbox-skills"];
 function containerJoin(root, ...parts) {
@@ -299,7 +305,7 @@ function resolveWorkspaceMounts(sandbox) {
 		containerRoot,
 		writable: false
 	}];
-	if (sandbox.workspaceAccess === "ro" && normalizePathForComparison$1(agentWorkspaceDir) !== normalizePathForComparison$1(workspaceDir)) mounts.push({
+	if (sandbox.workspaceAccess === "ro" && normalizeMxcPathForComparison(agentWorkspaceDir) !== normalizeMxcPathForComparison(workspaceDir)) mounts.push({
 		hostRoot: agentWorkspaceDir,
 		containerRoot: agentWorkspaceDir,
 		writable: false
@@ -324,7 +330,7 @@ function normalizeMxcProtectedSkillMount(mount) {
 function dedupeAndSortMounts(mounts) {
 	const deduped = /* @__PURE__ */ new Map();
 	for (const mount of mounts) {
-		const key = `${normalizePathForComparison$1(mount.hostRoot)}::${normalizePathForComparison$1(mount.containerRoot)}`;
+		const key = `${normalizeMxcPathForComparison(mount.hostRoot)}::${normalizeMxcPathForComparison(mount.containerRoot)}`;
 		if (!deduped.has(key)) deduped.set(key, mount);
 	}
 	return [...deduped.values()].toSorted((left, right) => {
@@ -338,11 +344,7 @@ function resolveRelativeParentPath(relativePath) {
 	return parent === "." || parent === "" ? null : parent;
 }
 function isSameMountRoot(first, second) {
-	return normalizePathForComparison$1(first) === normalizePathForComparison$1(second);
-}
-function normalizePathForComparison$1(value) {
-	const resolved = path.resolve(value);
-	return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+	return normalizeMxcPathForComparison(first) === normalizeMxcPathForComparison(second);
 }
 //#endregion
 //#region extensions/mxc/src/sandbox-baseline.ts
@@ -646,7 +648,7 @@ function resolveWorkspaceReadwritePathSpecs(workspace) {
 function resolveWorkspaceReadonlyPathSpecs(workspace) {
 	if (workspace.workspaceAccess === "rw") return [];
 	const readonlyPathSpecs = [requiredFilesystemPath(workspace.workspaceDir)];
-	if (workspace.workspaceAccess === "ro" && normalizePathForComparison(workspace.agentWorkspaceDir) !== normalizePathForComparison(workspace.workspaceDir)) readonlyPathSpecs.push(requiredFilesystemPath(workspace.agentWorkspaceDir));
+	if (workspace.workspaceAccess === "ro" && normalizeMxcPathForComparison(workspace.agentWorkspaceDir) !== normalizeMxcPathForComparison(workspace.workspaceDir)) readonlyPathSpecs.push(requiredFilesystemPath(workspace.agentWorkspaceDir));
 	return readonlyPathSpecs;
 }
 function resolveBaselineReadonlyPathSpecs(baseline, context) {
@@ -656,9 +658,9 @@ function resolveMxcProtectedSkillPolicyPaths(context) {
 	const deduped = /* @__PURE__ */ new Map();
 	for (const mount of resolveMxcProtectedSkillMounts(context)) {
 		const hostPath = path.resolve(mount.hostPath);
-		deduped.set(normalizePathForComparison(hostPath), hostPath);
+		deduped.set(normalizeMxcPathForComparison(hostPath), hostPath);
 		const containerPath = path.resolve(mount.containerPath);
-		deduped.set(normalizePathForComparison(containerPath), containerPath);
+		deduped.set(normalizeMxcPathForComparison(containerPath), containerPath);
 	}
 	return [...deduped.values()];
 }
@@ -676,7 +678,7 @@ function resolveMxcProtectedSkillMounts(context) {
 function resolveExistingFilesystemPaths(pathSpecs, accessLabel) {
 	const deduped = /* @__PURE__ */ new Map();
 	for (const pathSpec of pathSpecs) {
-		const key = normalizePathForComparison(pathSpec.path);
+		const key = normalizeMxcPathForComparison(pathSpec.path);
 		const existing = deduped.get(key);
 		if (existing) {
 			existing.required ||= pathSpec.required;
@@ -740,14 +742,10 @@ function assertNoMxcReadwriteReadonlyOverlap(params) {
 	for (const readwritePath of params.readwritePaths) for (const readonlyPath of params.readonlyPaths) if (pathsOverlap(readwritePath, readonlyPath)) throw new Error(`MXC readwrite path ${readwritePath} overlaps read-only path ${readonlyPath}. Windows MXC cannot safely enforce nested read-only overlays under writable paths.`);
 }
 function pathsOverlap(first, second) {
-	const left = normalizePathForComparison(first);
-	const right = normalizePathForComparison(second);
+	const left = normalizeMxcPathForComparison(first);
+	const right = normalizeMxcPathForComparison(second);
 	return isPathInside(left, right) || isPathInside(right, left);
 }
-function normalizePathForComparison(value) {
-	const resolved = path.resolve(value);
-	return process.platform === "win32" ? resolved.toLowerCase() : resolved;
-}
 function hostPathExists(candidatePath) {
 	try {
 		statSync(candidatePath);
@@ -1180,8 +1178,8 @@ function createMxcSandboxBackendHandle(params) {
 						baseEnv: buildLauncherEnv(),
 						input: execInput,
 						maxOutputBytes: {
-							stdout: 10 * 1024 * 1024,
-							stderr: 10 * 1024 * 1024
+							stdout: 10485760,
+							stderr: 10485760
 						},
 						signal: cmdParams.signal,
 						timeoutMs: 3e4
@@ -1329,11 +1327,11 @@ function registerMxcPlugin(api) {
 		factory: createMxcSandboxBackendFactory(config),
 		manager: mxcSandboxBackendManager
 	});
-	api.registerService({
+	api.lifecycle.registerRuntimeLifecycle({
 		id: "mxc-sandbox-cleanup",
-		start() {},
-		stop() {
-			unregister();
+		cleanup: ({ reason, sessionKey, runId }) => {
+			if (sessionKey !== void 0 || runId !== void 0) return;
+			if (reason === "disable" || reason === "restart") unregister();
 		}
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/mxc-sandbox",
-  "version": "2026.9.1-beta.1",
+  "version": "2026.9.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.9.1-beta.1"
+      "pluginApi": ">=2026.9.2"
     },
     "build": {
-      "openclawVersion": "2026.9.1-beta.1",
+      "openclawVersion": "2026.9.2",
       "bundledDist": false,
       "staticAssets": [
         {
@@ -47,7 +47,7 @@
     "README.md"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.9.1-beta.1"
+    "openclaw": ">=2026.9.2"
   },
   "peerDependenciesMeta": {
     "openclaw": {