@agent-compose/sdk 0.2.3 → 0.2.4

package/src/workflow-steps/runner.ts

@@ -0,0 +1,244 @@
+/**
+ * `runWorkflowSteps` — in-process step executor for a `Workflow`.
+ *
+ * Walks the step chain sequentially:
+ *   1. Validate workflow input against `workflow.input`.
+ *   2. For each step:
+ *      a. Optionally check `getCachedOutput(stepIndex, step.name)` — if a
+ *         previous run completed this step, skip and reuse its output.
+ *         (Phase 1b uses this for crash recovery.)
+ *      b. Validate current input against `step.input`.
+ *      c. Call `step.run({ input, ... })`.
+ *      d. Validate return value against `step.output`.
+ *      e. Call `onStepCompleted(stepIndex, step.name, output, durationMs)`.
+ *      f. Output becomes the next step's input.
+ *   3. Validate final output against `workflow.output`.
+ *
+ * Errors during any step bubble through `onStepFailed` and re-throw so the
+ * caller can decide whether to mark the run failed.
+ *
+ * The cache + completion hooks are injection points — a sandbox engine
+ * adapter (Phase 1c) wires them to `workflow_step_runs` rows. The default
+ * is an in-process map for tests.
+ */
+
+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 { StepObservabilityCollector, type StepObservability } from "./observability.js";
+
+export class StepValidationError extends Error {
+  readonly kind = "step-validation" as const;
+  constructor(
+    readonly stepName: string,
+    readonly side: "input" | "output",
+    cause: z.ZodError,
+  ) {
+    super(`Step "${stepName}" ${side} failed schema validation: ${cause.message}`);
+    this.name = "StepValidationError";
+    this.cause = cause;
+  }
+}
+
+export class WorkflowInputValidationError extends Error {
+  readonly kind = "workflow-input-validation" as const;
+  constructor(readonly workflowId: string, cause: z.ZodError) {
+    super(`Workflow "${workflowId}" input failed schema validation: ${cause.message}`);
+    this.name = "WorkflowInputValidationError";
+    this.cause = cause;
+  }
+}
+
+export class WorkflowOutputValidationError extends Error {
+  readonly kind = "workflow-output-validation" as const;
+  constructor(readonly workflowId: string, cause: z.ZodError) {
+    super(`Workflow "${workflowId}" output failed schema validation: ${cause.message}`);
+    this.name = "WorkflowOutputValidationError";
+    this.cause = cause;
+  }
+}
+
+export interface RunWorkflowStepsOpts<TInput, TOutput> {
+  workflow:        Workflow<TInput, TOutput>;
+  input:           TInput;
+  run:             WorkflowRun;
+  requestContext:  RequestContext;
+  sandbox?:        SandboxProvider;
+  abortSignal?:    AbortSignal;
+  /**
+   * Crash-recovery hook. Called before a step executes. Return the cached
+   * output to skip execution; return undefined to run the step.
+   *
+   * Phase 1b implementations will look up `workflow_step_runs` rows for
+   * (runId, stepIndex, stepName) and return completed step outputs here.
+   * Default: always undefined (no caching).
+   */
+  getCachedOutput?(stepIndex: number, stepName: string): unknown | undefined | Promise<unknown | undefined>;
+  /** Fire after a step's `execute` and output validation succeed. */
+  onStepCompleted?(stepIndex: number, stepName: string, output: unknown, durationMs: number): void | Promise<void>;
+  /** Fire when a step throws or fails validation. The error is re-thrown after this returns. */
+  onStepFailed?(stepIndex: number, stepName: string, error: Error, durationMs: number): void | Promise<void>;
+  /** 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"];
+}
+
+export interface RunWorkflowStepsResult<TOutput> {
+  output: TOutput;
+  /** Per-step results in order — useful for tests and lifecycle event emission. */
+  steps: ReadonlyArray<{ name: string } & StepRunResult>;
+}
+
+export interface RunWorkflowSingleStepOpts {
+  workflow:       Workflow<unknown, unknown>;
+  stepIndex:      number;
+  input:          unknown;
+  run:            WorkflowRun;
+  requestContext: RequestContext;
+  sandbox?:       SandboxProvider;
+  abortSignal?:   AbortSignal;
+  invokeChild?:   WorkflowCtx["invokeChild"];
+}
+
+/** Result of one step run — output plus whatever the step's observability
+ *  hooks recorded. `observability` is undefined when nothing was buffered,
+ *  so callers can drop it from the wire payload entirely. */
+export interface RunWorkflowSingleStepResult {
+  output:         unknown;
+  observability?: StepObservability;
+}
+
+export async function runWorkflowSingleStep(opts: RunWorkflowSingleStepOpts): Promise<RunWorkflowSingleStepResult> {
+  const step = opts.workflow.steps[opts.stepIndex];
+  if (!step) throw new Error(`Step index ${opts.stepIndex} not found in workflow "${opts.workflow.id}"`);
+  const parsedInput = step.input.safeParse(opts.input);
+  if (!parsedInput.success) throw new StepValidationError(step.name, "input", parsedInput.error);
+  const collector = new StepObservabilityCollector();
+  const stepCtx: StepContext<unknown> = {
+    input: parsedInput.data,
+    requestContext: opts.requestContext,
+    run: opts.run,
+    ...(opts.sandbox ? { sandbox: opts.sandbox } : {}),
+    stepName: step.name,
+    abortSignal: opts.abortSignal ?? new AbortController().signal,
+    invokeChild: opts.invokeChild ?? (() => { throw new Error("StepContext.invokeChild is not configured for this workflow engine"); }),
+    setMetadata: collector.setMetadata,
+    step:        collector.step,
+    agentEvents: collector.agentEvents,
+  };
+  const output = await step.run(stepCtx);
+  const parsedOutput = step.output.safeParse(output);
+  if (!parsedOutput.success) throw new StepValidationError(step.name, "output", parsedOutput.error);
+  const observability = collector.snapshot();
+  return observability === undefined
+    ? { output: parsedOutput.data }
+    : { output: parsedOutput.data, observability };
+}
+
+export async function runWorkflowSteps<TInput, TOutput>(
+  opts: RunWorkflowStepsOpts<TInput, TOutput>,
+): Promise<RunWorkflowStepsResult<TOutput>> {
+  const { workflow, run, requestContext } = opts;
+  const abortSignal = opts.abortSignal ?? new AbortController().signal;
+  const invokeChild: WorkflowCtx["invokeChild"] = opts.invokeChild ?? (() => {
+    throw new Error("StepContext.invokeChild is not configured for this workflow engine");
+  });
+
+  // Validate workflow input up front. If the caller supplied junk, none of
+  // the steps run — cleaner than letting step 1 fail with its own message.
+  const parsedInput = workflow.input.safeParse(opts.input);
+  if (!parsedInput.success) {
+    throw new WorkflowInputValidationError(workflow.id, parsedInput.error);
+  }
+  let current: unknown = parsedInput.data;
+
+  const stepResults: Array<{ name: string } & StepRunResult> = [];
+
+  for (let i = 0; i < workflow.steps.length; i++) {
+    const step = workflow.steps[i];
+    const cached = opts.getCachedOutput ? await opts.getCachedOutput(i, step.name) : undefined;
+    if (cached !== undefined) {
+      // Re-validate cached output so a corrupted row can't poison the chain.
+      const parsedCached = step.output.safeParse(cached);
+      if (!parsedCached.success) {
+        throw new StepValidationError(step.name, "output", parsedCached.error);
+      }
+      current = parsedCached.data;
+      stepResults.push({ name: step.name, status: "completed", output: parsedCached.data, durationMs: 0 });
+      continue;
+    }
+
+    await opts.onStepStarted?.(i, step.name);
+    const parsedStepInput = step.input.safeParse(current);
+    if (!parsedStepInput.success) {
+      const err = new StepValidationError(step.name, "input", parsedStepInput.error);
+      await opts.onStepFailed?.(i, step.name, err, 0);
+      throw err;
+    }
+
+    const collector = new StepObservabilityCollector();
+    const stepCtx: StepContext<unknown> = {
+      input:          parsedStepInput.data,
+      requestContext,
+      run,
+      ...(opts.sandbox ? { sandbox: opts.sandbox } : {}),
+      stepName:       step.name,
+      abortSignal,
+      invokeChild,
+      setMetadata:    collector.setMetadata,
+      step:           collector.step,
+      agentEvents:    collector.agentEvents,
+    };
+
+    const startedAt = Date.now();
+    let output: unknown;
+    try {
+      output = await step.run(stepCtx);
+    } catch (err) {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      const durationMs = Date.now() - startedAt;
+      const observability = collector.snapshot();
+      stepResults.push({
+        name: step.name, status: "failed", error: wrapped.message, durationMs,
+        ...(observability ? { observability } : {}),
+      });
+      await opts.onStepFailed?.(i, step.name, wrapped, durationMs);
+      throw wrapped;
+    }
+
+    const parsedOutput = step.output.safeParse(output);
+    if (!parsedOutput.success) {
+      const err = new StepValidationError(step.name, "output", parsedOutput.error);
+      const durationMs = Date.now() - startedAt;
+      const observability = collector.snapshot();
+      stepResults.push({
+        name: step.name, status: "failed", error: err.message, durationMs,
+        ...(observability ? { observability } : {}),
+      });
+      await opts.onStepFailed?.(i, step.name, err, durationMs);
+      throw err;
+    }
+
+    const durationMs = Date.now() - startedAt;
+    current = parsedOutput.data;
+    const observability = collector.snapshot();
+    stepResults.push({
+      name: step.name, status: "completed", output: parsedOutput.data, durationMs,
+      ...(observability ? { observability } : {}),
+    });
+    await opts.onStepCompleted?.(i, step.name, parsedOutput.data, durationMs);
+  }
+
+  // Validate workflow output against the declared `output` schema. The
+  // chain already ensured the final step's `output` matched at construction
+  // time, but parsing again here defends against corrupted cached outputs
+  // that bypassed step validation.
+  const parsedFinal = workflow.output.safeParse(current);
+  if (!parsedFinal.success) {
+    throw new WorkflowOutputValidationError(workflow.id, parsedFinal.error);
+  }
+  return { output: parsedFinal.data as TOutput, steps: stepResults };
+}

