@openclaw/openshell-sandbox 2026.7.2-beta.5 → 2026.7.2-beta.7

package/README.md

@@ -4,6 +4,14 @@ Official NVIDIA OpenShell sandbox backend for OpenClaw.
 
 This plugin lets OpenClaw use OpenShell-managed sandboxes with mirrored local workspaces and SSH command execution.
 
+Configuring an OpenShell workspace requires OpenShell `v0.0.88` or newer. The
+plugin supports OpenShell control-plane workspaces through
+`plugins.entries.openshell.config.workspace`; this is separate from OpenClaw's
+local/remote filesystem workspace mode. The setting applies to the whole plugin
+instance, not individual agents or sessions. When unset, the plugin preserves
+the OpenShell CLI's ambient `OPENSHELL_WORKSPACE` selection, or its `default`
+fallback when no ambient selection exists.
+
 ## Install
 
 ```bash

package/dist/index.js

@@ -1,5 +1,6 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { buildRemoteWorkdirValidationCommand, buildValidatedExecRemoteCommand, createRemoteShellSandboxFsBridge, createSshSandboxSessionFromConfigText, createWritableRenameTargetResolver, disposeSshSandboxSession, registerSandboxBackend, resolvePreferredOpenClawTmpDir, runPluginCommandWithTimeout, runSshSandboxCommand, sanitizeEnvVars, shellEscape, withTempWorkspace } from "openclaw/plugin-sdk/sandbox";
+import { createHash } from "node:crypto";
 import fsPromises from "node:fs/promises";
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
@@ -15,6 +16,7 @@ function buildOpenShellBaseArgv(config) {
 	const argv = [config.command];
 	if (config.gateway) argv.push("--gateway", config.gateway);
 	if (config.gatewayEndpoint) argv.push("--gateway-endpoint", config.gatewayEndpoint);
+	if (config.workspace) argv.push("--workspace", config.workspace);
 	return argv;
 }
 function buildRemoteCommand(argv) {
@@ -73,11 +75,13 @@ function normalizeProviders(value) {
 	return providers;
 }
 const nonEmptyTrimmedString = (message) => z.string({ error: message }).trim().min(1, { error: message });
+const openShellWorkspaceName = z.string({ error: "workspace must be a valid OpenShell workspace name" }).trim().min(1, { error: "workspace must be a valid OpenShell workspace name" }).max(19, { error: "workspace must be at most 19 characters" }).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { error: "workspace must contain lowercase alphanumeric characters or single hyphens and must not start or end with a hyphen" });
 const OpenShellPluginConfigSchema = z.strictObject({
 	mode: z.enum(["mirror", "remote"], { error: "mode must be one of mirror, remote" }).optional(),
 	command: nonEmptyTrimmedString("command must be a non-empty string").optional(),
 	gateway: nonEmptyTrimmedString("gateway must be a non-empty string").optional(),
 	gatewayEndpoint: nonEmptyTrimmedString("gatewayEndpoint must be a non-empty string").optional(),
+	workspace: openShellWorkspaceName.optional(),
 	from: nonEmptyTrimmedString("from must be a non-empty string").optional(),
 	policy: nonEmptyTrimmedString("policy must be a non-empty string").optional(),
 	providers: z.array(z.string({ error: "providers must be an array of strings" }).trim().min(1, { error: "providers must be an array of strings" }), { error: "providers must be an array of strings" }).optional(),
@@ -120,6 +124,7 @@ function resolveOpenShellPluginConfig(value) {
 		command: DEFAULT_COMMAND,
 		gateway: void 0,
 		gatewayEndpoint: void 0,
+		workspace: void 0,
 		from: DEFAULT_SOURCE,
 		policy: void 0,
 		providers: [],
@@ -140,6 +145,7 @@ function resolveOpenShellPluginConfig(value) {
 		command: cfg.command ?? DEFAULT_COMMAND,
 		gateway: cfg.gateway,
 		gatewayEndpoint: cfg.gatewayEndpoint,
+		workspace: cfg.workspace,
 		from: cfg.from ?? DEFAULT_SOURCE,
 		policy: cfg.policy,
 		providers: normalizeProviders(cfg.providers),
@@ -185,7 +191,12 @@ var OpenShellFsBridge = class {
 				allowMissingLeaf: false,
 				allowFinalSymlinkForUnlink: false
 			});
-			opened = await (await root(target.mountHostRoot)).open(path.relative(target.mountHostRoot, hostPath), { hardlinks: "reject" });
+			const root$1 = await root(target.mountHostRoot);
+			if (params.maxBytes !== void 0) return (await root$1.read(path.relative(target.mountHostRoot, hostPath), {
+				hardlinks: "reject",
+				maxBytes: params.maxBytes
+			})).buffer;
+			opened = await root$1.open(path.relative(target.mountHostRoot, hostPath), { hardlinks: "reject" });
 			try {
 				return await opened.handle.readFile();
 			} finally {
@@ -209,6 +220,27 @@ var OpenShellFsBridge = class {
 		await (await root(target.mountHostRoot)).write(path.relative(target.mountHostRoot, hostPath), buffer, { mkdir: params.mkdir });
 		await this.backend.syncLocalPathToRemote(hostPath, target.containerPath);
 	}
+	async createFileExclusive(params) {
+		const target = this.resolveTarget(params);
+		const hostPath = this.requireHostPath(target);
+		this.ensureWritable(target, "create files");
+		await assertLocalPathSafety({
+			target,
+			root: target.mountHostRoot,
+			allowMissingLeaf: true,
+			allowFinalSymlinkForUnlink: false
+		});
+		const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.from(params.data, params.encoding ?? "utf8");
+		const root$2 = await root(target.mountHostRoot);
+		try {
+			await root$2.create(path.relative(target.mountHostRoot, hostPath), buffer, { mkdir: params.mkdir !== false });
+		} catch (error) {
+			if (error instanceof FsSafeError && error.code === "already-exists") return "exists";
+			throw error;
+		}
+		await this.backend.syncLocalPathToRemote(hostPath, target.containerPath);
+		return "created";
+	}
 	async mkdirp(params) {
 		const target = this.resolveTarget(params);
 		const hostPath = this.requireHostPath(target);
@@ -395,7 +427,7 @@ async function mkdirLocalRootPath(params) {
 	await (await root(params.target.mountHostRoot)).mkdir(relativePath);
 }
 async function removeLocalRootPath(params) {
-	const root$1 = await root(params.target.mountHostRoot);
+	const root$3 = await root(params.target.mountHostRoot);
 	const relativePath = relativeToRoot(params.target, params.hostPath);
 	try {
 		if (params.force === false) await fsPromises.lstat(params.hostPath);
@@ -404,13 +436,13 @@ async function removeLocalRootPath(params) {
 				if (isNotFoundError(err)) return null;
 				throw err;
 			}))?.isSymbolicLink()) {
-				await root$1.remove(relativePath);
+				await root$3.remove(relativePath);
 				return;
 			}
-			await removeRootTree(root$1, relativePath);
+			await removeRootTree(root$3, relativePath);
 			return;
 		}
-		await root$1.remove(relativePath);
+		await root$3.remove(relativePath);
 	} catch (err) {
 		if (params.force !== false && isNotFoundError(err)) return;
 		throw err;
@@ -426,11 +458,11 @@ async function removeRootTree(root, relativePath, knownStats) {
 	await root.remove(relativePath);
 }
 async function moveLocalRootPath(params) {
-	const root$2 = await root(params.from.mountHostRoot);
+	const root$4 = await root(params.from.mountHostRoot);
 	const fromRelativePath = relativeToRoot(params.from, params.fromHostPath);
 	const toRelativePath = relativeToRoot(params.to, params.toHostPath);
-	await mkdirParentPath(root$2, toRelativePath);
-	await root$2.move(fromRelativePath, toRelativePath, { overwrite: true });
+	await mkdirParentPath(root$4, toRelativePath);
+	await root$4.move(fromRelativePath, toRelativePath, { overwrite: true });
 }
 async function mkdirParentPath(root, relativePath) {
 	const parentPath = path.dirname(relativePath);
@@ -813,7 +845,11 @@ function createOpenShellSandboxBackendManager(params) {
 }
 async function createOpenShellSandboxBackend(params) {
 	if ((params.createParams.cfg.docker.binds?.length ?? 0) > 0) throw new Error("OpenShell sandbox backend does not support sandbox.docker.binds.");
-	const sandboxName = buildOpenShellSandboxName(params.createParams.scopeKey);
+	const resolvedSandboxName = resolveOpenShellSandboxName({
+		scopeKey: params.createParams.scopeKey,
+		registeredRuntimeIds: params.createParams.registeredRuntimeIds
+	});
+	const sandboxName = resolvedSandboxName.sandboxName;
 	const execContext = {
 		config: params.pluginConfig,
 		sandboxName
@@ -821,6 +857,7 @@ async function createOpenShellSandboxBackend(params) {
 	const impl = new OpenShellSandboxBackendImpl({
 		createParams: params.createParams,
 		execContext,
+		legacyRuntimeAdopted: resolvedSandboxName.legacyRuntimeAdopted,
 		remoteWorkspaceDir: params.pluginConfig.remoteWorkspaceDir,
 		remoteAgentWorkspaceDir: params.pluginConfig.remoteAgentWorkspaceDir
 	});
@@ -1169,7 +1206,7 @@ var OpenShellSandboxBackendImpl = class {
 		}
 	}
 	async ensureSandboxExistsInner() {
-		if ((await runOpenShellCli({
+		const getResult = await runOpenShellCli({
 			context: this.params.execContext,
 			args: [
 				"sandbox",
@@ -1177,7 +1214,16 @@ var OpenShellSandboxBackendImpl = class {
 				this.params.execContext.sandboxName
 			],
 			cwd: this.params.createParams.workspaceDir
-		})).code === 0) return;
+		});
+		if (getResult.code === 0) {
+			if (this.params.legacyRuntimeAdopted) {
+				const phase = await this.resolveLegacyRuntimePhase();
+				if (!phase) throw this.buildLegacyRuntimeUnavailableError("OpenShell did not report a lifecycle phase for this sandbox.");
+				if (phase !== "Ready") throw this.buildLegacyRuntimeUnavailableError(`OpenShell reports phase "${phase}".`);
+			}
+			return;
+		}
+		if (this.params.legacyRuntimeAdopted) throw this.buildLegacyRuntimeUnavailableError(getResult.stderr.trim());
 		const createArgs = [
 			"sandbox",
 			"create",
@@ -1201,6 +1247,38 @@ var OpenShellSandboxBackendImpl = class {
 		if (createResult.code !== 0) throw new Error(createResult.stderr.trim() || "openshell sandbox create failed");
 		this.remoteSeedPending = true;
 	}
+	async resolveLegacyRuntimePhase() {
+		const pageSize = 100;
+		for (let offset = 0;; offset += pageSize) {
+			const listResult = await runOpenShellCli({
+				context: this.params.execContext,
+				args: [
+					"sandbox",
+					"list",
+					"--limit",
+					String(pageSize),
+					"--offset",
+					String(offset),
+					"--output",
+					"json"
+				],
+				cwd: this.params.createParams.workspaceDir
+			});
+			if (listResult.code !== 0) throw this.buildLegacyRuntimeUnavailableError(listResult.stderr.trim());
+			const page = parseOpenShellSandboxPhasePage(listResult.stdout, this.params.execContext.sandboxName);
+			if (!page) throw this.buildLegacyRuntimeUnavailableError("OpenShell returned malformed sandbox lifecycle data.");
+			if (page.phase) return page.phase;
+			if (page.count < pageSize) return;
+		}
+	}
+	buildLegacyRuntimeUnavailableError(detail) {
+		const recreateCommand = `openclaw sandbox recreate --session ${shellEscape(this.params.createParams.scopeKey)}`;
+		return new Error([
+			`Registered legacy OpenShell sandbox "${this.params.execContext.sandboxName}" is not usable.`,
+			detail,
+			`OpenClaw will not recreate this retired runtime name. Run \`${recreateCommand}\` to migrate this scope to the current naming format.`
+		].filter(Boolean).join(" "));
+	}
 	async syncWorkspaceToRemote() {
 		await this.runRemoteShellScriptInternal({
 			script: "mkdir -p -- \"$1\" && find \"$1\" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +",
@@ -1307,11 +1385,52 @@ function resolveOpenShellPluginConfigFromConfig(config, fallback) {
 	return resolveOpenShellPluginConfig(pluginConfig);
 }
 function buildOpenShellSandboxName(scopeKey) {
+	const trimmed = scopeKey.trim() || "session";
+	if (/:workspace:[a-f0-9]{32}$/i.test(trimmed)) {
+		const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 20);
+		return `oc-${BigInt(`0x${hash}`).toString(36).padStart(16, "0")}`;
+	}
+	return `oc-${createHash("sha256").update(trimmed).digest("hex").slice(0, 16)}`;
+}
+function buildLegacyOpenShellSandboxName(scopeKey) {
 	const trimmed = scopeKey.trim() || "session";
 	const safe = normalizeLowercaseStringOrEmpty(trimmed).replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
 	const hash = Array.from(trimmed).reduce((acc, char) => (acc * 33 ^ char.charCodeAt(0)) >>> 0, 5381);
 	return `openclaw-${safe || "session"}-${hash.toString(16).slice(0, 8)}`;
 }
+function resolveOpenShellSandboxName(params) {
+	const sandboxName = buildOpenShellSandboxName(params.scopeKey);
+	if (params.registeredRuntimeIds?.includes(sandboxName)) return {
+		sandboxName,
+		legacyRuntimeAdopted: false
+	};
+	const legacySandboxName = buildLegacyOpenShellSandboxName(params.scopeKey);
+	if (params.registeredRuntimeIds?.includes(legacySandboxName)) return {
+		sandboxName: legacySandboxName,
+		legacyRuntimeAdopted: true
+	};
+	return {
+		sandboxName,
+		legacyRuntimeAdopted: false
+	};
+}
+function parseOpenShellSandboxPhasePage(stdout, sandboxName) {
+	try {
+		const parsed = JSON.parse(stdout);
+		if (!Array.isArray(parsed)) return;
+		for (const entry of parsed) {
+			if (!entry || typeof entry !== "object") continue;
+			const record = entry;
+			if (record.name === sandboxName && typeof record.phase === "string") return {
+				count: parsed.length,
+				phase: record.phase
+			};
+		}
+		return { count: parsed.length };
+	} catch {
+		return;
+	}
+}
 function resolveRemoteMaterializedSkillsWorkspaceDir(remoteWorkspaceDir) {
 	const root = remoteWorkspaceDir.replace(/\\/g, "/").replace(/\/+$/, "") || "/";
 	return path.posix.join(root, ...MATERIALIZED_SKILLS_REMOTE_PARTS);

package/node_modules/p-limit/index.d.ts

@@ -17,7 +17,7 @@ export type LimitFunction = {
 	/**
 	Discard pending promises that are waiting to run.
 
-	This might be useful if you want to teardown the queue at the end of your program's lifecycle or discard any function calls referencing an intermediary state of your app.
+	This might be useful if you want to tear down the queue at the end of your program's lifecycle or discard any function calls referencing an intermediary state of your app.
 
 	Note: This does not cancel promises that are already running.
 

package/node_modules/p-limit/index.js

@@ -105,7 +105,7 @@ export default function pLimit(concurrency) {
 		},
 		map: {
 			async value(iterable, function_) {
-				const promises = Array.from(iterable, (value, index) => this(function_, value, index));
+				const promises = Array.from(iterable, (value, index) => generator(function_, value, index));
 				return Promise.all(promises);
 			},
 		},

package/node_modules/p-limit/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "p-limit",
-	"version": "7.3.0",
+	"version": "7.3.1",
 	"description": "Run multiple promise-returning & async functions with limited concurrency",
 	"license": "MIT",
 	"repository": "sindresorhus/p-limit",

package/node_modules/p-limit/readme.md

@@ -97,7 +97,7 @@ The number of promises that are waiting to run (i.e. their internal `fn` was not
 
 Discard pending promises that are waiting to run.
 
-This might be useful if you want to teardown the queue at the end of your program's lifecycle or discard any function calls referencing an intermediary state of your app.
+This might be useful if you want to tear down the queue at the end of your program's lifecycle or discard any function calls referencing an intermediary state of your app.
 
 Note: This does not cancel promises that are already running.
 

package/openclaw.plugin.json

@@ -25,6 +25,12 @@
         "type": "string",
         "minLength": 1
       },
+      "workspace": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 19,
+        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+      },
       "from": {
         "type": "string",
         "minLength": 1
@@ -78,6 +84,10 @@
       "label": "Gateway Endpoint",
       "help": "Optional OpenShell gateway endpoint passed as --gateway-endpoint."
     },
+    "workspace": {
+      "label": "OpenShell Workspace",
+      "help": "Existing OpenShell control-plane workspace for sandboxes, providers, policies, and inference routes. When unset, preserves the OpenShell CLI's ambient workspace selection."
+    },
     "from": {
       "label": "Sandbox Source",
       "help": "OpenShell sandbox source for first-time create. Defaults to openclaw."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/openshell-sandbox",
-  "version": "2026.7.2-beta.5",
+  "version": "2026.7.2-beta.7",
   "description": "OpenClaw sandbox backend for the NVIDIA OpenShell CLI with mirrored local workspaces and SSH command execution.",
   "repository": {
     "type": "git",
@@ -8,7 +8,7 @@
   },
   "type": "module",
   "dependencies": {
-    "p-limit": "7.3.0",
+    "p-limit": "7.3.1",
     "zod": "4.4.3"
   },
   "openclaw": {
@@ -21,10 +21,10 @@
       "minHostVersion": ">=2026.5.12-beta.1"
     },
     "compat": {
-      "pluginApi": ">=2026.7.2-beta.5"
+      "pluginApi": ">=2026.7.2-beta.7"
     },
     "build": {
-      "openclawVersion": "2026.7.2-beta.5",
+      "openclawVersion": "2026.7.2-beta.7",
       "bundledDist": false
     },
     "release": {
@@ -41,7 +41,7 @@
     "README.md"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.7.2-beta.5"
+    "openclaw": ">=2026.7.2-beta.7"
   },
   "peerDependenciesMeta": {
     "openclaw": {