@agent-compose/sdk 0.5.0 → 0.5.2

package/dist/runtimes/vercel.d.ts

@@ -23,6 +23,18 @@ export declare class VercelRunner implements ModelExecutionContract {
     private readonly messages;
     constructor(sandbox: SandboxProvider, options: RuntimeOptions, config: VercelRuntimeConfig);
     gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult>;
+    /** ADR-0006 pause-resume hooks. The Vercel AI SDK holds the running
+     *  conversation client-side in `this.messages` — every `streamText`
+     *  call passes the full array as `messages` and reconstructs it from
+     *  `response.messages` after completion. A pause-induced subprocess
+     *  exit loses the array; the new subprocess constructs a fresh
+     *  `VercelRunner` with `this.messages = []` and the next sendMessage
+     *  would see only the current iteration's prompt — conversation
+     *  history broken. The agent loop calls these at every iteration
+     *  boundary so the messages array round-trips through the sandbox
+     *  snapshot. */
+    captureCheckpoint(): unknown;
+    restoreCheckpoint(blob: unknown): void;
     private buildTools;
     sendMessage(opts: {
         prompt: string;

package/dist/runtimes/vercel.js

@@ -36,6 +36,17 @@ function q(value) {
 function resolvePath(path, cwd) {
   return cwd && !isAbsolute(path) ? join(cwd, path) : path;
 }
+function formatCommandFailure(command, result) {
+  const parts = [`Command failed with exit code ${result.exitCode}: ${command}`];
+  if (result.stderr.trim())
+    parts.push(`stderr:
+${result.stderr}`);
+  if (result.stdout.trim())
+    parts.push(`stdout:
+${result.stdout}`);
+  return parts.join(`
+`);
+}
 async function readFile(sandbox, path, opts) {
   const script = `
 const fs = require("fs");
@@ -49,13 +60,19 @@ const end = Math.min(lines.length, start + Math.max(0, limit) - 1);
 for (let i = start; i <= end; i++) console.log(String(i) + ": " + lines[i - 1]);
 `;
   const args = [q(path), opts?.offset !== undefined ? String(opts.offset) : "", opts?.limit !== undefined ? String(opts.limit) : ""].filter(Boolean).map(q).join(" ");
-  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${args}`, { cwd: opts?.cwd, timeoutMs: 30000 });
-  return stdout;
+  const command = `node -e ${q(script)} ${args}`;
+  const result = await sandbox.commands.run(command, { cwd: opts?.cwd, timeoutMs: 30000 });
+  if (result.exitCode !== 0)
+    throw new Error(formatCommandFailure(command, result));
+  return result.stdout;
 }
 async function readRawFile(sandbox, path, cwd) {
   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: 30000 });
-  return stdout;
+  const command = `node -e ${q(script)} ${q(path)}`;
+  const result = await sandbox.commands.run(command, { cwd, timeoutMs: 30000 });
+  if (result.exitCode !== 0)
+    throw new Error(formatCommandFailure(command, result));
+  return result.stdout;
 }
 var readTool = {
   name: "Read",
@@ -116,8 +133,7 @@ var bashTool = {
       timeoutMs: timeoutMs ?? 120000
     });
     if (result.exitCode !== 0)
-      throw new Error(`Command failed with exit code ${result.exitCode}${result.stdout ? `
-${result.stdout}` : ""}`);
+      throw new Error(formatCommandFailure(command, result));
     return result.stdout;
   }
 };
@@ -138,6 +154,7 @@ async function runProcessorChain(processors, selectHook, initial, ctx) {
 }
 
 // src/request-context/request-context.ts
+import { z as z2 } from "zod";
 var AC_RESERVED_PREFIX = "ac__";
 var AC_TEAM_ID = "ac__teamId";
 var AC_RUN_ID = "ac__runId";
@@ -163,6 +180,17 @@ var SERIALISABLE_RESERVED_KEYS = new Set([
   AC_API_KEY_SCOPES,
   AC_PARENT_RUN_ID
 ]);
+var RequestContextWireSchema = z2.object({
+  reserved: z2.object({
+    teamId: z2.string(),
+    runId: z2.string(),
+    workflowId: z2.string(),
+    factoryId: z2.string().nullable(),
+    apiKeyScopes: z2.array(z2.string()).readonly(),
+    parentRunId: z2.string().nullable()
+  }),
+  user: z2.record(z2.string(), z2.unknown())
+});
 
 class ReservedKeyError extends Error {
   key;
@@ -224,7 +252,8 @@ class RequestContext {
     return new RequestContext(reserved, new Map);
   }
   static deserialise(wire) {
-    const ctx = new RequestContext({ ...wire.reserved, abortSignal: undefined }, new Map(Object.entries(wire.user)));
+    const parsed = RequestContextWireSchema.parse(wire);
+    const ctx = new RequestContext({ ...parsed.reserved, abortSignal: undefined }, new Map(Object.entries(parsed.user)));
     return ctx;
   }
   withAbortSignal(signal) {
@@ -372,6 +401,20 @@ class VercelRunner {
       return { kind: "allow", call: verdict.value };
     return verdict;
   }
+  captureCheckpoint() {
+    return { messages: [...this.messages] };
+  }
+  restoreCheckpoint(blob) {
+    if (!blob || typeof blob !== "object") {
+      throw new Error("Vercel runtime checkpoint is invalid: expected an object with messages[]");
+    }
+    const incoming = blob.messages;
+    if (!Array.isArray(incoming)) {
+      throw new Error("Vercel runtime checkpoint is invalid: expected messages[]");
+    }
+    this.messages.length = 0;
+    this.messages.push(...incoming);
+  }
   buildTools(iteration, signal) {
     const set = {};
     for (const t of this.tools) {

package/dist/runtimes/vercel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sse.d.ts

@@ -7,9 +7,8 @@
  *   - `event`: event name (from `event:` line; `""` if absent)
  *   - `data`:  parsed JSON payload (the SDK's stream events are always JSON)
  *
- * Malformed payloads are silently skipped — same behaviour as the previous
- * CLI-side parser. Caller drives the loop via `for await (...)` and is
- * responsible for breaking on terminal events.
+ * Malformed payloads throw. A dropped terminal event is worse than a loud
+ * protocol error for log consumers.
  *
  * Output type stays loose (`Record<string, unknown>`) on purpose: typed
  * unions like `RunEvent` aren't structurally narrowable from

package/dist/step-invocation/index.d.ts

@@ -17,9 +17,9 @@
  * file + one tokenised stdout result line. Easy to reason about, easy
  * to test in isolation.
  */
-export { STEP_RESULT_PREFIX, STEP_ENV, RUNNER_BUNDLE_PATH, RUNNER_COMMAND, stepInputPath, requestContextPath, } from "./protocol.js";
+export { STEP_RESULT_PREFIX, STEP_PAUSE_PREFIX, STEP_ENV, RUNNER_BUNDLE_PATH, RUNNER_COMMAND, stepInputPath, requestContextPath, } from "./protocol.js";
 export { invokeStep, parseStepResult, buildStepEnvs } from "./invoker.js";
 export { serveStep } from "./server.js";
 export type { StepHandler, ServeStepRequest, StepHandlerResult } from "./server.js";
 export { StepExecutionError } from "./types.js";
-export type { StepRequest, StepResult, StepInvocationError } from "./types.js";
+export type { StepRequest, StepResult, StepInvocationError, StepPauseRequest } from "./types.js";

package/dist/step-invocation/invoker.d.ts

@@ -30,6 +30,7 @@ export declare function buildStepEnvs(args: {
     runId: string;
     stepIndex: number;
     resultToken: string;
+    isResume?: boolean;
 }): Record<string, string>;
 /** Scan the runner's stdout for the tokenised sentinel line and return a
  *  classified result. Returns `null` when no sentinel is present — the
@@ -51,6 +52,8 @@ export declare function parseStepResult<TOutput = unknown>(stdout: string, resul
  */
 export interface InvokeStepOptions {
     envs?: Record<string, string>;
+    /** True when re-entering a step after resolving or expiring a pause. */
+    isResume?: boolean;
     /** Live stdout / stderr from the runner subprocess, line-by-line. Called
      *  from inside `sandbox.commands.run` as chunks arrive. The sentinel line
      *  carrying the protocol result token is filtered out before delivery so

package/dist/step-invocation/protocol.d.ts

@@ -12,12 +12,23 @@
  *  invoker scans for `<prefix><token>:<json>` so any user `console.log`
  *  with the same prefix but a wrong token is rejected. */
 export declare const STEP_RESULT_PREFIX = "__AC_STEP_RESULT__";
+/** Parallel sentinel for pause requests. The runner emits this — instead
+ *  of (not in addition to) a step result — when user code calls
+ *  `ctx.pause(...)`. Exits cleanly afterwards so the activity can snapshot
+ *  the now-frozen sandbox and durably wait via Temporal `condition()`.
+ *  See ADR-0006 §"How it actually pauses — Temporal-native, end-to-end". */
+export declare const STEP_PAUSE_PREFIX = "__AC_STEP_PAUSE__";
 /** Build the line prefix the runner emits and the invoker scans for. The
  *  runner-side serveStep writes `<prefix><token>:<json>\n`; the invoker's
  *  result parser AND the stdout line splitter both match on this exact
  *  prefix so a future change can't make them drift (review found a
  *  separator mismatch that leaked the sentinel into captured logs). */
 export declare function stepResultLinePrefix(token: string): string;
+/** Build the pause sentinel line prefix. Same per-invocation token as the
+ *  result sentinel so the two channels share one secret — a user
+ *  `console.log` can't forge either without knowing the token, and the
+ *  invoker can filter both prefixes from captured stdout with one token. */
+export declare function stepPauseLinePrefix(token: string): string;
 /** Sandbox-side path where dispatch writes the compiled runner bundle.
  *  Both modes (full-mode `dispatch.ts` and step-mode `invokeStep`) spawn
  *  the runner from this path; single source of truth. */
@@ -34,6 +45,7 @@ export declare const STEP_ENV: {
     readonly STEP_INPUT_PATH: "AC_STEP_INPUT_PATH";
     readonly REQUEST_CONTEXT_PATH: "AC_REQUEST_CONTEXT_PATH";
     readonly STEP_RESULT_TOKEN: "AC_STEP_RESULT_TOKEN";
+    readonly STEP_RESUME: "AC_STEP_RESUME";
 };
 /** Sandbox-side path where the invoker writes the JSON-encoded step input.
  *  The serveStep reads from this exact path; both halves use this helper. */

package/dist/step-invocation/server.d.ts

@@ -27,6 +27,7 @@ import type { StepObservability } from "../workflow-steps/observability.js";
 export interface ServeStepRequest<TInput = unknown> {
     runId: string;
     stepIndex: number;
+    isResume: boolean;
     input: TInput;
     requestContext: RequestContextWire;
 }

package/dist/step-invocation/types.d.ts

@@ -2,6 +2,7 @@
  * StepInvocation public types — what callers (the activity) get back, and
  * the discriminated error union that classifies failure modes.
  */
+import { z } from "zod";
 import type { RequestContextWire } from "../request-context/request-context.js";
 import type { StepObservability } from "../workflow-steps/observability.js";
 /** What the invoker needs to drive one step invocation. The step's
@@ -16,20 +17,54 @@ export interface StepRequest<TInput = unknown> {
     requestContext: RequestContextWire;
 }
 /**
- * Outcome of one step invocation. Successful runs carry the step's output;
- * failed runs carry a kinded error so the caller can distinguish "user
- * code threw" from "runner crashed before emitting" from "wire protocol
- * violation". The dashboard surfaces the kind to operators; the activity
- * uses the kind to pick a useful failRun reason.
+ * Outcome of one step invocation. Three terminal states:
+ *
+ * - `ok: true` — step body resolved with `output`.
+ * - `ok: false` — step body or runner errored; kind classifies why.
+ * - `ok: "paused"` — step body called `ctx.pause(...)` and exited cleanly.
+ *   The activity captures a sandbox snapshot and the workflow waits on
+ *   Temporal `condition()` until something resumes the pause (HTTP
+ *   resume route, TTL expiry, cancellation). `pauseRequest` is what the
+ *   caller passed to `ctx.pause` — the route surfaces it on the
+ *   pending-pauses dashboard so an operator sees the question being
+ *   asked. `observability` carries any ctx metadata/sub-step/agent events
+ *   recorded before the pause unwound. See ADR-0006.
  */
 export type StepResult<TOutput = unknown> = {
     ok: true;
     output: TOutput;
     observability?: StepObservability;
+} | {
+    ok: "paused";
+    pauseId: string;
+    pauseRequest: StepPauseRequest;
+    observability?: StepObservability;
 } | {
     ok: false;
     error: StepInvocationError;
 };
+/** Wire schema for one pause request. Canonical here — `parseStepResult`
+ *  imports it for validation, and `StepPauseRequest` is `z.infer`'d from
+ *  it so the runtime type and the parsed shape can't drift.
+ *
+ *  Loose by design (the inner zod shape stops at orchestration fields
+ *  the engine needs): the SDK wrapper layer (`requestDecision` /
+ *  `sleep` / `waitForEvent`) owns its own payload contract, and the
+ *  engine treats `payload` as opaque. */
+export declare const StepPauseRequestSchema: z.ZodObject<{
+    reason: z.ZodString;
+    kind: z.ZodEnum<{
+        custom: "custom";
+        decision: "decision";
+        sleep: "sleep";
+        event: "event";
+    }>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    ttlMs: z.ZodOptional<z.ZodNumber>;
+    correlationKey: z.ZodOptional<z.ZodString>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type StepPauseRequest = z.infer<typeof StepPauseRequestSchema>;
 /**
  * Discriminated error union.
  *

package/dist/types/events.d.ts

@@ -14,6 +14,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";
     runId: string;

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

@@ -1,6 +1,8 @@
 /** Shared execution context capabilities for workflow functions and steps. */
 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. */
 export interface WorkflowRun {
@@ -19,4 +21,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/dist/types/protocol.d.ts

@@ -52,5 +52,13 @@ 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;
 }
 export {};

package/dist/types/runtime.d.ts

@@ -52,14 +52,69 @@ 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/dist/types/sandbox.d.ts

@@ -9,11 +9,16 @@ 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 {
     sandboxId: string;

package/dist/utils/schemas.d.ts

@@ -5,4 +5,6 @@ export declare const AgentStatusSchema: z.ZodObject<{
     completed: z.ZodArray<z.ZodString>;
     blockers: z.ZodArray<z.ZodString>;
     exit_signal: z.ZodBoolean;
+    needs_input: z.ZodOptional<z.ZodBoolean>;
+    question: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;

package/dist/workflow-steps/__tests__/pause-wiring.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -8,3 +8,5 @@ export type { Step, StepContext, StepRunResult, Workflow, } from "./types.js";
 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/dist/workflow-steps/observability.d.ts

@@ -5,18 +5,32 @@
  * 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";
 /** One named sub-step (from `ctx.step("name", async () => ...)`).
  *  Becomes a `workflow_substep_*` lifecycle event on the run timeline. */
 export interface SubStepEvent {
@@ -49,10 +63,28 @@ export declare class StepObservabilityCollector {
     private metadata;
     private events;
     private subSteps;
+    private readonly liveEmitter?;
+    /** Seqs of events the server confirmed via the live route. */
+    private readonly ackedSeqs;
+    /** Promises for in-flight live emits — awaited at snapshot time. */
+    private readonly inFlight;
+    constructor(opts?: {
+        liveEmitter?: LiveAgentEventEmitter;
+    });
     readonly setMetadata: (data: Record<string, unknown>) => Promise<void>;
     readonly step: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
     readonly agentEvents: AgentEventSink;
+    /** 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 drainInFlight;
     /** 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. */
+    snapshot(): Promise<StepObservability | undefined>;
 }

package/dist/workflow-steps/run-callback.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare function makeRunCallbackEmitterFromEnv(stepIndex: number): LiveAgentEventEmitter | undefined;

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

@@ -27,6 +27,7 @@ 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 StepObservability } from "./observability.js";
+import type { LiveAgentEventEmitter } from "./run-callback.js";
 export declare class StepValidationError extends Error {
     readonly stepName: string;
     readonly side: "input" | "output";
@@ -67,6 +68,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> {
     output: TOutput;
@@ -84,6 +90,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
  *  hooks recorded. `observability` is undefined when nothing was buffered,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {