agenttwin 0.1.0 → 0.2.0

package/dist/api.js

@@ -0,0 +1,659 @@
+#!/usr/bin/env node
+
+// src/runtime/gateway.ts
+import { createServer } from "http";
+import { createHash as createHash2, randomBytes as randomBytes2, randomUUID as randomUUID2, timingSafeEqual } from "crypto";
+import { mkdir as mkdir2, readFile as readFile4, writeFile as writeFile2, rename, mkdtemp as mkdtemp2, rm as rm2 } from "fs/promises";
+import { resolve as resolve2, join as join4, dirname as dirname2, extname } from "path";
+import { tmpdir as tmpdir2 } from "os";
+
+// src/runtime/spec.ts
+var object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var namePattern = /^[a-z][a-z0-9_]{0,39}$/;
+function parseWorld(value) {
+  const invalid = (message) => {
+    throw new Error(`Invalid world: ${message}`);
+  };
+  if (!object(value) || value.schema !== "agenttwin/world-v1") invalid("schema must be agenttwin/world-v1");
+  const v = value;
+  if (typeof v.name !== "string" || !namePattern.test(v.name)) invalid("name must be lowercase letters, digits or underscores");
+  if (!Array.isArray(v.files) || !v.files.length || v.files.length > 100 || !v.files.every((f) => typeof f === "string" && f.length > 0)) invalid("files must explicitly list 1\u2013100 application files");
+  if (new Set(v.files).size !== v.files.length) invalid("files must be unique");
+  if (!Array.isArray(v.command) || !v.command.length || !v.command.every((c) => typeof c === "string" && c.length > 0) || v.command[0] !== "node") invalid("command must be an argv array starting with node; supply a bundled Node application");
+  if (!Number.isInteger(v.timeoutSeconds) || Number(v.timeoutSeconds) < 1 || Number(v.timeoutSeconds) > 300) invalid("timeoutSeconds must be 1\u2013300");
+  if (v.workflowId !== void 0 && (typeof v.workflowId !== "string" || !v.workflowId)) invalid("workflowId must be a nonempty string");
+  if (!Array.isArray(v.services) || !v.services.length || v.services.length > 10) invalid("services must contain 1\u201310 HTTP services");
+  const services = /* @__PURE__ */ new Map();
+  for (const service of v.services) {
+    if (!object(service) || typeof service.name !== "string" || !namePattern.test(service.name) || services.has(service.name)) invalid("service names must be unique lowercase identifiers");
+    const item = service;
+    if (!Array.isArray(item.collections) || !item.collections.length || item.collections.length > 20) invalid("each service needs 1\u201320 collections");
+    if (item.adapter !== void 0 && !["json-collection", "slack"].includes(String(item.adapter))) invalid("unsupported service adapter");
+    const paths = /* @__PURE__ */ new Set();
+    for (const entry of item.collections) {
+      if (!object(entry) || typeof entry.path !== "string" || !/^\/[a-zA-Z0-9_/-]+$/.test(entry.path) || entry.path.includes("//") || paths.has(entry.path)) invalid("collection paths must be unique absolute HTTP paths");
+      const collection = entry;
+      if (!Array.isArray(collection.seed) || collection.seed.length > 1e3 || !collection.seed.every(object)) invalid("seed must be an array of up to 1000 JSON records");
+      paths.add(collection.path);
+    }
+    if (item.adapter === "slack" && (!paths.has("/messages") || !paths.has("/channels") || paths.size !== 2)) invalid("slack adapter requires /messages and /channels collections");
+    services.set(item.name, paths);
+  }
+  const known = (entry) => typeof entry.service === "string" && typeof entry.path === "string" && services.get(entry.service)?.has(entry.path);
+  if (!Array.isArray(v.assertions) || !v.assertions.length || v.assertions.length > 100) invalid("at least one final-state assertion is required (maximum 100)");
+  for (const assertion of v.assertions) {
+    if (!object(assertion) || !known(assertion) || !Number.isSafeInteger(assertion.count) || Number(assertion.count) < 0 || assertion.where !== void 0 && !object(assertion.where)) invalid("assertions need an existing service/path, nonnegative count, and optional where object");
+  }
+  if (v.postgres !== void 0) {
+    if (!object(v.postgres) || v.postgres.seedFile !== void 0 && !v.files.includes(String(v.postgres.seedFile)) || !Array.isArray(v.postgres.assertions) || !v.postgres.assertions.length || v.postgres.assertions.length > 100) invalid("postgres requires assertions and seedFile must be listed in files");
+    for (const a of v.postgres.assertions) {
+      if (!object(a) || typeof a.query !== "string" || !/^select\s/i.test(a.query) || a.query.includes(";") || !Array.isArray(a.equals) || !a.equals.every(object)) invalid("postgres assertions require a SELECT query without semicolons and an equals array");
+    }
+  }
+  if (v.redis !== void 0) {
+    if (!object(v.redis) || !Array.isArray(v.redis.assertions) || !v.redis.assertions.length || v.redis.assertions.length > 100) invalid("redis requires assertions");
+    for (const a of v.redis.assertions) {
+      if (!object(a) || typeof a.key !== "string" || !a.key || a.equals !== null && typeof a.equals !== "string") invalid("redis assertions require key and string/null equals");
+    }
+  }
+  if (v.fault !== void 0 && (!object(v.fault) || !known(v.fault) || v.fault.type !== "timeout-after-write" || !Number.isInteger(v.fault.delayMs) || Number(v.fault.delayMs) < 1 || Number(v.fault.delayMs) > 1e4)) invalid("fault requires an existing service/path and delayMs 1\u201310000");
+  const keys = ["schema", "name", "workflowId", "files", "command", "timeoutSeconds", "services", "assertions", "postgres", "redis", "fault"];
+  if (Object.keys(v).some((k) => !keys.includes(k))) invalid("unknown world field");
+  return v;
+}
+
+// src/commands/run.ts
+import { mkdtemp, mkdir, readFile as readFile3, writeFile, realpath, lstat, rm, copyFile } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname, isAbsolute, join as join3, relative, resolve, sep } from "path";
+import { fileURLToPath } from "url";
+import { createHash, randomUUID } from "crypto";
+
+// src/runtime/remote.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+
+// src/lib/exit.ts
+var EXIT = {
+  OK: 0,
+  ERROR: 1,
+  BLOCKED: 2,
+  USAGE: 3
+};
+var CliError = class extends Error {
+  code;
+  action;
+  resume;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = opts.code ?? EXIT.ERROR;
+    this.action = opts.action;
+    this.resume = opts.resume;
+  }
+};
+
+// src/runtime/remote.ts
+function apiBase(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new CliError("Invalid AGENTTWIN_API_URL", { code: EXIT.USAGE });
+  }
+  if (url.username || url.password || url.search || url.hash || url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))) throw new CliError("AgentTwin API requires HTTPS (loopback HTTP allowed for development)", { code: EXIT.USAGE });
+  return value.replace(/\/$/, "");
+}
+async function executeRemote(stage, spec, log) {
+  const base = apiBase(process.env.AGENTTWIN_API_URL ?? "");
+  const token = process.env.AGENTTWIN_TOKEN;
+  if (!token) throw new CliError("AGENTTWIN_TOKEN is not configured", { code: EXIT.BLOCKED });
+  const files = /* @__PURE__ */ Object.create(null);
+  for (const file of spec.files) files[file] = (await readFile(join(stage, "app", file))).toString("base64");
+  const headers = { authorization: `Bearer ${token}`, "content-type": "application/json" };
+  const response = await fetch(`${base}/v1/runs`, { method: "POST", headers, body: JSON.stringify({ spec, files }), redirect: "error", signal: AbortSignal.timeout(15e3) });
+  if (!response.ok) throw new CliError(`AgentTwin API rejected run (${response.status}): ${await response.text()}`, { code: response.status === 401 || response.status === 429 ? EXIT.BLOCKED : EXIT.ERROR });
+  const job = await response.json();
+  if (!/^[a-f0-9-]{36}$/.test(job.id)) throw new CliError("API returned an invalid run ID");
+  log(`Hosted run queued: ${job.id}`);
+  const deadline = Date.now() + (spec.timeoutSeconds + 150) * 1e3;
+  while (Date.now() < deadline) {
+    const result = await fetch(`${base}/v1/runs/${job.id}`, { headers, redirect: "error", signal: AbortSignal.timeout(15e3) });
+    if (!result.ok) throw new CliError(`Cannot read hosted run (${result.status})`);
+    const state = await result.json();
+    if (state.receipt) {
+      if (state.receipt.apiJobId !== job.id) throw new CliError("Hosted receipt belongs to a different API job");
+      return state.receipt;
+    }
+    if (["error", "cancelled"].includes(state.status)) throw new CliError(state.error ?? "Hosted runtime failed");
+    await new Promise((resolve3) => setTimeout(resolve3, 1e3));
+  }
+  throw new CliError(`Timed out waiting for hosted run ${job.id}; inspect this run in the API before retrying`);
+}
+
+// src/runtime/e2b.ts
+import { Sandbox } from "e2b";
+import { readFile as readFile2 } from "fs/promises";
+import { randomBytes } from "crypto";
+import { homedir } from "os";
+import { join as join2 } from "path";
+async function executeE2B(stage, spec, log, signal) {
+  signal?.throwIfAborted();
+  const apiKey = process.env.E2B_API_KEY;
+  if (!apiKey) throw new CliError("E2B_API_KEY is not configured", { code: EXIT.BLOCKED, action: "Set E2B_API_KEY in your shell. It remains on the host and is never passed to the application." });
+  let saved = {};
+  try {
+    saved = JSON.parse(await readFile2(join2(homedir(), ".agenttwin/runtime.json"), "utf8"));
+  } catch {
+  }
+  const template = process.env.E2B_TEMPLATE_ID ?? saved.templateId;
+  if (!template) throw new CliError("No hosted runtime template is configured", { code: EXIT.BLOCKED, action: "Run agenttwin setup once to build the E2B Node/PostgreSQL/Redis template." });
+  log(`Creating E2B sandbox from ${template}. Only the files listed in the world specification will be uploaded; outbound internet is disabled.`);
+  const sandbox = await Sandbox.create(template, { apiKey, timeoutMs: (spec.timeoutSeconds + 120) * 1e3, allowInternetAccess: false, network: { allowPublicTraffic: false, denyOut: ["0.0.0.0/0"] }, metadata: { product: "agenttwin", world: spec.name } });
+  const secrets = [apiKey];
+  const cleanup = () => {
+    void sandbox.kill().catch(() => {
+    });
+  };
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  signal?.addEventListener("abort", cleanup, { once: true });
+  try {
+    signal?.throwIfAborted();
+    await sandbox.commands.run("mkdir -p /input/app && chmod 755 /input /input/app", { user: "root" });
+    for (const file of ["world.json", "worker.js", ...spec.files.map((f) => `app/${f}`)]) {
+      await sandbox.files.write(`/input/${file}`, new Uint8Array(await readFile2(join2(stage, file))).buffer, { user: "root" });
+    }
+    await sandbox.commands.run("chmod -R a+rX /input", { user: "root" });
+    const runtimeEnv = {};
+    if (spec.postgres) {
+      const password = randomBytes(24).toString("hex");
+      secrets.push(password);
+      await sandbox.commands.run("pg_ctlcluster --skip-systemctl-redirect 15 main start -o '-c ssl=off -c listen_addresses=127.0.0.1'", { user: "root" });
+      await sandbox.files.write("/tmp/agenttwin-init.sql", `CREATE ROLE agenttwin LOGIN PASSWORD '${password}';
+CREATE DATABASE agenttwin OWNER agenttwin;
+`, { user: "root" });
+      await sandbox.commands.run("chmod 644 /tmp/agenttwin-init.sql && runuser -u postgres -- psql -v ON_ERROR_STOP=1 -f /tmp/agenttwin-init.sql && rm /tmp/agenttwin-init.sql", { user: "root" });
+      runtimeEnv.DATABASE_URL = `postgresql://agenttwin:${password}@127.0.0.1:5432/agenttwin`;
+      if (spec.postgres.seedFile) {
+        const quote = (s) => "'" + s.replaceAll("'", `'"'"'`) + "'";
+        await sandbox.commands.run(`psql -v ON_ERROR_STOP=1 -f ${quote("/input/app/" + spec.postgres.seedFile)}`, { user: "node", envs: { PGHOST: "127.0.0.1", PGUSER: "agenttwin", PGDATABASE: "agenttwin", PGPASSWORD: password } });
+      }
+    }
+    if (spec.redis) {
+      const password = randomBytes(24).toString("hex");
+      secrets.push(password);
+      await sandbox.files.write("/tmp/agenttwin-redis.conf", `bind 127.0.0.1
+port 6379
+requirepass ${password}
+save ""
+appendonly no
+daemonize yes
+logfile /tmp/agenttwin-redis.log
+`, { user: "root" });
+      await sandbox.commands.run("redis-server /tmp/agenttwin-redis.conf", { user: "root" });
+      runtimeEnv.REDIS_URL = `redis://:${password}@127.0.0.1:6379`;
+      runtimeEnv.REDISCLI_AUTH = password;
+    }
+    await sandbox.files.write("/input/runtime.json", JSON.stringify(runtimeEnv), { user: "root" });
+    await sandbox.commands.run("chmod -R a+rX /input", { user: "root" });
+    await sandbox.commands.run("iptables -A OUTPUT -o lo -j ACCEPT && iptables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT && iptables -A OUTPUT -j REJECT && ip6tables -A OUTPUT -o lo -j ACCEPT && ip6tables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT && ip6tables -A OUTPUT -j REJECT", { user: "root" });
+    const result = await sandbox.commands.run("node /input/worker.js", { user: "root", cwd: "/input/app", timeoutMs: (spec.timeoutSeconds + 15) * 1e3 });
+    signal?.throwIfAborted();
+    return {
+      result: { code: result.exitCode, stdout: result.stdout, stderr: result.stderr },
+      image: `e2b:${template}`,
+      templateBuildId: process.env.E2B_TEMPLATE_ID ? void 0 : saved.buildId,
+      sandboxId: sandbox.sandboxId,
+      isolation: { network: "E2B deny-all requested; guest IPv4/IPv6 OUTPUT firewall enforced", publicTraffic: false, productionCredentialsInherited: false, rootFilesystem: "ephemeral sandbox", user: "node", applicationFiles: spec.files }
+    };
+  } catch (error) {
+    const failure = error;
+    let message = failure.stderr || failure.message || "Hosted execution failed";
+    for (const secret of secrets) message = message.split(secret).join("[redacted]");
+    throw new CliError(message.slice(0, 4e3));
+  } finally {
+    signal?.removeEventListener("abort", cleanup);
+    process.removeListener("SIGINT", cleanup);
+    process.removeListener("SIGTERM", cleanup);
+    await sandbox.kill().catch(() => log("Sandbox cleanup could not be confirmed; its configured expiration remains active."));
+  }
+}
+
+// src/commands/run.ts
+async function stageApplication(root, files, destination) {
+  const canonicalRoot = await realpath(root);
+  const digests = {};
+  let bytes = 0;
+  for (const file of files) {
+    if (isAbsolute(file) || file.includes("\\") || file.split("/").some((p) => p === ".." || /^(\.env.*|\.git|\.ssh|\.aws|\.azure|\.config|\.npmrc|\.netrc|credentials.*)$/i.test(p)) || /\.(pem|key|p12|pfx)$/i.test(file)) throw new CliError(`Unsafe application file: ${file}`, { code: EXIT.USAGE });
+    const source = await realpath(resolve(canonicalRoot, file));
+    const rel = relative(canonicalRoot, source);
+    if (rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel) || source !== resolve(canonicalRoot, file) || !(await lstat(source)).isFile()) throw new CliError(`Files must be regular files within the project, without symlinks: ${file}`, { code: EXIT.USAGE });
+    const contents = await readFile3(source);
+    bytes += contents.length;
+    if (bytes > 20 * 1024 * 1024) throw new CliError("Application files exceed 20 MiB; supply a smaller built bundle", { code: EXIT.USAGE });
+    const target = join3(destination, file);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, contents, { mode: 420 });
+    digests[file] = createHash("sha256").update(contents).digest("hex");
+  }
+  return digests;
+}
+async function runWorld(cwd, opts) {
+  const file = resolve(cwd, opts.file ?? "agenttwin.world.json");
+  let spec;
+  try {
+    spec = parseWorld(JSON.parse(await readFile3(file, "utf8")));
+  } catch (error) {
+    throw new CliError(String(error), { code: EXIT.USAGE, action: "Create agenttwin.world.json; run agenttwin example --out ./agenttwin-example for a working example." });
+  }
+  if (spec.workflowId) {
+    let inventory;
+    try {
+      inventory = JSON.parse(await readFile3(join3(cwd, ".agenttwin/inventory.json"), "utf8"));
+    } catch {
+      throw new CliError("Linked workflow needs discovery inventory; run init first", { code: EXIT.BLOCKED });
+    }
+    if (!inventory.workflows?.some((w) => w.id === spec.workflowId)) throw new CliError("workflowId is absent from the current inventory", { code: EXIT.BLOCKED });
+  }
+  const runtime = opts.runtime ?? (process.env.AGENTTWIN_API_URL ? "hosted" : "e2b");
+  if (!["e2b", "hosted"].includes(runtime)) throw new CliError("runtime must be hosted or e2b; no local application execution", { code: EXIT.USAGE });
+  if (runtime === "e2b" && !process.env.E2B_API_KEY) throw new CliError("E2B_API_KEY is not configured", { code: EXIT.BLOCKED, action: "Configure your E2B key in the shell; it will not be uploaded." });
+  const stage = await mkdtemp(join3(tmpdir(), "agenttwin-world-"));
+  try {
+    const sourceDigests = await stageApplication(dirname(file), spec.files, join3(stage, "app"));
+    await writeFile(join3(stage, "world.json"), JSON.stringify(spec), { mode: 420 });
+    const worker = join3(dirname(fileURLToPath(import.meta.url)), "worker.js");
+    await copyFile(worker, join3(stage, "worker.js"));
+    if (runtime === "hosted") {
+      const receipt2 = await executeRemote(stage, spec, opts.log);
+      if (receipt2.schema !== "agenttwin/run-v1" || typeof receipt2.runId !== "string" || !/^[a-f0-9-]{36}$/.test(receipt2.runId) || !["passed", "failed", "error", "incomplete"].includes(String(receipt2.status))) throw new CliError("Invalid hosted receipt");
+      const expectedSpec = createHash("sha256").update(JSON.stringify(spec)).digest("hex");
+      const reportedSources = receipt2.sourceDigests;
+      if (receipt2.specDigest !== expectedSpec || !reportedSources || Object.keys(reportedSources).length !== Object.keys(sourceDigests).length || Object.entries(sourceDigests).some(([path, digest]) => reportedSources[path] !== digest)) throw new CliError("Hosted receipt does not match the submitted source/specification");
+      const out2 = resolve(cwd, opts.out ?? `.agenttwin/runs/${receipt2.runId}`);
+      await mkdir(out2, { recursive: true });
+      const evidencePath = join3(out2, "run.json");
+      const reportPath = join3(out2, "report.md");
+      await writeFile(evidencePath, JSON.stringify(receipt2, null, 2) + "\n", { mode: 384 });
+      await writeFile(reportPath, `# ${spec.name}: ${receipt2.status}
+
+Run: ${receipt2.runId}
+
+See run.json for assertions, service state, application output and isolation metadata.
+`);
+      return { ...receipt2, name: spec.name, status: String(receipt2.status), evidencePath, reportPath };
+    }
+    const { result, image, templateBuildId, sandboxId, isolation } = await executeE2B(stage, spec, opts.log, opts.signal);
+    if (result.code !== 0) throw new CliError(`Isolated runtime failed: ${result.stderr || `exit ${result.code}`}`);
+    let report;
+    try {
+      report = JSON.parse(result.stdout);
+    } catch {
+      throw new CliError("Runtime did not produce a valid run receipt");
+    }
+    if (report.schema !== "agenttwin/run-v1") throw new CliError("Unexpected runtime receipt schema");
+    const runId = randomUUID();
+    const receipt = {
+      ...report,
+      ...spec.workflowId ? { workflowId: spec.workflowId } : {},
+      runId,
+      runtime,
+      sandboxId,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      image,
+      templateBuildId,
+      sourceDigests,
+      specDigest: createHash("sha256").update(JSON.stringify(spec)).digest("hex"),
+      isolation
+    };
+    const out = resolve(cwd, opts.out ?? `.agenttwin/runs/${runId}`);
+    await mkdir(out, { recursive: true });
+    await writeFile(join3(out, "run.json"), JSON.stringify(receipt, null, 2) + "\n", { mode: 384 });
+    await writeFile(join3(out, "world.json"), JSON.stringify(spec, null, 2) + "\n", { mode: 384 });
+    const summary = [`# ${spec.name}: ${report.status}`, "", `Run: ${runId}`, `Image: ${image}`, "", "## Assertions", "", ...report.assertions.map((a) => `- ${a.passed ? "PASS" : "FAIL"} ${a.service}${a.path}: expected ${a.count}, observed ${a.actual}`), "", "## Infrastructure assertions", "", ...(report.infrastructureAssertions ?? []).map((a) => `- ${a.passed ? "PASS" : "FAIL"} ${a.service}: ${JSON.stringify(a.actual)}`), "", "## Coverage", "", report.coverage, "", "External networking disabled. Only explicitly listed source files were uploaded. New state and tokens are created for each run.", "", "See run.json for application output, faults, events, and initial/final state.", ""].join("\n");
+    await writeFile(join3(out, "report.md"), summary);
+    return { ...receipt, reportPath: join3(out, "report.md"), evidencePath: join3(out, "run.json") };
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
+}
+
+// src/runtime/gateway.ts
+var hash = (value) => createHash2("sha256").update(value).digest("hex");
+function uploadPath(path) {
+  if (!path || path.startsWith("/") || path.includes("\\") || path.includes("\0") || path.split("/").some((p) => !p || p === "." || p === ".." || /^(\.env.*|\.git|\.ssh|\.aws|\.azure|\.config|\.npmrc|\.netrc|credentials.*)$/i.test(p)) || /\.(pem|key|p12|pfx)$/i.test(path)) throw new Error("Unsafe uploaded file path");
+  return path;
+}
+async function body(req) {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of req) {
+    bytes += chunk.length;
+    if (bytes > 28 * 1024 * 1024) throw new Error("Request exceeds 28 MiB");
+    chunks.push(Buffer.from(chunk));
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function send(res, code, value) {
+  res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store" });
+  res.end(JSON.stringify(value));
+}
+function equal(a, b) {
+  const x = Buffer.from(hash(a)), y = Buffer.from(hash(b));
+  return timingSafeEqual(x, y);
+}
+async function startGateway(opts) {
+  if (opts.adminToken.length < 40) throw new Error("AGENTTWIN_ADMIN_TOKEN must have at least 40 characters");
+  if (!process.env.E2B_API_KEY || !process.env.E2B_TEMPLATE_ID) throw new Error("Gateway requires E2B_API_KEY and E2B_TEMPLATE_ID");
+  const allowedOrigins = new Set(opts.allowedOrigins ?? []);
+  for (const origin of allowedOrigins) {
+    const u = new URL(origin);
+    if (u.origin !== origin || u.protocol !== "https:" && !(u.protocol === "http:" && ["127.0.0.1", "localhost"].includes(u.hostname))) throw new Error("Invalid dashboard origin");
+  }
+  const controllers = /* @__PURE__ */ new Map();
+  const directory = resolve2(opts.directory);
+  await mkdir2(directory, { recursive: true, mode: 448 });
+  const storePath = join4(directory, "state.json");
+  let store;
+  try {
+    store = JSON.parse(await readFile4(storePath, "utf8"));
+    if (store.schema !== "agenttwin/gateway-v1") throw new Error("Invalid store");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    store = { schema: "agenttwin/gateway-v1", accounts: [], jobs: [] };
+  }
+  for (const job of store.jobs) if (job.status === "queued" || job.status === "running" || job.status === "cancelling") {
+    job.status = "error";
+    job.error = "Gateway restarted during run; sandbox expires automatically. Submit a fresh run.";
+  }
+  let writes = Promise.resolve();
+  let storageHealthy = true;
+  const save = () => {
+    const snapshot = JSON.stringify(store);
+    writes = writes.then(async () => {
+      const path = join4(directory, `state-${randomUUID2()}.tmp`);
+      await writeFile2(path, snapshot, { mode: 384 });
+      await rename(path, storePath);
+    }).catch((error) => {
+      storageHealthy = false;
+      throw error;
+    });
+    return writes;
+  };
+  await save();
+  store.jobs = store.jobs.filter((j) => Date.parse(j.createdAt) > Date.now() - 30 * 864e5);
+  const dailyLimit = opts.dailyLimit ?? 20;
+  const concurrency = opts.concurrency ?? 2;
+  if (!Number.isSafeInteger(dailyLimit) || dailyLimit < 1 || !Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 10) throw new Error("Invalid gateway limits");
+  let active = 0, stopping = false;
+  function busy(accountId) {
+    const pending = store.jobs.filter((j) => j.status === "queued" || j.status === "running" || j.status === "cancelling");
+    return pending.length >= 20 || pending.some((j) => j.accountId === accountId);
+  }
+  const queue = [];
+  const workers = /* @__PURE__ */ new Set();
+  function schedule() {
+    while (!stopping && storageHealthy && active < concurrency && queue.length) {
+      const item = queue.shift();
+      active++;
+      const worker = (async () => {
+        let workspace;
+        try {
+          if (!store.accounts.some((a) => a.id === item.job.accountId && a.active)) throw new Error("Account revoked before execution");
+          item.job.status = "running";
+          await save();
+          workspace = await mkdtemp2(join4(tmpdir2(), "agenttwin-api-run-"));
+          for (const [file, encoded] of Object.entries(item.files)) {
+            const destination = join4(workspace, uploadPath(file));
+            await mkdir2(dirname2(destination), { recursive: true });
+            await writeFile2(destination, Buffer.from(encoded, "base64"), { mode: 384 });
+          }
+          await writeFile2(join4(workspace, "agenttwin.world.json"), JSON.stringify(item.spec));
+          if (item.spec.workflowId) {
+            await mkdir2(join4(workspace, ".agenttwin"));
+            await writeFile2(join4(workspace, ".agenttwin/inventory.json"), JSON.stringify({ workflows: [{ id: item.spec.workflowId }] }));
+          }
+          const receipt = await runWorld(workspace, { runtime: "e2b", signal: controllers.get(item.job.id)?.signal, log: () => {
+          } });
+          controllers.get(item.job.id)?.signal.throwIfAborted();
+          const { reportPath: _report, evidencePath: _evidence, ...portable } = receipt;
+          item.job.receipt = { ...portable, apiJobId: item.job.id, provenance: "client-supplied workflow declaration" };
+          item.job.status = "completed";
+        } catch (error) {
+          item.job.status = controllers.get(item.job.id)?.signal.aborted ? "cancelled" : "error";
+          const message = error instanceof Error ? error.message : String(error);
+          item.job.error = message.split(process.env.E2B_API_KEY ?? "\0").join("[redacted]").replace(/(?:postgresql|redis):\/\/[^\s]+/g, "[test-connection]").slice(0, 2e3);
+        } finally {
+          try {
+            if (workspace) await rm2(workspace, { recursive: true, force: true });
+            await save();
+          } finally {
+            controllers.delete(item.job.id);
+            active--;
+            schedule();
+          }
+        }
+      })();
+      workers.add(worker);
+      void worker.finally(() => workers.delete(worker)).catch(() => {
+      });
+    }
+  }
+  const server = createServer(async (req, res) => {
+    try {
+      const path = new URL(req.url ?? "/", "http://localhost").pathname;
+      if (opts.dashboardDirectory && req.method === "GET" && (path === "/dashboard" || path.startsWith("/dashboard/"))) {
+        if (path === "/dashboard") {
+          res.writeHead(302, { location: "/dashboard/" });
+          res.end();
+          return;
+        }
+        const relative2 = decodeURIComponent(path.slice("/dashboard/".length)) || "index.html";
+        const root = resolve2(opts.dashboardDirectory), file = resolve2(root, relative2);
+        if (!file.startsWith(root + "/") || relative2 !== "index.html" && !relative2.startsWith("assets/")) {
+          send(res, 404, { error: "not_found" });
+          return;
+        }
+        try {
+          const bytes = await readFile4(file);
+          const types = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".ico": "image/x-icon", ".woff2": "font/woff2" };
+          res.writeHead(200, { "content-type": types[extname(file)] ?? "application/octet-stream", "cache-control": "no-store", "x-content-type-options": "nosniff", "referrer-policy": "no-referrer" });
+          res.end(bytes);
+        } catch {
+          send(res, 404, { error: "not_found" });
+        }
+        return;
+      }
+      const origin = req.headers.origin;
+      if (origin) {
+        if (!allowedOrigins.has(origin)) {
+          send(res, 403, { error: "origin_not_allowed" });
+          return;
+        }
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+        if (req.method === "OPTIONS") {
+          res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+          res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
+          res.setHeader("Access-Control-Max-Age", "600");
+          res.writeHead(204);
+          res.end();
+          return;
+        }
+      }
+      if (path === "/healthz" && req.method === "GET") {
+        send(res, 200, { status: stopping ? "stopping" : "ok" });
+        return;
+      }
+      if (!storageHealthy) {
+        send(res, 503, { error: "storage_unavailable" });
+        return;
+      }
+      const token = req.headers.authorization?.replace(/^Bearer /, "") ?? "";
+      const admin = equal(token, opts.adminToken);
+      if (path === "/v1/accounts" && req.method === "POST") {
+        if (!admin) {
+          send(res, 401, { error: "unauthorized" });
+          return;
+        }
+        const data = await body(req);
+        if (typeof data.label !== "string" || !data.label || data.label.length > 100) {
+          send(res, 400, { error: "label_required" });
+          return;
+        }
+        const accessToken = `at_user_${randomBytes2(32).toString("hex")}`;
+        const account2 = { id: randomUUID2(), tokenHash: hash(accessToken), label: data.label, active: true, usageDay: "", runs: 0 };
+        if (store.accounts.length >= 1e4) {
+          send(res, 429, { error: "account_capacity" });
+          return;
+        }
+        store.accounts.push(account2);
+        await save();
+        send(res, 201, { accountId: account2.id, token: accessToken });
+        return;
+      }
+      const revoke = path.match(/^\/v1\/accounts\/([a-f0-9-]{36})$/);
+      if (revoke && req.method === "DELETE") {
+        if (!admin) {
+          send(res, 401, { error: "unauthorized" });
+          return;
+        }
+        const account2 = store.accounts.find((a) => a.id === revoke[1]);
+        if (!account2) {
+          send(res, 404, { error: "not_found" });
+          return;
+        }
+        account2.active = false;
+        await save();
+        send(res, 200, { revoked: true });
+        return;
+      }
+      const account = store.accounts.find((a) => a.active && a.tokenHash === hash(token));
+      if (!account) {
+        send(res, 401, { error: "unauthorized" });
+        return;
+      }
+      if (path === "/v1/runs" && req.method === "GET") {
+        send(res, 200, { jobs: store.jobs.filter((j) => j.accountId === account.id).slice(-100).reverse().map(({ id, status, createdAt }) => ({ id, status, createdAt })) });
+        return;
+      }
+      if (path === "/v1/runs" && req.method === "POST") {
+        if (stopping) {
+          send(res, 503, { error: "stopping" });
+          return;
+        }
+        if (busy(account.id)) {
+          send(res, 429, { error: "run_in_progress_or_queue_full" });
+          return;
+        }
+        const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+        if (account.usageDay !== today) {
+          account.usageDay = today;
+          account.runs = 0;
+        }
+        if (account.runs >= dailyLimit) {
+          send(res, 429, { error: "daily_run_limit" });
+          return;
+        }
+        const input = await body(req);
+        const spec = parseWorld(input.spec);
+        if (!input.files || typeof input.files !== "object" || Array.isArray(input.files)) throw new Error("files object required");
+        if (Object.keys(input.files).length !== spec.files.length) throw new Error("Upload must match explicit file list");
+        let total = 0;
+        for (const file of spec.files) {
+          uploadPath(file);
+          const encoded = input.files[file];
+          if (typeof encoded !== "string" || Buffer.from(encoded, "base64").toString("base64") !== encoded) throw new Error("Files must use canonical base64");
+          total += Buffer.from(encoded, "base64").length;
+        }
+        if (total > 20 * 1024 * 1024) throw new Error("Application exceeds 20 MiB");
+        if (!account.active) {
+          send(res, 401, { error: "unauthorized" });
+          return;
+        }
+        if (busy(account.id)) {
+          send(res, 429, { error: "run_in_progress_or_queue_full" });
+          return;
+        }
+        const submissionDay = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+        if (account.usageDay !== submissionDay) {
+          account.usageDay = submissionDay;
+          account.runs = 0;
+        }
+        if (account.runs >= dailyLimit || store.jobs.filter((j) => j.createdAt.startsWith(submissionDay)).length >= 200) {
+          send(res, 429, { error: "daily_run_limit" });
+          return;
+        }
+        store.jobs = store.jobs.filter((j) => Date.parse(j.createdAt) > Date.now() - 30 * 864e5);
+        const job = { id: randomUUID2(), accountId: account.id, status: "queued", createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+        account.runs++;
+        store.jobs.push(job);
+        await save();
+        controllers.set(job.id, new AbortController());
+        queue.push({ job, spec, files: input.files });
+        schedule();
+        send(res, 202, { id: job.id, status: job.status });
+        return;
+      }
+      const match = path.match(/^\/v1\/runs\/([a-f0-9-]{36})$/);
+      if (match && req.method === "DELETE") {
+        const job = store.jobs.find((j) => j.id === match[1] && j.accountId === account.id);
+        if (!job) {
+          send(res, 404, { error: "not_found" });
+          return;
+        }
+        if (!["queued", "running", "cancelling"].includes(job.status)) {
+          send(res, 409, { error: "run_already_finished" });
+          return;
+        }
+        const index = queue.findIndex((item) => item.job.id === job.id);
+        if (index >= 0) {
+          queue.splice(index, 1);
+          job.status = "cancelled";
+          controllers.delete(job.id);
+        } else {
+          job.status = "cancelling";
+          controllers.get(job.id)?.abort(new Error("Run cancelled by account owner"));
+        }
+        await save();
+        send(res, 202, { id: job.id, status: job.status });
+        return;
+      }
+      if (match && req.method === "GET") {
+        const job = store.jobs.find((j) => j.id === match[1] && j.accountId === account.id);
+        if (!job) {
+          send(res, 404, { error: "not_found" });
+          return;
+        }
+        send(res, 200, { id: job.id, status: job.status, receipt: job.receipt, error: job.error });
+        return;
+      }
+      send(res, 404, { error: "not_found" });
+    } catch (error) {
+      if (!storageHealthy) {
+        send(res, 503, { error: "storage_unavailable" });
+        return;
+      }
+      send(res, 400, { error: "invalid_request", message: error instanceof Error ? error.message : "Invalid request" });
+    }
+  });
+  server.requestTimeout = 3e4;
+  server.headersTimeout = 1e4;
+  await new Promise((done, reject) => {
+    server.once("error", reject);
+    server.listen(opts.port, opts.host ?? "127.0.0.1", done);
+  });
+  return { server, async close() {
+    stopping = true;
+    server.close();
+    await Promise.allSettled([...workers]);
+    await writes;
+    server.closeAllConnections();
+  } };
+}
+export {
+  startGateway,
+  uploadPath
+};