@agent-compose/sdk 0.5.0 → 0.5.2

package/src/tools/coding.ts

@@ -10,6 +10,13 @@ function resolvePath(path: string, cwd?: string): string {
   return cwd && !isAbsolute(path) ? join(cwd, path) : path;
 }
 
+function formatCommandFailure(command: string, result: { exitCode: number; stdout: string; stderr: string }): string {
+  const parts = [`Command failed with exit code ${result.exitCode}: ${command}`];
+  if (result.stderr.trim()) parts.push(`stderr:\n${result.stderr}`);
+  if (result.stdout.trim()) parts.push(`stdout:\n${result.stdout}`);
+  return parts.join("\n");
+}
+
 async function readFile(sandbox: SandboxProvider, path: string, opts?: { offset?: number; limit?: number; cwd?: string }): Promise<string> {
   const script = `
 const fs = require("fs");
@@ -26,14 +33,18 @@ for (let i = start; i <= end; i++) console.log(String(i) + ": " + lines[i - 1]);
     .filter(Boolean)
     .map(q)
     .join(" ");
-  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${args}`, { cwd: opts?.cwd, timeoutMs: 30_000 });
-  return stdout;
+  const command = `node -e ${q(script)} ${args}`;
+  const result = await sandbox.commands.run(command, { cwd: opts?.cwd, timeoutMs: 30_000 });
+  if (result.exitCode !== 0) throw new Error(formatCommandFailure(command, result));
+  return result.stdout;
 }
 
 async function readRawFile(sandbox: SandboxProvider, path: string, cwd?: string): Promise<string> {
   const script = `const fs = require("fs"); process.stdout.write(fs.readFileSync(process.argv[1], "utf8"));`;
-  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${q(path)}`, { cwd, timeoutMs: 30_000 });
-  return stdout;
+  const command = `node -e ${q(script)} ${q(path)}`;
+  const result = await sandbox.commands.run(command, { cwd, timeoutMs: 30_000 });
+  if (result.exitCode !== 0) throw new Error(formatCommandFailure(command, result));
+  return result.stdout;
 }
 
 export interface CodingTool<TInput extends Record<string, unknown> = Record<string, unknown>> {
@@ -118,7 +129,7 @@ export const bashTool: CodingTool<{
       cwd: cwd ?? ctx.cwd,
       timeoutMs: timeoutMs ?? 120_000,
     });
-    if (result.exitCode !== 0) throw new Error(`Command failed with exit code ${result.exitCode}${result.stdout ? `\n${result.stdout}` : ""}`);
+    if (result.exitCode !== 0) throw new Error(formatCommandFailure(command, result));
     return result.stdout;
   },
 };

package/src/types/events.ts

@@ -15,6 +15,15 @@ export type RunEvent =
       seq?: number;
       agentId: string;
       label: string;
+      /** Tool whitelist passed to `agent({ tools: [...] })`. Drives the
+       *  per-agent "tools" badge on the dashboard. */
+      allowedTools?: string[];
+      /** Resolved model id (e.g. `claude-sonnet-4-6`). */
+      model?: string;
+      /** Short runtime self-identifier (`claude`, `openai-desktop`, …)
+       *  read off `ModelExecutionContract.kind`. The dashboard maps
+       *  this to a small runtime icon on the agent card header. */
+      runtimeKind?: string;
     }
   | {
       event: "agent.message";

package/src/types/execution-context.ts

@@ -2,6 +2,8 @@
 
 import type { InvokeAndWaitOptions, RunStatus } from "../client.js";
 import type { RequestContext } from "../request-context/request-context.js";
+import type { PauseRequest } from "../pause/pause-core.js";
+import type { RequestDecisionRequest, WaitForEventRequest } from "../pause/wrappers.js";
 import type { SandboxProvider } from "./sandbox.js";
 
 /** The identity of this workflow run. */
@@ -27,4 +29,27 @@ export interface BaseExecutionContext {
   setMetadata?: (data: Record<string, unknown>) => Promise<void>;
   /** Invoke another registered workflow and wait for it to settle. */
   invokeChild: InvokeChild;
+  /**
+   * Disk-backed memoise across pause-resume. First call runs `fn` and
+   * atomically writes the result to the sandbox; on resume the recorded
+   * value is returned and `fn` is NOT re-executed. Use for expensive
+   * deterministic transforms; for side effects, use `invokeChild`.
+   * See ADR-0006 §"`ctx.checkpoint(name, fn)` — disk-backed memoisation".
+   */
+  checkpoint<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+  /**
+   * Pause for feedback. The step exits and the workflow waits durably until
+   * something resolves the pause (a resume call, a TTL expiry); on resume the
+   * step body re-runs from the top and this call returns the resume payload.
+   * Provide a `schema` to validate the payload, `ttlMs` + `onExpiry` to bound
+   * the wait, `correlationKey` for by-key resume. Throws PauseRequestError /
+   * PauseExpiredError / PauseSchemaError. See ADR-0006 / ADR-0011.
+   */
+  pause<T = unknown>(req: PauseRequest<T>): Promise<T>;
+  /** Pause for a typed decision (a `schema` is required). Wrapper over `pause`. */
+  requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T>;
+  /** Lightweight timed pause — resolves after `durationMs`, no snapshot. */
+  sleep(durationMs: number): Promise<void>;
+  /** Pause until an event resumes by `correlationKey`. Wrapper over `pause`. */
+  waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
 }

package/src/types/protocol.ts

@@ -71,4 +71,12 @@ export interface AgentStatus {
   completed: string[];
   blockers: string[];
   exit_signal: boolean;
+  /** PR 7 self-pause (honoured only for `mode: "hitl"` agents). The agent
+   *  cannot proceed without a human decision: it sets this true, puts the
+   *  question in `question`, and ends its turn. The loop pauses at the next
+   *  boundary and injects the human's answer as the next turn. `auto` agents
+   *  ignore it and keep going. Should be paired with `exit_signal: false`. */
+  needs_input?: boolean;
+  /** The question to put to the human when `needs_input` is true. */
+  question?: string;
 }

package/src/types/runtime.ts

@@ -48,14 +48,66 @@ export type ToolCallGateResult =
 export interface ModelExecutionContract {
   /** True when this runtime can run `processToolCall` before tool execution. */
   supportsToolCallProcessor?: boolean;
+  /** Short self-identifier ("claude", "openai-desktop", "vercel", …). Read
+   *  by the agent loop and surfaced on `agent.spawned` so the dashboard
+   *  can show a per-agent runtime icon without re-fetching template
+   *  metadata. Optional — runtimes that omit it stay anonymous. */
+  kind?: string;
+  /** Resolved model id used by this runtime instance (already merged with
+   *  config + runtime defaults). Surfaced on `agent.spawned` so each
+   *  agent card on the Agent tab can label which model it ran against. */
+  model?: string;
   /** Runtime-owned pre-tool gate. Adapters call the shared processor chain
    *  through this seam; the agent loop stays SDK-agnostic. */
   gateToolCall?(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult>;
+  /**
+   * Capture runtime-private in-memory state that will not survive the
+   * runner subprocess exit. Called by the agent loop at pause time,
+   * AFTER the loop has flushed its own state to disk.
+   *
+   * Return value is opaque to the loop — whatever the runtime needs to
+   * round-trip its conversation across pause-resume. Must be JSON-
+   * serialisable; the loop atomically writes it to
+   * `/tmp/wf/state/runtime-<agentInstanceId>.json` and reads it back
+   * on resume to hand to `restoreCheckpoint`.
+   *
+   * Default (method omitted): runtime holds no instance state that
+   * needs to round-trip across pause. The shipped example is the
+   * Claude runtime — the conversation lives server-side at
+   * Anthropic, addressed by `session_id`, and the loop already holds
+   * `lastSessionId` as part of its own state. On resume the loop
+   * restores the id, the next `sendMessage` passes it through, and
+   * Anthropic resumes the server-side conversation.
+   *
+   * Runtimes that hold the conversation in-process — Vercel's
+   * `VercelRunner.messages` is the canonical case — MUST implement
+   * both hooks: the messages array is reconstructed from
+   * `response.messages` on each `streamText` and would be lost the
+   * moment the subprocess exits. See ADR-0006 §"Concrete examples
+   * for shipped runtimes" for the audit + worked examples.
+   */
+  captureCheckpoint?(): unknown;
+  /**
+   * Restore runtime-private state previously returned by
+   * `captureCheckpoint`. Called by the agent loop on resume, AFTER
+   * the loop has restored its own state but BEFORE iterations resume.
+   *
+   * `blob` is whatever this same runtime returned at pause time. If
+   * `captureCheckpoint` is omitted, this is never called.
+   */
+  restoreCheckpoint?(blob: unknown): void;
   sendMessage(opts: {
     prompt: string;
     sessionId?: string;
     iteration?: number;
     signal?: AbortSignal;
+    /** Push-iterable of mid-turn user messages from outside the agent
+     *  loop — e.g. dashboard chat injections. Runtimes that support
+     *  streaming-input mode (Claude Agent SDK) read from this in
+     *  parallel with the initial `prompt`; the SDK handles delivery
+     *  at the next safe boundary. Runtimes without streaming-input
+     *  support ignore this and fall back to per-iteration injection. */
+    inboxStream?: AsyncIterable<{ text: string; senderName?: string | null }>;
   }): AsyncGenerator<AgentMessage>;
 }
 

package/src/types/sandbox.ts

@@ -10,12 +10,17 @@ export interface SandboxCommandRunOptions {
   envs?: Record<string, string>;
   onStdout?: (data: string) => void;
   onStderr?: (data: string) => void;
-  background?: boolean;
+  /** Run the command with root privileges. Vercel maps this to its native
+   *  `sudo` flag; the local provider prepends `sudo`. Defaults to false.
+   *  Requires the sandbox image to grant the command root (Vercel's runtimes
+   *  do — passwordless). */
+  sudo?: boolean;
 }
 
 export interface SandboxCommandResult {
   exitCode: number;
   stdout: string;
+  stderr: string;
 }
 
 export interface SandboxProvider {
@@ -23,6 +28,10 @@ export interface SandboxProvider {
   /** Working directory for the agent process. Set by onStart after environment setup. */
   cwd?: string;
   commands: {
+    // NOTE: does NOT throw on non-zero exit. Callers must check
+    // `result.exitCode` themselves. The `agent-env` setup workflow's
+    // `run(sb, cmd)` helper is the canonical pattern — copy it into any
+    // setup workflow that needs to fail loudly on command errors.
     run(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxCommandResult>;
   };
   files: {

package/src/types/workflow.ts

@@ -210,7 +210,12 @@ function compileRunForm<TOutput, TInput extends Record<string, unknown>>(
         setMetadata:    stepCtx.setMetadata,
         step:           stepCtx.step,
         agentEvents:    stepCtx.agentEvents,
-        processors:     metadata.processors ?? [],
+        checkpoint:      stepCtx.checkpoint,
+        pause:           stepCtx.pause,
+        requestDecision: stepCtx.requestDecision,
+        sleep:           stepCtx.sleep,
+        waitForEvent:    stepCtx.waitForEvent,
+        processors:      metadata.processors ?? [],
       };
       const sandbox = stepCtx.sandbox;
       if (!sandbox) throw new Error("legacy run-form workflow requires a sandbox in StepContext");

package/src/utils/bundler.ts

@@ -111,8 +111,9 @@ async function bundle(path: string, label: string): Promise<string> {
 }
 
 /** Dynamically import a bundled source in-process and extract fields from its
- *  default export. Safe for CLI/test contexts. Returns `undefined` on
- *  resolver failure (missing deps) so callers fall through. */
+ *  default export. Safe for CLI/test contexts. Evaluation failures are
+ *  surfaced with their original cause so users fix the real import/runtime
+ *  problem instead of being told the default export shape is wrong. */
 async function extractFromBundle<T>(
   source: string,
   label: string,
@@ -123,7 +124,11 @@ async function extractFromBundle<T>(
     const loaded = await importSourceModule<Record<string, unknown>>(source, tmpPath);
     try { return pick(loaded.mod.default); }
     finally { await loaded.cleanup(); }
-  } catch { return undefined; }
+  } catch (err) {
+    throw new WorkflowSourceValidationError(
+      `Bundled ${label} could not be evaluated: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
 }
 
 /**

package/src/utils/schemas.ts

@@ -7,4 +7,6 @@ export const AgentStatusSchema = z.object({
   completed:    z.array(z.string()),
   blockers:     z.array(z.string()),
   exit_signal:  z.boolean(),
+  needs_input:  z.boolean().optional(),
+  question:     z.string().optional(),
 }) satisfies z.ZodType<AgentStatus>;

package/src/workflow-steps/index.ts

@@ -28,3 +28,6 @@ export { WORKFLOW_BRAND } from "./types.js";
 
 export { StepObservabilityCollector } from "./observability.js";
 export type { StepObservability, SubStepEvent } from "./observability.js";
+
+export { makeRunCallbackEmitterFromEnv } from "./run-callback.js";
+export type { LiveAgentEventEmitter } from "./run-callback.js";

package/src/workflow-steps/observability.ts

@@ -5,19 +5,34 @@
  * tokenised stdout sentinel; the activity persists the snapshot to the
  * run's metadata + lifecycle event tables.
  *
- * STREAMING — known gap. `agentEvents` are currently batched at step
- * end. For long-running steps that emit many agent events, this hides
- * progress from the dashboard until the step completes. The follow-up
- * is to bring back a minimal `/internal/runs/:runId/steps/:stepIndex/events`
- * route gated by a per-step JIT-signed token (mint in the activity,
- * stamp into the runner env, verify on receive) so `agentEvents.emit`
- * POSTs in real time. Until then `metadata` and `subSteps` are
- * effectively boundary events (no streaming need) and batching them
- * matches their natural granularity.
+ * Live streaming + batch backstop — the no-double-write design:
+ *
+ *   1. `agentEvents.emit` immediately fires the optional `liveEmitter`
+ *      (the runner's POST to `/internal/runs/.../events`).
+ *   2. The emitter returns `Promise<boolean>` — true means the server
+ *      accepted and persisted this event, false means it failed (POST
+ *      error, server 5xx, network blip).
+ *   3. The collector tracks which seqs were successfully ack'd.
+ *   4. At `snapshot()` time we await any in-flight emits (with a small
+ *      grace window so the agent loop's final-burst posts can finish),
+ *      then STRIP ack'd events from the returned `events` array.
+ *
+ *   The result: the snapshot's `events` array only contains events
+ *   that the live path didn't successfully deliver. The server's
+ *   batch-flush in `persistStepObservability` becomes a true backstop
+ *   for the FAILURE path — it never re-writes (and never re-notifies)
+ *   the events the live route already handled. No double pg_notify,
+ *   no dashboard duplicates.
+ *
+ *   `metadata` and `subSteps` remain batch-only because they're
+ *   naturally boundary events (no streaming benefit) and aren't
+ *   written by the live route at all.
  */
 
 import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
 import type { AgentEventSink } from "../types/workflow.js";
