@agent-compose/sdk 0.7.0 → 0.8.1

package/src/utils/bundler.ts

@@ -18,14 +18,28 @@
  * 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.
+ *
+ * Module resolution carries two more layers, because most workflow source is
+ * now written by an AGENT and the bundler's error is the only feedback it
+ * gets (the Workflow Studio's agent authored `import … from "agentc/sdk"`
+ * and prod answered with bun's `Maybe you need to "bun install"?` — advice
+ * nobody could act on inside a sandbox with no package.json):
+ *
+ *   - TOLERATE (`SDK_SPECIFIER_ALIASES` + `sdkAliasPlugin`) — near-miss
+ *     spellings of `@agent-compose/sdk` resolve to the real package, so a
+ *     draft already written with the wrong one builds unedited.
+ *   - SELF-CORRECT (`explainBundleFailure`) — anything that still fails to
+ *     resolve produces an error NAMING the real package, which an agent
+ *     reading its own tool error can fix on the next turn.
  */
 
 import { createHash } from "node:crypto";
+import { dirname } from "node:path";
 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 +115,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
@@ -118,11 +135,191 @@ export interface BundledWorkflow {
   /** Set by `defineSandboxEnvironment` — marks an environment build so the
    *  server skips the /factory mount for its runs (#13). */
   environmentBuild?: boolean;
+  /** Drive requirement declared via `defineWorkflow({ factoryDrive })`.
+   *  Absent ⇒ `"required"` (a failed /factory mount fails the run);
+   *  `"none"` = explicit no-drive opt-out. */
+  factoryDrive?: "required" | "none";
+}
+
+/** The one true import specifier for the platform SDK. */
+export const SDK_PACKAGE = "@agent-compose/sdk";
+
+/**
+ * Import specifiers that can only have MEANT `@agent-compose/sdk`, rewritten
+ * to it at bundle time so a draft written with the wrong spelling builds
+ * unedited.
+ *
+ * Every entry carries an `sdk` segment or suffix, so none of them can be a
+ * real third-party package a workflow might legitimately depend on: `a/b`
+ * forms are subpaths of packages that don't exist, and the `*-sdk` forms
+ * name this platform explicitly. Bare `agentc` / `agent-compose` are
+ * deliberately NOT aliased — those are plausible npm package names, and
+ * silently redirecting a real dependency is worse than a clear error.
+ *
+ * Exported for the unit test that pins the table.
+ */
+export const SDK_SPECIFIER_ALIASES: readonly string[] = [
+  "agentc/sdk",
+  "@agentc/sdk",
+  "agentc-sdk",
+  "agent-compose/sdk",
+  "agentcompose/sdk",
+  "@agentcompose/sdk",
+  "agent-compose-sdk",
+];
+
+const SDK_ALIAS_SET = new Set(SDK_SPECIFIER_ALIASES);
+
+/** `@agent-compose/sdk` when `specifier` is a known near-miss for it, else
+ *  null. The single authority: the plugin's regex filter is only a fast
+ *  pre-filter, and this decides. */
+export function resolveSdkAlias(specifier: string): string | null {
+  return SDK_ALIAS_SET.has(specifier) ? SDK_PACKAGE : null;
+}
+
+/** Minimal shape of the Bun surface this module drives. Accessed via
+ *  globalThis so the SDK keeps no compile-time dependency on @types/bun. */
+interface BunBuildLog { message: string; name?: string; specifier?: string }
+interface BunSurface {
+  build(opts: {
+    entrypoints: string[]; format: string; target: string;
+    plugins?: { name: string; setup(build: BunPluginBuild): void }[];
+  }): Promise<{ success: boolean; outputs: { text(): Promise<string> }[]; logs: BunBuildLog[] }>;
+  resolveSync(specifier: string, parent: string): string;
+}
+interface BunPluginBuild {
+  onResolve(
+    constraints: { filter: RegExp; namespace?: string },
+    callback: (args: { path: string; importer?: string; resolveDir?: string }) => { path: string } | undefined,
+  ): void;
+}
+
+/** Anchored regex over the alias table — the plugin filter. Specifiers are
+ *  literal package names, but escape anyway so a future entry with a `.`
+ *  or `+` can't widen the filter. */
+function aliasFilter(): RegExp {
+  const alternation = SDK_SPECIFIER_ALIASES
+    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|");
+  return new RegExp(`^(?:${alternation})$`);
+}
+
+/**
+ * The TOLERATE layer: a Bun resolve plugin that maps every known near-miss
+ * specifier onto the real SDK. Resolution goes through Bun's own resolver
+ * from the importing file's directory, so the alias lands on exactly the
+ * `@agent-compose/sdk` the build would have used had the source spelled it
+ * correctly. When the real SDK can't be resolved either, the plugin declines
+ * and Bun's failure flows into `explainBundleFailure` below.
+ */
+function sdkAliasPlugin(bun: BunSurface): { name: string; setup(build: BunPluginBuild): void } {
+  return {
+    name: "agent-compose-sdk-alias",
+    setup(build) {
+      build.onResolve({ filter: aliasFilter() }, (args) => {
+        const target = resolveSdkAlias(args.path);
+        if (!target) return undefined;
+        // `importer` is the importing FILE, `resolveDir` already a directory.
+        const from = args.importer ? dirname(args.importer) : args.resolveDir;
+        try {
+          return { path: bun.resolveSync(target, from && from.length > 0 ? from : process.cwd()) };
+        } catch {
+          return undefined;
+        }
+      });
+    },
+  };
+}
+
+/** The unresolved specifier a Bun diagnostic is about, or null when it isn't
+ *  a resolve failure. `ResolveMessage` carries it as a field; parsing the
+ *  message text is the fallback. */
+function readUnresolvedSpecifier(diag: unknown): string | null {
+  if (!diag || typeof diag !== "object") return null;
+  const d = diag as { specifier?: unknown; message?: unknown };
+  if (typeof d.specifier === "string" && d.specifier.length > 0) return d.specifier;
+  const message = typeof d.message === "string" ? d.message : "";
+  const m = /Could not resolve:?\s*"([^"]+)"/.exec(message);
+  return m ? m[1] : null;
+}
+
+/** Flatten a bundler failure into the diagnostics it actually carries.
+ *  Bun reports through two channels and both land here: a THROWN
+ *  `AggregateError("Bundle failed")` whose real messages hide in `.errors`,
+ *  and a returned `logs` array on `success: false`. */
+function flattenDiagnostics(failure: unknown): unknown[] {
+  const out: unknown[] = [];
+  const seen = new Set<unknown>();
+  const walk = (node: unknown, depth: number): void => {
+    if (!node || depth > 4 || seen.has(node)) return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (const sub of node) walk(sub, depth + 1);
+      return;
+    }
+    out.push(node);
+    if (typeof node === "object") {
+      const n = node as { errors?: unknown; cause?: unknown };
+      if (Array.isArray(n.errors)) for (const sub of n.errors) walk(sub, depth + 1);
+      if (n.cause) walk(n.cause, depth + 1);
+    }
+  };
+  walk(failure, 0);
+  return out;
+}
+
+function diagnosticText(diag: unknown): string {
+  if (diag instanceof Error) return diag.message || String(diag);
+  if (diag && typeof diag === "object" && typeof (diag as { message?: unknown }).message === "string") {
+    return (diag as { message: string }).message;
+  }
+  return String(diag);
+}
+
+/**
+ * The SELF-CORRECTING layer. Turns a Bun bundle failure into a message that
+ * names the real fix instead of leaking Bun's internals.
+ *
+ * An unresolved import is almost always one thing: workflow source naming
+ * the platform SDK by a specifier that isn't its package name. Bun answers
+ * that with `Could not resolve: "agentc/sdk". Maybe you need to "bun
+ * install"?` — advice the author cannot act on (there is no package.json to
+ * install into; the drive holds one file). The rewritten message says the
+ * package name, so an agent reading its own tool error can fix the import on
+ * the next turn.
+ *
+ * Non-resolve failures (syntax errors, transform failures) keep their
+ * verbatim diagnostics — those are already actionable.
+ *
+ * Exported for the unit test; `bundleWorkflow` is the supported entrypoint.
+ */
+export function explainBundleFailure(err: unknown, label: string): string {
+  const diagnostics = flattenDiagnostics(err);
+  const unresolved: string[] = [];
+  for (const diag of diagnostics) {
+    const specifier = readUnresolvedSpecifier(diag);
+    if (specifier && !unresolved.includes(specifier)) unresolved.push(specifier);
+  }
+
+  if (unresolved.length > 0) {
+    const quoted = unresolved.map((s) => `"${s}"`).join(", ");
+    return (
+      `Could not resolve ${quoted} — workflow source imports the platform SDK as "${SDK_PACKAGE}". ` +
+      `Fix the import specifier in ${label}; anything that is genuinely a third-party ` +
+      `package must be installed where the source is bundled.`
+    );
+  }
+
+  const detail = diagnostics
+    .map(diagnosticText)
+    .filter((t) => t.length > 0 && t !== "Bundle failed")
+    .join("\n");
+  return `Failed to bundle ${label}:\n${detail || "the bundler reported no diagnostics"}`;
 }
 
 async function bundle(path: string, label: string): Promise<string> {
   // Use globalThis to access Bun without a compile-time dependency on @types/bun.
-  const bun = globalThis as unknown as { Bun?: { build(opts: { entrypoints: string[]; format: string; target: string }): Promise<{ success: boolean; outputs: { text(): Promise<string> }[]; logs: { message: string }[] }> } };
+  const bun = globalThis as unknown as { Bun?: BunSurface };
   if (!bun.Bun?.build) throw new Error("bundleWorkflow requires the Bun runtime (Bun.build)");
   // target: "node" — the bundle runs inside the Vercel sandbox under Node 22+.
   //
@@ -138,9 +335,24 @@ async function bundle(path: string, label: string): Promise<string> {
   // Pure-ESM workflows (e.g. only importing `@agent-compose/sdk`) bundled
   // identically under either target — that's why this bug stayed hidden
   // until the first workflow that pulled CJS deps got dispatched.
-  const result = await bun.Bun.build({ entrypoints: [path], format: "esm", target: "node" });
+  //
+  // The alias plugin rewrites known near-miss SDK specifiers before Bun's
+  // resolver sees them; whatever still fails to resolve comes back through
+  // `explainBundleFailure` naming the real package instead of Bun's
+  // "Maybe you need to `bun install`?".
+  let result: Awaited<ReturnType<BunSurface["build"]>>;
+  try {
+    result = await bun.Bun.build({
+      entrypoints: [path], format: "esm", target: "node",
+      plugins: [sdkAliasPlugin(bun.Bun)],
+    });
+  } catch (err) {
+    // Modern Bun.build THROWS AggregateError("Bundle failed") on a resolve
+    // or transform error rather than returning `success: false`.
+    throw new WorkflowSourceValidationError(explainBundleFailure(err, label));
+  }
   if (!result.success) {
-    throw new Error(`Failed to bundle ${label}:\n${result.logs.map((l) => l.message).join("\n")}`);
+    throw new WorkflowSourceValidationError(explainBundleFailure(result.logs, label));
   }
   return result.outputs[0].text();
 }
@@ -173,7 +385,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 +496,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 +546,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,10 +575,12 @@ 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 }        : {}),
     ...(metadata.environmentBuild    !== undefined ? { environmentBuild:    metadata.environmentBuild }    : {}),
