@agent-compose/sdk 0.7.0 → 0.8.1

package/dist/types/conversation-stream.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 declare function normalizeConversationStreamEvent(eventName: string, data: Record<string, unknown>, sseId: number | undefined): ConversationStreamEvent;
+export {};

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;
@@ -21,6 +31,12 @@ export interface AgentMessageToolUse extends AgentMessageBase {
     toolName: string;
     toolInput: Record<string, unknown>;
     toolUseId: string;
+    /** The spawning subagent call's tool_use id when this call ran INSIDE a
+     *  subagent (claude stream-json stamps `parent_tool_use_id` on every
+     *  sidechain event) — lets renderers nest child activity under the
+     *  Agent/Task call instead of flattening it into the parent transcript.
+     *  Optional and additive: producers without sidechains omit it. */
+    parentToolUseId?: string;
 }
 export interface AgentMessageToolResult extends AgentMessageBase {
     type: "tool_result";
@@ -44,6 +60,8 @@ export interface AgentMessageToolResult extends AgentMessageBase {
         path: string;
         line?: number;
     }[];
+    /** Sidechain attribution, mirroring AgentMessageToolUse.parentToolUseId. */
+    parentToolUseId?: string;
 }
 export interface AgentMessageDone extends AgentMessageBase {
     type: "done";
@@ -62,6 +80,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 +113,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
@@ -118,10 +150,12 @@ export interface SandboxProvider {
          *  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"). This is what lets `launchStep`
-         *  recover the full logs + result after a live-stream fault. OPTIONAL —
-         *  implemented where durable file-readback is needed (E2B, local); providers
-         *  that never drive the recovery path (Vercel — foreground only) may omit it. */
+         *  ("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>;
@@ -137,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
@@ -149,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
@@ -206,10 +231,18 @@ export interface WorkflowMetadata {
      *  canonical metadata hash (frozen-metadata rule), so existing workflows are
      *  not forced to re-register. */
     environmentBuild?: boolean;
+    /** Whether this workflow's runs need the factory drive. ABSENT ⇒
+     *  `"required"`: on a drive-backed factory the server treats the /factory
+     *  mount as load-bearing — a mount failure FAILS the run instead of
+     *  silently proceeding drive-less. Declare `"none"` for a workflow that
+     *  genuinely never touches /factory: the server skips the mount entirely
+     *  for its runs (the explicit no-drive mode; there is no silent degrade).
+     *  Optional + additive (frozen-metadata rule). */
+    factoryDrive?: "required" | "none";
 }
 /**
- * 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[];