@agent-compose/sdk 0.6.0 → 0.8.0

package/dist/types/execution-context.d.ts

@@ -1,8 +1,8 @@
 /** Shared execution context capabilities for workflow functions and steps. */
-import type { InvokeAndWaitOptions, RunStatus } from "../client.js";
+import type { InvokeAndWaitOptions, RunStatus } from "./api-runs.js";
 import type { RequestContext } from "../request-context/request-context.js";
 import type { PauseRequest } from "../pause/pause-core.js";
-import type { WaitForEventRequest } from "../pause/wrappers.js";
+import type { DecisionRequest, WaitForEventRequest } from "../pause/wrappers.js";
 import type { SandboxProvider } from "./sandbox.js";
 /** The identity of this workflow run. */
 export interface WorkflowRun {
@@ -34,4 +34,14 @@ export interface BaseExecutionContext {
     sleep(durationMs: number): Promise<void>;
     /** Pause until an event resumes by `correlationKey`. Wrapper over `pause`. */
     waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
+    /**
+     * Pause for a typed human/agent decision (ADR-0042). The prompt, options,
+     * draft, and approver refs surface in the dashboard's decision UI (run
+     * page AND the spawning conversation's run card); resolves with the frozen
+     * `{ decision: string }` payload. With `approvers` named, only those team
+     * members can resolve it — server-enforced. Wrapper over `pause`.
+     */
+    requestDecision(req: DecisionRequest): Promise<{
+        decision: string;
+    }>;
 }

package/dist/types/protocol.d.ts

@@ -12,6 +12,16 @@ export interface AgentMessageText extends AgentMessageBase {
     type: "text";
     text: string;
 }
+/** LIVE-ONLY incremental chunk of the in-progress assistant text block
+ *  (claude stream-json `content_block_delta`/`text_delta` under
+ *  `--include-partial-messages`). Consumers that stream progressively
+ *  accumulate deltas; everyone else ignores them — the terminating `text`
+ *  message always carries the COMPLETE block and is the only durable form.
+ *  Additive kind: existing producers never emit it. */
+export interface AgentMessageTextDelta extends AgentMessageBase {
+    type: "text_delta";
+    text: string;
+}
 export interface AgentMessageThinking extends AgentMessageBase {
     type: "thinking";
     text: string;
@@ -62,6 +72,25 @@ export interface AgentMessageUsage extends AgentMessageBase {
     durationMs: number;
     numTurns: number;
 }
+/** LIVE-ONLY incremental usage off the harness's raw provider stream — the
+ *  `text_delta` of token counts. claude-code's `--include-partial-messages`
+ *  stream events carry per-model-call usage (`message_start` /
+ *  `message_delta`) that the terminal `usage` report only totals at turn
+ *  end; this forwards them so a streaming consumer (the cloud executor's
+ *  live token counter) can tick in real time. Semantics per model call
+ *  within the turn: `boundary: "call_start"` carries the call's input-side
+ *  finals (input + cache tokens, known at call start); `"call_delta"`
+ *  carries the call's CUMULATIVE output tokens so far. Never durable and
+ *  never a substitute for `usage` — the agent loop drops it exactly like
+ *  `text_delta`. Additive kind: existing producers never emit it. */
+export interface AgentMessageUsageDelta extends AgentMessageBase {
+    type: "usage_delta";
+    boundary: "call_start" | "call_delta";
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
 /** Structured execution plan emitted by an agent (ACP `plan` session update,
  *  WS-C / ADR-0020 Q2). Each `plan` notification REPLACES the whole plan — the
  *  normaliser emits one `AgentMessagePlan` per notification carrying the entire
@@ -76,7 +105,7 @@ export interface AgentMessagePlan extends AgentMessageBase {
         status: "pending" | "in_progress" | "completed";
     }[];
 }
-export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessagePlan;
+export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageTextDelta | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessageUsageDelta | AgentMessagePlan;
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {
     summary: string;

package/dist/types/sandbox-environment.d.ts

@@ -10,9 +10,10 @@
  *
  *     snapshots: { bootFrom: { snapshotId: "snap_..." } }
  *
- * `defineSandboxEnvironment` is sugar over `defineWorkflow` — it makes the
- * setup recipe read like an imperative script by supplying the local
- * sandbox provider (the runner's own VM) to the callback.
+ * `defineSandboxEnvironment` is sugar over the step builder — it wraps the
+ * `setup` callback as a single-step workflow, supplying the local sandbox
+ * provider (the runner's own VM) so the recipe reads like an imperative
+ * script.
  *
  * Typical flow:
  *   1. Author a setup file with `defineSandboxEnvironment`.
@@ -51,7 +52,9 @@ export interface SandboxEnvironmentDefinition {
      *  agent-env requires `resources: { provider: "e2b" }`. */
     resources?: SandboxResources;
 }
-/** Sugar over `defineWorkflow` for setup-only workflows that exist to
+/** Sugar over the step builder for setup-only workflows that exist to
  *  capture a snapshot. The workflow takes no meaningful input and returns
- *  nothing — its value is the side effect on the sandbox VM. */
+ *  nothing — its value is the side effect on the sandbox VM. Both schemas
+ *  are deliberately `z.unknown()` so no input/output contract is captured
+ *  into template metadata (there is nothing to render). */
 export declare function defineSandboxEnvironment(env: SandboxEnvironmentDefinition): Workflow<Record<string, unknown>, void>;

package/dist/types/sandbox.d.ts

@@ -74,6 +74,38 @@ export interface SandboxSpawnDuplexOptions {
     cwd?: string;
     envs?: Record<string, string>;
 }
+/** Options for opening a brokered interactive PTY in the sandbox
+ *  (ADR-0055 — the session Terminal surface). */
+export interface SandboxPtyOpts {
+    cols: number;
+    rows: number;
+    /** Working directory the shell opens in. Omitted → the guest user's home. */
+    cwd?: string;
+    /** Extra env for the shell. */
+    envs?: Record<string, string>;
+    /** Raw PTY output. */
+    onData: (data: Uint8Array) => void;
+    /** Fired once when the PTY process ends — shell exit, kill, or sandbox
+     *  fault. The server's broker closes the WebSocket off it. */
+    onExit?: () => void;
+}
+/** A live PTY inside the guest, brokered over the server's attach WebSocket. */
+export interface SandboxPtyHandle {
+    /** OS pid inside the VM. */
+    pid: number;
+    sendInput(data: Uint8Array): Promise<void>;
+    resize(size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
+    kill(): Promise<void>;
+    /** Detach this handle's event stream WITHOUT killing the guest process —
+     *  the PTY keeps running (and survives a VM pause) and is re-attachable
+     *  later via `connectPty(pid)`. The detach half of the ADR-0055 §7
+     *  persistent-terminal rework: the server's broker disconnects on socket
+     *  close; killing is a separate, explicit route decision. */
+    disconnect(): Promise<void>;
+}
 /**
  * A sandbox provider implements the RAW provider operations only. It does NOT
  * implement transient-failure retry/backoff: reconnecting and snapshotting both
@@ -114,6 +146,17 @@ export interface SandboxProvider {
     };
     files: {
         write(path: string, content: string): Promise<void>;
+        /** Read a file's text content over the provider's FILE transport. On E2B this
+         *  is the envd HTTP API (`Sandbox.files.read`), a DIFFERENT transport from
+         *  `commands` — so a large readback is immune to the connect-web gRPC
+         *  message-compression that can abort `commands.run` output on a big frame
+         *  ("received unsupported compressed output"). On Vercel it is the HTTP file
+         *  API (`readFileToBuffer`), independent of a faulted runCommand log stream.
+         *  This is what lets the step recovery paths (`launchStep`'s wait,
+         *  `invokeStep`'s foreground stream-fault recovery) backfill the full logs +
+         *  result after a live-stream fault. OPTIONAL — implemented where durable
+         *  file-readback is needed (E2B, Vercel, local). */
+        read?(path: string): Promise<string>;
     };
     kill(): Promise<void>;
     /** Capture the running sandbox's state as a reusable snapshot. Vercel and E2B
@@ -128,6 +171,15 @@ export interface SandboxProvider {
         snapshotId: string;
         sizeBytes?: number;
     }>;
+    /** Resolve a public forwarding host for a port bound inside the sandbox, or
+     *  null when the provider cannot expose ports. E2B returns its native
+     *  `*.e2b.app` host (`sb.getHost(port)`); Vercel/local leave it undefined.
+     *  Pure string op — no retry wrapper (unlike reconnect/snapshot). The
+     *  returned host is the RAW capability and MUST NOT reach a browser
+     *  (ADR-0052 §2.1); the server's member-gated preview proxy is the only
+     *  caller. The presence of this method IS the port-exposure capability
+     *  flag; providers without it leave it undefined (the no-shim rule). */
+    getHost?(port: number): string | null;
     /** Suspend the live VM in place and return a handle to resume it (ADR-0027).
      *  Present ONLY on process-resume-capable providers (E2B via `sandbox.pause()`,
      *  returning the sandbox id; resume is `Sandbox.connect(handle)`, which
@@ -140,6 +192,33 @@ export interface SandboxProvider {
     pauseProcess?(): Promise<{
         resumeHandle: string;
     }>;
+    /** Reset the PROVIDER-side kill-clock: the sandbox lives at least `ms`
+     *  more from now (shorter values SHORTEN the remaining lifetime — E2B's
+     *  `setTimeout` replaces the deadline rather than extending it). The
+     *  server's session lifecycle calls this on every attach-heartbeat tick
+     *  and when it arms the deferred hot-window suspend, so its own suspend
+     *  timer always beats the provider deadline — without it a long-attached
+     *  terminal outlives the create-time timeout and E2B kills the VM before
+     *  the pause can run (persistence silently lost; user-hit 2026-07-25).
+     *  Presence-is-capability: only providers with a live timeout primitive
+     *  (E2B `sandbox.setTimeout`) implement it; others leave it undefined and
+     *  ride their create-time lifetime. */
+    extendLifetime?(ms: number): Promise<void>;
+    /** Open an interactive PTY in the guest (ADR-0055 — the brokered session
+     *  terminal). Presence-is-capability, like `runBackground`: only E2B
+     *  implements it (native `sb.pty`); Vercel/local leave it undefined and
+     *  the server's terminal route answers 400 instead of shimming. */
+    createPty?(opts: SandboxPtyOpts): Promise<SandboxPtyHandle>;
+    /** Re-attach to a PTY that an earlier handle `disconnect()`ed from, by
+     *  pid (ADR-0055 §7 rework — the silent-reattach half of `disconnect`).
+     *  The process kept running (it survives socket close AND a VM
+     *  pause/resume); connecting resumes its output stream on `opts.onData`.
+     *  `opts.cols`/`rows`/`cwd`/`envs` describe the CALLER's viewport intent
+     *  only — the guest process already exists, so providers apply what their
+     *  transport accepts (E2B: onData only; the server jiggles a resize after
+     *  connect to repaint). Presence-is-capability, E2B-only; throws when no
+     *  PTY with that pid is running. */
+    connectPty?(pid: number, opts: SandboxPtyOpts): Promise<SandboxPtyHandle>;
     /** Replace the live sandbox's egress policy in place — so the server can
      *  push a freshly resolved policy (with re-minted connector access tokens)
      *  before each step instead of relying on the policy baked at create.

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

@@ -160,6 +160,23 @@ export interface SandboxResources {
      *  at first dispatch and reused across pause/resume/replay. */
     provider?: WorkflowSandboxProvider;
 }
+/**
+ * What happens to a drive branch at its producer's TERMINUS — the one
+ * vocabulary shared by both branch-producing surfaces (workflow runs and
+ * agent sessions).
+ *
+ * - `"auto"`   — the branch folds into `main` at the terminus.
+ * - `"manual"` — at the SAME terminus a merge APPROVAL is proposed instead.
+ *   The branch is durable, so `manual` never means "silently strand the
+ *   work": it means one click instead of zero.
+ *
+ * **Default for a workflow is `"auto"`** — absent (`mergePolicy` unset) is
+ * exactly what every already-registered workflow does today, so no existing
+ * template needs re-registering. (Sessions default the other way, `manual`,
+ * for the same reason: it is what they do today. The default belongs to the
+ * SURFACE, not to this type.)
+ */
+export type DriveMergePolicy = "auto" | "manual";
 export interface WorkflowMetadata {
     /** One-line, human-readable description of what the workflow does.
      *  Surfaced on the dashboard template tile + run page header. Authors
@@ -169,20 +186,28 @@ export interface WorkflowMetadata {
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
     /** Input schema captured at bundle time from the workflow's
-     *  declared `input` zod schema. Step-form workflows populate this
-     *  automatically; run-form workflows (no explicit input schema —
-     *  defaults to `z.unknown()`) leave it undefined. */
+     *  declared `input` zod schema. Undefined when the schema is
+     *  effectively `z.unknown()` — no contract to render. */
     inputSchema?: IOSchema;
     /** Output schema captured at bundle time from the workflow's
-     *  declared `output` zod schema. Step-form workflows populate this
-     *  automatically; run-form workflows whose `run()` returns
-     *  arbitrarily-typed values leave it undefined. */
+     *  declared `output` zod schema. Undefined when the schema is
+     *  effectively `z.unknown()`. */
     outputSchema?: IOSchema;
     /** All snapshot config — boot source + capture mode. */
     snapshots?: SnapshotConfig;
     /** Sandbox machine resources — size + provider. Optional; omit → smallest
      *  SKU on the platform-default provider (`vercel`). */
     resources?: SandboxResources;
+    /** What happens to this workflow's run branch at the run's terminus:
+     *  `"auto"` folds it into `main` (success AND failure — a failed run still
+     *  produced real outputs); `"manual"` proposes a merge approval at the same
+     *  terminus instead. A CANCELLED run does neither under either policy.
+     *
+     *  Optional + additive: an ABSENT policy means `"auto"` — today's hard-coded
+     *  behaviour — and contributes nothing to the canonical metadata hash
+     *  (frozen-metadata rule), so existing workflows are not forced to
+     *  re-register. */
+    mergePolicy?: DriveMergePolicy;
     processors?: readonly Processor[];
     /** Connector requirements — providers whose APIs this workflow calls.
      *  Dispatch resolves an authorized grant per provider and injects a
@@ -208,8 +233,8 @@ export interface WorkflowMetadata {
     environmentBuild?: boolean;
 }
 /**
- * Pull the server-readable declarations off a source object (run-form
- * `WorkflowDefinition` or step-form `StepWorkflowDefinition`) into a
+ * Pull the server-readable declarations off a `StepWorkflowDefinition`
+ * (or any source overlapping `WorkflowMetadata` in field shape) into a
  * single `WorkflowMetadata` bag. Undefined fields are omitted so the
  * canonical metadata hash (server-side) is stable across re-registers
  * that left a field unspecified.

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

@@ -9,9 +9,19 @@
  * workflows are wrapped at the SDK boundary as a single-step compiled
  * workflow (step name = "run"); the bundler sees the same shape regardless.
  */
+/** One artifact a step promises to produce — mirrors `StepDeliverable`,
+ *  restated here so the plan stays a self-contained wire shape. */
+export interface WorkflowStepDeliverable {
+    path: string;
+    description?: string;
+}
 export interface WorkflowStepPlan {
     index: number;
     name: string;
+    /** Author-declared narrative (defineStep `summary`) — optional, additive. */
+    summary?: string;
+    /** Author-declared artifacts (defineStep `deliverables`) — optional, additive. */
+    deliverables?: WorkflowStepDeliverable[];
 }
 export interface WorkflowPlan {
     steps: WorkflowStepPlan[];

package/dist/types/workflow.d.ts

@@ -1,217 +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.
- *
- * 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>;
-    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.
- *
- * Run form — wraps the legacy `(ctx, sandbox) => T` body as a single
- * step internally. Lifecycle granularity is workflow-level (one step).
+ * Declare a workflow — the typed step builder. Multiple steps with
+ * explicit input/output schemas, durability + replay at every step
+ * boundary:
  *
- * Step form — the typed builder. Multiple steps with explicit input/
- * output schemas, durability + replay at every step boundary.
+ *   defineWorkflow({ id, input, output }).step(defineStep(...)).build()
  *
- * 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.
+ * 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

@@ -20,8 +20,9 @@
  * manifest's `sourceHash` against the source it received.
  */
 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 +88,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
@@ -123,6 +127,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/utils/errors.d.ts

@@ -1,2 +1,10 @@
-/** Convert any thrown value to a string message. */
+/** Convert any thrown value to a string message, INCLUDING its `.cause` chain.
+ *
+ *  Many wrapped errors carry the real reason on `.cause` and only a generic
+ *  summary on `.message` — the Temporal SDK's "Failed to start Workflow" is the
+ *  canonical example (its `.cause` is the actual gRPC rejection, e.g. "search
+ *  attribute X is not defined"). Returning `.message` alone swallowed that, so
+ *  failures surfaced as opaque one-liners. Walk the chain and join the messages
+ *  so the root cause is always visible. Cycle-guarded against self-referential
+ *  `cause` links. */
 export declare function formatError(err: unknown): string;

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;
 }