pi-t3-bridge 0.2.0 → 0.3.0

package/README.md

@@ -25,7 +25,9 @@ You need the following programs:
 - Pi 1.4.0 or later
 - T3 Code, if you want to run Pi threads inside T3 or call T3 tools from Pi
 
-The child sandbox uses the macOS `sandbox-exec` command, so the shell sandbox for delegated children works on macOS only.
+Delegated children run their shell commands in a sandbox: `sandbox-exec` on macOS, and `bwrap` (bubblewrap) on Linux and WSL2. Linux needs the `bubblewrap` package and unprivileged user namespaces. On Ubuntu, the `bubblewrap` package ships an AppArmor profile that lets `bwrap` run (checked on 26.04). If AppArmor still blocks it, run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`. Native Windows and WSL1 have no sandbox. Where no sandbox can run, a child's shell commands are blocked unless `childSandbox` is `"off"` in the config.
+
+The tests need Docker, because they also run the child tests in Linux containers.
 
 ## Install
 
@@ -220,6 +222,7 @@ The bridge reads one JSON file per machine, at `~/.config/pi-t3/config.json`. Ev
 ```json
 {
   "bashTimeoutSeconds": 300,
+  "childSandbox": "on",
   "mcpUrl": "http://127.0.0.1:3773/mcp",
   "steer": "on"
 }
@@ -228,6 +231,7 @@ The bridge reads one JSON file per machine, at `~/.config/pi-t3/config.json`. Ev
 | Key | Default | Meaning |
 | --- | --- | --- |
 | `bashTimeoutSeconds` | `300` | The longest a shell command can run, in seconds. |