package/src/workflow-steps/step.ts

@@ -0,0 +1,38 @@
+/**
+ * `defineStep` — typed factory for one workflow step.
+ *
+ * Required:
+ *   - `name`    stable identifier (also the step row key)
+ *   - `input`   Zod schema; validated before `run` executes
+ *   - `output`  Zod schema; validated against `run`'s return value
+ *   - `run`     step body
+ *
+ * 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.
+ *
+ * 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";
+
+export interface DefineStepOpts<TInput, TOutput> {
+  name:   string;
+  input:  z.ZodType<TInput>;
+  output: z.ZodType<TOutput>;
+  run(ctx: StepContext<TInput>): TOutput | Promise<TOutput>;
+}
+
+export function defineStep<TInput, TOutput>(
+  opts: DefineStepOpts<TInput, TOutput>,
+): Step<TInput, TOutput> {
+  if (!opts.name) throw new Error("defineStep: 'name' is required");
+  return {
+    name:   opts.name,
+    input:  opts.input,
+    output: opts.output,
+    run:    opts.run,
+  };
+}

package/src/workflow-steps/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared types for the declarative workflow shape.
+ *
+ * Workflows-as-data — every workflow is a list of typed steps with explicit
+ * input/output Zod schemas. Mastra's shape, adapted for our runtime.
+ *
+ * Why: durable suspend/resume requires step boundaries to be addressable as
+ * data, not opaque async-function bodies. Each step's input + output is
+ * serialisable JSON so engine adapters (in-process, sandbox, future
+ * Inngest/Temporal) can record completion and replay from the last
+ * completed step.
+ */
+
+import type { z } from "zod";
+import type { BaseExecutionContext } from "../types/execution-context.js";
+import type { AgentEventSink } from "../types/workflow.js";
+import type { WorkflowMetadata } from "../types/workflow-metadata.js";
+
+/**
+ * Per-step execution context. Threaded into every step's `execute(...)` so
+ * the step can read tenant identity and run identity, log progress, and
+ * invoke sandbox commands.
+ *
+ * Sandbox is optional because in-process tests run steps without a sandbox.
+ */
+export interface StepContext<TInput = unknown> extends BaseExecutionContext {
+  /** Validated step input — already parsed against the step's `input` schema. */
+  input: TInput;
+  /** Step name — useful for logging. */
+  stepName: string;
+  /** AbortSignal that fires on workflow cancellation. */
+  abortSignal: AbortSignal;
+  /**
+   * Merge key-value metadata onto the run record. Buffered during the
+   * step and flushed when the step completes; the durable engine writes
+   * it via the same `mergeRunMetadata` path the legacy runner used, so
+   * the dashboard sees the same shape. Later keys win.
+   */
+  setMetadata(data: Record<string, unknown>): Promise<void>;
+  /**
+   * Wrap a named sub-step for observability. Emits
+   * `workflow_substep_started` / `workflow_substep_completed` /
+   * `workflow_substep_failed` lifecycle events on the run timeline with
+   * the measured `durationMs`. Use for long sub-phases inside one step
+   * (setup, external API call, submit).
+   *
+   * The block runs even if observability flushing fails — instrumentation
+   * never breaks the workflow.
+   */
+  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Sink for `agent({ events: ctx.agentEvents })`. Each emitted
+   * `AgentLifecycleEvent` is buffered and flushed at step end, then
+   * fanned out to the run's SSE stream. Mid-step the events are not
+   * yet visible to consumers — that's a deliberate tradeoff for the
+   * step-mode, /internal/*-free runner.
+   */
+  agentEvents: AgentEventSink;
+}
+
+/**
+ * Step definition — a single typed unit of work in a workflow chain.
+ *
+ * Both `input` and `output` are required: the workflow shape's value
+ * comes from every step boundary being recordable. Optional schemas
+ * would defeat the durability story.
+ *
+ * `run` may be sync or async; the engine awaits it uniformly.
+ */
+export interface Step<TInput, TOutput> {
+  /** Stable identifier — used as the step row key and for logs/metrics. */
+  readonly name: string;
+  /** Zod schema validated against the step's input before `run`. */
+  readonly input: z.ZodType<TInput>;
+  /** Zod schema validated against `run`'s return value. */
+  readonly output: z.ZodType<TOutput>;
+  /** Step body. Receives a `StepContext<TInput>` and returns the typed output. */
+  run(ctx: StepContext<TInput>): TOutput | Promise<TOutput>;
+}
+
+/**
+ * The result of running one step. Engine adapters persist these into the
+ * `workflow_step_runs` table (Phase 1b) so subsequent runs can skip
+ * completed steps. `observability` carries the snapshot of
+ * `ctx.setMetadata` / `ctx.step` / `ctx.agentEvents` recorded during
+ * the step; undefined when no hooks were used.
+ */
+export type StepRunResult<TOutput = unknown> =
+  | { status: "completed"; output: TOutput; durationMs: number; observability?: import("./observability.js").StepObservability }
+  | { status: "failed";    error: string;   durationMs: number; observability?: import("./observability.js").StepObservability };
+
+/**
+ * Workflow — a list of typed steps plus the workflow's input/output
+ * schemas plus its server-side metadata bag. Returned by `defineWorkflow(...)`
+ * (run form) and `defineWorkflow(...).step(...)...build()` (step form).
+ * Engine adapters consume this shape.
+ *
+ * `input` validates the workflow input before the first step runs.
+ * `output` validates the final step's output before the workflow
+ * completes successfully.
+ *
+ * `metadata` carries server-readable declarations — network policy,
+ * brokered-secret placeholders, snapshot reference/capture defaults,
+ * workflow-level processor chain. The bundler reads these at registration
+ * time. Always present, possibly empty.
+ *
+ * Historically named `CompiledWorkflow` back when an uncompiled form
+ * existed (a bare `WorkflowFn` was its own engine input). After the
+ * legacy delete in #55 every workflow goes through this shape, so the
+ * "Compiled" prefix carried no information — it's just `Workflow` now.
+ */
+export interface Workflow<TInput, TOutput> {
+  /** Stable workflow identifier. */
+  readonly id: string;
+  /** Validates the initial workflow input. */
+  readonly input: z.ZodType<TInput>;
+  /** Validates the final step's output. */
+  readonly output: z.ZodType<TOutput>;
+  /** Sequential list of steps to execute. Type chain proven at compile time. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly steps: ReadonlyArray<Step<any, any>>;
+  /** Server-readable declarations: network policy, placeholders, snapshot
+   *  defaults, processors. Always set; empty object when nothing declared. */
+  readonly metadata: WorkflowMetadata;
+}
+
+/**
+ * Discriminator brand stamped on every `Workflow` so `isWorkflow` can
+ * distinguish a real workflow from an arbitrary default export at
+ * registration / dispatch time. Workflow authors never see this —
+ * `defineWorkflow` and `defineWorkflow(...).step(...).build()` set it
+ * internally.
+ */
+export const WORKFLOW_BRAND = Symbol.for("@agent-compose/sdk.Workflow");

