agenttwin 0.1.0 → 0.2.1

package/dist/worker.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+// src/runtime/worker.ts
+import { readFile } from "fs/promises";
+import { promisify } from "util";
+import { execFile } from "child_process";
+import { spawn } from "child_process";
+
+// src/runtime/http-world.ts
+import { createServer } from "http";
+import { randomBytes } from "crypto";
+var HttpWorld = class {
+  constructor(spec) {
+    this.spec = spec;
+  }
+  spec;
+  events = [];
+  state = /* @__PURE__ */ Object.create(null);
+  credentials = /* @__PURE__ */ Object.create(null);
+  unsupported = [];
+  servers = [];
+  timers = /* @__PURE__ */ new Set();
+  fired = false;
+  record(service, operation, path, detail) {
+    if (this.events.length >= 5e4) return;
+    this.events.push({ sequence: this.events.length + 1, service, operation, path, detail });
+  }
+  async start() {
+    for (const service of this.spec.services) {
+      const token = `at_world_${randomBytes(24).toString("hex")}`;
+      const data = /* @__PURE__ */ Object.create(null);
+      this.state[service.name] = data;
+      for (const c of service.collections) data[c.path] = structuredClone(c.seed);
+      const keys = /* @__PURE__ */ new Map();
+      const server = createServer(async (req, res) => {
+        const send = (code, body) => {
+          if (!res.destroyed) {
+            res.writeHead(code, { "content-type": "application/json" });
+            res.end(JSON.stringify(body));
+          }
+        };
+        try {
+          if (req.headers.authorization !== `Bearer ${token}`) {
+            this.record(service.name, "auth-denied", req.url ?? "", "invalid test credential");
+            send(401, { error: "invalid_test_credential" });
+            return;
+          }
+          if (this.events.length >= 5e4 || this.unsupported.length >= 1e3) {
+            send(429, { error: "world_capacity" });
+            return;
+          }
+          const url = new URL(req.url ?? "/", "http://localhost");
+          let path = url.pathname;
+          const slack = service.adapter === "slack";
+          const slackMethod = path.replace(/^\/api\//, "");
+          let payload;
+          if (req.method === "POST") {
+            const chunks = [];
+            let bytes = 0;
+            for await (const chunk of req) {
+              bytes += chunk.length;
+              if (bytes > 1024 * 1024) {
+                send(413, { error: "body_too_large" });
+                return;
+              }
+              chunks.push(Buffer.from(chunk));
+            }
+            const text = Buffer.concat(chunks).toString("utf8");
+            let parsed;
+            try {
+              parsed = slack && req.headers["content-type"]?.startsWith("application/x-www-form-urlencoded") ? Object.fromEntries(new URLSearchParams(text)) : JSON.parse(text);
+            } catch {
+              send(400, { error: "expected_json_object" });
+              return;
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+              send(400, { error: "expected_json_object" });
+              return;
+            }
+            payload = parsed;
+          }
+          if (slack) {
+            const params = payload ?? Object.fromEntries(url.searchParams);
+            const allowed = slackMethod === "chat.postMessage" ? ["channel", "text"] : slackMethod === "conversations.history" ? ["channel"] : [];
+            if (Object.keys(params).some((k) => !allowed.includes(k))) {
+              this.unsupported.push(`${service.name}: unsupported parameters for ${slackMethod}`);
+              send(501, { ok: false, error: "unsupported_parameters", forwardedToProduction: false });
+              return;
+            }
+            if (slackMethod === "chat.postMessage" && req.method === "POST") path = "/messages";
+            else if (slackMethod === "conversations.history" && ["GET", "POST"].includes(req.method ?? "")) path = "/messages";
+            else if (slackMethod === "conversations.list" && ["GET", "POST"].includes(req.method ?? "")) path = "/channels";
+            else {
+              this.unsupported.push(`${service.name}: ${req.method} ${url.pathname}`);
+              send(501, { ok: false, error: "unsupported_operation" });
+              return;
+            }
+          }
+          if (!Object.hasOwn(data, path) || !["GET", "POST"].includes(req.method ?? "")) {
+            this.unsupported.push(`${service.name}: ${req.method} ${path}`);
+            send(501, { error: "unsupported_operation", forwardedToProduction: false });
+            return;
+          }
+          if (req.method === "GET" || slack && slackMethod !== "chat.postMessage") {
+            this.record(service.name, "read", path, `${data[path].length} records`);
+            if (slack && path === "/channels") send(200, { ok: true, channels: data[path], response_metadata: { next_cursor: "" } });
+            else if (slack) {
+              const channel = payload?.channel ?? url.searchParams.get("channel");
+              if (!data["/channels"].some((c) => c.id === channel)) send(200, { ok: false, error: "channel_not_found" });
+              else send(200, { ok: true, messages: data[path].filter((m) => m.channel === channel), has_more: false });
+            } else send(200, { data: data[path] });
+            return;
+          }
+          const body = payload;
+          if (slack) {
+            const message = body;
+            if (!data["/channels"].some((c) => c.id === message.channel)) {
+              send(200, { ok: false, error: "channel_not_found" });
+              return;
+            }
+            if (typeof message.text !== "string" || !message.text) {
+              send(200, { ok: false, error: "no_text" });
+              return;
+            }
+          }
+          if (data[path].length >= 1e4 || this.events.length >= 5e4) {
+            send(429, { error: "world_capacity" });
+            return;
+          }
+          const keyHeader = slack ? void 0 : req.headers["idempotency-key"];
+          const key = typeof keyHeader === "string" ? `${path}:${keyHeader}` : void 0;
+          const signature = JSON.stringify(body);
+          const previous = key ? keys.get(key) : void 0;
+          if (previous) {
+            if (previous.body !== signature) {
+              send(409, { error: "idempotency_conflict" });
+              return;
+            }
+            this.record(service.name, "replay", path, "same-key response replay");
+            send(200, previous.record);
+            return;
+          }
+          let index = data[path].length + 1;
+          while (data[path].some((r) => r.id === `${service.name}_${index}`)) index++;
+          const row = { ...body, id: `${service.name}_${index}` };
+          if (slack) row.ts = `${index}.000001`;
+          const reply = slack ? { ok: true, channel: row.channel, ts: row.ts, message: row } : row;
+          data[path].push(row);
+          if (key) keys.set(key, { body: signature, record: row });
+          this.record(service.name, "write", path, String(row.id));
+          const fault = this.spec.fault;
+          if (!this.fired && fault?.service === service.name && fault.path === path) {
+            this.fired = true;
+            this.record(service.name, "fault", path, `write committed; response delayed ${fault.delayMs}ms`);
+            const timer = setTimeout(() => {
+              this.timers.delete(timer);
+              send(slack ? 200 : 201, reply);
+            }, fault.delayMs);
+            this.timers.add(timer);
+          } else send(slack ? 200 : 201, reply);
+        } catch {
+          send(500, { error: "world_request_error" });
+        }
+      });
+      server.requestTimeout = 1e4;
+      await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+      });
+      this.servers.push(server);
+      this.credentials[service.name] = { endpoint: `http://127.0.0.1:${server.address().port}`, token };
+    }
+    return this.credentials;
+  }
+  assertions() {
+    return this.spec.assertions.map((a) => {
+      const rows = this.state[a.service][a.path].filter((row) => !a.where || Object.entries(a.where).every(([k, v]) => JSON.stringify(row[k]) === JSON.stringify(v)));
+      return { ...a, actual: rows.length, passed: rows.length === a.count };
+    });
+  }
+  get faultTriggered() {
+    return this.fired;
+  }
+  async close() {
+    for (const timer of this.timers) clearTimeout(timer);
+    this.timers.clear();
+    await Promise.all(this.servers.map((server) => new Promise((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections();
+    })));
+  }
+};
+
+// 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/runtime/worker.ts
+var secrets = [];
+async function main() {
+  const spec = parseWorld(JSON.parse(await readFile("/input/world.json", "utf8")));
+  const world = new HttpWorld(spec);
+  const started = Date.now();
+  try {
+    const credentials = await world.start();
+    secrets.push(...Object.values(credentials).map((c) => c.token));
+    const runtimeEnv = JSON.parse(await readFile("/input/runtime.json", "utf8"));
+    secrets.push(...Object.values(runtimeEnv));
+    const env = { PATH: "/usr/local/bin:/usr/bin:/bin", HOME: "/tmp", TMPDIR: "/tmp", NODE_ENV: "test", ...runtimeEnv };
+    for (const [name, credential] of Object.entries(credentials)) {
+      env[`AGENTTWIN_${name.toUpperCase()}_URL`] = credential.endpoint;
+      env[`AGENTTWIN_${name.toUpperCase()}_TOKEN`] = credential.token;
+    }
+    let stdout = "", stderr = "", timedOut = false;
+    const child = spawn(spec.command[0], spec.command.slice(1), { cwd: "/input/app", env, stdio: ["ignore", "pipe", "pipe"], detached: true, uid: 1e3, gid: 1e3 });
+    child.stdout.on("data", (b) => {
+      stdout = (stdout + b.toString()).slice(-65536);
+    });
+    child.stderr.on("data", (b) => {
+      stderr = (stderr + b.toString()).slice(-65536);
+    });
+    const kill = () => {
+      if (child.pid) {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+        }
+      }
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      kill();
+    }, spec.timeoutSeconds * 1e3);
+    const exitCode = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", resolve);
+    }).finally(() => {
+      clearTimeout(timer);
+      kill();
+    });
+    await world.close();
+    const assertions = world.assertions();
+    const infrastructureAssertions = [];
+    for (const assertion of spec.postgres?.assertions ?? []) {
+      const { stdout: output } = await promisify(execFile)("psql", [runtimeEnv.DATABASE_URL, "-qAt", "-v", "ON_ERROR_STOP=1", "-c", "BEGIN READ ONLY", "-c", `SELECT COALESCE(json_agg(t), '[]'::json) FROM (${assertion.query}) t`, "-c", "COMMIT"], { env: { ...env, PGOPTIONS: "-c statement_timeout=5000" }, timeout: 7e3 });
+      const actual = JSON.parse(output.trim());
+      infrastructureAssertions.push({ service: "postgres", query: assertion.query, expected: assertion.equals, actual, passed: JSON.stringify(actual) === JSON.stringify(assertion.equals) });
+    }
+    for (const assertion of spec.redis?.assertions ?? []) {
+      const { stdout: exists } = await promisify(execFile)("redis-cli", ["--raw", "EXISTS", assertion.key], { env, timeout: 5e3 });
+      const { stdout: output } = await promisify(execFile)("redis-cli", ["--raw", "GET", assertion.key], { env, timeout: 5e3 });
+      const actual = exists.trim() === "0" ? null : output.replace(/\n$/, "");
+      infrastructureAssertions.push({ service: "redis", key: assertion.key, expected: assertion.equals, actual, passed: actual === assertion.equals });
+    }
+    const status = world.unsupported.length || spec.fault && !world.faultTriggered ? "incomplete" : timedOut || exitCode !== 0 ? "error" : [...assertions, ...infrastructureAssertions].every((a) => a.passed) ? "passed" : "failed";
+    for (const c of Object.values(credentials)) {
+      stdout = stdout.split(c.token).join("[test-token]");
+      stderr = stderr.split(c.token).join("[test-token]");
+    }
+    for (const secret of Object.values(runtimeEnv)) {
+      stdout = stdout.split(secret).join("[test-credential]");
+      stderr = stderr.split(secret).join("[test-credential]");
+    }
+    process.stdout.write(JSON.stringify({
+      schema: "agenttwin/run-v1",
+      name: spec.name,
+      workflowId: spec.workflowId,
+      status,
+      application: { command: spec.command, exitCode, timedOut, stdout, stderr },
+      assertions,
+      infrastructureAssertions,
+      fault: spec.fault ? { ...spec.fault, triggered: world.faultTriggered } : null,
+      initialState: Object.fromEntries(spec.services.map((s) => [s.name, Object.fromEntries(s.collections.map((c) => [c.path, c.seed]))])),
+      finalState: world.state,
+      events: world.events,
+      unsupported: world.unsupported,
+      durationMs: Date.now() - started,
+      coverage: "JSON collections: GET/list, POST/create, idempotency replay. Slack subset (JSON/form): chat.postMessage, conversations.list/history (no OAuth, pagination or provider parity claim). Optional real PostgreSQL 15 / Redis with explicit final-state checks."
+    }) + "\n");
+  } finally {
+    await world.close();
+  }
+}
+main().catch((error) => {
+  let message = String(error);
+  for (const secret of secrets) message = message.split(secret).join("[test-credential]");
+  process.stderr.write(`World runtime failed: ${message}
+`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenttwin",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Give your agent a test world before it touches the real one.",
   "keywords": [
     "agent",
@@ -21,7 +21,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "license": "MIT",
   "scripts": {
@@ -29,11 +29,16 @@
     "dev": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "start:api": "node dist/gateway.js"
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "e2b": "^2.52.1",
+    "yaml": "^2.9.1"
+  },
   "devDependencies": {
     "@types/node": "^26.6.4",
     "tsup": "^8.5.1",