@agent-compose/sdk 0.6.0 → 0.8.0

package/src/types/workflow.ts

@@ -1,45 +1,33 @@
 /**
- * Workflow types — the context and function signature for authoring workflows.
+ * Workflow authoring types — `defineWorkflow` and the shared author-facing
+ * type surface.
  *
- * A workflow is `async (ctx, sandbox) => T`. Two positional args by design:
- *
- *   - `ctx` carries facts + observability about THIS run (id, input,
- *     setMetadata, step). Metadata bag.
- *   - `sandbox` is a capability handed to you by the engine for doing work
- *     (exec commands, write files). Pass it to `agent({ sandbox, ... })`
- *     and to any helper that takes a SandboxProvider (git utilities, file
- *     writers). Constructed once per run; reuse it.
+ * Workflows are STEP-FORM only: a builder of discrete, durable steps —
+ * `defineWorkflow({ id, input, output }).step(defineStep(...)).build()`.
+ * Every step is a replay checkpoint; pause/resume works at step
+ * granularity. The legacy run-form (`defineWorkflow({ run(ctx, sandbox)
+ * { … } })`) has been removed — passing a `run` key throws at
+ * definition time (i.e. at registration, loud and early).
  *
  * LLM agent loops live in `agent(opts)` (sdk/src/agent/run-agent.ts).
  * Invoking other workflows uses `AgentComposeClient.invoke[AndWait](...)`.
  */
 
-import { z } from "zod";
-import type { SandboxNetworkPolicy } from "../sandbox.js";
-import type { SandboxProvider } from "./sandbox.js";
 import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
-import type { Processor } from "../processors/processor.js";
 import { createStepWorkflow } from "../workflow-steps/workflow.js";
-import type { StepWorkflowDefinition } from "../workflow-steps/workflow.js";
-import type { Step, Workflow } from "../workflow-steps/types.js";
-import { WORKFLOW_BRAND } from "../workflow-steps/types.js";
-import type { BaseExecutionContext, WorkflowRun } from "./execution-context.js";
-import { extractMetadata, type WorkflowMetadata, type ConnectorRequirements, type ConnectorOperationTag, type InvokePolicy } from "./workflow-metadata.js";
+import type { StepWorkflowDefinition, WorkflowBuilder } from "../workflow-steps/workflow.js";
 
 export type { WorkflowRun, InvokeChild, BaseExecutionContext } from "./execution-context.js";
 // Re-export so consumers can keep importing `WorkflowMetadata` from
 // `@agent-compose/sdk` — the canonical definition lives in
 // `./workflow-metadata.js` to break a runtime import cycle with
 // `workflow-steps/workflow.ts`.
