@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/src/remote-workers/client.js

@@ -0,0 +1,332 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { once } from "node:events";
+import { lstat, mkdtemp, open, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { resolveCommit } from "../git.js";
+import { registerPrivateEnvNames } from "../env.js";
+import { durableWorkerDirectory } from "./durability.js";
+import { redactExport } from "../privacy.js";
+import { verificationIntegrity } from "../verification-integrity.js";
+import { assertTransferTree, chunks, contextManifest, importWorkerArtifact, sha256, sourceBundle } from "./bundles.js";
+import { CAPABILITY, COMMIT_ID, DIGEST, MAX_BUNDLE_BYTES, MAX_EVENTS_BYTES, MAX_FRAME_BYTES, REQUEST_ID, RemoteWorkerError, validateWorkerCapabilities, validateWorkerRequest } from "./protocol.js";
+const targetFingerprint = (target) => sha256(JSON.stringify({ sshHost: target.sshHost, command: target.command, containerProfile: target.containerProfile }));
+const ID = /^[a-z][a-z0-9-]{0,63}$/;
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const terminal = (state) => ["completed", "failed", "cancelled"].includes(state);
+const SSH_OPTIONS = ["-T", "-a", "-k", "-o", "BatchMode=yes", "-o", "StrictHostKeyChecking=yes", "-o", "ForwardAgent=no", "-o", "ForwardX11=no", "-o", "ClearAllForwardings=yes", "-o", "PermitLocalCommand=no", "-o", "RemoteCommand=none", "-o", "GSSAPIDelegateCredentials=no", "-o", "SendEnv=-*", "-o", "ControlMaster=no", "-o", "ControlPath=none", "-o", "ConnectTimeout=10"];
+function sshEnvironment() {
+  return { PATH: process.env.PATH, HOME: process.env.HOME, USER: process.env.USER, LOGNAME: process.env.LOGNAME, SYSTEMROOT: process.env.SYSTEMROOT, LANG: "C.UTF-8" };
+}
+function targetConfig(value) {
+  if (!object(value) || value.version !== 1 || !Array.isArray(value.workers) || value.workers.length > 20) throw new RemoteWorkerError("Remote workers need explicit version 1 configuration with at most 20 targets");
+  const workers = value.workers.map((raw) => {
+    if (!object(raw) || typeof raw.id !== "string" || !ID.test(raw.id) || typeof raw.name !== "string" || !raw.name.trim() || raw.name.length > 120 || typeof raw.sshHost !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._@-]{0,199}$/.test(raw.sshHost) || typeof raw.command !== "string" || !raw.command.trim() || raw.command.length > 2e3 || /[\r\n\0]/.test(raw.command) || !Array.isArray(raw.repoMappings) || !raw.repoMappings.length || raw.repoMappings.length > 20 || raw.repoMappings.some((id) => typeof id !== "string" || !ID.test(id)) || raw.containerProfile !== void 0 && (typeof raw.containerProfile !== "string" || !ID.test(raw.containerProfile))) throw new RemoteWorkerError("Invalid registered SSH worker, command or repository mapping");
+    return { id: raw.id, name: raw.name.trim(), sshHost: raw.sshHost, command: raw.command, repoMappings: [...new Set(raw.repoMappings)], ...raw.containerProfile ? { containerProfile: raw.containerProfile } : {} };
+  });
+  if (new Set(workers.map((worker) => worker.id)).size !== workers.length) throw new RemoteWorkerError("Remote worker IDs must be unique");
+  return workers;
+}
+class RemoteWorkers {
+  /** sshBinary is a transport fixture seam; application configuration cannot override it. */
+  constructor(options = {}) {
+    this.options = options;
+    this.directory = join(resolve(options.home ?? process.env.CODEFLOW_HOME ?? join(homedir(), ".codeflow")), "remote-worker-private");
+  }
+  targets = [];
+  directory;
+  artifacts = /* @__PURE__ */ new Set();
+  async load() {
+    registerPrivateEnvNames(["CODEFLOW_REMOTE_WORKERS_JSON", "CODEFLOW_REMOTE_WORKERS_FILE", "CODEFLOW_WORKER_CONFIG_FILE"]);
+    const env = this.options.environment ?? process.env;
+    let text = env.CODEFLOW_REMOTE_WORKERS_JSON;
+    if (text && env.CODEFLOW_REMOTE_WORKERS_FILE) throw new RemoteWorkerError("Choose one remote worker configuration source");
+    if (env.CODEFLOW_REMOTE_WORKERS_FILE) {
+      const path = env.CODEFLOW_REMOTE_WORKERS_FILE;
+      if (!isAbsolute(path)) throw new RemoteWorkerError("Remote worker configuration file must be absolute");
+      const info = await lstat(path);
+      if (!info.isFile() || info.isSymbolicLink() || info.size > 128 * 1024) throw new RemoteWorkerError("Remote worker configuration must be a bounded regular file");
+      text = await readFile(path, "utf8");
+    }
+    if (text && Buffer.byteLength(text) > 128 * 1024) throw new RemoteWorkerError("Remote worker configuration exceeds 128 KiB");
+    this.targets = text ? targetConfig(JSON.parse(text)) : [];
+    await durableWorkerDirectory(this.directory);
+    if (!(await lstat(this.directory)).isDirectory()) throw new RemoteWorkerError("Remote receipt store must be a regular directory");
+    for (const name of await readdir(this.directory)) if (/^artifact-[A-Za-z0-9_-]+$/.test(name)) await rm(join(this.directory, name), { recursive: true, force: true });
+  }
+  list() {
+    return this.targets.map(({ id, name, repoMappings, containerProfile }) => ({ id, name, repoMappings: [...repoMappings], containerProfile, protocol: 1 }));
+  }
+  target(id, mapping) {
+    const target = this.targets.find((item) => item.id === id);
+    if (!target || mapping && !target.repoMappings.includes(mapping)) throw new RemoteWorkerError("Select an explicitly registered worker and repository mapping");
+    return target;
+  }
+  file(id) {
+    if (!REQUEST_ID.test(id)) throw new RemoteWorkerError("Invalid remote request ID");
+    return join(this.directory, `${id}.json`);
+  }
+  async remembered(workerId, id) {
+    const file = this.file(id), info = await lstat(file).catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (!info) return void 0;
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 8192) throw new RemoteWorkerError("Private remote receipt is damaged");
+    const value = JSON.parse(await readFile(file, "utf8"));
+    if (value.version !== 1 || value.workerId !== workerId || value.requestId !== id || !CAPABILITY.test(value.capability) || !COMMIT_ID.test(value.baseCommit)) throw new RemoteWorkerError("Private remote receipt does not belong to this worker");
+    if (value.targetFingerprint !== targetFingerprint(this.target(workerId))) throw new RemoteWorkerError("The registered SSH target changed. Restore its original host, command and profile before inspecting this private receipt.");
+    return value;
+  }
+  async remember(value) {
+    if ((await readdir(this.directory)).filter((file) => file.endsWith(".json")).length >= 2e3) throw new RemoteWorkerError("Inspect and archive remote receipts before creating more than 2,000 requests");
+    const handle = await open(this.file(value.requestId), "wx", 384);
+    try {
+      await handle.writeFile(JSON.stringify(value));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    const folder = await open(this.directory, "r");
+    try {
+      await folder.sync();
+    } finally {
+      await folder.close();
+    }
+  }
+  async exchange(target, frames, options = {}) {
+    return new Promise((resolveResult, reject) => {
+      const child = spawn(this.options.sshBinary ?? "ssh", [...SSH_OPTIONS, target.sshHost, target.command], { env: sshEnvironment(), detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"] });
+      const result = {};
+      let buffer = "", stderr = "", done = false, closed = false, hello = false, accepted = false, lastSeen = Date.now(), received = 0, events = 0, artifactOffset = 0;
+      let killTimer;
+      const stop = (signal) => {
+        if (closed) return;
+        try {
+          if (process.platform !== "win32" && child.pid) process.kill(-child.pid, signal);
+          else child.kill(signal);
+        } catch {
+          child.kill(signal);
+        }
+      };
+      const finish = (error) => {
+        if (done) return;
+        done = true;
+        clearTimeout(deadline);
+        clearInterval(watch);
+        options.signal?.removeEventListener("abort", abort);
+        child.stdin.destroy();
+        stop("SIGTERM");
+        if (!closed) {
+          killTimer = setTimeout(() => stop("SIGKILL"), 2e3);
+          killTimer.unref();
+        }
+        if (error) reject(error);
+        else resolveResult(result);
+      };
+      const abort = () => finish(new RemoteWorkerError("Remote transport was cancelled. Inspect the durable receipt before retrying.", accepted));
+      const deadline = setTimeout(() => finish(new RemoteWorkerError("Remote channel exceeded its deadline; inspect its receipt before retrying", accepted)), options.timeoutMs ?? 2e4);
+      const watch = setInterval(() => {
+        if (accepted && Date.now() - lastSeen > 15e3) finish(new RemoteWorkerError("Remote heartbeat expired; execution outcome is ambiguous", true));
+      }, 1e3);
+      options.signal?.addEventListener("abort", abort, { once: true });
+      const send = async () => {
+        for (const frame of frames) {
+          if (done) return;
+          const line = JSON.stringify(frame) + "\n";
+          if (Buffer.byteLength(line) > MAX_FRAME_BYTES) throw new RemoteWorkerError("Remote input exceeds its frame bound");
+          if (!child.stdin.write(line)) await once(child.stdin, "drain");
+        }
+      };
+      const handle = (frame) => {
+        if (!frame || frame.v !== 1) throw new RemoteWorkerError("Unsupported worker protocol");
+        lastSeen = Date.now();
+        if (frame.type === "hello") {
+          if (hello || frame.protocol !== 1) throw new RemoteWorkerError("Unsupported worker handshake");
+          hello = true;
+          void send().catch((error) => finish(error));
+          return;
+        }
+        if (!hello) throw new RemoteWorkerError("Worker did not identify its protocol");
+        if (frame.type === "error") throw new RemoteWorkerError(typeof frame.message === "string" ? frame.message.slice(0, 2e3) : "Worker rejected the request", accepted);
+        if (frame.type === "probe") {
+          const capabilities = validateWorkerCapabilities(frame.capabilities);
+          if (frame.hasBase !== void 0 && typeof frame.hasBase !== "boolean" || frame.hasRepositoryBase !== void 0 && typeof frame.hasRepositoryBase !== "boolean") throw new RemoteWorkerError("Invalid worker commit availability");
+          result.probe = { capabilities, hasBase: frame.hasBase, hasRepositoryBase: frame.hasRepositoryBase };
+          finish();
+          return;
+        }
+        if (frame.type === "accepted" || frame.type === "heartbeat" || frame.type === "receipt" || frame.type === "result") {
+          const receipt = frame.receipt;
+          if (!receipt || receipt.version !== 1 || !REQUEST_ID.test(receipt.requestId) || !["accepted", "running", "completed", "failed", "cancelled", "unknown"].includes(receipt.state)) throw new RemoteWorkerError("Invalid worker receipt");
+          const expected = frames.find((item) => item.type === "begin" || item.type === "receipt" || item.type === "cancel");
+          const id = expected?.type === "begin" ? expected.request.id : expected && "id" in expected ? expected.id : void 0;
+          if (receipt.requestId !== id) throw new RemoteWorkerError("Worker receipt belongs to a different request");
+          result.receipt = receipt;
+          accepted = true;
+          options.onReceipt?.(receipt);
+          if (frame.type === "result") {
+            if (typeof frame.result?.ok !== "boolean" || typeof frame.result.finalText !== "string" || frame.result.finalText.length > 512 * 1024) throw new RemoteWorkerError("Invalid worker result");
+            result.result = { ...frame.result, sessionId: void 0 };
+            if (result.artifact && artifactOffset !== result.artifact.size) throw new RemoteWorkerError("Remote artifact transfer is incomplete");
+            finish();
+          } else if (frame.type === "receipt" && (!receipt.artifact || frames.some((item) => item.type === "receipt" && item.downloadArtifact === false))) finish();
+          return;
+        }
+        if (frame.type === "event") {
+          const size = Buffer.byteLength(JSON.stringify(frame.event));
+          events += size;
+          if (size > 256 * 1024 || events > MAX_EVENTS_BYTES) throw new RemoteWorkerError("Worker events exceeded their bound", accepted);
+          if (frame.event?.kind !== "session") options.onEvent?.(redactExport(frame.event));
+          return;
+        }
+        if (frame.type === "artifact") {
+          const value = frame.artifact;
+          if (result.artifact || !value || value.requestId !== result.receipt?.requestId || !COMMIT_ID.test(value.baseCommit) || !COMMIT_ID.test(value.head) || !DIGEST.test(value.sha256) || value.ref !== `refs/codeflow/results/${value.requestId}` || !Number.isSafeInteger(value.size) || value.size < 1 || value.size > MAX_BUNDLE_BYTES) throw new RemoteWorkerError("Invalid remote artifact manifest");
+          result.artifact = value;
+          result.bytes = Buffer.alloc(value.size);
+          return;
+        }
+        if (frame.type === "chunk") {
+          if (!result.bytes || frame.offset !== artifactOffset || typeof frame.data !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(frame.data)) throw new RemoteWorkerError("Invalid remote artifact chunk");
+          const bytes = Buffer.from(frame.data, "base64");
+          if (!bytes.length || artifactOffset + bytes.length > result.bytes.length) throw new RemoteWorkerError("Remote artifact exceeded its manifest");
+          result.bytes.set(bytes, artifactOffset);
+          artifactOffset += bytes.length;
+          if (artifactOffset === result.bytes.length && frames.some((item) => item.type === "receipt")) finish();
+          return;
+        }
+        throw new RemoteWorkerError("Unknown worker response frame");
+      };
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (data) => {
+        if (done) return;
+        received += Buffer.byteLength(data);
+        if (received > 112 * 1024 * 1024) {
+          finish(new RemoteWorkerError("Remote response exceeded its total bound", accepted));
+          return;
+        }
+        buffer += data;
+        try {
+          let at;
+          while ((at = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, at);
+            buffer = buffer.slice(at + 1);
+            if (Buffer.byteLength(line) > MAX_FRAME_BYTES) throw new RemoteWorkerError("Remote frame exceeds its bound", accepted);
+            handle(JSON.parse(line));
+            if (done) return;
+          }
+          if (Buffer.byteLength(buffer) > MAX_FRAME_BYTES) throw new RemoteWorkerError("Remote frame exceeds its bound", accepted);
+        } catch (error) {
+          finish(error);
+        }
+      });
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (data) => {
+        stderr = (stderr + data).slice(-2e3);
+      });
+      child.on("error", (error) => finish(new RemoteWorkerError(error.message, accepted)));
+      child.on("close", () => {
+        closed = true;
+        clearTimeout(killTimer);
+        if (!done) finish(new RemoteWorkerError(`SSH channel closed before a complete result${stderr ? `: ${redactExport(stderr).trim()}` : ""}`, accepted || frames.some((item) => item.type === "execute")));
+      });
+      child.stdin.on("error", () => void 0);
+      if (options.signal?.aborted) abort();
+    });
+  }
+  async probe(workerId, input = {}) {
+    const target = this.target(workerId, input.repoMapping);
+    for (const commit of [input.baseCommit, input.repositoryBase]) if (commit !== void 0 && !COMMIT_ID.test(commit)) throw new RemoteWorkerError("Worker probe requires exact commit IDs");
+    const value = await this.exchange(target, [{ v: 1, type: "probe", ...input, containerProfile: target.containerProfile }]);
+    return value.probe;
+  }
+  async outcome(record, value) {
+    const receipt = value.receipt, state = receipt?.state ?? "unknown", ambiguous = !terminal(state);
+    const result = { ...value.result ?? receipt?.result ?? { ok: false, finalText: "", error: receipt?.reason ?? "Remote outcome is ambiguous; inspect its receipt before explicitly retrying", errorKind: "other" }, sessionId: void 0, remote: { workerId: record.workerId, requestId: record.requestId, state, receipt: receipt?.fingerprint, ...ambiguous ? { ambiguous: true } : {}, baseCommit: record.baseCommit, resultHead: value.artifact?.head ?? receipt?.artifact?.head } };
+    if (value.artifact && value.bytes) {
+      if (value.artifact.baseCommit !== record.baseCommit || sha256(value.bytes) !== value.artifact.sha256) throw new RemoteWorkerError("Remote artifact failed its digest or accepted base");
+      if (this.artifacts.size >= 32) throw new RemoteWorkerError("Import or discard pending remote artifacts before downloading more than 32 bundles");
+      const folder = await mkdtemp(join(this.directory, "artifact-"));
+      const file = join(folder, "result.bundle");
+      await writeFile(file, value.bytes, { flag: "wx", mode: 384 });
+      this.artifacts.add(file);
+      result.artifact = { ...value.artifact, file };
+    }
+    return result;
+  }
+  async hasRequest(workerId, id) {
+    return !!await this.remembered(workerId, id);
+  }
+  assertScope(record, expected) {
+    if (expected && (record.scope.runId !== expected.runId || !expected.stepIds.includes(record.scope.stepId))) throw new RemoteWorkerError("The private remote capability belongs to a different run or step");
+  }
+  async receipt(workerId, id, options = {}) {
+    const record = await this.remembered(workerId, id);
+    if (!record) throw new RemoteWorkerError("This server has no private capability for that remote request");
+    this.assertScope(record, options.expectedScope);
+    return this.outcome(record, await this.exchange(this.target(workerId), [{ v: 1, type: "receipt", id, capability: record.capability, downloadArtifact: options.downloadArtifact }], { timeoutMs: 9e4 }));
+  }
+  async cancel(workerId, id, options = {}) {
+    const record = await this.remembered(workerId, id);
+    if (!record) throw new RemoteWorkerError("This server has no private capability for that remote request");
+    this.assertScope(record, options.expectedScope);
+    return this.outcome(record, await this.exchange(this.target(workerId), [{ v: 1, type: "cancel", id, capability: record.capability }]));
+  }
+  async execute(input, onEvent) {
+    const target = this.target(input.workerId, input.repoMapping), opts = input.options, agent = input.agent ?? opts.agent;
+    if (!agent) throw new RemoteWorkerError("Remote execution requires an explicit provider");
+    if (opts.interactiveApprovals || opts.teamTools || opts.resumeSessionId) throw new RemoteWorkerError("Remote turns use fresh sessions and structured replies; native approvals, live team tools and resumed sessions are unsupported");
+    if (opts.agentContainer && !target.containerProfile) throw new RemoteWorkerError("Register an explicit worker-local container profile; host container settings and credential volumes are never forwarded");
+    const id = input.requestId ?? randomBytes(16).toString("hex"), baseCommit = await resolveCommit(opts.cwd);
+    await assertTransferTree(opts.cwd, baseCommit);
+    const integrity = await verificationIntegrity(opts.cwd, opts.signal);
+    if (integrity.head !== baseCommit) throw new RemoteWorkerError("The source checkout changed before transfer");
+    const managedPermissions = opts.permissions ? { version: 1, revision: opts.permissions.policyRevision, trust: opts.permissions.trust, toolApprovals: opts.permissions.toolApprovals, delegation: opts.permissions.delegation, required: [...opts.permissions.required] } : void 0;
+    const fingerprint = sha256(JSON.stringify({ managedPermissions, scope: input.scope, repoMapping: input.repoMapping, agent, baseCommit, mode: opts.mode, prompt: opts.prompt, model: opts.model, effort: opts.effort, trust: opts.trust ?? "standard", jsonSchema: opts.jsonSchema }));
+    const prior = await this.remembered(input.workerId, id);
+    if (prior) {
+      if (prior.fingerprint !== fingerprint) throw new RemoteWorkerError("Remote request ID already belongs to another scoped invocation");
+      return this.receipt(input.workerId, id);
+    }
+    const probe = await this.probe(input.workerId, { repoMapping: input.repoMapping, baseCommit, repositoryBase: input.repositoryBase });
+    if (!probe.capabilities.repoMappings.includes(input.repoMapping) || !probe.capabilities.providers.some((item) => item.id === agent && item.available) || target.containerProfile && !probe.capabilities.containerProfiles.includes(target.containerProfile)) throw new RemoteWorkerError("Selected provider, mapping or worker-local container profile is unavailable on the registered worker");
+    const context = await contextManifest(opts.cwd), capability = randomBytes(32).toString("hex"), transfer = probe.hasBase ? void 0 : await sourceBundle(opts.cwd, baseCommit, id, probe.hasRepositoryBase ? input.repositoryBase : void 0);
+    const request = validateWorkerRequest({ managedPermissions, id, capability, scope: input.scope, repoMapping: input.repoMapping, baseCommit, agent, mode: opts.mode, prompt: opts.prompt, model: opts.model, effort: opts.effort, trust: opts.trust ?? "standard", timeoutMs: Math.min(opts.timeoutMs ?? 30 * 6e4, 30 * 6e4), idleTimeoutMs: opts.idleTimeoutMs, jsonSchema: opts.jsonSchema, questionProtocol: opts.questionProtocol, containerProfile: target.containerProfile, context: context.files, ...transfer ? { source: { size: transfer.size, sha256: transfer.sha256, ref: transfer.ref } } : {} });
+    const record = { version: 1, workerId: input.workerId, requestId: id, capability, scope: input.scope, baseCommit, fingerprint, targetFingerprint: targetFingerprint(target), createdAt: Date.now() };
+    await integrity.assert("source transfer");
+    await this.remember(record);
+    const frames = [{ v: 1, type: "begin", request }];
+    if (transfer) for (const chunk of chunks(transfer.data)) frames.push({ v: 1, type: "source", id, capability, ...chunk });
+    for (const [path, bytes] of context.data) for (const chunk of chunks(bytes)) frames.push({ v: 1, type: "context", id, capability, path, ...chunk });
+    frames.push({ v: 1, type: "execute", id, capability });
+    const abort = () => {
+      void this.cancel(input.workerId, id).catch(() => void 0);
+    };
+    opts.signal?.addEventListener("abort", abort, { once: true });
+    try {
+      return await this.outcome(record, await this.exchange(target, frames, { onEvent, signal: opts.signal, timeoutMs: request.timeoutMs + 45e3, onReceipt: (receipt) => input.onReceipt?.({ workerId: input.workerId, requestId: id, baseCommit, state: receipt.state, receipt: receipt.fingerprint, ...receipt.state === "unknown" ? { ambiguous: true } : {} }) }));
+    } catch (error) {
+      return { ok: false, finalText: "", error: redactExport(error.message), errorKind: opts.signal?.aborted ? "cancelled" : "other", remote: { workerId: input.workerId, requestId: id, baseCommit, state: "unknown", ambiguous: true } };
+    } finally {
+      opts.signal?.removeEventListener("abort", abort);
+    }
+  }
+  async importArtifact(repo, artifact, expectedHead) {
+    if (!this.artifacts.has(artifact.file)) throw new RemoteWorkerError("Artifact does not belong to this worker client");
+    try {
+      return await importWorkerArtifact(repo, artifact, expectedHead);
+    } finally {
+      this.artifacts.delete(artifact.file);
+      await rm(resolve(artifact.file, ".."), { recursive: true, force: true });
+    }
+  }
+  async discardArtifact(artifact) {
+    if (this.artifacts.delete(artifact.file)) await rm(resolve(artifact.file, ".."), { recursive: true, force: true });
+  }
+}
+export {
+  RemoteWorkers,
+  SSH_OPTIONS
+};

