bottleship 0.0.1 → 0.1.0-prototype.0

package/dist/src/ui.js

@@ -0,0 +1,127 @@
+// The terminal side of `bottleship init`: the header, prompts, spinners. Only used on a TTY.
+import * as p from "@clack/prompts";
+import { spawnSync } from "node:child_process";
+const color = !process.env.NO_COLOR && process.stdout.isTTY;
+const sgr = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const c = {
+    bold: sgr("1"),
+    dim: sgr("2"),
+    cyan: sgr("36"),
+    green: sgr("32"),
+    red: sgr("31"),
+    yellow: sgr("33"),
+    blue: sgr("34"),
+    white: sgr("97"),
+};
+// a ship in a bottle, with a color mask per line: c glass, y cork and stars, w sails, r hull and flags, b sea
+const ART = [
+    "            .-----------------------------------------------.",
+    "            ccccccccccccccccccccccccccccccccccccccccccccccccc",
+    "           /                                                 \\",
+    "           c                                                 c",
+    " _________/     *             |>          |>                  \\",
+    " cccccccccc     y             wr          wr                  c",
+    "[####|                       /|\\         /|\\          .        |",
+    "yyyyyc                       www         www          y        c",
+    "[####|             .        / | \\       / | \\                  |",
+    "yyyyyc             y        w w w       w w w                  c",
+    "[####|____                 /__|__\\     /__|__\\      *          |",
+    "yyyyyccccc                 wwwwwww     wwwwwww      y          c",
+    "          \\         ~~~~~~\\__o___o___o___o___o__/~~~~~~       /",
+    "          c         bbbbbbrrryrrryrrryrrryrrryrrrbbbbbb       c",
+    "           \\   ~     ~     ~     ~     ~     ~     ~     ~   /",
+    "           c   b     b     b     b     b     b     b     b   c",
+    "            '-----------------------------------------------'",
+    "            ccccccccccccccccccccccccccccccccccccccccccccccccc",
+];
+const paint = { c: c.cyan, y: c.yellow, w: c.white, r: c.red, b: c.blue };
+export function header() {
+    const rows = [];
+    for (let i = 0; i < ART.length; i += 2) {
+        const [text, mask] = [ART[i], ART[i + 1]];
+        rows.push([...text].map((ch, j) => (paint[mask[j]] ?? String)(ch)).join(""));
+    }
+    return `\n${rows.join("\n")}\n\n   ${c.bold("bottleship")}  ${c.dim("coding agents in little boxes, run by your agent")}\n`;
+}
+// soft-wraps each line to width, keeping a list item's hanging indent
+function wrap(text, width) {
+    return text.split("\n").map((line) => {
+        const indent = " ".repeat(line.match(/^\s*(- )?/)[0].length);
+        const out = [];
+        let cur = "";
+        for (const word of line.split(" ")) {
+            if (cur && (cur + " " + word).length > width) {
+                out.push(cur);
+                cur = indent + word;
+            }
+            else
+                cur = cur ? cur + " " + word : word;
+        }
+        return [...out, cur].join("\n");
+    }).join("\n");
+}
+// Ctrl-C at any prompt ends init without writing anything half-done
+function answered(v) {
+    if (p.isCancel(v)) {
+        p.cancel("Setup cancelled, nothing changed.");
+        process.exit(130);
+    }
+    return v;
+}
+export function terminalUI() {
+    let closed = false;
+    return {
+        intro() {
+            process.stdout.write(header() + "\n");
+            p.intro(c.bold(" setup "));
+        },
+        say: (line = "") => p.log.message(line.replace(/^ +/gm, "")),
+        section: (title) => p.log.step(c.bold(title)),
+        ok: (label, detail) => p.log.success(`${label}${detail ? "  " + c.dim(detail) : ""}`),
+        warn: (label, detail) => p.log.warn(`${label}${detail ? "  " + c.dim(detail) : ""}`),
+        note: (title, body) => p.note(wrap(body, Math.min((process.stdout.columns || 80) - 8, 88)), title),
+        async text(question, def) {
+            const v = answered(await p.text({ message: question, placeholder: def, defaultValue: def }));
+            return v.trim() || def || "";
+        },
+        async choose(question, options, def) {
+            return answered(await p.select({ message: question, initialValue: def, options: options.map((o) => ({ value: o.value, label: o.value, hint: o.hint })) }));
+        },
+        async secret(question) {
+            return answered(await p.password({ message: `${question} ${c.dim("(Enter to skip)")}`, mask: "•" })).trim();
+        },
+        async confirm(question) {
+            return answered(await p.confirm({ message: question }));
+        },
+        async handOver(command) {
+            p.log.info(`running ${c.bold(command)}`);
+            return spawnSync("sh", ["-c", command], { stdio: "inherit" }).status;
+        },
+        async step(label, fn) {
+            const s = p.spinner();
+            const t0 = Date.now();
+            const secs = () => c.dim(`${((Date.now() - t0) / 1000).toFixed(1)}s`);
+            s.start(label);
+            try {
+                const v = await fn();
+                s.stop(`${label}  ${secs()}`);
+                return v;
+            }
+            catch (e) {
+                s.stop(`${c.red(label)}  ${secs()}`, 1);
+                throw e;
+            }
+        },
+        fail(message, fix) {
+            p.log.error(`${message}${fix ? "\n" + c.dim(fix) : ""}`);
+            p.outro(c.red("Setup did not finish."));
+            closed = true;
+        },
+        close(message) {
+            if (closed)
+                return;
+            closed = true;
+            p.outro(message ?? "Done.");
+        },
+    };
+}

