@agent-compose/sdk 0.2.5 → 0.3.0

package/README.md

@@ -64,10 +64,10 @@ export default defineWorkflow({
 ```
 
 `defineWorkflow` is a thin sugar — it returns the bare `run` function with
-`networkPolicy` / `placeholders` / `snapshot` / `saveSnapshot` attached as
-metadata that the bundler picks up at registration time. A plain
-`export default async (ctx, sandbox) => {...}` is also valid; you just lose
-the metadata channel.
+`networkPolicy` / `placeholders` / `snapshots` / `memory` / `postRunHooks`
+attached as metadata that the bundler picks up at registration time. A
+plain `export default async (ctx, sandbox) => {...}` is also valid; you
+just lose the metadata channel.
 
 ### What the workflow can do with `ctx`
 
@@ -183,7 +183,7 @@ await client.register({
   runtimes:    bundled.runtimes,        // [{ name, source }] — embedded so the runner has them locally
   schedule:    "*/30 * * * *",          // optional cron
   factorySlug: "default",                // optional — defaults to "default"
-  // snapshot, saveSnapshot, networkPolicy, placeholders — all optional
+  // snapshots, memory, postRunHooks, networkPolicy, placeholders — all optional
 });
 ```
 
@@ -216,9 +216,10 @@ async run() { return … } })` resolves to). `setMetadata()` writes to a
 separate `metadata` field — useful for "side-channel" facts (PR url, plan
 url) without polluting the structured return.
 
-`invoke` and `invokeAndWait` both accept `{ factorySlug, snapshot,
-saveSnapshot, parentRunId }` as the third argument. `factorySlug` defaults
-to `"default"`.
+`invoke` and `invokeAndWait` both accept `{ factorySlug, snapshots,
+memory, postRunHooks, networkPolicy, placeholders, parentRunId }` as the
+third argument. Per-invocation `snapshots` merges field-by-field with
+the registered default. `factorySlug` defaults to `"default"`.
 
 ### Auto parent/child tracing
 
@@ -348,26 +349,37 @@ CLI equivalent: `agentc usage`.
 ## Snapshots (replay-friendly sandboxes)
 
 Long-running workflows can capture the runner sandbox as a Vercel snapshot
-on success (`saveSnapshot: true`). Other workflows reference that snapshot
-via the `snapshot` field to boot into the same prepared VM (deps installed,
-repo cloned, etc.) instead of repeating setup.
+on success (`snapshots: { saveLatest: true }`). Other workflows reference
+that snapshot via `snapshots.bootFrom` to boot into the same prepared VM
+(deps installed, repo cloned, etc.) instead of repeating setup.
 
 ```ts
 // Capture per-invocation:
-await client.invoke("my-workflow", input, { saveSnapshot: true });
+await client.invoke("my-workflow", input, { snapshots: { saveLatest: true } });
 
-// Boot from a different snapshot per invocation (per-invocation override):
-await client.invoke("my-workflow", input, { snapshot: "<run-id-or-name>" });
+// Boot from a captured snapshot — pick the id from `agentc snapshot
+// list` or the dashboard snapshots page:
+await client.invoke("my-workflow", input, {
+  snapshots: { bootFrom: { snapshotId: "snap_…" } },
+});
+
+// Set a default at registration time:
+defineWorkflow({ run, snapshots: { saveLatest: true } });
 
-// Or set a default at registration time:
-defineWorkflow({ run, saveSnapshot: true });
+// Retain every step's snapshot (not just the latest):
+defineWorkflow({ run, snapshots: { saveLatest: true, retainSteps: true } });
 
 // Browse / clean up:
