@agent-compose/sdk 0.7.0 → 0.8.1

package/dist/types/workflow.d.ts

@@ -1,229 +1,42 @@
 /**
- * Workflow types — the context and function signature for authoring workflows.
+ * Workflow authoring types — `defineWorkflow` and the shared author-facing
+ * type surface.
  *
- * A workflow is `async (ctx, sandbox) => T`. Two positional args by design:
- *
- *   - `ctx` carries facts + observability about THIS run (id, input,
- *     setMetadata, step). Metadata bag.
- *   - `sandbox` is a capability handed to you by the engine for doing work
- *     (exec commands, write files). Pass it to `agent({ sandbox, ... })`
- *     and to any helper that takes a SandboxProvider (git utilities, file
- *     writers). Constructed once per run; reuse it.
+ * Workflows are STEP-FORM only: a builder of discrete, durable steps —
+ * `defineWorkflow({ id, input, output }).step(defineStep(...)).build()`.
+ * Every step is a replay checkpoint; pause/resume works at step
+ * granularity. The legacy run-form (`defineWorkflow({ run(ctx, sandbox)
+ * { … } })`) has been removed — passing a `run` key throws at
+ * definition time (i.e. at registration, loud and early).
  *
  * LLM agent loops live in `agent(opts)` (sdk/src/agent/run-agent.ts).
  * Invoking other workflows uses `AgentComposeClient.invoke[AndWait](...)`.
  */
-import { z } from "zod";
-import type { SandboxNetworkPolicy } from "../sandbox.js";
-import type { SandboxProvider } from "./sandbox.js";
 import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
-import type { Processor } from "../processors/processor.js";
-import type { StepWorkflowDefinition } from "../workflow-steps/workflow.js";
-import type { Workflow } from "../workflow-steps/types.js";
-import type { BaseExecutionContext } from "./execution-context.js";
-import { type ConnectorRequirements, type ConnectorOperationTag, type InvokePolicy } from "./workflow-metadata.js";
+import type { StepWorkflowDefinition, WorkflowBuilder } from "../workflow-steps/workflow.js";
 export type { WorkflowRun, InvokeChild, BaseExecutionContext } from "./execution-context.js";
-export type { WorkflowMetadata } from "./workflow-metadata.js";
+export type { WorkflowMetadata, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources } from "./workflow-metadata.js";
 export interface AgentEventSink {
     emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
-import type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources } from "./workflow-metadata.js";
-export type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources };
 /** Turn/iteration budget for `agent(opts)`. Re-exported here so authors
  *  can type per-invoke budget overrides they pass as workflow input. */
 export interface AgentBudget {
     turnsPerIteration: number;
     maxIterations: number;
 }
