@agentswf/sandbox 0.0.0-stage → 0.1.0-beta.1

package/docker/Dockerfile

@@ -0,0 +1,45 @@
+# The docker provider's default image (story 004): node 22 for pi, the proxy and the door's relay,
+# bun for the bundled wf, git, the four harnesses, and Herdr. Its tag is a hash of this file, so
+# every input is pinned here: a change to one is a new image, not a stale one under the old tag.
+# The proxy and the relay are run from their sources beside this file, not copied in.
+ARG BUN_VERSION=1.4.0
+FROM oven/bun:${BUN_VERSION}-debian AS bun
+
+FROM node:22.20.0-bookworm-slim
+ARG CLAUDE_CODE_VERSION=2.1.283
+ARG CODEX_VERSION=0.159.3
+ARG PI_VERSION=0.87.1
+COPY --from=bun /usr/local/bin/bun /usr/local/bin/bun
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates git curl procps zsh \
+    && rm -rf /var/lib/apt/lists/*
+# The Herdr the adapter drives (`HERDR_VERSION` in its herdr.ts), by release and checksum: a box
+# whose Herdr differs is refused panes. The checksums are this release's; a new one needs its own.
+ENV HERDR_VERSION=0.9.1
+ARG TARGETARCH
+RUN case "${TARGETARCH}" in \
+      amd64) arch=x86_64; sum=2a02fed16beb651ef006e1d43f048f652ca4dc58ad053cd2d44450563d5c54b7 ;; \
+      arm64) arch=aarch64; sum=f4ccf4de745f2cb9a39a983e9ba3703dad50ec2a58dea83026ceab721bbd8d9e ;; \
+      *) echo "no Herdr for ${TARGETARCH}" >&2; exit 1 ;; \
+    esac \
+    && curl -fsSL -o /usr/local/bin/herdr \
+      "https://github.com/herdrdev/herdr/releases/download/v${HERDR_VERSION}/herdr-linux-${arch}" \
+    && echo "${sum}  /usr/local/bin/herdr" | sha256sum -c - \
+    && chmod 755 /usr/local/bin/herdr
+# cursor-agent, a release directory holding its own node, by version and checksum, as Herdr is.
+ARG CURSOR_AGENT_VERSION=2026.10.01-14929f9
+RUN case "${TARGETARCH}" in \
+      amd64) arch=x64; sum=ba9a855f8f813c91b9f2707127572d2dc9ae5a62818e1c36719625d0fb8bd452 ;; \
+      arm64) arch=arm64; sum=c31ef0ba6b827fdf8053919de57abae4a7bd71afefdf2cab061e276faac42b3a ;; \
+      *) echo "no cursor-agent for ${TARGETARCH}" >&2; exit 1 ;; \
+    esac \
+    && curl -fsSL -o /tmp/cursor-agent.tgz \
+      "https://downloads.cursor.com/lab/${CURSOR_AGENT_VERSION}/linux/${arch}/agent-cli-package.tar.gz" \
+    && echo "${sum}  /tmp/cursor-agent.tgz" | sha256sum -c - \
+    && mkdir -p /opt/cursor-agent \
+    && tar --strip-components=1 -xzf /tmp/cursor-agent.tgz -C /opt/cursor-agent \
+    && rm /tmp/cursor-agent.tgz \
+    && ln -s /opt/cursor-agent/cursor-agent /usr/local/bin/cursor-agent
+ENV SHELL=/bin/bash
+RUN npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" "@openai/codex@${CODEX_VERSION}" \
+      "@earendil-works/pi-coding-agent@${PI_VERSION}" \
+    && npm cache clean --force

package/docker/proxy.js

@@ -0,0 +1,45 @@
+// A CONNECT-only filtering proxy, run by `node -e` in a sandbox's proxy container (story 004, X8).
+// The allowlist file is re-read on every request, so it grows as agents are admitted. Domain
+// grammar: exact host, or `*.` and a name for its subdomains only. An address is never allowed.
+const net = require("node:net"),
+  http = require("node:http"),
+  fs = require("node:fs");
+const [list, port] = [process.argv[1], Number(process.argv[2] || 3128)];
+// The sandbox's internal network is its first: listening there alone keeps other containers on
+// the default bridge, which it joins later, from borrowing it.
+const internal = Object.values(require("node:os").networkInterfaces())
+  .flat()
+  .find((address) => address && address.family === "IPv4" && !address.internal);
+const allowed = (host) =>
+  fs
+    .readFileSync(list, "utf8")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .some((d) => (d.startsWith("*.") ? host.endsWith(d.slice(1)) : host === d));
+const server = http.createServer((req, res) => {
+  console.log("deny plain", req.url);
+  res.writeHead(403).end();
+});
+server.on("connect", (req, client, head) => {
+  const [raw, p] = req.url.split(":");
+  const host = raw.toLowerCase().replace(/\.$/, "");
+  // A client that resets a refused connection must not take the proxy down with it.
+  client.on("error", () => {});
+  // TLS on 443 only: an allowed name's other ports are not what was allowed.
+  if (net.isIP(host) || Number(p || 443) !== 443 || !allowed(host)) {
+    console.log("deny", req.url);
+    client.end("HTTP/1.1 403 Forbidden\r\n\r\n");
+    return;
+  }
+  console.log("allow", req.url);
+  const up = net.connect(Number(p || 443), host, () => {
+    client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+    up.write(head);
+    up.pipe(client);
+    client.pipe(up);
+  });
+  up.on("error", () => client.destroy());
+  client.on("error", () => up.destroy());
+});
+server.listen(port, internal ? internal.address : "0.0.0.0");

package/docker/relay.js

@@ -0,0 +1,36 @@
+// The door's half in a box (story 004, X6): listen at the door's path; each connection's request
+// goes out on stdout as one line {id, b64}, and its reply comes back on stdin the same way. The
+// socket is the agent's to connect to, so it is made connectable by any uid in the box.
+const net = require("node:net"),
+  fs = require("node:fs");
+const path = process.argv[1];
+try {
+  fs.unlinkSync(path);
+} catch {}
+const open = new Map();
+let next = 0;
+net
+  .createServer({ allowHalfOpen: true }, (c) => {
+    const id = next++,
+      chunks = [];
+    open.set(id, c);
+    c.on("data", (d) => chunks.push(d));
+    c.on("end", () =>
+      process.stdout.write(
+        `${JSON.stringify({ id, b64: Buffer.concat(chunks).toString("base64") })}\n`,
+      ),
+    );
+    c.on("error", () => open.delete(id));
+  })
+  .listen(path, () => {
+    fs.chmodSync(path, 0o666);
+    process.stderr.write("ready\n");
+  });
+const lines = require("node:readline").createInterface({ input: process.stdin });
+lines.on("line", (line) => {
+  const { id, b64 } = JSON.parse(line);
+  const c = open.get(id);
+  open.delete(id);
+  c?.end(Buffer.from(b64, "base64"));
+});
+lines.on("close", () => process.exit(0));

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@agentswf/sandbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "description": "agents.wf: the sandboxes a workflow opens, and their providers",
+  "license": "MIT",
+  "homepage": "https://github.com/romanlv/agentswf",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/romanlv/agentswf.git",
+    "directory": "packages/sandbox"
+  },
+  "type": "module",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./testing": "./src/testing/index.ts",
+    "./testing/fake": "./src/testing/fake.ts",
+    "./srt": "./src/srt/index.ts",
+    "./docker": "./src/docker/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.eval.ts",
+    "!src/**/fixtures",
+    "docker"
+  ],
+  "dependencies": {
+    "@agentswf/contract": "0.1.0-beta.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/docker/args.ts

@@ -0,0 +1,65 @@
+import { RECORD_LEADER } from "../groups";
+import { writableIn } from "../resolve";
+import type { ResolvedSandbox } from "../seam";
+
+/**
+ * The box's mounts, at the host's paths: the working directory and `read` read-only, `write`
+ * writable, `homes/` and `quarantine/`, the gitdirs, read-only unless writable, and an empty tmpfs
+ * over each `hidden` path. The most specific path decides, so mounts go shortest first and a
+ * nested one lies over its parent. `guarded` names the protected gitdir paths that exist, each
+ * mounted read-only over a writable gitdir. `--mount`, not `-v`, which would make a missing source
+ * as root rather than refuse it.
+ */
+export function mountArgs(
+  spec: ResolvedSandbox<unknown>,
+  directory: string,
+  guarded: readonly string[],
+): string[] {
+  const mounts = new Map<string, boolean | "empty">();
+  for (const path of [spec.cwd, ...spec.read, ...spec.write]) {
+    mounts.set(path, !writableIn(spec, path));
+  }
+  for (const gitdir of spec.gitdirs) {
+    if (!mounts.has(gitdir.path)) mounts.set(gitdir.path, !gitdir.writable);
+  }
+  for (const path of guarded) mounts.set(path, true);
+  mounts.set(`${directory}/homes`, false);
+  mounts.set(`${directory}/quarantine`, false);
+  for (const path of spec.hidden) mounts.set(path, "empty");
+  return [...mounts]
+    .sort(([a], [b]) => a.length - b.length || a.localeCompare(b))
+    .flatMap(([path, readOnly]) => {
+      if (path.includes(",")) throw new Error(`docker: cannot mount ${path}, which holds a comma`);
+      if (readOnly === "empty") return ["--mount", `type=tmpfs,target=${path}`];
+      return ["--mount", `type=bind,source=${path},target=${path}${readOnly ? ",readonly" : ""}`];
+    });
+}
+
+/**
+ * The `docker exec` that runs `argv` for an agent: in its working directory, recording its pid in
+ * `pidFile` (the exec'd process leads its own group, as runc makes it a session leader), with its
+ * variables set by `-e`. A secret passes by name alone, its value in the client's environment, so
+ * it never shows in the host's `ps`.
+ */
+export function execArgs(options: {
+  box: string;
+  cwd: string | undefined;
+  env: Readonly<Record<string, string>>;
+  secrets: readonly string[];
+  pidFile: string;
+  argv: readonly string[];
+}): string[] {
+  return [
+    "exec",
+    "-i",
+    ...(options.cwd ? ["-w", options.cwd] : []),
+    ...Object.entries(options.env).flatMap(([name, value]) => ["-e", `${name}=${value}`]),
+    ...options.secrets.flatMap((name) => ["-e", name]),
+    options.box,
+    "sh",
+    "-c",
+    RECORD_LEADER,
+    options.pidFile,
+    ...options.argv,
+  ];
+}