-export type { WorkflowMetadata } from "./workflow-metadata.js";
+export type { WorkflowMetadata, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources } from "./workflow-metadata.js";
 
 export interface AgentEventSink {
   emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
 
-import type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources } from "./workflow-metadata.js";
-export type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources };
-
 /** 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 {
@@ -47,270 +35,27 @@ export interface AgentBudget {
   maxIterations: number;
 }
 
-/** Context passed to a workflow function — facts + observability for this run. */
-export interface WorkflowCtx<TInput extends Record<string, unknown> = Record<string, unknown>> extends Omit<BaseExecutionContext, "sandbox"> {
-  input?: TInput;
-  /** Persist key-value metadata on the run record (e.g. prUrl, planUrl). */
-  setMetadata: (data: Record<string, unknown>) => Promise<void>;
-  /**
-   * Durable named step (ADR-0012). Runs `fn` once and memoises its result to
-   * the sandbox state-dir; on a pause-resume re-entry the recorded value is
-   * returned and `fn` is NOT re-run (a duration-0 "restored" sub-step). Also
-   * emits substep_started / substep_completed / substep_failed lifecycle
-   * events with duration — use for long phases you want both durable and
-   * visible on the run's timeline (setup, external API calls, submit).
-   *
-   * Names must be unique within a step body (they key the memoise file).
-   * A body that pauses is never memoised — the resume re-runs it. For
-   * cross-process side effects (DB writes, emails) use `invokeChild`.
-   */
-  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
-  /** Pass to `agent({ events: ctx.agentEvents })` to stream agent lifecycle events. */
-  agentEvents: AgentEventSink;
-  /**
-   * Workflow-level processors registered via `defineWorkflow({ processors })`.
-   * Read-only here. Authors merge with agent-specific lists when calling
-   * `agent({ processors: [...ctx.processors, mySpecific] })`.
-   *
-   * Empty array when the workflow declared no processors.
-   */
-  processors: readonly Processor[];
-}
-
-/** A workflow is `async (ctx, sandbox) => TOutput`. */
-export type WorkflowFn<
-  TOutput = unknown,
-  TInput extends Record<string, unknown> = Record<string, unknown>,
-> = (ctx: WorkflowCtx<TInput>, sandbox: SandboxProvider) => Promise<TOutput>;
-
-/**
- * Declare a workflow with server-side metadata.
- * Use `export default defineWorkflow({ run, networkPolicy, ... })` to attach
- * a runner network policy so the server brokers credentials for the workflow
- * sandbox.
- *
- * Without defineWorkflow, a plain `export default async (ctx) => {...}` still
- * works — the workflow just runs with secrets passed directly in env.
- */
-export interface WorkflowDefinition<
-  TOutput = unknown,
-  TInput extends Record<string, unknown> = Record<string, unknown>,
-> {
-  /** One-line, human-readable description of what this workflow does.
-   *  Surfaced on the dashboard template tile + run page header. */
-  description?: string;
-  /** Zod schema for the workflow's `input`. When declared, the SDK
-   *  bundler captures it as JSON-Schema-shaped `inputSchema` in
-   *  template metadata, the dashboard playground renders a typed
-   *  form, and the engine validates dispatched payloads against it
-   *  at the step boundary. Omit to leave inputs as `unknown` (the
-   *  legacy default — playground falls back to a freeform JSON
-   *  textarea). */
-  input?:  z.ZodType<TInput>;
-  /** Same as `input`, for the workflow's return value. Captured into
-   *  `outputSchema` metadata and rendered in the IO panel. */
-  output?: z.ZodType<TOutput>;
-  run: WorkflowFn<TOutput, TInput>;
-  /**
-   * 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.
-   */
-  snapshots?: SnapshotConfig;
-  /**
-   * Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string:
-   * `2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`) and `provider`
-   * (`vercel` | `e2b`). `size` maps to provider machine specs at create
-   * (Vercel: vCPUs, 2048 MB RAM per vCPU); E2B sizing is template-defined and
-   * ignores it. Optional; omit → smallest SKU on the default provider.
-   * Per-invocation `invoke({ size })` overrides the size.
-   */
-  resources?: SandboxResources;
-  /**
-   * Outbound network policy for the runner sandbox.
-   * Use "*": [] to allow all traffic while still injecting headers for specific domains.
-   * Secret values are referenced as $VARIABLE and resolved from GCP at dispatch time.
-   * Vercel only — E2B ignores.
-   *
-   * @example
-   * networkPolicy: {
-   *   allow: {
-   *     "*": [],
-   *     "api.github.com": [{ transform: [{ headers: { "Authorization": "basic:$GITHUB_TOKEN" } }] }],
-   *   }
-   * }
-   */
-  networkPolicy?: SandboxNetworkPolicy;
-  /**
-   * Workflow-level processor chain — runs around every `agent(...)` loop the
-   * workflow body launches, ahead of any agent-specific processors. Use for
-   * org-wide gating (deny destructive tools, require scopes). Authors merge
-   * with agent-specific lists via `[...ctx.processors, ...]`.
-   */
-  processors?: readonly Processor[];
-  /**
-   * Optional placeholder env var values for secrets referenced in the network policy.
-   * By default, brokered secrets are removed from the runner env entirely — the real
-   * values are only ever present inside the Vercel firewall config, never in the VM.
-   * Only set this if a tool or SDK validates the env var format on startup before
-   * making any requests (e.g. some CLIs check that ANTHROPIC_API_KEY looks like a
-   * real key). The placeholder is a syntactically valid but non-functional stand-in.
-   *
-   * @example
-   * placeholders: {
-   *   ANTHROPIC_API_KEY: `sk-ant-api03-${"a".repeat(95)}`,
-   * }
-   */
-  placeholders?: Record<string, string>;
-  /**
-   * Connector requirements (ADR-0007). Declaring a provider makes the
-   * server resolve an authorized OAuth grant for the calling principal at
-   * dispatch time and inject a fresh access token at the network layer —
-   * workflow code talks to the provider API with plain fetch/SDKs and
-   * never holds the credential.
-   *
-   * @example
-   * connectors: { github: { scopes: ["repo"] } }
-   */
-  connectors?: ConnectorRequirements;
-  /**
-   * Marks this workflow as a catalogue OPERATION of a connector — e.g.
-   * the `create-issue` operation of the `github` connector. Pair with
-   * `description` + `input`/`output` schemas so the operation is fully
-   * self-describing (MCP-tool-like) to humans and agents browsing the
-   * connector catalogue.
-   *
-   * @example
-   * connectorOperation: { provider: "github", operation: "create-issue" }
-   */
-  connectorOperation?: ConnectorOperationTag;
-  /**
-   * Tier-1 invoke ACL (connector credential boundary). When this workflow
-   * declares `connectors` (it brokers a credential) AND an `invokePolicy`,
-   * the server evaluates the calling principal against the policy BEFORE
-   * binding any grant — a caller matching no clause is refused with HTTP
-   * 403. Has no effect on workflows that declare no connectors. Omit to
-   * leave the workflow invokable by the whole team.
-   *
-   * @example
-   * connectors: { github: { access: "read" } },
-   * invokePolicy: { users: "owner", workflows: ["nightly-orchestrator"] }
-   */
-  invokePolicy?: InvokePolicy;
-  /**
-   * Internal — set by `defineSandboxEnvironment`, not by workflow authors.
-   * Marks the workflow as an environment build (base-env / agent-env) so the
-   * server skips mounting the shared factory drive for its runs (#13). See
-   * `WorkflowMetadata.environmentBuild`.
-   */
-  environmentBuild?: boolean;
-}
-
-/**
- * Wrap a legacy `(ctx, sandbox) => T` workflow body as a single-step
- * `Workflow` so the engine has one shape to drive. The synthesised step
- * runs the user's `run` body inline; `ctx.setMetadata` / `ctx.step` /
- * `ctx.agentEvents` proxy directly to the underlying `StepContext` hooks,
- * which the engine flushes to the run timeline exactly as the legacy
- * full-mode runner did.
- *
- * Lifecycle granularity is workflow-level (one outer "run" step) — the
- * `ctx.step("name", fn)` calls inside the body become sub-step events
- * under that one step. Authors keep the same source; the dashboard sees
- * the same timeline shape.
- */
-// TODO: collapse run-form into pure sugar over step-form. Run-form
-// already compiles to step-form-with-one-step here, so maintaining two
-// authoring surfaces is API duplication that periodically drifts (see
-// the input/output thread-through bug fixed on 2026-05-20: step-form
-// preserved schemas, run-form silently stamped z.unknown()). Cleaner:
-// turn `defineWorkflow({ run })` into a thin wrapper that calls the
-// step builder with a synthesised `{name:"run", input, output, run}`
-// step, then delete this function. Runtime stays identical.
-function compileRunForm<TOutput, TInput extends Record<string, unknown>>(
-  def: WorkflowDefinition<TOutput, TInput>,
-  metadata: WorkflowMetadata,
-): Workflow<TInput, TOutput> {
-  const unknownSchema = z.unknown() as z.ZodType<unknown>;
-  const inputSchema:  z.ZodType<TInput>  = def.input  ?? (unknownSchema as z.ZodType<TInput>);
-  const outputSchema: z.ZodType<TOutput> = def.output ?? (unknownSchema as z.ZodType<TOutput>);
-  const step: Step<TInput, TOutput> = {
-    name:   "run",
-    input:  inputSchema,
-    output: outputSchema,
-    run: async (stepCtx) => {
-      // Proxy the legacy WorkflowCtx hooks to the step's collector-backed
-      // implementations. The engine harvests the snapshot after execute
-      // returns; nothing here is a no-op.
-      const workflowCtx: WorkflowCtx<TInput> = {
-        input:          stepCtx.input,
-        run:            stepCtx.run,
-        requestContext: stepCtx.requestContext,
-        invokeChild:    stepCtx.invokeChild,
-        setMetadata:    stepCtx.setMetadata,
-        step:           stepCtx.step,
-        agentEvents:    stepCtx.agentEvents,
-        pause:           stepCtx.pause,
-        sleep:           stepCtx.sleep,
-        waitForEvent:    stepCtx.waitForEvent,
-        processors:      metadata.processors ?? [],
-      };
-      const sandbox = stepCtx.sandbox;
-      if (!sandbox) throw new Error("legacy run-form workflow requires a sandbox in StepContext");
-      return def.run(workflowCtx, sandbox);
-    },
-  };
-  const workflow: Workflow<TInput, TOutput> = {
-    id:     "@run-form",
-    input:  inputSchema,
-    output: outputSchema,
-    steps:  Object.freeze([step]),
-    metadata,
-  };
-  // Brand BEFORE freezing — defineProperty is the only way to set a
-  // non-enumerable key, and frozen objects refuse it.
-  Object.defineProperty(workflow, WORKFLOW_BRAND, { value: true, enumerable: false });
-  return Object.freeze(workflow);
-}
-
 /**
- * Declare a workflow. Two forms; both return a `Workflow` whose
- * `metadata` field carries the server-readable declarations.
- *
- * Run form — wraps the legacy `(ctx, sandbox) => T` body as a single
- * step internally. Lifecycle granularity is workflow-level (one step).
+ * Declare a workflow — the typed step builder. Multiple steps with
+ * explicit input/output schemas, durability + replay at every step
+ * boundary:
  *
- * Step form — the typed builder. Multiple steps with explicit input/
- * output schemas, durability + replay at every step boundary.
+ *   defineWorkflow({ id, input, output }).step(defineStep(...)).build()
  *
- * Both forms produce the same downstream shape: the bundler reads
- * `workflow.metadata.networkPolicy` / `placeholders` / etc.; the server
- * stores the step plan; runner subprocesses execute one step at a time
- * via the StepInvocation seam.
+ * The bundler reads `workflow.metadata.networkPolicy` / `placeholders` /
+ * etc. off the built `Workflow`; the server stores the step plan; runner
+ * subprocesses execute one step at a time via the StepInvocation seam.
  */