-/** Context passed to a workflow function — facts + observability for this run. */
-export interface WorkflowCtx<TInput extends Record<string, unknown> = Record<string, unknown>> extends Omit<BaseExecutionContext, "sandbox"> {
-    input?: TInput;
-    /** Persist key-value metadata on the run record (e.g. prUrl, planUrl). */
-    setMetadata: (data: Record<string, unknown>) => Promise<void>;
-    /**
-     * Durable named step (ADR-0012). Runs `fn` once and memoises its result to
-     * the sandbox state-dir; on a pause-resume re-entry the recorded value is
-     * returned and `fn` is NOT re-run (a duration-0 "restored" sub-step). Also
-     * emits substep_started / substep_completed / substep_failed lifecycle
-     * events with duration — use for long phases you want both durable and
-     * visible on the run's timeline (setup, external API calls, submit).
-     *
-     * Names must be unique within a step body (they key the memoise file).
-     * A body that pauses is never memoised — the resume re-runs it. For
-     * cross-process side effects (DB writes, emails) use `invokeChild`.
-     */
-    step<T>(name: string, fn: () => Promise<T>): Promise<T>;
-    /** Pass to `agent({ events: ctx.agentEvents })` to stream agent lifecycle events. */
-    agentEvents: AgentEventSink;
-    /**
-     * Workflow-level processors registered via `defineWorkflow({ processors })`.
-     * Read-only here. Authors merge with agent-specific lists when calling
-     * `agent({ processors: [...ctx.processors, mySpecific] })`.
-     *
-     * Empty array when the workflow declared no processors.
-     */
-    processors: readonly Processor[];
-}
-/** A workflow is `async (ctx, sandbox) => TOutput`. */
-export type WorkflowFn<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>> = (ctx: WorkflowCtx<TInput>, sandbox: SandboxProvider) => Promise<TOutput>;
 /**
- * Declare a workflow with server-side metadata.
- * Use `export default defineWorkflow({ run, networkPolicy, ... })` to attach
- * a runner network policy so the server brokers credentials for the workflow
- * sandbox.
+ * Declare a workflow — the typed step builder. Multiple steps with
+ * explicit input/output schemas, durability + replay at every step
+ * boundary:
  *
- * Without defineWorkflow, a plain `export default async (ctx) => {...}` still
- * works — the workflow just runs with secrets passed directly in env.
- */
-export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>> {
-    /** One-line, human-readable description of what this workflow does.
-     *  Surfaced on the dashboard template tile + run page header. */
-    description?: string;
-    /** Zod schema for the workflow's `input`. When declared, the SDK
-     *  bundler captures it as JSON-Schema-shaped `inputSchema` in
-     *  template metadata, the dashboard playground renders a typed
-     *  form, and the engine validates dispatched payloads against it
-     *  at the step boundary. Omit to leave inputs as `unknown` (the
-     *  legacy default — playground falls back to a freeform JSON
-     *  textarea). */
-    input?: z.ZodType<TInput>;
-    /** Same as `input`, for the workflow's return value. Captured into
-     *  `outputSchema` metadata and rendered in the IO panel. */
-    output?: z.ZodType<TOutput>;
-    /**
-     * @deprecated Legacy run-form. Prefer step-form — the
-     * `.step(defineStep(...))` builder — for per-step durability/replay and
-     * working pause. A run-form body compiles to one opaque step
-     * (`compileRunForm`), so any failure/resume re-runs the whole body.
-     */
-    run: WorkflowFn<TOutput, TInput>;
-    /**
-     * All snapshot config — boot source plus capture mode.
-     *
-     * `snapshots.bootFrom`: the runner restores from this exact provider
-     * snapshot id at run start. Omit to boot a fresh sandbox.
-     *
-     * `snapshots.saveLatest`: `true` captures one snapshot after each
-     * successful step (latest-only — prior is freed).
-     * `{ saveLatest: true, retainSteps: true }` keeps every step's
-     * snapshot for fork / replay / time-travel.
-     *
-     * Snapshots are long-lived (never auto-expire). List + delete via
-     * `agentc snapshot list/delete`. Per-invocation
-     * `invoke({ snapshots })` overrides this default.
-     */
-    snapshots?: SnapshotConfig;
-    /**
-     * Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string:
-     * `2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`) and `provider`
-     * (`vercel` | `e2b`). `size` maps to provider machine specs at create
-     * (Vercel: vCPUs, 2048 MB RAM per vCPU); E2B sizing is template-defined and
-     * ignores it. Optional; omit → smallest SKU on the default provider.
-     * Per-invocation `invoke({ size })` overrides the size.
-     */
-    resources?: SandboxResources;
-    /**
-     * Outbound network policy for the runner sandbox.
-     * Use "*": [] to allow all traffic while still injecting headers for specific domains.
-     * Secret values are referenced as $VARIABLE and resolved from GCP at dispatch time.
-     * Vercel only — E2B ignores.
-     *
-     * @example
-     * networkPolicy: {
-     *   allow: {
-     *     "*": [],
-     *     "api.github.com": [{ transform: [{ headers: { "Authorization": "basic:$GITHUB_TOKEN" } }] }],
-     *   }
-     * }
-     */
-    networkPolicy?: SandboxNetworkPolicy;
-    /**
-     * Workflow-level processor chain — runs around every `agent(...)` loop the
-     * workflow body launches, ahead of any agent-specific processors. Use for
-     * org-wide gating (deny destructive tools, require scopes). Authors merge
-     * with agent-specific lists via `[...ctx.processors, ...]`.
-     */
-    processors?: readonly Processor[];
-    /**
-     * Optional placeholder env var values for secrets referenced in the network policy.
-     * By default, brokered secrets are removed from the runner env entirely — the real
-     * values are only ever present inside the Vercel firewall config, never in the VM.
-     * Only set this if a tool or SDK validates the env var format on startup before
-     * making any requests (e.g. some CLIs check that ANTHROPIC_API_KEY looks like a
-     * real key). The placeholder is a syntactically valid but non-functional stand-in.
-     *
-     * @example
-     * placeholders: {
-     *   ANTHROPIC_API_KEY: `sk-ant-api03-${"a".repeat(95)}`,
-     * }
-     */
-    placeholders?: Record<string, string>;
-    /**
-     * Connector requirements (ADR-0007). Declaring a provider makes the
-     * server resolve an authorized OAuth grant for the calling principal at
-     * dispatch time and inject a fresh access token at the network layer —
-     * workflow code talks to the provider API with plain fetch/SDKs and
-     * never holds the credential.
-     *
-     * @example
-     * connectors: { github: { scopes: ["repo"] } }
-     */
-    connectors?: ConnectorRequirements;
-    /**
-     * Marks this workflow as a catalogue OPERATION of a connector — e.g.
-     * the `create-issue` operation of the `github` connector. Pair with
-     * `description` + `input`/`output` schemas so the operation is fully
-     * self-describing (MCP-tool-like) to humans and agents browsing the
-     * connector catalogue.
-     *
-     * @example
-     * connectorOperation: { provider: "github", operation: "create-issue" }
-     */
-    connectorOperation?: ConnectorOperationTag;
-    /**
-     * Tier-1 invoke ACL (connector credential boundary). When this workflow
-     * declares `connectors` (it brokers a credential) AND an `invokePolicy`,
-     * the server evaluates the calling principal against the policy BEFORE
-     * binding any grant — a caller matching no clause is refused with HTTP
-     * 403. Has no effect on workflows that declare no connectors. Omit to
-     * leave the workflow invokable by the whole team.
-     *
-     * @example
-     * connectors: { github: { access: "read" } },
-     * invokePolicy: { users: "owner", workflows: ["nightly-orchestrator"] }
-     */
-    invokePolicy?: InvokePolicy;
-    /**
-     * Internal — set by `defineSandboxEnvironment`, not by workflow authors.
-     * Marks the workflow as an environment build (base-env / agent-env) so the
-     * server skips mounting the shared factory drive for its runs (#13). See
-     * `WorkflowMetadata.environmentBuild`.
-     */
-    environmentBuild?: boolean;
-}
-/**
- * Declare a workflow. Two forms; both return a `Workflow` whose
- * `metadata` field carries the server-readable declarations.
+ *   defineWorkflow({ id, input, output }).step(defineStep(...)).build()
  *
- * 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.
- */
-/**
- * @deprecated Run-form is legacy. Use the step-form overload —
- * `defineWorkflow({ id, input, output }).step(defineStep(...)).build()` — for
- * durable, replayable steps and working pause. Run-form compiles to a single
- * opaque step (`compileRunForm`); there is no per-step replay.
+ * The bundler reads `workflow.metadata.networkPolicy` / `placeholders` /
+ * etc. off the built `Workflow`; the server stores the step plan; runner
+ * subprocesses execute one step at a time via the StepInvocation seam.
  */