+| `childSandbox` | `"on"` | Whether a delegated child's shell commands need a sandbox. With `"on"`, a child's `bash` is blocked when no sandbox can run. With `"off"`, commands run with no sandbox on every platform, and the child's report says `SANDBOX: off`. |
 | `mcpUrl` | `http://127.0.0.1:3773/mcp` | The T3 MCP endpoint to use outside a T3 thread. |
 | `steer` | `"on"` | The stop checks, as `"on"`, `"shadow"`, or `"off"`. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-t3-bridge",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pi extension adapter for t3-pstack inside T3 Code.",
   "keywords": [
     "pi-extension",
@@ -53,6 +53,7 @@
     "@types/node": "^26.6.5",
     "oxfmt": "^0.74.0",
     "oxlint": "^1.89.0",
+    "testcontainers": "^12.2.1",
     "typebox": "1.3.27",
     "typescript": "^7.0.2",
     "ultracite": "^8.0.1"

package/src/bridge/config.ts

@@ -17,8 +17,14 @@ const SteerSchema = Type.Union([
   Type.Literal("shadow"),
 ]);
 
+const ChildSandboxSchema = Type.Union([
+  Type.Literal("on"),
+  Type.Literal("off"),
+]);
+
 export interface Config {
   readonly bashTimeoutSeconds: number | undefined;
+  readonly childSandbox: Static<typeof ChildSandboxSchema> | undefined;
   readonly mcpUrl: string | undefined;
   readonly steer: Static<typeof SteerSchema> | undefined;
 }
@@ -30,6 +36,7 @@ interface Loaded {
 
 const EMPTY: Config = {
   bashTimeoutSeconds: undefined,
+  childSandbox: undefined,
   mcpUrl: undefined,
   steer: undefined,
 };
@@ -80,6 +87,7 @@ const parse = (text: string): Loaded => {
         "bashTimeoutSeconds",
         Type.Number({ exclusiveMinimum: 0 })
       ),
+      childSandbox: field("childSandbox", ChildSandboxSchema),
       mcpUrl: field("mcpUrl", Type.String({ minLength: 1 })),
       steer: field("steer", SteerSchema),
     },

package/src/pstack/child.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -17,33 +17,29 @@ import { ownThreadId } from "../bridge/thread.ts";
 import { sessionBrief } from "./brief.ts";
 import type { Brief } from "./brief.ts";
 import { policyPath } from "./resources.ts";
+import {
+  chooseSandbox,
+  real,
+  sandboxLabel,
+  unavailableReason,
+  wrap,
+} from "./sandbox.ts";
+import type { Sandbox } from "./sandbox.ts";
 
 // Rules a delegated child cannot talk its way around. A session whose first
-// message is a pstack brief gets them: writes only inside its workdir (a macOS
-// sandbox around every shell command) and only to its listed files (write and
-// edit), its time and disk limits, and a report line the code writes from
-// commands it runs itself, not from what the model says.
+// message is a pstack brief gets them: writes only inside its workdir (a
+// sandbox around every shell command, or no shell at all) and only to its
+// listed files (write and edit), its time and disk limits, and a report line
+// the code writes from commands it runs itself, not from what the model says.
 
 const run = promisify(execFile);
 
-const SANDBOX = "/usr/bin/sandbox-exec";
-
 const DU_TIMEOUT_MS = 15_000;
 
 const SCRATCH = ".scratch/";
 
 const WRITE_TOOLS: ReadonlySet<string> = new Set(["edit", "write"]);
 
-const quote = (text: string): string => `'${text.replaceAll("'", `'\\''`)}'`;
-
-const real = (target: string): string => {
-  try {
-    return realpathSync(target);
-  } catch {
-    return target;
-  }
-};
-
 // Where a write to target lands once every symlink on its path is followed.
 // Undefined for a dangling link, whose landing spot cannot be known.
 const landing = (target: string): string | undefined => {
@@ -68,50 +64,6 @@ const landing = (target: string): string | undefined => {
     : path.join(base, path.basename(target));
 };
 
-// Tool caches and installs stay writable, so uv, npm and mise work.
-const writableRoots = (workdir: string, gitDir: string | undefined) => {
-  const home = homedir();
-
-  return [
-    workdir,
-    gitDir,
-    path.join(home, ".cache"),
-    path.join(home, "Library", "Caches"),
-    path.join(home, ".npm"),
-    path.join(home, ".local", "share", "uv"),
-    path.join(home, ".local", "share", "mise"),
-    "/private/var/folders",
-    "/dev",
-  ]
-    .filter((root): root is string => root !== undefined)
-    .flatMap((root) => [root, real(root)]);
-};
-
-// Hooks and config in the git dir run later, outside the sandbox, when the
-// parent commits or merges the child's work, so they stay read-only.
-const gitDenies = (gitDir: string | undefined): string[] =>
-  gitDir === undefined
-    ? []
-    : [gitDir, real(gitDir)].flatMap((dir) => [
-        `(subpath ${JSON.stringify(path.join(dir, "hooks"))})`,
-        `(literal ${JSON.stringify(path.join(dir, "config"))})`,
-        `(literal ${JSON.stringify(path.join(dir, "config.lock"))})`,
-      ]);
-
-const sandboxProfile = (
-  roots: readonly string[],
-  denies: readonly string[]
-): string =>
-  [
-    "(version 1)",
-    "(allow default)",
-    "(deny file-write*)",
-    `(allow file-write* ${[...new Set(roots)].map((root) => `(subpath ${JSON.stringify(root)})`).join(" ")})`,
-    ...(denies.length === 0
-      ? []
-      : [`(deny file-write* ${[...new Set(denies)].join(" ")})`]),
-  ].join("");
-
 const globToRegExp = (glob: string): RegExp => {
   const source = glob
     .replace(/^\.\//u, "")
@@ -228,11 +180,12 @@ interface Report {
   readonly diskMb: number | undefined;
   readonly minutes: number;
   readonly outside: readonly string[];
+  readonly sandbox: Sandbox | undefined;
   readonly status: string;
 }
 
 const reportBlock = (report: Report): string => {
-  const { accepted, brief, diskMb, minutes, outside } = report;
+  const { accepted, brief, diskMb, minutes, outside, sandbox } = report;
   const tail = accepted.tail.trim().split("\n").slice(-10).join("\n");
 
   const before =
@@ -248,6 +201,7 @@ const reportBlock = (report: Report): string => {
     `FILES: ${report.changed} changed; outside the list: ${outside.length === 0 ? "none" : outside.join(", ")}`,
     `DISK: ${diskMb === undefined ? "unknown" : `+${diskMb.toFixed(1)} MB`} in the workdir (limit ${brief.diskMb ?? "?"} MB)`,
     `TIME: ${minutes.toFixed(1)} of ${brief.minutes ?? "?"} min`,
+    `SANDBOX: ${sandboxLabel(sandbox)}`,
   ].join("\n");
 };
 
@@ -260,6 +214,7 @@ interface ChildState {
   gitDir: string | undefined;
   greenAtStart: boolean;
   ready: boolean;
+  sandbox: Sandbox | undefined;
 }
 
 export const registerChild = (pi: ExtensionAPI): void => {
@@ -272,24 +227,29 @@ export const registerChild = (pi: ExtensionAPI): void => {
     gitDir: undefined,
     greenAtStart: false,
     ready: false,
+    sandbox: undefined,
   };
 
-  const sandboxed = (command: string, workdir: string): string =>
-    existsSync(SANDBOX)
-      ? `${SANDBOX} -p ${quote(sandboxProfile(writableRoots(workdir, state.gitDir), gitDenies(state.gitDir)))} /bin/bash -c ${quote(command)}`
-      : command;
-
   const runAcceptance = async (
     command: string,
     workdir: string,
     seconds: number
   ): Promise<{ exit: number; tail: string }> => {
+    const wrapped = wrap(state.sandbox, command, workdir, state.gitDir);
+
+    if (wrapped === undefined) {
+      return {
+        exit: 126,
+        tail: `not run: no sandbox (${unavailableReason(state.sandbox)})`,
+      };
+    }
+
     try {
-      const { stdout, stderr } = await run(
-        "/bin/bash",
-        ["-c", sandboxed(command, workdir)],
-        { cwd: workdir, maxBuffer: 16 * 1024 * 1024, timeout: seconds * 1000 }
-      );
+      const { stdout, stderr } = await run("/bin/bash", ["-c", wrapped], {
+        cwd: workdir,
+        maxBuffer: 16 * 1024 * 1024,
+        timeout: seconds * 1000,
+      });
 
       return { exit: 0, tail: `${stdout}${stderr}` };
     } catch (error) {
@@ -321,6 +281,8 @@ export const registerChild = (pi: ExtensionAPI): void => {
       state.gitDir = undefined;
     }
 
+    state.sandbox = await chooseSandbox(state.gitDir);
+
     state.baselineKb = await duKb(ctx.cwd);
 
     const redBeforeGreen = readRedBeforeGreen();
@@ -388,12 +350,21 @@ export const registerChild = (pi: ExtensionAPI): void => {
     const { input } = event;
 
     if (event.toolName === "bash" && Value.Check(BashInputSchema, input)) {
+      const wrapped = wrap(state.sandbox, input.command, ctx.cwd, state.gitDir);
+
+      if (wrapped === undefined) {
+        return {
+          block: true,
+          reason: `No sandbox can run for this shell (${unavailableReason(state.sandbox)}), so shell commands are blocked. The user can install \`bubblewrap\`, set kernel.apparmor_restrict_unprivileged_userns=0, or set "childSandbox": "off" in ~/.config/pi-t3/config.json. Use no more shell commands. Report STATUS: BLOCKED (no sandbox).`,
+        };
+      }
+
       const limit = Math.max(1, Math.ceil(remaining));
 
       input.timeout = Value.Check(Type.Number(), input.timeout)
         ? Math.min(input.timeout, limit)
         : limit;
