@stixxert/pi-docker-sandbox 1.1.4 → 1.1.5

package/index.ts

@@ -44,6 +44,7 @@ import path from "node:path";
 import fs from "node:fs";
 import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "@earendil-works/pi-ai";
+import { claimLifecycleOwnership } from "./sandbox/session-scope.ts";
 
 // Host pi cwd is the root that the agent's VM mounts at /workspace.
 const hostRoot = process.cwd();
@@ -1691,9 +1692,15 @@ async function armSessionLifecycle(): Promise<void> {
 }
 
 export default function (pi: ExtensionAPI) {
+	// The sandbox execution backend (`sandbox/`) shares this lifecycle, and the
+	// auto-discovered `sbx-backend` bridge loads that backend into subagent
+	// sessions so their built-in tools run in the same sandbox. Only the
+	// top-level session — the first to load either entry — may tear it down.
+	const ownsLifecycle = claimLifecycleOwnership();
 	// Lifecycle: tear down this session's sandbox when the session ends
 	// (exit / Ctrl+C / Ctrl+D / SIGHUP / SIGTERM, /new, /resume, /fork).
 	pi.on("session_shutdown", async () => {
+		if (!ownsLifecycle) return;
 		await teardownSandbox("session_shutdown");
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stixxert/pi-docker-sandbox",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "pi extension: a private docker sandbox (sbx microVM with its own daemon) as the agent's deploy target — the host's docker is never exposed.",
   "license": "Apache-2.0",
   "publishConfig": {

package/sandbox/index.ts

@@ -29,6 +29,7 @@
  *   DOCKER_SANDBOX / DOCKER_SANDBOX_*                see the docker_* extension
  */
 
+import path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	type GrepToolInput,
@@ -58,8 +59,15 @@ import {
 	executeSandboxGrep,
 } from "./operations.ts";
 import { type ExecTransport, defaultProjectSandbox, resolveTransport } from "./transport.ts";
+import { claimLifecycleOwnership } from "./session-scope.ts";
 
 export default function (pi: ExtensionAPI) {
+	// Subagent sessions (pi-subagents) load this router too, through the
+	// auto-discovered `sbx-backend` bridge, so a subagent's built-in tools run in
+	// the same sandbox as the main agent's instead of on the host. Only the
+	// top-level session may tear the shared (per-process) sandbox down; child
+	// sessions share it.
+	const ownsLifecycle = claimLifecycleOwnership();
 	const localCwd = process.cwd();
 
 	// Settle the sandbox NAME synchronously, before any session event can compute
@@ -208,6 +216,30 @@ export default function (pi: ExtensionAPI) {
 		return starting;
 	}
 
+	/**
+	 * The working directory a session's routed tools must operate in.
+	 *
+	 * The backend mounts the process working directory (`localCwd`) into the
+	 * sandbox, while pi builds a session's tools with that SESSION's cwd. They
+	 * coincide for the top-level session, but not necessarily for a subagent — a
+	 * pi-subagents git worktree lives under the host tmpdir, outside the mount.
+	 * Routing now happens for subagents too, so the cwd is resolved per call: a
+	 * directory inside the mount is used as-is, one outside it is refused rather
+	 * than silently executed against (or written to) the wrong tree.
+	 */
+	function sessionCwd(ctx?: ExtensionContext): string {
+		const cwd = ctx?.cwd;
+		if (!cwd || cwd === localCwd) return localCwd;
+		const rel = path.relative(localCwd, cwd);
+		if (rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel)) return cwd;
+		throw new Error(
+			`sbx sandbox mounts only ${localCwd}, but this session's working directory is ${cwd}. ` +
+				`Its tools cannot be routed into the sandbox; nothing was executed. ` +
+				`Do not use worktree isolation (\`isolation: "worktree"\`) under the sbx backend, ` +
+				`or re-run the session without it.`,
+		);
+	}
+
 	/**
 	 * Route a tool to the sandbox, refusing to run it on the host when no sandbox
 	 * can be had (fail closed) unless the user opted in.
@@ -217,18 +249,21 @@ export default function (pi: ExtensionAPI) {
 	 */
 	function routed<T extends { execute: (...args: never[]) => unknown }>(
 		local: T,
-		build: (t: ExecTransport) => T,
+		build: (t: ExecTransport, cwd: string) => T,
 	): T {
 		return {
 			...local,
 			async execute(id: unknown, params: unknown, signal: unknown, onUpdate: unknown, ctx?: ExtensionContext) {
+				// Resolved before the transport: an unroutable cwd must fail closed
+				// whether or not a sandbox happens to be available.
+				const cwd = sessionCwd(ctx);
 				const t = await ensureTransport(ctx);
 				if (!t) {
 					assertLocalFallbackAllowed();
 					return (local.execute as Function)(id, params, signal, onUpdate, ctx);
 				}
 				return withSandboxFailureHandling(ctx, () =>
-					(build(t).execute as Function)(id, params, signal, onUpdate, ctx),
+					(build(t, cwd).execute as Function)(id, params, signal, onUpdate, ctx),
 				);
 			},
 		} as T;
@@ -266,6 +301,9 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", async () => {
+		// Child (subagent) sessions share the parent's per-process sandbox;
+		// tearing it down from one would kill the VM out from under the parent.
+		if (!ownsLifecycle) return;
 		// Only an sbx sandbox is ours to reclaim; a container backend is a
 		// caller-supplied environment (docker_* owns its own sandbox lifecycle).
 		if (transport?.kind === "sbx") await teardownSandbox("session_shutdown");
@@ -295,12 +333,12 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool(routed(localRead, (t) => createReadToolDefinition(localCwd, { operations: createReadOps(t) })));
-	pi.registerTool(routed(localWrite, (t) => createWriteToolDefinition(localCwd, { operations: createWriteOps(t) })));
-	pi.registerTool(routed(localEdit, (t) => createEditToolDefinition(localCwd, { operations: createEditOps(t) })));
-	pi.registerTool(routed(localBash, (t) => createBashToolDefinition(localCwd, { operations: createBashOps(t, { allowEnv: bashAllowEnv }) })));
-	pi.registerTool(routed(localLs, (t) => createLsToolDefinition(localCwd, { operations: createLsOps(t) })));
-	pi.registerTool(routed(localFind, (t) => createFindToolDefinition(localCwd, { operations: createFindOps(t) })));
+	pi.registerTool(routed(localRead, (t, cwd) => createReadToolDefinition(cwd, { operations: createReadOps(t) })));
+	pi.registerTool(routed(localWrite, (t, cwd) => createWriteToolDefinition(cwd, { operations: createWriteOps(t) })));
+	pi.registerTool(routed(localEdit, (t, cwd) => createEditToolDefinition(cwd, { operations: createEditOps(t) })));
+	pi.registerTool(routed(localBash, (t, cwd) => createBashToolDefinition(cwd, { operations: createBashOps(t, { allowEnv: bashAllowEnv }) })));
+	pi.registerTool(routed(localLs, (t, cwd) => createLsToolDefinition(cwd, { operations: createLsOps(t) })));
+	pi.registerTool(routed(localFind, (t, cwd) => createFindToolDefinition(cwd, { operations: createFindOps(t) })));
 	// grep is replaced wholesale, not merely re-pointed: pi's grep tool spawns
 	// host ripgrep for match discovery regardless of custom operations, which
 	// would scan the host filesystem and require rg on the host. The sandbox
@@ -308,12 +346,13 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		...localGrep,
 		async execute(id, params, signal, onUpdate, ctx) {
+			const cwd = sessionCwd(ctx);
 			const t = await ensureTransport(ctx);
 			if (!t) {
 				assertLocalFallbackAllowed();
 				return localGrep.execute(id, params, signal, onUpdate, ctx);
 			}
-			return withSandboxFailureHandling(ctx, () => executeSandboxGrep(t, localCwd, params as GrepToolInput));
+			return withSandboxFailureHandling(ctx, () => executeSandboxGrep(t, cwd, params as GrepToolInput));
 		},
 	});
 

package/sandbox/session-scope.ts

@@ -0,0 +1,63 @@
+/**
+ * Session-scope guards for the sbx tool router.
+ *
+ * **Zero imports on purpose** (same discipline as `failure.ts`): the vendored
+ * repo's own suite cannot run from the config repo, but this module can be
+ * unit-tested by relative path from `agent/extensions/sbx-backend/`.
+ *
+ * Why these exist: `@tintinweb/pi-subagents` builds every subagent as a FRESH
+ * `AgentSession` **in the same process**, seeded from pi's *built-in* tool
+ * definitions and a fresh `DefaultResourceLoader`. It never sees the parent's
+ * CLI `-e <checkout>/sandbox` extension, so without help a subagent's `bash`
+ * runs on the HOST (measured: `uid=502(sas054)` / `Darwin`, CoreSimulator
+ * visible) while the main agent's runs in the VM.
+ *
+ * The bridge that fixes that (`agent/extensions/sbx-backend/`) is loaded into
+ * every subagent session, and it is the ONLY loader under `pidock` (the
+ * launcher no longer passes `-e`). Two invariants still need enforcing:
+ *
+ *  1. **Only the top-level session tears the sandbox down.** The sandbox name
+ *     is per-process (`pi-sbx-<pid>-<rand>`); every child session shares the
+ *     parent's VM. A child's `session_shutdown` would otherwise `sbx rm
+ *     --force` the sandbox out from under the running parent.
+ *
+ *  2. **One loader per session.** Normally this is by construction, but if a
+ *     caller ALSO loads the backend explicitly (`pi -e <checkout>/sandbox,
+ *     the vendored repo's standalone usage) while the bridge is active, pi
+ *     refuses the second registration (`Tool "read" conflicts with …`). There
+ *     is no way to dedupe that from here: pi gives each EXTENSION its own
+ *     `ExtensionAPI` object (measured — a marker stored on it did not dedupe),
+ *     so the two loaders cannot see each other. Documented, not guarded.
+ */
+
+/** Process-wide marker: which session owns sandbox teardown. */
+const LIFECYCLE_OWNER = Symbol.for("pi-docker-sandbox.lifecycle.owner");
+
+/**
+ * Claim process-wide lifecycle ownership.
+ *
+ * `true` only for the FIRST session to ask — the top-level one, which is
+ * necessarily the first to load the router. Child sessions get `false` and
+ * must skip teardown. The claim is intentionally never released: pi can create
+ * a new top-level session in the same process (`/new`), and that session must
+ * not tear down a sandbox other sessions may still be using; leaked sandboxes
+ * are reclaimed by the existing `gcSweep` safety net.
+ */
+export function claimLifecycleOwnership(): boolean {
+	const g = globalThis as unknown as Record<symbol, unknown>;
+	if (g[LIFECYCLE_OWNER]) return false;
+	g[LIFECYCLE_OWNER] = true;
+	return true;
+}
+
+/**
+ * Whether the launcher selected the sbx router for this process.
+ *
+ * `sbx/pidock` exports `PI_TOOL_ROUTER=sbx` to make the auto-discovered
+ * gondolin backend yield; this backend uses the same marker so the bridge is
+ * inert under bare `pi`, `pix` and `sbxpi` (none of which route host tools
+ * into an sbx sandbox).
+ */
+export function isSbxRouterSelected(env: Record<string, string | undefined>): boolean {
+	return (env.PI_TOOL_ROUTER ?? "").trim().toLowerCase() === "sbx";
+}