pi-glovebox 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Ferenczy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# pi-glovebox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/glovebox.webp" alt="A white π reaching into a stainless steel glovebox whose window shows bash, read, write and edit among fairy lights" width="360">
+
+A [Pi](https://github.com/earendil-works/pi) extension that runs the model's `bash`, `read`, `write` and `edit` calls in a sandbox you start, such as [sbox](https://github.com/DavHau/sbox), instead of in Pi's process. The sandbox runs without Pi's config, credentials or session history. They talk over a Unix socket.
+
+Every call becomes one command run by `pi-glovebox-server` inside your sandbox:
+
+| Tool | Command |
+|---|---|
+| `bash` | `bash -c <command>` in Pi's working directory |
+| `read` | `: < file` to check access, `head -c 4100` to detect images with Pi's own detector, `cat` |
+| `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.
+
+pi-glovebox also blocks calls to tools that would run in Pi's process instead, returning an error the model sees:
+
+- every tool built into Pi, such as `grep`, `find`, `ls` and `codemode`, even if another extension activates it;
+- `bash`, `read`, `write` or `edit` when another extension provides it.
+
+## When to use it
+
+Pi sandbox extensions mostly take one of three approaches:
+
+- check tool calls against allow and deny lists, often asking the user, and wrap bash commands in an OS sandbox;
+- run the tools in a micro-VM the extension manages;
+- run all of Pi, extensions included, in a container.
+
+pi-glovebox separates where Pi runs from where the model's commands run, and leaves the second entirely to you: a bubblewrap or sbox sandbox, a container, a VM, or another machine reached through a forwarded socket. It has no policy and asks no questions, so it also works unattended, and Pi's process, environment, files and session history stay outside whatever you choose.
+
+## Requirements
+
+- 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.
+
+## Install
+
+```bash
+pi install npm:pi-glovebox          # or: pi install git:github.com/421anon/pi-glovebox
+npm install -g pi-glovebox          # pi-glovebox-server, or: nix-build -E '(import <nixpkgs> { }).callPackage ./. { }'
+```
+
+## Use
+
+```bash
+SOCKET_DIR=$(mktemp -d)
+env -i PATH="$PATH" HOME="$HOME" USER="$USER" sbox --bind "$SOCKET_DIR" "$SOCKET_DIR" -- pi-glovebox-server "$SOCKET_DIR/socket" &
+PI_GLOVEBOX_SOCKET="$SOCKET_DIR/socket" pi --no-builtin-tools
+```
+
+This sandbox sees the project read-write, `/nix` and the directories on your `PATH` read-only, and little else of the host: not the rest of `$HOME`, host `/tmp`, Pi's processes or the shell's environment. The server is ready once the socket exists.
+
+- `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.
+- 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.
+
+## License
+
+[MIT](LICENSE)

package/bin/pi-glovebox-server.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import net from "node:net";
+
+const output = 1;
+const exit = 2;
+
+const frame = (type, payload) => {
+  const header = Buffer.alloc(5);
+  header[0] = type;
+  header.writeUInt32BE(payload.length, 1);
+  return Buffer.concat([header, payload]);
+};
+
+net
+  .createServer((socket) => {
+    let received = Buffer.alloc(0);
+    let child;
+    let exited = false;
+
+    const finish = (code) => {
+      if (exited) return;
+      exited = true;
+      socket.end(frame(exit, Buffer.from(JSON.stringify(code))));
+    };
+
+    const forward = (stream) =>
+      stream.on("data", (chunk) => {
+        if (socket.write(frame(output, chunk))) return;
+        stream.pause();
+        socket.once("drain", () => stream.resume());
+      });
+
+    socket.on("error", () => {});
+    socket.on("close", () => {
+      if (!child || exited) return;
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {}
+    });
+
+    socket.on("data", function onRequest(chunk) {
+      received = Buffer.concat([received, chunk]);
+      const end = received.indexOf(10);
+      if (end < 0) return;
+      socket.off("data", onRequest);
+
+      let request;
+      try {
+        request = JSON.parse(received.subarray(0, end).toString());
+      } catch {}
+      const valid =
+        Array.isArray(request?.argv) &&
+        request.argv.length > 0 &&
+        request.argv.every((arg) => typeof arg === "string") &&
+        typeof request.cwd === "string" &&
+        (request.stdin === undefined || typeof request.stdin === "string");
+      if (!valid) return socket.destroy();
+      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);
+      }
+      forward(child.stdout);
+      forward(child.stderr);
+      child.on("error", (error) => {
+        socket.write(frame(output, Buffer.from(`${error.message}\n`)));
+        finish(null);
+      });
+      child.on("close", (code) => finish(code));
+      child.stdin.on("error", () => {});
+      child.stdin.end(request.stdin ?? "");
+    });
+  })
+  .listen(process.argv[2]);

package/extensions/index.ts

