@agent-compose/sdk 0.2.3 → 0.2.4

package/src/types/workflow.ts

@@ -6,23 +6,41 @@
  *   - `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 { 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 } from "./workflow-metadata.js";
 
-/** The identity of this workflow run. */
-export interface WorkflowRun {
-  id: string;
+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 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;
@@ -30,9 +48,8 @@ export interface AgentBudget {
 }
 
 /** 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>;
   /**
@@ -41,10 +58,23 @@ 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.
@@ -55,8 +85,11 @@ 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
@@ -88,6 +121,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
@@ -102,22 +142,95 @@ 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.
+ * 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.
+ */
+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 step: Step<TInput, TOutput> = {
+    name:   "run",
+    input:  unknownSchema as z.ZodType<TInput>,
+    output: unknownSchema as z.ZodType<TOutput>,
+    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,
+        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:  unknownSchema as z.ZodType<TInput>,
+    output: unknownSchema as z.ZodType<TOutput>,
+    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).
+ *
+ * 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 function defineWorkflow<T = unknown>(
-  def: WorkflowDefinition<T>,
-): WorkflowFn<T> & Pick<WorkflowDefinition, "networkPolicy" | "placeholders" | "snapshot" | "saveSnapshot"> {
-  return Object.assign(def.run, {
-    networkPolicy: def.networkPolicy,
-    placeholders:  def.placeholders,
-    snapshot:      def.snapshot,
-    saveSnapshot:  def.saveSnapshot,
-  });
+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));
+  return createStepWorkflow(def);
 }
 
 /** Observability-only lifecycle hooks — passed to the workflow engine, not workflow authors. */
@@ -125,4 +238,5 @@ 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/src/utils/bundler.ts

@@ -4,17 +4,65 @@
  * 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 { createHash } from "node:crypto";
+import { parse as babelParse } from "@babel/parser";
+import type { File, ExportDefaultDeclaration, CallExpression, Expression, Statement } from "@babel/types";
 import { importSourceModule } from "./source-loader.js";
-import type { WorkflowFn, WorkflowDefinition } from "../types/workflow.js";
+import type { WorkflowMemoryConfig } from "../types/workflow.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
+import { isWorkflow } from "../workflow-steps/workflow.js";
+import type { Workflow } from "../workflow-steps/types.js";
+import { workflowPlan, 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 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 class WorkflowSourceValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowSourceValidationError";
+  }
+}
 
 export interface BundledWorkflow {
   source: string;
+  manifest: WorkflowManifest;
   networkPolicy?: SandboxNetworkPolicy;
   placeholders?: Record<string, string>;
   /** Run UUID, workflow name, or `name@version` referencing the snapshot
@@ -23,6 +71,9 @@ export interface BundledWorkflow {
   snapshot?: string;
   /** Default capture-on-success flag from the workflow definition. */
   saveSnapshot?: boolean;
+  workflowPlan: WorkflowPlan;
+  /** Workflow Memory extractor config. */
+  memory?: WorkflowMemoryConfig;
 }
 
 async function bundle(path: string, label: string): Promise<string> {
@@ -66,30 +117,159 @@ async function extractFromBundle<T>(
   } catch { return undefined; }
 }
 
+/**
+ * Bun bundles `import { defineWorkflow }` to a local identifier — usually
+ * the exact name, or a numeric suffix like `defineWorkflow2` to disambiguate
+ * scopes. Match exactly that pattern, NOT `startsWith("defineWorkflow")` —
+ * the latter would also accept `defineWorkflowAttacker`. The runtime brand
+ * check is the second gate, but the syntactic check should be tight.
+ */
+const DEFINE_WORKFLOW_CALLEE = /^defineWorkflow\d*$/;
+
+function isDefineWorkflowCall(node: CallExpression): boolean {
+  if (node.callee.type === "Identifier") {
+    return DEFINE_WORKFLOW_CALLEE.test(node.callee.name);
+  }
+  // `defineWorkflow(...).step(...).build()` — walk the call chain back to
+  // the leftmost callee; if any step in the chain hands off to a
+  // defineWorkflow identifier, accept it.
+  if (node.callee.type === "MemberExpression" && node.callee.object.type === "CallExpression") {
+    return isDefineWorkflowCall(node.callee.object);
+  }
+  return false;
+}
+
+/**
+ * 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 function assertDefaultExportIsDefineWorkflow(source: string, label: string): void {
+  let ast: File;
+  try {
+    ast = babelParse(source, {
+      sourceType: "module",
+      // Bundler output is plain JS; no JSX, no TS. Allow modern syntax
+      // (Bun's bundler may still emit `??=`/`?.` etc).
+      plugins: [],
+      errorRecovery: false,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new WorkflowSourceValidationError(
+      `Bundled workflow ${label} failed to parse as JavaScript: ${msg}. ` +
+      `If you registered raw .ts source, switch to \`agentc register <file.ts>\` so the source is bundled first.`,
+    );
+  }
+
+  const defaultExpr = findDefaultExportExpression(ast.program.body);
+  if (!defaultExpr) {
+    throw new WorkflowSourceValidationError(
+      `Bundled workflow ${label} has no default export. ` +
+      `Use \`export default defineWorkflow({ run: ... })\`.`,
+    );
+  }
+
+  if (defaultExpr.type !== "CallExpression" || !isDefineWorkflowCall(defaultExpr)) {
+    throw new WorkflowSourceValidationError(
+      `Bundled workflow ${label} default export must be a \`defineWorkflow({...})\` call ` +
+      `(or a \`defineWorkflow(...).step(...).build()\` chain). ` +
+      `Got: ${defaultExpr.type}. Wrap your workflow with \`defineWorkflow\` from "@agent-compose/sdk".`,
+    );
+  }
+}
+
+function findDefaultExportExpression(body: Statement[]): Expression | null {
+  const defaultDecl = body.find(
+    (node): node is ExportDefaultDeclaration => node.type === "ExportDefaultDeclaration",
+  );
+  if (defaultDecl) {
+    return defaultDecl.declaration as Expression;
+  }
+
+  // Bun bundles `export default defineWorkflow(...)` as:
+  //   var workflow_default = defineWorkflow(...);
+  //   export { workflow_default as default };
+  const exportNamed = body.find((node) => node.type === "ExportNamedDeclaration" &&
+    node.specifiers.some((spec) => spec.type === "ExportSpecifier" &&
+      spec.exported.type === "Identifier" && spec.exported.name === "default"));
+  if (!exportNamed || exportNamed.type !== "ExportNamedDeclaration") return null;
+  const spec = exportNamed.specifiers.find((s) => s.type === "ExportSpecifier" &&
+    s.exported.type === "Identifier" && s.exported.name === "default");
+  if (!spec || spec.type !== "ExportSpecifier" || spec.local.type !== "Identifier") return null;
+  const localName = spec.local.name;
+
+  for (const stmt of body) {
+    if (stmt.type !== "VariableDeclaration") continue;
+    for (const decl of stmt.declarations) {
+      if (decl.id.type === "Identifier" && decl.id.name === localName && decl.init && decl.init.type !== "TSSatisfiesExpression") {
+        return decl.init as Expression;
+      }
+    }
+  }
+  return null;
+}
+
+/** SHA-256 hex digest of a string. Used to bind a manifest to its source. */
+function sha256(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
 /** Bundle a workflow from source. */
 export async function bundleWorkflow(
   workflowPath: string,
   overrides?: { networkPolicy?: SandboxNetworkPolicy; placeholders?: Record<string, string> },
 ): Promise<BundledWorkflow> {
-  const source = await bundle(workflowPath, `workflow "${workflowPath}"`);
+  const label = `"${workflowPath}"`;
+  const source = await bundle(workflowPath, `workflow ${label}`);
+
+  // Layer 1: AST gate on the bundled output. Cheapest check; rejects raw TS
+  // and non-defineWorkflow defaults before we even try to import the bundle.
+  assertDefaultExportIsDefineWorkflow(source, label);
 
-  type Wf = WorkflowFn & Pick<WorkflowDefinition, "networkPolicy" | "placeholders" | "snapshot" | "saveSnapshot">;
-  const wfBits = await extractFromBundle<Pick<Wf, "networkPolicy" | "placeholders" | "snapshot" | "saveSnapshot">>(
+  // Layer 2: actually load the bundle and check the runtime brand on the
+  // default export. Catches indirection (re-exports, aliasing) the AST walk
+  // can't follow. Reads metadata + steps from the workflow's own fields.
+  const workflow = await extractFromBundle<Workflow<unknown, unknown>>(
     source, "workflow",
-    (wf) => wf ? {
-      networkPolicy: (wf as Wf).networkPolicy,
-      placeholders:  (wf as Wf).placeholders,
-      snapshot:      (wf as Wf).snapshot,
-      saveSnapshot:  (wf as Wf).saveSnapshot,
-    } : undefined,
+    (wf) => (isWorkflow(wf) ? wf : undefined),
   );
-  const { networkPolicy, placeholders, snapshot, saveSnapshot } = wfBits ?? {};
+  if (!workflow) {
+    throw new WorkflowSourceValidationError(
+      `Bundled workflow ${label} default export is not a Workflow. ` +
+      `Wrap your workflow with \`defineWorkflow\` from "@agent-compose/sdk" — ` +
+      `raw \`export default async function\` is no longer supported.`,
+    );
+  }
+
+  const { metadata } = workflow;
+  const plan: WorkflowPlan = workflowPlan(workflow.steps.map((step, index) => ({ index, name: step.name })));
+  const manifest: WorkflowManifest = {
+    definitionBrand: true,
+    sourceHash:      sha256(source),
+    bundlerVersion:  BUNDLER_VERSION,
+  };
 
   return {
     source,
-    networkPolicy: overrides?.networkPolicy ?? networkPolicy,
-    placeholders:  overrides?.placeholders  ?? placeholders,
-    ...(snapshot     !== undefined ? { snapshot }     : {}),
-    ...(saveSnapshot !== undefined ? { saveSnapshot } : {}),
+    manifest,
+    workflowPlan: plan,
+    networkPolicy: overrides?.networkPolicy ?? metadata.networkPolicy,
+    placeholders:  overrides?.placeholders  ?? metadata.placeholders,
+    ...(metadata.snapshot     !== undefined ? { snapshot:     metadata.snapshot }     : {}),
+    ...(metadata.saveSnapshot !== undefined ? { saveSnapshot: metadata.saveSnapshot } : {}),
+    ...(metadata.memory       !== undefined ? { memory:       metadata.memory }       : {}),
   };
 }

package/src/utils/source-loader.ts

@@ -1,5 +1,5 @@
 import { dirname } from "path";
-import { writeFile, unlink, mkdir } from "node:fs/promises";
+import { writeFile, rm, mkdir } from "node:fs/promises";
 
 export const TMP_DIR       = process.env.TMP_DIR ?? "/tmp/agent-compose";
 export const LATEST_VERSION = "$LATEST";
@@ -11,6 +11,6 @@ export async function importSourceModule<T>(
   await mkdir(dirname(tmpPath), { recursive: true });
   await writeFile(tmpPath, source, "utf8");
   const mod     = await import(tmpPath) as T;
-  const cleanup = () => unlink(tmpPath).catch(() => {});
+  const cleanup = () => rm(tmpPath, { force: true });
   return { mod, cleanup };
 }

package/src/workflow-steps/index.ts

@@ -0,0 +1,30 @@
+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/src/workflow-steps/observability.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 class StepObservabilityCollector {
+  private metadata: Record<string, unknown> = {};
+  private events:   AgentLifecycleEvent[]   = [];
+  private subSteps: SubStepEvent[]          = [];
+
+  readonly setMetadata = async (data: Record<string, unknown>): Promise<void> => {
+    Object.assign(this.metadata, data);
+  };
+
+  readonly step = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
+    const startedAt = Date.now();
+    try {
+      const result = await fn();
+      this.subSteps.push({
+        name,
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        status:     "completed",
+      });
+      return result;
+    } catch (err) {
+      this.subSteps.push({
+        name,
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        status:     "failed",
+        error:      err instanceof Error ? err.message : String(err),
+      });
+      throw err;
+    }
+  };
+
+  readonly agentEvents: AgentEventSink = {
+    emit: (event: AgentLifecycleEvent) => {
+      this.events.push(event);
+    },
+  };
+
+  /** Snapshot the accumulated state. Returns `undefined` when nothing
+   *  was recorded so the wire payload can drop the field entirely. */
+  snapshot(): StepObservability | undefined {
+    const hasMetadata = Object.keys(this.metadata).length > 0;
+    const hasEvents   = this.events.length > 0;
+    const hasSubSteps = this.subSteps.length > 0;
+    if (!hasMetadata && !hasEvents && !hasSubSteps) return undefined;
+    const result: StepObservability = {};
+    if (hasMetadata) result.metadata = { ...this.metadata };
+    if (hasEvents)   result.events   = [...this.events];
+    if (hasSubSteps) result.subSteps = [...this.subSteps];
+    return result;
+  }
+}