@agent-compose/sdk 0.2.5 → 0.3.0

package/dist/types/sandbox-environment.d.ts

@@ -1,16 +1,14 @@
 /**
  * A sandbox environment is a workflow whose job is to leave its VM in a
  * configured state, then snapshot it so other workflows can boot from that
- * state. Capture is **opt-in**: the wrapper below sets `saveSnapshot: true`
- * by default (opt out with `saveSnapshot: false` if you only want side
- * effects).
+ * state. Capture is **opt-in**: the wrapper below sets
+ * `snapshots: { saveLatest: true }` by default (opt out with
+ * `saveLatest: false` if you only want side effects).
  *
- * Once captured, reference the snapshot from another workflow's `snapshot`
- * field by run UUID, workflow name, or `name@version`:
+ * Once captured, reference the snapshot from another workflow's
+ * `snapshots.bootFrom` field by provider snapshot id:
  *
- *     snapshot: "my-setup"          // most recent successful snapshot
- *     snapshot: "my-setup@v1"       // version-scoped recency
- *     snapshot: "<run-uuid>"        // pinned to an exact run
+ *     snapshots: { bootFrom: { snapshotId: "snap_..." } }
  *
  * `defineSandboxEnvironment` is sugar over `defineWorkflow` — it makes the
  * setup recipe read like an imperative script by supplying the local
@@ -20,7 +18,7 @@
  *   1. Author a setup file with `defineSandboxEnvironment`.
  *   2. `agentc register setup.ts --build` — registers and invokes once to
  *      capture the snapshot.
- *   3. Other workflows declare `snapshot: "name"` and boot from it.
+ *   3. Other workflows declare `snapshots: { bootFrom: { snapshotId } }`.
  *   4. `agentc snapshot list` / `delete` to manage the Vercel storage bill.
  *
  * @example
@@ -37,16 +35,27 @@
  */
 import type { SandboxProvider } from "./sandbox.js";
 import type { Workflow } from "../workflow-steps/types.js";
+import type { SnapshotConfig } from "./workflow-metadata.js";
 export interface SandboxEnvironmentDefinition {
     name: string;
     description?: string;
     setup: (sb: SandboxProvider) => Promise<void>;
-    /** Override the sugar's `saveSnapshot: true` default. Set `false` to opt
-     *  out of snapshot capture (rarely useful — an env with no snapshot can't
-     *  be referenced as the `snapshot` field on another workflow). */
-    saveSnapshot?: boolean;
+    /** Override the sugar's `{ saveLatest: true }` default. Set
+     *  `{ saveLatest: false }` to opt out of snapshot capture (rarely
+     *  useful — an env with no snapshot can't be referenced as a
+     *  `bootFrom` on another workflow). */
+    snapshots?: SnapshotConfig;
+    /** Override the sugar's `memory: false` default. Setup workflows
+     *  don't typically benefit from memory extraction; opt in explicitly
+     *  when they do. */
+    memory?: boolean;
 }
 /** Sugar over `defineWorkflow` for setup-only workflows that exist to
  *  capture a snapshot. The workflow takes no meaningful input and returns
- *  nothing — its value is the side effect on the sandbox VM. */
+ *  nothing — its value is the side effect on the sandbox VM.
+ *
+ *  Defaults `memory: false` because sandbox environments emit setup
+ *  output (npm installs, command exit codes) rather than agent traces
+ *  worth memorising. Authors can opt in explicitly via `env.memory:
+ *  true` if their environment somehow does want extraction. */
 export declare function defineSandboxEnvironment(env: SandboxEnvironmentDefinition): Workflow<Record<string, unknown>, void>;

package/dist/types/sandbox.d.ts

