pi-t3-bridge 0.2.0 → 0.4.0

package/src/bridge/t3-json.ts

@@ -1,5 +1,5 @@
-import { Type } from "@earendil-works/pi-ai";
-import type { Static, TSchema } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { Static, TSchema } from "typebox";
 import { Value } from "typebox/value";
 
 const ResultEnvelopeSchema = Type.Object({

package/src/bridge/tasks.ts

@@ -1,6 +1,6 @@
-import { Type } from "@earendil-works/pi-ai";
-import type { Static } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Static } from "typebox";
 
 import {
   escapeHtml,

package/src/bridge/thread.ts

@@ -1,4 +1,4 @@
-import { Type } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { callT3Tool, insideT3 } from "./t3-http.ts";

package/src/bridge/transcript.ts

@@ -1,10 +1,10 @@
-import { Type } from "@earendil-works/pi-ai";
-import type { Static } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Static } from "typebox";
 
 import { registerUnlessTaken } from "./claim.ts";
 

package/src/pstack/brief.ts

@@ -1,5 +1,5 @@
-import { Type } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { Value } from "typebox/value";
 
 // The child's extension reads its limits from the delegation brief

package/src/pstack/child.ts

@@ -1,14 +1,14 @@
 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";
 
-import { Type } from "@earendil-works/pi-ai";
 import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { bashTimeoutSeconds } from "../bridge/bash-timeout.ts";
@@ -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/models.ts

@@ -1,12 +1,12 @@
 import { readFileSync } from "node:fs";
 
-import { Type } from "@earendil-works/pi-ai";
-import type { Static } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import type {
   ExtensionAPI,
   ExtensionToolContext,
 } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Static } from "typebox";
 import { Value } from "typebox/value";
 
 import {

package/src/pstack/overlay.ts

@@ -0,0 +1,251 @@
+import { createHash } from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
+
+interface Patch {
+  readonly find: string;
+  readonly replace: string;
+}
+
+const PatchSchema = Type.Object({
+  find: Type.String(),
+  replace: Type.String(),
+});
+
+const OverlayManifestSchema = Type.Object({
+  files: Type.Record(Type.String(), Type.Array(PatchSchema)),
+  global: Type.Array(PatchSchema),
+  shared: Type.Array(
+    Type.Object({
+      files: Type.Array(Type.String()),
+      patches: Type.Array(PatchSchema),
+    })
+  ),
+  version: Type.Number(),
+});
+
+export type OverlayManifest = Static<typeof OverlayManifestSchema>;
+
+const TEXT_SUFFIX = ".md";
+const COPIED_ENTRIES = ["skills", "agents", "models.json"] as const;
+
+export const overlayDir = (extensionDir: string): string =>
+  path.join(extensionDir, "overlay");
+
+export const loadManifest = (dir: string): OverlayManifest => {
+  const manifestPath = path.join(dir, "overlay.json");
+  const parsed: unknown = JSON.parse(readFileSync(manifestPath, "utf-8"));
+
+  if (!Value.Check(OverlayManifestSchema, parsed)) {
+    throw new Error(
+      `overlay manifest ${manifestPath} does not match the overlay schema`
+    );
+  }
+
+  return parsed;
+};
+
+const patchesFor = (
+  manifest: OverlayManifest,
+  relativePath: string
+): readonly Patch[] => {
+  const own = manifest.files[relativePath] ?? [];
+
+  const shared = manifest.shared
+    .filter((group) => group.files.includes(relativePath))
+    .flatMap((group) => group.patches);
+
+  return [...shared, ...own];
+};
+
+export const applyOverlay = (
+  manifest: OverlayManifest,
+  relativePath: string,
+  text: string
+): string => {
+  let result = text;
+
+  for (const patch of patchesFor(manifest, relativePath)) {
+    if (!result.includes(patch.find)) {
+      throw new Error(
+        `overlay patch for ${relativePath} no longer matches upstream text: ${JSON.stringify(patch.find.slice(0, 120))}. Update overlay/overlay.json for the new upstream wording.`
+      );
+    }
+
+    result = result.replaceAll(patch.find, patch.replace);
+  }
+
+  for (const patch of manifest.global) {
+    result = result.replaceAll(patch.find, patch.replace);
+  }
+
+  return result;
+};
+
+const walkFiles = (root: string, base = root): string[] =>
+  readdirSync(base, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(base, entry.name);
+
+    if (entry.isDirectory()) {
+      return walkFiles(root, full);
+    }
+
+    return entry.isFile() ? [path.relative(root, full)] : [];
+  });
+
+const overlayCacheRoot = (): string => {
+  const stateHome =
+    process.env.XDG_STATE_HOME?.trim() ||
+    path.join(homedir(), ".local", "state");
+
+  return path.join(stateHome, "pi-t3", "pstack-overlay");
+};
+
+const INPUT_ENTRIES = [
+  ...COPIED_ENTRIES,
+  "hooks/session-start-context.md",
+] as const;
+
+const fingerprint = (
+  upstreamRoot: string,
+  manifestText: string,
+  extensionModules: string
+): string => {
+  const hash = createHash("sha256")
+    .update(manifestText)
+    .update(extensionModules);
+
+  for (const entry of INPUT_ENTRIES) {
+    const full = path.join(upstreamRoot, entry);
+
+    if (!existsSync(full)) {
+      continue;
+    }
+
+    const files = statSync(full).isDirectory() ? walkFiles(full) : [entry];
+
+    for (const relative of files.toSorted()) {
+      const filePath = statSync(full).isDirectory()
+        ? path.join(full, relative)
+        : full;
+
+      const name = statSync(full).isDirectory()
+        ? path.join(entry, relative)
+        : entry;
+
+      hash.update(name).update(readFileSync(filePath));
+    }
+  }
+
+  return hash.digest("hex").slice(0, 16);
+};
+
+// The pstack the agent reads: upstream copied out of pstack/, with the
+// overlay in overlay/ applied. A copy keyed by the hash of both inputs, so
+// an upstream sync or an overlay edit builds a fresh copy and a stale one
+// is never served. Nothing here writes into pstack/.
+export const materializePstack = (
+  upstreamRoot: string,
+  dir: string,
+  cacheRoot: string = overlayCacheRoot()
+): string => {
+  if (!existsSync(path.join(upstreamRoot, "skills"))) {
+    return upstreamRoot;
+  }
+
+  const manifestText = readFileSync(path.join(dir, "overlay.json"), "utf-8");
+  const manifest = loadManifest(dir);
+
+  const extensionModules = path.resolve(
+    path.dirname(upstreamRoot),
+    "node_modules"
+  );
+
+  const target = path.join(
+    cacheRoot,
+    fingerprint(upstreamRoot, manifestText, extensionModules)
+  );
+
+  if (
+    existsSync(path.join(target, ".complete")) &&
+    (!existsSync(extensionModules) ||
+      existsSync(path.join(target, "node_modules")))
+  ) {
+    return target;
+  }
+
+  mkdirSync(cacheRoot, { recursive: true });
+  rmSync(target, { force: true, recursive: true });
+
+  const staging = `${target}.${process.pid}.tmp`;
+
+  rmSync(staging, { force: true, recursive: true });
+
+  try {
+    for (const entry of COPIED_ENTRIES) {
+      const from = path.join(upstreamRoot, entry);
+
+      if (existsSync(from)) {
+        cpSync(from, path.join(staging, entry), { recursive: true });
+      }
+    }
+
+    const hookFrom = path.join(
+      upstreamRoot,
+      "hooks",
+      "session-start-context.md"
+    );
+
+    if (existsSync(hookFrom)) {
+      mkdirSync(path.join(staging, "hooks"), { recursive: true });
+      cpSync(hookFrom, path.join(staging, "hooks", "session-start-context.md"));
+    }
+
+    // Scripts under skills/ import packages such as commander. Inside the
+    // extension they resolve them from the extension's node_modules, so
+    // the copy links that directory in instead of copying it.
+    if (
+      existsSync(extensionModules) &&
+      !existsSync(path.join(staging, "node_modules"))
+    ) {
+      symlinkSync(extensionModules, path.join(staging, "node_modules"), "dir");
+    }
+
+    for (const relative of walkFiles(staging)) {
+      if (!relative.endsWith(TEXT_SUFFIX)) {
+        continue;
+      }
+
+      const filePath = path.join(staging, relative);
+
+      writeFileSync(
+        filePath,
+        applyOverlay(manifest, relative, readFileSync(filePath, "utf-8"))
+      );
+    }
+
+    writeFileSync(path.join(staging, ".complete"), "");
+    renameSync(staging, target);
+  } catch (error) {
+    rmSync(staging, { force: true, recursive: true });
+    throw error;
+  }
+
+  return target;
+};

package/src/pstack/resources.ts

@@ -1,21 +1,35 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 
+import { materializePstack, overlayDir } from "./overlay.ts";
+
 export interface PstackPaths {
   readonly extensionDir: string;
   readonly pstackRoot: string;
   readonly skillsDir: string;
+  readonly upstreamRoot: string;
 }
 
+let cached: PstackPaths | undefined;
+
 export const pstackPaths = (): PstackPaths => {
+  if (cached) {
+    return cached;
+  }
+
   const extensionDir = path.resolve(import.meta.dirname, "../..");
-  const pstackRoot = path.join(extensionDir, "pstack");
+  const upstreamRoot = path.join(extensionDir, "pstack");
+
+  const pstackRoot = materializePstack(upstreamRoot, overlayDir(extensionDir));
 
-  return {
+  cached = {
     extensionDir,
     pstackRoot,
     skillsDir: path.join(pstackRoot, "skills"),
+    upstreamRoot,
   };
+
+  return cached;
 };
 
 export const policyPath = (): string =>

package/src/pstack/results.ts

@@ -1,5 +1,5 @@
-import { Type } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { readLedger } from "../bridge/state.ts";