pi-glovebox 0.1.0 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@ Every call becomes one command run by `pi-glovebox-server` inside your sandbox:
 | `write` | `mkdir -p`, then `cat > file` with the content on stdin |
 | `edit` | `: < file && : >> file` to check access, `cat`, `cat > file` |
 
-Commands get the server's environment, not Pi's. Aborts and timeouts close the connection, and the server kills the command's process group.
+Your `!` and `!!` commands run the same way as `bash`. Commands get the server's environment, not Pi's. Aborts and timeouts close the connection, and the server kills the command's process group. Like Pi's own `bash`, a command counts as finished once it has exited and any background processes it started have printed nothing for 100 ms; those processes keep running.
 
 pi-glovebox also blocks calls to tools that would run in Pi's process instead, returning an error the model sees:
 
@@ -32,6 +32,7 @@ pi-glovebox separates where Pi runs from where the model's commands run, and lea
 
 ## Requirements
 
+- Pi 0.85.0 or later.
 - Node.js 22 or later for the server, and `bash`, `cat`, `head` and `mkdir` inside the sandbox.
 - Pi's working directory must exist at the same path inside the sandbox.
 
@@ -55,14 +56,14 @@ This sandbox sees the project read-write, `/nix` and the directories on your `PA
 - `env -i` keeps exported API keys out of the sandbox, since sbox passes its environment through.
 - `--no-builtin-tools` leaves Pi's own tools inactive. If pi-glovebox fails to load, Pi has no tools unless another extension activates Pi's own.
 - Other extensions, including their tools, run in Pi's process with Pi's environment. Load only extensions you trust, or pass `--no-extensions` and name each with `-e`.
-- The bash environment Pi normally sets (`PI_SESSION_ID`, `PI_MODEL`, …) and the `shellPath` and `shellCommandPrefix` settings do not reach the sandbox.
+- The bash environment Pi normally sets (`PI_SESSION_ID`, `PI_MODEL`, …) and the `shellPath` and `shellCommandPrefix` settings do not reach the sandbox; the `bash` tool does not mention them to the model.
 - Anything that can reach the socket can run commands in the sandbox.
 - Pi still reads `AGENTS.md`, skills, extensions and settings from the host. If the model can write them, it can influence later sessions; see Pi's `--no-context-files`, `--no-skills`, `--no-extensions` and `--no-approve`.
 - Pi saves truncated bash output under its `TMPDIR`. Mount that directory into the sandbox if the model should read those files.
 
 ## Protocol
 
-One connection runs one command. The client sends one line of JSON, `{"argv": [...], "cwd": "/abs/path", "stdin": "optional text"}`. The server answers with frames of a 1-byte type, a 4-byte big-endian length and a payload: type 1 carries output (stdout and stderr as they arrive), type 2 carries the exit code as JSON (`null` if the command was killed by a signal or could not start) and is last. Closing the connection early kills the command's process group; a malformed request closes it without running anything.
+One connection runs one command. The client sends one line of JSON, `{"argv": [...], "cwd": "/abs/path", "stdin": "optional text"}`. The server answers with frames of a 1-byte type, a 4-byte big-endian length and a payload: type 1 carries output (stdout and stderr as they arrive); type 2 carries the exit code as JSON (`null` if the command was killed by a signal); type 3 carries an error message if the command could not start, such as a missing `cwd`. Either type 2 or type 3 comes last, then the server closes the connection. Closing the connection early, including only its writing side, kills the command's process group, so keep it fully open until the last frame; a malformed request closes it without running anything.
 
 ## License
 

package/bin/pi-glovebox-server.mjs

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import net from "node:net";
 
 const output = 1;
 const exit = 2;
+const failure = 3;
+// Background processes can hold stdout and stderr open after the command exits. Like Pi's own bash,
+// stop waiting for their output once none has arrived for this long.
+const quietMs = 100;
 
 const frame = (type, payload) => {
   const header = Buffer.alloc(5);
@@ -14,18 +19,35 @@ const frame = (type, payload) => {
 
 net
   .createServer((socket) => {
-    let received = Buffer.alloc(0);
+    const received = [];
     let child;
     let exited = false;
+    let finished = false;
+    let quiet;
 
-    const finish = (code) => {
-      if (exited) return;
-      exited = true;
-      socket.end(frame(exit, Buffer.from(JSON.stringify(code))));
+    const finish = (type, payload) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(quiet);
+      socket.end(frame(type, Buffer.from(payload)));
+    };
+
+    const finishWhenQuiet = () => {
+      clearTimeout(quiet);
+      if (finished) return;
+      quiet = setTimeout(() => {
+        // A paused stream still holds output the client has not taken yet.
+        if (child.stdout.isPaused() || child.stderr.isPaused()) return finishWhenQuiet();
+        child.stdout.destroy();
+        child.stderr.destroy();
+        finish(exit, JSON.stringify(child.exitCode));
+      }, quietMs);
     };
 
     const forward = (stream) =>
       stream.on("data", (chunk) => {
+        if (finished) return;
+        if (exited) finishWhenQuiet();
         if (socket.write(frame(output, chunk))) return;
         stream.pause();
         socket.once("drain", () => stream.resume());
@@ -33,21 +55,27 @@ net
 
     socket.on("error", () => {});
     socket.on("close", () => {
-      if (!child || exited) return;
+      if (finished) return;
+      finished = true;
+      clearTimeout(quiet);
+      if (!child) return;
       try {
         process.kill(-child.pid, "SIGKILL");
       } catch {}
+      // Drain what the killed processes left behind so the child can be reaped.
+      child.stdout.resume();
+      child.stderr.resume();
     });
 
     socket.on("data", function onRequest(chunk) {
-      received = Buffer.concat([received, chunk]);
-      const end = received.indexOf(10);
-      if (end < 0) return;
+      const end = chunk.indexOf(10);
+      if (end < 0) return void received.push(chunk);
+      received.push(chunk.subarray(0, end));
       socket.off("data", onRequest);
 
       let request;
       try {
-        request = JSON.parse(received.subarray(0, end).toString());
+        request = JSON.parse(Buffer.concat(received).toString());
       } catch {}
       const valid =
         Array.isArray(request?.argv) &&
@@ -56,19 +84,20 @@ net
         typeof request.cwd === "string" &&
         (request.stdin === undefined || typeof request.stdin === "string");
       if (!valid) return socket.destroy();
+      if (!existsSync(request.cwd)) return finish(failure, `Working directory does not exist: ${request.cwd}`);
       try {
         child = spawn(request.argv[0], request.argv.slice(1), { cwd: request.cwd, detached: true });
       } catch (error) {
-        socket.write(frame(output, Buffer.from(`${error.message}\n`)));
-        return finish(null);
+        return finish(failure, error.message);
       }
       forward(child.stdout);
       forward(child.stderr);
-      child.on("error", (error) => {
-        socket.write(frame(output, Buffer.from(`${error.message}\n`)));
-        finish(null);
+      child.on("error", (error) => finish(failure, error.message));
+      child.on("exit", () => {
+        exited = true;
+        finishWhenQuiet();
       });
-      child.on("close", (code) => finish(code));
+      child.on("close", (code) => finish(exit, JSON.stringify(code)));
       child.stdin.on("error", () => {});
       child.stdin.end(request.stdin ?? "");
     });

package/extensions/index.ts

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
+	type BashOperations,
 	createBashTool,
 	createEditTool,
 	createReadTool,
@@ -20,6 +21,11 @@ const imageSniffBytes = "4100";
 const ownFile = realpathSync(fileURLToPath(import.meta.url));
 const ownPaths = [ownFile, path.dirname(ownFile)];
 const ownTools = ["bash", "read", "write", "edit"];
+// The largest delay setTimeout accepts; Pi's own bash rejects longer timeouts the same way.
+const maxTimeoutMs = 2147483647;
+const frameOutput = 1;
+const frameExit = 2;
+const frameFailure = 3;
 
 type Request = { argv: string[]; cwd: string; stdin?: string };
 type Options = { onData?: (data: Buffer) => void; signal?: AbortSignal; timeout?: number };
@@ -31,6 +37,7 @@ const run = (request: Request, { onData, signal, timeout }: Options = {}) =>
 		const output: Buffer[] = [];
 		let received = Buffer.alloc(0);
 		let exitCode: number | null | undefined;
+		let failure: string | undefined;
 
 		const stop = (error: Error) => {
 			socket.destroy();
@@ -44,11 +51,13 @@ const run = (request: Request, { onData, signal, timeout }: Options = {}) =>
 			received = Buffer.concat([received, chunk]);
 			while (received.length >= 5 && received.length >= 5 + received.readUInt32BE(1)) {
 				const payload = received.subarray(5, 5 + received.readUInt32BE(1));
-				if (received[0] === 1) {
+				if (received[0] === frameOutput) {
 					if (onData) onData(payload);
 					else output.push(payload);
-				} else {
+				} else if (received[0] === frameExit) {
 					exitCode = JSON.parse(payload.toString());
+				} else if (received[0] === frameFailure) {
+					failure = payload.toString();
 				}
 				received = received.subarray(5 + payload.length);
 			}
@@ -57,7 +66,8 @@ const run = (request: Request, { onData, signal, timeout }: Options = {}) =>
 		socket.on("close", () => {
 			clearTimeout(timer);
 			signal?.removeEventListener("abort", abort);
-			if (exitCode === undefined) reject(new Error("pi-glovebox: connection closed before the command finished"));
+			if (failure !== undefined) reject(new Error(failure));
+			else if (exitCode === undefined) reject(new Error("pi-glovebox: connection closed before the command finished"));
 			else resolve({ output: Buffer.concat(output), exitCode });
 		});
 
@@ -74,6 +84,15 @@ const succeed = async (argv: string[], stdin?: string) => {
 const shell = (script: string, file: string, stdin?: string) =>
 	succeed(["bash", "-c", script, "pi-glovebox", file], stdin).then(() => {});
 
+const exec: BashOperations["exec"] = async (command, cwd, { onData, signal, timeout }) => {
+	if (timeout !== undefined) {
+		if (!Number.isFinite(timeout) || timeout <= 0) throw new Error("Invalid timeout: must be a finite number of seconds");
+		if (timeout * 1000 > maxTimeoutMs) throw new Error(`Invalid timeout: maximum is ${maxTimeoutMs / 1000} seconds`);
+	}
+	const { exitCode } = await run({ argv: ["bash", "-c", command], cwd }, { onData, signal, timeout });
+	return { exitCode };
+};
+
 const detectImageMimeType = async (file: string) => {
 	const head = await succeed(["head", "-c", imageSniffBytes, "--", file]);
 	const directory = await mkdtemp(path.join(tmpdir(), "pi-glovebox-"));
@@ -93,17 +112,12 @@ export default function (pi: ExtensionAPI) {
 			return { block: true, reason: `pi-glovebox: ${toolName} is built into Pi and would run outside the sandbox` };
 		}
 		if (ownTools.includes(toolName) && !(source && existsSync(source.path) && ownPaths.includes(realpathSync(source.path)))) {
-			return { block: true, reason: `pi-glovebox: ${toolName} comes from ${source?.path}, not pi-glovebox, and would run outside the sandbox` };
+			return { block: true, reason: `pi-glovebox: ${toolName} comes from ${source?.path}, not this pi-glovebox (${ownFile}), and would run outside the sandbox` };
 		}
 	});
-	pi.registerTool(
-		createBashTool(cwd, {
-			operations: {
-				exec: (command, directory, options) =>
-					run({ argv: ["bash", "-c", command], cwd: directory }, options).then(({ exitCode }) => ({ exitCode })),
-			},
-		}),
-	);
+	pi.on("user_bash", () => ({ operations: { exec } }));
+	// The sandbox gets the server's environment, so the PI_* variables Pi would advertise never reach it.
+	pi.registerTool(createBashTool(cwd, { operations: { exec }, exposeSessionEnvironment: false }));
 	pi.registerTool(
 		createReadTool(cwd, {
 			operations: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-glovebox",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Run Pi's bash, read, write and edit tools in a separate sandbox, reached over a Unix socket",
   "keywords": [
     "pi-package",
@@ -30,7 +30,7 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": ">=0.85.0"
   },
   "engines": {
     "node": ">=22"