drej 0.4.0 → 0.5.0

package/dist/index.js

@@ -0,0 +1,1096 @@
+// ../../core/src/ledger.ts
+var LedgerEvent = /* @__PURE__ */ ((LedgerEvent2) => {
+  LedgerEvent2["RunStarted"] = "run_started";
+  LedgerEvent2["StepStart"] = "step_start";
+  LedgerEvent2["StepComplete"] = "step_complete";
+  LedgerEvent2["StepFailed"] = "step_failed";
+  LedgerEvent2["StepRolledBack"] = "step_rolled_back";
+  LedgerEvent2["WorkflowComplete"] = "workflow_complete";
+  LedgerEvent2["WorkflowFailed"] = "workflow_failed";
+  LedgerEvent2["Checkpoint"] = "checkpoint";
+  LedgerEvent2["ExecEvent"] = "exec_event";
+  LedgerEvent2["Snapshot"] = "snapshot";
+  return LedgerEvent2;
+})(LedgerEvent || {});
+
+// ../../core/src/logger.ts
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+
+// ../../core/src/workflow.ts
+var Workflow = class _Workflow {
+  constructor(name, runId, steps, deps) {
+    this.steps = steps;
+    this.deps = deps;
+    this.name = name;
+    this.runId = runId;
+    this.log = deps.logger ?? noopLogger;
+  }
+  steps;
+  deps;
+  name;
+  runId;
+  _status = "idle";
+  completedSteps = /* @__PURE__ */ new Map();
+  log;
+  get status() {
+    return this._status;
+  }
+  async callHook(name, info) {
+    const hook = this.deps.hooks?.[name];
+    if (!hook) return;
+    try {
+      await hook(info);
+    } catch (err) {
+      this.log.warn(`hook ${name} threw`, { error: String(err) });
+    }
+  }
+  async run(input, startFromStep = 0) {
+    this._status = "running";
+    this.log.info("workflow started", { workflowName: this.name, runId: this.runId, startFromStep, totalSteps: this.steps.length });
+    let current = startFromStep > 0 ? this.completedSteps.get(startFromStep - 1)?.output ?? input : input;
+    for (let i = startFromStep; i < this.steps.length; i++) {
+      const step = this.steps[i];
+      const ctx = this.makeContext(i);
+      this.log.debug("step starting", { workflowName: this.name, runId: this.runId, stepIndex: i, stepId: step.id });
+      await this.callHook("onStepStart", { workflowName: this.name, runId: this.runId, stepIndex: i, stepId: step.id });
+      await ctx.emit({ ts: Date.now(), workflowName: this.name, runId: this.runId, stepIndex: i, event: "step_start" /* StepStart */ });
+      try {
+        const output = await step.run(current, ctx);
+        this.completedSteps.set(i, { output, completedAt: Date.now() });
+        current = output;
+        this.log.debug("step complete", { workflowName: this.name, runId: this.runId, stepIndex: i, stepId: step.id });
+        await this.callHook("onStepComplete", { workflowName: this.name, runId: this.runId, stepIndex: i, stepId: step.id, output });
+        await ctx.emit({
+          ts: Date.now(),
+          workflowName: this.name,
+          runId: this.runId,
+          stepIndex: i,
+          event: "step_complete" /* StepComplete */,
+          payload: output
+        });
+        await this.deps.adapter.append({
+          ts: Date.now(),
+          workflowName: this.name,
+          runId: this.runId,
+          stepIndex: i + 1,
+          event: "checkpoint" /* Checkpoint */,
+          payload: this.snapshot()
+        });
+      } catch (err) {
+        this._status = "failed";
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.log.error("step failed", { workflowName: this.name, runId: this.runId, stepIndex: i, stepId: step.id, error: error.message });
+        await this.callHook("onStepFailed", { workflowName: this.name, runId: this.runId, stepIndex: i, stepId: step.id, error });
+        await ctx.emit({
+          ts: Date.now(),
+          workflowName: this.name,
+          runId: this.runId,
+          stepIndex: i,
+          event: "step_failed" /* StepFailed */,
+          error: error.message
+        });
+        await this.callHook("onWorkflowFailed", { workflowName: this.name, runId: this.runId, error });
+        throw error;
+      }
+    }
+    this._status = "completed";
+    this.log.info("workflow complete", { workflowName: this.name, runId: this.runId });
+    await this.deps.adapter.append({
+      ts: Date.now(),
+      workflowName: this.name,
+      runId: this.runId,
+      stepIndex: -1,
+      event: "workflow_complete" /* WorkflowComplete */
+    });
+    await this.callHook("onWorkflowComplete", { workflowName: this.name, runId: this.runId, output: current });
+    return current;
+  }
+  async rollback(toStep = 0) {
+    this.log.info("rolling back workflow", { workflowName: this.name, runId: this.runId });
+    const stepsToUndo = [...this.completedSteps.entries()].filter(([i]) => i >= toStep).sort(([a], [b]) => b - a);
+    for (const [i, result] of stepsToUndo) {
+      const step = this.steps[i];
+      if (step.rollback) {
+        const ctx = this.makeContext(i);
+        this.log.debug("rolling back step", { workflowName: this.name, runId: this.runId, stepIndex: i, stepId: step.id });
+        await step.rollback(result.output, ctx);
+        await this.callHook("onStepRolledBack", { workflowName: this.name, runId: this.runId, stepIndex: i, stepId: step.id });
+        await ctx.emit({
+          ts: Date.now(),
+          workflowName: this.name,
+          runId: this.runId,
+          stepIndex: i,
+          event: "step_rolled_back" /* StepRolledBack */
+        });
+        this.completedSteps.delete(i);
+      }
+    }
+    this._status = "rolled_back";
+    this.log.info("workflow rolled back", { workflowName: this.name, runId: this.runId });
+    await this.deps.adapter.append({
+      ts: Date.now(),
+      workflowName: this.name,
+      runId: this.runId,
+      stepIndex: -1,
+      event: "workflow_failed" /* WorkflowFailed */,
+      error: "rolled_back"
+    });
+    await this.callHook("onWorkflowFailed", { workflowName: this.name, runId: this.runId, error: new Error("rolled_back") });
+  }
+  snapshot() {
+    return {
+      workflowName: this.name,
+      runId: this.runId,
+      stepIndex: this.completedSteps.size,
+      completedSteps: Object.fromEntries(this.completedSteps),
+      timestamp: Date.now()
+    };
+  }
+  static async resumeFromLedger(workflowName, runId, steps, deps) {
+    const wf = new _Workflow(workflowName, runId, steps, deps);
+    const entry = await deps.adapter.lastCheckpoint(workflowName, runId);
+    if (entry?.payload) {
+      const cp = entry.payload;
+      for (const [idx, result] of Object.entries(cp.completedSteps)) {
+        wf.completedSteps.set(Number(idx), result);
+      }
+      const lastOutput = cp.completedSteps[cp.stepIndex - 1]?.output ?? {};
+      deps.logger?.info("resuming workflow from checkpoint", { workflowName, runId, nextStep: cp.stepIndex });
+      return { workflow: wf, nextStep: cp.stepIndex, lastOutput };
+    }
+    return { workflow: wf, nextStep: 0, lastOutput: {} };
+  }
+  makeContext(stepIndex) {
+    return {
+      workflowName: this.name,
+      runId: this.runId,
+      stepIndex,
+      control: this.deps.control,
+      resolveExec: this.deps.resolveExec,
+      emit: (entry) => this.deps.adapter.append(entry)
+    };
+  }
+};
+
+// ../../opensandbox/src/control.ts
+function flattenSnapshot(raw) {
+  return { id: raw.id, sandboxId: raw.sandboxId, state: raw.status.state, createdAt: raw.createdAt };
+}
+var OpenSandboxError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "OpenSandboxError";
+  }
+  status;
+};
+var ControlClient = class {
+  baseUrl;
+  apiKey;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        "OPEN-SANDBOX-API-KEY": this.apiKey,
+        ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new OpenSandboxError(text || "OpenSandbox API error", res.status);
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  createSandbox(options) {
+    return this.request("POST", "/v1/sandboxes", options);
+  }
+  listSandboxes(options = {}) {
+    const params = new URLSearchParams();
+    if (options.state) params.set("state", options.state);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    if (options.offset !== void 0) params.set("offset", String(options.offset));
+    const qs = params.toString();
+    return this.request("GET", `/v1/sandboxes${qs ? `?${qs}` : ""}`);
+  }
+  getSandbox(id) {
+    return this.request("GET", `/v1/sandboxes/${id}`);
+  }
+  deleteSandbox(id) {
+    return this.request("DELETE", `/v1/sandboxes/${id}`);
+  }
+  pauseSandbox(id) {
+    return this.request("POST", `/v1/sandboxes/${id}/pause`);
+  }
+  resumeSandbox(id) {
+    return this.request("POST", `/v1/sandboxes/${id}/resume`);
+  }
+  renewExpiration(id) {
+    return this.request("POST", `/v1/sandboxes/${id}/renew-expiration`);
+  }
+  // Returns { endpoint, headers: { "X-EXECD-ACCESS-TOKEN": "..." } }
+  getEndpoint(sandboxId, port) {
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/endpoints/${port}`);
+  }
+  getDiagnosticLogs(sandboxId) {
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/diagnostics/logs`);
+  }
+  getDiagnosticEvents(sandboxId) {
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/diagnostics/events`);
+  }
+  async createSnapshot(sandboxId) {
+    const raw = await this.request("POST", `/v1/sandboxes/${sandboxId}/snapshots`);
+    return flattenSnapshot(raw);
+  }
+  listSnapshots(options = {}) {
+    const params = new URLSearchParams();
+    if (options.sandboxId) params.set("sandboxId", options.sandboxId);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    if (options.offset !== void 0) params.set("offset", String(options.offset));
+    const qs = params.toString();
+    return this.request("GET", `/v1/snapshots${qs ? `?${qs}` : ""}`);
+  }
+  async getSnapshot(id) {
+    const raw = await this.request("GET", `/v1/snapshots/${id}`);
+    return flattenSnapshot(raw);
+  }
+  deleteSnapshot(id) {
+    return this.request("DELETE", `/v1/snapshots/${id}`);
+  }
+};
+
+// ../../opensandbox/src/exec.ts
+async function* parseSSE(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const blocks = buffer.split("\n\n");
+      buffer = blocks.pop() ?? "";
+      for (const block of blocks) {
+        const trimmed = block.trim();
+        if (!trimmed) continue;
+        if (trimmed.startsWith("{")) {
+          try {
+            yield JSON.parse(trimmed);
+          } catch {
+          }
+        } else {
+          let type;
+          let data;
+          for (const line of block.split("\n")) {
+            if (line.startsWith("event:")) type = line.slice(6).trim();
+            else if (line.startsWith("data:")) data = line.slice(5).trim();
+          }
+          if (data !== void 0) {
+            yield { type: type ?? "message", ...JSON.parse(data) };
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+var ExecClient = class {
+  baseUrl;
+  accessToken;
+  constructor(options) {
+    this.baseUrl = (options.baseUrl ?? "http://localhost:44772").replace(/\/$/, "");
+    this.accessToken = options.accessToken;
+  }
+  get authHeader() {
+    return { "X-EXECD-ACCESS-TOKEN": this.accessToken };
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        ...this.authHeader,
+        ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(text || `execd error ${res.status}`);
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  async *streamRequest(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        ...this.authHeader,
+        ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(text || `execd error ${res.status}`);
+    }
+    if (!res.body) return;
+    yield* parseSSE(res.body);
+  }
+  ping() {
+    return this.request("GET", "/ping");
+  }
+  listContexts(language) {
+    const qs = language ? `?language=${encodeURIComponent(language)}` : "";
+    return this.request("GET", `/code/contexts${qs}`);
+  }
+  clearContexts(language) {
+    const qs = language ? `?language=${encodeURIComponent(language)}` : "";
+    return this.request("DELETE", `/code/contexts${qs}`);
+  }
+  deleteContext(contextId) {
+    return this.request("DELETE", `/code/contexts/${contextId}`);
+  }
+  createContext(language) {
+    return this.request("POST", "/code/context", { language });
+  }
+  async *executeCode(options) {
+    yield* this.streamRequest("POST", "/code", options);
+  }
+  interruptCode() {
+    return this.request("DELETE", "/code");
+  }
+  async *executeCommand(options) {
+    yield* this.streamRequest("POST", "/command", options);
+  }
+  interruptCommand() {
+    return this.request("DELETE", "/command");
+  }
+  getCommandStatus(session) {
+    return this.request("GET", `/command/status/${session}`);
+  }
+  getCommandOutput(session) {
+    return this.request("GET", `/command/output/${session}`);
+  }
+  getFileInfo(path) {
+    return this.request("GET", `/files/info?path=${encodeURIComponent(path)}`);
+  }
+  deleteFile(path) {
+    return this.request("DELETE", `/files?path=${encodeURIComponent(path)}`);
+  }
+  setPermissions(path, mode) {
+    return this.request("POST", "/files/permissions", { path, mode });
+  }
+  moveFile(from, to) {
+    return this.request("POST", "/files/mv", { from, to });
+  }
+  searchFiles(pattern, dir) {
+    const params = new URLSearchParams({ pattern });
+    if (dir) params.set("dir", dir);
+    return this.request("GET", `/files/search?${params}`);
+  }
+  replaceInFiles(replacements) {
+    return this.request("POST", "/files/replace", { replacements });
+  }
+  async uploadFile(path, content) {
+    const formData = new FormData();
+    formData.append("metadata", new File([JSON.stringify({ path })], "metadata.json", { type: "application/json" }));
+    formData.append("file", new File([content], path.split("/").pop() ?? "file", { type: "application/octet-stream" }));
+    const res = await fetch(`${this.baseUrl}/files/upload`, {
+      method: "POST",
+      headers: this.authHeader,
+      body: formData
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(text || `execd error ${res.status}`);
+    }
+  }
+  async downloadFile(path) {
+    const res = await fetch(`${this.baseUrl}/files/download?path=${encodeURIComponent(path)}`, {
+      headers: this.authHeader
+    });
+    if (!res.ok) throw new Error(`execd error ${res.status}`);
+    if (!res.body) throw new Error("empty response body");
+    return res.body;
+  }
+  listDirectory(path, depth) {
+    const params = new URLSearchParams({ path });
+    if (depth !== void 0) params.set("depth", String(depth));
+    return this.request("GET", `/directories/list?${params}`);
+  }
+  createDirectory(path) {
+    return this.request("POST", "/directories", { path });
+  }
+  deleteDirectory(path) {
+    return this.request("DELETE", `/directories?path=${encodeURIComponent(path)}`);
+  }
+  getMetrics() {
+    return this.request("GET", "/metrics");
+  }
+  async *watchMetrics() {
+    yield* this.streamRequest("GET", "/metrics/watch");
+  }
+};
+
+// ../../core/src/steps.ts
+async function resolveExecClient(control, sandboxId, retries = 15, delayMs = 1e3) {
+  const ep = await control.getEndpoint(sandboxId, 44772);
+  const baseUrl = ep.endpoint.startsWith("http") ? ep.endpoint : `http://${ep.endpoint}`;
+  const token = ep.headers?.["X-EXECD-ACCESS-TOKEN"] ?? "";
+  const client = new ExecClient({ baseUrl, accessToken: token });
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      await client.listContexts();
+      return client;
+    } catch {
+      if (attempt === retries) throw new Error(`execd not ready after ${retries}s for sandbox ${sandboxId}`);
+      await new Promise((r) => setTimeout(r, delayMs));
+    }
+  }
+  throw new Error("unreachable");
+}
+function shouldSnapshot(config, stepIndex) {
+  if (config.afterSteps?.includes(stepIndex)) return true;
+  if (config.everyNSteps && (stepIndex + 1) % config.everyNSteps === 0) return true;
+  return false;
+}
+async function waitForSnapshot(control, snapshotId, timeoutMs = 12e4) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const snap = await control.getSnapshot(snapshotId);
+    if (snap.state === "Ready") return;
+    if (snap.state === "Failed") throw new Error(`Snapshot ${snapshotId} failed`);
+    await new Promise((r) => setTimeout(r, 2e3));
+  }
+  throw new Error(`Snapshot ${snapshotId} did not become ready within ${timeoutMs}ms`);
+}
+function getPath(obj, path) {
+  return path.split(".").reduce((cur, key) => {
+    if (cur === null || cur === void 0 || typeof cur !== "object") return void 0;
+    return cur[key];
+  }, obj);
+}
+function interpolate(template, state) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const val = state[key];
+    return val !== void 0 ? String(val) : `{{${key}}}`;
+  });
+}
+function evaluate(predicate, state) {
+  switch (predicate.op) {
+    case "eq":
+      return getPath(state, predicate.field) === predicate.value;
+    case "neq":
+      return getPath(state, predicate.field) !== predicate.value;
+    case "gt":
+      return Number(getPath(state, predicate.field)) > predicate.value;
+    case "lt":
+      return Number(getPath(state, predicate.field)) < predicate.value;
+    case "gte":
+      return Number(getPath(state, predicate.field)) >= predicate.value;
+    case "lte":
+      return Number(getPath(state, predicate.field)) <= predicate.value;
+    case "exists":
+      return getPath(state, predicate.field) !== void 0;
+    case "not_exists":
+      return getPath(state, predicate.field) === void 0;
+    case "and":
+      return predicate.predicates.every((p) => evaluate(p, state));
+    case "or":
+      return predicate.predicates.some((p) => evaluate(p, state));
+  }
+}
+function buildStep(def) {
+  switch (def.type) {
+    case "create_sandbox":
+      return {
+        id: "create_sandbox",
+        async run(input, ctx) {
+          const state = input ?? {};
+          const sb = await ctx.control.createSandbox({
+            image: def.image,
+            snapshotId: def.snapshotId,
+            timeout: def.timeout,
+            entrypoint: def.entrypoint,
+            env: def.env,
+            metadata: def.metadata,
+            resourceLimits: def.resourceLimits
+          });
+          const deadline = Date.now() + 12e4;
+          while (Date.now() < deadline) {
+            const s = await ctx.control.getSandbox(sb.id);
+            if (s.status.state === "Running") break;
+            if (s.status.state === "Failed" || s.status.state === "Terminated") {
+              throw new Error(`Sandbox ${sb.id} entered state ${s.status.state}: ${s.status.message ?? ""}`);
+            }
+            await new Promise((r) => setTimeout(r, 1e3));
+          }
+          return { ...state, sandboxId: sb.id };
+        },
+        async rollback(output, ctx) {
+          const state = output;
+          if (state.sandboxId) await ctx.control.deleteSandbox(state.sandboxId);
+        }
+      };
+    case "exec_code":
+      return {
+        id: "exec_code",
+        async run(input, ctx) {
+          const state = input ?? {};
+          if (!state.sandboxId) throw new Error("exec_code requires sandboxId in workflow state");
+          const exec = await ctx.resolveExec(state.sandboxId);
+          const events = [];
+          for await (const ev of exec.executeCode({ code: def.code, context: def.context })) {
+            await ctx.emit({
+              ts: Date.now(),
+              workflowName: ctx.workflowName,
+              runId: ctx.runId,
+              stepIndex: ctx.stepIndex,
+              event: "exec_event" /* ExecEvent */,
+              payload: ev
+            });
+            events.push(ev);
+          }
+          return { ...state, codeEvents: events };
+        }
+      };
+    case "exec_command":
+      return {
+        id: "exec_command",
+        async run(input, ctx) {
+          const state = input ?? {};
+          if (!state.sandboxId) throw new Error("exec_command requires sandboxId in workflow state");
+          const exec = await ctx.resolveExec(state.sandboxId);
+          const raw = interpolate(def.command, state);
+          const command = `echo ${Buffer.from(raw).toString("base64")} | base64 -d | bash`;
+          const events = [];
+          for await (const ev of exec.executeCommand({ command, cwd: def.cwd, envs: def.envs })) {
+            await ctx.emit({
+              ts: Date.now(),
+              workflowName: ctx.workflowName,
+              runId: ctx.runId,
+              stepIndex: ctx.stepIndex,
+              event: "exec_event" /* ExecEvent */,
+              payload: ev
+            });
+            events.push(ev);
+          }
+          return { ...state, commandEvents: events };
+        }
+      };
+    case "delete_sandbox":
+      return {
+        id: "delete_sandbox",
+        async run(input, ctx) {
+          const state = input ?? {};
+          if (state.sandboxId) await ctx.control.deleteSandbox(state.sandboxId);
+          return { ...state, sandboxId: void 0 };
+        }
+      };
+    case "write_file":
+      return {
+        id: "write_file",
+        async run(input, ctx) {
+          const state = input ?? {};
+          if (!state.sandboxId) throw new Error("write_file requires sandboxId in workflow state");
+          const exec = await ctx.resolveExec(state.sandboxId);
+          const content = def.encoding === "base64" ? Buffer.from(def.content, "base64").buffer : def.content;
+          await exec.uploadFile(def.path, content);
+          return state;
+        }
+      };
+    case "retry": {
+      const child = buildStep(def.step);
+      return {
+        id: "retry",
+        rollback: child.rollback,
+        async run(input, ctx) {
+          let lastErr;
+          for (let attempt = 0; attempt < def.maxAttempts; attempt++) {
+            try {
+              return await child.run(input, ctx);
+            } catch (err) {
+              lastErr = err;
+              if (attempt < def.maxAttempts - 1) {
+                const base = def.delayMs ?? 500;
+                const delay = def.backoff === "exponential" ? base * Math.pow(2, attempt) : base;
+                await ctx.emit({
+                  ts: Date.now(),
+                  workflowName: ctx.workflowName,
+                  runId: ctx.runId,
+                  stepIndex: ctx.stepIndex,
+                  event: "exec_event" /* ExecEvent */,
+                  payload: { type: "retry_attempt", attempt: attempt + 1, maxAttempts: def.maxAttempts, error: String(err) }
+                });
+                await new Promise((r) => setTimeout(r, delay));
+              }
+            }
+          }
+          throw lastErr;
+        }
+      };
+    }
+    case "conditional": {
+      const thenSteps = def.then.map(buildStep);
+      const elseSteps = (def.else ?? []).map(buildStep);
+      return {
+        id: "conditional",
+        async run(input, ctx) {
+          const branch = evaluate(def.condition, input) ? thenSteps : elseSteps;
+          let current = input;
+          for (const step of branch) {
+            current = await step.run(current, ctx);
+          }
+          return current;
+        }
+      };
+    }
+    case "loop": {
+      return {
+        id: "loop",
+        async run(input, ctx) {
+          const arr = def.items ?? (def.over ? getPath(input, def.over) : void 0);
+          if (!Array.isArray(arr)) throw new Error(`loop: must provide either "items" or "over" pointing to an array in workflow state`);
+          const runIteration = async (item, index) => {
+            const iterState = { ...input, [def.as]: item, loopIndex: index };
+            let current = iterState;
+            for (const step of def.steps.map(buildStep)) {
+              current = await step.run(current, ctx);
+            }
+            return current;
+          };
+          const loopResults = def.concurrently ? await Promise.all(arr.map((item, i) => runIteration(item, i))) : await arr.reduce(async (accP, item, i) => {
+            const acc = await accP;
+            acc.push(await runIteration(item, i));
+            return acc;
+          }, Promise.resolve([]));
+          return { ...input, loopResults };
+        }
+      };
+    }
+    case "parallel": {
+      return {
+        id: "parallel",
+        async run(input, ctx) {
+          const results = await Promise.all(
+            def.steps.map((stepDef, branchIndex) => {
+              const branchCtx = {
+                ...ctx,
+                stepIndex: ctx.stepIndex * 1e3 + branchIndex,
+                emit: (entry) => ctx.emit({ ...entry, branch: branchIndex })
+              };
+              return buildStep(stepDef).run(input, branchCtx);
+            })
+          );
+          const merged = results.reduce(
+            (acc, result) => ({ ...acc, ...result }),
+            input
+          );
+          return { ...merged, parallelResults: results };
+        }
+      };
+    }
+    case "sequence": {
+      const childSteps = def.steps.map(buildStep);
+      return {
+        id: "sequence",
+        async run(input, ctx) {
+          let current = input;
+          for (const step of childSteps) {
+            current = await step.run(current, ctx);
+          }
+          return current;
+        },
+        async rollback(input, ctx) {
+          for (const step of [...childSteps].reverse()) {
+            if (step.rollback) await step.rollback(input, ctx);
+          }
+        }
+      };
+    }
+  }
+}
+
+// src/client.ts
+var DrejError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "DrejError";
+  }
+  status;
+};
+var WorkflowRun = class {
+  constructor(name, id, _events) {
+    this.name = name;
+    this.id = id;
+    this._events = _events;
+  }
+  name;
+  id;
+  _events;
+  [Symbol.asyncIterator]() {
+    return this._events;
+  }
+};
+var DrejClient = class {
+  control;
+  adapter;
+  constructor(options) {
+    this.control = new ControlClient({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey ?? ""
+    });
+    this.adapter = options.adapter;
+  }
+  /** Call once before first use when using a DB-backed adapter. */
+  async connect() {
+    await this.adapter.connect?.();
+  }
+  /** Releases adapter resources (e.g. closes DB connection pool). */
+  async close() {
+    await this.adapter.close?.();
+  }
+  // ── Sandbox management ────────────────────────────────────────────────────
+  createSandbox(options) {
+    return this.control.createSandbox(options);
+  }
+  listSandboxes(options = {}) {
+    return this.control.listSandboxes(options);
+  }
+  getSandbox(id) {
+    return this.control.getSandbox(id);
+  }
+  deleteSandbox(id) {
+    return this.control.deleteSandbox(id);
+  }
+  pauseSandbox(id) {
+    return this.control.pauseSandbox(id);
+  }
+  resumeSandbox(id) {
+    return this.control.resumeSandbox(id);
+  }
+  renewSandbox(id) {
+    return this.control.renewExpiration(id);
+  }
+  async waitForRunning(id, options = {}) {
+    const { timeoutMs = 6e4, pollIntervalMs = 1e3 } = options;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const sandbox = await this.control.getSandbox(id);
+      const { state } = sandbox.status;
+      if (state === "Running") return sandbox;
+      if (state === "Failed" || state === "Terminated") {
+        throw new DrejError(`Sandbox ${id} entered state ${state}`, 500);
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    throw new DrejError(`Sandbox ${id} did not reach Running within ${timeoutMs}ms`, 408);
+  }
+  // ── Snapshot management ───────────────────────────────────────────────────
+  createSnapshot(sandboxId) {
+    return this.control.createSnapshot(sandboxId);
+  }
+  listSnapshots(options = {}) {
+    return this.control.listSnapshots(options);
+  }
+  getSnapshot(id) {
+    return this.control.getSnapshot(id);
+  }
+  deleteSnapshot(id) {
+    return this.control.deleteSnapshot(id);
+  }
+  // ── Diagnostics ───────────────────────────────────────────────────────────
+  getDiagnosticLogs(sandboxId) {
+    return this.control.getDiagnosticLogs(sandboxId);
+  }
+  getDiagnosticEvents(sandboxId) {
+    return this.control.getDiagnosticEvents(sandboxId);
+  }
+  // ── Workflow execution ────────────────────────────────────────────────────
+  async run(w, options) {
+    const { name, steps } = w.build();
+    const runId = crypto.randomUUID();
+    return new WorkflowRun(name, runId, this._execute(name, runId, steps, options));
+  }
+  async replayFromSnapshot(name, runId, w) {
+    const entries = await this.adapter.readAll(name, runId);
+    const snapEntry = [...entries].reverse().find((e) => e.event === "snapshot" /* Snapshot */);
+    if (!snapEntry) throw new DrejError(`No snapshot found in ledger for ${name}/${runId}`, 404);
+    const { snapshotId } = snapEntry.payload;
+    const { name: wfName, steps } = w.build();
+    const replaySteps = steps.map(
+      (s) => s.type === "create_sandbox" ? { ...s, snapshotId } : s
+    );
+    const replayRunId = crypto.randomUUID();
+    return new WorkflowRun(wfName, replayRunId, this._execute(wfName, replayRunId, replaySteps));
+  }
+  async resumeRun(name, runId, w) {
+    const { steps } = w.build();
+    const workflowSteps = steps.map(buildStep);
+    const stream = this._makeStream(name, runId, async (teeDeps) => {
+      const { workflow: workflow2, nextStep, lastOutput } = await Workflow.resumeFromLedger(
+        name,
+        runId,
+        workflowSteps,
+        teeDeps
+      );
+      try {
+        await workflow2.run(lastOutput, nextStep);
+      } catch {
+        try {
+          await workflow2.rollback();
+        } catch {
+        }
+      }
+    });
+    return new WorkflowRun(name, runId, stream);
+  }
+  // ── Adapter access ────────────────────────────────────────────────────────
+  listRuns(workflowName) {
+    return this.adapter.listRuns(workflowName);
+  }
+  getRunLedger(workflowName, runId) {
+    return this.adapter.readAll(workflowName, runId);
+  }
+  // ── Internal ──────────────────────────────────────────────────────────────
+  _execute(name, runId, steps, options) {
+    return this._makeStream(name, runId, async (teeDeps) => {
+      const snapshotHook = options?.snapshotConfig ? {
+        async onStepComplete({ workflowName: wfName, runId: rid, stepIndex, output }) {
+          if (!shouldSnapshot(options.snapshotConfig, stepIndex)) return;
+          const sandboxId = output?.sandboxId;
+          if (typeof sandboxId !== "string") return;
+          const snap = await teeDeps.control.createSnapshot(sandboxId);
+          await waitForSnapshot(teeDeps.control, snap.id);
+          await teeDeps.adapter.append({
+            ts: Date.now(),
+            workflowName: wfName,
+            runId: rid,
+            stepIndex,
+            event: "snapshot" /* Snapshot */,
+            payload: { snapshotId: snap.id, sandboxId }
+          });
+        }
+      } : void 0;
+      const deps = { ...teeDeps, hooks: snapshotHook };
+      const wf = new Workflow(name, runId, steps.map(buildStep), deps);
+      try {
+        await wf.run({});
+      } catch {
+        try {
+          await wf.rollback();
+        } catch {
+        }
+      }
+    });
+  }
+  // Runs `execute` in the background and returns an async generator that
+  // yields WorkflowEvents in real-time as they are appended to the adapter.
+  _makeStream(name, runId, execute) {
+    const queue = [];
+    let wakeup = null;
+    let done = false;
+    const enqueue = (entry) => {
+      queue.push(entry);
+      const fn = wakeup;
+      wakeup = null;
+      fn?.();
+    };
+    const teeAdapter = {
+      append: async (entry) => {
+        await this.adapter.append(entry);
+        enqueue(entry);
+      },
+      readAll: (n, id) => this.adapter.readAll(n, id),
+      lastCheckpoint: (n, id) => this.adapter.lastCheckpoint(n, id),
+      listRuns: (n) => this.adapter.listRuns(n)
+    };
+    const teeDeps = {
+      control: this.control,
+      resolveExec: (sandboxId) => resolveExecClient(this.control, sandboxId),
+      adapter: teeAdapter
+    };
+    enqueue({ ts: Date.now(), workflowName: name, runId, stepIndex: -1, event: "run_started" /* RunStarted */, payload: { workflowName: name, runId } });
+    execute(teeDeps).finally(() => {
+      done = true;
+      const fn = wakeup;
+      wakeup = null;
+      fn?.();
+    });
+    return (async function* () {
+      while (true) {
+        while (queue.length > 0) yield queue.shift();
+        if (done) break;
+        await new Promise((r) => {
+          wakeup = r;
+        });
+      }
+      while (queue.length > 0) yield queue.shift();
+    })();
+  }
+};
+
+// src/workflow.ts
+var LoopVar = class {
+  constructor(name) {
+    this.name = name;
+  }
+  name;
+  toString() {
+    return `{{${this.name}}}`;
+  }
+};
+function wrapSteps(steps) {
+  return steps.length === 1 ? steps[0] : { type: "sequence", steps };
+}
+var SandboxStepBuilder = class _SandboxStepBuilder {
+  _steps = [];
+  exec(command, opts) {
+    this._steps.push({ type: "exec_command", command, ...opts });
+    return this;
+  }
+  writeFile(path, content, encoding) {
+    this._steps.push({ type: "write_file", path, content, ...encoding ? { encoding } : {} });
+    return this;
+  }
+  retry(maxAttempts, fn, opts) {
+    const inner = new _SandboxStepBuilder();
+    fn(inner);
+    this._steps.push({ type: "retry", step: wrapSteps(inner.build()), maxAttempts, ...opts });
+    return this;
+  }
+  forEach(source, optsOrFn, fn) {
+    const opts = typeof optsOrFn === "function" ? {} : optsOrFn;
+    const callback = typeof optsOrFn === "function" ? optsOrFn : fn;
+    const varName = opts.as ?? "item";
+    const loopVar = new LoopVar(varName);
+    const inner = new _SandboxStepBuilder();
+    const result = callback(inner, loopVar);
+    const steps = typeof result === "string" ? [{ type: "exec_command", command: result }] : result.build();
+    this._steps.push({
+      type: "loop",
+      as: varName,
+      steps,
+      ...Array.isArray(source) ? { items: source } : { over: source.from },
+      ...opts.concurrency !== void 0 && opts.concurrency > 1 ? { concurrently: true } : {}
+    });
+    return this;
+  }
+  when(condition, thenFn, elseFn) {
+    const thenBuilder = new _SandboxStepBuilder();
+    thenFn(thenBuilder);
+    const elseSteps = elseFn ? (() => {
+      const b = new _SandboxStepBuilder();
+      elseFn(b);
+      return b.build();
+    })() : void 0;
+    this._steps.push({
+      type: "conditional",
+      condition,
+      then: thenBuilder.build(),
+      ...elseSteps ? { else: elseSteps } : {}
+    });
+    return this;
+  }
+  parallel(fn) {
+    const pb = new SandboxParallelBuilder();
+    fn(pb);
+    this._steps.push({ type: "parallel", steps: pb.build() });
+    return this;
+  }
+  build() {
+    return [...this._steps];
+  }
+};
+var SandboxParallelBuilder = class {
+  _branches = [];
+  branch(fn) {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._branches.push(wrapSteps(sb.build()));
+    return this;
+  }
+  build() {
+    return this._branches;
+  }
+};
+var WorkflowParallelBuilder = class {
+  _branches = [];
+  sandbox(opts, fn) {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._branches.push({
+      type: "sequence",
+      steps: [
+        { type: "create_sandbox", entrypoint: ["tail", "-f", "/dev/null"], ...opts },
+        ...sb.build(),
+        { type: "delete_sandbox" }
+      ]
+    });
+    return this;
+  }
+  branch(fn) {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._branches.push(wrapSteps(sb.build()));
+    return this;
+  }
+  build() {
+    return this._branches;
+  }
+};
+var WorkflowBuilder = class {
+  constructor(_name) {
+    this._name = _name;
+  }
+  _name;
+  _steps = [];
+  sandbox(opts, fn) {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._steps.push(
+      { type: "create_sandbox", entrypoint: ["tail", "-f", "/dev/null"], ...opts },
+      ...sb.build(),
+      { type: "delete_sandbox" }
+    );
+    return this;
+  }
+  parallel(fn) {
+    const pb = new WorkflowParallelBuilder();
+    fn(pb);
+    this._steps.push({ type: "parallel", steps: pb.build() });
+    return this;
+  }
+  build() {
+    return { name: this._name, steps: this._steps };
+  }
+};
+function workflow(name) {
+  return new WorkflowBuilder(name);
+}
+export {
+  DrejClient,
+  DrejError,
+  LedgerEvent,
+  SandboxStepBuilder,
+  WorkflowBuilder,
+  WorkflowRun,
+  workflow
+};