@agent-compose/sdk 0.2.2 → 0.2.4

package/dist/types/workflow.d.ts

@@ -6,29 +6,36 @@
  *   - `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 `runAgent({ sandbox, ... })`
+ *     (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.
  *
- * LLM agent loops live in `runAgent(opts)` (sdk/src/agent/run-agent.ts).
+ * LLM agent loops live in `agent(opts)` (sdk/src/agent/run-agent.ts).
  * Invoking other workflows uses `AgentComposeClient.invoke[AndWait](...)`.
  */
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { SandboxProvider } from "./sandbox.js";
-/** The identity of this workflow run. */
-export interface WorkflowRun {
-    id: string;
+import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
+import type { Processor } from "../processors/processor.js";
+import type { StepWorkflowDefinition } from "../workflow-steps/workflow.js";
+import type { Workflow } from "../workflow-steps/types.js";
+import type { BaseExecutionContext } from "./execution-context.js";
+export type { WorkflowRun, InvokeChild, BaseExecutionContext } from "./execution-context.js";
+export type { WorkflowMetadata } from "./workflow-metadata.js";
+export interface AgentEventSink {
+    emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
-/** Turn/iteration budget for `runAgent(opts)`. Re-exported here so authors
+import type { WorkflowMemoryConfig } from "./workflow-metadata.js";
+export type { WorkflowMemoryConfig };
+/** 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 {
     turnsPerIteration: number;
     maxIterations: number;
 }
 /** Context passed to a workflow function — facts + observability for this run. */
-export interface WorkflowCtx {
-    run: WorkflowRun;
-    input?: Record<string, unknown>;
+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>;
     /**
@@ -37,9 +44,19 @@ export interface WorkflowCtx {
      * visible on the run's timeline (setup, external API calls, submit).
      */
     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) => T`. */
-export type WorkflowFn<T = unknown> = (ctx: WorkflowCtx, sandbox: SandboxProvider) => Promise<T>;
+/** 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
@@ -49,8 +66,8 @@ export type WorkflowFn<T = unknown> = (ctx: WorkflowCtx, sandbox: SandboxProvide
  * Without defineWorkflow, a plain `export default async (ctx) => {...}` still
  * works — the workflow just runs with secrets passed directly in env.
  */