-const snaps = await client.listSnapshots({ workflow: "my-workflow", limit: 50 });
-await client.deleteSnapshot(snaps[0].runId);
+const page = await client.listSnapshotsPage({ workflow: "my-workflow", limit: 50 });
+const snaps = page.data;
+await client.deleteRunSnapshot(snaps[0].runId, snaps[0].snapshotId);
 ```
 
-CLI equivalents: `agentc snapshot list` / `agentc snapshot delete <run-id>`.
+CLI equivalents: `agentc snapshot list` / `agentc snapshot delete <run-id> <snapshot-id>`.
+
+### Per-invocation overrides merge field-by-field
+
+The `snapshots` object on `invoke()` is **merged** with the registered template's `snapshots` config — you can override `bootFrom` alone without losing `saveLatest`, or vice versa. Same for `memory` (boolean) and `postRunHooks` (string[]).
 
 ---
 

package/dist/client.d.ts

@@ -13,12 +13,20 @@
 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";
 export interface RegisterResult {
     id: string;
     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 {
     id: string;
@@ -44,25 +52,32 @@ 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;
 }
 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;
@@ -71,6 +86,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. */
@@ -86,8 +108,12 @@ export interface InvokeResult {
     id: string;
 }
 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 {
     name: string;
@@ -275,32 +301,55 @@ export interface CancelRunResponse {
     canceledAt: string;
 }
 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;
 }
 export declare class AgentComposeClient {
     private readonly fetch;
     private readonly baseUrl;
     private readonly apiKey;
-    constructor(baseUrl: string, apiKey: string);
+    constructor(options?: AgentComposeClientOptions);
     /** Register (or update) a workflow template inside a factory. Defaults to
      *  the team's `default` factory when `factorySlug` is omitted. */
     register(payload: RegisterWorkflowInput): Promise<RegisterResult>;
     /** 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
@@ -320,10 +369,18 @@ export declare class AgentComposeClient {
      *  tests, tune up for long-running workflows. The parent-child auto-
      *  detection from `invoke()` applies here too. */
     invokeAndWait<TOutput = unknown>(name: string, input?: Record<string, unknown>, opts?: InvokeAndWaitOptions): Promise<RunStatus<TOutput>>;
-    /** List runs this account has captured snapshots for. */
+    /** List captured snapshots in a factory. */
     listSnapshots(opts?: ListSnapshotsOptions): Promise<SnapshotListEntry[]>;
+    /** List one page of captured snapshots in a factory. */
+    listSnapshotsPage(opts?: ListSnapshotsOptions): Promise<SnapshotListResponse>;
     /** Delete the snapshot captured by a specific run. Frees Vercel storage. */
     deleteSnapshot(runId: string): Promise<void>;
+    /** List all snapshots captured for a single run — the latest pointer
+     *  plus any retained per-step rows (`snapshots: { retainSteps: true }`). */
+    listRunSnapshots(runId: string): Promise<RunSnapshotEntry[]>;
+    /** 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>;
     /** Poll run status. */
     getStatus<TOutput = unknown>(runId: string): Promise<RunStatus<TOutput>>;
     /** Full run detail, including input/output and lifecycle events. */

package/dist/index.d.ts

@@ -16,7 +16,8 @@ export type { WorkflowDefinition } from "./types/workflow.js";
 export { defineSandboxEnvironment } from "./types/sandbox-environment.js";
 export type { SandboxEnvironmentDefinition } from "./types/sandbox-environment.js";
 export type { AgentRuntime, McpServerConfig, ModelExecutionContract, ToolCallGateResult, RuntimeOptions, } from "./types/runtime.js";
-export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks, } from "./types/workflow.js";
+export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema, WorkflowMemoryConfig, } from "./types/workflow.js";
+export type { RunSnapshotEntry } from "./client.js";
 export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
 export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
 export { RequestContext, ReservedKeyError, NonSerialisableValueError, AC_RESERVED_PREFIX, AC_TEAM_ID, AC_RUN_ID, AC_WORKFLOW_ID, AC_FACTORY_ID, AC_API_KEY_SCOPES, AC_PARENT_RUN_ID, AC_ABORT_SIGNAL, } from "./request-context/index.js";
@@ -26,7 +27,7 @@ export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from ".
 export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, } from "./types/sandbox.js";
 export { AgentComposeClient } from "./client.js";
-export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, CancelRunResponse, } from "./client.js";
+export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, CancelRunResponse, } from "./client.js";
 export { parseSseStream } from "./sse.js";
 export { AgentComposeError } from "./errors.js";
 export { formatError } from "./utils/errors.js";

package/dist/index.js

@@ -481,14 +481,18 @@ function extractMetadata(source) {
     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;
+    out.memory = source.memory;
+  if (source.postRunHooks !== undefined)
+    out.postRunHooks = Object.freeze([...source.postRunHooks]);
   return Object.freeze(out);
 }
 function freezeMetadataValue(value) {
@@ -583,7 +587,8 @@ function defineSandboxEnvironment(env) {
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
   return defineWorkflow({
-    saveSnapshot: env.saveSnapshot ?? true,
+    snapshots: env.snapshots ?? { saveLatest: true },
+    memory: env.memory ?? false,
     run: async (_ctx, sandbox) => env.setup(sandbox)
   });
 }
@@ -695,12 +700,18 @@ function templatePath(factorySlug, ...rest) {
   const tail = rest.length > 0 ? "/" + rest.map(encodeURIComponent).join("/") : "";
   return `/api/v1/factories/${encodeURIComponent(factorySlug)}/templates${tail}`;
 }
+var PUBLIC_API_HOST = "https://api.agentcompose.ai";
 
 class AgentComposeClient {
   fetch;
   baseUrl;
   apiKey;
-  constructor(baseUrl, apiKey) {
+  constructor(options = {}) {
+    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({
@@ -723,10 +734,11 @@ 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 } : {}
       }
@@ -747,16 +759,29 @@ class AgentComposeClient {
     throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
   }
   async listSnapshots(opts) {
+    const body = await this.listSnapshotsPage(opts);
+    return body.data;
+  }
+  async listSnapshotsPage(opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     const q2 = new URLSearchParams;
     if (opts?.workflow)
       q2.set("workflow", opts.workflow);
     if (opts?.limit != null)
       q2.set("limit", String(opts.limit));
-    const body = await this.fetch(`/api/v1/snapshots${q2.toString() ? `?${q2}` : ""}`);
-    return body.data;
+    if (opts?.before)
+      q2.set("before", opts.before);
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/snapshots${q2.toString() ? `?${q2}` : ""}`);
   }
   deleteSnapshot(runId) {
-    return this.fetch(`/api/v1/workflows/${runId}/snapshot`, { method: "DELETE" });
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/snapshot`, { method: "DELETE" });
+  }
+  async listRunSnapshots(runId) {
+    const body = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/snapshots`);
+    return body.data;
+  }
+  deleteRunSnapshot(runId, snapshotId) {
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/snapshots/${encodeURIComponent(snapshotId)}`, { method: "DELETE" });
   }
   getStatus(runId) {
     return this.fetch(`/api/v1/workflows/${runId}/status`);
@@ -1017,17 +1042,59 @@ async function bundleWorkflow(workflowPath, overrides) {
     sourceHash: sha256(source),
     bundlerVersion: BUNDLER_VERSION
   };
+  const inputSchema = extractIOSchema(workflow.input);
+  const outputSchema = extractIOSchema(workflow.output);
   return {
     source,
     manifest,
     workflowPlan: plan,
     networkPolicy: overrides?.networkPolicy ?? metadata.networkPolicy,
     placeholders: overrides?.placeholders ?? metadata.placeholders,
-    ...metadata.snapshot !== undefined ? { snapshot: metadata.snapshot } : {},
-    ...metadata.saveSnapshot !== undefined ? { saveSnapshot: metadata.saveSnapshot } : {},
-    ...metadata.memory !== undefined ? { memory: metadata.memory } : {}
+    ...inputSchema !== undefined ? { inputSchema } : {},
+    ...outputSchema !== undefined ? { outputSchema } : {},
+    ...metadata.snapshots !== undefined ? { snapshots: metadata.snapshots } : {},
+    ...metadata.memory !== undefined ? { memory: metadata.memory } : {},
+    ...metadata.postRunHooks !== undefined ? { postRunHooks: metadata.postRunHooks } : {}
   };
 }
+function extractIOSchema(zodSchema) {
+  let json;
+  try {
+    const z3 = __require("zod");
+    if (!z3.toJSONSchema)
+      return;
+    json = z3.toJSONSchema(zodSchema);
+  } catch {
+    return;
+  }
+  if (!json || typeof json !== "object")
+    return;
+  if (Object.keys(json).filter((k) => k !== "$schema").length === 0)
+    return;
+  const out = {};
+  if (json.type !== undefined)
+    out.type = json.type;
+  if (json.description !== undefined)
+    out.description = String(json.description);
+  if (json.properties && typeof json.properties === "object") {
+    const props = {};
+    for (const [key, raw] of Object.entries(json.properties)) {
+      if (raw && typeof raw === "object") {
+        const r = raw;
+        props[key] = {};
+        if (r.type !== undefined)
+          props[key].type = r.type;
+        if (r.description !== undefined)
+          props[key].description = String(r.description);
+      }
+    }
+    if (Object.keys(props).length > 0)
+      out.properties = props;
+  }
+  if (Array.isArray(json.required))
+    out.required = json.required.map(String);
+  return out;
+}
 // src/utils/schemas.ts
 import { z as z3 } from "zod";
 var AgentStatusSchema = z3.object({
@@ -1544,7 +1611,11 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
     },
     async snapshot() {
       const res = await sb.snapshot({ expiration: 0 });
-      return { snapshotId: res.snapshotId };
+      const sizeBytes = typeof res.sizeBytes === "number" ? res.sizeBytes : undefined;
+      return {
+        snapshotId: res.snapshotId,
+        ...sizeBytes !== undefined ? { sizeBytes } : {}
+      };
     }
   };
 }
@@ -2049,7 +2120,7 @@ function buildInvokeChild(runId, opts = {}) {
     if (!baseUrl || !apiKey) {
       throw new Error("ctx.invokeChild requires AGENT_COMPOSE_URL and AGENT_COMPOSE_API_KEY");
     }
-    childClient = new AgentComposeClient(baseUrl, apiKey);
+    childClient = new AgentComposeClient({ apiKey, baseUrl });
     return childClient;
   };
   return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {

package/dist/runtimes/openai-desktop.js

@@ -481,14 +481,18 @@ function extractMetadata(source) {
     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;
+    out.memory = source.memory;
+  if (source.postRunHooks !== undefined)
+    out.postRunHooks = Object.freeze([...source.postRunHooks]);
   return Object.freeze(out);
 }
 function freezeMetadataValue(value) {
@@ -583,7 +587,8 @@ function defineSandboxEnvironment(env) {
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
   return defineWorkflow({
-    saveSnapshot: env.saveSnapshot ?? true,
+    snapshots: env.snapshots ?? { saveLatest: true },
+    memory: env.memory ?? false,
     run: async (_ctx, sandbox) => env.setup(sandbox)
   });
 }
@@ -695,12 +700,18 @@ function templatePath(factorySlug, ...rest) {
   const tail = rest.length > 0 ? "/" + rest.map(encodeURIComponent).join("/") : "";
   return `/api/v1/factories/${encodeURIComponent(factorySlug)}/templates${tail}`;
 }
+var PUBLIC_API_HOST = "https://api.agentcompose.ai";
 
 class AgentComposeClient {
   fetch;
   baseUrl;
   apiKey;
-  constructor(baseUrl, apiKey) {
+  constructor(options = {}) {
+    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({
@@ -723,10 +734,11 @@ 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 } : {}
       }
@@ -747,16 +759,29 @@ class AgentComposeClient {
     throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
   }
   async listSnapshots(opts) {
+    const body = await this.listSnapshotsPage(opts);
+    return body.data;
+  }
+  async listSnapshotsPage(opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     const q2 = new URLSearchParams;
     if (opts?.workflow)
       q2.set("workflow", opts.workflow);
     if (opts?.limit != null)
       q2.set("limit", String(opts.limit));
-    const body = await this.fetch(`/api/v1/snapshots${q2.toString() ? `?${q2}` : ""}`);
-    return body.data;
+    if (opts?.before)
+      q2.set("before", opts.before);
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/snapshots${q2.toString() ? `?${q2}` : ""}`);
   }
   deleteSnapshot(runId) {
-    return this.fetch(`/api/v1/workflows/${runId}/snapshot`, { method: "DELETE" });
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/snapshot`, { method: "DELETE" });
+  }
+  async listRunSnapshots(runId) {
+    const body = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/snapshots`);
+    return body.data;
+  }
+  deleteRunSnapshot(runId, snapshotId) {
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/snapshots/${encodeURIComponent(snapshotId)}`, { method: "DELETE" });
   }
   getStatus(runId) {
     return this.fetch(`/api/v1/workflows/${runId}/status`);
@@ -1017,17 +1042,59 @@ async function bundleWorkflow(workflowPath, overrides) {
     sourceHash: sha256(source),
     bundlerVersion: BUNDLER_VERSION
   };
+  const inputSchema = extractIOSchema(workflow.input);
+  const outputSchema = extractIOSchema(workflow.output);
   return {
     source,
     manifest,
     workflowPlan: plan,
     networkPolicy: overrides?.networkPolicy ?? metadata.networkPolicy,
     placeholders: overrides?.placeholders ?? metadata.placeholders,
-    ...metadata.snapshot !== undefined ? { snapshot: metadata.snapshot } : {},
-    ...metadata.saveSnapshot !== undefined ? { saveSnapshot: metadata.saveSnapshot } : {},
-    ...metadata.memory !== undefined ? { memory: metadata.memory } : {}
+    ...inputSchema !== undefined ? { inputSchema } : {},
+    ...outputSchema !== undefined ? { outputSchema } : {},
+    ...metadata.snapshots !== undefined ? { snapshots: metadata.snapshots } : {},
+    ...metadata.memory !== undefined ? { memory: metadata.memory } : {},
+    ...metadata.postRunHooks !== undefined ? { postRunHooks: metadata.postRunHooks } : {}
   };
 }
+function extractIOSchema(zodSchema) {
+  let json;
+  try {
+    const z3 = __require("zod");
+    if (!z3.toJSONSchema)
+      return;
+    json = z3.toJSONSchema(zodSchema);
+  } catch {
+    return;
+  }
+  if (!json || typeof json !== "object")
+    return;
+  if (Object.keys(json).filter((k) => k !== "$schema").length === 0)
+    return;
+  const out = {};
+  if (json.type !== undefined)
+    out.type = json.type;
+  if (json.description !== undefined)
+    out.description = String(json.description);
+  if (json.properties && typeof json.properties === "object") {
+    const props = {};
+    for (const [key, raw] of Object.entries(json.properties)) {
+      if (raw && typeof raw === "object") {
+        const r = raw;
+        props[key] = {};
+        if (r.type !== undefined)
+          props[key].type = r.type;
+        if (r.description !== undefined)
+          props[key].description = String(r.description);
+      }
+    }
+    if (Object.keys(props).length > 0)
+      out.properties = props;
+  }
+  if (Array.isArray(json.required))
+    out.required = json.required.map(String);
+  return out;
+}
 // src/utils/schemas.ts
 import { z as z3 } from "zod";
 var AgentStatusSchema = z3.object({
@@ -1544,7 +1611,11 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
     },
     async snapshot() {
       const res = await sb.snapshot({ expiration: 0 });
-      return { snapshotId: res.snapshotId };
+      const sizeBytes = typeof res.sizeBytes === "number" ? res.sizeBytes : undefined;
+      return {
+        snapshotId: res.snapshotId,
+        ...sizeBytes !== undefined ? { sizeBytes } : {}
+      };
     }
   };
 }
@@ -2049,7 +2120,7 @@ function buildInvokeChild(runId, opts = {}) {
     if (!baseUrl || !apiKey) {
       throw new Error("ctx.invokeChild requires AGENT_COMPOSE_URL and AGENT_COMPOSE_API_KEY");
     }
-    childClient = new AgentComposeClient(baseUrl, apiKey);
+    childClient = new AgentComposeClient({ apiKey, baseUrl });
     return childClient;
   };
   return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {