@agent-compose/sdk 0.2.5 → 0.3.0

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[];
 }
 
 /**

package/src/utils/bundler.ts

@@ -24,7 +24,7 @@ import { createHash } from "node:crypto";
 import { parse as babelParse } from "@babel/parser";
 import type { File, ExportDefaultDeclaration, CallExpression, Expression, Statement } from "@babel/types";
 import { importSourceModule } from "./source-loader.js";
-import type { WorkflowMemoryConfig } from "../types/workflow.js";
+import type { WorkflowMemoryConfig, SnapshotConfig } from "../types/workflow.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import { isWorkflow } from "../workflow-steps/workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
@@ -65,15 +65,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;
 }
 
 async function bundle(path: string, label: string): Promise<string> {
@@ -270,14 +275,76 @@ export async function bundleWorkflow(
     bundlerVersion:  BUNDLER_VERSION,
   };
 
+  // Input + output schemas: the workflow's `input` / `output` zod
+  // schemas → compact JSON-Schema-shaped descriptions carried in
+  // template metadata. Used by the dashboard's "Registered" panel to
+  // render schema tables and (eventually) client-side validation in
+  // the playground. Run-form workflows stamp `z.unknown()` for both
+  // — `extractIOSchema` filters those down to undefined so the
+  // dashboard renders the "no declared schema" empty state instead
+  // of a meaningless empty table.
+  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 } : {}),
   };
 }
+
+/** Convert a workflow's `input` or `output` zod schema into a compact,
+ *  serialisable description for template metadata. Uses Zod 4's
+ *  `toJSONSchema` and trims the result to fields the dashboard
+ *  renders — full draft 2020-12 schemas have refs / unions / nested
+ *  allOf chains that are noisier than the dashboard needs.
+ *
+ *  Returns undefined when:
+ *    - The schema can't be serialised (corrupt / unknown variant)
+ *    - The schema is effectively `unknown` (the run-form sugar default —
+ *      no meaningful contract to render). */
+function extractIOSchema(
+  zodSchema: { _zod?: unknown } | unknown,
+): import("../types/workflow-metadata.js").IOSchema | undefined {
+  // Late require to keep this module tree-shakeable for callers that
+  // don't bundle. `toJSONSchema` lives on the top-level Zod export in v4.
+  let json: Record<string, unknown> | undefined;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const z = require("zod") as { toJSONSchema?: (s: unknown) => Record<string, unknown> };
+    if (!z.toJSONSchema) return undefined;
+    json = z.toJSONSchema(zodSchema);
+  } catch {
+    return undefined;
+  }
+  if (!json || typeof json !== "object") return undefined;
+
+  // `z.unknown()` serialises to `{}` (no type, no properties). Skip that
+  // — there's nothing useful to show.
+  if (Object.keys(json).filter((k) => k !== "$schema").length === 0) return undefined;
+
+  const out: import("../types/workflow-metadata.js").OutputSchema = {};
+  if (json.type        !== undefined) out.type        = json.type as string | string[];
+  if (json.description !== undefined) out.description = String(json.description);
+  if (json.properties && typeof json.properties === "object") {
+    const props: Record<string, { type?: string | string[]; description?: string }> = {};
+    for (const [key, raw] of Object.entries(json.properties as Record<string, unknown>)) {
+      if (raw && typeof raw === "object") {
+        const r = raw as Record<string, unknown>;
+        props[key] = {};
+        if (r.type        !== undefined) props[key].type        = r.type as string | string[];
+        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;
+}

package/src/workflow-steps/workflow.ts

@@ -23,6 +23,7 @@ import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";
 import { WORKFLOW_BRAND } from "./types.js";
 import { extractMetadata } from "../types/workflow-metadata.js";
+import type { SnapshotConfig, WorkflowMemoryConfig } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 
@@ -46,8 +47,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[];
 }
 

package/src/workflows/invoke-child.ts

@@ -18,7 +18,7 @@ export function buildInvokeChild(
     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, {