feat(sparsekernel): sandbox plugin subprocess workers

Author: AbrahamGreenman

docs/architecture/local-agent-kernel.md

@@ -121,7 +121,7 @@ Sensitive operations should check capabilities before they mutate state or alloc
 - sandbox allocation;
 - tool invocation.
 
-Capability grants, revokes, and denied checks are audited. Embedded agent runs now materialize the active step as a task lease and transcript events, then wrap the effective tool set with the local ToolBroker outside tests unless explicitly disabled with `OPENCLAW_RUNTIME_TOOL_BROKER=off`. Set `OPENCLAW_RUNTIME_TOOL_BROKER=daemon` to use the `sparsekerneld` run-ledger and ToolBroker path; daemon setup failures fall back to the local runtime broker. Set `OPENCLAW_RUNTIME_TOOL_CAPABILITY_MODE=strict` to stop auto-granting sensitive tools such as `exec`, `read`, `write`, and `browser`; those tools then fail closed unless a capability already exists or `OPENCLAW_RUNTIME_TOOL_ALLOW_SENSITIVE=1` is set for compatibility. Set `OPENCLAW_RUNTIME_TOOL_SANDBOX_EXEC=1` to route `exec`, `bash`, and `shell` shaped tools through the sandbox broker command runner instead of the ambient in-process tool implementation when the active agent has sandbox allocation capability. Native in-process plugins remain trusted by default. When `OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY=subprocess` or `OPENCLAW_RUNTIME_PLUGIN_PROCESS=strict` is set, plugin tools with subprocess metadata execute through a JSON stdin/stdout worker process and emit subprocess audit events; plugin tools without subprocess metadata fail closed.
+Capability grants, revokes, and denied checks are audited. Embedded agent runs now materialize the active step as a task lease and transcript events, then wrap the effective tool set with the local ToolBroker outside tests unless explicitly disabled with `OPENCLAW_RUNTIME_TOOL_BROKER=off`. Set `OPENCLAW_RUNTIME_TOOL_BROKER=daemon` to use the `sparsekerneld` run-ledger and ToolBroker path; daemon setup failures fall back to the local runtime broker. Set `OPENCLAW_RUNTIME_TOOL_CAPABILITY_MODE=strict` to stop auto-granting sensitive tools such as `exec`, `read`, `write`, and `browser`; those tools then fail closed unless a capability already exists or `OPENCLAW_RUNTIME_TOOL_ALLOW_SENSITIVE=1` is set for compatibility. Set `OPENCLAW_RUNTIME_TOOL_SANDBOX_EXEC=1` to route `exec`, `bash`, and `shell` shaped tools through the sandbox broker command runner instead of the ambient in-process tool implementation when the active agent has sandbox allocation capability. Native in-process plugins remain trusted by default. When `OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY=subprocess` or `OPENCLAW_RUNTIME_PLUGIN_PROCESS=strict` is set, plugin tools with subprocess metadata execute through a JSON stdin/stdout worker via the sandbox broker, emit subprocess and sandbox audit events, and fail closed if the worker would use `local/no_isolation` without an explicit trusted-worker opt-out; plugin tools without subprocess metadata fail closed.
 
 The SparseKernel daemon now exposes the v0 run and ToolBroker lifecycle over local JSON: session upsert/list, transcript append/list, task enqueue/claim-by-id/claim-next/heartbeat/complete/fail, tool-call create/start/complete/fail/list, browser acquire/release, sandbox allocate/release, and artifact access. Tool-call create checks `tool` / `<tool-name>` / `invoke`; completion records small structured output plus `artifact_ids`; and every transition writes audit records. See [Tool Broker](/architecture/tool-broker).
 

docs/architecture/security-boundaries.md

@@ -23,7 +23,7 @@ SparseKernel security claims must be precise.
 - Docker command execution requires an explicit image and disables container networking by default, but its isolation is only the host Docker daemon's isolation; it is not a per-agent security model.
 - Persisted lease metadata records the selected backend and policy intent; it is audit/accounting state, not isolation by itself.
 - Untrusted plugins must not get ambient host authority.
-- The subprocess-required plugin mode can run plugin tools with explicit subprocess metadata through a JSON worker protocol; that worker still needs an appropriate sandbox backend before it should be treated as safe for untrusted code.
+- The subprocess-required plugin mode runs explicit JSON workers through the sandbox broker. It still only becomes suitable for untrusted code when the selected backend is a real isolation backend; `local/no_isolation` is blocked by default for plugin subprocess workers and should only be enabled for trusted local workers.
 - Secrets should be referenced, not stored as plaintext in SQLite.
 
 Capabilities are the v0 policy primitive. They are intentionally simple: subject, resource, action, optional constraints, optional expiry. Denied sensitive checks are audit-logged.