+    ...(metadata.factoryDrive        !== undefined ? { factoryDrive:        metadata.factoryDrive }        : {}),
   };
 }
 
@@ -356,8 +592,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

@@ -8,7 +8,22 @@
  *  so the root cause is always visible. Cycle-guarded against self-referential
  *  `cause` links. */
 export function formatError(err: unknown): string {
-  if (!(err instanceof Error)) return 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;

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 }))) }
+      : {}),
   };
 }

package/src/workflow-steps/types.ts

@@ -15,6 +15,7 @@ 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";
+import type { StepObservability } from "./observability.js";
 
 /**
  * Per-step execution context. Threaded into every step's `execute(...)` so
@@ -62,6 +63,15 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
   agentEvents: AgentEventSink;
 }
 
+/** One artifact a step promises to produce. `path` is workspace/drive-relative
+ *  (e.g. "out/report.html"); the dashboard derives the format tag from the
+ *  extension client-side — no `format` field here. */
+export interface StepDeliverable {
+  path: string;
+  /** Optional one-line description of the artifact. */
+  description?: string;
+}
+
 /**
  * Step definition — a single typed unit of work in a workflow chain.
  *
@@ -80,6 +90,11 @@ export interface Step<TInput, TOutput> {
   readonly output: z.ZodType<TOutput>;
   /** Step body. Receives a `StepContext<TInput>` and returns the typed output. */
   run(ctx: StepContext<TInput>): TOutput | Promise<TOutput>;