package/package.json

@@ -1,8 +1,54 @@
 {
   "name": "bottleship",
-  "version": "0.0.1",
-  "description": "Coming soon.",
-  "license": "UNLICENSED",
+  "version": "0.1.0-prototype.0",
+  "description": "Run coding agents in remote sandboxes, like subagents, from your local coding agent.",
+  "license": "MIT",
   "author": "Joshua Knauber",
-  "files": ["README.md"]
+  "type": "module",
+  "bin": {
+    "bottleship": "bin/bottleship"
+  },
+  "files": [
+    "bin",
+    "dist/src",
+    "dist/presets",
+    "presets",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/types.d.ts",
+      "default": "./dist/src/types.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && vitest run",
+    "prepare": "npm run build",
+    "release": "node scripts/release.mjs"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "5.9",
+    "vitest": "^3.2.7"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@daytonaio/sdk": "^0.231.1",
+    "e2b": "^2.63.0",
+    "modal": "^0.11.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joshuaKnauber/bottleship.git"
+  }
 }

package/presets/agents/claude.json

@@ -0,0 +1,12 @@
+{
+  "install": ["command -v claude >/dev/null || npm install -g --silent @anthropic-ai/claude-code"],
+  "run": "claude -p {prompt} --dangerously-skip-permissions",
+  "resume": "claude -p {prompt} --continue --dangerously-skip-permissions",
+  "env": { "IS_SANDBOX": "1" },
+  "unset": ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+  "login": {
+    "routes": ["token"],
+    "use": "token",
+    "token": { "env": "CLAUDE_CODE_OAUTH_TOKEN", "store": "claude", "command": "claude setup-token", "hint": "paste the long-lived token `claude setup-token` prints; it uses your Claude subscription" }
+  }
+}

package/presets/agents/codex.json

@@ -0,0 +1,15 @@
+{
+  "install": ["command -v codex >/dev/null || npm install -g --silent @openai/codex"],
+  "run": "codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -- {prompt}",
+  "resume": "codex exec resume --last --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -- {prompt}",
+  "login": {
+    "routes": ["device", "token"],
+    "use": "device",
+    "device": {
+      "command": "codex login --device-auth",
+      "status": "codex login status",
+      "setup": "in ChatGPT, open Settings, Security and turn on device code login for Codex"
+    },
+    "token": { "env": "CODEX_API_KEY", "store": "openai", "hint": "create an OpenAI API key at https://platform.openai.com/api-keys and paste it; it bills to the API, not your ChatGPT plan" }
+  }
+}

package/presets/agents/cursor.json

@@ -0,0 +1,14 @@
+{
+  "install": ["command -v cursor-agent >/dev/null || { curl -fsS https://cursor.com/install | bash; command -v cursor-agent >/dev/null; }"],
+  "run": "cursor-agent -p --force --trust --sandbox disabled --output-format text -- {prompt}",
+  "resume": "cursor-agent -p --continue --force --trust --sandbox disabled --output-format text -- {prompt}",
+  "login": {
+    "routes": ["token", "device"],
+    "use": "token",
+    "token": { "env": "CURSOR_API_KEY", "store": "cursor", "hint": "create an API key at https://cursor.com/dashboard/api and paste it; it bills to your Cursor plan" },
+    "device": {
+      "command": "NO_OPEN_BROWSER=1 cursor-agent login",
+      "status": "! cursor-agent status 2>&1 | grep -qi 'not logged in'"
+    }
+  }
+}

