@omg-dev/sandbox 0.4.30 → 0.4.32

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { _ as SandboxClient, a as compileStartScript, c as download, d as templateContentVersionRef, f as templateDefinitionHash, g as SandboxApiError, h as waitForSnapshotUpload, i as check, l as files, m as templateVersionRef, n as apt, o as compileStep, p as templateRuntimeContract, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as run, v as assertTemplateId } from "./templates-C3mBSGdT.mjs";
+import { _ as SandboxClient, a as compileStartScript, c as download, d as templateContentVersionRef, f as templateDefinitionHash, g as SandboxApiError, h as waitForSnapshotUpload, i as check, l as files, m as templateVersionRef, n as apt, o as compileStep, p as templateRuntimeContract, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as run, v as assertTemplateId } from "./templates-BLd13wPT.mjs";
 export { SandboxApiError, SandboxClient, applyTemplate, apt, assertTemplateId, bakeTemplate, check, compileStartScript, compileStep, defineTemplate, download, files, run, templateContentVersionRef, templateDefinitionHash, templateRuntimeContract, templateVersionRef, waitForSnapshotUpload };

package/dist/{templates-C3mBSGdT.mjs → templates-BLd13wPT.mjs}

@@ -96,7 +96,7 @@ var SandboxClient = class {
 					mode: file.mode
 				})));
 			},
-			snapshot: () => this.request("POST", `/v1/sandboxes/${id}/snapshot`),
+			snapshot: (options = {}) => this.request("POST", `/v1/sandboxes/${id}/snapshot`, options),
 			stop: () => this.request("DELETE", `/v1/sandboxes/${id}`)
 		};
 	}
@@ -150,6 +150,7 @@ function defineTemplate(definition) {
 	assertTemplateId(definition.id);
 	if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,19}$/.test(definition.version)) throw new Error("invalid template version");
 	if (!definition.title.trim()) throw new Error("template title is required");
+	if (definition.restoreKind !== "project_only" && definition.restoreKind !== "full_rootfs") throw new Error("template restoreKind must be project_only or full_rootfs");
 	for (const port of definition.ports ?? []) if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`invalid template port ${port}`);
 	return Object.freeze(definition);
 }