package/src/workflow-steps/workflow.ts

@@ -0,0 +1,95 @@
+/**
+ * `createStepWorkflow` — internal typed builder for a step-based workflow.
+ *
+ *   const wf = defineWorkflow({
+ *     id:     "my-workflow",
+ *     input:  z.object({ url: z.string().url() }),
+ *     output: z.object({ pageTitle: z.string() }),
+ *   })
+ *     .step(fetchStep)
+ *     .step(parseStep)
+ *     .build();
+ *
+ * The chain enforces that each step's input matches the previous step's
+ * output at compile time. `.build()` returns a `Workflow` and verifies
+ * at construction time that the workflow's declared `output` schema
+ * matches the final step's `output` schema.
+ *
+ * Workflows-as-data — the result is consumable by any engine adapter
+ * (in-process today; sandbox + Inngest/Temporal in future PRs).
+ */
+
+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 { SandboxNetworkPolicy } from "../sandbox.js";
+import type { Processor } from "../processors/processor.js";
+
+export interface WorkflowBuilder<TInput, TCurrent> {
+  /** Append a step whose input matches the current builder output. */
+  step<TOutput>(step: Step<TCurrent, TOutput>): WorkflowBuilder<TInput, TOutput>;
+  /**
+   * Freeze the chain into a `Workflow`. Throws when no steps have been
+   * added or when the final step's `output` schema is not the same Zod
+   * schema instance as the workflow's declared `output` schema.
+   *
+   * The schema-identity check catches the "I edited one of two schemas"
+   * footgun that's easy to introduce when output types drift.
+   */
+  build(): Workflow<TInput, TCurrent>;
+}
+
+export interface StepWorkflowDefinition<TInput, TOutput> {
+  id:     string;
+  input:  z.ZodType<TInput>;
+  output: z.ZodType<TOutput>;
+  networkPolicy?: SandboxNetworkPolicy;
+  placeholders?:  Record<string, string>;
+  snapshot?:      string;
+  saveSnapshot?:  boolean;
+  processors?:    readonly Processor[];
+}
+
+export function createStepWorkflow<TInput, TOutput>(
+  opts: StepWorkflowDefinition<TInput, TOutput>,
+): WorkflowBuilder<TInput, TInput> {
+  if (!opts.id) throw new Error("defineWorkflow: 'id' is required for step-based workflows");
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const build = <TCurrent,>(steps: ReadonlyArray<Step<any, any>>): WorkflowBuilder<TInput, TCurrent> => ({
+    step<TNext>(step: Step<TCurrent, TNext>): WorkflowBuilder<TInput, TNext> {
+      return build<TNext>([...steps, step]);
+    },
+    build(): Workflow<TInput, TCurrent> {
+      if (steps.length === 0) {
+        throw new Error(`defineWorkflow("${opts.id}").build: no steps registered — add at least one with .step(step)`);
+      }
+      const finalStep = steps[steps.length - 1];
+      if (finalStep.output !== opts.output as unknown) {
+        throw new Error(
+          `defineWorkflow("${opts.id}").build: final step "${finalStep.name}" output schema is not the same Zod schema instance as the workflow's declared output schema. ` +
+          `Pass the same schema reference to both the final step and defineWorkflow.`,
+        );
+      }
+      const workflow: Workflow<TInput, TCurrent> = {
+        id:     opts.id,
+        input:  opts.input,
+        output: opts.output as unknown as z.ZodType<TCurrent>,
+        steps:  Object.freeze([...steps]),
+        metadata: extractMetadata(opts),
+      };
+      // 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);
+    },
+  });
+
+  return build<TInput>([]);
+}
+
+/** Type guard — true when `value` is a `Workflow`. */
+export function isWorkflow(value: unknown): value is Workflow<unknown, unknown> {
+  return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[WORKFLOW_BRAND] === true;
+}