docs/architecture/sparsekernel.md

@@ -56,4 +56,4 @@ The tool broker records tool-call lifecycle transitions, capability-checks agent
 
 ## Current limitations
 
-V0 proves the foundation. It does not launch or supervise Playwright browser process pools, implement production sandbox backends, enforce an egress proxy, isolate plugins in subprocesses, stream large artifact transfers, or rewrite OpenClaw around SparseKernel.
+V0 proves the foundation. It does not launch or supervise Playwright browser process pools, implement production sandbox backends, enforce an egress proxy, make subprocess plugin workers safe without a real isolation backend, stream large artifact transfers, or rewrite OpenClaw around SparseKernel.

docs/architecture/tool-broker.md

@@ -42,4 +42,4 @@ For exec-shaped tools, set `OPENCLAW_RUNTIME_TOOL_SANDBOX_EXEC=1` to route `exec
 
 Sandbox allocations persist the selected backend and trust-zone policy snapshot in resource-lease metadata. A restarted broker object can recover whether an allocation was local/no-isolation, bwrap, minijail, or Docker without relying on an in-memory map. Docker command execution is explicit: callers must provide `dockerImage` or `OPENCLAW_SPARSEKERNEL_DOCKER_IMAGE`, the wrapper uses `--pull never`, drops Linux capabilities, sets `no-new-privileges`, applies read-only root/tmpfs defaults, maps trust-zone memory/process limits to Docker flags, and keeps container networking disabled unless a policy proxy is configured.
 
-V0 does not move native plugins out of process by default. It establishes the ledger and API contract so OpenClaw adapters can route invocation through SparseKernel now, then move untrusted or community plugins behind stronger process or sandbox boundaries later. Set `OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY=subprocess` or `OPENCLAW_RUNTIME_PLUGIN_PROCESS=strict` to require plugin tools to provide subprocess metadata. Opt-in workers receive a JSON request on stdin with `protocol`, `pluginId`, `toolName`, `toolCallId`, `params`, and broker context, and must return an `AgentToolResult` JSON object on stdout. Plugin tools without subprocess metadata fail closed with `plugin_tool.subprocess_required` audit records.
+V0 does not move native plugins out of process by default. It establishes the ledger and API contract so OpenClaw adapters can route invocation through SparseKernel now, then move untrusted or community plugins behind stronger process or sandbox boundaries later. Set `OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY=subprocess` or `OPENCLAW_RUNTIME_PLUGIN_PROCESS=strict` to require plugin tools to provide subprocess metadata. Opt-in workers receive a JSON request on stdin with `protocol`, `pluginId`, `toolName`, `toolCallId`, `params`, and broker context, and must return an `AgentToolResult` JSON object on stdout. Plugin subprocess workers now execute through the sandbox broker as `plugin_untrusted` leases by default, so allocation capability, command audit events, usage records, and release accounting apply to plugin workers too. The broker fails closed when a worker would use `local/no_isolation` unless the plugin marks the subprocess sandbox `requireIsolated: false` or `OPENCLAW_RUNTIME_PLUGIN_ALLOW_NO_ISOLATION=1` is set for trusted local workers. Plugin tools without subprocess metadata fail closed with `plugin_tool.subprocess_required` audit records.

src/local-kernel/database.test.ts

@@ -530,6 +530,34 @@ describe("local runtime kernel database", () => {
     ).rejects.toThrow(/not active/);
   });
 
+  it("passes stdin through sandbox command leases", async () => {
+    const db = openTempDb();
+    db.ensureAgent({ id: "main" });
+    db.enqueueTask({ id: "task-a", kind: "demo" });
+    db.grantCapability({
+      subjectType: "agent",
+      subjectId: "main",
+      resourceType: "sandbox",
+      resourceId: "code_execution",
+      action: "allocate",
+    });
+    const broker = new LocalSandboxBroker(db);
+    const allocation = broker.allocateSandbox({
+      taskId: "task-a",
+      agentId: "main",
+      trustZoneId: "code_execution",
+      requirements: { maxRuntimeMs: 5_000, maxBytesOut: 1024 },
+    });
+    await expect(
+      broker.runCommand({
+        allocationId: allocation.id,
+        command: process.execPath,
+        args: ["-e", "process.stdin.pipe(process.stdout)"],
+        stdin: "worker-input",
+      }),
+    ).resolves.toMatchObject({ exitCode: 0, stdout: "worker-input", timedOut: false });
+  });
+
   it("persists sandbox backend metadata across broker instances", async () => {
     const db = openTempDb();
     db.ensureAgent({ id: "main" });
@@ -671,6 +699,16 @@ describe("local runtime kernel database", () => {
         "-v",
       ]),
     });
+    expect(
+      buildSandboxSpawnPlan({
+        backend: "docker",
+        command: "node",
+        args: ["worker.mjs"],
+        dockerImage: "openclaw-runtime:local",
+        stdin: true,
+        resolveCommand: () => "docker",
+      }).args.slice(0, 4),
+    ).toEqual(["run", "--rm", "-i", "--pull"]);
   });
 
   it("accounts sandboxed runs without requiring a queued task row", () => {

src/local-kernel/sandbox-broker.ts

@@ -37,6 +37,8 @@ export type SandboxCommandRequest = {
   args?: string[];
   cwd?: string;
   env?: Record<string, string>;
+  stdin?: string | Buffer | Uint8Array;
+  signal?: AbortSignal;
   timeoutMs?: number;
   maxOutputBytes?: number;
 };
@@ -224,6 +226,7 @@ export function buildSandboxSpawnPlan(params: {
   args: string[];
   cwd?: string;
   env?: Record<string, string>;
+  stdin?: boolean;
   dockerImage?: string;
   dockerPolicy?: DockerSandboxPolicy;
   resolveCommand?: CommandResolver;
@@ -293,6 +296,7 @@ export function buildSandboxSpawnPlan(params: {
       const args = [
         "run",
         "--rm",
+        ...(params.stdin ? ["-i"] : []),
         "--pull",
         "never",
         "--network",
@@ -480,6 +484,7 @@ export class LocalSandboxBroker implements SandboxBroker {
         args: request.args ?? [],
         cwd: request.cwd,
         env: request.env,
+        stdin: request.stdin !== undefined,
         dockerImage:
           request.dockerImage ??
           metadata.dockerImage ??
@@ -526,25 +531,38 @@ export class LocalSandboxBroker implements SandboxBroker {
       const child = spawn(spawnPlan.command, spawnPlan.args, {
         cwd: backend === "local/no_isolation" ? request.cwd : undefined,
         env: request.env ? { ...process.env, ...request.env } : process.env,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: [request.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
       });
       let timedOut = false;
       let stdout = Buffer.alloc(0);
       let stderr = Buffer.alloc(0);
+      const abort = () => {
+        child.kill("SIGTERM");
+      };
       const append = (current: Buffer, chunk: Buffer) =>
         Buffer.concat([current, chunk]).subarray(0, maxOutputBytes);
       const timer = setTimeout(() => {
         timedOut = true;
         child.kill("SIGTERM");
       }, timeoutMs);
-      child.stdout.on("data", (chunk: Buffer) => {
+      timer.unref?.();
+      if (request.signal?.aborted) {
+        abort();
+      } else {
+        request.signal?.addEventListener("abort", abort, { once: true });
+      }
+      if (request.stdin !== undefined) {
+        child.stdin?.end(request.stdin);
+      }
+      child.stdout?.on("data", (chunk: Buffer) => {
         stdout = append(stdout, chunk);
       });
-      child.stderr.on("data", (chunk: Buffer) => {
+      child.stderr?.on("data", (chunk: Buffer) => {
         stderr = append(stderr, chunk);
       });
       child.on("error", (error) => {
         clearTimeout(timer);
+        request.signal?.removeEventListener("abort", abort);
         this.db.recordAudit({
           actor: { type: "runtime" },
           action: "sandbox.command_failed",
@@ -556,6 +574,7 @@ export class LocalSandboxBroker implements SandboxBroker {
       });
       child.on("close", (exitCode, signal) => {
         clearTimeout(timer);
+        request.signal?.removeEventListener("abort", abort);
         const durationMs = Date.now() - started;
         const result: SandboxCommandResult = {
           allocationId: request.allocationId,

src/local-kernel/tool-broker-runtime.ts

@@ -5,6 +5,7 @@ import {
   type OpenClawSparseKernelToolBrokerClient,
 } from "../../packages/openclaw-sparsekernel-adapter/src/index.js";
 import type { AnyAgentTool } from "../agents/tools/common.js";
+import { getPluginToolMeta } from "../plugins/tools.js";
 import { resolveSparseKernelBrowserCdpEndpoint } from "./browser-managed-cdp.js";
 import type { acquireNativeBrowserProcess } from "./browser-process-pool.js";
 import { openLocalKernelDatabase, type LocalKernelDatabase } from "./database.js";
@@ -204,6 +205,26 @@ export function brokerToolsForRun(input: BrokerToolsForRunInput): LocalBrokeredT
           expiresAt: capabilityExpiresAt,
         });
       }
+      const pluginMeta = getPluginToolMeta(tool);
+      if (pluginMeta?.subprocess) {
+        const trustZoneId =
+          pluginMeta.subprocess.sandbox?.trustZoneId?.trim() || "plugin_untrusted";
+        db.grantCapability({
+          subjectType: "agent",
+          subjectId: input.agentId,
+          resourceType: "sandbox",
+          resourceId: trustZoneId,
+          action: "allocate",
+          constraints: {
+            sessionId: input.sessionId,
+            sessionKey: input.sessionKey,
+            runId: input.runId,
+            pluginId: pluginMeta.pluginId,
+            reason: "plugin subprocess worker available for brokered run",
+          },
+          expiresAt: capabilityExpiresAt,
+        });
+      }
     }
     broker = new CapabilityToolBroker(db, {
       artifactRootDir: input.artifactRootDir,

src/local-kernel/tool-broker.test.ts

@@ -358,6 +358,13 @@ describe("CapabilityToolBroker", () => {
         resourceId: "plugin_tool",
         action: "invoke",
       });
+      db.grantCapability({
+        subjectType: "agent",
+        subjectId: "main",
+        resourceType: "sandbox",
+        resourceId: "plugin_untrusted",
+        action: "allocate",
+      });
       const rawTool = makeTool("plugin_tool");
       setPluginToolMeta(rawTool, {
         pluginId: "community-plugin",
@@ -366,6 +373,11 @@ describe("CapabilityToolBroker", () => {
           command: process.execPath,
           args: [workerPath],
           timeoutMs: 5_000,
+          sandbox: {
+            backend: "local/no_isolation",
+            requireIsolated: false,
+            maxBytesOut: 16_384,
+          },
         },
       });
       const broker = new CapabilityToolBroker(db, {
@@ -383,6 +395,10 @@ describe("CapabilityToolBroker", () => {
         expect.arrayContaining([
           "plugin_tool.subprocess_started",
           "plugin_tool.subprocess_finished",
+          "sandbox.allocated",
+          "sandbox.command_started",
+          "sandbox.command_completed",
+          "sandbox.released",
           "tool_call.completed",
         ]),
       );
@@ -392,6 +408,44 @@ describe("CapabilityToolBroker", () => {
     }
   });
 
+  it("fails closed for plugin subprocess workers without an isolated sandbox", async () => {
+    const db = new LocalKernelDatabase({ dbPath: ":memory:" });
+    try {
+      db.ensureAgent({ id: "main" });
+      db.grantCapability({
+        subjectType: "agent",
+        subjectId: "main",
+        resourceType: "tool",
+        resourceId: "plugin_tool",
+        action: "invoke",
+      });
+      const rawTool = makeTool("plugin_tool");
+      setPluginToolMeta(rawTool, {
+        pluginId: "community-plugin",
+        optional: false,
+        subprocess: {
+          command: process.execPath,
+          args: ["-e", "process.stdout.write('{}')"],
+        },
+      });
+      const broker = new CapabilityToolBroker(db, {
+        env: { OPENCLAW_RUNTIME_PLUGIN_PROCESS_BOUNDARY: "subprocess" } as NodeJS.ProcessEnv,
+      });
+      const tool = broker.wrapTool(rawTool, {
+        subject: { subjectType: "agent", subjectId: "main" },
+        agentId: "main",
+      });
+      await expect(tool.execute("call-plugin-worker-unsafe", {})).rejects.toThrow(
+        /requires an isolated sandbox backend/,
+      );
+      expect(db.listAudit({ limit: 20 }).map((entry) => entry.action)).toEqual(
+        expect.arrayContaining(["plugin_tool.sandbox_required", "tool_call.failed"]),
+      );
+    } finally {
+      db.close();
+    }
+  });
+
   it("does not auto-grant sensitive tools in strict capability mode", async () => {
     const run = brokerToolsForRun({
       tools: [makeTool("exec")],