@@ -0,0 +1,133 @@
+import { existsSync, realpathSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	createBashTool,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	detectSupportedImageMimeTypeFromFile,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+
+const socketPath = process.env.PI_GLOVEBOX_SOCKET;
+if (!socketPath) throw new Error("PI_GLOVEBOX_SOCKET is not set");
+
+const imageSniffBytes = "4100";
+const ownFile = realpathSync(fileURLToPath(import.meta.url));
+const ownPaths = [ownFile, path.dirname(ownFile)];
+const ownTools = ["bash", "read", "write", "edit"];
+
+type Request = { argv: string[]; cwd: string; stdin?: string };
+type Options = { onData?: (data: Buffer) => void; signal?: AbortSignal; timeout?: number };
+type Result = { output: Buffer; exitCode: number | null };
+
+const run = (request: Request, { onData, signal, timeout }: Options = {}) =>
+	new Promise<Result>((resolve, reject) => {
+		const socket = net.createConnection(socketPath);
+		const output: Buffer[] = [];
+		let received = Buffer.alloc(0);
+		let exitCode: number | null | undefined;
+
+		const stop = (error: Error) => {
+			socket.destroy();
+			reject(error);
+		};
+		const abort = () => stop(new Error("aborted"));
+		const timer = timeout ? setTimeout(() => stop(new Error(`timeout:${timeout}`)), timeout * 1000) : undefined;
+		signal?.addEventListener("abort", abort, { once: true });
+
+		socket.on("data", (chunk) => {
+			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 (onData) onData(payload);
+					else output.push(payload);
+				} else {
+					exitCode = JSON.parse(payload.toString());
+				}
+				received = received.subarray(5 + payload.length);
+			}
+		});
+		socket.on("error", reject);
+		socket.on("close", () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			if (exitCode === undefined) reject(new Error("pi-glovebox: connection closed before the command finished"));
+			else resolve({ output: Buffer.concat(output), exitCode });
+		});
+
+		if (signal?.aborted) abort();
+		else socket.write(`${JSON.stringify(request)}\n`);
+	});
+
+const succeed = async (argv: string[], stdin?: string) => {
+	const { output, exitCode } = await run({ argv, cwd: "/", stdin });
+	if (exitCode !== 0) throw new Error(output.toString().trim() || `exit code ${exitCode}`);
+	return output;
+};
+
+const shell = (script: string, file: string, stdin?: string) =>
+	succeed(["bash", "-c", script, "pi-glovebox", file], stdin).then(() => {});
+
+const detectImageMimeType = async (file: string) => {
+	const head = await succeed(["head", "-c", imageSniffBytes, "--", file]);
+	const directory = await mkdtemp(path.join(tmpdir(), "pi-glovebox-"));
+	try {
+		await writeFile(path.join(directory, "head"), head);
+		return await detectSupportedImageMimeTypeFromFile(path.join(directory, "head"));
+	} finally {
+		await rm(directory, { recursive: true, force: true });
+	}
+};
+
+export default function (pi: ExtensionAPI) {
+	const cwd = process.cwd();
+	pi.on("tool_call", ({ toolName }) => {
+		const source = pi.getAllTools().find((tool) => tool.name === toolName)?.sourceInfo;
+		if (source?.source === "builtin") {
+			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` };
+		}
+	});
+	pi.registerTool(
+		createBashTool(cwd, {
+			operations: {
+				exec: (command, directory, options) =>
+					run({ argv: ["bash", "-c", command], cwd: directory }, options).then(({ exitCode }) => ({ exitCode })),
+			},
+		}),
+	);
+	pi.registerTool(
+		createReadTool(cwd, {
+			operations: {
+				readFile: (file) => succeed(["cat", "--", file]),
+				access: (file) => shell(': < "$1"', file),
+				detectImageMimeType,
+			},
+		}),
+	);
+	pi.registerTool(
+		createWriteTool(cwd, {
+			operations: {
+				writeFile: (file, content) => shell('cat > "$1"', file, content),
+				mkdir: (directory) => succeed(["mkdir", "-p", "--", directory]).then(() => {}),
+			},
+		}),
+	);
+	pi.registerTool(
+		createEditTool(cwd, {
+			operations: {
+				readFile: (file) => succeed(["cat", "--", file]),
+				writeFile: (file, content) => shell('cat > "$1"', file, content),
+				access: (file) => shell(': < "$1" && : >> "$1"', file),
+			},
+		}),
+	);
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "pi-glovebox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Run Pi's bash, read, write and edit tools in a separate sandbox, reached over a Unix socket",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "sandbox",
+    "bubblewrap"
+  ],
+  "license": "MIT",
+  "author": "Peter Ferenczy <ggpeti@gmail.com>",
+  "homepage": "https://github.com/421anon/pi-glovebox#readme",
+  "bugs": "https://github.com/421anon/pi-glovebox/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/421anon/pi-glovebox.git"
+  },
+  "type": "module",
+  "bin": {
+    "pi-glovebox-server": "bin/pi-glovebox-server.mjs"
+  },
+  "files": [
+    "bin",
+    "extensions"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}