@agent-compose/sdk 0.6.0 → 0.8.0

package/src/types/conversation-stream.ts

@@ -0,0 +1,231 @@
+/**
+ * Conversation SSE stream — typed wire events (ADR-0033 phase 1 shapes,
+ * extended by ADR-0037 with the live-only `turn_state` / `presence` frames).
+ *
+ * The server (`server/src/routes/conversations.ts`, `GET
+ * /conversations/:id/stream`) emits two classes of event:
+ *
+ *   - **Durable** events (`part`, `message_done`, `error`, `reaction`,
+ *     `message_deleted`): each is a persisted `conversation_stream_events`
+ *     row, carries an SSE `id:` field (the conversation-global row id), and
+ *     replays on reconnect. Clients advance `Last-Event-ID` from these — and
+ *     ONLY these.
+ *   - **Live-only** frames (`part_partial`, `turn_state`, `presence`,
+ *     `session_status`): no row, no SSE `id:` field, never replayed.
+ *     Advancing `Last-Event-ID` from one would skip durable rows on
+ *     reconnect and corrupt replay — this is a pinned invariant on every
+ *     client (dashboard, SDK, TUI).
+ *
+ * Two sequences ride the wire — do not conflate them:
+ *   - the SSE `id:` field is the conversation-global stream-event row id
+ *     (`Last-Event-ID` resumption is keyed on this);
+ *   - `seq` is the per-message part index (0, 1, …) — part ordering and
+ *     replay dedupe within one message key on this.
+ *
+ * `normalizeConversationStreamEvent` folds both transports' framing (SSE
+ * `event:`/`id:` fields + JSON data payload) into one union member with a
+ * single rule: `id` is present ⇔ the event is durable.
+ */
+
+import type { ConversationMessagePart } from "./api-conversations.js";
+
+/** Message author metadata — rides every message-scoped event (live and
+ *  replayed) so a teammate's user message mirrored onto a shared thread
+ *  renders as a user message, not as the agent. */
+export interface ConversationStreamAuthor {
+  authorKind?: "user" | "agent" | "system";
+  authorId?: string | null;
+  /** Present only on thread replies — absent = a room message. */
+  threadRootId?: string;
+}
+
+interface DurableEventBase extends ConversationStreamAuthor {
+  conversationId: string;
+  /** Durable stream-event row id (the SSE `id:` field). Present on every
+   *  durable event; clients advance `Last-Event-ID` from it. */
+  id?: number;
+  /** Producer timestamp, ms epoch. */
+  at: number;
+}
+
+/** One persisted message part (final). Replay-safe: a reconnect that
+ *  re-delivers seq N is a no-op for a buffer that already holds it. */
+export interface ConversationPartEvent extends DurableEventBase {
+  event: "part";
+  messageId: string;
+  seq: number;
+  part: ConversationMessagePart;
+}
+
+/** Live-only progressive re-emit of an in-flight text block: the block's
+ *  FULL text grown so far, at the same `seq` its final `part` event will
+ *  use. Never persisted, never carries an SSE id. */
+export interface ConversationPartPartialEvent extends ConversationStreamAuthor {
+  event: "part_partial";
+  conversationId: string;
+  messageId: string;
+  seq: number;
+  at: number;
+  part: ConversationMessagePart;
+  partial: true;
+}
+
+/** The message's turn completed — the persisted row is authoritative from
+ *  here on. */
+export interface ConversationMessageDoneEvent extends DurableEventBase {
+  event: "message_done";
+  messageId: string;
+  seq: number;
+}
+
+/** A turn error (durable, message-scoped: carries `part` and/or `error`) —
+ *  or a stream-level rejection (`messageId` absent, `error` only: the
+ *  conversation is gone or access was revoked; the server ends the stream). */
+export interface ConversationErrorEvent extends ConversationStreamAuthor {
+  event: "error";
+  conversationId?: string;
+  id?: number;
+  messageId?: string | null;
+  seq?: number;
+  at?: number;
+  part?: ConversationMessagePart;
+  error?: string;
+}
+
+/** Whole-map replacement of one message's reactions — replays and
+ *  out-of-order arrivals are harmless (last write wins). */
+export interface ConversationReactionEvent extends DurableEventBase {
+  event: "reaction";
+  messageId: string;
+  seq: number;
+  reactions: Record<string, string[]>;
+}
+
+/** A message was deleted. `tombstoned: true` = a thread root that kept its
+ *  shell; false/absent = hard-deleted. Durable either way (hard deletes
+ *  persist a null-FK marker row), so it replays on reconnect. */
+export interface ConversationMessageDeletedEvent extends DurableEventBase {
+  event: "message_deleted";
+  messageId: string;
+  seq: number;
+  tombstoned?: boolean;
+}
+
+/** The bounded replay batch filled before reaching the live head — the
+ *  server ends the stream after this. Reconnect immediately with
+ *  `Last-Event-ID: nextAfterSeq` (no backoff). */
+export interface ConversationReplayContinueEvent {
+  event: "replay.continue";
+  nextAfterSeq: number;
+}
+
+/** Live-only turn-machine state (ADR-0037 §6): `running` = a claim is held
+ *  and a turn is executing; `queued` = a send coalesced behind the in-flight
+ *  turn (owed work — answered by its release loop); `idle` = nothing owed. */
+export interface ConversationTurnStateEvent {
+  event: "turn_state";
+  conversationId: string;
+  messageId: null;
+  state: "running" | "queued" | "idle";
+  pendingCount: number;
+  at: number;
+  partial: true;
+}
+
+/** One attached surface (a dashboard tab, an `agentc session` TUI process)
+ *  as carried on a `presence` beat. Clients key the roster on `clientId` —
+ *  the same user attached from two surfaces is two entries — and expire an
+ *  entry after the server-declared TTL (`ConversationPresenceSnapshot.ttlMs`). */
+export interface ConversationPresenceClient {
+  clientId: string;
+  userId: string | null;
+  /** The attaching user's display name (null for key callers with no
+   *  user binding). */
+  name: string | null;
+  surface: "dashboard" | "terminal";
+}
+
+/** The conversation agent's executor substrate + liveness, derived fresh
+ *  server-side at emit time: `platform` and `cloud` executors are
+ *  server-resident (always online); `local` is online iff the bridge
+ *  daemon heartbeated within the server's TTL. Null = no agent (a dm). */
+export interface ConversationAgentPresence {
+  executor: "platform" | "local" | "cloud";
+  online: boolean;
+  /** The daemon's machine label (local executor only). */
+  machineName: string | null;
+}
+
+/** Live-only presence beat (ADR-0037 §6, Phase 6): ONE attached client's
+ *  heartbeat + a fresh agent-liveness snapshot. There is deliberately no
+ *  server-side roster — every subscriber assembles it from beats (keyed by
+ *  `clientId`, TTL-expired), the same stateless discipline as the bridge
+ *  daemon's DB heartbeat. Never persisted, never carries an SSE id, never
+ *  advances `Last-Event-ID`. */
+export interface ConversationPresenceEvent {
+  event: "presence";
+  conversationId: string;
+  at: number;
+  partial: true;
+  client: ConversationPresenceClient;
+  agent: ConversationAgentPresence | null;
+}
+
+/** Live-only rail-status frame on a CHANNEL's stream (ADR-0057 Seam 5):
+ *  one ATTACHED session flipped running/idle. `conversationId` is the
+ *  channel; `sessionConversationId` is the session whose turn machine
+ *  moved. Same contract as `turn_state`: never persisted, never carries an
+ *  SSE id, never advances `Last-Event-ID`. Durable rail fields (unread /
+ *  awaiting / failed) refresh via the channel-sessions list, not this. */
+export interface ConversationSessionStatusEvent {
+  event: "session_status";
+  conversationId: string;
+  sessionConversationId: string;
+  state: "running" | "idle";
+  at: number;
+}
+
+export type ConversationStreamEvent =
+  | ConversationPartEvent
+  | ConversationPartPartialEvent
+  | ConversationMessageDoneEvent
+  | ConversationErrorEvent
+  | ConversationReactionEvent
+  | ConversationMessageDeletedEvent
+  | ConversationReplayContinueEvent
+  | ConversationTurnStateEvent
+  | ConversationPresenceEvent
+  | ConversationSessionStatusEvent;
+
+/**
+ * Fold one parsed SSE frame into a `ConversationStreamEvent`.
+ *
+ * Normalizes the two places the wire carries framing metadata:
+ *   - the event name comes from the SSE `event:` field, falling back to the
+ *     data payload's own `event` (replayed rows carry both; `replay.continue`
+ *     carries only the SSE field);
+ *   - `id` is set from the SSE `id:` field when present and positive —
+ *     replayed rows carry it ONLY there, live durable notifies carry it in
+ *     both places (equal), and live-only frames carry a `-1` sentinel inside
+ *     the data which is stripped here. The result is one invariant: `id`
+ *     present ⇔ durable ⇔ may advance `Last-Event-ID`.
+ *
+ * Unknown future event names flow through untyped (cast) — callers using
+ * the discriminated union see them via the default branch, mirroring
+ * `streamRunLogs`.
+ */
+export function normalizeConversationStreamEvent(
+  eventName: string,
+  data: Record<string, unknown>,
+  sseId: number | undefined,
+): ConversationStreamEvent {
+  const name = eventName || (typeof data.event === "string" ? data.event : "message");
+  const dataId = typeof data.id === "number" && Number.isFinite(data.id) ? data.id : undefined;
+  const durableId = sseId !== undefined && Number.isFinite(sseId) && sseId > 0
+    ? sseId
+    : dataId !== undefined && dataId > 0 ? dataId : undefined;
+  const ev: Record<string, unknown> = { ...data, event: name };
+  if (durableId !== undefined) ev.id = durableId;
+  else delete ev.id;
+  return ev as unknown as ConversationStreamEvent;
+}

