Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

feat: box build folder shadows and port forwards

ogsamrat034be5977f3f
diff --git a/apps/app/src/app/lib/omnirush-server.ts b/apps/app/src/app/lib/omnirush-server.ts
index 937d7400..46c7e23f 100644
--- a/apps/app/src/app/lib/omnirush-server.ts
+++ b/apps/app/src/app/lib/omnirush-server.ts
@@ -540,6 +540,8 @@ export type OmniRushWorkspaceBox = {
setup?: OmniRushWorkspaceBoxSetup | null;
/** Asked for one chat: it started on this computer before the sandbox was required and stays here. */
chatKept?: boolean;
+ /** Servers in the sandbox open at the same port on this computer's 127.0.0.1 (Docker/Podman). Older servers: absent. */
+ ports?: Array<{ port: number; url: string; line: string }>;
};
export type OmniRushWorkspaceBoxSetup = {
need: "none" | "linux_allow" | "win_install" | "win_restart" | "win_update" | "mac_vm" | "runtime" | "cannot_run";
diff --git a/apps/app/src/react-app/domains/settings/linux-sandbox.ts b/apps/app/src/react-app/domains/settings/linux-sandbox.ts
index 2cc858ff..7f2406b2 100644
--- a/apps/app/src/react-app/domains/settings/linux-sandbox.ts
+++ b/apps/app/src/react-app/domains/settings/linux-sandbox.ts
@@ -96,6 +96,12 @@ export function linuxSandboxNextStep(box: OmniRushWorkspaceBox): LinuxSandboxNex
return { title: "No sandbox backend works here", detail: box.runtime?.reason ?? "No container runtime was found on this computer.", command: null };
}
+/** A ready box's detail, then one line per server in it open on this computer (Docker/Podman boxes). */
+function withPorts(detail: string, box: OmniRushWorkspaceBox): string {
+ const lines = (box.ports ?? []).slice(0, 3).map((item) => item.line);
+ return lines.length ? [detail, ...lines].join(" ") : detail;
+}
+
/** The status row: what the sandbox is doing now, or why it is not used and what to do. */
export function linuxSandboxView(box: OmniRushWorkspaceBox, pending: LinuxSandboxPending = null): LinuxSandboxView {
const base = { progress: null, step: null, action: null, errorDetail: null };
@@ -121,8 +127,8 @@ export function linuxSandboxView(box: OmniRushWorkspaceBox, pending: LinuxSandbo
return { ...base, tone: "busy", title: "Starting the sandbox…", detail: using ? `Using ${using}. This takes a few seconds.` : "This takes a few seconds." };
case "ready":
// On by choice in a folder with this computer's builds: the warning; on macOS / Windows: that chats run in Linux.
- if (box.hostBuilds && !box.hostBuilds.native) return { ...base, tone: "attention", title: "Ready", detail: box.hostBuilds.notice };
- return { ...base, tone: "ready", title: "Ready", detail: box.boxNotice ?? (using ? `Commands run in a Linux container (${using}).` : "Commands run in a Linux container.") };
+ if (box.hostBuilds && !box.hostBuilds.native) return { ...base, tone: "attention", title: "Ready", detail: withPorts(box.hostBuilds.notice, box) };
+ return { ...base, tone: "ready", title: "Ready", detail: withPorts(box.boxNotice ?? (using ? `Commands run in a Linux container (${using}).` : "Commands run in a Linux container."), box) };
case "failed":
return { ...base, tone: "error", title: "The sandbox could not start", detail: RUNS_HERE, action: { kind: "retry", label: "Try again" }, errorDetail: box.error ?? box.notice };
case "unavailable": {
diff --git a/apps/app/tests/linux-sandbox-card.test.tsx b/apps/app/tests/linux-sandbox-card.test.tsx
index 6485ea3a..7588bfa1 100644
--- a/apps/app/tests/linux-sandbox-card.test.tsx
+++ b/apps/app/tests/linux-sandbox-card.test.tsx
@@ -121,6 +121,12 @@ describe("Linux sandbox card", () => {
expect(markup).not.toContain("Try again");
});
+ test("ready with a server in the box open on this computer: its line after the usual one", () => {
+ const ports = [{ port: 8765, url: "http://127.0.0.1:8765", line: "Port 8765 in the sandbox is open on this computer at http://127.0.0.1:8765" }];
+ const ready = linuxSandboxView(box({ ...on, state: "ready", ports }));
+ expect(ready.detail).toBe("Commands run in a Linux container (Docker Desktop 27.1). Port 8765 in the sandbox is open on this computer at http://127.0.0.1:8765");
+ });
+
test("failed: plain words, Try again, the raw error behind Show details", () => {
const raw = "could not start the sandbox: boxd did not answer on 127.0.0.1:41871 within 20s";
const view = linuxSandboxView(box({ ...on, state: "failed", error: raw }));
diff --git a/apps/server/src/box/backends/apple.ts b/apps/server/src/box/backends/apple.ts
index f7e75933..6c91e575 100644
--- a/apps/server/src/box/backends/apple.ts
+++ b/apps/server/src/box/backends/apple.ts
@@ -283,6 +283,8 @@ async function open(ctx: OpenContext): Promise<Opened> {
export const appleDriver: BoxDriver = {
kind: "apple",
+ /** Its own VM network: the box's servers reach this computer's 127.0.0.1 through boxd (ports.ts). */
+ forwardsPorts: false,
execFallback: false,
imagePresent,
pull,
diff --git a/apps/server/src/box/backends/bwrap.ts b/apps/server/src/box/backends/bwrap.ts
index 473e2325..6db43b91 100644
--- a/apps/server/src/box/backends/bwrap.ts
+++ b/apps/server/src/box/backends/bwrap.ts
@@ -22,6 +22,7 @@ import os from "node:os";
import path from "node:path";
import { GOARCH, RUN_DIR, SHIMS_DIR, containerName, containerRoot, helperPath, newToken, readJson, writeJson, type BoxInstallLog, type BoxRuntime } from "../common.js";
+import { shadowId, type ShadowPlan } from "../required.js";
import { runCommand, type RunCommand, type RunOptions } from "../run.js";
import type { RuntimeResult } from "../runtime.js";
import { YOUNG_IMAGE_MS, removableImage, removeTree, staleEntries } from "../retention.mjs";
@@ -166,13 +167,19 @@ export function boxdEnv({ token, croot, idleMinutes = IDLE_MINUTES, listen = "12
}
/** `boxrun up` arguments for a project's box. */
-export function upArgs({ box, store, image, boxd, portFile, root, croot, runFolder, shims = null, pkglog = null, token, bwrap = null, idleMinutes = IDLE_MINUTES, listen, platform = "linux", mapPath = (p: string) => p }: { box: string; store: string; image: string; boxd: string; portFile: string; root: string; croot: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; bwrap?: string | null; idleMinutes?: number; listen?: string; platform?: NodeJS.Platform; mapPath?: (p: string) => string }): string[] {
+export function upArgs({ box, store, image, boxd, portFile, root, croot, runFolder, shims = null, pkglog = null, token, bwrap = null, idleMinutes = IDLE_MINUTES, listen, platform = "linux", mapPath = (p: string) => p, shadows = null, shadowStore = null }: { box: string; store: string; image: string; boxd: string; portFile: string; root: string; croot: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; bwrap?: string | null; idleMinutes?: number; listen?: string; platform?: NodeJS.Platform; mapPath?: (p: string) => string; shadows?: Pick<ShadowPlan, "binds"> | null; shadowStore?: string | null }): string[] {
const args = ["up", "--box", box, "--store", store, "--image", image, "--boxd", boxd, "--port-file", portFile,
"--bind", `${mapPath(root)}=${croot}`, "--bind", `${mapPath(runFolder)}=${RUN_DIR}`];
if (shims) args.push("--ro-bind", `${mapPath(shims)}=${SHIMS_DIR}-src`);
if (pkglog) args.push("--bind", `${mapPath(pkglog.root)}=${containerRoot(pkglog.root, platform)}`);
for (const kv of boxdEnv({ token, croot, idleMinutes, ...(listen ? { listen } : {}) })) args.push("--env", kv);
if (bwrap) args.push("--bwrap", bwrap);
+ // The box's own build folders (required.ts shadowPlan; backends whose boxrun runs as root):
+ // the per-box store on the backend's own disk, and each folder bound from it (boxrun init Binds).
+ if (shadows && shadowStore) {
+ args.push("--shadow-store", shadowStore);
+ for (const bind of shadows.binds ?? []) args.push("--shadow", `${bind.id ?? shadowId(bind.path)}=${bind.target}`);
+ }
return args;
}
diff --git a/apps/server/src/box/backends/container.ts b/apps/server/src/box/backends/container.ts
index a1f3e6eb..ee8c5278 100644
--- a/apps/server/src/box/backends/container.ts
+++ b/apps/server/src/box/backends/container.ts
@@ -249,6 +249,8 @@ export async function listContainers(runtime: BoxRuntime, { run = runCommand }:
export const containerDriver: BoxDriver = {
kind: "container",
+ /** The box has its own network: its servers reach this computer's 127.0.0.1 through boxd (ports.ts). */
+ forwardsPorts: false,
/** `docker exec` works when boxd is down (boxsh's fallback). */
execFallback: true,
async imagePresent(runtime, image, { run = runCommand } = {}) {
diff --git a/apps/server/src/box/backends/index.ts b/apps/server/src/box/backends/index.ts
index a0d3fae9..2eeecf51 100644
--- a/apps/server/src/box/backends/index.ts
+++ b/apps/server/src/box/backends/index.ts
@@ -212,14 +212,14 @@ function alternative(r: Probed | { backend: string; name: string; ok: false; rea
* flavor, ..., why }) or { ok: false, reason, tried }. `asked`: a backend id
* or "auto" (the setting); `allow`: the server's allowlist (null: any).
*/
-export async function detectBackend({ boxHome, env = process.env, platform = process.platform, home = os.homedir(), exists = existsSync, run = runCommand, wsl = platform === "linux" && isWsl(env), now = Date.now(), fresh = false, all = false, timeoutMs, asked = env.OMNIRUSH_BOX_BACKEND, allow = null, arch = process.arch, release = os.release() }: DetectOptions = {}): Promise<RuntimeResult> {
+export async function detectBackend({ boxHome, env = process.env, platform = process.platform, home = os.homedir(), exists = existsSync, run = runCommand, wsl = platform === "linux" && isWsl(env), now = Date.now(), fresh = false, all = false, timeoutMs, asked = env.OMNIRUSH_BOX_BACKEND, allow = null, arch = process.arch, release = os.release(), preferShadows = false }: DetectOptions = {}): Promise<RuntimeResult> {
let wanted = normalizeBackend(asked);
let legacyRuntime = String(env.OMNIRUSH_BOX_RUNTIME || "").trim();
// OMNIRUSH_BOX_RUNTIME naming a backend's own program picks that backend (the host kits do).
const named = runtimeBackend(legacyRuntime, platform);
if (named && wanted === "auto") { wanted = normalizeBackend(named); legacyRuntime = ""; }
const allowList = Array.isArray(allow) ? allow.map(normalizeBackend).filter((id): id is BackendId | "auto" | "native" => Boolean(id)) : null;
- const key = JSON.stringify([2, platform, wanted, allowList, legacyRuntime, env.DOCKER_HOST || "", env.PATH || env.Path || "", env.OMNIRUSH_BOX_BWRAP || ""]);
+ const key = JSON.stringify([2, platform, wanted, allowList, ...(preferShadows ? ["shadows"] : []), legacyRuntime, env.DOCKER_HOST || "", env.PATH || env.Path || "", env.OMNIRUSH_BOX_BWRAP || ""]);
if (boxHome && !fresh && !all) {
const cached = readCache(boxHome, now, key);
if (cached) return { ...cached, cached: true };
@@ -229,6 +229,9 @@ export async function detectBackend({ boxHome, env = process.env, platform = pro
let order: string[] = backendsFor(platform);
// OMNIRUSH_BOX_RUNTIME (docker, podman or a path) keeps meaning "this container CLI".
if (legacyRuntime) order = order.filter((id) => !["bwrap", "apple", "wslc", "wsl", "wsl-engine"].includes(id));
+ // Under the required sandbox on macOS/Windows: the backends whose boxes get their own build
+ // folders (driver.shadows: boxrun as root, the WSL distro) before the others.
+ if (preferShadows && wanted === "auto") order = [...order.filter((id) => driverFor({ backend: id }).shadows), ...order.filter((id) => !driverFor({ backend: id }).shadows)];
let why = `the first that works here, in order: ${order.join(" > ")}`;
if (wanted !== "auto") {
order = [wanted];
diff --git a/apps/server/src/box/backends/types.ts b/apps/server/src/box/backends/types.ts
index 6169d8cf..2a52e8ae 100644
--- a/apps/server/src/box/backends/types.ts
+++ b/apps/server/src/box/backends/types.ts
@@ -6,6 +6,7 @@ import type { ChildProcess, SpawnOptions } from "node:child_process";
import type { BoxEndpoint } from "../client.js";
import type { BoxInstallLog, BoxLog, BoxRuntime } from "../common.js";
import type { BoxImage } from "../images.js";
+import type { ShadowPlan } from "../required.js";
import type { RunCommand, RunOptions, RunResult } from "../run.js";
type Env = NodeJS.ProcessEnv;
@@ -30,6 +31,8 @@ export type OpenContext = {
pull: boolean;
shims: string | null;
pkglog: BoxInstallLog | null;
+ /** The box's own build folders (required.ts shadowPlan), for backends with `shadows` (boxrun as root); null: none. */
+ shadows?: ShadowPlan | null;
env: Env;
platform: NodeJS.Platform;
log: BoxLog;
@@ -53,6 +56,8 @@ export type Opened =
containerId: string;
imageId: string;
mounts: string[];
+ /** The folders inside that boxrun shadowed (a box found running keeps the set it started with). */
+ shadows?: string[];
timing?: { ms?: number; reused: boolean };
}
| { ok: false; error: string };
@@ -66,6 +71,10 @@ export type BoxDriver = {
kind: "container" | "bwrap" | "apple" | "wsl" | "wslc";
/** boxsh may fall back to `<runtime> exec` when boxd does not answer (container engines and wslc). */
execFallback: boolean;
+ /** boxrun runs as root here (the WSL distro): a box on a macOS/Windows host gets its own build folders (required.ts). */
+ shadows?: boolean;
+ /** false: the box has its own network; its servers reach this computer's 127.0.0.1 through boxd (ports.ts). */
+ forwardsPorts?: boolean;
imagePresent: (runtime: BoxRuntime, image: BoxImage, opts?: DriverOptions) => Promise<PresentImage | null>;
pull: (runtime: BoxRuntime, image: BoxImage, opts?: DriverOptions) => Promise<{ ok: true } | { ok: false; error: string }>;
/** The detached download; null: the download runs in this process (Desktop: the WSL distro). */
diff --git a/apps/server/src/box/backends/wsl.ts b/apps/server/src/box/backends/wsl.ts
index 9a804a60..8f60acc8 100644
--- a/apps/server/src/box/backends/wsl.ts
+++ b/apps/server/src/box/backends/wsl.ts
@@ -50,6 +50,8 @@ type WslRuntime = Pick<BoxRuntime, "bin" | "distro" | "arch" | "installed">;
export const DEFAULT_DISTRO = "OmniRushBox";
export const STORE = "/var/lib/omnirush/store";
export const BOXES = "/var/lib/omnirush/boxes";
+/** Where a box's own build folders (shadows) live in the distro: one folder per box, mounted at the same path inside it. */
+export const SHADOW_STORES = "/var/lib/omnirush/shadows";
export const ENABLE_HINT = "WSL 2 is not enabled on this Windows. One time, in an administrator terminal: `wsl --install --no-distribution`, then restart Windows";
export type WslAsset = { url: string | null; sha256: string | null; bytes?: number | null };
@@ -317,10 +319,10 @@ export function startKeeper(runtime: WslRuntime, args: string[], { env = process
});
}
-type WslMeta = BoxMeta & { mounts?: string[] };
+type WslMeta = BoxMeta & { mounts?: string[]; shadows?: string[] };
async function open(ctx: OpenContext): Promise<Opened> {
- const { key, root, croot, runtime, run, home, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling, spawnImpl } = ctx;
+ const { key, root, croot, runtime, run, home, runFolder, image, pull: mayPull, shims, pkglog, shadows = null, env, log, onPulling, spawnImpl } = ctx;
const file = metaFile(home, key);
let meta = readJson<WslMeta>(file);
if (meta && meta.root !== root) return { ok: false, error: `box ${key} belongs to another folder` };
@@ -331,7 +333,7 @@ async function open(ctx: OpenContext): Promise<Opened> {
const asks = ctx.ping ?? ping;
const answers = (await asks(live.endpoint, { timeoutMs: 1_500 })) || (live.alternates.length > 0 && (await asks(live.alternates[0]!, { timeoutMs: 1_500 })));
if (answers) {
- return { ok: true, created: null, endpoint: live.endpoint, alternates: live.alternates, uid: 0, gid: 0, containerId: `wsl_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: meta.mounts ?? [] };
+ return { ok: true, created: null, endpoint: live.endpoint, alternates: live.alternates, uid: 0, gid: 0, containerId: `wsl_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: meta.mounts ?? [], shadows: meta.shadows ?? [] };
}
log("info", "box keeper running but boxd not answering; starting it again", { key });
try { live.child.kill(); } catch { /* gone */ }
@@ -363,7 +365,7 @@ async function open(ctx: OpenContext): Promise<Opened> {
const args = upArgs({
box: boxPath(key), store: STORE, image: meta.image, boxd: "/opt/omnirush/boxd", portFile: `${wslPath(runFolder)}/boxd.port`,
root, croot, runFolder, shims, pkglog, token: meta.token, idleMinutes: idle, listen: listenAny ? "0.0.0.0:0" : "127.0.0.1:0",
- platform: "win32", mapPath: wslPath,
+ platform: "win32", mapPath: wslPath, shadows, shadowStore: shadows ? `${SHADOW_STORES}/${key}` : null,
});
const kept = await startKeeper(runtime, args, { env, ...(spawnImpl ? { spawnImpl } : {}) });
if (!kept.ok) return { ok: false, error: `could not start the sandbox: ${kept.error}` };
@@ -376,9 +378,12 @@ async function open(ctx: OpenContext): Promise<Opened> {
if (addr) alternates.push({ host: addr, port, token: meta.token });
}
const mounts = [croot, "/run/omnirush", ...(shims ? ["/opt/omnirush/pkglog-src"] : []), ...(pkglog ? [containerRoot(pkglog.root, "win32")] : [])];
- if (!kept.out.reused) writeJson(file, { ...meta, mounts, started_at: new Date().toISOString() });
+ // The folders boxrun shadowed (a box it found running keeps the set it started with).
+ const reported = Array.isArray(kept.out.shadows) ? kept.out.shadows.filter((item): item is string => typeof item === "string") : null;
+ const shadowed = reported ?? (kept.out.reused ? (meta.shadows ?? []) : []);
+ if (!kept.out.reused) writeJson(file, { ...meta, mounts, shadows: shadowed, started_at: new Date().toISOString() });
keepers.set(key, { child: kept.child, endpoint, alternates });
- return { ok: true, created, endpoint, alternates, uid: 0, gid: 0, containerId: `wsl_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: kept.out.reused ? (meta.mounts ?? mounts) : mounts };
+ return { ok: true, created, endpoint, alternates, uid: 0, gid: 0, containerId: `wsl_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: kept.out.reused ? (meta.mounts ?? mounts) : mounts, shadows: shadowed };
}
function keeperAlive(key: string): boolean {
@@ -389,6 +394,8 @@ function keeperAlive(key: string): boolean {
export const wslDriver: BoxDriver = {
kind: "wsl",
execFallback: false,
+ /** boxrun runs as root in the distro: a box here gets its own build folders on a Windows host (required.ts). */
+ shadows: true,
imagePresent,
pull,
/** Desktop: the distro import, the helpers and the image download run in this process (launch.ts pullInBackground). */
diff --git a/apps/server/src/box/backends/wslc.ts b/apps/server/src/box/backends/wslc.ts
index 9b36cb7b..64286cfd 100644
--- a/apps/server/src/box/backends/wslc.ts
+++ b/apps/server/src/box/backends/wslc.ts
@@ -225,6 +225,8 @@ async function open(ctx: OpenContext): Promise<Opened> {
export const wslcDriver: BoxDriver = {
kind: "wslc",
+ /** Its own container network: the box's servers reach this computer's 127.0.0.1 through boxd (ports.ts). */
+ forwardsPorts: false,
/** boxsh's fallback `<runtime> exec -i -w -u -e` matches wslc exec's flags. */
execFallback: true,
imagePresent,
diff --git a/apps/server/src/box/box-ports.test.ts b/apps/server/src/box/box-ports.test.ts
new file mode 100644
index 00000000..fce32bb7
--- /dev/null
+++ b/apps/server/src/box/box-ports.test.ts
@@ -0,0 +1,287 @@
+// Ported from the CLI (omnirush-cli test/box-ports.test.js): a server the
+// agent starts in a box with its own network (Docker, Podman) answers at the
+// same port on this computer's 127.0.0.1: the project's box run lists the
+// box's listeners through boxd and carries each connection through a boxd
+// stream (ports.ts). No container runtime here: a stand-in boxd speaks the
+// wire format (box/go/proto) and dials local servers.
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync } from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+import { connectPort, listPorts, type BoxEndpoint, type BoxListener } from "./client.js";
+import { bwrapDriver } from "./backends/bwrap.js";
+import { containerDriver } from "./backends/container.js";
+import { wslDriver } from "./backends/wsl.js";
+import type { Box } from "./box.js";
+import { boxRun, type ReadyPlan } from "./launch.js";
+import { forwardable, portForwards, portLine, type PortForwardOptions, type PortForwards } from "./ports.js";
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+async function until(fn: () => boolean, ms = 3_000): Promise<boolean> {
+ const end = Date.now() + ms;
+ while (Date.now() < end) { if (fn()) return true; await sleep(20); }
+ return false;
+}
+
+function frame(kind: string, payload: Buffer = Buffer.alloc(0)): Buffer {
+ const head = Buffer.alloc(5);
+ head[0] = kind.charCodeAt(0);
+ head.writeUInt32BE(payload.length, 1);
+ return Buffer.concat([head, payload]);
+}
+
+async function freePort(): Promise<number> {
+ const server = net.createServer();
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ const { port } = server.address() as net.AddressInfo;
+ await new Promise<void>((resolve) => server.close(() => resolve()));
+ return port;
+}
+
+/** A server that upper-cases what it reads and answers with it once the client half-closes. */
+async function upperServer(): Promise<net.Server> {
+ const server = net.createServer({ allowHalfOpen: true }, (socket) => {
+ const parts: Buffer[] = [];
+ socket.on("data", (chunk: Buffer) => parts.push(chunk));
+ socket.on("end", () => socket.end(Buffer.concat(parts).toString("utf8").toUpperCase()));
+ });
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ return server;
+}
+const portOf = (server: net.Server) => (server.address() as net.AddressInfo).port;
+
+/** A stand-in boxd: op "ports" answers `ports()` ("unknown op" when `old`), op "connect" dials `target(port)` here. */
+async function fakeBoxd({ token = "tok", ports = () => [] as BoxListener[], target = (p: number) => p, old = false }: { token?: string; ports?: () => BoxListener[]; target?: (port: number) => number; old?: boolean } = {}) {
+ const calls: Array<{ op: string; port?: number; token?: string }> = [];
+ const server = net.createServer({ allowHalfOpen: true }, (socket) => {
+ let buffered = Buffer.alloc(0);
+ const onData = (chunk: Buffer) => {
+ buffered = Buffer.concat([buffered, chunk]);
+ const nl = buffered.indexOf(0x0a);
+ if (nl < 0) return;
+ socket.removeListener("data", onData);
+ const req = JSON.parse(buffered.subarray(0, nl).toString("utf8"));
+ const rest = buffered.subarray(nl + 1);
+ calls.push(req);
+ const fail = (text: string) => socket.end(Buffer.concat([frame("E", Buffer.from(text)), frame("x", Buffer.from(JSON.stringify({ code: 125 })))]));
+ if (req.token !== token) return fail("unauthorized");
+ if (old || (req.op !== "ports" && req.op !== "connect")) return fail(`unknown op "${req.op}"`);
+ if (req.op === "ports") {
+ socket.end(Buffer.concat([frame("d", Buffer.from(JSON.stringify(ports()))), frame("x", Buffer.from(JSON.stringify({ code: 0 })))]));
+ return;
+ }
+ const inner = net.connect({ host: "127.0.0.1", port: target(req.port), allowHalfOpen: true });
+ inner.once("error", () => fail(`nothing answers on port ${req.port} in the sandbox`));
+ inner.once("connect", () => {
+ socket.write(frame("d", Buffer.from('{"ok":true}')));
+ if (rest.length) inner.write(rest);
+ socket.pipe(inner);
+ inner.pipe(socket);
+ });
+ };
+ socket.on("data", onData);
+ socket.on("error", () => {});
+ });
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ const endpoint: BoxEndpoint = { host: "127.0.0.1", port: portOf(server), token };
+ return { server, calls, endpoint };
+}
+
+/** Send `text` to 127.0.0.1:<port>, half-close, read the answer. */
+function roundTrip(port: number, text: string): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const socket = net.connect({ host: "127.0.0.1", port, allowHalfOpen: true });
+ const parts: Buffer[] = [];
+ socket.on("data", (chunk: Buffer) => parts.push(chunk));
+ socket.on("end", () => { socket.end(); resolve(Buffer.concat(parts).toString("utf8")); });
+ socket.on("error", reject);
+ socket.once("connect", () => socket.end(text));
+ });
+}
+
+describe("box ports on this computer", () => {
+ test("the backends that need forwards say so; bwrap and the WSL distro share or forward localhost", () => {
+ expect(containerDriver.forwardsPorts).toBe(false);
+ expect(bwrapDriver.forwardsPorts).not.toBe(false);
+ expect(wslDriver.forwardsPorts).not.toBe(false);
+ });
+
+ test("which box ports are forwarded, and the one line", () => {
+ expect(forwardable(8765)).toBe(true);
+ expect(forwardable(1023)).toBe(false);
+ expect(forwardable(65536)).toBe(false);
+ expect(forwardable(7777)).toBe(false);
+ expect(forwardable(3000, new Set())).toBe(true);
+ expect(portLine(8765)).toBe("Port 8765 in the sandbox is open on this computer at http://127.0.0.1:8765");
+ });
+
+ test("client: ports lists the box's listeners; connect streams both ways; an old boxd reads as null", async () => {
+ const inner = await upperServer();
+ const boxd = await fakeBoxd({ ports: () => [{ port: 3000, addr: "0.0.0.0" }], target: () => portOf(inner) });
+ try {
+ expect(await listPorts(boxd.endpoint)).toEqual([{ port: 3000, addr: "0.0.0.0" }]);
+ const { socket, head } = await connectPort(boxd.endpoint, 3000);
+ expect(head.length).toBe(0);
+ const parts: Buffer[] = [];
+ socket.on("data", (chunk: Buffer) => parts.push(chunk));
+ const ended = new Promise((resolve) => socket.on("end", resolve));
+ socket.resume();
+ socket.end("hello box");
+ await ended;
+ expect(Buffer.concat(parts).toString("utf8")).toBe("HELLO BOX");
+ await expect(connectPort({ ...boxd.endpoint, token: "nope" }, 3000)).rejects.toThrow(/unauthorized/);
+ } finally {
+ boxd.server.close();
+ inner.close();
+ }
+ const old = await fakeBoxd({ old: true });
+ try {
+ expect(await listPorts(old.endpoint)).toBeNull();
+ } finally {
+ old.server.close();
+ }
+ });
+
+ test("a new box listener opens on 127.0.0.1 here, carries connections, closes when it goes", async () => {
+ const port = await freePort();
+ const inner = await upperServer();
+ let listening: BoxListener[] = [{ port, addr: "0.0.0.0" }, { port: 80, addr: "0.0.0.0" }, { port: 7777, addr: "0.0.0.0" }];
+ const boxd = await fakeBoxd({ ports: () => listening, target: () => portOf(inner) });
+ const opened: Array<[number, string]> = [];
+ const closed: Array<[number, string]> = [];
+ const forwards = portForwards({ endpoint: () => boxd.endpoint, timers: false, onOpen: (p, line) => opened.push([p, line]), onClose: (p, why) => closed.push([p, why]) });
+ try {
+ await forwards.tick();
+ expect(forwards.ports()).toEqual([port]);
+ expect(opened).toEqual([[port, portLine(port)]]);
+ expect(await roundTrip(port, "page please")).toBe("PAGE PLEASE");
+ expect(await Promise.all([roundTrip(port, "one"), roundTrip(port, "two")])).toEqual(["ONE", "TWO"]);
+ expect(boxd.calls.filter((c) => c.op === "connect").length).toBe(3);
+ listening = [];
+ await forwards.tick();
+ expect(forwards.ports()).toEqual([]);
+ expect(closed).toEqual([[port, "gone"]]);
+ await expect(roundTrip(port, "x")).rejects.toThrow();
+ } finally {
+ forwards.close();
+ boxd.server.close();
+ inner.close();
+ }
+ });
+
+ test("a port this computer already uses stays its own (said once); nothing beyond 127.0.0.1", async () => {
+ const mine = await upperServer();
+ const port = portOf(mine);
+ const inner = await upperServer();
+ const free = await freePort();
+ const boxd = await fakeBoxd({ ports: () => [{ port, addr: "0.0.0.0" }, { port: free, addr: "127.0.0.1" }], target: () => portOf(inner) });
+ const logged: Array<[string, string]> = [];
+ const forwards = portForwards({ endpoint: () => boxd.endpoint, timers: false, log: (level, message) => logged.push([level, message]) });
+ try {
+ await forwards.tick();
+ await forwards.tick();
+ expect(forwards.ports()).toEqual([free]);
+ expect(logged.filter((l) => l[1] === "box port not forwarded: in use on this computer").length).toBe(1);
+ expect(await roundTrip(port, "host")).toBe("HOST");
+ const other = Object.values(os.networkInterfaces()).flat().find((i) => i && i.family === "IPv4" && !i.internal);
+ if (other) {
+ await expect(new Promise<void>((resolve, reject) => {
+ const s = net.connect({ host: other.address, port: free });
+ s.once("connect", () => { s.destroy(); resolve(); });
+ s.once("error", reject);
+ })).rejects.toThrow();
+ }
+ } finally {
+ forwards.close();
+ boxd.server.close();
+ inner.close();
+ mine.close();
+ }
+ });
+
+ test("none while the box is not usable; an old boxd stops the poll; close() ends every forward", async () => {
+ const port = await freePort();
+ const inner = await upperServer();
+ const boxd = await fakeBoxd({ ports: () => [{ port, addr: "0.0.0.0" }], target: () => portOf(inner) });
+ let ep: BoxEndpoint | null = null;
+ const forwards = portForwards({ endpoint: () => ep, timers: false });
+ try {
+ await forwards.tick();
+ expect(boxd.calls.length).toBe(0);
+ ep = boxd.endpoint;
+ await forwards.tick();
+ expect(forwards.ports()).toEqual([port]);
+ ep = { ...boxd.endpoint, port: await freePort() };
+ await forwards.tick();
+ expect(forwards.ports()).toEqual([port]);
+ forwards.close();
+ expect(forwards.ports()).toEqual([]);
+ await expect(roundTrip(port, "x")).rejects.toThrow();
+ } finally {
+ forwards.close();
+ boxd.server.close();
+ inner.close();
+ }
+ const old = await fakeBoxd({ old: true });
+ const logged: string[] = [];
+ const legacy = portForwards({ endpoint: () => old.endpoint, timers: false, log: (_level, message) => logged.push(message) });
+ try {
+ await legacy.tick();
+ await legacy.tick();
+ expect(old.calls.length).toBe(1);
+ expect(logged[0]).toMatch(/older version/);
+ } finally {
+ legacy.close();
+ old.server.close();
+ }
+ });
+
+ test("the poll runs on its own every pollMs", async () => {
+ const port = await freePort();
+ const inner = await upperServer();
+ let listening: BoxListener[] = [];
+ const boxd = await fakeBoxd({ ports: () => listening, target: () => portOf(inner) });
+ const forwards = portForwards({ endpoint: () => boxd.endpoint, pollMs: 30 });
+ try {
+ listening = [{ port, addr: "::" }];
+ expect(await until(() => forwards.ports().includes(port))).toBe(true);
+ expect(await roundTrip(port, "late server")).toBe("LATE SERVER");
+ } finally {
+ forwards.close();
+ boxd.server.close();
+ inner.close();
+ }
+ });
+
+ test("boxRun: forwards only for a backend with its own network, unless OMNIRUSH_BOX_PORTS=off; closed with the run", async () => {
+ const box = { ready: true, error: null, endpoint: { host: "127.0.0.1", port: 1, token: "t" }, setTurn() {} };
+ const plan = (backend: string): ReadyPlan => {
+ const home = mkdtempSync(path.join(os.tmpdir(), "box-ports-"));
+ mkdirSync(path.join(home, "boxes"), { recursive: true });
+ return { box: { key: "k1", home, root: "/p", runtime: { name: backend, backend, bin: "/x/rt" } }, notice: null, shell: "/x/boxsh", phase: "ready", start: async () => box as unknown as Box } as unknown as ReadyPlan;
+ };
+ const made: Array<{ opts: PortForwardOptions; closed: boolean }> = [];
+ const stub = (opts: PortForwardOptions): PortForwards => {
+ const entry = { opts, closed: false };
+ made.push(entry);
+ return { tick: async () => {}, ports: () => [4000], close() { entry.closed = true; } };
+ };
+ const said: unknown[] = [];
+ const docker = boxRun(plan("docker"), { forwards: stub, env: {}, ping: (async () => ({})) as never, onPort: (e) => said.push(e) });
+ expect(made.length).toBe(1);
+ await docker.ready();
+ expect(made[0]!.opts.endpoint()).toEqual(box.endpoint);
+ expect(docker.forwardedPorts?.()).toEqual([4000]);
+ made[0]!.opts.onOpen!(3000, portLine(3000));
+ expect(said).toEqual([{ port: 3000, line: portLine(3000), open: true }]);
+ docker.close();
+ expect(made[0]!.closed).toBe(true);
+ expect(made[0]!.opts.endpoint()).toBeNull();
+ boxRun(plan("bwrap"), { forwards: stub, env: {} }).close();
+ boxRun(plan("wsl"), { forwards: stub, env: {} }).close();
+ boxRun(plan("podman"), { forwards: stub, env: { OMNIRUSH_BOX_PORTS: "off" } }).close();
+ expect(made.length).toBe(1);
+ });
+});
diff --git a/apps/server/src/box/box-shadows.test.ts b/apps/server/src/box/box-shadows.test.ts
new file mode 100644
index 00000000..1dbbe8e7
--- /dev/null
+++ b/apps/server/src/box/box-shadows.test.ts
@@ -0,0 +1,152 @@
+// Ported from the CLI (omnirush-cli test/box-required.test.js, the shadow
+// tests): on a macOS or Windows host a box on a backend whose boxrun runs as
+// root (the WSL distro) gets its own Linux copy of each build folder. The
+// plan (required.json shadows), boxrun's arguments, the env redirections, the
+// plan boxd reads for folders made mid-chat, the agent's line, record.json,
+// and that shadows are never in a snapshot. No runtime is touched.
+import { afterEach, describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { detectBackend, driverFor } from "./backends/index.js";
+import { upArgs } from "./backends/bwrap.js";
+import { Box, dependencyFolders, recordFile } from "./box.js";
+import { BOX_NOTE } from "./plugin-lib.js";
+import { REQUIRED_RULES, shadowId, shadowPlan, shadowRecord, shadowsApply, shadowsNotice } from "./required.js";
+import type { RunCommand } from "./run.js";
+
+const dirs: string[] = [];
+const tmp = (name: string) => {
+ const dir = mkdtempSync(path.join(os.tmpdir(), `box-shadow-${name}-`));
+ dirs.push(dir);
+ return dir;
+};
+afterEach(() => {
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+const down: RunCommand = async () => ({ code: 1, stdout: "", stderr: "not here" });
+const store = REQUIRED_RULES.shadows.store;
+
+describe("build-artefact shadows: the plan", () => {
+ test("node_modules even if absent, existing build folders, env redirections; nothing on Linux", () => {
+ const root = tmp("plan");
+ writeFileSync(path.join(root, "package.json"), "{}");
+ writeFileSync(path.join(root, "pyproject.toml"), "[project]\nname='x'\n");
+ writeFileSync(path.join(root, "Cargo.toml"), "[package]\nname='x'\n");
+ mkdirSync(path.join(root, ".venv"));
+ writeFileSync(path.join(root, ".venv", "pyvenv.cfg"), "home = /opt/homebrew/bin\n");
+ mkdirSync(path.join(root, ".next"));
+ mkdirSync(path.join(root, "packages", "web", "node_modules"), { recursive: true });
+ writeFileSync(path.join(root, "packages", "web", "package.json"), "{}");
+ mkdirSync(path.join(root, "packages", "lib"), { recursive: true });
+ writeFileSync(path.join(root, "packages", "lib", "package.json"), "{}");
+ mkdirSync(path.join(root, "dist"));
+ writeFileSync(path.join(root, "dist", "readme.txt"), "source, not a build");
+ const plan = shadowPlan(root, { platform: "darwin", croot: root });
+ const byPath = Object.fromEntries(plan.binds.map((b) => [b.path, b]));
+ expect(Object.keys(byPath).sort()).toEqual([".next", ".venv", "node_modules", "packages/lib/node_modules", "packages/web/node_modules"]);
+ expect(byPath.node_modules!.existed).toBe(false);
+ expect(byPath["packages/web/node_modules"]!.existed).toBe(true);
+ expect(byPath.node_modules!.target).toBe(`${root}/node_modules`);
+ expect(byPath.node_modules!.id).toBe(createHash("sha256").update("node_modules").digest("hex").slice(0, 12));
+ expect(plan.env.UV_PROJECT_ENVIRONMENT).toBe(`${store}/${shadowId(".")}/venv`);
+ expect(plan.env.CARGO_TARGET_DIR).toBe(`${store}/${shadowId(".")}/cargo-target`);
+ expect(plan.env.POETRY_VIRTUALENVS_PATH).toBeUndefined();
+ expect(shadowRecord(plan)!.binds.find((b) => b.path === "node_modules")).toEqual({ path: "node_modules", existed: false });
+ // The desktop's words (texts.desktop.shadows) on the card; the CLI's (texts.cli.shadows) for the agent.
+ expect(shadowsNotice(plan, "darwin")).toMatch(/^In the sandbox, node_modules, \.venv, \.next(, target)? are the sandbox's own Linux copies; your Mac copies are left as they are\.$/);
+ expect(shadowsNotice(plan, "darwin", "cli")).toMatch(/your Mac copies are left as they are\. Install dependencies inside as needed\.$/);
+ // Windows: the same rules, with the folder as the box sees it (/c/...).
+ const win = shadowPlan(root, { platform: "win32", croot: "/c/Users/u/proj" });
+ expect(win.binds.find((b) => b.path === "node_modules")!.target).toBe("/c/Users/u/proj/node_modules");
+ expect(shadowsNotice(win, "win32")).toMatch(/your Windows copies are left as they are\.$/);
+ expect(shadowPlan(root, { platform: "linux" }).binds.length).toBe(0);
+ expect(shadowsApply("darwin", { OMNIRUSH_BOX_SHADOWS: "off" })).toBe(false);
+ expect(shadowsApply("linux", {})).toBe(false);
+ expect(shadowsNotice(shadowPlan(root, { platform: "linux" }), "linux")).toBeNull();
+ });
+
+ test("store ids: sha256 of the project-relative POSIX path, 12 hex digits, \".\" for the root (boxd computes the same)", () => {
+ expect(shadowId(".")).toBe(createHash("sha256").update(".").digest("hex").slice(0, 12));
+ expect(shadowId("")).toBe(shadowId("."));
+ expect(shadowId("packages\\web\\node_modules")).toBe(shadowId("packages/web/node_modules"));
+ expect(shadowId("./a//b/")).toBe(shadowId("a/b"));
+ });
+
+ test("a Mac program in dist/ shadows dist; the scan stays within its limits", () => {
+ const root = tmp("dist");
+ mkdirSync(path.join(root, "dist"));
+ const macho = Buffer.alloc(64);
+ macho.writeUInt32BE(0xcffaedfe, 0);
+ writeFileSync(path.join(root, "dist", "app"), macho, { mode: 0o755 });
+ expect(shadowPlan(root, { platform: "darwin", croot: root }).binds.map((b) => b.path)).toEqual(["dist"]);
+ const deep = tmp("deep");
+ let dir = deep;
+ for (let i = 0; i < 8; i += 1) { dir = path.join(dir, `d${i}`); mkdirSync(dir); writeFileSync(path.join(dir, "package.json"), "{}"); }
+ expect(shadowPlan(deep, { platform: "darwin", croot: deep }).binds.length).toBe(REQUIRED_RULES.shadows.limits.depth);
+ });
+});
+
+describe("build-artefact shadows: the backends", () => {
+ test("upArgs: shadows go to boxrun as a store and ID=DST pairs (only when asked)", () => {
+ const base = { box: "/b", store: "/s", image: "i", boxd: "/d", portFile: "/p", root: "/r", croot: "/r", runFolder: "/run", token: "t" };
+ expect(upArgs(base).includes("--shadow-store")).toBe(false);
+ const args = upArgs({ ...base, shadows: { binds: [{ path: "node_modules", existed: false, id: "0123456789ab", target: "/r/node_modules" }] }, shadowStore: "/var/lib/omnirush/shadows/k" });
+ expect(args.slice(args.indexOf("--shadow-store"))).toEqual(["--shadow-store", "/var/lib/omnirush/shadows/k", "--shadow", "0123456789ab=/r/node_modules"]);
+ });
+
+ test("only the WSL distro applies shadows; under required on Windows it comes first", async () => {
+ expect(driverFor({ backend: "wsl" }).shadows).toBe(true);
+ for (const id of ["bwrap", "docker", "podman", "wslc", "apple"]) expect(Boolean(driverFor({ backend: id }).shadows)).toBe(false);
+ const probeAll = async (preferShadows: boolean) => detectBackend({ platform: "win32", env: { SystemRoot: "/nonexistent" }, exists: () => false, run: down, fresh: true, preferShadows });
+ const tried = (result: unknown) => ((result as { tried?: Array<{ backend: string }> }).tried ?? []).map((t) => t.backend);
+ const plain = tried(await probeAll(false));
+ const shadowed = tried(await probeAll(true));
+ expect(plain.indexOf("wslc")).toBeLessThan(plain.indexOf("wsl"));
+ expect(shadowed.indexOf("wsl")).toBeLessThan(shadowed.indexOf("wslc"));
+ });
+});
+
+describe("build-artefact shadows: a box", () => {
+ test("redirections in the env file, the plan for boxd, the agent's line, record.json; never in a snapshot", () => {
+ const root = tmp("root");
+ writeFileSync(path.join(root, "package.json"), "{}");
+ writeFileSync(path.join(root, "pyproject.toml"), "");
+ mkdirSync(path.join(root, "node_modules", "left"), { recursive: true });
+ mkdirSync(path.join(root, "packages", "a", "node_modules"), { recursive: true });
+ const home = tmp("home");
+ const runFolder = path.join(home, "run", "k");
+ mkdirSync(runFolder, { recursive: true });
+ // What the wrappers and the git identity wrote before: kept.
+ writeFileSync(path.join(runFolder, "env"), "BOXD_PATH_PREFIX=/x\nGIT_CONFIG_SYSTEM=/run/omnirush/gitconfig\n");
+ const box = new Box({ key: "k", name: "omnirush-box-k", root, croot: root, runtime: { name: "wsl", backend: "wsl", bin: "wsl.exe" }, home, runFolder, run: down, log: () => {}, platform: "win32", env: {} });
+ const plan = shadowPlan(root, { platform: "win32", croot: root });
+ // boxrun bound only the root's node_modules (a box started before keeps its own set).
+ box.useShadows(plan, [`${root}/node_modules`]);
+ box.useShadows(plan, [`${root}/node_modules`]);
+ const envFile = readFileSync(path.join(runFolder, "env"), "utf8");
+ expect(envFile).toBe(`BOXD_PATH_PREFIX=/x\nGIT_CONFIG_SYSTEM=/run/omnirush/gitconfig\nUV_PROJECT_ENVIRONMENT=${store}/${shadowId(".")}/venv\n`);
+ const forBoxd = JSON.parse(readFileSync(path.join(runFolder, "shadows.json"), "utf8"));
+ expect(forBoxd.active).toEqual([`${root}/node_modules`]);
+ expect(forBoxd.lazy).toEqual([{ dir: "node_modules", when_any: ["package.json"] }]);
+ expect(forBoxd.store).toBe(store);
+ const rec = JSON.parse(readFileSync(recordFile(home, "k"), "utf8"));
+ expect(rec.shadows_note).toMatch(/^In the sandbox, node_modules(, \.venv)? are the sandbox's own Linux copies; your Windows copies are left as they are\. Install dependencies inside as needed\.$/);
+ expect(BOX_NOTE(root, 0, root, rec.shadows_note)).toMatch(/\nIn the sandbox, node_modules/);
+ expect(BOX_NOTE(root, 0, root)).not.toMatch(/own Linux copies/);
+ // boxd bound packages/a/node_modules mid-chat (shadows-lazy.json): in the record, out of snapshots.
+ writeFileSync(path.join(runFolder, "shadows-lazy.json"), JSON.stringify({ binds: [{ path: "packages/a/node_modules" }] }));
+ const described = box.describe() as ReturnType<Box["describe"]> & { shadows?: unknown };
+ expect(described.shadows).toEqual({ binds: [{ path: "node_modules", existed: true }, { path: "packages/a/node_modules", existed: false }], env: { UV_PROJECT_ENVIRONMENT: `${store}/${shadowId(".")}/venv` } });
+ const skip = new Set(box.currentShadows()!.binds.map((b) => b.path));
+ expect(dependencyFolders(root, { skip })).toEqual([]);
+ expect(dependencyFolders(root).map((p) => path.relative(root, p)).sort()).toEqual(["node_modules", path.join("packages", "a", "node_modules")]);
+ // No shadows: no shadows key and no note (as before).
+ const plain = new Box({ key: "p", name: "omnirush-box-p", root, croot: root, runtime: { name: "bwrap", backend: "bwrap", bin: "boxrun" }, home, runFolder, run: down, log: () => {}, platform: "linux", env: {} });
+ plain.writeRecord();
+ expect("shadows" in plain.describe()).toBe(false);
+ expect(JSON.parse(readFileSync(recordFile(home, "p"), "utf8")).shadows_note).toBeUndefined();
+ });
+});
diff --git a/apps/server/src/box/box.ts b/apps/server/src/box/box.ts
index 150982f2..22c9398d 100644
--- a/apps/server/src/box/box.ts
+++ b/apps/server/src/box/box.ts
@@ -39,6 +39,7 @@ import type { ListedBox, SpawnLike } from "./backends/types.js";
import { detectStack, imageFor, type BoxImage, type ImagePins } from "./images.js";
import { runCommand, type RunCommand, type RunOptions } from "./run.js";
import { keptImages } from "./retention.mjs";
+import { REQUIRED_RULES, shadowRecord, shadowsNotice, type ShadowBind, type ShadowPlan } from "./required.js";
type Env = NodeJS.ProcessEnv;
@@ -177,8 +178,12 @@ function topmost(paths: string[]): string[] {
return out;
}
-/** Dependency folders of the project (top level, and one or two levels down). */
-export function dependencyFolders(root: string, { maxDepth = 2 }: { maxDepth?: number } = {}): string[] {
+/**
+ * Dependency folders of the project (top level, and one or two levels down).
+ * `skip`: project-relative POSIX paths left out (the box's own shadow copies,
+ * required.ts: never in a snapshot; a rebuild makes them from the manifests).
+ */
+export function dependencyFolders(root: string, { maxDepth = 2, skip = null }: { maxDepth?: number; skip?: Set<string> | null } = {}): string[] {
const out: string[] = [];
const visit = (dir: string, depth: number) => {
let entries;
@@ -186,6 +191,7 @@ export function dependencyFolders(root: string, { maxDepth = 2 }: { maxDepth?: n
for (const entry of entries) {
if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
const full = path.join(dir, entry.name);
+ if (skip?.has(path.relative(root, full).split(path.sep).join("/"))) continue;
if (DEPENDENCY_DIRS.has(entry.name)) { out.push(full); continue; }
if (depth < maxDepth && !entry.name.startsWith(".") && entry.name !== "dist" && entry.name !== "build" && entry.name !== "target") visit(full, depth + 1);
}
@@ -205,7 +211,7 @@ type OnState = (state: BoxState, error: string | null) => void;
* (the record boxsh reads says the same). Throws only for programming
* errors; a box that cannot start is a Box with state "failed" and `error`.
*/
-export async function openBox({ root, runtime, env = process.env, platform = process.platform, home = boxHome(env), run = runCommand, log = () => {}, shims = null, pkglog = null, pull = true, image: asked = null, onState = () => {}, onLine, spawnImpl, readyMs = 15_000, revive = false }: { root: string; runtime: BoxRuntime; env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand; log?: BoxLog; shims?: string | null; pkglog?: BoxInstallLog | null; pull?: boolean; image?: BoxImage | null; onState?: OnState; onLine?: RunOptions["onLine"]; spawnImpl?: SpawnLike; readyMs?: number; revive?: boolean }): Promise<Box> {
+export async function openBox({ root, runtime, env = process.env, platform = process.platform, home = boxHome(env), run = runCommand, log = () => {}, shims = null, pkglog = null, pull = true, image: asked = null, onState = () => {}, onLine, spawnImpl, readyMs = 15_000, revive = false, shadows = null }: { root: string; runtime: BoxRuntime; env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand; log?: BoxLog; shims?: string | null; pkglog?: BoxInstallLog | null; pull?: boolean; image?: BoxImage | null; onState?: OnState; onLine?: RunOptions["onLine"]; spawnImpl?: SpawnLike; readyMs?: number; revive?: boolean; shadows?: ShadowPlan | null }): Promise<Box> {
const projectRoot = path.resolve(root);
const key = boxKey(projectRoot, { platform });
const name = containerName(key, env);
@@ -216,13 +222,15 @@ export async function openBox({ root, runtime, env = process.env, platform = pro
// The app restarts boxd when a shell call finds it stopped (boxsh asks through boxes/<key>.revive).
box.revive = revive;
const driver = driverFor(runtime);
+ // Shadows only where the backend applies them (driver.shadows: boxrun as root, macOS/Windows hosts).
+ const wanted = driver.shadows && shadows && (shadows.binds?.length || Object.keys(shadows.env ?? {}).length) ? shadows : null;
const lock = await acquireLock(home, key);
try {
box.setState("starting", null, onState);
const chosen = asked ?? imageFor(detectStack(projectRoot), { env });
let opened: Awaited<ReturnType<typeof driver.open>>;
for (let attempt = 0; ; attempt += 1) {
- opened = await driver.open({ key, name, root: projectRoot, croot, runtime, run, home, runFolder, image: chosen, pull, shims, pkglog, env, platform, log, ...(spawnImpl ? { spawnImpl } : {}), ...(onLine ? { onLine } : {}), onPulling: () => box.setState("pulling", null, onState) });
+ opened = await driver.open({ key, name, root: projectRoot, croot, runtime, run, home, runFolder, image: chosen, pull, shims, pkglog, shadows: wanted, env, platform, log, ...(spawnImpl ? { spawnImpl } : {}), ...(onLine ? { onLine } : {}), onPulling: () => box.setState("pulling", null, onState) });
if (!opened.ok) return box.fail(opened.error, onState);
if (opened.created || attempt > 0 || !(await mountReplaced(opened, { croot, readyMs }))) break;
// The folder was deleted and made again at its path (a new clone) while its box ran:
@@ -251,6 +259,8 @@ export async function openBox({ root, runtime, env = process.env, platform = pro
else log("info", "box made before the install log: its wrappers are not in this box (Reset sandbox adds them)", { key });
}
try { box.useGitIdentity(); } catch (error) { log("warn", "box git identity not set", { error: error instanceof Error ? error.message : String(error) }); }
+ // The shadows boxrun really bound (a box another start made before keeps its own set until it stops).
+ if (wanted) box.useShadows(wanted, opened.shadows ?? null);
box.setState("ready", null, onState);
return box;
} catch (error) {
@@ -374,6 +384,8 @@ export class Box {
gid: number | undefined;
containerId: string | undefined;
imageId: string | undefined;
+ /** The box's own build folders in use (macOS/Windows hosts; required.ts), null with none. */
+ shadows: ShadowPlan | null = null;
private queue: Promise<unknown> = Promise.resolve();
constructor({ key, name, root, croot, runtime, home, runFolder, run, log, platform, env }: BoxInit) {
@@ -409,6 +421,8 @@ export class Box {
host: this.endpoint?.host ?? "127.0.0.1", port: this.endpoint?.port ?? 0, token: this.endpoint?.token ?? "",
state: this.state, error: this.error ?? "", uid: this.uid ?? 0, gid: this.gid ?? 0, home: HOME_IN_BOX, shell: "/bin/bash",
path_prefix: this.pathPrefix, env_file: `${RUN_DIR}/env`, updated: Date.now(), pid: process.pid, revive: this.revive,
+ // The agent's box notice adds this line (plugin-lib.ts BOX_NOTE): the CLI's words, so both apps tell the model the same.
+ ...(this.shadows ? { shadows_note: shadowsNotice(this.shadows, this.platform, "cli") ?? undefined } : {}),
};
writeJson(recordFile(this.home, this.key), record);
}
@@ -488,6 +502,40 @@ export class Box {
writeFileSync(file, `${lines.join("\n")}\n`, { mode: 0o644 });
}
+ /**
+ * The box's own build folders (required.ts shadowPlan): `applied` lists the
+ * folders inside that boxrun bound (null: all of the plan). Their
+ * redirections (UV_PROJECT_ENVIRONMENT, ...) go in the env file for every
+ * command; shadows.json in the run folder tells boxd which folders are
+ * shadowed and what to bind when a new package appears mid-chat. CLI: the same.
+ */
+ useShadows(plan: ShadowPlan, applied: string[] | null = null): void {
+ const set = Array.isArray(applied) ? new Set(applied) : null;
+ const binds = plan.binds.filter((b) => !set || set.has(b.target));
+ this.shadows = { ...plan, binds, dirs: [...new Set(binds.map((b) => b.path.split("/").pop()!))] };
+ const rules = REQUIRED_RULES.shadows;
+ const lazy = rules.binds.filter((rule) => rule.even_if_absent).map((rule) => ({ dir: rule.dir, when_any: rule.when_any }));
+ writeJson(path.join(this.runFolder, "shadows.json"), { v: 1, root: this.croot, store: rules.store, active: binds.map((b) => b.target), lazy, limits: rules.limits, skip_dirs: rules.skip_dirs }, 0o644);
+ // The env file keeps what the wrappers and the git identity wrote; the redirections are set once.
+ const names = Object.keys(plan.env ?? {});
+ const file = path.join(this.runFolder, "env");
+ let lines: string[] = [];
+ try { lines = readFileSync(file, "utf8").split("\n").filter((line) => line && !names.some((name) => line.startsWith(`${name}=`))); } catch { /* none yet */ }
+ lines.push(...Object.entries(plan.env ?? {}).map(([k, v]) => `${k}=${v}`));
+ writeFileSync(file, `${lines.join("\n")}\n`, { mode: 0o644 });
+ this.writeRecord();
+ }
+
+ /** The shadows in use now: the start's, plus the folders boxd bound mid-chat (shadows-lazy.json in the run folder). */
+ currentShadows(): ShadowPlan | null {
+ if (!this.shadows) return null;
+ const lazy = readJson<{ binds?: Array<{ path?: unknown }> }>(path.join(this.runFolder, "shadows-lazy.json"));
+ const extra = (Array.isArray(lazy?.binds) ? lazy.binds : []).filter((b): b is { path: string } => typeof b?.path === "string" && !this.shadows!.binds.some((x) => x.path === b.path));
+ if (!extra.length) return this.shadows;
+ const more: ShadowBind[] = extra.map((b) => ({ path: b.path, existed: false, target: `${this.croot}/${b.path}` }));
+ return { ...this.shadows, binds: [...this.shadows.binds, ...more] };
+ }
+
/** The prompt number the package-manager wrappers write into their lines. */
setTurn(turn: number): void {
try { writeFileSync(path.join(this.runFolder, "state", "turn"), `${turn}\n`); } catch { /* best effort */ }
@@ -513,6 +561,8 @@ export class Box {
user: { uid: this.uid ?? 0, gid: this.gid ?? 0, home: HOME_IN_BOX },
environment: { HOME: HOME_IN_BOX, shims: this.pathPrefix ? SHIMS_DIR : null },
excluded: { prefixes: NOISE_PREFIXES, keep: KEEP_PREFIXES, patterns: NOISE_PATTERNS.map(String), dependency_dirs: [...DEPENDENCY_DIRS] },
+ // The box's own copies of build folders (macOS/Windows hosts), never in a checkpoint.
+ ...(this.shadows ? { [REQUIRED_RULES.shadows.record_key]: shadowRecord(this.currentShadows()) } : {}),
};
}
@@ -554,7 +604,9 @@ export class Box {
// What the box changed against its image: boxd's walk (fast, any runtime), else `diff`
// (overlay2's naive diff walks the whole image on most Linux kernels: ~1 s for 1 GB).
const mounts = [this.croot, RUN_DIR, `${SHIMS_DIR}-src`];
- const walked = await client.changes(endpoint, NOISE_PREFIXES, KEEP_PREFIXES);
+ // The shadow store's mount point (made at the box's start) is no change of the box.
+ const shadowed = this.currentShadows();
+ const walked = await client.changes(endpoint, shadowed ? [...NOISE_PREFIXES, path.posix.dirname(REQUIRED_RULES.shadows.store)] : NOISE_PREFIXES, KEEP_PREFIXES);
let entries: DiffEntry[];
let stats: BoxStat[];
let source = "boxd";
@@ -577,7 +629,8 @@ export class Box {
let depStats: BoxStat[] = [];
let depsInfo: { folders: number; entries: number; truncated: boolean } | null = null;
if (deps) {
- const folders = dependencyFolders(this.root).map((folder) => path.posix.join(this.croot, path.relative(this.root, folder).split(path.sep).join("/")));
+ const skip = shadowed ? new Set(shadowed.binds.map((b) => b.path)) : null;
+ const folders = dependencyFolders(this.root, { skip }).map((folder) => path.posix.join(this.croot, path.relative(this.root, folder).split(path.sep).join("/")));
if (folders.length) {
const walkedDeps = await client.walk(endpoint, folders);
depStats = (walkedDeps.entries ?? []).filter((entry) => !NOISE_PATTERNS.some((pattern) => pattern.test(entry.path)) && !/\/node_modules\/\.cache(\/|$)/.test(entry.path));
@@ -708,7 +761,9 @@ export class Box {
settled = true;
mkdirSync(to, { recursive: true });
const recordPath = path.join(to, "record.json");
- if (!existsSync(recordPath)) writeJson(recordPath, record, 0o600);
+ // A folder boxd shadowed mid-chat is in the next checkpoint's record (shadows are never in the tar).
+ const shadowsNow = (record as { shadows?: unknown }).shadows;
+ if (!existsSync(recordPath) || (shadowsNow && JSON.stringify(readJson<{ shadows?: unknown }>(recordPath)?.shadows ?? null) !== JSON.stringify(shadowsNow))) writeJson(recordPath, record, 0o600);
rmSync(path.join(to, `${label}.tar`), { force: true });
for (const name of readdirSync(stage)) renameSync(path.join(stage, name), path.join(to, name));
rmSync(stage, { recursive: true, force: true });
diff --git a/apps/server/src/box/client.ts b/apps/server/src/box/client.ts
index 8f606d2e..05f339e5 100644
--- a/apps/server/src/box/client.ts
+++ b/apps/server/src/box/client.ts
@@ -112,6 +112,72 @@ export async function exec(box: BoxEndpoint, argv: string[], { cwd, env, root =
return { code: result.exit.code, stdout: result.stdout, stderr: result.stderr, ms: result.exit.ms };
}
+/** A listening TCP socket inside the box (op "ports"). */
+export type BoxListener = { port: number; addr: string };
+
+/**
+ * The box's listening TCP ports (boxd's own left out), or null when this
+ * box's boxd predates the request (a box made by an older version: Reset
+ * sandbox gives it the new helper). Rejects when the box cannot be reached.
+ */
+export async function listPorts(box: BoxEndpoint, { timeoutMs = 5_000 }: { timeoutMs?: number } = {}): Promise<BoxListener[] | null> {
+ const result = await request(box, { op: "ports" }, { timeoutMs });
+ if (result.exit.code !== 0) {
+ if (/unknown op/.test(result.stderr)) return null;
+ throw new Error(`box ports failed: ${result.stderr.trim() || result.exit.code}`);
+ }
+ const parsed: unknown = JSON.parse(result.data.toString("utf8") || "[]");
+ return Array.isArray(parsed) ? parsed.filter((item): item is BoxListener => Number.isInteger(item?.port)) : [];
+}
+
+/**
+ * A TCP stream to `port` inside the box, through boxd: resolves { socket,
+ * head } once boxd connected (socket paused; `head` is what already arrived
+ * after boxd's answer and goes first), rejects with boxd's reason otherwise.
+ */
+export function connectPort(box: BoxEndpoint, port: number, { timeoutMs = 5_000 }: { timeoutMs?: number } = {}): Promise<{ socket: net.Socket; head: Buffer }> {
+ return new Promise((resolve, reject) => {
+ const socket = net.connect({ host: box.host || "127.0.0.1", port: box.port, allowHalfOpen: true });
+ socket.setNoDelay(true);
+ let buffered: Buffer = Buffer.alloc(0);
+ let settled = false;
+ const failText: string[] = [];
+ const done = (error: Error | null, value?: { socket: net.Socket; head: Buffer }) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ socket.removeListener("data", onData);
+ socket.removeListener("error", onError);
+ socket.removeListener("close", onClose);
+ if (error || !value) { socket.destroy(); reject(error ?? new Error("box connect failed")); } else resolve(value);
+ };
+ const timer = setTimeout(() => done(new Error(`box connect to port ${port} timed out after ${timeoutMs} ms`)), timeoutMs);
+ const onError = (error: Error) => done(error);
+ const onClose = () => done(new Error(`box closed the connect to port ${port} early`));
+ const onData = (chunk: Buffer) => {
+ buffered = buffered.length ? Buffer.concat([buffered, chunk]) : chunk;
+ while (buffered.length >= 5) {
+ const size = buffered.readUInt32BE(1);
+ if (buffered.length < 5 + size) return;
+ const kind = buffered[0];
+ const payload = buffered.subarray(5, 5 + size);
+ buffered = buffered.subarray(5 + size);
+ if (kind === T.data) {
+ socket.pause();
+ done(null, { socket, head: Buffer.from(buffered) });
+ return;
+ }
+ if (kind === T.fail || kind === T.stderr) failText.push(payload.toString("utf8"));
+ else if (kind === T.exit) { done(new Error(failText.join("").trim() || `box could not connect to port ${port}`)); return; }
+ }
+ };
+ socket.once("connect", () => socket.write(`${JSON.stringify({ v: PROTO_VERSION, token: box.token, op: "connect", port })}\n`));
+ socket.on("data", onData);
+ socket.on("error", onError);
+ socket.on("close", onClose);
+ });
+}
+
/** lstat of each path, in order (type "missing" for a path that is gone). */
export async function stat(box: BoxEndpoint, paths: string[], { timeoutMs = 60_000, budget = REQUEST_LINE_BUDGET }: { timeoutMs?: number; budget?: number } = {}): Promise<BoxStat[]> {
const out: BoxStat[] = [];
diff --git a/apps/server/src/box/common.ts b/apps/server/src/box/common.ts
index 92defd44..9113eb3a 100644
--- a/apps/server/src/box/common.ts
+++ b/apps/server/src/box/common.ts
@@ -96,6 +96,8 @@ export type BoxRecord = {
home: string; shell: string; path_prefix: string; env_file: string; updated: number; pid: number;
/** The app restarts boxd when boxsh asks (boxes/<key>.revive). */
revive?: boolean;
+ /** The agent's box notice adds this line (plugin-lib.ts BOX_NOTE): the box's own build folders (macOS/Windows hosts). */
+ shadows_note?: string;
};
export function readRecord(home: string, key: string): BoxRecord | null {
diff --git a/apps/server/src/box/launch.ts b/apps/server/src/box/launch.ts
index 35d1e818..0b4798b7 100644
--- a/apps/server/src/box/launch.ts
+++ b/apps/server/src/box/launch.ts
@@ -22,12 +22,13 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, r
import path from "node:path";
import * as client from "./client.js";
-import { boxKey, containerName, gcBoxes, installShell, openBox, recordFile, reviveFile, savedTurns, type Box, type BoxInstallLog, type BoxLabel, type BoxLog, type BoxRuntime, type CheckpointSummary } from "./box.js";
+import { boxKey, containerName, containerRoot, gcBoxes, installShell, openBox, recordFile, reviveFile, savedTurns, type Box, type BoxInstallLog, type BoxLabel, type BoxLog, type BoxRuntime, type CheckpointSummary } from "./box.js";
import { driverFor, normalizeBackend } from "./backends/index.js";
import type { BoxExec } from "./backends/types.js";
import { detectStack, imageFor, loadPins, type BoxImage } from "./images.js";
+import { portForwards, type PortForwardOptions, type PortForwards } from "./ports.js";
import { rememberPins } from "./retention.mjs";
-import { requiredFallback, type RequiredFallback } from "./required.js";
+import { requiredFallback, shadowPlan, shadowsApply, shadowsNotice, type RequiredFallback, type ShadowPlan } from "./required.js";
import { detectRuntime, runCommand, type RunCommand, type RuntimeResult } from "./runtime.js";
export const MODES = ["off", "offer", "on"] as const;
@@ -277,6 +278,10 @@ export type ReadyPlan = {
restart?: () => Promise<Box>;
/** What the box start is doing ("starting", "pulling", "ready", "failed"; null before it starts). */
readonly phase: string | null;
+ /** macOS / Windows with a backend that runs boxrun as root: the box's own build folders (required.ts), else null. */
+ shadows?: ShadowPlan | null;
+ /** The one line that says so (required.json texts.desktop.shadows), else null. */
+ shadowsLine?: string | null;
};
export type NativePlan = { box: null; notice: string | null; runtime: RuntimeResult | null; image?: BoxImage; downloading?: boolean };
export type BoxPlan = ReadyPlan | NativePlan;
@@ -286,10 +291,10 @@ export type BoxPlan = ReadyPlan | NativePlan;
* { box: null, notice } when its chats run on this machine for now (no
* runtime, no helpers, the image still downloading), else a ready plan.
*/
-export async function planBox({ env = process.env, home, root, log = () => {}, run = runCommand, probeMs = 4_000, shims = null, asked = null, allow = null }: { env?: NodeJS.ProcessEnv; home: string; root: string; log?: BoxLog; run?: RunCommand; probeMs?: number; shims?: string | null; asked?: string | null; allow?: string[] | null }): Promise<BoxPlan> {
+export async function planBox({ env = process.env, home, root, log = () => {}, run = runCommand, probeMs = 4_000, shims = null, asked = null, allow = null, platform = process.platform, stateDir = null, preferShadows = false }: { env?: NodeJS.ProcessEnv; home: string; root: string; log?: BoxLog; run?: RunCommand; probeMs?: number; shims?: string | null; asked?: string | null; allow?: string[] | null; platform?: NodeJS.Platform; stateDir?: string | null; preferShadows?: boolean }): Promise<BoxPlan> {
const key = boxKey(root);
const bounded = <T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> => Promise.race([promise, new Promise<T>((resolve) => setTimeout(() => resolve(fallback), ms))]);
- const runtime = await bounded<RuntimeResult>(detectRuntime({ boxHome: home, env, run, ...(asked ? { asked } : {}), allow }), probeMs, { ok: false, reason: "the sandbox backend did not answer in time" });
+ const runtime = await bounded<RuntimeResult>(detectRuntime({ boxHome: home, env, run, ...(asked ? { asked } : {}), allow, ...(preferShadows ? { preferShadows } : {}) }), probeMs, { ok: false, reason: "the sandbox backend did not answer in time" });
if (!runtime.ok) {
log("info", "box unavailable", { reason: runtime.reason });
return { box: null, notice: `Sandbox off for now: ${runtime.reason}.`, runtime };
@@ -317,9 +322,16 @@ export async function planBox({ env = process.env, home, root, log = () => {}, r
let opening: Promise<Box> | null = null;
let phase: string | null = null;
let startedWith: BoxInstallLog | null = null;
+ // macOS / Windows with a backend that runs boxrun as root (the WSL distro): the box's own build folders
+ // (required.ts shadowPlan), found now (bounded) so the project's one line can say so.
+ let shadows: ShadowPlan | null = null;
+ if (driver.shadows && shadowsApply(platform, env)) {
+ try { shadows = shadowPlan(root, { platform, croot: containerRoot(root, platform), stateDir, env }); } catch (error) { log("warn", "box shadows scan failed", { error: error instanceof Error ? error.message : String(error) }); }
+ if (shadows) log("info", "box shadows", { binds: shadows.binds.length, env: Object.keys(shadows.env), ms: shadows.ms, truncated: shadows.truncated });
+ }
const start = ({ pkglog = null }: { pkglog?: BoxInstallLog | null } = {}): Promise<Box> => {
if (!opening) startedWith = pkglog;
- opening ??= openBox({ root, runtime, env, home, log, pull: false, shims, pkglog, revive: true, onState: (state) => { phase = state; } });
+ opening ??= openBox({ root, runtime, env, home, log, pull: false, shims, pkglog, revive: true, shadows, platform, onState: (state) => { phase = state; } });
return opening;
};
return {
@@ -329,10 +341,12 @@ export async function planBox({ env = process.env, home, root, log = () => {}, r
start,
restart: () => {
if (!opening) return start();
- opening = openBox({ root, runtime, env, home, log, pull: false, shims, pkglog: startedWith, revive: true });
+ opening = openBox({ root, runtime, env, home, log, pull: false, shims, pkglog: startedWith, revive: true, shadows, platform });
return opening;
},
get phase() { return phase; },
+ shadows,
+ shadowsLine: shadowsNotice(shadows, platform),
};
}
@@ -418,7 +432,9 @@ export type BoxRun = {
setTurn: (turn: number) => void;
/** Start boxd again when it does not answer (resolves the Box now in use). */
heal: (why: string) => Promise<Box | null>;
- /** Stop watching for restart requests (the project's box is let go). */
+ /** The box's ports open on this computer now (ports.ts). */
+ forwardedPorts?: () => number[];
+ /** Stop watching for restart requests and close the port forwards (the project's box is let go). */
close: () => void;
/** `sessionTurn`: the chat's own number of the prompt the checkpoint comes before (written as session_turn). */
freeze: (label: string, options: { sessionId: string; turn?: number | null; sessionTurn?: number | null; chain?: string | null }) => Promise<Frozen | null>;
@@ -432,18 +448,29 @@ export type BoxRun = {
* "off"; the shell runs on this machine, its chats are not labelled); later
* failures are logged and that turn has no checkpoint.
*/
-export function boxRun(plan: ReadyPlan, { log = () => {}, readyWaitMs = 30_000, onNative = () => {}, onRevive = () => {}, tmpRoot, pkglog = null, pollMs = REVIVE_POLL_MS, ping = client.ping }: { log?: BoxLog; readyWaitMs?: number; onNative?: (reason: string) => void; onRevive?: (event: { ok: boolean; why: string; error?: string }) => void; tmpRoot?: string; pkglog?: BoxInstallLog | null; pollMs?: number; ping?: typeof client.ping } = {}): BoxRun {
+export function boxRun(plan: ReadyPlan, { log = () => {}, readyWaitMs = 30_000, onNative = () => {}, onRevive = () => {}, onPort = () => {}, tmpRoot, pkglog = null, pollMs = REVIVE_POLL_MS, ping = client.ping, env = process.env, forwards: makeForwards = portForwards }: { log?: BoxLog; readyWaitMs?: number; onNative?: (reason: string) => void; onRevive?: (event: { ok: boolean; why: string; error?: string }) => void; onPort?: (event: { port: number; open: boolean; line?: string; why?: string }) => void; tmpRoot?: string; pkglog?: BoxInstallLog | null; pollMs?: number; ping?: typeof client.ping; env?: NodeJS.ProcessEnv; forwards?: (options: PortForwardOptions) => PortForwards } = {}): BoxRun {
const { key, home, runtime, root } = plan.box;
let box: Box | null = null;
let native = false;
+ let closed = false;
const checkpoints = new Map<string, number>();
const requestFile = reviveFile(home, key);
// A restart request nobody answered before (the app quit): this start answers it.
try { rmSync(requestFile, { force: true }); } catch { /* not there */ }
const opening = plan.start({ pkglog }).then((opened) => { box = opened; return opened; });
+ // A box with its own network (Docker, Podman): its servers at the same port on this computer's 127.0.0.1
+ // (ports.ts), polled while the box is usable (none before it is ready, after a failure, once let go).
+ const wantsForwards = driverFor(runtime).forwardsPorts === false && String(env.OMNIRUSH_BOX_PORTS ?? "").trim().toLowerCase() !== "off";
+ const forwards = wantsForwards ? makeForwards({
+ endpoint: () => { const current: Box | null = box; return current?.ready && !native && !closed ? current.endpoint : null; },
+ log,
+ onOpen: (port, line) => { try { onPort({ port, line, open: true }); } catch { /* the caller's problem */ } },
+ onClose: (port, why) => { try { onPort({ port, open: false, why }); } catch { /* the caller's problem */ } },
+ }) : null;
const goNative = (reason: string) => {
if (native) return;
native = true;
+ forwards?.close();
recordOff(home, key, reason);
log("warn", "box off for this project", { reason });
onNative(reason);
@@ -539,7 +566,8 @@ export function boxRun(plan: ReadyPlan, { log = () => {}, readyWaitMs = 30_000,
label: (sessionId) => (box?.ready && !native && (checkpoints.get(sessionId) ?? 0) > 0 ? box.label() : null),
setTurn: (turn) => { lastTurn = turn; box?.setTurn(turn); },
heal,
- close: () => clearInterval(watcher),
+ forwardedPorts: () => forwards?.ports() ?? [],
+ close: () => { closed = true; clearInterval(watcher); forwards?.close(); },
/**
* The old sandbox's freeze(label, { turn, chain }) -> { save(dir), discard() } | null:
* the checkpoint is taken now and placed by save(); `final` (the state a
diff --git a/apps/server/src/box/plugin-lib.ts b/apps/server/src/box/plugin-lib.ts
index dd062632..25e5e631 100644
--- a/apps/server/src/box/plugin-lib.ts
+++ b/apps/server/src/box/plugin-lib.ts
@@ -21,7 +21,7 @@ export function keyOf(dir: string): string {
return createHash("sha256").update(resolved).digest("hex").slice(0, 12);
}
-export function record(key: string): { state?: string; uid?: number; croot?: string } | null {
+export function record(key: string): { state?: string; uid?: number; croot?: string; shadows_note?: string } | null {
try { return JSON.parse(readFileSync(path.join(boxHome(), "boxes", `${key}.json`), "utf8")); } catch { return null; }
}
@@ -77,11 +77,13 @@ export function toolPaths(tool: string, args: Record<string, unknown> = {}): str
return [args.filePath, args.path, args.file_path].filter((value): value is string => typeof value === "string" && Boolean(value));
}
-export const BOX_NOTE = (root: string, uid = 0, croot = root): string => [
+// `shadows`: the record's shadows_note (macOS/Windows hosts: the box's own node_modules, .venv, ...), one more line.
+export const BOX_NOTE = (root: string, uid = 0, croot = root, shadows: unknown = null): string => [
`Sandbox: shell commands run in a Linux (Debian) container, ${uid === 0 ? "as root" : "as a user with passwordless sudo"}, with HOME=/root.`,
croot && croot !== root
? `The project folder ${root} is ${croot} inside the container (the same files); use ${croot} in shell commands. Changes are visible on both sides.`
: `The project folder ${root} is the same folder inside the container (same path); changes to it are visible on both sides.`,
"Files outside the project folder (/tmp, HOME, system folders) exist only inside the container: read and change them with shell commands, not with the file tools.",
"Install what the task needs with the usual package managers (apt-get, pip, npm, cargo, go, ...); installs persist in this project's container across sessions.",
+ ...(typeof shadows === "string" && shadows ? [shadows] : []),
].join("\n");
diff --git a/apps/server/src/box/ports.ts b/apps/server/src/box/ports.ts
new file mode 100644
index 00000000..cf81e3d6
--- /dev/null
+++ b/apps/server/src/box/ports.ts
@@ -0,0 +1,210 @@
+// Ported from the CLI (omnirush-cli src/box/ports.js); keep the two in step.
+// Only types were added here.
+//
+// A server the agent starts in the box (`npm run dev` on :3000), at the same
+// port on this computer's 127.0.0.1, for backends whose box has its own
+// network (Docker, Podman, Apple container: driver.forwardsPorts === false).
+// bubblewrap shares this computer's network, WSL forwards localhost, and the
+// macOS VM forwards its guest's ports: they need none of this.
+//
+// While the box is in use, its listening ports are read from boxd every
+// ~2 s; a new one (1024-65535, not boxd's own, free on this computer) gets a
+// listener on 127.0.0.1:<port> here, and each connection to it goes through
+// its own boxd stream (op "connect"). The listener closes when the box stops
+// listening there or the box is let go. Nothing is ever bound beyond 127.0.0.1.
+
+import net from "node:net";
+
+import * as client from "./client.js";
+import type { BoxEndpoint, BoxListener } from "./client.js";
+import { BOX_PORT, type BoxLog } from "./common.js";
+
+export const PORT_POLL_MS = 2_000;
+export const PORT_MIN = 1024;
+export const PORT_MAX = 65535;
+/** At most this many forwards at once (a box listening on hundreds of ports is not a dev server). */
+export const PORT_FORWARDS_MAX = 32;
+
+/** The one line a forward's opening is told with. */
+export function portLine(port: number): string {
+ return `Port ${port} in the sandbox is open on this computer at http://127.0.0.1:${port}`;
+}
+
+/** Whether a box listener is one to forward (`skip`: ports never forwarded). */
+export function forwardable(port: number, skip: Set<number> = new Set([BOX_PORT])): boolean {
+ return Number.isInteger(port) && port >= PORT_MIN && port <= PORT_MAX && !skip.has(port);
+}
+
+/** Whether something on this computer answers at 127.0.0.1:<port>. */
+export function hostAnswers(port: number, { timeoutMs = 300 }: { timeoutMs?: number } = {}): Promise<boolean> {
+ return new Promise((resolve) => {
+ const socket = net.connect({ host: "127.0.0.1", port });
+ const done = (value: boolean) => { clearTimeout(timer); socket.destroy(); resolve(value); };
+ const timer = setTimeout(() => done(false), timeoutMs);
+ socket.once("connect", () => done(true));
+ socket.once("error", () => done(false));
+ });
+}
+
+/** Listen on 127.0.0.1:<port> (only there); resolves the server, or null when the port is taken. */
+export function listenLoopback(port: number, onConnection: (socket: net.Socket) => void): Promise<net.Server | null> {
+ return new Promise((resolve) => {
+ const server = net.createServer({ allowHalfOpen: true, pauseOnConnect: true }, onConnection);
+ const onError = () => { server.close(); resolve(null); };
+ server.once("error", onError);
+ server.listen({ host: "127.0.0.1", port, exclusive: true }, () => {
+ server.removeListener("error", onError);
+ server.on("error", () => {});
+ server.unref();
+ resolve(server);
+ });
+ });
+}
+
+/** Join a connection on this computer to a boxd stream: both ways, each end half-closing the other. */
+export function joinStreams(local: net.Socket, remote: net.Socket, head: Buffer = Buffer.alloc(0)): void {
+ const both = () => { local.destroy(); remote.destroy(); };
+ local.on("error", both);
+ remote.on("error", both);
+ local.on("close", () => remote.destroy());
+ remote.on("close", () => { if (!local.destroyed) local.end(); });
+ if (head.length) local.write(head);
+ remote.pipe(local);
+ local.pipe(remote);
+ local.resume();
+ remote.resume();
+}
+
+export type PortForwards = { tick: () => Promise<void>; ports: () => number[]; close: () => void };
+
+export type PortForwardOptions = {
+ /** boxd's address now; null while the box is not usable. */
+ endpoint: () => BoxEndpoint | null;
+ log?: BoxLog;
+ onOpen?: (port: number, line: string) => void;
+ onClose?: (port: number, why: string) => void;
+ pollMs?: number;
+ skip?: Set<number>;
+ max?: number;
+ list?: (endpoint: BoxEndpoint) => Promise<BoxListener[] | null>;
+ connect?: (endpoint: BoxEndpoint, port: number) => Promise<{ socket: net.Socket; head: Buffer }>;
+ hostBusy?: (port: number) => Promise<boolean>;
+ listen?: (port: number, onConnection: (socket: net.Socket) => void) => Promise<net.Server | null>;
+ /** Poll on its own (false: only tick(), tests). */
+ timers?: boolean;
+};
+
+/** The forwards of one project's box; the poll runs until close(). */
+export function portForwards({
+ endpoint,
+ log = () => {},
+ onOpen = () => {},
+ onClose = () => {},
+ pollMs = PORT_POLL_MS,
+ skip = new Set([BOX_PORT]),
+ max = PORT_FORWARDS_MAX,
+ list = (ep) => client.listPorts(ep),
+ connect = (ep, port) => client.connectPort(ep, port),
+ hostBusy = (port) => hostAnswers(port),
+ listen = listenLoopback,
+ timers = true,
+}: PortForwardOptions): PortForwards {
+ const forwards = new Map<number, { server: net.Server; sockets: Set<net.Socket> }>();
+ const told = new Set<number>(); // ports already said to be taken here (said once)
+ let closed = false;
+ let running: Promise<void> | null = null;
+ let unsupported = false;
+ let timer: ReturnType<typeof setInterval> | null = null;
+
+ const shut = (port: number, why: string) => {
+ const forward = forwards.get(port);
+ if (!forward) return;
+ forwards.delete(port);
+ forward.server.close();
+ for (const socket of forward.sockets) socket.destroy();
+ log("info", "box port forward closed", { port, why });
+ onClose(port, why);
+ };
+
+ const taken = (port: number) => {
+ if (told.has(port)) return;
+ told.add(port);
+ log("info", "box port not forwarded: in use on this computer", { port });
+ };
+
+ const open = async (port: number) => {
+ // Something of this computer's own answers there: it stays this computer's.
+ if (await hostBusy(port)) return taken(port);
+ const sockets = new Set<net.Socket>();
+ const server = await listen(port, (local) => {
+ sockets.add(local);
+ local.on("close", () => sockets.delete(local));
+ const ep = endpoint();
+ if (!ep) { local.destroy(); return; }
+ connect(ep, port).then(({ socket, head }) => {
+ if (local.destroyed || closed) { socket.destroy(); return; }
+ sockets.add(socket);
+ socket.on("close", () => sockets.delete(socket));
+ joinStreams(local, socket, head);
+ }, (error: unknown) => {
+ log("info", "box port connection failed", { port, error: error instanceof Error ? error.message : String(error) });
+ local.destroy();
+ });
+ });
+ if (!server) return taken(port);
+ if (closed) { server.close(); return; }
+ told.delete(port);
+ forwards.set(port, { server, sockets });
+ log("info", "box port forwarded", { port, line: portLine(port) });
+ onOpen(port, portLine(port));
+ };
+
+ const once = async () => {
+ const ep = endpoint();
+ if (!ep || unsupported) return;
+ let listening: BoxListener[] | null;
+ try {
+ listening = await list(ep);
+ } catch {
+ return; // the box does not answer now (stopped, restarting): the forwards stay until it says otherwise
+ }
+ if (listening === null) {
+ unsupported = true;
+ log("info", "box ports not forwarded: this sandbox was made by an older version (Reset sandbox gives it the new helper)");
+ return;
+ }
+ const wanted = new Set(listening.map((item) => item.port).filter((port) => forwardable(port, skip)));
+ for (const port of [...forwards.keys()]) if (!wanted.has(port)) shut(port, "gone");
+ for (const port of [...wanted].sort((a, b) => a - b)) {
+ if (closed) return;
+ if (forwards.has(port)) continue;
+ if (forwards.size >= max) break;
+ await open(port);
+ }
+ };
+
+ const tick = (): Promise<void> => {
+ if (closed) return Promise.resolve();
+ running ??= once()
+ .catch((error: unknown) => log("warn", "box port forwards failed", { error: error instanceof Error ? error.message : String(error) }))
+ .finally(() => { running = null; });
+ return running;
+ };
+
+ if (timers) {
+ timer = setInterval(() => { void tick(); }, pollMs);
+ timer.unref?.();
+ void tick();
+ }
+
+ return {
+ tick,
+ ports: () => [...forwards.keys()].sort((a, b) => a - b),
+ close() {
+ if (closed) return;
+ closed = true;
+ if (timer) clearInterval(timer);
+ for (const port of [...forwards.keys()]) shut(port, "ended");
+ },
+ };
+}
diff --git a/apps/server/src/box/required.ts b/apps/server/src/box/required.ts
index 6a6eceab..ac5729a4 100644
--- a/apps/server/src/box/required.ts
+++ b/apps/server/src/box/required.ts
@@ -8,10 +8,11 @@
// (host_only), OMNIRUSH_BOX=0 (env_off), and machines where the box cannot
// run (the `required_fallback` answer; the setup screen says why).
-import { closeSync, openSync, readSync, readdirSync, type Dirent } from "node:fs";
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync, type Dirent } from "node:fs";
import path from "node:path";
-import { HOST_BUILD_RULES } from "./host-builds.js";
+import { HOST_BUILD_RULES, hostBuilds, hostRules } from "./host-builds.js";
import rules from "./required.json" with { type: "json" };
export type RequiredFallback = "native" | "native_uncounted";
@@ -104,3 +105,126 @@ export function hostOnlyProject(root: string, { platform = process.platform, rea
const host = HOST_BUILD_RULES.hosts[platform];
return { things, notice: desktopText("host_only", { label: host?.label ?? platform, things: things.slice(0, 3).join(", "), machine: host?.machine ?? "this computer" }) };
}
+
+// --- build-artefact shadows ------------------------------------------------------
+// The box's own copy of each build folder on a macOS or Windows host (CLI:
+// required.js shadowPlan; boxrun/boxd shadows.go in box/go do the mounts).
+
+/** One shadowed folder: `path` project-relative (POSIX), `target` the folder inside the box, `id` its store name. */
+export type ShadowBind = { path: string; existed: boolean; id?: string; target: string };
+/** What a box start found: binds, env redirections ({store} filled in), the folder names, how the scan went. */
+export type ShadowPlan = { binds: ShadowBind[]; env: Record<string, string>; dirs: string[]; scanned: number; truncated: boolean; ms: number };
+/** record.json `shadows` (the converter maps these back and drops the host copies). */
+export type ShadowRecord = { binds: Array<{ path: string; existed: boolean }>; env: Record<string, string> };
+
+type ShadowLimits = { entries: number; ms: number; depth: number; max: number };
+
+/** Whether boxes on this host get shadows at all (macOS, Windows; OMNIRUSH_BOX_SHADOWS=off: never). */
+export function shadowsApply(platform: string = process.platform, env: NodeJS.ProcessEnv = process.env): boolean {
+ if (String(env.OMNIRUSH_BOX_SHADOWS ?? "").trim().toLowerCase() === "off") return false;
+ return rules.shadows.hosts.includes(platform);
+}
+
+/**
+ * The store name of a project-relative path: sha256 of the path (POSIX
+ * separators, "." for the project root), first 12 hex digits. boxd computes
+ * the same for a folder it shadows mid-chat (box/go/cmd/boxd shadows.go).
+ */
+export function shadowId(rel: string | null | undefined): string {
+ const clean = String(rel ?? "").split(/[\\/]+/).filter((p) => p && p !== ".").join("/") || ".";
+ return createHash("sha256").update(clean).digest("hex").slice(0, 12);
+}
+
+/**
+ * Whether `dir` satisfies one `when_any` marker: a file name in the folder
+ * ("package.json"), a glob of one ("*.csproj"), a file inside the shadowed
+ * folder itself ("pyvenv.cfg@dir"), or "@host-binaries" (host-builds.ts found
+ * this host's programs in that folder).
+ */
+function markerHolds(marker: string, { names, target, rel, hostBinary }: { names: string[]; target: string; rel: string; hostBinary: (rel: string) => boolean }): boolean {
+ if (marker === "@host-binaries") return hostBinary(rel);
+ if (marker.endsWith("@dir")) return existsSync(path.join(target, marker.slice(0, -4)));
+ if (marker.startsWith("*")) return names.some((name) => name.endsWith(marker.slice(1)));
+ return names.includes(marker);
+}
+
+/**
+ * The shadows a box on this host gets for `root` (box start): a bounded scan
+ * (shadows.limits: entries, ms, depth; at most `max`) of the project's
+ * folders against shadows.binds and, in the root only, shadows.env. Paths
+ * are relative to the root (POSIX), `target` is the folder inside the box
+ * (`croot`/path). `{store}` in an env value is `<store>/<shadowId(".")>`.
+ */
+export function shadowPlan(root: string, { platform = process.platform, croot = root, stateDir = null, env = process.env, now = Date.now, limits = rules.shadows.limits }: { platform?: string; croot?: string; stateDir?: string | null; env?: NodeJS.ProcessEnv; now?: () => number; limits?: ShadowLimits } = {}): ShadowPlan {
+ const set = rules.shadows;
+ const started = now();
+ const out: ShadowPlan = { binds: [], env: {}, dirs: [], scanned: 0, truncated: false, ms: 0 };
+ if (!shadowsApply(platform, env)) return out;
+ let found: { hits: Array<{ kind: string; path: string }> } | null = null;
+ const hostBinary = (rel: string) => {
+ found ??= (() => { try { return hostBuilds(root, { platform, stateDir, env }); } catch { return { hits: [] }; } })();
+ return (found.hits ?? []).some((hit) => hit.kind === "binary" && (hit.path === rel || hit.path.startsWith(`${rel}/`)));
+ };
+ const seen = new Set<string>();
+ const over = () => {
+ if (out.scanned > limits.entries || now() - started > limits.ms) out.truncated = true;
+ return out.truncated;
+ };
+ const inBox = (rel: string) => (rel ? `${String(croot).replace(/\/+$/, "")}/${rel}` : croot);
+ const visit = (dir: string, rel: string, depth: number) => {
+ if (over()) return;
+ let list: Dirent[];
+ try { list = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+ out.scanned += list.length + 1;
+ const names = list.filter((e) => e.isFile()).map((e) => e.name);
+ if (depth === 0) {
+ for (const rule of set.env) {
+ if (!rule.when_any.some((m) => names.includes(m))) continue;
+ for (const [name, value] of Object.entries(rule.set)) if (typeof value === "string") out.env[name] = value.replaceAll("{store}", `${set.store}/${shadowId(".")}`);
+ }
+ }
+ for (const rule of set.binds) {
+ if (out.binds.length >= limits.max) { out.truncated = true; break; }
+ const relDir = rel ? `${rel}/${rule.dir}` : rule.dir;
+ if (seen.has(relDir)) continue;
+ const target = path.join(dir, ...rule.dir.split("/"));
+ let existed = false;
+ try { existed = statSync(target).isDirectory(); } catch { existed = false; }
+ if (!existed && !rule.even_if_absent) continue;
+ if (!rule.when_any.some((m) => markerHolds(m, { names, target, rel: relDir, hostBinary }))) continue;
+ seen.add(relDir);
+ out.binds.push({ path: relDir, existed, id: shadowId(relDir), target: inBox(relDir) });
+ if (!out.dirs.includes(rule.dir)) out.dirs.push(rule.dir);
+ }
+ if (depth >= limits.depth) return;
+ for (const entry of list) {
+ if (over()) return;
+ if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+ if (entry.name.startsWith(".") || set.skip_dirs.includes(entry.name)) continue;
+ const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+ // A shadowed folder is the box's own: nothing in it is the project's.
+ if (seen.has(childRel)) continue;
+ visit(path.join(dir, entry.name), childRel, depth + 1);
+ }
+ };
+ visit(root, "", 0);
+ out.ms = now() - started;
+ return out;
+}
+
+/** What a box record (record.json) says of its shadows, or null with none. */
+export function shadowRecord(plan: Pick<ShadowPlan, "binds" | "env"> | null | undefined): ShadowRecord | null {
+ if (!plan || (!plan.binds?.length && !Object.keys(plan.env ?? {}).length)) return null;
+ return { binds: plan.binds.map((b) => ({ path: b.path, existed: Boolean(b.existed) })), env: { ...plan.env } };
+}
+
+/** The one shadows line (required.json texts.desktop.shadows; null with none active). */
+export function shadowsNotice(plan: Pick<ShadowPlan, "binds" | "env" | "dirs"> | null | undefined, platform: string = process.platform, surface: "desktop" | "cli" = "desktop"): string | null {
+ if (!plan || !shadowRecord(plan)) return null;
+ const dirs = [...(plan.dirs ?? [])];
+ const envDirs: Record<string, string> = { UV_PROJECT_ENVIRONMENT: ".venv", POETRY_VIRTUALENVS_PATH: ".venv", CARGO_TARGET_DIR: "target" };
+ for (const name of Object.keys(plan.env ?? {})) if (envDirs[name] && !dirs.includes(envDirs[name]!)) dirs.push(envDirs[name]!);
+ const host = hostRules(platform);
+ const texts: Record<string, string> = surface === "cli" ? rules.texts.cli : rules.texts.desktop;
+ return fill(texts.shadows ?? rules.texts.desktop.shadows, { dirs: dirs.slice(0, 4).join(", "), label: host?.label ?? "this computer's" });
+}
diff --git a/apps/server/src/box/runtime.ts b/apps/server/src/box/runtime.ts
index 116351d3..3114eb64 100644
--- a/apps/server/src/box/runtime.ts
+++ b/apps/server/src/box/runtime.ts
@@ -358,4 +358,6 @@ export type DetectOptions = {
allow?: string[] | null;
arch?: string;
release?: string;
+ /** Under the required sandbox on macOS/Windows: the backends whose boxes get their own build folders (driver.shadows) first. */
+ preferShadows?: boolean;
};
diff --git a/apps/server/src/box/service.ts b/apps/server/src/box/service.ts
index eb18fc52..9ca8e06a 100644
--- a/apps/server/src/box/service.ts
+++ b/apps/server/src/box/service.ts
@@ -30,8 +30,9 @@ import type { BoxExec } from "./backends/types.js";
import type { BoxEndpoint } from "./client.js";
import { hostBuilds, hostBuildsNotice, hostBuildThings, hostRules } from "./host-builds.js";
import { detectStack, imageFor, type BoxImage } from "./images.js";
+import { portLine } from "./ports.js";
import { askedBackend, boxRun, planBox, pullLog, pullMarker, pulling, pullInBackground, resolveMode, saveBackend, serverBackends, serverDefault, serverRequired, shimsDir, type BoxRun, type ProjectBoxMode, type ServerBoxDefault } from "./launch.js";
-import { desktopText, hostOnlyProject, type RequiredFallback } from "./required.js";
+import { desktopText, hostOnlyProject, shadowsApply, shadowsNotice, type RequiredFallback } from "./required.js";
import { cachedWindowsChecks, classifySetup, linuxAllow, resumeWinSetup, saveSetupState, setupState, windowsInstall, windowsRestart, windowsUpdate, type BoxSetup } from "./setup.js";
import type { BoxInstallLogPaths } from "./install-log.js";
import { DESKTOP_PROJECTS_FILE } from "./plugin-lib.js";
@@ -106,6 +107,8 @@ export type BoxStatus = {
setup: (BoxSetup & { line: string | null }) | null;
/** Asked for one chat (`?session=`): it ran on this computer before the sandbox was required and stays here. */
chatKept: boolean;
+ /** Servers in the box open at the same port on this computer's 127.0.0.1 (Docker/Podman boxes; ports.ts). */
+ ports: Array<{ port: number; url: string; line: string }>;
};
/** The setup screen's steps (POST /workspace/:id/box/setup). */
@@ -257,10 +260,12 @@ export class BoxService {
* The backend detection's inputs: the setting (or OMNIRUSH_BOX_BACKEND) and the server's allowlist.
* While the sandbox is required, a saved "native" reads as automatic (OMNIRUSH_BOX_BACKEND=native still counts).
*/
- private detectOptions(): Pick<DetectOptions, "asked" | "allow"> {
+ private detectOptions(): Pick<DetectOptions, "asked" | "allow" | "preferShadows"> {
const asked = askedBackend({ env: this.env, stateDir: this.options.stateDir });
- const backend = asked.source === "setting" && asked.backend === "native" && this.required().required ? "auto" : asked.backend;
- return { asked: backend, allow: serverBackends(this.options.stateDir) };
+ const required = this.required().required;
+ const backend = asked.source === "setting" && asked.backend === "native" && required ? "auto" : asked.backend;
+ // Under required on macOS / Windows the backends that give the box its own build folders (shadows) come first.
+ return { asked: backend, allow: serverBackends(this.options.stateDir), ...(required && shadowsApply(this.platform, this.env) ? { preferShadows: true } : {}) };
}
private detect(extra: DetectOptions = {}): Promise<RuntimeResult> {
@@ -419,7 +424,7 @@ export class BoxService {
project.nextPlanAt = 0;
}
if (Date.now() < project.nextPlanAt) return null;
- const plan = await planBox({ env: this.env, home: this.home, root, log: this.log, shims: shimsDir(this.env), ...this.detectOptions() });
+ const plan = await planBox({ env: this.env, home: this.home, root, log: this.log, shims: shimsDir(this.env), platform: this.platform, stateDir: this.options.stateDir, ...this.detectOptions() });
project.waitingImage = !plan.box && plan.downloading === true;
project.lastRuntime = plan.box ? null : plan.runtime;
project.pull = !plan.box && plan.downloading === true && plan.image && plan.runtime?.ok ? { runtime: plan.runtime, image: plan.image } : null;
@@ -449,6 +454,8 @@ export class BoxService {
project.notice = `Sandbox stopped: ${event.error}.`;
}
},
+ // A server in the box (its own network) at the same port on this computer's 127.0.0.1: one log line (ports.ts).
+ onPort: (event) => { if (event.open) this.log("info", event.line ?? `box port ${event.port} open`, { key, port: event.port }); },
onNative: (reason) => {
project.notice = `Sandbox off for now: ${reason}.`;
project.nextPlanAt = Date.now() + REPLAN_MS;
@@ -561,7 +568,7 @@ export class BoxService {
const needed = required === true;
const requiredText = needed ? { line: desktopText("required_line"), optOut: desktopText("opt_out_refused"), keptOldChat: desktopText("kept_old_chat") } : null;
const chatKept = Boolean(sessionId && this.nativeChats.has(sessionId));
- const base = { mode: settings.mode, serverDefault: server, on, source, offer, error: null, hostBuilds: gate, boxNotice: null, required: needed, requiredText, hostOnly, setup: null, chatKept };
+ const base = { mode: settings.mode, serverDefault: server, on, source, offer, error: null, hostBuilds: gate, boxNotice: null, required: needed, requiredText, hostOnly, setup: null, chatKept, ports: [] as BoxStatus["ports"] };
const backendSetting = { ...askedBackend({ env: this.env, stateDir: this.options.stateDir }), choices: backendChoices() };
const setting = { value: backendSetting.backend, source: backendSetting.source, choices: backendSetting.choices };
if (workspace.workspaceType !== "local") return { ...base, on: false, offer: false, state: "off", runtime: null, backend: null, backendSetting: setting, image: null, progress: null, container: null, platform: this.platform, notice: "The sandbox is for folders on this computer." };
@@ -633,8 +640,11 @@ export class BoxService {
: offer && source === "buildathon" ? BUILDATHON_OFFER_NOTICE
: null,
error: run?.box?.error ?? (record?.state === "off" || record?.state === "failed" ? record.error || null : null),
- boxNotice: on && hostRules(this.platform) ? hostBuildsNotice("box", { platform: this.platform }) : null,
+ // The box's own build folders in use (required.json texts.desktop.shadows), else the plain macOS/Windows line.
+ boxNotice: on && run && !run.native && run.box?.shadows ? shadowsNotice(run.box.currentShadows(), this.platform) ?? hostBuildsNotice("box", { platform: this.platform })
+ : on && hostRules(this.platform) ? hostBuildsNotice("box", { platform: this.platform }) : null,
setup,
+ ports: run && !run.native ? (run.forwardedPorts?.() ?? []).map((port) => ({ port, url: `http://127.0.0.1:${port}`, line: portLine(port) })) : [],
};
}
diff --git a/apps/server/src/opencode-plugins/omnirush-box.ts b/apps/server/src/opencode-plugins/omnirush-box.ts
index 0e94084b..820ba138 100644
--- a/apps/server/src/opencode-plugins/omnirush-box.ts
+++ b/apps/server/src/opencode-plugins/omnirush-box.ts
@@ -84,7 +84,7 @@ export const OmniRushBox = async ({ directory, client }: { directory?: string; c
const line = output.system[i];
if (typeof line === "string") output.system[i] = line.replace(/^(\s*Platform:\s*)(darwin|win32|linux)\s*$/m, "$1linux");
}
- output.system.push(BOX_NOTE(root, Number(rec.uid) || 0, typeof rec.croot === "string" ? rec.croot : root));
+ output.system.push(BOX_NOTE(root, Number(rec.uid) || 0, typeof rec.croot === "string" ? rec.croot : root, rec.shadows_note));
},
};
};