+  /** One plain sentence of what the step actually does — rendered on the
+   *  dashboard workflow graph. ≤200 chars, no newlines. */
+  readonly summary?: string;
+  /** Files the step promises to produce. ≤8 entries. */
+  readonly deliverables?: readonly StepDeliverable[];
 }
 
 /**
@@ -90,14 +105,14 @@ export interface Step<TInput, TOutput> {
  * 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 };
+  | { status: "completed"; output: TOutput; durationMs: number; observability?: StepObservability }
+  | { status: "failed";    error: string;   durationMs: number; observability?: 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.
+ * schemas plus its server-side metadata bag. Returned by
+ * `defineWorkflow(...).step(...)...build()`. 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

package/src/workflow-steps/workflow.ts

@@ -23,7 +23,7 @@ import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";
 import { WORKFLOW_BRAND } from "./types.js";
 import { extractMetadata } from "../types/workflow-metadata.js";
-import type { SnapshotConfig, SandboxResources } from "../types/workflow-metadata.js";
+import type { SnapshotConfig, SandboxResources, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, DriveMergePolicy } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 
@@ -55,7 +55,35 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
    *  and `provider` (`vercel` | `e2b`). Vercel maps `size` to vCPUs; E2B
    *  sizing is template-defined. Omit → smallest SKU on the default provider. */
   resources?:     SandboxResources;