package/presets/agents/opencode.json

@@ -0,0 +1,19 @@
+{
+  "install": ["command -v opencode >/dev/null || npm install -g --silent @opencode/cli"],
+  "run": "opencode run --standalone --auto -- {prompt}",
+  "resume": "opencode run --standalone --continue --auto -- {prompt}",
+  "login": {
+    "routes": ["none", "device", "token"],
+    "use": "none",
+    "device": {
+      "command": "opencode auth login openai --method chatgpt-headless --standalone",
+      "status": "opencode auth list --standalone --format json | grep -q '\"openai\"'"
+    },
+    "token": { "env": "OPENCODE_API_KEY", "store": "opencode", "hint": "sign in at https://opencode.ai/console, copy your API key (OpenCode Zen) and paste it" },
+    "tokens": [
+      { "env": "OPENCODE_API_KEY", "store": "opencode", "hint": "OpenCode Zen: sign in at https://opencode.ai/console, copy your API key and paste it" },
+      { "env": "ANTHROPIC_API_KEY", "store": "anthropic", "hint": "an Anthropic API key (not a Claude subscription) from https://console.anthropic.com/settings/keys" },
+      { "env": "OPENAI_API_KEY", "store": "openai", "hint": "an OpenAI API key from https://platform.openai.com/api-keys" }
+    ]
+  }
+}

package/presets/providers/command.ts

@@ -0,0 +1,43 @@
+// A provider driven by shell command templates, for sandboxes that have a CLI.
+// Values substituted into a template are shell-quoted: {script}, {id}.
+// {name!} inserts the raw value, for URLs and the like.
+//
+// options:
+//   create:   creates box {id}; may print JSON {"id": ...} or a bare id (else {id} is used)
+//   exec:     runs {script} with bash in box {id}; must pass stdin/stdout through
+//   stream:   (optional) like exec but kept open, binary-clean (no TTY); defaults to exec
+//   destroy:  removes box {id}
+//   status:   (optional) exits 0 if box {id} is running
+//
+// example:
+//   "corp": { "module": "builtin:command",
+//             "create": "corpbox create --name {id}",
+//             "exec": "corpbox ssh {id} -- bash -c {script}",
+//             "destroy": "corpbox rm {id}" }
+import { fill, run, spawnStream } from "./util.ts";
+import type { ProviderFactory, RunOptions } from "../../src/types.ts";
+
+const command: ProviderFactory = ({ options }) => {
+  for (const k of ["create", "exec", "destroy"]) if (!options[k]) throw new Error(`command provider: missing "${k}" template`);
+  const sh = (tpl: string, values: Record<string, unknown>, opts?: RunOptions) => run("sh", ["-c", fill(tpl, values)], opts);
+
+  return {
+    async create({ id }) {
+      const out = (await sh(options.create, { id })).stdout.trim();
+      try {
+        return { id: JSON.parse(out).id ?? id };
+      } catch {
+        return { id: out && !/\s/.test(out) ? out : id };
+      }
+    },
+
+    exec: (id, script, { stdin } = {}) => sh(options.exec, { id, script }, { stdin, check: false }),
+
+    openStream: (id, script) => spawnStream("sh", ["-c", fill(options.stream ?? options.exec, { id, script })]),
+
+    ...(options.status && { status: async (id: string) => ((await sh(options.status, { id }, { check: false })).code === 0 ? "running" : "gone") }),
+
+    destroy: (id) => sh(options.destroy, { id }, { check: false }),
+  };
+};
+export default command;

package/presets/providers/daytona.ts