@@ -172,6 +173,7 @@ function templateDefinitionHash(definition) {
 function templateRuntimeContract(definition, immutableRef) {
 	return {
 		immutableRef,
+		restoreKind: definition.restoreKind,
 		startCommand: definition.start ? "exec /home/user/.omg/template/bootstrap.sh" : void 0,
 		readinessPort: definition.start?.readiness?.port,
 		readinessPath: definition.start?.readiness?.path,
@@ -218,12 +220,14 @@ function compileStep(step) {
 function compileStartScript(start) {
 	const port = start.readiness?.port;
 	const timeout = start.readiness?.timeoutSeconds ?? 60;
+	const supervisorMarker = "omg-template-supervisor";
 	const foreground = commandForUser(`${shellEnvAssignments({
 		HOME: start.user ? `/home/${start.user}` : "/root",
 		...start.env ?? {}
 	}).map((assignment) => `export ${assignment}`).join("\n")}\n${`${start.cwd ? `cd ${quote(start.cwd)} && ` : ""}${start.command}`}`, start.user);
 	const probe = port ? `for _ in $(seq 1 ${timeout}); do curl -fsS -m1 -o /dev/null ${quote(`http://127.0.0.1:${port}${start.readiness?.path ?? "/"}`)} && exit 0; sleep 1; done\necho 'template service did not become ready on :${port}' >&2\nexit 1` : "exit 0";
-	return `#!/usr/bin/env bash\nset -euo pipefail\nmkdir -p /home/user/.omg/template\npidfile=/home/user/.omg/template/start.pid\nif [ -s \"$pidfile\" ] && kill -0 \"$(cat \"$pidfile\")\" 2>/dev/null; then exit 0; fi\nnohup /bin/bash -lc ${quote(`while true; do ${foreground} >>/home/user/.omg/template/start.log 2>&1 || true; sleep 2; done`)} >/dev/null 2>&1 &\necho $! > \"$pidfile\"\n${probe}\n`;
+	const supervisor = `while true; do ${foreground} >>/home/user/.omg/template/start.log 2>&1 || true; sleep 2; done`;
+	return `#!/usr/bin/env bash\nset -euo pipefail\nmkdir -p /home/user/.omg/template\npidfile=/home/user/.omg/template/start.pid\npid=\"\"\nif [ -s \"$pidfile\" ]; then pid=\"$(cat \"$pidfile\" 2>/dev/null || true)\"; fi\nsupervisor_alive=false\nif [[ \"$pid\" =~ ^[0-9]+$ ]] && kill -0 \"$pid\" 2>/dev/null && tr '\\0' '\\n' < \"/proc/$pid/cmdline\" 2>/dev/null | grep -Fxq ${quote(supervisorMarker)}; then supervisor_alive=true; fi\nif [ \"$supervisor_alive\" != true ]; then\n  rm -f \"$pidfile\"\n  nohup /bin/bash -lc ${quote(supervisor)} ${quote(supervisorMarker)} >/dev/null 2>&1 &\n  echo $! > \"$pidfile\"\nfi\n${probe}\n`;
 }
 async function assertExec(label, result) {
 	if (result.exitCode !== 0) throw new Error(`${label} failed (${result.exitCode}): ${(result.stderr || result.stdout).trim().slice(-1200)}`);
@@ -289,7 +293,7 @@ async function runTemplateStep(sandbox, label, script, timeoutMs) {
 		await sandbox.shell(`rm -rf ${quote(workDir)}`, { timeoutMs: 1e4 }).catch(() => {});
 	}
 }
-const FILES_STEP_SKIP_NAMES = new Set([".gitkeep", ".DS_Store"]);
+const FILES_STEP_SKIP_NAMES = /* @__PURE__ */ new Set([".gitkeep", ".DS_Store"]);
 async function walkSourceDir(dir) {
 	const out = [];
 	async function visit(d) {
@@ -374,7 +378,7 @@ async function bakeTemplate(client, definition, options = {}) {
 	let snapshotted = false;
 	try {
 		await applyTemplate(sandbox, definition, log);
-		const snapshot = await sandbox.snapshot();
+		const snapshot = await sandbox.snapshot({ restoreKind: definition.restoreKind });
 		snapshotted = true;
 		const rootfsSha = (await waitForSnapshotUpload(client, snapshot)).rootfsSha?.trim();
 		if (!rootfsSha) throw new Error(`snapshot ${snapshot.id} has no rootfsSha — cannot derive an immutable template version identity`);

package/dist/templates.mjs

@@ -1,2 +1,2 @@
-import { a as compileStartScript, c as download, d as templateContentVersionRef, f as templateDefinitionHash, h as waitForSnapshotUpload, i as check, l as files, m as templateVersionRef, n as apt, o as compileStep, p as templateRuntimeContract, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as run } from "./templates-C3mBSGdT.mjs";
+import { a as compileStartScript, c as download, d as templateContentVersionRef, f as templateDefinitionHash, h as waitForSnapshotUpload, i as check, l as files, m as templateVersionRef, n as apt, o as compileStep, p as templateRuntimeContract, r as bakeTemplate, s as defineTemplate, t as applyTemplate, u as run } from "./templates-BLd13wPT.mjs";
 export { applyTemplate, apt, bakeTemplate, check, compileStartScript, compileStep, defineTemplate, download, files, run, templateContentVersionRef, templateDefinitionHash, templateRuntimeContract, templateVersionRef, waitForSnapshotUpload };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omg-dev/sandbox",
-  "version": "0.4.30",
+  "version": "0.4.32",
   "type": "module",
   "exports": {
     ".": {

package/src/client.test.ts

@@ -44,6 +44,7 @@ describe("template version identity", () => {
     id: "my-agent",
     version: "3",
     title: "Mine",
+    restoreKind: "full_rootfs",
     install: [],
   });
 
@@ -68,7 +69,7 @@ describe("template version identity", () => {
   });
 
   test("long ids truncate to fit the 40-char registry limit", () => {
-    const long = defineTemplate({ id: "a".repeat(40), version: "12", title: "Long", install: [] });
+    const long = defineTemplate({ id: "a".repeat(40), version: "12", title: "Long", restoreKind: "full_rootfs", install: [] });
     const ref = templateContentVersionRef(long, "rootfs-sha-1");
     expect(ref.length).toBeLessThanOrEqual(40);
     expect(ref).toMatch(/-v12-[0-9a-f]{8}$/);
@@ -84,6 +85,7 @@ describe("SandboxClient template bake", () => {
       id: "my-agent",
       version: "3",
       title: "Mine",
+      restoreKind: "full_rootfs",
       ports: [8766],
       install: [],
       start: { command: "bun start", readiness: { port: 8766, path: "/health" } },
@@ -101,6 +103,7 @@ describe("SandboxClient template bake", () => {
     expect(calls.filter((call) => call.path.includes("/v1/templates/") && call.method === "POST").map((call) => call.body)).toEqual([
       {
         snapshotId: "snap-1",
+        restoreKind: "full_rootfs",
         startCommand: "exec /home/user/.omg/template/bootstrap.sh",
         readinessPort: 8766,
         readinessPath: "/health",
@@ -108,6 +111,7 @@ describe("SandboxClient template bake", () => {
       },
       {
         snapshotId: "snap-1",
+        restoreKind: "full_rootfs",
         startCommand: "exec /home/user/.omg/template/bootstrap.sh",
         readinessPort: 8766,
         readinessPath: "/health",
@@ -124,6 +128,7 @@ describe("SandboxClient template bake", () => {
       id: "my-agent",
       version: "3",
       title: "Mine",
+      restoreKind: "full_rootfs",
       install: [],
     }), { systemClient });
     const sandboxCalls = calls.filter((call) => !call.path.includes("/v1/templates/"));
@@ -133,7 +138,7 @@ describe("SandboxClient template bake", () => {
   });
 
   test("an already-published content identity is reused: latest repoints, the immutable version is never republished", async () => {
-    const definition = defineTemplate({ id: "my-agent", version: "3", title: "Mine", install: [] });
+    const definition = defineTemplate({ id: "my-agent", version: "3", title: "Mine", restoreKind: "full_rootfs", install: [] });
     const ref = templateContentVersionRef(definition, "rootfs-sha-1");
     const { calls, fakeFetch } = fakeInfra({ existingVersions: { [ref]: "snap-old" } });
     const client = new SandboxClient({ baseUrl: "https://infra.example", token: "secret", ownerId: "user-123", fetch: fakeFetch });
@@ -154,7 +159,7 @@ describe("SandboxClient template bake", () => {
   test("missing rootfsSha fails loud instead of publishing a collision-prone static ref", async () => {
     const { fakeFetch } = fakeInfra({ snapshotRootfsSha: null });
     const client = new SandboxClient({ baseUrl: "https://infra.example", token: "secret", ownerId: "user-123", fetch: fakeFetch });
-    await expect(bakeTemplate(client, defineTemplate({ id: "my-agent", version: "3", title: "Mine", install: [] })))
+    await expect(bakeTemplate(client, defineTemplate({ id: "my-agent", version: "3", title: "Mine", restoreKind: "full_rootfs", install: [] })))
       .rejects.toThrow(/rootfsSha/);
   });
 });

package/src/client.ts

@@ -29,6 +29,10 @@ export interface Snapshot {
   rootfsSha?: string;
 }
 
+export interface SnapshotOptions {
+  restoreKind?: "project_only" | "full_rootfs";
+}
+
 /** Error thrown by SandboxClient.request carrying the HTTP status, so callers
  * can branch on well-defined statuses (e.g. 404 template probe) instead of
  * string-matching error messages. */
@@ -53,6 +57,7 @@ export interface CreateSandboxOptions {
 export interface TemplateRuntimeContract {
   /** Reserved for service-owned system template versions. */
   immutableRef?: string;
+  restoreKind?: "project_only" | "full_rootfs";
   startCommand?: string;
   readinessPort?: number;
   readinessPath?: string;
@@ -64,7 +69,7 @@ export interface Sandbox {
   exec(command: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
   shell(script: string, options?: ExecOptions): Promise<ExecResult>;
   writeFiles(files: Array<{ path: string; content: Uint8Array | string; mode?: number }>): Promise<void>;
-  snapshot(): Promise<Snapshot>;
+  snapshot(options?: SnapshotOptions): Promise<Snapshot>;
   stop(): Promise<void>;
 }
 
@@ -156,7 +161,7 @@ export class SandboxClient {
           mode: file.mode,
         })));
       },
-      snapshot: () => this.request("POST", `/v1/sandboxes/${id}/snapshot`),
+      snapshot: (options = {}) => this.request("POST", `/v1/sandboxes/${id}/snapshot`, options),
       stop: () => this.request("DELETE", `/v1/sandboxes/${id}`),
     };
   }

package/src/templates.test.ts

@@ -28,7 +28,7 @@ function fakeSandbox(): Sandbox & { writeBatches: Array<Array<{ path: string; co
 
 describe("sandbox templates", () => {
   test("defines a typed, immutable versioned template", () => {
-    const template = defineTemplate({ id: "angel-lfg", version: "12", title: "Angel", install: [apt.packages(["tmux"])], checks: [check.command("tmux")] });
+    const template = defineTemplate({ id: "angel-lfg", version: "12", title: "Angel", restoreKind: "full_rootfs", install: [apt.packages(["tmux"])], checks: [check.command("tmux")] });
     expect(templateVersionRef(template)).toBe("angel-lfg-v12");
     expect(Object.isFrozen(template)).toBe(true);
   });
@@ -44,6 +44,9 @@ describe("sandbox templates", () => {
     const script = compileStartScript({ command: "bun start", user: "user", readiness: { port: 8766 } });
     expect(script).toContain("/home/user/.omg/template/start.pid");
     expect(script).toContain("http://127.0.0.1:8766/");
+    expect(script).toContain("grep -Fxq 'omg-template-supervisor'");
+    expect(script).toContain("nohup /bin/bash -lc");
+    expect(script).not.toContain(`kill -0 "$(cat "$pidfile")" 2>/dev/null; then exit 0`);
     expect(() => compileStep(run({ command: "true", env: { "BAD-NAME": "x" } }))).toThrow("invalid environment variable");
   });
 
@@ -62,6 +65,7 @@ describe("sandbox templates", () => {
       id: "files-fixture",
       version: "1",
       title: "files fixture",
+      restoreKind: "full_rootfs",
       install: [files.copy({ sourceDir: FIXTURE_DIR, destination: "/home/user/app/" })],
     });
     await applyTemplate(sandbox, definition);
@@ -82,6 +86,7 @@ describe("sandbox templates", () => {
       id: "empty-fixture",
       version: "1",
       title: "empty fixture",
+      restoreKind: "full_rootfs",
       install: [files.copy({ sourceDir: join(FIXTURE_DIR, "nested", "does-not-exist"), destination: "/home/user/app" })],
     });
     await expect(applyTemplate(sandbox, definition)).rejects.toThrow();
@@ -110,6 +115,7 @@ describe("sandbox templates", () => {
       id: "async-install",
       version: "1",
       title: "async install",
+      restoreKind: "full_rootfs",
       install: [run({ command: "sleep 120 && echo installed" })],
     }));
 
@@ -135,24 +141,37 @@ describe("sandbox templates", () => {
       id: "async-failure",
       version: "1",
       title: "async failure",
+      restoreKind: "full_rootfs",
       install: [run({ command: "exit 42" })],
     }))).rejects.toThrow("package exploded");
   });
 
   test("LFG owns every runtime dependency and zero-config transport default", () => {
     const lfg = agentTemplates.lfg;
-    expect(templateVersionRef(lfg)).toBe("agent-lfg-v17");
+    expect(templateVersionRef(lfg)).toBe("agent-lfg-v33");
     expect(lfg.install).toContainEqual(apt.packages(["tmux"]));
     expect(lfg.checks).toContainEqual(check.command("tmux"));
+    expect(lfg.checks).toContainEqual(check.file("/home/user/lfg/omg-start.sh"));
+    expect(lfg.start?.command).toBe("exec /home/user/lfg/omg-start.sh");
     expect(lfg.start?.env?.LIVE_TRANSPORT).toBe("ws");
     expect(lfg.start?.readiness?.port).toBe(8766);
     expect(templateRuntimeContract(lfg, templateVersionRef(lfg))).toEqual({
-      immutableRef: "agent-lfg-v17",
+      immutableRef: "agent-lfg-v33",
+      restoreKind: "full_rootfs",
       startCommand: "exec /home/user/.omg/template/bootstrap.sh",
       readinessPort: 8766,
       readinessPath: "/",
       ports: [8766, 5173],
     });
+
+    const commands = lfg.install
+      .filter((step): step is Extract<typeof step, { kind: "run" }> => step.kind === "run")
+      .map((step) => step.command);
+    const startScript = commands.find((command) => command.includes("OMG_START_EOF"));
+    expect(startScript).toBeDefined();
+    expect(startScript!).toContain("LFG_CONNECT_EVENTS=1");
+    expect(startScript!).toContain("relay-credentials.json");
+    expect(startScript!).toContain("trap cleanup EXIT INT TERM");
   });
 
   test("LFG bakes the react-ts scaffold into /home/user/project at bake time", () => {
@@ -169,6 +188,10 @@ describe("sandbox templates", () => {
       .filter((step): step is Extract<typeof step, { kind: "run" }> => step.kind === "run")
       .map((step) => step.command);
     expect(commands.some((c) => c.includes("recipe.sh"))).toBe(true);
-    expect(lfg.metadata?.lfgRelease).toBe("v0.1.40");
+    expect(lfg.metadata?.lfgRelease).toBe("v0.1.167");
+    const lfgInstall = commands.find((c) => c.includes("bun install --production"));
+    expect(lfgInstall).toBeDefined();
+    expect(lfgInstall!).not.toContain("delete manifest.workspaces");
+    expect(lfgInstall!).not.toContain("rm -f bun.lock bun.lockb");
   });
 });

package/src/templates.ts

@@ -34,6 +34,12 @@ export interface SandboxTemplate {
   version: string;
   title: string;
   description?: string;
+  /**
+   * Declares whether the recipe's complete mutable payload is confined to
+   * /home/user/project. Typed recipes must choose explicitly: the baker cannot
+   * safely infer arbitrary shell-command side effects.
+   */
+  restoreKind: "project_only" | "full_rootfs";
   ports?: readonly number[];
   install: readonly TemplateStep[];
   checks?: readonly TemplateCheck[];
@@ -89,6 +95,9 @@ export function defineTemplate<const T extends SandboxTemplate>(definition: T):
   assertTemplateId(definition.id);
   if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,19}$/.test(definition.version)) throw new Error("invalid template version");
   if (!definition.title.trim()) throw new Error("template title is required");
+  if (definition.restoreKind !== "project_only" && definition.restoreKind !== "full_rootfs") {
+    throw new Error("template restoreKind must be project_only or full_rootfs");
+  }
   for (const port of definition.ports ?? []) {
     if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`invalid template port ${port}`);
   }
@@ -136,6 +145,7 @@ export function templateDefinitionHash(definition: SandboxTemplate): string {
 export function templateRuntimeContract(definition: SandboxTemplate, immutableRef?: string) {
   return {
     immutableRef,
+    restoreKind: definition.restoreKind,
     startCommand: definition.start ? "exec /home/user/.omg/template/bootstrap.sh" : undefined,
     readinessPort: definition.start?.readiness?.port,
     readinessPath: definition.start?.readiness?.path,
@@ -189,6 +199,7 @@ export function compileStep(step: TemplateStep): { script: string; timeoutMs?: n
 export function compileStartScript(start: TemplateStart): string {
   const port = start.readiness?.port;
   const timeout = start.readiness?.timeoutSeconds ?? 60;
+  const supervisorMarker = "omg-template-supervisor";
   const env = { HOME: start.user ? `/home/${start.user}` : "/root", ...(start.env ?? {}) };
   const exports = shellEnvAssignments(env).map((assignment) => `export ${assignment}`).join("\n");
   const command = `${start.cwd ? `cd ${quote(start.cwd)} && ` : ""}${start.command}`;
@@ -196,7 +207,8 @@ export function compileStartScript(start: TemplateStart): string {
   const probe = port
     ? `for _ in $(seq 1 ${timeout}); do curl -fsS -m1 -o /dev/null ${quote(`http://127.0.0.1:${port}${start.readiness?.path ?? "/"}`)} && exit 0; sleep 1; done\necho 'template service did not become ready on :${port}' >&2\nexit 1`
     : "exit 0";
-  return `#!/usr/bin/env bash\nset -euo pipefail\nmkdir -p /home/user/.omg/template\npidfile=/home/user/.omg/template/start.pid\nif [ -s \"$pidfile\" ] && kill -0 \"$(cat \"$pidfile\")\" 2>/dev/null; then exit 0; fi\nnohup /bin/bash -lc ${quote(`while true; do ${foreground} >>/home/user/.omg/template/start.log 2>&1 || true; sleep 2; done`)} >/dev/null 2>&1 &\necho $! > \"$pidfile\"\n${probe}\n`;
+  const supervisor = `while true; do ${foreground} >>/home/user/.omg/template/start.log 2>&1 || true; sleep 2; done`;
+  return `#!/usr/bin/env bash\nset -euo pipefail\nmkdir -p /home/user/.omg/template\npidfile=/home/user/.omg/template/start.pid\npid=\"\"\nif [ -s \"$pidfile\" ]; then pid=\"$(cat \"$pidfile\" 2>/dev/null || true)\"; fi\nsupervisor_alive=false\nif [[ \"$pid\" =~ ^[0-9]+$ ]] && kill -0 \"$pid\" 2>/dev/null && tr '\\0' '\\n' < \"/proc/$pid/cmdline\" 2>/dev/null | grep -Fxq ${quote(supervisorMarker)}; then supervisor_alive=true; fi\nif [ \"$supervisor_alive\" != true ]; then\n  rm -f \"$pidfile\"\n  nohup /bin/bash -lc ${quote(supervisor)} ${quote(supervisorMarker)} >/dev/null 2>&1 &\n  echo $! > \"$pidfile\"\nfi\n${probe}\n`;
 }
 
 async function assertExec(label: string, result: { exitCode: number; stdout: string; stderr: string }): Promise<void> {
@@ -356,7 +368,7 @@ export async function bakeTemplate(
   let snapshotted = false;
   try {
     await applyTemplate(sandbox, definition, log);
-    const snapshot = await sandbox.snapshot();
+    const snapshot = await sandbox.snapshot({ restoreKind: definition.restoreKind });
     snapshotted = true;
     const uploaded = await waitForSnapshotUpload(client, snapshot);
     // The immutable version ref is content-addressed: definition hash + the