-export function defineWorkflow<
-  TOutput = unknown,
-  TInput extends Record<string, unknown> = Record<string, unknown>,
->(
-  def: WorkflowDefinition<TOutput, TInput>,
-): Workflow<TInput, TOutput>;
 export function defineWorkflow<TInput, TOutput>(
   def: StepWorkflowDefinition<TInput, TOutput>,
-): import("../workflow-steps/workflow.js").WorkflowBuilder<TInput, TInput>;
-export function defineWorkflow<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
-  def: WorkflowDefinition<TOutput, TInput> | StepWorkflowDefinition<unknown, unknown>,
-): Workflow<TInput, TOutput> | import("../workflow-steps/workflow.js").WorkflowBuilder<unknown, unknown> {
-  if ("run" in def) return compileRunForm(def, extractMetadata(def));
+): WorkflowBuilder<TInput, TInput> {
+  if ("run" in def) {
+    throw new Error(
+      "defineWorkflow: the legacy run-form (`defineWorkflow({ run(ctx, sandbox) { … } })`) has been removed. " +
+      "Author workflows in step-form — `defineWorkflow({ id, input, output }).step(defineStep(...)).build()` — " +
+      "or run /ac:generate-workflow to scaffold the current shape.",
+    );
+  }
   return createStepWorkflow(def);
 }
 