-export interface WorkflowDefinition<T = unknown> {
-    run: WorkflowFn<T>;
+export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>> {
+    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
@@ -82,6 +99,13 @@ export interface WorkflowDefinition<T = unknown> {
      * }
      */
     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
@@ -96,16 +120,32 @@ export interface WorkflowDefinition<T = unknown> {
      * }
      */
     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. */
+    memory?: WorkflowMemoryConfig;
 }
 /**
- * Attach server-side metadata to a workflow function.
- * The returned function is a valid WorkflowFn with metadata fields attached
- * for the bundler / registration layer to read.
+ * 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).
+ *
+ * Step form — the typed builder. Multiple steps with explicit input/
+ * output schemas, durability + replay at every step boundary.
+ *
+ * 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.
  */
-export declare function defineWorkflow<T = unknown>(def: WorkflowDefinition<T>): WorkflowFn<T> & Pick<WorkflowDefinition, "networkPolicy" | "placeholders" | "snapshot" | "saveSnapshot">;
+export declare function defineWorkflow<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(def: WorkflowDefinition<TOutput, TInput>): Workflow<TInput, TOutput>;
+export declare function defineWorkflow<TInput, TOutput>(def: StepWorkflowDefinition<TInput, TOutput>): import("../workflow-steps/workflow.js").WorkflowBuilder<TInput, TInput>;
 /** Observability-only lifecycle hooks — passed to the workflow engine, not workflow authors. */
 export interface WorkflowHooks {
     onStepStart?: (step: string) => void;
     onStepComplete?: (step: string, durationMs: number) => void;
     onStepFail?: (step: string, durationMs: number, reason: string) => void;
+    onAgentLifecycleEvent?: (event: AgentLifecycleEvent) => void;
 }

package/dist/utils/bundler.d.ts

@@ -4,13 +4,51 @@
  * Shared between the CLI (agentc register) and tests. Uses `Bun.build`
  * to bundle TypeScript sources into a self-contained ESM module.
  *
- * Post de-broker there are no agent bundles to produce — workflows embed
- * their agent loops inline via `runAgent(...)`, and workflows invoke other
- * workflows via the public SDK client.
+ * Two layers of validation run before the bundle leaves this function:
+ *   1. AST check (`assertDefaultExportIsDefineWorkflow`) on the bundled
+ *      output — proves the default export is a `defineWorkflow(...)` call,
+ *      not a raw `async function`. Catches harnesses that hand-roll their
+ *      own register flow without going through `defineWorkflow`.
+ *   2. Runtime brand check (`isWorkflow`) — confirms the value the module
+ *      actually exports carries the `WORKFLOW_BRAND` symbol that
+ *      `defineWorkflow` / `defineWorkflow(...).build()` stamps. Catches
+ *      indirection (re-exports, aliasing) that the AST walk can't follow.
+ *
+ * Both checks happen here, in the user's dev environment. The server NEVER
+ * parses or imports user source — it only validates the structured manifest
+ * this function returns alongside the bundled bytes, and cross-checks the
+ * manifest's `sourceHash` against the source it received.
  */
+import type { WorkflowMemoryConfig } from "../types/workflow.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
+import { type WorkflowPlan } from "../types/workflow-plan.js";
+/** Bumped when the manifest contract changes in a way the server should
+ *  notice. The server pins its manifest schema to this exact value (no
+ *  `>=` accepted) so a manifest forged with a future version is refused
+ *  by zod before any other validation runs. */
+export declare const BUNDLER_VERSION = 1;
+/**
+ * Manifest emitted alongside the bundled source. Fully serialisable JSON;
+ * the server validates its shape with zod and never inspects the source
+ * bytes themselves. Manifest is bound to source via `sourceHash` so the
+ * server can refuse manifests detached from the source they describe.
+ */
+export interface WorkflowManifest {
+    /** Always `true`. The bundler stamps this only after both validation
+     *  gates pass; the server's zod schema pins it as `z.literal(true)`. */
+    definitionBrand: true;
+    /** sha256 hex digest of `source`. The server cross-checks this against
+     *  `hashSource(body.source)` to bind the manifest to the bytes it describes. */
+    sourceHash: string;
+    /** Bundler contract version. See `BUNDLER_VERSION`. */
+    bundlerVersion: number;
+}
+export declare class WorkflowSourceValidationError extends Error {
+    constructor(message: string);
+}
 export interface BundledWorkflow {
     source: string;
+    manifest: WorkflowManifest;
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
     /** Run UUID, workflow name, or `name@version` referencing the snapshot
@@ -19,7 +57,28 @@ export interface BundledWorkflow {
     snapshot?: string;
     /** Default capture-on-success flag from the workflow definition. */
     saveSnapshot?: boolean;
+    workflowPlan: WorkflowPlan;
+    /** Workflow Memory extractor config. */
+    memory?: WorkflowMemoryConfig;
 }
+/**
+ * Parse the bundled source and assert the default export is a CallExpression
+ * to an identifier named `defineWorkflow` (or to a `.step(...).build()` chain
+ * rooted in one). This catches:
+ *
+ *   - Raw TypeScript shipped to the registry (parse fails on type syntax)
+ *   - `export default async function run(ctx)` (default is not a call)
+ *   - `export default { run }` etc. (default is not a call)
+ *   - `export default someFunction` (default is not a defineWorkflow call)
+ *
+ * The check is intentionally syntactic — it doesn't follow imports or trace
+ * through aliases. The runtime brand check (`isWorkflow`) picks up edge
+ * cases the AST can't see, so the two layers compose.
+ *
+ * Exported so the unit tests can exercise this exact code path; do NOT call
+ * from outside the SDK — `bundleWorkflow` is the supported entrypoint.
+ */
+export declare function assertDefaultExportIsDefineWorkflow(source: string, label: string): void;
 /** Bundle a workflow from source. */
 export declare function bundleWorkflow(workflowPath: string, overrides?: {
     networkPolicy?: SandboxNetworkPolicy;

package/dist/workflow-steps/__tests__/observability.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workflow-steps/index.d.ts

@@ -0,0 +1,10 @@
+export { defineStep } from "./step.js";
+export type { DefineStepOpts } from "./step.js";
+export { createStepWorkflow, isWorkflow } from "./workflow.js";
+export type { StepWorkflowDefinition, WorkflowBuilder } from "./workflow.js";
+export { runWorkflowSteps, runWorkflowSingleStep, StepValidationError, WorkflowInputValidationError, WorkflowOutputValidationError, } from "./runner.js";
+export type { RunWorkflowStepsOpts, RunWorkflowStepsResult, RunWorkflowSingleStepOpts, RunWorkflowSingleStepResult, } from "./runner.js";
+export type { Step, StepContext, StepRunResult, Workflow, } from "./types.js";
+export { WORKFLOW_BRAND } from "./types.js";
+export { StepObservabilityCollector } from "./observability.js";
+export type { StepObservability, SubStepEvent } from "./observability.js";

package/dist/workflow-steps/observability.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Per-step observability collector — buffers metadata writes, agent
+ * lifecycle events, and `ctx.step("name", fn)` sub-step records during one
+ * step's execution. The runner flushes the snapshot through the
+ * tokenised stdout sentinel; the activity persists the snapshot to the
+ * run's metadata + lifecycle event tables.
+ *
+ * STREAMING — known gap. `agentEvents` are currently batched at step
+ * end. For long-running steps that emit many agent events, this hides
+ * progress from the dashboard until the step completes. The follow-up
+ * is to bring back a minimal `/internal/runs/:runId/steps/:stepIndex/events`
+ * route gated by a per-step JIT-signed token (mint in the activity,
+ * stamp into the runner env, verify on receive) so `agentEvents.emit`
+ * POSTs in real time. Until then `metadata` and `subSteps` are
+ * effectively boundary events (no streaming need) and batching them
+ * matches their natural granularity.
+ */
+import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
+import type { AgentEventSink } from "../types/workflow.js";
+/** One named sub-step (from `ctx.step("name", async () => ...)`).
+ *  Becomes a `workflow_substep_*` lifecycle event on the run timeline. */
+export interface SubStepEvent {
+    name: string;
+    startedAt: number;
+    durationMs: number;
+    status: "completed" | "failed";
+    /** Present when status="failed" — the user error's message. */
+    error?: string;
+}
+/** Snapshot of everything the step's observability hooks recorded. All
+ *  fields are optional so a step that uses none of the hooks produces an
+ *  empty snapshot (and the wire payload omits the field entirely). */
+export interface StepObservability {
+    metadata?: Record<string, unknown>;
+    events?: AgentLifecycleEvent[];
+    subSteps?: SubStepEvent[];
+}
+/**
+ * Append-only collector bound to a single step's `StepContext`. The
+ * step's `setMetadata` / `step` / `agentEvents` properties all point at
+ * this instance. After the step finishes, the engine calls `snapshot()`
+ * to extract the bundle for transport.
+ *
+ * Metadata writes merge (later keys win) — matches the legacy
+ * `mergeRunMetadata` semantics so authors don't see a behaviour change
+ * across migrations.
+ */
+export declare class StepObservabilityCollector {
+    private metadata;
+    private events;
+    private subSteps;
+    readonly setMetadata: (data: Record<string, unknown>) => Promise<void>;
+    readonly step: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
+    readonly agentEvents: AgentEventSink;
+    /** Snapshot the accumulated state. Returns `undefined` when nothing
+     *  was recorded so the wire payload can drop the field entirely. */
+    snapshot(): StepObservability | undefined;
+}

package/dist/workflow-steps/runner.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `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, 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 StepObservability } from "./observability.js";
+export declare class StepValidationError extends Error {
+    readonly stepName: string;
+    readonly side: "input" | "output";
+    readonly kind: "step-validation";
+    constructor(stepName: string, side: "input" | "output", cause: z.ZodError);
+}
+export declare class WorkflowInputValidationError extends Error {
+    readonly workflowId: string;
+    readonly kind: "workflow-input-validation";
+    constructor(workflowId: string, cause: z.ZodError);
+}
+export declare class WorkflowOutputValidationError extends Error {
+    readonly workflowId: string;
+    readonly kind: "workflow-output-validation";
+    constructor(workflowId: string, cause: z.ZodError);
+}
+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 declare function runWorkflowSingleStep(opts: RunWorkflowSingleStepOpts): Promise<RunWorkflowSingleStepResult>;
+export declare function runWorkflowSteps<TInput, TOutput>(opts: RunWorkflowStepsOpts<TInput, TOutput>): Promise<RunWorkflowStepsResult<TOutput>>;

package/dist/workflow-steps/step.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `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 declare function defineStep<TInput, TOutput>(opts: DefineStepOpts<TInput, TOutput>): Step<TInput, TOutput>;

package/dist/workflow-steps/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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. */
+    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 declare const WORKFLOW_BRAND: unique symbol;

package/dist/workflow-steps/workflow-steps.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workflow-steps/workflow.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `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 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 declare function createStepWorkflow<TInput, TOutput>(opts: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;
+/** Type guard — true when `value` is a `Workflow`. */
+export declare function isWorkflow(value: unknown): value is Workflow<unknown, unknown>;

package/dist/workflows/engine.d.ts

@@ -1,17 +1,17 @@
 /**
- * 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 { RequestContext } from "../request-context/request-context.js";
+import type { Workflow } from "../workflow-steps/types.js";
+import { type RunWorkflowStepsOpts } from "../workflow-steps/runner.js";
 /**
  * Thrown from `runWorkflow` when the authored workflow threw.
  * User-level; not a bug in the platform.
@@ -44,7 +44,21 @@ export interface WorkflowResult<T = unknown> {
     /** The value returned by the workflow function. `null` for void workflows. */
     response: T | null;
 }
-export declare function runWorkflow<T = unknown>(wf: WorkflowFn<T>, ctx: Pick<WorkflowCtx, "run" | "input">, opts?: {
+export interface RunWorkflowOptions {
     hooks?: WorkflowHooks;
-    setMetadata?: (data: Record<string, unknown>) => Promise<void>;
-}): Promise<WorkflowResult<T>>;
+    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 declare function runWorkflow<TInput, TOutput>(wf: Workflow<TInput, TOutput>, ctx: {
+    run: {
+        id: string;
+    };
+    input?: TInput;
+}, opts?: RunWorkflowOptions): Promise<WorkflowResult<TOutput>>;