package/src/workflows/engine.ts

@@ -1,20 +1,23 @@
 /**
- * Workflow engine — runs a workflow function with a minimal ctx.
+ * Workflow engine — drives a `Workflow`'s steps.
  *
- * Post de-broker there is no agent-spawning primitive here. Workflows that
- * want to embed an LLM agent call `runAgent(opts)` directly from
- * `@agent-compose/sdk`. Workflows that want to invoke OTHER workflows use
- * `AgentComposeClient.invoke[AndWait](...)`. The engine's only job now is:
+ * Single execution entry point: `runWorkflow`. Every workflow has the same
+ * shape (defineWorkflow always returns a `Workflow`), so there's one
+ * runner.
  *
- *   - build the `ctx` the workflow function receives
- *   - funnel `onStepStart / onStepComplete / onStepFail` hooks
- *   - classify errors into `WorkflowError` vs `EngineError` for the runner
- *     harness to emit on /fail
+ * Errors classified into `WorkflowError` (user code threw) vs `EngineError`
+ * (platform problem) for the runner harness to surface upstream.
  */
 
-import type { WorkflowHooks, WorkflowCtx, WorkflowFn } from "../types/workflow.js";
+import type { WorkflowHooks, WorkflowCtx } from "../types/workflow.js";
 import { makeLocalSandboxProvider } from "../sandbox.js";
 import { formatError } from "../utils/errors.js";