package/src/utils/bundler.ts

@@ -25,7 +25,7 @@ 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 { SnapshotConfig } from "../types/workflow.js";
-import type { IOSchema, OutputSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "../types/workflow-metadata.js";
+import type { IOSchema, OutputSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources, DriveMergePolicy } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import { isWorkflow } from "../workflow-steps/workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
@@ -101,6 +101,9 @@ export interface BundledWorkflow {
   /** Sandbox resources declared via `defineWorkflow({ resources })` — machine
    *  SKU (`size`) and `provider` (`vercel` | `e2b`). */
   resources?: SandboxResources;
+  /** Run-branch merge policy declared via `defineWorkflow({ mergePolicy })`.
+   *  Absent ⇒ `"auto"` (today's behaviour). */
+  mergePolicy?: DriveMergePolicy;
   workflowPlan: WorkflowPlan;
   /** Compact JSON-Schema-shaped description of the workflow's input
    *  type. Extracted from the workflow's declared `input` zod schema
@@ -173,7 +176,7 @@ async function extractFromBundle<T>(
  * the latter would also accept `defineWorkflowAttacker`. The runtime brand
  * check is the second gate, but the syntactic check should be tight.
  *
- * `defineSandboxEnvironment` is sugar over `defineWorkflow` (see
+ * `defineSandboxEnvironment` is sugar over the step builder (see
  * `src/types/sandbox-environment.ts`) and is explicitly registerable via
  * `agentc register setup.ts --build` to capture a snapshot. The AST gate
  * accepts it for the same reason it accepts `defineWorkflow`: the bundled
@@ -284,6 +287,28 @@ function sha256(text: string): string {
   return createHash("sha256").update(text, "utf8").digest("hex");
 }
 
+/**
+ * The registration-time step plan read off an (already evaluated) workflow
+ * object. Narrative fields (`summary`, `deliverables`) ride along additively;
+ * conditional spreads keep absent fields ABSENT — the plan travels as JSON,
+ * so no `undefined` keys. Exported for tests.
+ */
+export function extractWorkflowPlan(workflow: Workflow<unknown, unknown>): WorkflowPlan {
+  return workflowPlan(workflow.steps.map((step, index) => ({
+    index,
+    name: step.name,
+    ...(step.summary !== undefined ? { summary: step.summary } : {}),
+    ...(step.deliverables?.length
+      ? {
+          deliverables: step.deliverables.map((d) => ({
+            path: d.path,
+            ...(d.description !== undefined ? { description: d.description } : {}),
+          })),
+        }
+      : {}),
+  })));
+}
+
 /** Bundle a workflow from source. */
 export async function bundleWorkflow(
   workflowPath: string,
@@ -312,7 +337,7 @@ export async function bundleWorkflow(
   }
 
   const { metadata } = workflow;
-  const plan: WorkflowPlan = workflowPlan(workflow.steps.map((step, index) => ({ index, name: step.name })));
+  const plan = extractWorkflowPlan(workflow);
   const manifest: WorkflowManifest = {
     definitionBrand: true,
     sourceHash:      sha256(source),
@@ -341,6 +366,7 @@ export async function bundleWorkflow(
     ...(outputSchema             !== undefined ? { outputSchema }                       : {}),
     ...(metadata.snapshots       !== undefined ? { snapshots:    metadata.snapshots }    : {}),
     ...(metadata.resources       !== undefined ? { resources:    metadata.resources }    : {}),
+    ...(metadata.mergePolicy     !== undefined ? { mergePolicy:  metadata.mergePolicy }  : {}),
     ...(metadata.connectors          !== undefined ? { connectors:          metadata.connectors }          : {}),
     ...(metadata.connectorOperation  !== undefined ? { connectorOperation:  metadata.connectorOperation }  : {}),
     ...(metadata.invokePolicy        !== undefined ? { invokePolicy:        metadata.invokePolicy }        : {}),
@@ -356,8 +382,9 @@ export async function bundleWorkflow(
  *
  *  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). */
+ *    - The schema is effectively `unknown` (e.g. the
+ *      `defineSandboxEnvironment` sugar's schemas — no meaningful
+ *      contract to render). */
 function extractIOSchema(
   zodSchema: { _zod?: unknown } | unknown,
 ): IOSchema | undefined {

package/src/utils/errors.ts

@@ -1,4 +1,36 @@
-/** Convert any thrown value to a string message. */
+/** Convert any thrown value to a string message, INCLUDING its `.cause` chain.
+ *
+ *  Many wrapped errors carry the real reason on `.cause` and only a generic
+ *  summary on `.message` — the Temporal SDK's "Failed to start Workflow" is the
+ *  canonical example (its `.cause` is the actual gRPC rejection, e.g. "search
+ *  attribute X is not defined"). Returning `.message` alone swallowed that, so
+ *  failures surfaced as opaque one-liners. Walk the chain and join the messages
+ *  so the root cause is always visible. Cycle-guarded against self-referential
+ *  `cause` links. */
 export function formatError(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
+  if (!(err instanceof Error)) {
+    // Parsed-JSON error payloads (a CLI runtime's `{"error":{"message":…}}`,
+    // a provider body) are plain objects, and `String({...})` is the literal
+    // "[object Object]" — the exact string that reached session transcripts.
+    // Prefer the conventional `.message`; otherwise show the JSON itself.
+    if (typeof err === "object" && err !== null) {
+      const msg = (err as { message?: unknown }).message;
+      if (typeof msg === "string" && msg.length > 0) return msg;
+      try {
+        return JSON.stringify(err) ?? String(err);
+      } catch {
+        return String(err);
+      }
+    }
+    return String(err);
+  }
+  const parts: string[] = [err.message];
+  const seen = new Set<unknown>([err]);
+  let cause: unknown = (err as { cause?: unknown }).cause;
+  while (cause != null && !seen.has(cause)) {
+    seen.add(cause);
+    parts.push(cause instanceof Error ? cause.message : String(cause));
+    cause = cause instanceof Error ? (cause as { cause?: unknown }).cause : undefined;
+  }
+  return parts.join(": ");
 }

package/src/workflow-steps/index.ts

@@ -21,6 +21,7 @@ export type {
 export type {
   Step,
   StepContext,
+  StepDeliverable,
   StepRunResult,
   Workflow,
 } from "./types.js";

package/src/workflow-steps/observability.ts

@@ -56,7 +56,12 @@ export interface SubStepEvent {
  *  empty snapshot (and the wire payload omits the field entirely). */
 export interface StepObservability {
   metadata?: Record<string, unknown>;
-  events?:   AgentLifecycleEvent[];
+  /** Residual events that failed live delivery, each carrying its ORIGINAL
+   *  emit-time `seq`. The server keys its idempotency on that seq — the SAME
+   *  key the live route used — so a live write whose ack was lost collapses
+   *  on redelivery instead of duplicating. Array position is NOT the seq:
+   *  acked events are stripped, so indices shift. */
+  events?:   Array<AgentLifecycleEvent & { seq: number }>;
   subSteps?: SubStepEvent[];
 }
 
@@ -163,11 +168,12 @@ export class StepObservabilityCollector {
 
   readonly agentEvents: AgentEventSink = {
     emit: (event: AgentLifecycleEvent) => {
-      // `seq` is the event's index in `events`, captured BEFORE push so
-      // it matches the index the server-side batch flush uses (its
-      // `.entries()` loop). Same index → same idempotency key on the
-      // server. The live route's `acceptedSeqs` response uses this seq;
-      // we strip those from the snapshot in `snapshot()`.
+      // `seq` is the event's emit-time index in `events`, captured BEFORE
+      // push. It is THE idempotency handle on both delivery paths: the
+      // live POST carries it per event, and `snapshot()` stamps it onto
+      // every residual event so the server's batch backstop builds the
+      // byte-identical key. The live route's `acceptedSeqs` response uses
+      // this seq; we strip acked events in `snapshot()`.
       const seq = this.events.length;
       this.events.push(event);
       if (this.liveEmitter) {
@@ -206,8 +212,13 @@ export class StepObservabilityCollector {
 
     const hasMetadata = Object.keys(this.metadata).length > 0;
     const hasSubSteps = this.subSteps.length > 0;
-    // Filter out ack'd events — the live route already wrote them.
-    const remainingEvents = this.events.filter((_, idx) => !this.ackedSeqs.has(idx));
+    // Filter out ack'd events — the live route already wrote them — and
+    // stamp each survivor with its ORIGINAL emit-time seq. Filtering shifts
+    // array positions, so the seq must travel explicitly for the server's
+    // backstop to reproduce the live path's idempotency key.
+    const remainingEvents = this.events
+      .map((event, seq) => ({ ...event, seq }))
+      .filter(({ seq }) => !this.ackedSeqs.has(seq));
     const hasEvents = remainingEvents.length > 0;
 
     if (!hasMetadata && !hasEvents && !hasSubSteps) return undefined;

package/src/workflow-steps/runner.ts

@@ -26,7 +26,7 @@ import { z } from "zod";
 import type { Workflow, StepContext, StepRunResult } from "./types.js";
 import type { RequestContext } from "../request-context/request-context.js";
 import type { SandboxProvider } from "../types/sandbox.js";
-import type { WorkflowRun, WorkflowCtx } from "../types/workflow.js";
+import type { WorkflowRun, InvokeChild } from "../types/execution-context.js";
 import { StepObservabilityCollector, type StepObservability } from "./observability.js";
 import type { LiveAgentEventEmitter } from "./run-callback.js";
 import { scopedMemoize } from "../pause/checkpoint.js";
@@ -89,7 +89,7 @@ export interface RunWorkflowStepsOpts<TInput, TOutput> {
   /** Fire before a step runs (after cache check / before input validation). */
   onStepStarted?(stepIndex: number, stepName: string): void | Promise<void>;
   /** Child workflow invocation implementation. Defaults to a clear unsupported error. */
-  invokeChild?: WorkflowCtx["invokeChild"];
+  invokeChild?: InvokeChild;
   /** Optional live-stream emitter for agent lifecycle events. The runner
    *  passes a fetch-based emitter wired to the per-run callback token so
    *  the dashboard sees events as the agent loop produces them; tests
@@ -111,7 +111,7 @@ export interface RunWorkflowSingleStepOpts {
   requestContext: RequestContext;
   sandbox?:       SandboxProvider;
   abortSignal?:   AbortSignal;
-  invokeChild?:   WorkflowCtx["invokeChild"];
+  invokeChild?:   InvokeChild;
   /** Optional live-stream emitter — see `RunWorkflowStepsOpts.liveAgentEventEmitter`. */
   liveAgentEventEmitter?: LiveAgentEventEmitter;
 }
@@ -189,7 +189,7 @@ export async function runWorkflowSteps<TInput, TOutput>(
 ): Promise<RunWorkflowStepsResult<TOutput>> {
   const { workflow, run, requestContext } = opts;
   const abortSignal = opts.abortSignal ?? new AbortController().signal;
-  const invokeChild: WorkflowCtx["invokeChild"] = opts.invokeChild ?? (() => {
+  const invokeChild: InvokeChild = opts.invokeChild ?? (() => {
     throw new Error("StepContext.invokeChild is not configured for this workflow engine");
   });
 

package/src/workflow-steps/step.ts

@@ -7,32 +7,80 @@
  *   - `output`  Zod schema; validated against `run`'s return value
  *   - `run`     step body
  *
+ * Optional narrative fields (rendered on the dashboard workflow graph):
+ *   - `summary`       one plain sentence of what the step actually does
+ *   - `deliverables`  files the step promises to produce
+ *
  * Validation is required (not optional) because the durability story rides
  * on every step boundary being a recordable, replayable JSON value. A step
  * without a schema is invisible to the engine's persistence layer.
  *
+ * Narrative caps are enforced HERE, at construction — the bundler evaluates
+ * the module at registration, so this is the "length-capped at registration"
+ * point and the error names the step in the author's own environment. The
+ * server's manifest zod re-checks the same caps (untrusted input).
+ *
  * Type inference flows: `defineStep` infers TInput/TOutput from the schemas
  * so `run(ctx)` is fully typed via `ctx.input` at the call site.
  */
 
 import type { z } from "zod";
-import type { Step, StepContext } from "./types.js";
+import type { Step, StepContext, StepDeliverable } from "./types.js";
 
 export interface DefineStepOpts<TInput, TOutput> {
   name:   string;
   input:  z.ZodType<TInput>;
   output: z.ZodType<TOutput>;
   run(ctx: StepContext<TInput>): TOutput | Promise<TOutput>;
+  /** One plain sentence of what the step actually does. 1-200 chars, no
+   *  control characters (so no newlines). */
+  summary?: string;
+  /** Files the step promises to produce. At most 8. */
+  deliverables?: StepDeliverable[];
 }
 
+// C0 controls + DEL — narrative text is one-line prose, never structural.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+
 export function defineStep<TInput, TOutput>(
   opts: DefineStepOpts<TInput, TOutput>,
 ): Step<TInput, TOutput> {
   if (!opts.name) throw new Error("defineStep: 'name' is required");
+  if (opts.summary !== undefined) {
+    if (opts.summary.length === 0 || opts.summary.length > 200 || CONTROL_CHARS.test(opts.summary)) {
+      throw new Error(
+        `defineStep("${opts.name}"): 'summary' must be one plain sentence, 1-200 characters, no control characters`,
+      );
+    }
+  }
+  if (opts.deliverables !== undefined) {
+    if (opts.deliverables.length > 8) {
+      throw new Error(`defineStep("${opts.name}"): at most 8 deliverables`);
+    }
+    for (const d of opts.deliverables) {
+      if (!d.path || d.path.length > 200 || CONTROL_CHARS.test(d.path)) {
+        throw new Error(
+          `defineStep("${opts.name}"): each deliverable needs a 'path' of 1-200 characters, no control characters`,
+        );
+      }
+      if (d.description !== undefined && (d.description.length === 0 || d.description.length > 200 || CONTROL_CHARS.test(d.description))) {
+        throw new Error(
+          `defineStep("${opts.name}"): deliverable descriptions must be 1-200 characters, no control characters`,
+        );
+      }
+    }
+  }
+  // Conditional spreads keep absent fields ABSENT (no `undefined` keys —
+  // matters for the canonical-hash discipline used elsewhere).
   return {
     name:   opts.name,
     input:  opts.input,
     output: opts.output,
     run:    opts.run,
+    ...(opts.summary !== undefined ? { summary: opts.summary } : {}),
+    ...(opts.deliverables !== undefined
+      ? { deliverables: Object.freeze(opts.deliverables.map((d) => ({ ...d }))) }
+      : {}),
   };
 }