package/src/remote-workers/durability.js

@@ -0,0 +1,37 @@
+import { lstat, mkdir, open } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+async function syncWorkerDirectory(path) {
+  if (process.platform === "win32") return;
+  const directory = await open(path, "r");
+  try {
+    await directory.sync();
+  } finally {
+    await directory.close();
+  }
+}
+async function durableWorkerDirectory(path, synchronize = syncWorkerDirectory) {
+  const destination = resolve(path), missing = [];
+  let current = destination;
+  for (; ; ) {
+    const info2 = await lstat(current).catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (info2) {
+      if (!info2.isDirectory() || info2.isSymbolicLink()) throw new Error("Worker state must use a regular directory");
+      break;
+    }
+    missing.push(current);
+    const parent = dirname(current);
+    if (parent === current) throw new Error("Worker directory has no existing ancestor");
+    current = parent;
+  }
+  await mkdir(destination, { recursive: true, mode: 448 });
+  const info = await lstat(destination);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Worker state must use a regular directory");
+  for (const directory of new Set(missing.length ? [...missing, current] : [destination, dirname(destination)])) await synchronize(directory);
+}
+export {
+  durableWorkerDirectory,
+  syncWorkerDirectory
+};

package/src/remote-workers/protocol.js

@@ -0,0 +1,68 @@
+import { validateRunPermissions } from "../run-permissions.js";
+const WORKER_PROTOCOL = 1;
+const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const MAX_CONTEXT_BYTES = 16 * 1024 * 1024;
+const CHUNK_BYTES = 192 * 1024;
+const MAX_FRAME_BYTES = 2 * 1024 * 1024;
+const MAX_EVENTS_BYTES = 16 * 1024 * 1024;
+const REQUEST_ID = /^[a-f0-9]{32}$/;
+const CAPABILITY = /^[a-f0-9]{64}$/;
+const COMMIT_ID = /^[a-f0-9]{40,64}$/i;
+const DIGEST = /^[a-f0-9]{64}$/;
+function validateWorkerSelection(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["workerId", "repoMapping"].includes(key)) || !/^[a-z][a-z0-9-]{0,63}$/.test(value.workerId) || !/^[a-z][a-z0-9-]{0,63}$/.test(value.repoMapping)) throw new RemoteWorkerError("Choose a registered worker ID and repository mapping");
+  return { workerId: value.workerId, repoMapping: value.repoMapping };
+}
+class RemoteWorkerError extends Error {
+  constructor(message, ambiguous = false) {
+    super(message);
+    this.ambiguous = ambiguous;
+  }
+}
+function validateWorkerCapabilities(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new RemoteWorkerError("Invalid worker capabilities");
+  const raw = value, mapping = (item) => typeof item === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(item);
+  if (raw.protocol !== 1 || !Array.isArray(raw.providers) || raw.providers.length > 3 || raw.providers.some((provider) => !provider || typeof provider !== "object" || Object.keys(provider).some((key) => !["id", "available"].includes(key)) || !["claude", "codex", "agy"].includes(provider.id) || typeof provider.available !== "boolean") || new Set(raw.providers.map((provider) => provider.id)).size !== raw.providers.length || !Array.isArray(raw.repoMappings) || raw.repoMappings.length > 20 || !raw.repoMappings.every(mapping) || !Array.isArray(raw.containerProfiles) || raw.containerProfiles.length > 20 || !raw.containerProfiles.every(mapping) || raw.resumeSessions !== false || raw.liveTeamTools !== false || raw.interactiveApprovals !== false || raw.stagedContext !== true || raw.maximumBundleBytes !== MAX_BUNDLE_BYTES || raw.maximumContextBytes !== MAX_CONTEXT_BYTES) throw new RemoteWorkerError("Invalid or incompatible bounded worker capabilities");
+  return structuredClone(raw);
+}
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const bounded = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max && !value.includes("\0");
+function contextPath(value) {
+  return typeof value === "string" && value.startsWith(".codeflow-context/") && value.length <= 500 && !/[\\\x00-\x1f\x7f]/.test(value) && !value.split("/").some((part) => !part || part === "." || part === ".." || part.toLowerCase() === ".git") && !/(^|\/)(?:\.env(?:\..*)?|.*\.(?:pem|key))$/i.test(value);
+}
+function validateWorkerRequest(value) {
+  if (!object(value) || !REQUEST_ID.test(String(value.id)) || !CAPABILITY.test(String(value.capability)) || !object(value.scope) || Object.values(value.scope).length !== 3 || ![value.scope.runId, value.scope.stepId, value.scope.threadId].every((item) => bounded(item, 256)) || !bounded(value.repoMapping, 64) || !/^[a-z][a-z0-9-]*$/.test(value.repoMapping) || !COMMIT_ID.test(String(value.baseCommit)) || !["claude", "codex", "agy"].includes(String(value.agent)) || !["read", "write"].includes(String(value.mode)) || !["safe", "standard", "trusted", "full"].includes(String(value.trust)) || !bounded(value.prompt, 512 * 1024) || !Number.isInteger(value.timeoutMs) || value.timeoutMs < 100 || value.timeoutMs > 30 * 6e4) throw new RemoteWorkerError("Invalid or unbounded remote execution request");
+  if (value.model !== void 0 && !/^[A-Za-z0-9][\w.:/[\]@-]{0,99}$/.test(String(value.model)) || value.effort !== void 0 && !/^[a-z]{2,12}$/.test(String(value.effort)) || value.idleTimeoutMs !== void 0 && (!Number.isInteger(value.idleTimeoutMs) || value.idleTimeoutMs < 100 || value.idleTimeoutMs > 30 * 6e4)) throw new RemoteWorkerError("Invalid remote model, effort or idle timeout");
+  if (value.jsonSchema !== void 0 && (!object(value.jsonSchema) || JSON.stringify(value.jsonSchema).length > 128 * 1024)) throw new RemoteWorkerError("Remote output schema exceeds its bound");
+  if (value.containerProfile !== void 0 && !/^[a-z][a-z0-9-]{0,63}$/.test(String(value.containerProfile)) || value.questionProtocol !== void 0 && value.questionProtocol !== "structured") throw new RemoteWorkerError("Invalid worker-local execution profile");
+  if (!Array.isArray(value.context) || value.context.length > 100 || value.context.some((file) => !object(file) || !contextPath(file.path) || typeof file.size !== "number" || !Number.isSafeInteger(file.size) || file.size < 0 || file.size > 8 * 1024 * 1024 || typeof file.sha256 !== "string" || !DIGEST.test(file.sha256)) || value.context.reduce((total, file) => total + file.size, 0) > MAX_CONTEXT_BYTES || new Set(value.context.map((file) => file.path)).size !== value.context.length) throw new RemoteWorkerError("Remote context must contain at most 100 bounded regular reference files");
+  if (value.source !== void 0 && (!object(value.source) || !Number.isSafeInteger(value.source.size) || value.source.size < 1 || value.source.size > MAX_BUNDLE_BYTES || !DIGEST.test(String(value.source.sha256)) || value.source.ref !== `refs/codeflow/transfers/${value.id}`)) throw new RemoteWorkerError("Invalid source bundle manifest");
+  if (value.managedPermissions !== void 0) {
+    try {
+      validateRunPermissions(value.managedPermissions);
+    } catch {
+      throw new RemoteWorkerError("Invalid managed permission policy");
+    }
+  }
+  const allowed = ["managedPermissions", "id", "capability", "scope", "repoMapping", "baseCommit", "agent", "mode", "prompt", "model", "effort", "trust", "timeoutMs", "idleTimeoutMs", "jsonSchema", "questionProtocol", "containerProfile", "source", "context"];
+  if (Object.keys(value).some((key) => !allowed.includes(key))) throw new RemoteWorkerError("Remote requests cannot forward arbitrary environment, callbacks, session handles or paths");
+  return structuredClone(value);
+}
+export {
+  CAPABILITY,
+  CHUNK_BYTES,
+  COMMIT_ID,
+  DIGEST,
+  MAX_BUNDLE_BYTES,
+  MAX_CONTEXT_BYTES,
+  MAX_EVENTS_BYTES,
+  MAX_FRAME_BYTES,
+  REQUEST_ID,
+  RemoteWorkerError,
+  WORKER_PROTOCOL,
+  contextPath,
+  validateWorkerCapabilities,
+  validateWorkerRequest,
+  validateWorkerSelection
+};

package/src/remote-workers/stdio.js

@@ -0,0 +1,138 @@
+import { readFile } from "node:fs/promises";
+import { once } from "node:events";
+import { join } from "node:path";
+import { git } from "../git.js";
+import { chunks } from "./bundles.js";
+import { MAX_FRAME_BYTES, RemoteWorkerError, validateWorkerRequest } from "./protocol.js";
+async function serveWorker(worker) {
+  const controller = new AbortController();
+  let buffer = "", frames = 0, finished = false, executing = false;
+  let request, source, sourceOffset = 0;
+  const context = /* @__PURE__ */ new Map(), offsets = /* @__PURE__ */ new Map();
+  let output = Promise.resolve();
+  const write = async (frame) => {
+    const line = JSON.stringify(frame) + "\n";
+    if (Buffer.byteLength(line) > MAX_FRAME_BYTES) throw new RemoteWorkerError("Worker response frame exceeds its bound");
+    if (!process.stdout.write(line)) await once(process.stdout, "drain");
+  };
+  const send = (frame) => {
+    const next = output.then(() => write(frame));
+    output = next.catch(() => void 0);
+    return next;
+  };
+  const uploadDeadline = setTimeout(() => {
+    void fail(new RemoteWorkerError("Worker channel did not complete its upload within 30 seconds"));
+  }, 3e4);
+  const close = () => {
+    finished = true;
+    clearTimeout(uploadDeadline);
+    process.stdin.destroy();
+  };
+  const fail = async (error) => {
+    controller.abort();
+    await send({ v: 1, type: "error", message: error.message.slice(0, 2e3) }).catch(() => void 0);
+    close();
+  };
+  const owned = (frame) => {
+    if (!request || frame.id !== request.id || frame.capability !== request.capability) throw new RemoteWorkerError("Frame does not own this scoped request");
+  };
+  const handle = async (frame) => {
+    if (!frame || frame.v !== 1) throw new RemoteWorkerError("Invalid protocol version or excessive frames");
+    if (frame.type === "probe") {
+      const repo = frame.repoMapping ? worker.repo(frame.repoMapping) : void 0;
+      const exists = async (commit) => !!repo && !!commit && /^[a-f0-9]{40,64}$/i.test(commit) && !(await git(["cat-file", "-e", `${commit}^{commit}`], repo, { timeoutMs: 1e4 })).code;
+      await send({ v: 1, type: "probe", capabilities: await worker.capabilities(frame.containerProfile, frame.discoverModels === true), hasBase: await exists(frame.baseCommit), hasRepositoryBase: await exists(frame.repositoryBase) });
+      close();
+      return;
+    }
+    if (frame.type === "receipt" || frame.type === "cancel") {
+      const receipt = frame.type === "receipt" ? await worker.receipt(frame.id, frame.capability) : await worker.cancel(frame.id, frame.capability);
+      await send({ v: 1, type: "receipt", receipt });
+      if (frame.type === "receipt" && frame.downloadArtifact !== false && receipt.artifact) {
+        const artifact = receipt.artifact, file = join(worker.config.root, "requests", frame.id, "result.bundle");
+        await send({ v: 1, type: "artifact", artifact });
+        for (const chunk of chunks(await readFile(file))) await send({ v: 1, type: "chunk", ...chunk });
+      }
+      if (!executing) close();
+      return;
+    }
+    if (frame.type === "begin") {
+      if (request || executing) throw new RemoteWorkerError("Only one execution is allowed per channel");
+      request = validateWorkerRequest(frame.request);
+      if (request.source) source = Buffer.alloc(request.source.size);
+      for (const file of request.context) {
+        context.set(file.path, Buffer.alloc(file.size));
+        offsets.set(file.path, 0);
+      }
+      return;
+    }
+    owned(frame);
+    if (frame.type === "source" || frame.type === "context") {
+      if (executing || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(frame.data)) throw new RemoteWorkerError("Invalid binary transfer frame");
+      const data = Buffer.from(frame.data, "base64"), target = frame.type === "source" ? source : context.get(frame.path ?? ""), offset = frame.type === "source" ? sourceOffset : offsets.get(frame.path ?? "");
+      if (!target || frame.offset !== offset || !data.length || frame.offset + data.length > target.length) throw new RemoteWorkerError("Transfer offsets or file identity do not match the accepted manifest");
+      target.set(data, frame.offset);
+      if (frame.type === "source") sourceOffset += data.length;
+      else offsets.set(frame.path, frame.offset + data.length);
+      return;
+    }
+    if (frame.type !== "execute" || executing || !request || source && sourceOffset !== source.length || request.context.some((file) => offsets.get(file.path) !== file.size)) throw new RemoteWorkerError("The accepted transfer is incomplete or already executing");
+    executing = true;
+    clearTimeout(uploadDeadline);
+    void worker.execute(request, source, context, (event) => {
+      void send({ v: 1, type: "event", event }).catch(() => controller.abort());
+    }, (receipt) => {
+      void send({ v: 1, type: receipt.state === "accepted" ? "accepted" : "heartbeat", receipt }).catch(() => controller.abort());
+    }, controller.signal).then(async ({ result, receipt, artifact }) => {
+      if (artifact) {
+        const { file, ...manifest } = artifact;
+        await send({ v: 1, type: "artifact", artifact: manifest });
+        for (const chunk of chunks(await readFile(file))) await send({ v: 1, type: "chunk", ...chunk });
+      }
+      await send({ v: 1, type: "result", receipt, result });
+      close();
+    }).catch(fail);
+  };
+  let queue = Promise.resolve();
+  await send({ v: 1, type: "hello", protocol: 1 });
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (data) => {
+    if (finished) return;
+    buffer += data;
+    if (Buffer.byteLength(buffer) > MAX_FRAME_BYTES && !buffer.includes("\n")) {
+      void fail(new RemoteWorkerError("Worker input frame exceeds its bound"));
+      return;
+    }
+    let at;
+    while ((at = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, at);
+      buffer = buffer.slice(at + 1);
+      if (++frames > 1e3 || Buffer.byteLength(line) > MAX_FRAME_BYTES) {
+        void fail(new RemoteWorkerError("Worker frame limit exceeded"));
+        return;
+      }
+      queue = queue.then(async () => {
+        if (finished) return;
+        if (Buffer.byteLength(line) > MAX_FRAME_BYTES) throw new RemoteWorkerError("Worker input frame exceeds its bound");
+        await handle(JSON.parse(line));
+      }).catch(fail);
+    }
+  });
+  process.stdin.on("end", () => {
+    if (!finished) controller.abort();
+  });
+  process.stdout.on("error", () => controller.abort());
+  process.on("SIGTERM", () => controller.abort());
+  process.on("SIGHUP", () => controller.abort());
+  return new Promise((resolve) => {
+    const timer = setInterval(() => {
+      if (finished) {
+        clearInterval(timer);
+        resolve();
+      }
+    }, 20);
+  });
+}
+export {
+  serveWorker
+};