package/src/types/execution-context.ts

@@ -1,9 +1,9 @@
 /** 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. */
@@ -42,4 +42,12 @@ 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/src/types/protocol.ts

@@ -16,6 +16,17 @@ export interface AgentMessageText extends AgentMessageBase {
   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;
@@ -65,6 +76,26 @@ export interface AgentMessageUsage extends AgentMessageBase {
   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
@@ -83,12 +114,14 @@ export interface AgentMessagePlan extends AgentMessageBase {
 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. */

package/src/types/sandbox-environment.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`.
@@ -34,8 +35,9 @@
  * ```
  */
 
+import { z } from "zod";
 import type { SandboxProvider } from "./sandbox.js";
-import { defineWorkflow } from "./workflow.js";
+import { createStepWorkflow } from "../workflow-steps/workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
 import type { SandboxResources, SnapshotConfig } from "./workflow-metadata.js";
 
@@ -55,24 +57,41 @@ export interface SandboxEnvironmentDefinition {
   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 function defineSandboxEnvironment(
   env: SandboxEnvironmentDefinition,
 ): Workflow<Record<string, unknown>, void> {
   if (typeof env.setup !== "function") {
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
-  return defineWorkflow<void, Record<string, unknown>>({
+  const input  = z.unknown() as z.ZodType<Record<string, unknown>>;
+  const output = z.unknown() as z.ZodType<void>;
+  return createStepWorkflow<Record<string, unknown>, void>({
+    id: env.name,
     ...(env.description !== undefined ? { description: env.description } : {}),
     ...(env.resources !== undefined ? { resources: env.resources } : {}),
+    input,
+    output,
     snapshots: env.snapshots ?? { saveLatest: true },
     // Mark this as an environment build so the server skips the /factory mount
     // for its runs — an env build builds a platform image and never touches the
     // shared drive; baking a live Archil mount into its snapshot breaks the
     // re-mount of every workflow that later boots from it (#13).
     environmentBuild: true,
-    run: async (_ctx, sandbox) => env.setup(sandbox),
-  });
+  })
+    .step({
+      name: "setup",
+      input,
+      output,
+      run: async (ctx) => {
+        const sandbox = ctx.sandbox;
+        if (!sandbox) throw new Error(`defineSandboxEnvironment(${env.name}): setup requires a sandbox in StepContext`);
+        await env.setup(sandbox);
+      },
+    })
+    .build();
 }

package/src/types/sandbox.ts

@@ -78,6 +78,37 @@ export interface SandboxSpawnDuplexOptions {
   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
@@ -122,6 +153,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
@@ -133,6 +175,15 @@ export interface SandboxProvider {
    *  be omitted when the provider doesn't expose it; the server stores
    *  `null` for missing values rather than estimating. */
   snapshot?(): Promise<{ 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
@@ -143,6 +194,33 @@ export interface SandboxProvider {
    *  flag: providers without native VM-suspend leave it undefined and fall back
    *  to `snapshot()` + re-run. */
   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/src/types/workflow-metadata.ts

@@ -169,6 +169,24 @@ export interface SandboxResources {
   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
@@ -178,20 +196,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
@@ -218,8 +244,8 @@ export interface WorkflowMetadata {
 }
 
 /**
- * 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.
@@ -242,6 +268,7 @@ export function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMeta
   if (source.outputSchema  !== undefined) out.outputSchema  = freezeMetadataValue(source.outputSchema);
   if (source.snapshots     !== undefined) out.snapshots     = Object.freeze({ ...source.snapshots });
   if (source.resources     !== undefined) out.resources     = Object.freeze({ ...source.resources });
+  if (source.mergePolicy   !== undefined) out.mergePolicy   = source.mergePolicy;
   if (source.processors    !== undefined) out.processors    = Object.freeze([...source.processors]);
   if (source.connectors        !== undefined) out.connectors        = freezeMetadataValue(source.connectors);
   if (source.connectorOperation !== undefined) out.connectorOperation = Object.freeze({ ...source.connectorOperation });

package/src/types/workflow-plan.ts

@@ -10,9 +10,20 @@
  * 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 {