@@ -29,9 +29,14 @@ export interface SandboxProvider {
     /** Capture the running sandbox's state as a reusable snapshot. Vercel
      *  supports it natively; E2B's model is Dockerfile-based and doesn't map
      *  cleanly — `undefined` on providers that don't. Used by the server's
-     *  `--build` flow to stamp the snapshot id on the workflow row. */
+     *  `--build` flow to stamp the snapshot id on the workflow row.
+     *
+     *  `sizeBytes` is the on-disk footprint reported by the provider. May
+     *  be omitted when the provider doesn't expose it; the server stores
+     *  `null` for missing values rather than estimating. */
     snapshot?(): Promise<{
         snapshotId: string;
+        sizeBytes?: number;
     }>;
 }
 /** Stateless provider-level snapshot deletion — no live sandbox needed,

package/dist/types/workflow-metadata.d.ts

@@ -18,19 +18,83 @@ import type { Processor } from "../processors/processor.js";
  * The bundler reads these from the default export at registration time
  * and forwards them to the server's POST /api/v1/templates payload.
  */
-/** Server-side knob for whether/how a Workflow Memory agent should run
- *  after this workflow completes. `"default"` runs the built-in extractor;
- *  `false` disables; an object names a custom memory workflow to dispatch. */
-export type WorkflowMemoryConfig = "default" | false | {
-    workflow: string;
+/** Whether the built-in Workflow Memory extractor should run after this
+ *  workflow completes. Boolean toggle — custom post-run workflows live
+ *  in the separate `postRunHooks` array on `WorkflowMetadata`. */
+export type WorkflowMemoryConfig = boolean;
+/** Where a run boots from. The snapshot id is the unit of identity —
+ *  each captured snapshot already records the workflow + version it
+ *  came from on the snapshot row, so there's no separate "latest of
+ *  workflow X" resolution at dispatch time. Operators pick a snapshot
+ *  from the dashboard snapshot list (or `agentc snapshot list`) and
+ *  paste the id here.
+ *
+ *  Omit `bootFrom` entirely to boot a fresh base sandbox. */
+export type BootSnapshot = {
+    snapshotId: string;
 };
+/** Snapshot configuration — boot source plus capture knobs. One object
+ *  per workflow / per invocation; collapsing boot + capture under a
+ *  single key reads as "all snapshot config lives here." */
+export interface SnapshotConfig {
+    /** Where the runner restores from at run start. Structured (workflow
+     *  ref or snapshot id) so the intent is explicit at the call site. */
+    bootFrom?: BootSnapshot;
+    /** Capture the sandbox state on terminal success. The latest pointer
+     *  on `workflow_runs.vercel_snapshot_id` always tracks the most
+     *  recent capture; without `retainSteps`, prior captures are deleted
+     *  as new ones land — constant storage cost. */
+    saveLatest?: boolean;
+    /** Only meaningful with `saveLatest: true`. Retain every step's
+     *  snapshot in `run_step_snapshots` so a future dispatch can boot
+     *  from a specific step's checkpoint via its `snapshotId`. Cost
+     *  scales linearly with step count. */
+    retainSteps?: boolean;
+}
+/** JSON-Schema-shaped description captured by the bundler from a
+ *  workflow's `input` or `output` zod schema. Carried in template
+ *  metadata so the dashboard can render typed input forms + output
+ *  type tables. */
+export interface IOSchema {
+    /** JSON Schema `type` keyword, when single-valued. Omitted for unions / unknowns. */
+    type?: string | string[];
+    /** Free-form description pulled from `.describe(...)` on the root. */
+    description?: string;
+    /** Object-shape: one entry per property. */
+    properties?: Record<string, {
+        type?: string | string[];
+        description?: string;
+    }>;
+    /** Required property names — relevant only when `type === "object"`. */
+    required?: string[];
+}
+/** Alias kept for backwards source-compatibility with the original
+ *  output-only release. New code should prefer `IOSchema`. */
+export type OutputSchema = IOSchema;
 export interface WorkflowMetadata {
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
-    snapshot?: string;
-    saveSnapshot?: boolean;
+    /** Input schema captured at bundle time from the workflow's
+     *  declared `input` zod schema. Step-form workflows populate this
+     *  automatically; run-form workflows (no explicit input schema —
+     *  defaults to `z.unknown()`) leave it undefined. */
+    inputSchema?: IOSchema;
+    /** Output schema captured at bundle time from the workflow's
+     *  declared `output` zod schema. Step-form workflows populate this
+     *  automatically; run-form workflows whose `run()` returns
+     *  arbitrarily-typed values leave it undefined. */
+    outputSchema?: IOSchema;
+    /** All snapshot config — boot source + capture mode. */
+    snapshots?: SnapshotConfig;
     processors?: readonly Processor[];
-    memory?: WorkflowMemoryConfig;
+    /** Run the built-in memory extractor after this workflow completes.
+     *  Opt-in; defaults to false when omitted. */
+    memory?: boolean;
+    /** Ordered list of workflow names that run after this workflow
+     *  completes. The runtime dispatches them in declaration order; the
+     *  built-in memory extractor (when `memory: true`) runs as a separate
+     *  hook alongside whatever's declared here. */
+    postRunHooks?: readonly string[];
 }
 /**
  * Pull the server-readable declarations off a source object (run-form

package/dist/types/workflow.d.ts

@@ -25,8 +25,8 @@ export type { WorkflowMetadata } from "./workflow-metadata.js";
 export interface AgentEventSink {
     emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
-import type { WorkflowMemoryConfig } from "./workflow-metadata.js";
-export type { WorkflowMemoryConfig };
+import type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
+export type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema };
 /** Turn/iteration budget for `agent(opts)`. Re-exported here so authors
  *  can type per-invoke budget overrides they pass as workflow input. */
 export interface AgentBudget {
@@ -69,21 +69,21 @@ export type WorkflowFn<TOutput = unknown, TInput extends Record<string, unknown>
 export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>> {
     run: WorkflowFn<TOutput, TInput>;
     /**
-     * Reference to a snapshot the runner should boot from at run start.
-     * Accepts a run UUID, a workflow name, or `name@version` — any workflow
-     * registered with `--build` produces a snapshot you can name here. The
-     * runner VM starts in that pre-configured state. Per-invocation
-     * `invoke({ snapshot })` overrides this default.
-     */
-    snapshot?: string;
-    /**
-     * Capture a snapshot of the sandbox on successful /complete. Snapshots
-     * are long-lived (never auto-expire) — customers list + delete them
-     * explicitly via `agentc snapshot list/delete`. Per-invocation
-     * `invoke({ saveSnapshot })` overrides this default.
-     * `defineSandboxEnvironment` sugar sets this to true by default.
+     * All snapshot config — boot source plus capture mode.
+     *
+     * `snapshots.bootFrom`: the runner restores from this exact provider
+     * snapshot id at run start. Omit to boot a fresh sandbox.
+     *
+     * `snapshots.saveLatest`: `true` captures one snapshot after each
+     * successful step (latest-only — prior is freed).
+     * `{ saveLatest: true, retainSteps: true }` keeps every step's
+     * snapshot for fork / replay / time-travel.
+     *
+     * Snapshots are long-lived (never auto-expire). List + delete via
+     * `agentc snapshot list/delete`. Per-invocation
+     * `invoke({ snapshots })` overrides this default.
      */
-    saveSnapshot?: boolean;
+    snapshots?: SnapshotConfig;
     /**
      * Outbound network policy for the runner sandbox.
      * Use "*": [] to allow all traffic while still injecting headers for specific domains.
@@ -120,10 +120,14 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
      * }
      */
     placeholders?: Record<string, string>;
-    /** Workflow Memory extraction. Defaults to "default" when omitted.
-     * Set false to skip memory extraction for this workflow, or point at a
-     * custom memory workflow once custom extractors are supported. */
+    /** Run the built-in memory extractor after this workflow completes.
+     *  Opt-in; defaults to false when omitted. */
     memory?: WorkflowMemoryConfig;
+    /** Ordered list of workflow names to dispatch as post-hooks after
+     *  this workflow completes. Each hook receives the source run's
+     *  context. The memory extractor (when `memory: true`) runs as an
+     *  additional hook alongside these. */
+    postRunHooks?: readonly string[];
 }
 /**
  * Declare a workflow. Two forms; both return a `Workflow` whose

package/dist/utils/bundler.d.ts

@@ -19,7 +19,7 @@
  * this function returns alongside the bundled bytes, and cross-checks the
  * manifest's `sourceHash` against the source it received.
  */
-import type { WorkflowMemoryConfig } from "../types/workflow.js";
+import type { WorkflowMemoryConfig, SnapshotConfig } from "../types/workflow.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import { type WorkflowPlan } from "../types/workflow-plan.js";
 /** Bumped when the manifest contract changes in a way the server should
@@ -51,15 +51,20 @@ export interface BundledWorkflow {
     manifest: WorkflowManifest;
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
-    /** Run UUID, workflow name, or `name@version` referencing the snapshot
-     *  this workflow's runner boots from, if declared via the `snapshot`
-     *  field on `defineWorkflow`. */
-    snapshot?: string;
-    /** Default capture-on-success flag from the workflow definition. */
-    saveSnapshot?: boolean;
+    /** Snapshot config from the workflow definition — `bootFrom` (where to
+     *  restore at run start), `save`, `retain`. */
+    snapshots?: SnapshotConfig;
     workflowPlan: WorkflowPlan;
     /** Workflow Memory extractor config. */
     memory?: WorkflowMemoryConfig;
+    /** Ordered post-hook workflow names declared on the workflow. */
+    postRunHooks?: readonly string[];
+    /** Compact JSON-Schema-shaped description of the workflow's input
+     *  type. Extracted from the workflow's declared `input` zod schema
+     *  at bundle time; undefined when the schema is `z.unknown()`. */
+    inputSchema?: import("../types/workflow-metadata.js").IOSchema;
+    /** Same for the workflow's output zod schema. */
+    outputSchema?: import("../types/workflow-metadata.js").IOSchema;
 }
 /**
  * Parse the bundled source and assert the default export is a CallExpression

package/dist/workflow-steps/workflow.d.ts

@@ -20,6 +20,7 @@
  */
 import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";
+import type { SnapshotConfig, WorkflowMemoryConfig } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 export interface WorkflowBuilder<TInput, TCurrent> {
@@ -41,8 +42,9 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
     output: z.ZodType<TOutput>;
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
-    snapshot?: string;
-    saveSnapshot?: boolean;
+    snapshots?: SnapshotConfig;
+    memory?: WorkflowMemoryConfig;
+    postRunHooks?: readonly string[];
     processors?: readonly Processor[];
 }
 export declare function createStepWorkflow<TInput, TOutput>(opts: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {

package/src/client.ts

@@ -17,6 +17,7 @@ import { parseSseStream } from "./sse.js";
 import type { SandboxNetworkPolicy } from "./sandbox.js";
 import type { RunEvent } from "./types/events.js";
 import type { WorkflowPlan } from "./types/workflow-plan.js";
+import type { SnapshotConfig, IOSchema } from "./types/workflow-metadata.js";
 import type { WorkflowManifest } from "./utils/bundler.js";
 
 /** UUID-v4-ish — matches the server-side predicate. Used to auto-detect
@@ -51,6 +52,13 @@ export interface RegisterResult {
   name: string;
   version: string;
   runtimes?: RegisteredRuntime[];
+  /** Non-fatal advisories from the server. Surfaced at register time so the
+   *  operator sees them while still in front of the terminal — currently
+   *  covers "memory extraction is configured but its workflow is not
+   *  registered in this factory". Empty/undefined when registration was
+   *  cleanly resolved against everything the workflow declares it
+   *  depends on. */
+  warnings?: string[];
 }
 
 export interface RegisteredRuntime {
@@ -79,14 +87,22 @@ export interface RegisterWorkflowInput {
   runtimes?: RuntimeSourceInput[];
   networkPolicy?: unknown;
   placeholders?: Record<string, string>;
-  /** Reference to a snapshot the runner should boot from at run start. */
-  snapshot?: string;
-  /** If true, runs default to capturing a long-lived sandbox snapshot on success. */
-  saveSnapshot?: boolean;
+  /** All snapshot config — `bootFrom` (where to restore at run start),
+   *  `save`, `retain`. See `WorkflowMetadata.snapshots`. */
+  snapshots?: SnapshotConfig;
   /** Provider-neutral execution plan detected by the CLI bundler. */
   workflowPlan?: WorkflowPlan;
-  /** Workflow Memory extraction config. Defaults to "default" when omitted. */
-  memory?: "default" | false | { workflow: string };
+  /** Run the built-in memory extractor after this workflow completes.
+   *  Opt-in; defaults to false when omitted. */
+  memory?: boolean;
+  /** Ordered list of workflow names that run as post-hooks after this
+   *  workflow completes. The memory extractor (when `memory: true`)
+   *  runs as an additional hook alongside these. */
+  postRunHooks?: readonly string[];
+  /** Input schema extracted from the workflow's `input` zod schema. */
+  inputSchema?: IOSchema;
+  /** Output schema extracted from the workflow's `output` zod schema. */
+  outputSchema?: IOSchema;
   /** Factory slug. Defaults to `"default"`. */
   factorySlug?: string;
 }
@@ -94,10 +110,11 @@ export interface RegisterWorkflowInput {
 export type RunState = "running" | "success" | "failed" | "abandoned" | "canceled";
 
 export interface InvokeWorkflowOptions {
-  /** Per-invocation snapshot override: run UUID, workflow name, or `name@version`. */
-  snapshot?:     string;
-  /** Per-invocation snapshot capture override. */
-  saveSnapshot?: boolean;
+  /** Per-invocation snapshot config override. `snapshots.bootFrom`
+   *  replaces the template's boot source; `snapshots.saveLatest` and
+   *  `snapshots.retainSteps` override capture mode. Anything omitted
+   *  falls back to the template's registered default. */
+  snapshots?: SnapshotConfig;
   /** Per-invocation network policy override. Replaces the template-level
    *  policy for this run only — registered metadata is not mutated. */
   networkPolicy?: SandboxNetworkPolicy;
@@ -106,6 +123,13 @@ export interface InvokeWorkflowOptions {
    *  vars after brokering. Replaces the template-level placeholders for
    *  this run only — registered metadata is not mutated. */
   placeholders?: Record<string, string>;
+  /** Per-invocation memory-extractor override — `false` skips the
+   *  built-in memory hook for this run; omitting leaves the registered
+   *  default in place. */
+  memory?:       boolean;
+  /** Per-invocation post-hook override — replaces the registered
+   *  `postRunHooks` array for this run only. */
+  postRunHooks?:    readonly string[];
   /** Explicit parent run id. Pass `null` to suppress ambient RUN_ID auto-detection. */
   parentRunId?:  string | null;
   /** Agent loop inside the parent run that caused this invoke, when applicable. */
@@ -124,8 +148,12 @@ export interface InvokeResult {
 }
 
 export interface ListSnapshotsOptions {
+  /** Factory slug. Defaults to `"default"`. */
+  factorySlug?: string;
   workflow?: string;
   limit?: number;
+  /** Cursor returned as `next_cursor` from `listSnapshotsPage`. */
+  before?: string;
 }
 
 export interface TemplateRow {
@@ -332,19 +360,66 @@ export interface CancelRunResponse {
 }
 
 export interface SnapshotListEntry {
+  snapshotId: string;
+  kind: "latest" | "step";
+  stepIndex: number | null;
   runId: string;
   workflow: string | null;
   version: string | null;
-  vercelSnapshotId: string;
-  endedAt: string | null;
+  createdAt: string | null;
+  /** Provider-reported on-disk size, or null when unavailable. */
+  sizeBytes: number | null;
+}
+
+export interface SnapshotListResponse {
+  object: "list";
+  data: SnapshotListEntry[];
+  has_more: boolean;
+  next_cursor: string | null;
 }
 
+export interface RunSnapshotEntry {
+  snapshotId: string;
+  /** `"latest"` = current/last pointer on the run.
+   *  `"step"` = retained per-step snapshot. */
+  kind: "latest" | "step";
+  stepIndex: number | null;
+  createdAt: string | null;
+  /** Provider-reported on-disk size, or null when unavailable. */
+  sizeBytes: number | null;
+}
+
+export interface AgentComposeClientOptions {
+  /** Your team's API key — minted from the dashboard or `agentc keys create`.
+   *  Required. Resolved from `process.env.AGENT_COMPOSE_API_KEY` when omitted. */
+  apiKey?: string;
+  /** Override the API host. Defaults to `process.env.AGENT_COMPOSE_URL` if
+   *  set, otherwise the public host (`https://api.agentcompose.ai`). Most
+   *  callers should leave this unset — the only consumers that need it are
+   *  the CLI's local-dev path and tests that point at a fake server. */
+  baseUrl?: string;
+}
+
+const PUBLIC_API_HOST = "https://api.agentcompose.ai";
+
 export class AgentComposeClient {
   private readonly fetch:   typeof ofetch;
   private readonly baseUrl: string;
   private readonly apiKey:  string;
 
-  constructor(baseUrl: string, apiKey: string) {
+  constructor(options: AgentComposeClientOptions = {}) {
+    const apiKey = options.apiKey
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_API_KEY : undefined)
+      ?? "";
+    if (!apiKey) {
+      throw new Error(
+        "AgentComposeClient: `apiKey` is required. Pass it as `{ apiKey }` " +
+        "or set the AGENT_COMPOSE_API_KEY env var.",
+      );
+    }
+    const baseUrl = options.baseUrl
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_URL : undefined)
+      ?? PUBLIC_API_HOST;
     this.baseUrl = baseUrl.replace(/\/$/, "");
     this.apiKey  = apiKey;
     this.fetch = ofetch.create({
@@ -366,16 +441,9 @@ export class AgentComposeClient {
 
   /** Invoke a workflow. Returns run ID immediately — workflow runs asynchronously.
    *
-   *  `snapshot`: per-invocation override of the template-level `snapshot`
-   *  field. Same forms — a run UUID, a workflow name, or `name@version`.
-   *  Use this when one template needs to boot from many different
-   *  snapshots (e.g. a benchmark workflow running against a different
-   *  starting state per invocation). Does not change the template's
-   *  registered default; only affects this run.
-   *
-   *  `saveSnapshot`: `true` overrides the workflow default; `false` opts
-   *  out. When the run captures a snapshot, its id is stamped on the row
-   *  and can be referenced as the `snapshot` field on other workflows.
+   *  `snapshots`: per-invocation snapshot config override. `bootFrom`
+   *  accepts `{ snapshotId }`; `saveLatest` / `retainSteps` control
+   *  capture. Merged field-by-field with the registered default.
    *
    *  `parentRunId`: links the new run to another of the same account's
    *  currently-running runs. When omitted, the client auto-detects from
@@ -399,10 +467,11 @@ export class AgentComposeClient {
       method: "POST",
       body: {
         input,
-        ...(opts?.snapshot      !== undefined ? { snapshot:      opts.snapshot }      : {}),
-        ...(opts?.saveSnapshot  !== undefined ? { saveSnapshot:  opts.saveSnapshot }  : {}),
+        ...(opts?.snapshots     !== undefined ? { snapshots:     opts.snapshots }     : {}),
         ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
         ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
+        ...(opts?.memory        !== undefined ? { memory:        opts.memory }        : {}),
+        ...(opts?.postRunHooks     !== undefined ? { postRunHooks:     opts.postRunHooks }     : {}),
         ...(parentRunId                       ? { parentRunId }                       : {}),
         ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
       },
@@ -441,20 +510,45 @@ export class AgentComposeClient {
     throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
   }
 
-  /** List runs this account has captured snapshots for. */
+  /** List captured snapshots in a factory. */
   async listSnapshots(opts?: ListSnapshotsOptions): Promise<SnapshotListEntry[]> {
+    const body = await this.listSnapshotsPage(opts);
+    return body.data;
+  }
+
+  /** List one page of captured snapshots in a factory. */
+  async listSnapshotsPage(opts?: ListSnapshotsOptions): Promise<SnapshotListResponse> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     const q = new URLSearchParams();
     if (opts?.workflow) q.set("workflow", opts.workflow);
     if (opts?.limit    != null) q.set("limit", String(opts.limit));
-    const body = await this.fetch<{ object: "list"; data: SnapshotListEntry[]; has_more: boolean }>(
-      `/api/v1/snapshots${q.toString() ? `?${q}` : ""}`,
+    if (opts?.before) q.set("before", opts.before);
+    return this.fetch<SnapshotListResponse>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/snapshots${q.toString() ? `?${q}` : ""}`,
     );
-    return body.data;
   }
 
   /** Delete the snapshot captured by a specific run. Frees Vercel storage. */
   deleteSnapshot(runId: string): Promise<void> {
-    return this.fetch(`/api/v1/workflows/${runId}/snapshot`, { method: "DELETE" });
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/snapshot`, { method: "DELETE" });
+  }
+
+  /** List all snapshots captured for a single run — the latest pointer
+   *  plus any retained per-step rows (`snapshots: { retainSteps: true }`). */
+  async listRunSnapshots(runId: string): Promise<RunSnapshotEntry[]> {
+    const body = await this.fetch<{ object: "list"; data: RunSnapshotEntry[]; has_more: boolean }>(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/snapshots`,
+    );
+    return body.data;
+  }
+
+  /** Delete one snapshot from a run by id. Walks both the latest pointer
+   *  and the retention rows; provider-side delete is best-effort. */
+  deleteRunSnapshot(runId: string, snapshotId: string): Promise<void> {
+    return this.fetch(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/snapshots/${encodeURIComponent(snapshotId)}`,
+      { method: "DELETE" },
+    );
   }
 
   /** Poll run status. */

package/src/index.ts

@@ -36,7 +36,15 @@ export type {
   WorkflowRun,
   AgentBudget,
   WorkflowHooks,
+  SnapshotConfig,
+  BootSnapshot,
+  IOSchema,
+  OutputSchema,
+  WorkflowMemoryConfig,
 } from "./types/workflow.js";
+
+// Snapshot entry type re-exported for consumers (dashboard, CLI).
+export type { RunSnapshotEntry } from "./client.js";
 export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
 export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
 
@@ -105,7 +113,7 @@ export type {
   CreateApiKeyInput, StreamRunLogsOptions,
   EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult,
   RunLogLine, ListRunLogsOptions,
-  RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry,
+  RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse,
   ApiKey, ApiKeyCreated,
   UsageRollupRow, UsageResponse,
   CancelRunResponse,

package/src/sandbox.ts

@@ -239,7 +239,11 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
     async snapshot() {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const res: any = await sb.snapshot({ expiration: 0 });
-      return { snapshotId: res.snapshotId as string };
+      const sizeBytes = typeof res.sizeBytes === "number" ? res.sizeBytes : undefined;
+      return {
+        snapshotId: res.snapshotId as string,
+        ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+      };
     },
   };
 }