-export 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>;
+export declare function defineWorkflow<TInput, TOutput>(def: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;
 /** Observability-only lifecycle hooks — passed to the workflow engine, not workflow authors. */
 export interface WorkflowHooks {
     onStepStart?: (step: string) => void;

package/dist/utils/bundler.d.ts

@@ -18,10 +18,24 @@
  * 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 type { SnapshotConfig } from "../types/workflow.js";
-import type { IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "../types/workflow-metadata.js";
+import type { IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources, DriveMergePolicy } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
+import type { Workflow } from "../workflow-steps/types.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
@@ -87,6 +101,9 @@ export interface BundledWorkflow {
     /** Sandbox resources declared via `defineWorkflow({ resources })` — machine
      *  SKU (`size`) and `provider` (`vercel` | `e2b`). */
     resources?: SandboxResources;
+    /** Run-branch merge policy declared via `defineWorkflow({ mergePolicy })`.
+     *  Absent ⇒ `"auto"` (today's behaviour). */
+    mergePolicy?: DriveMergePolicy;
     workflowPlan: WorkflowPlan;
     /** Compact JSON-Schema-shaped description of the workflow's input
      *  type. Extracted from the workflow's declared `input` zod schema
@@ -104,7 +121,50 @@ 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 declare 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 declare const SDK_SPECIFIER_ALIASES: readonly string[];
+/** `@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 declare function resolveSdkAlias(specifier: string): string | null;
+/**
+ * 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 declare function explainBundleFailure(err: unknown, label: string): string;
 /**
  * Parse the bundled source and assert the default export is a CallExpression
  * to an identifier named `defineWorkflow` (or to a `.step(...).build()` chain
@@ -123,6 +183,13 @@ export interface BundledWorkflow {
  * from outside the SDK — `bundleWorkflow` is the supported entrypoint.
  */
 export declare function assertDefaultExportIsDefineWorkflow(source: string, label: string): void;
+/**
+ * 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 declare function extractWorkflowPlan(workflow: Workflow<unknown, unknown>): WorkflowPlan;
 /** Bundle a workflow from source. */
 export declare function bundleWorkflow(workflowPath: string, overrides?: {
     networkPolicy?: SandboxNetworkPolicy;

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

@@ -4,7 +4,7 @@ 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 type { Step, StepContext, StepDeliverable, 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

@@ -52,7 +52,14 @@ 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[];
 }
 /**

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

@@ -25,7 +25,7 @@ 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 { WorkflowRun, InvokeChild } from "../types/execution-context.js";
 import { type StepObservability } from "./observability.js";
 import type { LiveAgentEventEmitter } from "./run-callback.js";
 export declare class StepValidationError extends Error {
@@ -67,7 +67,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
@@ -89,7 +89,7 @@ export interface RunWorkflowSingleStepOpts {
     requestContext: RequestContext;
     sandbox?: SandboxProvider;
     abortSignal?: AbortSignal;
-    invokeChild?: WorkflowCtx["invokeChild"];
+    invokeChild?: InvokeChild;
     /** Optional live-stream emitter — see `RunWorkflowStepsOpts.liveAgentEventEmitter`. */
     liveAgentEventEmitter?: LiveAgentEventEmitter;
 }

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

@@ -7,19 +7,33 @@
  *   - `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[];
 }
 export declare function defineStep<TInput, TOutput>(opts: DefineStepOpts<TInput, TOutput>): Step<TInput, TOutput>;

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

@@ -14,6 +14,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
  * the step can read tenant identity and run identity, log progress, and
@@ -59,6 +60,14 @@ 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.
  *
@@ -77,6 +86,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[];
 }
 /**
  * The result of running one step. Engine adapters persist these into the
@@ -89,18 +103,18 @@ export type StepRunResult<TOutput = unknown> = {
     status: "completed";
     output: TOutput;
     durationMs: number;
-    observability?: import("./observability.js").StepObservability;
+    observability?: StepObservability;
 } | {
     status: "failed";
     error: string;
     durationMs: number;
-    observability?: import("./observability.js").StepObservability;
+    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/dist/workflow-steps/workflow.d.ts

@@ -20,7 +20,7 @@
  */
 import type { z } from "zod";
 import type { Step, Workflow } from "./types.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";
 export interface WorkflowBuilder<TInput, TCurrent> {
@@ -50,7 +50,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 declare function createStepWorkflow<TInput, TOutput>(opts: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;
 /** Type guard — true when `value` is a `Workflow`. */

package/dist/workflows/engine.d.ts

@@ -8,7 +8,8 @@
  * Errors classified into `WorkflowError` (user code threw) vs `EngineError`
  * (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 { RequestContext } from "../request-context/request-context.js";
 import type { Workflow } from "../workflow-steps/types.js";
 import { type RunWorkflowStepsOpts } from "../workflow-steps/runner.js";
@@ -54,7 +55,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 declare function runWorkflow<TInput, TOutput>(wf: Workflow<TInput, TOutput>, ctx: {
     run: {

package/dist/workflows/invoke-child.d.ts

@@ -1,4 +1,22 @@
-import type { WorkflowCtx } from "../types/workflow.js";
+import type { InvokeChild } from "../types/execution-context.js";
+/**
+ * Derive the deterministic per-call `Idempotency-Key` for a `ctx.invokeChild`
+ * dispatch: `invoke-child:<parentRunId>:step<stepIndex>:<childName>:<ordinal>`.
+ *
+ * Replay safety: a replayed step re-runs its body from the top, so the k-th
+ * `invokeChild(name)` call in a step re-derives the SAME key (the per-scope
+ * ordinal counter lives on the active-step state, which resets identically on
+ * every (re-)entry — the `nextPauseOrdinalInActiveStep` pattern). The server's
+ * idempotency window then returns the original child run instead of
+ * double-dispatching. Outside step execution (local dev, tests) there is no
+ * stable coordinate to key on — returns null and the dispatch is unkeyed,
+ * exactly the old behavior.
+ *
+ * Key syntax matches the server's `Idempotency-Key` grammar
+ * (`[A-Za-z0-9_\-:.]{1,255}`): runId is a UUID, step index a number, and
+ * workflow names are kebab-case.
+ */
+export declare function deriveInvokeChildIdempotencyKey(parentRunId: string, childName: string): string | null;
 /**
  * Build the public-API child workflow invoker used by legacy and sandboxed
  * workflow execution. Provider-backed engines may inject a different
@@ -7,4 +25,4 @@ import type { WorkflowCtx } from "../types/workflow.js";
 export declare function buildInvokeChild(runId: string, opts?: {
     fallbackBaseUrl?: string;
     defaultFactorySlug?: string;
-}): WorkflowCtx["invokeChild"];
+}): InvokeChild;

package/dist/workflows/invoke-child.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Replay-safety pin for `ctx.invokeChild` (parity plan P3.3): the
+ * Idempotency-Key a child dispatch carries is DETERMINISTIC per
+ * (parentRunId, stepIndex, childName, call ordinal) — a step body re-run
+ * from the top (pause/resume re-entry, crash-replayed attempt) re-derives
+ * byte-identical keys, so the server's idempotency window collapses the
+ * replayed dispatch into the original child run instead of double-running.
+ */
+export {};

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Layr-Labs/agent-compose.git",
+    "url": "git+https://github.com/Chris-Moller/agent-compose.git",
     "directory": "sdk"
   },
   "type": "module",