drej 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # drej
 
+## 0.4.0
+
+### Minor Changes
+
+- d0486df: Add fluent workflow builder API to TypeScript SDK.
+
+  `workflow(id)` returns a `WorkflowBuilder` with chainable `.sandbox()` and `.parallel()` methods. Inside a sandbox scope, `SandboxStepBuilder` provides `.exec()`, `.writeFile()`, `.retry()`, `.forEach()`, `.when()`, and `.parallel()`. The `forEach` callback receives `(s, item)` where `item` serialises to `{{name}}` in template literals, enabling natural JS interpolation. Top-level `.parallel()` supports multiple concurrent sandbox sessions via `WorkflowParallelBuilder`. `DrejClient.run(w)` accepts a built workflow directly. The `sandbox()` helper defaults the entrypoint to `["tail", "-f", "/dev/null"]`.
+
+  Adds a server-side `sequence` step type that runs child steps sequentially, used internally by the builder to represent multi-step parallel branches.
+
+- e1f9bb8: Add `snapshotConfig` option to `client.run()` and a `replayFromSnapshot()` method.
+
+  Pass `snapshotConfig: { afterSteps?: number[]; everyNSteps?: number }` to capture sandbox snapshots at specific points in a workflow. Call `client.replayFromSnapshot(name, runId, workflow)` to start a new run booted from the latest captured snapshot — skipping any setup steps already baked into the image.
+
+- 9a30c31: Introduce per-run ledger with workflow name / run ID separation.
+
+  Each workflow execution now has a stable **workflow name** (user-defined) and an auto-generated **run ID** (UUID). Ledger files are stored at `ledgers/<name>/<runId>.ndjson` so all runs of a workflow are grouped together.
+
+  API changes:
+
+  - `POST /v1/workflows/:name/runs` — starts a run; first SSE event is `run_started` carrying the run ID
+  - `POST /v1/workflows/:name/runs/:runId/resume` — resumes a specific run
+  - `GET /v1/workflows/:name/runs` — lists all run IDs for a workflow
+  - `GET /v1/workflows/:name/runs/:runId/ledger` — fetches ledger for a specific run
+
+  SDK changes:
+
+  - `client.run(w)` is now `async` and returns `Promise<WorkflowRun>`; `run.id` gives the run ID, `run.name` the workflow name, and it is async-iterable for events
+  - `client.resumeRun(name, runId, w)` resumes a run
+  - `client.listWorkflowRuns(name)` lists runs
+  - `client.getWorkflowLedger(name, runId)` fetches the ledger
+  - `WorkflowEvent` fields renamed: `workflowId` → `workflowName` + `runId`
+
+### Patch Changes
+
+- b3c0bc9: feat: lifecycle hooks, append-only WAL, and clean adapter layer
+
+  - Add `WorkflowHooks` interface with `onStepStart`, `onStepComplete`, `onStepFailed`, `onStepRolledBack`, `onWorkflowComplete`, `onWorkflowFailed` callbacks on `WorkflowDeps`
+  - Fix `NdjsonLedger.append` to use `appendFileSync` (O_APPEND) instead of read-then-overwrite (O_TRUNC), preventing ledger truncation on crash
+  - Make `NdjsonLedger.readAll` resilient to malformed lines from partial writes
+  - Add `OpenSandboxControlAdapter` and `OpenSandboxExecFactory` to `@drej/opensandbox` — concrete implementations of `ISandboxControl` and `IExecClientFactory` that encapsulate execd readiness polling
+  - Remove `as unknown as` double-cast from `apps/api`; adapter wiring is now explicit and type-safe
+
+## 0.3.0
+
+### Minor Changes
+
+- 6256955: Add retry, conditional, loop, and parallel step types to the workflow engine.
+
+  - `retry` — retries a child step up to N times with fixed or exponential backoff
+  - `conditional` — branches on a structured predicate (`eq`, `neq`, `gt`, `lt`, `exists`, `and`, `or`) evaluated against workflow state
+  - `loop` — iterates over a static `items` array or a dot-path `over` pointing to an array in state; supports `concurrently` flag for parallel iterations
+  - `parallel` — fans out multiple steps with `Promise.all`; emits events with a `branch` index for demuxing
+  - `{{key}}` interpolation in `exec_command` so loop items and other state values can be referenced in command strings
+  - `branch` field added to `WorkflowEvent` to identify parallel branch origin
+  - `Predicate` type exported from the SDK for use with `conditional` steps
+
+- 2da4112: Add workflow engine support: `runWorkflow()` now supports `create_sandbox`, `exec_code`, `exec_command`, and `delete_sandbox` step types with SSE streaming and saga rollback.
+- eb72eea: Add `write_file` workflow step type and always base64-encode `exec_command` strings.
+
+  - `write_file` step writes text or binary content to a path inside the sandbox; accepts `encoding: "utf8"` (default) or `"base64"` for binary files
+  - `exec_command` now unconditionally base64-encodes the command string before sending to the container, eliminating all quoting and special-character edge cases
+
 ## 0.2.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drej",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {

package/src/client.ts

@@ -8,36 +8,677 @@ export class DrejError extends Error {
   }
 }
 
-export interface DrejClientOptions {
-  baseUrl?: string;
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface Resources {
+  cpu?: string;
+  memory?: string;
+  gpu?: string;
+}
+
+export interface ImageAuth {
+  username: string;
+  password: string;
+}
+
+export interface ImageSpec {
+  uri: string;
+  auth?: ImageAuth;
+}
+
+export type SandboxState =
+  | "Pending"
+  | "Running"
+  | "Pausing"
+  | "Paused"
+  | "Resuming"
+  | "Stopping"
+  | "Terminated"
+  | "Failed"
+  | "Unknown";
+
+export interface SandboxStatus {
+  state: SandboxState;
+  reason?: string;
+  message?: string;
+  lastTransitionAt?: string;
 }
 
-export interface SandboxRunResult {
+export interface Sandbox {
   id: string;
+  status: SandboxStatus;
+  createdAt: string;
+  expiresAt?: string | null;
+  image?: ImageSpec;
+  snapshotId?: string;
+  entrypoint?: string[];
+  metadata?: Record<string, string>;
+}
+
+export interface CreateSandboxOptions {
+  image?: ImageSpec;
+  snapshotId?: string;
+  timeout?: number;
+  resourceLimits?: Resources;
+  entrypoint?: string[];
+  env?: Record<string, string>;
+  metadata?: Record<string, string>;
+  secureAccess?: boolean;
+}
+
+export interface ListSandboxesOptions {
+  state?: SandboxState;
+  limit?: number;
+  offset?: number;
+}
+
+export type SnapshotState = "Pending" | "Committing" | "Pushing" | "Ready" | "Failed";
+
+export interface Snapshot {
+  id: string;
+  sandboxId: string;
+  state: SnapshotState;
+  createdAt: string;
+}
+
+export interface ListSnapshotsOptions {
+  sandboxId?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export type SSEEventType =
+  | "init"
+  | "status"
+  | "stdout"
+  | "stderr"
+  | "result"
+  | "execution_complete"
+  | "execution_count"
+  | "error"
+  | "ping"
+  | "message";
+
+export interface SSEEvent {
+  type: SSEEventType;
+  text?: string;
+  results?: Record<string, string>;
+  error?: { name?: string; message: string };
+  execution_count?: number;
+  execution_time?: number;
+  timestamp: number;
+}
+
+export interface CodeContext {
+  id: string;
+  language: string;
+}
+
+export interface ExecuteCodeOptions {
   code: string;
-  status: "queued";
+  context?: {
+    id: string;
+    language: string;
+  };
+}
+
+export interface ExecuteCommandOptions {
+  command: string;
+  cwd?: string;
+  background?: boolean;
+  timeout?: number;
+  uid?: number;
+  gid?: number;
+  envs?: Record<string, string>;
+}
+
+export interface CommandStatus {
+  session: string;
+  status: "running" | "completed" | "failed";
+  exitCode?: number;
+}
+
+export interface FileInfo {
+  path: string;
+  size: number;
+  mode: string;
+  modifiedAt: string;
+  isDirectory: boolean;
 }
 
+export interface DirectoryEntry {
+  name: string;
+  path: string;
+  isDirectory: boolean;
+  size?: number;
+}
+
+export interface FileReplacement {
+  path: string;
+  old: string;
+  new: string;
+}
+
+export interface Metrics {
+  cpu: number;
+  memory: number;
+  timestamp: string;
+}
+
+export interface DiagnosticLog {
+  name: string;
+  size: number;
+  url?: string;
+  inline?: string;
+}
+
+export interface DiagnosticEvent {
+  timestamp: string;
+  type: string;
+  message: string;
+}
+
+export interface DrejClientOptions {
+  baseUrl?: string;
+}
+
+// ── Workflow types ─────────────────────────────────────────────────────────
+
+export type WorkflowEventKind =
+  | "run_started"
+  | "step_start"
+  | "step_complete"
+  | "step_failed"
+  | "step_rolled_back"
+  | "workflow_complete"
+  | "workflow_failed"
+  | "checkpoint"
+  | "exec_event"
+  | "snapshot";
+
+export interface SnapshotConfig {
+  /** Take a snapshot after these step indices (0-based). */
+  afterSteps?: number[];
+  /** Take a snapshot after every N steps. */
+  everyNSteps?: number;
+}
+
+export interface RunOptions {
+  snapshotConfig?: SnapshotConfig;
+}
+
+export interface WorkflowEvent {
+  ts: number;
+  workflowName: string;
+  runId: string;
+  stepIndex: number;
+  branch?: number;
+  event: WorkflowEventKind;
+  payload?: unknown;
+  error?: string;
+  result?: unknown;
+}
+
+export class WorkflowRun implements AsyncIterable<WorkflowEvent> {
+  constructor(
+    public readonly name: string,
+    public readonly id: string,
+    private readonly _events: AsyncGenerator<WorkflowEvent>,
+  ) {}
+
+  [Symbol.asyncIterator](): AsyncIterator<WorkflowEvent> {
+    return this._events;
+  }
+}
+
+export type Predicate =
+  | { op: "eq" | "neq"; field: string; value: unknown }
+  | { op: "gt" | "lt" | "gte" | "lte"; field: string; value: number }
+  | { op: "exists" | "not_exists"; field: string }
+  | { op: "and" | "or"; predicates: Predicate[] };
+
+export type StepDef =
+  | {
+      type: "create_sandbox";
+      image?: ImageSpec;
+      snapshotId?: string;
+      timeout?: number;
+      entrypoint?: string[];
+      env?: Record<string, string>;
+      metadata?: Record<string, string>;
+      resourceLimits?: Resources;
+    }
+  | { type: "exec_code"; code: string; context?: { id: string; language: string } }
+  | { type: "exec_command"; command: string; cwd?: string; envs?: Record<string, string> }
+  | { type: "delete_sandbox" }
+  | { type: "write_file"; path: string; content: string; encoding?: "utf8" | "base64" }
+  | { type: "retry"; step: StepDef; maxAttempts: number; delayMs?: number; backoff?: "fixed" | "exponential" }
+  | { type: "conditional"; condition: Predicate; then: StepDef[]; else?: StepDef[] }
+  | { type: "loop"; over?: string; items?: unknown[]; as: string; steps: StepDef[]; concurrently?: boolean }
+  | { type: "parallel"; steps: StepDef[] }
+  | { type: "sequence"; steps: StepDef[] };
+
+// ── SSE parsers ────────────────────────────────────────────────────────────
+
+async function* parseWorkflowSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<WorkflowEvent> {
+  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) {
+        if (!block.trim()) continue;
+        for (const line of block.split("\n")) {
+          if (line.startsWith("data:")) {
+            yield JSON.parse(line.slice(5).trim()) as WorkflowEvent;
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function* parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<SSEEvent> {
+  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) {
+        if (!block.trim()) continue;
+        let type: string | undefined;
+        let data: string | undefined;
+        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 !== undefined) {
+          yield { type: (type ?? "message") as SSEEventType, ...JSON.parse(data) };
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// ── Client ─────────────────────────────────────────────────────────────────
+
 export class DrejClient {
   private baseUrl: string;
 
   constructor(options: DrejClientOptions = {}) {
-    this.baseUrl = options.baseUrl ?? "http://localhost:3000";
+    this.baseUrl = (options.baseUrl ?? "http://localhost:6000").replace(/\/$/, "");
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: body !== undefined ? { "Content-Type": "application/json" } : {},
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    if (!res.ok) throw new DrejError("drej API error", res.status);
+    if (res.status === 204) return undefined as T;
+    return res.json() as Promise<T>;
+  }
+
+  private async *streamRequest(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): AsyncGenerator<SSEEvent> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: body !== undefined ? { "Content-Type": "application/json" } : {},
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    if (!res.ok) throw new DrejError("drej API error", res.status);
+    if (!res.body) return;
+    yield* parseSSE(res.body);
+  }
+
+  // ── Health ───────────────────────────────────────────────────────────────
+
+  health(): Promise<{ healthy: boolean }> {
+    return this.request("GET", "/health");
+  }
+
+  // ── Sandbox lifecycle ────────────────────────────────────────────────────
+
+  createSandbox(options: CreateSandboxOptions): Promise<Sandbox> {
+    return this.request("POST", "/v1/sandboxes", options);
+  }
+
+  listSandboxes(options: ListSandboxesOptions = {}): Promise<Sandbox[]> {
+    const params = new URLSearchParams();
+    if (options.state) params.set("state", options.state);
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.offset !== undefined) params.set("offset", String(options.offset));
+    const qs = params.toString();
+    return this.request("GET", `/v1/sandboxes${qs ? `?${qs}` : ""}`);
+  }
+
+  getSandbox(id: string): Promise<Sandbox> {
+    return this.request("GET", `/v1/sandboxes/${id}`);
   }
 
-  async health(): Promise<{ healthy: boolean }> {
-    const res = await fetch(`${this.baseUrl}/health`);
-    if (!res.ok) throw new DrejError(`drej API error`, res.status);
-    return res.json();
+  deleteSandbox(id: string): Promise<void> {
+    return this.request("DELETE", `/v1/sandboxes/${id}`);
   }
 
-  async run(code: string): Promise<SandboxRunResult> {
-    const res = await fetch(`${this.baseUrl}/sandbox/run`, {
+  pauseSandbox(id: string): Promise<void> {
+    return this.request("POST", `/v1/sandboxes/${id}/pause`);
+  }
+
+  resumeSandbox(id: string): Promise<void> {
+    return this.request("POST", `/v1/sandboxes/${id}/resume`);
+  }
+
+  renewSandbox(id: string): Promise<void> {
+    return this.request("POST", `/v1/sandboxes/${id}/renew`);
+  }
+
+  async waitForRunning(
+    id: string,
+    options: { timeoutMs?: number; pollIntervalMs?: number } = {},
+  ): Promise<Sandbox> {
+    const { timeoutMs = 60_000, pollIntervalMs = 1_000 } = options;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const sandbox = await this.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<void>((r) => setTimeout(r, pollIntervalMs));
+    }
+    throw new DrejError(`Sandbox ${id} did not reach Running within ${timeoutMs}ms`, 408);
+  }
+
+  // ── Snapshots ────────────────────────────────────────────────────────────
+
+  createSnapshot(sandboxId: string): Promise<Snapshot> {
+    return this.request("POST", `/v1/sandboxes/${sandboxId}/snapshots`);
+  }
+
+  listSnapshots(options: ListSnapshotsOptions = {}): Promise<Snapshot[]> {
+    const params = new URLSearchParams();
+    if (options.sandboxId) params.set("sandboxId", options.sandboxId);
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.offset !== undefined) params.set("offset", String(options.offset));
+    const qs = params.toString();
+    return this.request("GET", `/v1/snapshots${qs ? `?${qs}` : ""}`);
+  }
+
+  getSnapshot(id: string): Promise<Snapshot> {
+    return this.request("GET", `/v1/snapshots/${id}`);
+  }
+
+  deleteSnapshot(id: string): Promise<void> {
+    return this.request("DELETE", `/v1/snapshots/${id}`);
+  }
+
+  // ── Diagnostics ──────────────────────────────────────────────────────────
+
+  getDiagnosticLogs(sandboxId: string): Promise<DiagnosticLog[]> {
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/diagnostics/logs`);
+  }
+
+  getDiagnosticEvents(sandboxId: string): Promise<DiagnosticEvent[]> {
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/diagnostics/events`);
+  }
+
+  // ── Code execution ───────────────────────────────────────────────────────
+
+  async *executeCode(sandboxId: string, options: ExecuteCodeOptions): AsyncGenerator<SSEEvent> {
+    yield* this.streamRequest("POST", `/v1/sandboxes/${sandboxId}/exec/code`, options);
+  }
+
+  interruptCode(sandboxId: string): Promise<void> {
+    return this.request("DELETE", `/v1/sandboxes/${sandboxId}/exec/code`);
+  }
+
+  // ── Code contexts ────────────────────────────────────────────────────────
+
+  listContexts(sandboxId: string, language?: string): Promise<CodeContext[]> {
+    const qs = language ? `?language=${encodeURIComponent(language)}` : "";
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/exec/contexts${qs}`);
+  }
+
+  createContext(sandboxId: string, language: string): Promise<CodeContext> {
+    return this.request("POST", `/v1/sandboxes/${sandboxId}/exec/contexts`, { language });
+  }
+
+  clearContexts(sandboxId: string, language?: string): Promise<void> {
+    const qs = language ? `?language=${encodeURIComponent(language)}` : "";
+    return this.request("DELETE", `/v1/sandboxes/${sandboxId}/exec/contexts${qs}`);
+  }
+
+  deleteContext(sandboxId: string, contextId: string): Promise<void> {
+    return this.request("DELETE", `/v1/sandboxes/${sandboxId}/exec/contexts/${contextId}`);
+  }
+
+  // ── Command execution ────────────────────────────────────────────────────
+
+  async *executeCommand(
+    sandboxId: string,
+    options: ExecuteCommandOptions,
+  ): AsyncGenerator<SSEEvent> {
+    yield* this.streamRequest("POST", `/v1/sandboxes/${sandboxId}/exec/command`, options);
+  }
+
+  interruptCommand(sandboxId: string): Promise<void> {
+    return this.request("DELETE", `/v1/sandboxes/${sandboxId}/exec/command`);
+  }
+
+  getCommandStatus(sandboxId: string, session: string): Promise<CommandStatus> {
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/exec/command/status/${session}`);
+  }
+
+  getCommandOutput(
+    sandboxId: string,
+    session: string,
+  ): Promise<{ stdout: string; stderr: string }> {
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/exec/command/output/${session}`);
+  }
+
+  // ── Files ────────────────────────────────────────────────────────────────
+
+  getFileInfo(sandboxId: string, path: string): Promise<FileInfo> {
+    return this.request(
+      "GET",
+      `/v1/sandboxes/${sandboxId}/files/info?path=${encodeURIComponent(path)}`,
+    );
+  }
+
+  deleteFile(sandboxId: string, path: string): Promise<void> {
+    return this.request(
+      "DELETE",
+      `/v1/sandboxes/${sandboxId}/files?path=${encodeURIComponent(path)}`,
+    );
+  }
+
+  setFilePermissions(sandboxId: string, path: string, mode: string): Promise<void> {
+    return this.request("POST", `/v1/sandboxes/${sandboxId}/files/permissions`, { path, mode });
+  }
+
+  moveFile(sandboxId: string, from: string, to: string): Promise<void> {
+    return this.request("POST", `/v1/sandboxes/${sandboxId}/files/move`, { from, to });
+  }
+
+  searchFiles(sandboxId: string, pattern: string, dir?: string): Promise<string[]> {
+    const params = new URLSearchParams({ pattern });
+    if (dir) params.set("dir", dir);
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/files/search?${params}`);
+  }
+
+  replaceInFiles(sandboxId: string, replacements: FileReplacement[]): Promise<void> {
+    return this.request("POST", `/v1/sandboxes/${sandboxId}/files/replace`, { replacements });
+  }
+
+  async uploadFile(
+    sandboxId: string,
+    path: string,
+    content: Blob | BufferSource | string,
+  ): Promise<void> {
+    const blob = content instanceof Blob ? content : new Blob([content]);
+    const formData = new FormData();
+    formData.append("file", blob, path.split("/").pop());
+    formData.append("path", path);
+    const res = await fetch(`${this.baseUrl}/v1/sandboxes/${sandboxId}/files/upload`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ code }),
+      body: formData,
     });
-    if (!res.ok) throw new DrejError(`drej API error`, res.status);
-    return res.json();
+    if (!res.ok) throw new DrejError("drej API error", res.status);
+  }
+
+  async downloadFile(sandboxId: string, path: string): Promise<ReadableStream<Uint8Array>> {
+    const res = await fetch(
+      `${this.baseUrl}/v1/sandboxes/${sandboxId}/files/download?path=${encodeURIComponent(path)}`,
+    );
+    if (!res.ok) throw new DrejError("drej API error", res.status);
+    if (!res.body) throw new Error("empty response body");
+    return res.body;
+  }
+
+  // ── Directories ──────────────────────────────────────────────────────────
+
+  listDirectory(sandboxId: string, path: string, depth?: number): Promise<DirectoryEntry[]> {
+    const params = new URLSearchParams({ path });
+    if (depth !== undefined) params.set("depth", String(depth));
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/directories?${params}`);
+  }
+
+  createDirectory(sandboxId: string, path: string): Promise<void> {
+    return this.request("POST", `/v1/sandboxes/${sandboxId}/directories`, { path });
+  }
+
+  deleteDirectory(sandboxId: string, path: string): Promise<void> {
+    return this.request(
+      "DELETE",
+      `/v1/sandboxes/${sandboxId}/directories?path=${encodeURIComponent(path)}`,
+    );
+  }
+
+  // ── Metrics ──────────────────────────────────────────────────────────────
+
+  getMetrics(sandboxId: string): Promise<Metrics> {
+    return this.request("GET", `/v1/sandboxes/${sandboxId}/metrics`);
+  }
+
+  async *watchMetrics(sandboxId: string): AsyncGenerator<SSEEvent> {
+    yield* this.streamRequest("GET", `/v1/sandboxes/${sandboxId}/metrics/watch`);
+  }
+
+  // ── Workflows ────────────────────────────────────────────────────────────
+
+  async run(
+    w: { build(): { name: string; steps: StepDef[] } },
+    options?: RunOptions,
+  ): Promise<WorkflowRun> {
+    const { name, steps } = w.build();
+    return this._startRun(name, steps, options?.snapshotConfig);
+  }
+
+  /**
+   * Start a new run using a snapshot captured from a previous run.
+   *
+   * Reads the ledger for the given run, finds the latest snapshot entry,
+   * and injects the snapshotId into the first `create_sandbox` step of the
+   * provided workflow — so the new sandbox boots from that snapshot with the
+   * previous environment already in place.
+   */
+  async replayFromSnapshot(
+    name: string,
+    runId: string,
+    w: { build(): { name: string; steps: StepDef[] } },
+  ): Promise<WorkflowRun> {
+    const ledger = await this.getWorkflowLedger(name, runId);
+    const snapEntry = [...ledger].reverse().find((e) => e.event === "snapshot");
+    if (!snapEntry) throw new DrejError(`No snapshot found in ledger for ${name}/${runId}`, 404);
+    const { snapshotId } = snapEntry.payload as { snapshotId: string };
+
+    const { name: wfName, steps } = w.build();
+    const replaySteps: StepDef[] = steps.map((step) =>
+      step.type === "create_sandbox" ? { ...step, snapshotId } : step,
+    );
+
+    return this._startRun(wfName, replaySteps);
+  }
+
+  async resumeRun(
+    name: string,
+    runId: string,
+    w: { build(): { name: string; steps: StepDef[] } } | StepDef[],
+  ): Promise<WorkflowRun> {
+    const steps = Array.isArray(w) ? w : w.build().steps;
+    const res = await fetch(
+      `${this.baseUrl}/v1/workflows/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/resume`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ steps }),
+      },
+    );
+    if (!res.ok) throw new DrejError("drej API error", res.status);
+    if (!res.body) throw new DrejError("empty response body", 500);
+    return this._consumeRunStarted(name, res.body);
+  }
+
+  listWorkflowRuns(name: string): Promise<{ runs: string[] }> {
+    return this.request("GET", `/v1/workflows/${encodeURIComponent(name)}/runs`);
+  }
+
+  getWorkflowLedger(name: string, runId: string): Promise<WorkflowEvent[]> {
+    return this.request(
+      "GET",
+      `/v1/workflows/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/ledger`,
+    );
+  }
+
+  private async _startRun(
+    name: string,
+    steps: StepDef[],
+    snapshotConfig?: SnapshotConfig,
+  ): Promise<WorkflowRun> {
+    const res = await fetch(
+      `${this.baseUrl}/v1/workflows/${encodeURIComponent(name)}/runs`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ steps, ...(snapshotConfig ? { snapshotConfig } : {}) }),
+      },
+    );
+    if (!res.ok) throw new DrejError("drej API error", res.status);
+    if (!res.body) throw new DrejError("empty response body", 500);
+    return this._consumeRunStarted(name, res.body);
+  }
+
+  private async _consumeRunStarted(
+    name: string,
+    body: ReadableStream<Uint8Array>,
+  ): Promise<WorkflowRun> {
+    const stream = parseWorkflowSSE(body);
+    const first = await stream.next();
+    if (first.done || first.value.event !== "run_started") {
+      throw new DrejError("expected run_started as first SSE event", 500);
+    }
+    const { runId } = first.value.payload as { runId: string };
+    return new WorkflowRun(name, runId, stream);
   }
 }

package/src/index.ts

@@ -1,2 +1,35 @@
-export { DrejClient, DrejError } from "./client";
-export type { DrejClientOptions, SandboxRunResult } from "./client";
+export { DrejClient, DrejError, WorkflowRun } from "./client";
+export type {
+  DrejClientOptions,
+  Resources,
+  ImageAuth,
+  ImageSpec,
+  Sandbox,
+  SandboxState,
+  SandboxStatus,
+  CreateSandboxOptions,
+  ListSandboxesOptions,
+  Snapshot,
+  SnapshotState,
+  ListSnapshotsOptions,
+  SSEEvent,
+  SSEEventType,
+  CodeContext,
+  ExecuteCodeOptions,
+  ExecuteCommandOptions,
+  CommandStatus,
+  FileInfo,
+  DirectoryEntry,
+  FileReplacement,
+  Metrics,
+  DiagnosticLog,
+  DiagnosticEvent,
+  WorkflowEvent,
+  WorkflowEventKind,
+  StepDef,
+  SnapshotConfig,
+  RunOptions,
+} from "./client";
+
+export { workflow, WorkflowBuilder, SandboxStepBuilder } from "./workflow";
+export type { SandboxOpts, LoopItem } from "./workflow";

package/src/workflow.ts

@@ -0,0 +1,214 @@
+import type { StepDef, ImageSpec, Resources, Predicate } from "./client";
+
+// Placeholder that serialises to {{name}} inside template literals.
+// Used as the `item` parameter in forEach callbacks so users write
+// `s.exec(`upload ${item}`)` instead of `s.exec("upload {{item}}")`.
+class LoopVar {
+  constructor(private name: string) {}
+  toString() {
+    return `{{${this.name}}}`;
+  }
+}
+
+export type LoopItem = { toString(): string };
+
+export type SandboxOpts = {
+  image?: ImageSpec;
+  snapshotId?: string;
+  timeout?: number;
+  entrypoint?: string[];
+  env?: Record<string, string>;
+  metadata?: Record<string, string>;
+  resourceLimits?: Resources;
+};
+
+type ForEachOpts = {
+  concurrency?: number;
+  as?: string;
+};
+
+type ForEachSource = unknown[] | { from: string };
+type ForEachCallback = (s: SandboxStepBuilder, item: LoopItem) => SandboxStepBuilder | string;
+
+function wrapSteps(steps: StepDef[]): StepDef {
+  return steps.length === 1 ? steps[0] : { type: "sequence", steps };
+}
+
+// ── SandboxStepBuilder ────────────────────────────────────────────────────────
+
+export class SandboxStepBuilder {
+  protected _steps: StepDef[] = [];
+
+  exec(command: string, opts?: { cwd?: string; envs?: Record<string, string> }): this {
+    this._steps.push({ type: "exec_command", command, ...opts });
+    return this;
+  }
+
+  writeFile(path: string, content: string, encoding?: "utf8" | "base64"): this {
+    this._steps.push({ type: "write_file", path, content, ...(encoding ? { encoding } : {}) });
+    return this;
+  }
+
+  retry(
+    maxAttempts: number,
+    fn: (s: SandboxStepBuilder) => SandboxStepBuilder,
+    opts?: { delayMs?: number; backoff?: "fixed" | "exponential" },
+  ): this {
+    const inner = new SandboxStepBuilder();
+    fn(inner);
+    this._steps.push({ type: "retry", step: wrapSteps(inner.build()), maxAttempts, ...opts });
+    return this;
+  }
+
+  forEach(source: ForEachSource, fn: ForEachCallback): this;
+  forEach(source: ForEachSource, opts: ForEachOpts, fn: ForEachCallback): this;
+  forEach(
+    source: ForEachSource,
+    optsOrFn: ForEachOpts | ForEachCallback,
+    fn?: ForEachCallback,
+  ): this {
+    const opts: ForEachOpts = typeof optsOrFn === "function" ? {} : optsOrFn;
+    const callback: ForEachCallback = 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: StepDef[] =
+      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 !== undefined && opts.concurrency > 1 ? { concurrently: true } : {}),
+    });
+
+    return this;
+  }
+
+  when(
+    condition: Predicate,
+    thenFn: (s: SandboxStepBuilder) => SandboxStepBuilder,
+    elseFn?: (s: SandboxStepBuilder) => SandboxStepBuilder,
+  ): this {
+    const thenBuilder = new SandboxStepBuilder();
+    thenFn(thenBuilder);
+
+    const elseSteps = elseFn
+      ? (() => {
+          const b = new SandboxStepBuilder();
+          elseFn(b);
+          return b.build();
+        })()
+      : undefined;
+
+    this._steps.push({
+      type: "conditional",
+      condition,
+      then: thenBuilder.build(),
+      ...(elseSteps ? { else: elseSteps } : {}),
+    });
+
+    return this;
+  }
+
+  parallel(fn: (p: SandboxParallelBuilder) => SandboxParallelBuilder): this {
+    const pb = new SandboxParallelBuilder();
+    fn(pb);
+    this._steps.push({ type: "parallel", steps: pb.build() });
+    return this;
+  }
+
+  build(): StepDef[] {
+    return [...this._steps];
+  }
+}
+
+// ── SandboxParallelBuilder ────────────────────────────────────────────────────
+// Used inside a sandbox scope — branches share the same sandbox, no new ones.
+
+class SandboxParallelBuilder {
+  private _branches: StepDef[] = [];
+
+  branch(fn: (s: SandboxStepBuilder) => SandboxStepBuilder): this {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._branches.push(wrapSteps(sb.build()));
+    return this;
+  }
+
+  build(): StepDef[] {
+    return this._branches;
+  }
+}
+
+// ── WorkflowParallelBuilder ───────────────────────────────────────────────────
+// Used at the top-level workflow scope — each branch can own its own sandbox.
+
+class WorkflowParallelBuilder {
+  private _branches: StepDef[] = [];
+
+  sandbox(opts: SandboxOpts, fn: (s: SandboxStepBuilder) => SandboxStepBuilder): this {
+    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: (s: SandboxStepBuilder) => SandboxStepBuilder): this {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._branches.push(wrapSteps(sb.build()));
+    return this;
+  }
+
+  build(): StepDef[] {
+    return this._branches;
+  }
+}
+
+// ── WorkflowBuilder ───────────────────────────────────────────────────────────
+
+export class WorkflowBuilder {
+  private _steps: StepDef[] = [];
+
+  constructor(private _name: string) {}
+
+  sandbox(opts: SandboxOpts, fn: (s: SandboxStepBuilder) => SandboxStepBuilder): this {
+    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: (p: WorkflowParallelBuilder) => WorkflowParallelBuilder): this {
+    const pb = new WorkflowParallelBuilder();
+    fn(pb);
+    this._steps.push({ type: "parallel", steps: pb.build() });
+    return this;
+  }
+
+  build(): { name: string; steps: StepDef[] } {
+    return { name: this._name, steps: this._steps };
+  }
+}
+
+export function workflow(name: string): WorkflowBuilder {
+  return new WorkflowBuilder(name);
+}