+import { RequestContext } from "../request-context/request-context.js";
+import type { Workflow } from "../workflow-steps/types.js";
+import {
+  runWorkflowSteps,
+  type RunWorkflowStepsOpts,
+} from "../workflow-steps/runner.js";
 
 // ── Error classification ─────────────────────────────────────────────────────
 
@@ -70,41 +73,67 @@ export interface WorkflowResult<T = unknown> {
   response: T | null;
 }
 
-export async function runWorkflow<T = unknown>(
-  wf: WorkflowFn<T>,
-  ctx: Pick<WorkflowCtx, "run" | "input">,
-  opts?: { hooks?: WorkflowHooks; setMetadata?: (data: Record<string, unknown>) => Promise<void> },
-): Promise<WorkflowResult<T>> {
+function defaultRequestContext(runId: string, workflowId = ""): RequestContext {
+  return RequestContext.fromReserved({
+    teamId:       "",
+    runId,
+    workflowId,
+    factoryId:    null,
+    apiKeyScopes: [],
+    parentRunId:  null,
+  });
+}
+
+export interface RunWorkflowOptions {
+  hooks?:           WorkflowHooks;
+  requestContext?:  RequestContext;
+  getCachedOutput?: RunWorkflowStepsOpts<unknown, unknown>["getCachedOutput"];
+  onStepStarted?:   RunWorkflowStepsOpts<unknown, unknown>["onStepStarted"];
+  onStepCompleted?: RunWorkflowStepsOpts<unknown, unknown>["onStepCompleted"];
+  onStepFailed?:    RunWorkflowStepsOpts<unknown, unknown>["onStepFailed"];
+  /** Provider-specific child workflow invocation. Temporal/Inngest providers
+   *  inject their native child-workflow primitive; the LocalProvider injects
+   *  the public Agent Compose API client. */
+  invokeChild?:     WorkflowCtx["invokeChild"];
+}
+
+export async function runWorkflow<TInput, TOutput>(
+  wf: Workflow<TInput, TOutput>,
+  ctx: { run: { id: string }; input?: TInput },
+  opts?: RunWorkflowOptions,
+): Promise<WorkflowResult<TOutput>> {
   const hooks = opts?.hooks ?? {};
-  const setMetadata = opts?.setMetadata ?? (async () => {});
-  // Single SandboxProvider for the whole run — handed to the workflow as
-  // its second positional arg. Stateless wrapper over child_process.spawn
-  // + fs.writeFile, so reuse is purely a matter of shape consistency.
+  const requestContext = opts?.requestContext ?? defaultRequestContext(ctx.run.id, wf.id);
   const sandbox = makeLocalSandboxProvider();
+  const invokeChild = opts?.invokeChild ?? (() => {
+    throw new Error("StepContext.invokeChild is not configured for this workflow engine");
+  });
 
-  let workflowErr: unknown;
-  let wfOutput: unknown;
   try {
-    wfOutput = await wf(
-      {
-        ...ctx,
-        setMetadata,
-        step: async <S>(name: string, fn: () => Promise<S>): Promise<S> => {
-          const startedAt = Date.now();
-          hooks.onStepStart?.(name);
-          try   { const r = await fn(); hooks.onStepComplete?.(name, Date.now() - startedAt); return r; }
-          catch (err) { hooks.onStepFail?.(name, Date.now() - startedAt, formatError(err)); throw err; }
-        },
-      },
+    const result = await runWorkflowSteps<TInput, TOutput>({
+      workflow:       wf,
+      input:          (ctx.input as TInput),
+      run:            ctx.run,
+      requestContext,
       sandbox,
-    );
+      invokeChild,
+      ...(opts?.getCachedOutput ? { getCachedOutput: opts.getCachedOutput } : {}),
+      onStepStarted: async (idx, name) => {
+        hooks.onStepStart?.(name);
+        await opts?.onStepStarted?.(idx, name);
+      },
+      onStepCompleted: async (idx, name, output, durationMs) => {
+        hooks.onStepComplete?.(name, durationMs);
+        await opts?.onStepCompleted?.(idx, name, output, durationMs);
+      },
+      onStepFailed: async (idx, name, err, durationMs) => {
+        hooks.onStepFail?.(name, durationMs, formatError(err));
+        await opts?.onStepFailed?.(idx, name, err, durationMs);
+      },
+    });
+    return { response: (result.output ?? null) as TOutput | null };
   } catch (err) {
-    workflowErr = err;
-  }
-
-  if (workflowErr !== undefined) {
-    if (workflowErr instanceof WorkflowError) throw workflowErr;
-    throw new WorkflowError(formatError(workflowErr), { cause: workflowErr });
+    if (err instanceof WorkflowError) throw err;
+    throw new WorkflowError(formatError(err), { cause: err });
   }
-  return { response: (wfOutput ?? null) as T | null };
 }

package/src/workflows/invoke-child.ts

@@ -0,0 +1,29 @@
+import { AgentComposeClient } from "../client.js";
+import type { WorkflowCtx } from "../types/workflow.js";
+
+/**
+ * Build the public-API child workflow invoker used by legacy and sandboxed
+ * workflow execution. Provider-backed engines may inject a different
+ * implementation (Temporal child workflow, Inngest invoke, etc.).
+ */
+export function buildInvokeChild(
+  runId: string,
+  opts: { fallbackBaseUrl?: string; defaultFactorySlug?: string } = {},
+): WorkflowCtx["invokeChild"] {
+  let childClient: AgentComposeClient | null = null;
+  const getChildClient = (): AgentComposeClient => {
+    if (childClient) return childClient;
+    const baseUrl = process.env.AGENT_COMPOSE_URL ?? opts.fallbackBaseUrl;
+    const apiKey = process.env.AGENT_COMPOSE_API_KEY;
+    if (!baseUrl || !apiKey) {
+      throw new Error("ctx.invokeChild requires AGENT_COMPOSE_URL and AGENT_COMPOSE_API_KEY");
+    }
+    childClient = new AgentComposeClient(baseUrl, apiKey);
+    return childClient;
+  };
+  return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {
+    ...childOpts,
+    parentRunId: runId,
+    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default",
+  });
+}