+import type { LiveAgentEventEmitter } from "./run-callback.js";
+import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 
 /** One named sub-step (from `ctx.step("name", async () => ...)`).
  *  Becomes a `workflow_substep_*` lifecycle event on the run timeline. */
@@ -39,6 +54,13 @@ export interface StepObservability {
   subSteps?: SubStepEvent[];
 }
 
+/** Maximum time we'll wait for in-flight live-emit POSTs to settle
+ *  before taking the snapshot. Tuned to be longer than a healthy POST
+ *  (~50ms) but short enough that a totally-broken live path doesn't
+ *  block step return — the batch backstop will handle whatever doesn't
+ *  resolve in time. */
+const LIVE_EMIT_DRAIN_TIMEOUT_MS = 1_500;
+
 /**
  * Append-only collector bound to a single step's `StepContext`. The
  * step's `setMetadata` / `step` / `agentEvents` properties all point at
@@ -53,6 +75,15 @@ export class StepObservabilityCollector {
   private metadata: Record<string, unknown> = {};
   private events:   AgentLifecycleEvent[]   = [];
   private subSteps: SubStepEvent[]          = [];
+  private readonly liveEmitter?: LiveAgentEventEmitter;
+  /** Seqs of events the server confirmed via the live route. */
+  private readonly ackedSeqs: Set<number> = new Set();
+  /** Promises for in-flight live emits — awaited at snapshot time. */
+  private readonly inFlight: Set<Promise<void>> = new Set();
+
+  constructor(opts: { liveEmitter?: LiveAgentEventEmitter } = {}) {
+    this.liveEmitter = opts.liveEmitter;
+  }
 
   readonly setMetadata = async (data: Record<string, unknown>): Promise<void> => {
     Object.assign(this.metadata, data);
@@ -70,6 +101,9 @@ export class StepObservabilityCollector {
       });
       return result;
     } catch (err) {
+      // A pause inside ctx.step is control flow, not a failed sub-step — let
+      // it propagate untouched so serveStep emits the pause sentinel.
+      if (isPauseSignal(err)) throw err;
       this.subSteps.push({
         name,
         startedAt,
@@ -83,20 +117,57 @@ export class StepObservabilityCollector {
 
   readonly agentEvents: AgentEventSink = {
     emit: (event: AgentLifecycleEvent) => {
+      // `seq` is the event's index in `events`, captured BEFORE push so
+      // it matches the index the server-side batch flush uses (its
+      // `.entries()` loop). Same index → same idempotency key on the
+      // server. The live route's `acceptedSeqs` response uses this seq;
+      // we strip those from the snapshot in `snapshot()`.
+      const seq = this.events.length;
       this.events.push(event);
+      if (this.liveEmitter) {
+        const tracked = this.liveEmitter(event, seq)
+          .then((ok) => { if (ok) this.ackedSeqs.add(seq); })
+          .catch(() => { /* leave unacked → batch backstop delivers */ });
+        this.inFlight.add(tracked);
+        // Self-clean so completed promises don't leak across long-
+        // running steps.
+        void tracked.finally(() => this.inFlight.delete(tracked));
+      }
     },
   };
 
+  /** Wait for in-flight live emits to settle (or timeout) so the
+   *  ackedSeqs set is maximally up-to-date before we filter. Used by
+   *  `snapshot()` — exposed separately for tests. */
+  private async drainInFlight(timeoutMs = LIVE_EMIT_DRAIN_TIMEOUT_MS): Promise<void> {
+    if (this.inFlight.size === 0) return;
+    await Promise.race([
+      Promise.allSettled([...this.inFlight]),
+      new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+  }
+
   /** Snapshot the accumulated state. Returns `undefined` when nothing
-   *  was recorded so the wire payload can drop the field entirely. */
-  snapshot(): StepObservability | undefined {
+   *  was recorded so the wire payload can drop the field entirely.
+   *
+   *  Async because we drain in-flight live emits first. Any event the
+   *  server acknowledged is REMOVED from the returned `events` array
+   *  so the server-side batch flush doesn't re-write/re-notify it.
+   *  Events that failed live delivery (POST error, timeout) stay in
+   *  the array as the durable backstop. */
+  async snapshot(): Promise<StepObservability | undefined> {
+    await this.drainInFlight();
+
     const hasMetadata = Object.keys(this.metadata).length > 0;
-    const hasEvents   = this.events.length > 0;
     const hasSubSteps = this.subSteps.length > 0;
+    // Filter out ack'd events — the live route already wrote them.
+    const remainingEvents = this.events.filter((_, idx) => !this.ackedSeqs.has(idx));
+    const hasEvents = remainingEvents.length > 0;
+
     if (!hasMetadata && !hasEvents && !hasSubSteps) return undefined;
     const result: StepObservability = {};
     if (hasMetadata) result.metadata = { ...this.metadata };
-    if (hasEvents)   result.events   = [...this.events];
+    if (hasEvents)   result.events   = remainingEvents;
     if (hasSubSteps) result.subSteps = [...this.subSteps];
     return result;
   }

package/src/workflow-steps/run-callback.ts

@@ -0,0 +1,72 @@
+/**
+ * Runner → server live event emitter.
+ *
+ * Pairs with the server-side `/api/v1/internal/runs/:runId/steps/:stepIndex/events`
+ * route. The runner reads `AGENT_COMPOSE_URL`, `AGENT_COMPOSE_RUN_TOKEN`,
+ * and `RUN_ID` from env; if all three are present it builds a POST
+ * function that sends each agent lifecycle event to the server as
+ * soon as the agent loop emits it.
+ *
+ * Non-blocking: the agent loop doesn't await the emitter — the runtime
+ * keeps emitting events at full speed. But the emitter still returns a
+ * `Promise<boolean>` so the collector can later decide whether to
+ * include each event in the batch-end durable backstop. `true` = server
+ * accepted the event (don't re-deliver in batch); `false` = POST
+ * failed (DO re-deliver). The collector awaits these promises with a
+ * short grace window at snapshot time.
+ *
+ * This is the seam that lets us avoid the double-write problem: every
+ * successfully-ack'd live event is stripped from `observability.events`
+ * before the batch flush runs, so the durable backstop only carries
+ * events that genuinely failed live delivery. No more two paths writing
+ * the same row + double pg_notify.
+ */
+
+import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
+
+export type LiveAgentEventEmitter =
+  (event: AgentLifecycleEvent, seq: number) => Promise<boolean>;
+
+/**
+ * Build a live emitter from process env + the caller-supplied stepIndex.
+ * Returns `undefined` when any required env var is missing (local tests,
+ * non-sandbox callers) so the caller can wire `undefined` straight
+ * through to the collector and get batch-only delivery without
+ * conditional plumbing.
+ *
+ * `stepIndex` is a parameter rather than an env read because
+ * `serveStep` scrubs `AC_STEP_INDEX` from `process.env` before invoking
+ * the workflow handler (to keep the transport envelope unreachable
+ * from user code); the handler still holds the parsed integer and
+ * passes it here.
+ */
+export function makeRunCallbackEmitterFromEnv(stepIndex: number): LiveAgentEventEmitter | undefined {
+  const baseUrl = process.env.AGENT_COMPOSE_URL;
+  const token   = process.env.AGENT_COMPOSE_RUN_TOKEN;
+  const runId   = process.env.RUN_ID;
+  if (!baseUrl || !token || !runId) return undefined;
+  if (!Number.isFinite(stepIndex) || stepIndex < 0) return undefined;
+  const url = `${baseUrl.replace(/\/+$/, "")}/api/v1/internal/runs/${runId}/steps/${stepIndex}/events`;
+  const headers = {
+    "content-type":  "application/json",
+    "authorization": `Bearer ${token}`,
+  } as const;
+  return async (event, seq) => {
+    try {
+      const res = await fetch(url, {
+        method:  "POST",
+        headers,
+        body:    JSON.stringify({ events: [{ ...event, seq }] }),
+      });
+      if (!res.ok) return false;
+      // Parse the route's response to confirm THIS seq was accepted.
+      // The route returns `{ acceptedSeqs: number[] }`; absence means
+      // the server logged but didn't persist (rare — DB hiccup), and
+      // we should leave the event in the batch backstop.
+      const body = await res.json().catch(() => null) as { acceptedSeqs?: number[] } | null;
+      return Array.isArray(body?.acceptedSeqs) && body.acceptedSeqs.includes(seq);
+    } catch {
+      return false;
+    }
+  };
+}

package/src/workflow-steps/runner.ts

@@ -28,6 +28,12 @@ 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 { StepObservabilityCollector, type StepObservability } from "./observability.js";
+import type { LiveAgentEventEmitter } from "./run-callback.js";
+import { scopedCheckpoint } from "../pause/checkpoint.js";
+import { corePause, PauseSignal, isPauseSignal, type PauseRequest } from "../pause/pause-core.js";
+import type { StepPauseRequest } from "../step-invocation/types.js";
+import { buildPauseWrappers, type PauseFn, type KindedPauseFn } from "../pause/wrappers.js";
+import { runWithActiveStep, setActiveStepBridge, restoreActiveStepBridge } from "../active-step.js";
 
 export class StepValidationError extends Error {
   readonly kind = "step-validation" as const;
@@ -84,6 +90,11 @@ export interface RunWorkflowStepsOpts<TInput, TOutput> {
   onStepStarted?(stepIndex: number, stepName: string): void | Promise<void>;
   /** Child workflow invocation implementation. Defaults to a clear unsupported error. */
   invokeChild?: WorkflowCtx["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
+   *  leave it undefined and get batch-only delivery. */
+  liveAgentEventEmitter?: LiveAgentEventEmitter;
 }
 
 export interface RunWorkflowStepsResult<TOutput> {
@@ -101,6 +112,8 @@ export interface RunWorkflowSingleStepOpts {
   sandbox?:       SandboxProvider;
   abortSignal?:   AbortSignal;
   invokeChild?:   WorkflowCtx["invokeChild"];
+  /** Optional live-stream emitter — see `RunWorkflowStepsOpts.liveAgentEventEmitter`. */
+  liveAgentEventEmitter?: LiveAgentEventEmitter;
 }
 
 /** Result of one step run — output plus whatever the step's observability
@@ -116,7 +129,14 @@ export async function runWorkflowSingleStep(opts: RunWorkflowSingleStepOpts): Pr
   if (!step) throw new Error(`Step index ${opts.stepIndex} not found in workflow "${opts.workflow.id}"`);
   const parsedInput = step.input.safeParse(opts.input);
   if (!parsedInput.success) throw new StepValidationError(step.name, "input", parsedInput.error);
-  const collector = new StepObservabilityCollector();
+  const collector = new StepObservabilityCollector({ liveEmitter: opts.liveAgentEventEmitter });
+  const coord = { runId: opts.run.id, stepIndex: opts.stepIndex };
+  const pauseWithKind: KindedPauseFn = function <T>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]): Promise<T> {
+    return corePause(req, coord, kind);
+  };
+  const pause: PauseFn = function <T>(req: PauseRequest<T>): Promise<T> {
+    return corePause(req, coord);
+  };
   const stepCtx: StepContext<unknown> = {
     input: parsedInput.data,
     requestContext: opts.requestContext,
@@ -128,11 +148,35 @@ export async function runWorkflowSingleStep(opts: RunWorkflowSingleStepOpts): Pr
     setMetadata: collector.setMetadata,
     step:        collector.step,
     agentEvents: collector.agentEvents,
+    checkpoint:  scopedCheckpoint(`step${opts.stepIndex}`),
+    pause,
+    ...buildPauseWrappers(pauseWithKind),
   };
-  const output = await step.run(stepCtx);
+  let output: unknown;
+  try {
+    // Set the active step so `agent()` / `ctx.pause` derive deterministic
+    // ids from the un-scrubbed index (see active-step.ts). Async-local scope
+    // keeps concurrent in-process runs from clobbering each other. ALSO publish
+    // on the cross-instance bridge: a bundled workflow inlines its own SDK copy
+    // (a separate AsyncLocalStorage), so its `agent()` can't see the ALS we set
+    // here — the bridge carries the step across that boundary. One step per
+    // subprocess in the sandbox ⇒ no concurrency on the global slot.
+    const bridged = setActiveStepBridge({ stepIndex: opts.stepIndex });
+    try {
+      output = await runWithActiveStep({ stepIndex: opts.stepIndex }, () => Promise.resolve(step.run(stepCtx)));
+    } finally {
+      restoreActiveStepBridge(bridged);
+    }
+  } catch (err) {
+    if (isPauseSignal(err)) {
+      const observability = await collector.snapshot();
+      throw new PauseSignal(err.pauseId, err.pauseRequest, observability);
+    }
+    throw err;
+  }
   const parsedOutput = step.output.safeParse(output);
   if (!parsedOutput.success) throw new StepValidationError(step.name, "output", parsedOutput.error);
-  const observability = collector.snapshot();
+  const observability = await collector.snapshot();
   return observability === undefined
     ? { output: parsedOutput.data }
     : { output: parsedOutput.data, observability };
@@ -179,7 +223,14 @@ export async function runWorkflowSteps<TInput, TOutput>(
       throw err;
     }
 
-    const collector = new StepObservabilityCollector();
+    const collector = new StepObservabilityCollector({ liveEmitter: opts.liveAgentEventEmitter });
+    const coord = { runId: run.id, stepIndex: i };
+    const pauseWithKind: KindedPauseFn = function <T>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]): Promise<T> {
+      return corePause(req, coord, kind);
+    };
+    const pause: PauseFn = function <T>(req: PauseRequest<T>): Promise<T> {
+      return corePause(req, coord);
+    };
     const stepCtx: StepContext<unknown> = {
       input:          parsedStepInput.data,
       requestContext,
@@ -191,16 +242,27 @@ export async function runWorkflowSteps<TInput, TOutput>(
       setMetadata:    collector.setMetadata,
       step:           collector.step,
       agentEvents:    collector.agentEvents,
+      checkpoint:     scopedCheckpoint(`step${i}`),
+      pause,
+      ...buildPauseWrappers(pauseWithKind),
     };
 
     const startedAt = Date.now();
     let output: unknown;
     try {
-      output = await step.run(stepCtx);
+      // Active step for deterministic agent/pause id derivation (active-step.ts).
+      // Async-local scope keeps concurrent in-process runs isolated.
+      output = await runWithActiveStep({ stepIndex: i }, () => Promise.resolve(step.run(stepCtx)));
     } catch (err) {
+      // A pause is control flow, not a failure — let it propagate so serveStep
+      // emits the pause sentinel instead of recording a failed step.
+      if (isPauseSignal(err)) {
+        const observability = await collector.snapshot();
+        throw new PauseSignal(err.pauseId, err.pauseRequest, observability);
+      }
       const wrapped = err instanceof Error ? err : new Error(String(err));
       const durationMs = Date.now() - startedAt;
-      const observability = collector.snapshot();
+      const observability = await collector.snapshot();
       stepResults.push({
         name: step.name, status: "failed", error: wrapped.message, durationMs,
         ...(observability ? { observability } : {}),
@@ -213,7 +275,7 @@ export async function runWorkflowSteps<TInput, TOutput>(
     if (!parsedOutput.success) {
       const err = new StepValidationError(step.name, "output", parsedOutput.error);
       const durationMs = Date.now() - startedAt;
-      const observability = collector.snapshot();
+      const observability = await collector.snapshot();
       stepResults.push({
         name: step.name, status: "failed", error: err.message, durationMs,
         ...(observability ? { observability } : {}),
@@ -224,7 +286,7 @@ export async function runWorkflowSteps<TInput, TOutput>(
 
     const durationMs = Date.now() - startedAt;
     current = parsedOutput.data;
-    const observability = collector.snapshot();
+    const observability = await collector.snapshot();
     stepResults.push({
       name: step.name, status: "completed", output: parsedOutput.data, durationMs,
       ...(observability ? { observability } : {}),

package/dist/utils/discovery.d.ts

@@ -1,2 +0,0 @@
-/** Find the runtime name referenced via runtime: "name" in workflow source. */
-export declare function discoverRuntimeName(source: string): string | null;

package/src/utils/discovery.ts

@@ -1,4 +0,0 @@
-/** Find the runtime name referenced via runtime: "name" in workflow source. */
-export function discoverRuntimeName(source: string): string | null {
-  return source.match(/runtime:\s*["']([^"']+)["']/)?.[1] ?? null;
-}