-      input.command = sandboxed(input.command, ctx.cwd);
+      input.command = wrapped;
 
       return;
     }
@@ -497,7 +468,10 @@ export const registerChild = (pi: ExtensionAPI): void => {
     const diskOver = state.diskOver || overLimit(diskMb, brief.diskMb);
 
     const status = reportStatus(
-      state.greenAtStart || overTime || diskOver,
+      state.greenAtStart ||
+        overTime ||
+        diskOver ||
+        unavailableReason(state.sandbox) !== undefined,
       accepted,
       outside
     );
@@ -510,6 +484,7 @@ export const registerChild = (pi: ExtensionAPI): void => {
       diskMb,
       minutes,
       outside,
+      sandbox: state.sandbox,
       status,
     });
 

package/src/pstack/sandbox.ts

@@ -0,0 +1,253 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { Type } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
+
+import { readConfig } from "../bridge/config.ts";
+
+// Which sandbox a delegated child's shell commands run in, and how a command
+// is wrapped for it. The policy (which paths a command may write, which stay
+// read-only inside them) is the same on every OS. Each backend turns it into
+// a wrapped command string.
+
+const run = promisify(execFile);
+
+const SANDBOX = "/usr/bin/sandbox-exec";
+
+// Only root can write these, unlike the mise and npm directories on PATH,
+// which a child can write, so a child cannot swap in a bwrap of its own.
+const BWRAP_PATHS = ["/usr/bin/bwrap", "/usr/local/bin/bwrap"];
+
+const PROBE_TIMEOUT_MS = 10_000;
+
+const ProbeFailureSchema = Type.Object({
+  code: Type.Optional(Type.Union([Type.Number(), Type.String()])),
+  message: Type.Optional(Type.String()),
+  stderr: Type.Optional(Type.String()),
+});
+
+export type Sandbox =
+  | { kind: "bubblewrap"; bwrap: string }
+  | { kind: "off" }
+  | { kind: "sandbox-exec" }
+  | { kind: "unavailable"; reason: string };
+
+const quote = (text: string): string => `'${text.replaceAll("'", `'\\''`)}'`;
+
+export const real = (target: string): string => {
+  try {
+    return realpathSync(target);
+  } catch {
+    return target;
+  }
+};
+
+// Tool caches and installs stay writable, so uv, npm and mise work.
+const cacheRoots = (): string[] => {
+  const home = homedir();
+
+  return [
+    path.join(home, ".cache"),
+    path.join(home, ".npm"),
+    path.join(home, ".local", "share", "uv"),
+    path.join(home, ".local", "share", "mise"),
+  ];
+};
+
+const writableRoots = (workdir: string, gitDir: string | undefined) =>
+  [
+    workdir,
+    gitDir,
+    ...cacheRoots(),
+    path.join(homedir(), "Library", "Caches"),
+    "/private/var/folders",
+    tmpdir(),
+    "/dev",
+  ]
+    .filter((root): root is string => root !== undefined)
+    .flatMap((root) => [root, real(root)]);
+
+// Hooks and config in the git dir run later, outside the sandbox, when the
+// parent commits or merges the child's work, so they stay read-only.
+const gitDenies = (gitDir: string | undefined): string[] =>
+  gitDir === undefined
+    ? []
+    : [gitDir, real(gitDir)].flatMap((dir) => [
+        `(subpath ${JSON.stringify(path.join(dir, "hooks"))})`,
+        `(literal ${JSON.stringify(path.join(dir, "config"))})`,
+        `(literal ${JSON.stringify(path.join(dir, "config.lock"))})`,
+      ]);
+
+const sandboxProfile = (
+  roots: readonly string[],
+  denies: readonly string[]
+): string =>
+  [
+    "(version 1)",
+    "(allow default)",
+    "(deny file-write*)",
+    `(allow file-write* ${[...new Set(roots)].map((root) => `(subpath ${JSON.stringify(root)})`).join(" ")})`,
+    ...(denies.length === 0
+      ? []
+      : [`(deny file-write* ${[...new Set(denies)].join(" ")})`]),
+  ].join("");
+
+// bwrap creates a missing bind target on the host, so only paths that exist
+// are bound, each once, where it really is.
+const existing = (paths: readonly string[]): string[] => [
+  ...new Set(
+    paths.flatMap((target) => (existsSync(target) ? [real(target)] : []))
+  ),
+];
+
+// A read-only config also stops `git config`: its rename of config.lock over
+// config fails on the mount, so config.lock needs no bind of its own.
+const bwrapArgs = (
+  bwrap: string,
+  command: string,
+  workdir: string,
+  gitDir: string | undefined
+): string[] => [
+  bwrap,
+  "--ro-bind",
+  "/",
+  "/",
+  "--dev-bind",
+  "/dev",
+  "/dev",
+  "--proc",
+  "/proc",
+  ...existing(writableRoots(workdir, gitDir)).flatMap((root) =>
+    root === "/dev" ? [] : ["--bind", root, root]
+  ),
+  ...existing(
+    gitDir === undefined
+      ? []
+      : [path.join(gitDir, "hooks"), path.join(gitDir, "config")]
+  ).flatMap((deny) => ["--ro-bind", deny, deny]),
+  "--",
+  "/bin/bash",
+  "-c",
+  command,
+];
+
+// One run of bwrap tells whether it is installed and may make the user
+// namespace it needs. Docker's default seccomp, Ubuntu 24.04's AppArmor
+// default, and WSL1 all stop it here.
+const probeBwrap = async (bwrap: string): Promise<string | undefined> => {
+  try {
+    await run(bwrap, ["--ro-bind", "/", "/", "--", "/bin/true"], {
+      timeout: PROBE_TIMEOUT_MS,
+    });
+
+    return undefined;
+  } catch (error) {
+    const failed = Value.Check(ProbeFailureSchema, error) ? error : {};
+
+    return `bwrap cannot start: ${(failed.stderr || failed.message || "no output").trim()}`;
+  }
+};
+
+// A missing root can't be bound, and a missing hooks directory could be
+// created by the child, so both are made on the host first. They are empty
+// directories, so git and the tools see no change.
+const prepareBinds = (gitDir: string | undefined): void => {
+  for (const root of cacheRoots()) {
+    mkdirSync(root, { recursive: true });
+  }
+
+  if (gitDir !== undefined) {
+    mkdirSync(path.join(gitDir, "hooks"), { recursive: true });
+  }
+};
+
+// Run once per child, before its first command. "childSandbox": "off" in the
+// config wins on every platform.
+export const chooseSandbox = async (
+  gitDir: string | undefined
+): Promise<Sandbox> => {
+  if (readConfig().childSandbox === "off") {
+    return { kind: "off" };
+  }
+
+  if (process.platform === "darwin" && existsSync(SANDBOX)) {
+    return { kind: "sandbox-exec" };
+  }
+
+  if (process.platform !== "linux") {
+    return {
+      kind: "unavailable",
+      reason: `no sandbox for ${process.platform}`,
+    };
+  }
+
+  const bwrap = BWRAP_PATHS.find((candidate) => existsSync(candidate));
+
+  if (bwrap === undefined) {
+    return {
+      kind: "unavailable",
+      reason: `bwrap is not installed in ${BWRAP_PATHS.join(" or ")}`,
+    };
+  }
+
+  const problem = await probeBwrap(bwrap);
+
+  if (problem !== undefined) {
+    return { kind: "unavailable", reason: problem };
+  }
+
+  prepareBinds(gitDir);
+
+  return { bwrap, kind: "bubblewrap" };
+};
+
+// Undefined when no sandbox runs: the caller must not run the command.
+export const wrap = (
+  sandbox: Sandbox | undefined,
+  command: string,
+  workdir: string,
+  gitDir: string | undefined
+): string | undefined => {
+  switch (sandbox?.kind) {
+    case "sandbox-exec": {
+      return `${SANDBOX} -p ${quote(sandboxProfile(writableRoots(workdir, gitDir), gitDenies(gitDir)))} /bin/bash -c ${quote(command)}`;
+    }
+
+    case "bubblewrap": {
+      return bwrapArgs(sandbox.bwrap, command, workdir, gitDir)
+        .map(quote)
+        .join(" ");
+    }
+
+    case "off": {
+      return command;
+    }
+
+    default: {
+      return undefined;
+    }
+  }
+};
+
+// Why no sandbox runs, or undefined when one does (or "off" was chosen).
+export const unavailableReason = (
+  sandbox: Sandbox | undefined
+): string | undefined => {
+  if (sandbox === undefined) {
+    return "not chosen yet";
+  }
+
+  return sandbox.kind === "unavailable" ? sandbox.reason : undefined;
+};
+
+export const sandboxLabel = (sandbox: Sandbox | undefined): string => {
+  const reason = unavailableReason(sandbox);
+
+  return reason === undefined
+    ? (sandbox?.kind ?? "")
+    : `unavailable (${reason})`;
+};