@agent-compose/sdk 0.2.4 → 0.3.0

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 } : {}),
+      };
     },
   };
 }

package/src/types/sandbox-environment.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
@@ -39,20 +37,31 @@
 import type { SandboxProvider } from "./sandbox.js";
 import { defineWorkflow } from "./workflow.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 function defineSandboxEnvironment(
   env: SandboxEnvironmentDefinition,
 ): Workflow<Record<string, unknown>, void> {
@@ -60,7 +69,8 @@ export function defineSandboxEnvironment(
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
   return defineWorkflow<void, Record<string, unknown>>({
-    saveSnapshot: env.saveSnapshot ?? true,
+    snapshots: env.snapshots ?? { saveLatest: true },
+    memory:    env.memory    ?? false,
     run: async (_ctx, sandbox) => env.setup(sandbox),
   });
 }

package/src/types/sandbox.ts

@@ -32,8 +32,12 @@ 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. */
-  snapshot?(): Promise<{ snapshotId: string }>;
+   *  `--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/src/types/workflow-metadata.ts

@@ -20,18 +20,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[];
 }
 
 /**
@@ -54,12 +119,12 @@ export function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMeta
   const out: WorkflowMetadata = {};
   if (source.networkPolicy !== undefined) out.networkPolicy = freezeMetadataValue(source.networkPolicy);
   if (source.placeholders  !== undefined) out.placeholders  = Object.freeze({ ...source.placeholders });
-  if (source.snapshot      !== undefined) out.snapshot      = source.snapshot;
-  if (source.saveSnapshot  !== undefined) out.saveSnapshot  = source.saveSnapshot;
+  if (source.inputSchema   !== undefined) out.inputSchema   = freezeMetadataValue(source.inputSchema);
+  if (source.outputSchema  !== undefined) out.outputSchema  = freezeMetadataValue(source.outputSchema);
+  if (source.snapshots     !== undefined) out.snapshots     = Object.freeze({ ...source.snapshots });
   if (source.processors    !== undefined) out.processors    = Object.freeze([...source.processors]);
-  if (source.memory        !== undefined) out.memory        = typeof source.memory === "object" && source.memory !== null
-    ? Object.freeze({ ...source.memory })
-    : source.memory;
+  if (source.memory        !== undefined) out.memory        = source.memory;
+  if (source.postRunHooks     !== undefined) out.postRunHooks     = Object.freeze([...source.postRunHooks]);
   return Object.freeze(out);
 }
 

package/src/types/workflow.ts

@@ -37,8 +37,8 @@ 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. */
@@ -91,21 +91,21 @@ export interface WorkflowDefinition<
 > {
   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.
@@ -142,10 +142,14 @@ export interface WorkflowDefinition<
    * }
    */
   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[];
 }
 
 /**