@@ -0,0 +1,181 @@
+// Daytona sandboxes through @daytonaio/sdk. A box is a sandbox; its id is the sandbox id.
+//
+// options: {
+//   apiKey (secret source, e.g. { "store": "daytona" }), apiUrl?, target? (region),
+//   snapshot? (default: Daytona's default snapshot, user "daytona" with bash, git, curl and a writable $HOME),
+//   image? (any registry image instead of a snapshot; it needs bash, git, curl, base64 and a writable $HOME),
+//   autoStopMinutes? (default 0 = never)
+// }
+//
+// template() builds a Daytona snapshot from the Dockerfile, in the organization's default region or `target`; COPY from a local context does not work since spec Dockerfiles have none.
+import { randomBytes } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PassThrough, Writable } from "node:stream";
+import { shq } from "./util.ts";
+import type { Sandbox } from "@daytonaio/sdk";
+import type { BoxStream, ExecResult, ProviderFactory } from "../../src/types.ts";
+
+const GONE = new Set(["destroyed", "destroying", "error", "build_failed"]);
+const RESTARTABLE = new Set(["stopped", "archived", "paused"]);
+const hex = () => randomBytes(6).toString("hex");
+const SNAPSHOT_BUSY = new Set(["pending", "building", "pulling", "snapshotting", "removing"]);
+
+const daytona: ProviderFactory = async ({ options, secret, log }) => {
+  if (!options.apiKey) throw new Error('daytona needs an apiKey option, e.g. "apiKey": { "store": "daytona" }');
+  // loaded here so other providers never pay for the SDK
+  const { Daytona, DaytonaNotFoundError, Image } = await import("@daytonaio/sdk");
+  const client = new Daytona({ apiKey: secret(options.apiKey), apiUrl: options.apiUrl, target: options.target });
+  // ponytail: never auto-stops, because Daytona counts a running agent as idle and would stop it mid-task; idle boxes bill until `bottleship rm`. Set autoStopMinutes to cap that, a stopped box restarts on the next exec but its agent is gone
+  const autoStopInterval: number = options.autoStopMinutes ?? 0;
+
+  const cache = new Map<string, Sandbox>();
+  const lookup = async (id: string): Promise<Sandbox | undefined> => {
+    try {
+      const sb = await client.get(id);
+      cache.set(id, sb);
+      return sb;
+    } catch (e) {
+      if (e instanceof DaytonaNotFoundError) return undefined;
+      throw e;
+    }
+  };
+
+  // a sandbox that can run commands, started again if it was stopped or archived
+  async function started(id: string): Promise<Sandbox> {
+    const cached = cache.get(id);
+    if (cached?.state === "started") return cached;
+    const sb = await lookup(id);
+    if (!sb || GONE.has(sb.state ?? "")) throw new Error(`daytona sandbox ${id} is gone`);
+    if (RESTARTABLE.has(sb.state ?? "")) await sb.start(600);
+    else await sb.waitUntilStarted(600);
+    return sb;
+  }
+
+  // drops the cached sandbox on failure, so the next call looks its state up again
+  async function withBox<T>(id: string, fn: (sb: Sandbox) => Promise<T>): Promise<T> {
+    try {
+      return await fn(await started(id));
+    } catch (e) {
+      cache.delete(id);
+      throw e;
+    }
+  }
+
+  // the snapshot's state, or undefined once there is none by that name
+  const snapshotState = (name: string) =>
+    client.snapshot.get(name).then((s) => s.state as string, (e) => {
+      if (e instanceof DaytonaNotFoundError) return undefined;
+      throw e;
+    });
+
+  // ponytail: a snapshot another init is still building is polled for at most 30 minutes; raise it if agent installs get that slow
+  async function settled(name: string): Promise<string | undefined> {
+    for (let i = 0; i < 900; i++) {
+      const state = await snapshotState(name);
+      if (!state || !SNAPSHOT_BUSY.has(state)) return state;
+      await new Promise((res) => setTimeout(res, 2000));
+    }
+    throw new Error(`daytona snapshot ${name} is still not active after 30 minutes`);
+  }
+
+  return {
+    // snapshots belong to the organization, so a name cannot resolve to another organization's snapshot
+    async template({ name, dockerfile }) {
+      let state = await settled(name);
+      // Daytona deactivates a snapshot after 2 weeks without use
+      if (state === "inactive") {
+        await client.snapshot.activate(name);
+        state = await settled(name);
+      }
+      if (state === "active") return name;
+      // a failed build keeps its name taken, so it goes before the rebuild
+      if (state) {
+        await client.snapshot.delete(name);
+        await settled(name);
+      }
+      // the SDK reads a Dockerfile only from disk
+      const dir = mkdtempSync(join(tmpdir(), "bottleship-daytona-"));
+      try {
+        writeFileSync(join(dir, "Dockerfile"), dockerfile);
+        await client.snapshot.create({ name, image: Image.fromDockerfile(join(dir, "Dockerfile")) }, { onLogs: (l) => log(l) });
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+      return name;
+    },
+
+    async create({ id, template }) {
+      const base = { name: id, labels: { bottleship: "1" }, autoStopInterval };
+      const sb = options.image && !template
+        ? await client.create({ ...base, image: options.image }, { timeout: 600 })
+        : await client.create({ ...base, snapshot: template ?? options.snapshot }, { timeout: 300 });
+      cache.set(sb.id, sb);
+      return { id: sb.id };
+    },
+
+    // the one-shot API merges stdout and stderr and takes no stdin, so stdin goes up as a file and both outputs come back base64'd
+    exec: (id, script, { stdin } = {}) =>
+      withBox(id, async (sb): Promise<ExecResult> => {
+        // a fresh 0700 dir, since stdin carries secrets (env.sh) and output may too
+        const d = `/tmp/bottleship-${hex()}`;
+        if (stdin !== undefined) {
+          await sb.fs.createFolder(d, "700");
+          await sb.fs.uploadFile(Buffer.from(stdin), `${d}/in`);
+        }
+        const r = await sb.process.executeCommand(
+          `${stdin !== undefined ? "" : `mkdir -m 700 ${d} || exit 1; `}bash -c ${shq(script)} < ${stdin !== undefined ? `${d}/in` : "/dev/null"} > ${d}/out 2> ${d}/err; echo $?; base64 < ${d}/out | tr -d '\\n'; echo; base64 < ${d}/err | tr -d '\\n'; echo; rm -rf ${d}`,
+        );
+        const [code, out, err] = r.result.split("\n");
+        if (r.exitCode !== 0 || !/^\d+$/.test(code ?? "")) throw new Error(`daytona exec in ${id} failed (exit ${r.exitCode}): ${r.result.slice(-500)}`);
+        return { code: Number(code), stdout: Buffer.from(out ?? "", "base64").toString(), stderr: Buffer.from(err ?? "", "base64").toString() };
+      }),
+
+    // a session command: stdin goes as base64 lines decoded in the box, so it stays binary-clean and "." ends it
+    // ponytail: Daytona relays output line by line as UTF-8 text, so a partial line shows once it ends and binary output is mangled; a PTY or a raw socket would fix that
+    openStream: (id, script) =>
+      withBox(id, async (sb): Promise<BoxStream> => {
+        const session = `bottleship-${hex()}`;
+        await sb.process.createSession(session);
+        const wrapper = `exec 3< <(while IFS= read -r l; do [ "$l" = . ] && break; printf %s "$l" | base64 -d; done)
+bash -c ${shq(script)} <&3; c=$?; kill $! 2>/dev/null; exit $c`;
+        const { cmdId } = await sb.process.executeSessionCommand(session, { command: `bash -c ${shq(wrapper)}`, runAsync: true, suppressInputEcho: true });
+        const send = (line: string) => sb.process.sendSessionCommandInput(session, cmdId!, line).catch(() => {});
+
+        const stdout = new PassThrough();
+        const stderr = new PassThrough();
+        const closers: ((code?: number | null) => void)[] = [];
+        const end = () => sb.process.deleteSession(session).catch(() => {});
+        const stdin = new Writable({
+          write: (chunk: Buffer, _enc, cb) => void send(chunk.toString("base64") + "\n").then(() => cb()),
+          final: (cb) => void send(".\n").then(() => cb()),
+        });
+
+        sb.process
+          .getSessionCommandLogs(session, cmdId!, (s) => stdout.write(s), (s) => stderr.write(s))
+          .catch(() => {})
+          .then(() => sb.process.getSessionCommand(session, cmdId!).then((c) => c.exitCode ?? null, () => null))
+          .then((code) => {
+            stdout.end();
+            stderr.end();
+            closers.forEach((cb) => cb(code));
+            void end();
+          });
+        return { stdin, stdout, stderr, close: () => void end(), onClose: (cb) => closers.push(cb) };
+      }),
+
+    // a stopped or archived sandbox still counts as running, since exec starts it again
+    async status(id) {
+      const sb = await lookup(id);
+      return sb && !GONE.has(sb.state ?? "") ? "running" : "gone";
+    },
+
+    async destroy(id) {
+      const sb = await lookup(id);
+      cache.delete(id);
+      if (sb && !GONE.has(sb.state ?? "")) await sb.delete(120);
+    },
+  };
+};
+export default daytona;

package/presets/providers/docker.ts

@@ -0,0 +1,38 @@
+// Local Docker as a provider. Boxes are containers that live until `bottleship rm`.
+// The template is a local image tagged with its spec name, running as its own non-root user box.
+//
+// options: { image? (used without a template; default exeuntu, a dev image with git, curl and a non-root user), user? }
+import { run, spawnStream } from "./util.ts";
+import type { ProviderFactory } from "../../src/types.ts";
+
+const docker: ProviderFactory = ({ options }) => {
+  const image: string = options.image ?? "ghcr.io/boldsoftware/exeuntu:latest";
+  const user: string | undefined = options.user ?? (image.includes("exeuntu") ? "exedev" : undefined);
+  // execs run as the container's user, set at create
+  const execArgs = (id: string, script: string) => ["exec", "-i", id, "bash", "-c", script];
+
+  return {
+    async template({ name, dockerfile }) {
+      if ((await run("docker", ["image", "inspect", name], { check: false })).code !== 0) await run("docker", ["build", "-q", "-t", name, "-"], { stdin: dockerfile });
+      return name;
+    },
+
+    async create({ id, template }) {
+      const from = template ? [template] : [...(user ? ["--user", user] : []), image];
+      await run("docker", ["run", "-d", "--name", id, "--label", "bottleship=1", "--entrypoint", "sleep", ...from, "infinity"]);
+      return { id };
+    },
+
+    exec: (id, script, { stdin } = {}) => run("docker", execArgs(id, script), { stdin, check: false }),
+
+    openStream: (id, script) => spawnStream("docker", execArgs(id, script)),
+
+    async status(id) {
+      const r = await run("docker", ["inspect", "-f", "{{.State.Running}}", id], { check: false });
+      return r.code === 0 && r.stdout.trim() === "true" ? "running" : "gone";
+    },
+
+    destroy: (id) => run("docker", ["rm", "-f", id], { check: false }),
+  };
+};
+export default docker;

package/presets/providers/e2b.ts

@@ -0,0 +1,130 @@
+// E2B: Firecracker sandboxes over the e2b SDK. The default "base" template is Debian with bash, git, curl,
+// node and gh, run as a user with a writable $HOME.
+//
+// template() builds an E2B template from the Dockerfile; the E2B builder ignores SHELL, and COPY or ADD from a local context does not work since spec Dockerfiles have none.
+//
+// options: { apiKey? (secret source, else E2B_API_KEY), template? (default "base"), timeoutMinutes? (default 60) }
+import { PassThrough, Writable } from "node:stream";
+import type { BoxStream, ExecResult, ProviderFactory } from "../../src/types.ts";
+import type { CommandResult, Sandbox as SandboxT } from "e2b";
+
+const e2b: ProviderFactory = async ({ options, secret, log }) => {
+  const { Sandbox, Template, ApiClient, ConnectionConfig, CommandExitError, NotFoundError } = await import("e2b");
+  const apiKey: string | undefined = options.apiKey ? secret(options.apiKey) : undefined;
+  // ponytail: a box dies this long after bottleship last touched it, and E2B caps a box's whole life at 1h (Hobby) or 24h (Pro); pause/resume lifecycle if agents run longer
+  const timeoutMs = (options.timeoutMinutes ?? 60) * 60_000;
+
+  // connecting also extends the box's timeout, so every exec and status keeps a box someone checks on alive
+  const boxes = new Map<string, { sbx: SandboxT; at: number }>();
+  async function box(id: string): Promise<SandboxT> {
+    const hit = boxes.get(id);
+    if (hit && Date.now() - hit.at < 60_000) return hit.sbx;
+    const sbx = await Sandbox.connect(id, { apiKey, timeoutMs });
+    boxes.set(id, { sbx, at: Date.now() });
+    return sbx;
+  }
+
+  const result = (r: CommandResult): ExecResult => ({ code: r.exitCode, stdout: r.stdout, stderr: r.stderr });
+  // a non-zero exit is a result, not an error
+  const settle = (p: Promise<CommandResult>) => p.then(result, (e) => {
+    if (e instanceof CommandExitError) return result(e);
+    throw e;
+  });
+
+  // the id of this team's template named name with a finished build; a bare name can also resolve to another team's public template, so names are never handed to create
+  async function ownTemplate(name: string): Promise<string | undefined> {
+    const { api } = new ApiClient(new ConnectionConfig({ apiKey }));
+    let nextToken: string | undefined;
+    do {
+      const res = await api.GET("/v2/templates", { params: { query: { limit: 100, nextToken } } });
+      if (!res.data) throw new Error(`e2b could not list templates: ${res.response.status} ${JSON.stringify(res.error)}`);
+      const hit = res.data.find((t) => !t.isDefault && t.buildStatus === "ready" && t.names.some((n) => n === name || n.endsWith(`/${name}`)));
+      if (hit) return hit.templateID;
+      nextToken = res.response.headers.get("X-Next-Token") || undefined;
+    } while (nextToken);
+  }
+
+  return {
+    // ponytail: two inits racing on one name both build, E2B keeps the later build; fine since both come from the same Dockerfile
+    async template({ name, dockerfile }) {
+      const found = await ownTemplate(name);
+      if (found) return found;
+      const built = await Template.build(Template().fromDockerfile(dockerfile), name, { apiKey, onBuildLogs: (e) => log(String(e)) });
+      return built.templateId;
+    },
+
+    // the bottleship id goes into metadata; E2B picks the sandbox id
+    async create({ id, template }) {
+      const sbx = await Sandbox.create(template ?? options.template ?? "base", { apiKey, timeoutMs, metadata: { bottleship: id } });
+      await sbx.commands.run("true");
+      boxes.set(sbx.sandboxId, { sbx, at: Date.now() });
+      return { id: sbx.sandboxId };
+    },
+
+    // the SDK runs `bash -l -c <script>`; timeoutMs 0 lifts its 60 second command limit
+    async exec(id, script, { stdin } = {}) {
+      const sbx = await box(id);
+      if (stdin === undefined) return settle(sbx.commands.run(script, { timeoutMs: 0 }));
+      const h = await sbx.commands.run(script, { background: true, stdin: true, timeoutMs: 0 });
+      if (stdin.length) await h.sendStdin(stdin);
+      await h.closeStdin();
+      return settle(h.wait());
+    },
+
+    // ponytail: the SDK hands output over as UTF-8 text, so binary stdout gets mangled; fine for text protocols
+    async openStream(id, script): Promise<BoxStream> {
+      const sbx = await box(id);
+      const stdout = new PassThrough();
+      const stderr = new PassThrough();
+      const h = await sbx.commands.run(script, {
+        background: true,
+        stdin: true,
+        timeoutMs: 0,
+        onStdout: (d) => void stdout.write(d),
+        onStderr: (d) => void stderr.write(d),
+      });
+      let code: number | null | undefined;
+      const closers: ((code?: number | null) => void)[] = [];
+      const done = h.wait().then(
+        (r) => r.exitCode,
+        (e) => (e instanceof CommandExitError ? e.exitCode : null),
+      );
+      void done.then((c) => {
+        code = c;
+        stdout.end();
+        stderr.end();
+        closers.splice(0).forEach((cb) => cb(c));
+      });
+      // Writable runs one write at a time, so stdin arrives in order
+      const stdin = new Writable({
+        write: (chunk: Buffer, _enc, cb) => void h.sendStdin(chunk).then(() => cb(), cb),
+        final: (cb) => void h.closeStdin().then(() => cb(), cb),
+      });
+      stdin.on("error", () => {});
+      return {
+        stdin,
+        stdout,
+        stderr,
+        close: () => void h.kill().catch(() => {}),
+        onClose: (cb) => (code === undefined ? closers.push(cb) : cb(code)),
+      };
+    },
+
+    async status(id) {
+      boxes.delete(id);
+      try {
+        await box(id);
+        return "running";
+      } catch (e) {
+        if (e instanceof NotFoundError) return "gone";
+        throw e;
+      }
+    },
+
+    async destroy(id) {
+      boxes.delete(id);
+      return Sandbox.kill(id, { apiKey });
+    },
+  };
+};
+export default e2b;