+  /** What happens to this workflow's drive branch when a run ends:
+   *  `"auto"` (the default when omitted — today's behaviour) folds it into
+   *  `main`; `"manual"` proposes a merge approval at the same terminus
+   *  instead, leaving the branch durable until a human clicks approve. A
+   *  cancelled run neither merges nor proposes under either policy. */
+  mergePolicy?:   DriveMergePolicy;
   processors?:    readonly Processor[];
+  /** Connector requirements (ADR-0007) — providers whose APIs this workflow
+   *  calls. Dispatch resolves an authorized grant per provider and injects a
+   *  fresh access token at the network layer. */
+  connectors?: ConnectorRequirements;
+  /** Marks this workflow as a catalogue OPERATION of a connector — e.g. the
+   *  `create-issue` operation of the `github` connector. */
+  connectorOperation?: ConnectorOperationTag;
+  /** Tier-1 invoke ACL — who may dispatch this connector-brokering workflow.
+   *  See `InvokePolicy`. */
+  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;
+  /** Whether this workflow's runs need the factory drive. Omit (⇒
+   *  `"required"`) for any workflow that reads or writes /factory: a failed
+   *  mount then FAILS the run instead of silently proceeding drive-less.
+   *  Declare `"none"` for a drive-agnostic workflow — the server skips the
+   *  /factory mount entirely for its runs. See
+   *  `WorkflowMetadata.factoryDrive`. */
+  factoryDrive?: "required" | "none";
 }
 
 export function createStepWorkflow<TInput, TOutput>(

package/src/workflows/engine.ts

@@ -9,7 +9,8 @@
  * (platform problem) for the runner harness to surface upstream.
  */
 
-import type { WorkflowHooks, WorkflowCtx } from "../types/workflow.js";
+import type { WorkflowHooks } from "../types/workflow.js";
+import type { InvokeChild } from "../types/execution-context.js";
 import { makeLocalSandboxProvider } from "../sandbox.js";
 import { formatError } from "../utils/errors.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -94,7 +95,7 @@ export interface RunWorkflowOptions {
   /** 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"];
+  invokeChild?:     InvokeChild;
 }
 
 export async function runWorkflow<TInput, TOutput>(