@axlsdk/axl 0.17.2 → 0.17.4

package/dist/index.cjs

@@ -113,11 +113,13 @@ __export(index_exports, {
   AXL_EVENT_TYPES: () => AXL_EVENT_TYPES,
   AnthropicProvider: () => AnthropicProvider,
   AxlError: () => AxlError,
+  AxlEventBus: () => AxlEventBus,
   AxlRuntime: () => AxlRuntime,
   AxlStream: () => AxlStream,
   BudgetExceededError: () => BudgetExceededError,
   CONFIG_CANDIDATES: () => CONFIG_CANDIDATES,
   COST_BEARING_LEAF_TYPES: () => COST_BEARING_LEAF_TYPES,
+  EventStreamOverflowError: () => EventStreamOverflowError,
   GeminiProvider: () => GeminiProvider,
   GuardrailError: () => GuardrailError,
   InMemoryVectorStore: () => InMemoryVectorStore,
@@ -2523,6 +2525,598 @@ function isRootLevel(event) {
   return (d ?? 0) === 0;
 }
 
+// src/event-stream.ts
+var import_node_events = require("events");
+
+// src/types.ts
+var AXL_EVENT_TYPES = [
+  // Workflow lifecycle
+  "workflow_start",
+  "workflow_end",
+  // Ask boundary
+  "ask_start",
+  "ask_end",
+  // Agent turn lifecycle
+  "agent_call_start",
+  "agent_call_end",
+  // Content delivery (stream-only)
+  "token",
+  // Tool invocation lifecycle
+  "tool_call_start",
+  "tool_call_end",
+  // Single-point tool events
+  "tool_approval",
+  "tool_denied",
+  // Delegation
+  "delegate",
+  // Handoff (spans two asks; not AskScoped).
+  // `handoff_start` emits before the target ask begins; always fired.
+  // `handoff_return` emits when control returns to source; roundtrip only
+  // (oneway handoffs have no return trip — the target's `ask_end` IS the
+  // end of the chain).
+  "handoff_start",
+  "handoff_return",
+  // Pipeline (retry/validation lifecycle) — added in PR 2; reserved here.
+  "pipeline",
+  // Progressive structured output — added in PR 2; reserved here.
+  "partial_object",
+  // Verification
+  "verify",
+  // Observability
+  "log",
+  "memory_remember",
+  "memory_recall",
+  "memory_forget",
+  // Durable execution checkpoints (`ctx.checkpoint`)
+  "checkpoint_save",
+  "checkpoint_replay",
+  // Human-in-the-loop (`ctx.awaitHuman`)
+  "await_human",
+  "await_human_resolved",
+  // Legacy gate events — emitted by current code; collapsed into `pipeline`
+  // in PR 2 (spec/16-streaming-wire-reliability §4.2).
+  "guardrail",
+  "schema_check",
+  "validate",
+  // Terminal workflow markers
+  "done",
+  "error"
+];
+
+// src/event-stream.ts
+var STREAM_EVENTS = new Set(AXL_EVENT_TYPES);
+var TERMINAL_TYPES = /* @__PURE__ */ new Set([
+  "done",
+  "error",
+  "workflow_end"
+]);
+var LIFECYCLE_TYPES = /* @__PURE__ */ new Set([
+  "ask_start",
+  "ask_end",
+  "agent_call_start",
+  "agent_call_end",
+  "tool_call_start",
+  "tool_call_end",
+  "tool_approval",
+  "tool_denied",
+  "handoff_start",
+  "handoff_return",
+  "delegate",
+  "pipeline",
+  "verify",
+  "workflow_start",
+  "workflow_end",
+  "checkpoint_save",
+  "checkpoint_replay",
+  "await_human",
+  "await_human_resolved"
+]);
+var EventStreamOverflowError = class extends Error {
+  maxQueued;
+  eventType;
+  constructor(maxQueued, eventType) {
+    super(
+      `AxlEventBus queue exceeded maxQueued=${maxQueued} (event type: ${eventType}). Consumer is too slow or the producer is unbounded. Configure \`maxQueued\`/\`onOverflow\` on the runtime, or set maxQueued: Infinity to disable.`
+    );
+    this.name = "EventStreamOverflowError";
+    this.maxQueued = maxQueued;
+    this.eventType = eventType;
+  }
+};
+var DEFAULT_MAX_QUEUED = 1e4;
+var DEFAULT_OVERFLOW = "drop-oldest-non-terminal";
+var AxlEventBus = class {
+  bus = new import_node_events.EventEmitter();
+  eventQueue = [];
+  waiters = [];
+  finished = false;
+  maxQueued;
+  onOverflow;
+  overflowWarned = false;
+  /** Callbacks fired exactly once when `_finish()` is called. Used by
+   *  curated views (e.g., `partialObjects`) that are listener-based and
+   *  need a termination signal independent of any synthetic `done` event. */
+  finishCallbacks = [];
+  /**
+   * Latest coalesced partial-object snapshot per `askId`, maintained on
+   * every `_push` regardless of consumer state. Seeds the
+   * `partialObjects` view's `pending` map at subscription time so a
+   * late subscriber recovers the most recent state per ask even if
+   * earlier `partial_object` events were already delivered to a prior
+   * iterator's waiter (and thus removed from `eventQueue`).
+   *
+   * The pre-fix snapshot walked `eventQueue` directly — that misses
+   * events already drained by past consumers. The map walks past
+   * `_push` calls instead, which is the actual definition of "what's
+   * the latest partial per ask". `pipeline(status: 'failed')` clears
+   * the entry for the affected askId so a discarded attempt can't
+   * surface to a future subscriber.
+   *
+   * Memory bound: O(active asks holding a pending partial). Cleared
+   * on `pipeline(failed)` (per ask) and otherwise grows with the
+   * number of distinct askIds that emitted at least one partial.
+   */
+  latestPartialByAsk = /* @__PURE__ */ new Map();
+  /**
+   * Hook fired when an iterator obtained from `[Symbol.asyncIterator]`
+   * is `await using`-disposed. Set via the second constructor argument.
+   * Used by `AxlStream` to call `Readable.destroy()` on its owning
+   * stream so disposing the iterator cascades to the Readable contract.
+   * Set once at construction; never reassigned.
+   *
+   * Replaces the previous `AxlStreamEventBus extends AxlEventBus`
+   * subclass — composition over inheritance for what is essentially a
+   * single function-pointer hook.
+   *
+   * @internal
+   */
+  onIteratorDispose;
+  /**
+   * @param options Public stream options (queue cap, overflow policy).
+   * @param onIteratorDispose @internal Invoked from `_disposeIterator`
+   *   when an iterator obtained from this bus is `await using`-disposed.
+   *   Used by `AxlStream` to forward to `Readable.destroy()`.
+   */
+  constructor(options, onIteratorDispose) {
+    const requestedMax = options?.maxQueued ?? DEFAULT_MAX_QUEUED;
+    if (typeof requestedMax !== "number" || Number.isNaN(requestedMax) || requestedMax !== Infinity && requestedMax < 1) {
+      throw new Error(
+        `EventStreamOptions.maxQueued must be >= 1 or Infinity (got ${String(requestedMax)}). To disable the cap, pass Infinity.`
+      );
+    }
+    this.maxQueued = requestedMax;
+    this.onOverflow = options?.onOverflow ?? DEFAULT_OVERFLOW;
+    this.onIteratorDispose = onIteratorDispose;
+    this.bus.on("error", () => {
+    });
+  }
+  unknownEventWarned = false;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  on(event, handler) {
+    if (STREAM_EVENTS.has(event)) {
+      this.bus.on(event, handler);
+    } else {
+      this.warnUnknownEventName("on", event);
+    }
+    return this;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  off(event, handler) {
+    if (STREAM_EVENTS.has(event)) {
+      this.bus.off(event, handler);
+    } else {
+      this.warnUnknownEventName("off", event);
+    }
+    return this;
+  }
+  /** One-shot warn on subscribe/unsubscribe for an event name outside
+   *  `AXL_EVENT_TYPES`. Pre-fix this branch silently dropped, which
+   *  meant a typo like `'agent_call_ended'` produced no signal. */
+  warnUnknownEventName(method, event) {
+    if (this.unknownEventWarned) return;
+    this.unknownEventWarned = true;
+    console.warn(
+      `[axl] AxlEventBus.${method}('${event}', ...) \u2014 '${event}' is not an AxlEventType; subscription dropped. Valid names: ${AXL_EVENT_TYPES.join(", ")}. This warning fires once per bus instance.`
+    );
+  }
+  // No explicit return-type annotation: structural inference yields a type
+  // assignable to Readable's `() => AsyncIterator<any, undefined, any>` when
+  // AxlStream delegates here, while preserving the richer iterator-with-dispose
+  // shape for direct AxlEventBus consumers.
+  [Symbol.asyncIterator]() {
+    const self = this;
+    let myResolver = null;
+    return {
+      next: () => {
+        if (self.eventQueue.length > 0) {
+          return Promise.resolve({ value: self.eventQueue.shift(), done: false });
+        }
+        if (self.finished && self.eventQueue.length === 0) {
+          return Promise.resolve({ value: void 0, done: true });
+        }
+        return new Promise((resolve2) => {
+          const wrapped = (value) => {
+            myResolver = null;
+            resolve2(value);
+          };
+          myResolver = wrapped;
+          self.waiters.push(wrapped);
+        });
+      },
+      return: () => {
+        if (myResolver) {
+          const idx = self.waiters.indexOf(myResolver);
+          if (idx >= 0) self.waiters.splice(idx, 1);
+          const r = myResolver;
+          myResolver = null;
+          r({ value: void 0, done: true });
+        }
+        return Promise.resolve({ value: void 0, done: true });
+      },
+      [Symbol.asyncIterator]() {
+        return this;
+      },
+      [Symbol.asyncDispose]: () => self._disposeIterator()
+    };
+  }
+  /** Hook for iterator disposal. Calls the constructor-supplied
+   *  `onIteratorDispose` callback if any. The default behavior is a
+   *  no-op when no callback was passed — a plain bus has no
+   *  Node-stream resource to release. */
+  _disposeIterator() {
+    this.onIteratorDispose?.();
+    return Promise.resolve();
+  }
+  /** Iterator over root-only `token` chunks. Skips nested-ask tokens
+   *  (consumers wanting nested can iterate the full bus and filter on
+   *  `event.depth >= 1`). */
+  get text() {
+    const self = this;
+    return {
+      [Symbol.asyncIterator]() {
+        const iter = self[Symbol.asyncIterator]();
+        return {
+          async next() {
+            while (true) {
+              const { value, done } = await iter.next();
+              if (done) return { value: void 0, done: true };
+              if (value.type === "token" && isRootLevel(value)) {
+                return { value: value.data, done: false };
+              }
+            }
+          },
+          // Propagate `return()` to the underlying bus iterator so its
+          // parked resolver (if any) is spliced out of `waiters`. Without
+          // this, breaking out of `for await (const t of bus.text)` would
+          // orphan the inner waiter and lose the next event.
+          async return() {
+            await iter.return?.();
+            return { value: void 0, done: true };
+          }
+        };
+      }
+    };
+  }
+  /** Iterator over `{ askId, agent?, text }` for every token across root and
+   *  nested asks. Useful for split-pane UIs that render each sub-agent's
+   *  output in its own lane. `agent` is undefined when the token was emitted
+   *  outside any ask (rare — synthesized test fixtures). */
+  get textByAsk() {
+    const self = this;
+    return {
+      [Symbol.asyncIterator]() {
+        const iter = self[Symbol.asyncIterator]();
+        return {
+          async next() {
+            while (true) {
+              const { value, done } = await iter.next();
+              if (done) {
+                return {
+                  value: void 0,
+                  done: true
+                };
+              }
+              if (value.type === "token") {
+                return {
+                  value: { askId: value.askId, agent: value.agent, text: value.data },
+                  done: false
+                };
+              }
+            }
+          },
+          async return() {
+            await iter.return?.();
+            return {
+              value: void 0,
+              done: true
+            };
+          }
+        };
+      }
+    };
+  }
+  /**
+   * Coalescing iterator over `partial_object` events — yields the latest
+   * payload per `askId`. When a newer `partial_object` arrives for an
+   * `askId` while the consumer is busy, the older value is silently
+   * superseded; the consumer sees only the most recent state per ask on
+   * its next `.next()` await.
+   *
+   * Memory bound: O(active asks holding a pending partial), not O(events).
+   * This is what UIs streaming structured output actually want — rendering
+   * every intermediate snapshot just to overwrite it ms later is wasted
+   * work, and unbounded queueing of intermediate JSON snapshots is the
+   * memory-pressure scenario this view is designed to avoid. In practice
+   * "active asks" is small (1-10 even for fan-out workflows); a workflow
+   * fanning out to 10k concurrent asks each producing partials would
+   * accumulate ≈10k pending entries (~1 MB), which is the realistic
+   * ceiling for this view.
+   *
+   * Schema-retry awareness: each yielded value carries the 1-indexed
+   * `attempt` field from the underlying `partial_object` event. When a
+   * schema check fails and the agent retries, the runtime emits
+   * `pipeline(status: 'failed')`; this view drops any undrained pending
+   * partial for the affected ask so the consumer never sees stale
+   * attempt-N snapshots after attempt-N+1 has begun. Mirrors the
+   * per-attempt buffer reset that `AxlStream.fullText` applies to
+   * tokens. (Validate-stage and guardrail retries trigger the same
+   * reset.)
+   *
+   * Malformed `partial_object` events (those missing `data.object`) are
+   * silently filtered — the variant shape requires the field, so an
+   * undefined value is a producer bug rather than a meaningful state.
+   *
+   * Implementation note: this is a listener-based view (subscribes to the
+   * bus's `partial_object` channel via `.on()`), not an iterator-based
+   * filter like `.text` / `.lifecycle` / `.textByAsk`. As a result it does
+   * NOT race with the main async iterator — running `for await (const e of bus)`
+   * concurrently with `for await (const p of bus.partialObjects)` works
+   * cleanly (each `partial_object` event fires the listener AND queues for
+   * iterators).
+   *
+   * Termination: yields any pending coalesced values first, then `done: true`
+   * once the bus is finished (via `_finish()`).
+   */
+  get partialObjects() {
+    const self = this;
+    return {
+      [Symbol.asyncIterator]() {
+        const pending = /* @__PURE__ */ new Map();
+        let resolveWaiter = null;
+        let finished = self.finished;
+        let unsubscribed = false;
+        const wakeWaiter = () => {
+          const r = resolveWaiter;
+          resolveWaiter = null;
+          r?.();
+        };
+        const recordPartial = (event) => {
+          if (event.data?.object === void 0) return;
+          const askId = event.askId ?? "";
+          pending.set(askId, {
+            askId,
+            agent: event.agent,
+            object: event.data.object,
+            attempt: event.attempt
+          });
+        };
+        for (const [askId, value] of self.latestPartialByAsk) {
+          pending.set(askId, value);
+        }
+        const handler = (event) => {
+          if (event.type !== "partial_object") return;
+          recordPartial(event);
+          wakeWaiter();
+        };
+        self.bus.on("partial_object", handler);
+        const pipelineHandler = (event) => {
+          if (event.type !== "pipeline") return;
+          if (event.status !== "failed") return;
+          const askId = event.askId ?? "";
+          pending.delete(askId);
+        };
+        self.bus.on("pipeline", pipelineHandler);
+        const unsubscribe = () => {
+          if (unsubscribed) return;
+          unsubscribed = true;
+          self.bus.off("partial_object", handler);
+          self.bus.off("pipeline", pipelineHandler);
+          unsubscribeFinish();
+        };
+        const unsubscribeFinish = self._onFinish(() => {
+          finished = true;
+          self.bus.off("partial_object", handler);
+          self.bus.off("pipeline", pipelineHandler);
+          wakeWaiter();
+        });
+        return {
+          async next() {
+            while (true) {
+              if (pending.size > 0) {
+                const it = pending.entries().next();
+                if (!it.done) {
+                  const [key, value] = it.value;
+                  pending.delete(key);
+                  return { value, done: false };
+                }
+              }
+              if (finished) {
+                unsubscribe();
+                return { value: void 0, done: true };
+              }
+              await new Promise((res) => {
+                resolveWaiter = res;
+              });
+            }
+          },
+          async return() {
+            unsubscribe();
+            return { value: void 0, done: true };
+          },
+          [Symbol.asyncIterator]() {
+            return this;
+          }
+        };
+      }
+    };
+  }
+  /** Iterator over structural lifecycle events only — skips per-token chatter
+   *  and progressive `partial_object` emissions. Useful for waterfall UIs
+   *  and any consumer that wants the "what happened" timeline. */
+  get lifecycle() {
+    const self = this;
+    return {
+      [Symbol.asyncIterator]() {
+        const iter = self[Symbol.asyncIterator]();
+        return {
+          async next() {
+            while (true) {
+              const { value, done } = await iter.next();
+              if (done) return { value: void 0, done: true };
+              if (LIFECYCLE_TYPES.has(value.type)) return { value, done: false };
+            }
+          },
+          async return() {
+            await iter.return?.();
+            return { value: void 0, done: true };
+          }
+        };
+      }
+    };
+  }
+  /**
+   * Push an event onto the bus. Emits on the typed channel (for `.on()`
+   * subscribers) and queues for async iterators. No-op once `_finish()` has
+   * been called.
+   *
+   * Subclasses (AxlStream) override to add token accounting and Readable
+   * fan-out before delegating to this implementation.
+   *
+   * @internal — called by the runtime / WorkflowContext / AxlStream.
+   */
+  _push(event) {
+    if (this.finished) return;
+    try {
+      this.bus.emit(event.type, event);
+    } catch (err) {
+      console.error(
+        `[axl] AxlEventBus listener for "${event.type}" threw; ignoring:`,
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+    if (event.type === "partial_object" && event.data?.object !== void 0) {
+      const askId = event.askId ?? "";
+      this.latestPartialByAsk.set(askId, {
+        askId,
+        agent: event.agent,
+        object: event.data.object,
+        attempt: event.attempt
+      });
+    } else if (event.type === "pipeline" && event.status === "failed") {
+      this.latestPartialByAsk.delete(event.askId ?? "");
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value: event, done: false });
+      return;
+    }
+    if (this.eventQueue.length >= this.maxQueued && !TERMINAL_TYPES.has(event.type)) {
+      this.handleOverflow(event);
+      return;
+    }
+    this.eventQueue.push(event);
+  }
+  /** Apply the overflow policy when the queue is at `maxQueued` and a
+   *  non-terminal event arrives. Terminal events bypass this path entirely
+   *  (checked by the caller). */
+  handleOverflow(event) {
+    if (this.onOverflow === "throw") {
+      throw new EventStreamOverflowError(this.maxQueued, event.type);
+    }
+    let droppedIdx = -1;
+    for (let i = 0; i < this.eventQueue.length; i++) {
+      if (!TERMINAL_TYPES.has(this.eventQueue[i].type)) {
+        droppedIdx = i;
+        break;
+      }
+    }
+    if (!this.overflowWarned) {
+      this.overflowWarned = true;
+      console.warn(
+        `[axl] AxlEventBus queue exceeded maxQueued=${this.maxQueued}` + (droppedIdx >= 0 ? `; dropping oldest non-terminal events (consumer is slower than producer).` : `; queue is all terminals (preserved past cap so no terminal is lost).`) + ` This warning fires once per bus instance.`
+      );
+    }
+    if (droppedIdx >= 0) {
+      this.eventQueue.splice(droppedIdx, 1);
+    }
+    this.eventQueue.push(event);
+  }
+  /**
+   * Mark the bus as finished. Wakes any pending iterators with `done: true`
+   * and drops further `_push` calls. Idempotent.
+   *
+   * Does not synthesize a terminal `done` AxlEvent — callers (AxlStream) that
+   * want one push it via `_push` before calling `_finish`.
+   *
+   * Late iterators that connect after `_finish()` still drain any events
+   * remaining in `eventQueue` (the `next()` short-circuit in
+   * `[Symbol.asyncIterator]` checks the queue before checking `finished`),
+   * then receive `done: true`.
+   *
+   * @internal
+   */
+  _finish() {
+    if (this.finished) return;
+    this.finished = true;
+    for (const w of this.waiters) {
+      w({ value: void 0, done: true });
+    }
+    this.waiters.length = 0;
+    const callbacks = this.finishCallbacks;
+    this.finishCallbacks = [];
+    for (const cb of callbacks) {
+      try {
+        cb();
+      } catch (err) {
+        console.error("[axl] AxlEventBus finish callback threw:", err);
+      }
+    }
+  }
+  /** Register a one-shot callback fired when `_finish()` is called.
+   *  Returns an unsubscribe function. If the bus is already finished,
+   *  the callback is invoked synchronously and the returned unsubscribe
+   *  is a no-op.
+   *
+   *  Used by listener-based curated views (e.g., `partialObjects`) that
+   *  need a termination signal independent of any synthesized `done`
+   *  event. Iterator consumers don't need this — `[Symbol.asyncIterator]`
+   *  resolves with `done: true` automatically.
+   *
+   *  @internal */
+  _onFinish(cb) {
+    if (this.finished) {
+      cb();
+      return () => {
+      };
+    }
+    this.finishCallbacks.push(cb);
+    return () => {
+      const i = this.finishCallbacks.indexOf(cb);
+      if (i >= 0) this.finishCallbacks.splice(i, 1);
+    };
+  }
+  /** Whether `event` is one of the `AxlEventType` names this bus emits.
+   *  Subclasses (e.g., `AxlStream`) consult this to route AxlEvent names to
+   *  the bus and other names (`'close'`, `'data'`, ...) to a wider emitter. */
+  knowsEventName(event) {
+    return STREAM_EVENTS.has(event);
+  }
+  /** Whether `_finish()` has been called. */
+  get isFinished() {
+    return this.finished;
+  }
+};
+
 // src/redaction.ts
 var REDACTED = "[redacted]";
 function walkObjectOneLevel(obj, preserveKeys) {
@@ -2888,6 +3482,103 @@ var WorkflowContext = class _WorkflowContext {
   awaitHumanHandler;
   onAgentStart;
   onAgentCallComplete;
+  /** Shared mutable slot for the lazy `AxlEventBus`. The slot is shared
+   *  by reference across parent/child contexts so a late allocation
+   *  (consumer subscribes after a child context exists) is visible
+   *  everywhere. Until first access `_busRef.current` is undefined and
+   *  `emitEvent` skips the bus fan-out entirely (zero overhead for
+   *  contexts that never observe). */
+  _busRef;
+  _eventStreamOptions;
+  /** Removes the constructor-registered `'abort'` listener from
+   *  `this.signal` so a long-lived signal (e.g., a request-scoped or
+   *  process-wide signal reused across many `runtime.createContext()` /
+   *  `runtime.execute()` calls) doesn't accumulate listeners forever.
+   *  Called from `disposeEvents()` and from the workflow_end/error
+   *  emission in `emitEvent`. Undefined when no abort listener was
+   *  registered (no signal, signal already aborted, or non-root
+   *  context). */
+  abortListenerCleanup;
+  /**
+   * Iterable + EventEmitter view over every `AxlEvent` emitted by this
+   * context (and its child contexts — agent-as-tool nested asks bubble up).
+   *
+   * Use cases:
+   *  - **Inside a workflow handler**: subscribe before the first `ctx.ask()`
+   *    to observe `partial_object`, `agent_call_*`, `tool_call_*`, etc.
+   *    *between* asks. `ctx.events.partialObjects` is the coalescing view
+   *    designed for streaming-structured-output UIs.
+   *  - **Ad-hoc contexts** from `runtime.createContext()`: the same
+   *    iterable replaces the legacy `onToken` / `onToolCall` /
+   *    `onAgentStart` callbacks.
+   *  - **Cross-execution**: prefer `runtime.on('trace', …)` instead — that
+   *    fans out across all executions, while `ctx.events` is per-context.
+   *
+   * Lazy: the bus is allocated on first access. The bus's iterator
+   * queue retains events emitted before any consumer iterates, so a
+   * late `for await (const e of ctx.events)` still drains queued
+   * events. The `partialObjects` view additionally seeds from a
+   * per-bus `latestPartialByAsk` map, so a late subscriber may see
+   * the latest coalesced state per ask even when earlier events were
+   * already drained by another iterator. **Neither rescues a late
+   * subscriber from the streaming-gate behavior** (see below).
+   *
+   * **Subscribe before the first `ctx.ask()`.** The streaming code
+   * path inside `ctx.ask()` activates only when an observer is
+   * present at the time the ask starts (`_streamingEnabled` — either
+   * the legacy `onToken` callback is set or `ctx.events` has been
+   * allocated). If you allocate `ctx.events` AFTER a `ctx.ask()` has
+   * begun, that in-flight ask will not stream `token` /
+   * `partial_object` events at all (the agent loop went through
+   * `provider.chat` instead of `provider.stream`). Subsequent asks
+   * will stream normally — the gate is re-checked per ask. The
+   * unambiguous pattern is `const events = ctx.events;` on the first
+   * line of the handler.
+   *
+   * Auto-termination: `emitEvent` calls `_eventBus._finish()` after
+   * emitting `workflow_end` or `error`, so iterators terminate
+   * cleanly with `done: true`. For ad-hoc contexts that never run a
+   * workflow (no terminal event), pass `signal: AbortSignal.timeout(...)`
+   * to `runtime.createContext` (the bus auto-disposes on abort) or
+   * call `ctx.disposeEvents()` when done observing.
+   */
+  get events() {
+    if (!this._busRef.current) {
+      this._busRef.current = new AxlEventBus(this._eventStreamOptions);
+      if (this.signal?.aborted) {
+        this._busRef.current._finish();
+      }
+    }
+    return this._busRef.current;
+  }
+  /** Manually finish the `ctx.events` bus, terminating any active
+   *  iterators with `done: true`. Idempotent. Useful for ad-hoc contexts
+   *  from `runtime.createContext()` that never emit a `workflow_end` /
+   *  `error` terminal — observers iterating `for await (const e of
+   *  ctx.events)` would otherwise hang. Workflow-driven contexts
+   *  (`runtime.execute` / `runtime.stream`) terminate automatically and
+   *  don't need this.
+   *
+   *  Also removes the constructor-registered abort listener so a
+   *  long-lived `signal` reused across many ad-hoc contexts doesn't
+   *  accumulate listeners. */
+  disposeEvents() {
+    this._busRef.current?._finish();
+    this.abortListenerCleanup?.();
+  }
+  /** True if any observer wants per-token streaming for asks started
+   *  from this context: either the legacy `onToken` callback is set
+   *  (e.g., `runtime.stream()` plumbs a sentinel) OR `ctx.events` has
+   *  been allocated (a workflow-handler consumer subscribed before
+   *  the ask). `ctx.ask` reads this to decide whether to enter the
+   *  streaming code path; the gate is re-checked per ask, so a
+   *  consumer subscribing AFTER the first ask started still gets
+   *  streaming on the next one. The check `_busRef.current !== undefined`
+   *  is a one-way flag — `_finish` does not unset the reference, so
+   *  once an observer was present, every subsequent ask streams. */
+  get _streamingEnabled() {
+    return this.onToken !== void 0 || this._busRef.current !== void 0;
+  }
   constructor(init) {
     this.input = init.input;
     this.executionId = init.executionId;
@@ -2911,6 +3602,19 @@ var WorkflowContext = class _WorkflowContext {
     this.awaitHumanHandler = init.awaitHumanHandler;
     this.onAgentStart = init.onAgentStart;
     this.onAgentCallComplete = init.onAgentCallComplete;
+    this._busRef = init._busRef ?? { current: void 0 };
+    this._eventStreamOptions = init.eventStreamOptions;
+    if (init._busRef === void 0 && this.signal && !this.signal.aborted) {
+      const signal = this.signal;
+      const onAbort = () => {
+        this._busRef.current?._finish();
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      this.abortListenerCleanup = () => {
+        signal.removeEventListener("abort", onAbort);
+        this.abortListenerCleanup = void 0;
+      };
+    }
     this.autoCheckpointCounters = init.autoCheckpointCounters ?? {
       byAgent: /* @__PURE__ */ new Map(),
       root: 0
@@ -2965,7 +3669,14 @@ var WorkflowContext = class _WorkflowContext {
       // Share the parent's auto-checkpoint counters so internal checkpoints
       // emitted from `ctx.ask` / spawn / race / parallel / map in this
       // child context don't collide with the parent's in the state store.
-      autoCheckpointCounters: this.autoCheckpointCounters
+      autoCheckpointCounters: this.autoCheckpointCounters,
+      // Share the parent's bus slot (mutable ref). Late allocation in
+      // either parent or child propagates because both read the same
+      // slot. Nested-ask events (agent-as-tool pattern) bubble up to
+      // the parent's iterator with `parentAskId`/`depth` correlation
+      // intact.
+      _busRef: this._busRef,
+      eventStreamOptions: this._eventStreamOptions
       // Isolated: sessionHistory (empty)
     });
   }
@@ -3101,15 +3812,26 @@ var WorkflowContext = class _WorkflowContext {
             };
             throw err;
           } finally {
-            this.emitEvent({
-              type: "ask_end",
-              outcome: outcome ?? {
-                ok: false,
-                error: "ask_end emitted without outcome \u2014 internal bug"
-              },
-              cost: frame.askCost.value,
-              duration: Date.now() - askStart
-            });
+            try {
+              this.emitEvent({
+                type: "ask_end",
+                outcome: outcome ?? {
+                  ok: false,
+                  error: "ask_end emitted without outcome \u2014 internal bug"
+                },
+                cost: frame.askCost.value,
+                duration: Date.now() - askStart
+              });
+            } catch (emitErr) {
+              if (emitErr instanceof EventStreamOverflowError && outcome && !outcome.ok) {
+                console.error(
+                  "[axl] ask_end emit overflowed during error path; preserving original error:",
+                  emitErr.message
+                );
+              } else {
+                throw emitErr;
+              }
+            }
           }
         });
       },
@@ -3346,7 +4068,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       this.onAgentStart?.({ agent: agent2._name, model: modelUri }, callbackMeta);
       let response;
       try {
-        if (this.onToken) {
+        if (this._streamingEnabled) {
           let content2 = "";
           const toolCalls = [];
           const toolCallBuffers = /* @__PURE__ */ new Map();
@@ -3361,7 +4083,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
             if (chunk.type === "text_delta") {
               content2 += chunk.content;
               this.emitEvent({ type: "token", data: chunk.content });
-              this.onToken(chunk.content, callbackMeta);
+              this.onToken?.(chunk.content, callbackMeta);
               if (partialObjectEnabled) {
                 for (const ch of chunk.content) {
                   if (escaped) {
@@ -4076,19 +4798,21 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         attempt: lastStartAttempt,
         maxAttempts: lastStartMaxAttempts
       });
-      this.pushAssistantToSessionHistory(content, response.providerMetadata);
+      this.pushAssistantToSessionHistory(content, agent2._name, response.providerMetadata);
       return validated ?? content;
     }
     throw new MaxTurnsError("ctx.ask()", maxTurns);
   }
   /**
    * Push the final assistant message into session history, preserving providerMetadata
-   * (e.g., Gemini thought signatures needed for multi-turn reasoning context).
+   * (e.g., Gemini thought signatures needed for multi-turn reasoning context) and
+   * stamping the agent name for observability + future per-agent scoping.
    */
-  pushAssistantToSessionHistory(content, providerMetadata) {
+  pushAssistantToSessionHistory(content, agentName, providerMetadata) {
     this.sessionHistory.push({
       role: "assistant",
       content,
+      agent: agentName,
       ...providerMetadata ? { providerMetadata } : {}
     });
   }
@@ -5274,16 +5998,48 @@ ${summaryResponse.content}`
       data
     };
     const finalEvent = this.config.trace?.redact ? redactEvent(event) : event;
+    let overflowErr;
     if (this.onTrace) {
       try {
         this.onTrace(finalEvent);
       } catch (err) {
-        console.error(
-          "[axl] onTrace handler threw; trace event dropped:",
-          err instanceof Error ? err.message : String(err)
-        );
+        if (err instanceof EventStreamOverflowError) {
+          overflowErr = err;
+        } else {
+          console.error(
+            "[axl] onTrace handler threw; trace event dropped:",
+            err instanceof Error ? err.message : String(err)
+          );
+        }
+      }
+    }
+    const bus = this._busRef.current;
+    if (bus) {
+      try {
+        bus._push(finalEvent);
+      } catch (err) {
+        if (err instanceof EventStreamOverflowError) {
+          if (!overflowErr) {
+            overflowErr = err;
+          } else {
+            console.error(
+              '[axl] ctx.events bus also overflowed for event "' + finalEvent.type + '"; first overflow already in flight:',
+              err.message
+            );
+          }
+        } else {
+          console.error(
+            "[axl] AxlEventBus._push threw unexpectedly:",
+            err instanceof Error ? err.message : String(err)
+          );
+        }
       }
     }
+    if (finalEvent.type === "workflow_end" || finalEvent.type === "error") {
+      bus?._finish();
+      this.abortListenerCleanup?.();
+    }
+    if (overflowErr) throw overflowErr;
   }
 };
 
@@ -5887,56 +6643,28 @@ var Session = class _Session {
   get id() {
     return this.sessionId;
   }
-  async send(workflowName, input) {
+  async send(workflowName, input, options) {
     if (this.closed) throw new Error("Session has been ended");
-    const history = await this.store.getSession(this.sessionId);
-    let cachedSummary = await this.store.getSessionMeta(this.sessionId, "summaryCache");
-    const maxMessages = this.options.history?.maxMessages;
-    if (maxMessages && history.length > maxMessages) {
-      if (this.options.history?.summarize) {
-        const summaryModel = this.options.history?.summaryModel;
-        if (!summaryModel) {
-          throw new Error("SessionOptions.history.summaryModel is required when summarize is true");
-        }
-        const messagesToDrop = history.slice(0, history.length - maxMessages);
-        const toSummarize = cachedSummary ? [
-          { role: "system", content: `Previous conversation summary: ${cachedSummary}` },
-          ...messagesToDrop
-        ] : messagesToDrop;
-        const summary = await this.runtime.summarizeMessages(toSummarize, summaryModel);
-        await this.store.saveSessionMeta(this.sessionId, "summaryCache", summary);
-        cachedSummary = summary;
-      }
-      const trimmed = history.slice(-maxMessages);
-      history.length = 0;
-      history.push(...trimmed);
-    }
-    const userMessage = {
-      role: "user",
-      content: typeof input === "string" ? input : JSON.stringify(input)
-    };
-    history.push(userMessage);
-    const result = await this.runtime.execute(workflowName, input, {
-      metadata: {
-        sessionId: this.sessionId,
-        sessionHistory: history,
-        ...cachedSummary ? { summaryCache: cachedSummary } : {}
-      }
-    });
-    const lastMsg = history[history.length - 1];
-    if (!(lastMsg && lastMsg.role === "assistant")) {
-      history.push({
-        role: "assistant",
-        content: typeof result === "string" ? result : JSON.stringify(result)
-      });
-    }
-    if (this.options.persist !== false) {
-      await this.store.saveSession(this.sessionId, history);
-    }
+    options?.signal?.throwIfAborted?.();
+    return this.runtime._serializeSession(
+      this.sessionId,
+      () => this.sendImpl(workflowName, input, options?.signal, options?.events)
+    );
+  }
+  async sendImpl(workflowName, input, signal, events) {
+    const { history, metadata } = await this.prepareHistory(input);
+    const result = await this.runtime.execute(workflowName, input, { metadata, signal, events });
+    await this.commitHistory(history, result);
     return result;
   }
-  async stream(workflowName, input) {
-    if (this.closed) throw new Error("Session has been ended");
+  /** Read history + summary, apply maxMessages limit (with optional
+   *  summarization), and push the new user message. Returns the mutable
+   *  `history` array (which `executeAgentCall` will append the assistant
+   *  reply to in-place) and the `metadata` payload to forward to
+   *  `runtime.execute()` / `runtime.stream()`. Shared by `sendImpl` and
+   *  `streamImpl` so future fixes (e.g., to summarization wiring) land in
+   *  one place. */
+  async prepareHistory(input) {
     const history = await this.store.getSession(this.sessionId);
     let cachedSummary = await this.store.getSessionMeta(this.sessionId, "summaryCache");
     const maxMessages = this.options.history?.maxMessages;
@@ -5959,41 +6687,83 @@ var Session = class _Session {
       history.length = 0;
       history.push(...trimmed);
     }
-    const userMessage = {
+    history.push({
       role: "user",
       content: typeof input === "string" ? input : JSON.stringify(input)
-    };
-    history.push(userMessage);
-    const axlStream = this.runtime.stream(workflowName, input, {
-      metadata: {
-        sessionId: this.sessionId,
-        sessionHistory: history,
-        ...cachedSummary ? { summaryCache: cachedSummary } : {}
-      }
     });
-    const updateHistory = async (result) => {
-      const lastMsg = history[history.length - 1];
-      if (!(lastMsg && lastMsg.role === "assistant")) {
-        history.push({
-          role: "assistant",
-          content: typeof result === "string" ? result : JSON.stringify(result)
-        });
-      }
-      if (this.options.persist !== false) {
-        await this.store.saveSession(this.sessionId, history);
-      }
+    const metadata = {
+      sessionId: this.sessionId,
+      sessionHistory: history,
+      ...cachedSummary ? { summaryCache: cachedSummary } : {}
     };
-    axlStream.on("done", (event) => {
-      const data = event.data;
-      updateHistory(data.result).catch((err) => {
+    return { history, metadata };
+  }
+  /** Push the assistant reply (if `executeAgentCall` didn't already) and
+   *  persist. Shared by `sendImpl` and `streamImpl`. The fallback assistant
+   *  push has no agent context and so leaves `agent` undefined — see the
+   *  `ChatMessage.agent` field doc. */
+  async commitHistory(history, result) {
+    const lastMsg = history[history.length - 1];
+    if (!(lastMsg && lastMsg.role === "assistant")) {
+      history.push({
+        role: "assistant",
+        content: typeof result === "string" ? result : JSON.stringify(result)
+      });
+    }
+    if (this.options.persist !== false) {
+      await this.store.saveSession(this.sessionId, history);
+    }
+  }
+  async stream(workflowName, input, options) {
+    if (this.closed) throw new Error("Session has been ended");
+    options?.signal?.throwIfAborted?.();
+    let resolveReady;
+    let rejectReady;
+    const streamReady = new Promise((res, rej) => {
+      resolveReady = res;
+      rejectReady = rej;
+    });
+    void this.runtime._serializeSession(
+      this.sessionId,
+      () => this.streamImpl(
+        workflowName,
+        input,
+        resolveReady,
+        rejectReady,
+        options?.signal,
+        options?.events
+      )
+    ).catch(() => {
+    });
+    return streamReady;
+  }
+  async streamImpl(workflowName, input, resolveReady, rejectReady, signal, events) {
+    let history;
+    let axlStream;
+    try {
+      const prepared = await this.prepareHistory(input);
+      history = prepared.history;
+      axlStream = this.runtime.stream(workflowName, input, {
+        metadata: prepared.metadata,
+        signal,
+        events
+      });
+    } catch (err) {
+      rejectReady(err);
+      throw err;
+    }
+    resolveReady(axlStream);
+    const completion = axlStream.promise.then(
+      (result) => this.commitHistory(history, result).catch((err) => {
         this.runtime.emit("error", {
           type: "session_history_save_failed",
           sessionId: this.sessionId,
           error: err instanceof Error ? err.message : String(err)
         });
-      });
-    });
-    return axlStream;
+      }),
+      () => void 0
+    );
+    await completion;
   }
   async history() {
     return this.store.getSession(this.sessionId);
@@ -6004,99 +6774,71 @@ var Session = class _Session {
   }
   async end() {
     this.closed = true;
-    if (this.options.persist !== false) {
-      await this.store.deleteSession(this.sessionId);
-    }
+    return this.runtime._serializeSession(this.sessionId, async () => {
+      if (this.options.persist !== false) {
+        await this.store.deleteSession(this.sessionId);
+      }
+    });
   }
-  async fork(newId) {
-    const history = await this.store.getSession(this.sessionId);
-    const forked = new _Session(newId, this.runtime, this.store, this.options);
-    await this.store.saveSession(newId, [...history]);
-    const summaryCache = await this.store.getSessionMeta(this.sessionId, "summaryCache");
-    if (summaryCache !== null) {
-      await this.store.saveSessionMeta(newId, "summaryCache", summaryCache);
-    }
-    const handoffHistory = await this.store.getSessionMeta(this.sessionId, "handoffHistory");
-    if (handoffHistory !== null) {
-      await this.store.saveSessionMeta(newId, "handoffHistory", handoffHistory);
-    }
-    return forked;
+  async fork(newId, options) {
+    if (newId === this.sessionId) {
+      throw new Error(`Session.fork: newId must differ from source id (${this.sessionId})`);
+    }
+    const [first, second] = [this.sessionId, newId].sort();
+    return this.runtime._serializeSession(
+      first,
+      () => this.runtime._serializeSession(second, async () => {
+        if (!options?.overwrite) {
+          const existing = await this.store.getSession(newId);
+          if (existing.length > 0) {
+            throw new Error(
+              `Session.fork: target id "${newId}" already has history. Pass { overwrite: true } to replace it, or choose a different id.`
+            );
+          }
+        }
+        const history = await this.store.getSession(this.sessionId);
+        const forked = new _Session(newId, this.runtime, this.store, this.options);
+        await this.store.saveSession(newId, [...history]);
+        const summaryCache = await this.store.getSessionMeta(this.sessionId, "summaryCache");
+        if (summaryCache !== null) {
+          await this.store.saveSessionMeta(newId, "summaryCache", summaryCache);
+        }
+        const handoffHistory = await this.store.getSessionMeta(this.sessionId, "handoffHistory");
+        if (handoffHistory !== null) {
+          await this.store.saveSessionMeta(newId, "handoffHistory", handoffHistory);
+        }
+        if (this.store.getAllMemory && this.store.saveMemory) {
+          const sourceScope = `session:${this.sessionId}`;
+          const targetScope = `session:${newId}`;
+          const entries = await this.store.getAllMemory(sourceScope);
+          for (const { key, value } of entries) {
+            await this.store.saveMemory(targetScope, key, value);
+          }
+        }
+        return forked;
+      })
+    );
   }
 };
 
 // src/stream.ts
 var import_node_stream = require("stream");
-var import_node_events = require("events");
-
-// src/types.ts
-var AXL_EVENT_TYPES = [
-  // Workflow lifecycle
-  "workflow_start",
-  "workflow_end",
-  // Ask boundary
-  "ask_start",
-  "ask_end",
-  // Agent turn lifecycle
-  "agent_call_start",
-  "agent_call_end",
-  // Content delivery (stream-only)
-  "token",
-  // Tool invocation lifecycle
-  "tool_call_start",
-  "tool_call_end",
-  // Single-point tool events
-  "tool_approval",
-  "tool_denied",
-  // Delegation
-  "delegate",
-  // Handoff (spans two asks; not AskScoped).
-  // `handoff_start` emits before the target ask begins; always fired.
-  // `handoff_return` emits when control returns to source; roundtrip only
-  // (oneway handoffs have no return trip — the target's `ask_end` IS the
-  // end of the chain).
-  "handoff_start",
-  "handoff_return",
-  // Pipeline (retry/validation lifecycle) — added in PR 2; reserved here.
-  "pipeline",
-  // Progressive structured output — added in PR 2; reserved here.
-  "partial_object",
-  // Verification
-  "verify",
-  // Observability
-  "log",
-  "memory_remember",
-  "memory_recall",
-  "memory_forget",
-  // Durable execution checkpoints (`ctx.checkpoint`)
-  "checkpoint_save",
-  "checkpoint_replay",
-  // Human-in-the-loop (`ctx.awaitHuman`)
-  "await_human",
-  "await_human_resolved",
-  // Legacy gate events — emitted by current code; collapsed into `pipeline`
-  // in PR 2 (spec/16-streaming-wire-reliability §4.2).
-  "guardrail",
-  "schema_check",
-  "validate",
-  // Terminal workflow markers
-  "done",
-  "error"
-];
-
-// src/stream.ts
-var AxlStream = class _AxlStream extends import_node_stream.Readable {
-  bus = new import_node_events.EventEmitter();
+var AxlStream = class extends import_node_stream.Readable {
+  /** Composed event bus — owns iterator queue, EventEmitter gating, and
+   *  curated views (`.text`, `.lifecycle`, `.textByAsk`). Private; the
+   *  public surface is via the delegating methods below. */
+  events;
   /**
-   * Per-ask token buffers split into "in-progress" and "committed"
-   * halves so `fullText` only includes tokens from attempts that
-   * actually won. Scoping is per-`askId` so concurrent root-level asks
-   * (`ctx.parallel`, `ctx.spawn`, `ctx.race`, `ctx.map`) don't
-   * interleave each other's tokens — each branch's chunks stay
-   * contiguous, and a `pipeline(failed)` on one branch only discards
-   * THAT branch's in-progress buffer (previously: shared buffer caused
-   * a failure on one branch to discard a peer's in-flight successful
-   * tokens). Insertion order in the Maps reflects which ask emitted
-   * its first token first, which is what `fullText` joins on.
+   * Per-ask token buffers split into "in-progress" and "committed" halves
+   * so `fullText` only includes tokens from attempts that actually won.
+   * Scoping is per-`askId` so concurrent root-level asks
+   * (`ctx.parallel`, `ctx.spawn`, `ctx.race`, `ctx.map`) don't interleave
+   * each other's tokens — each branch's chunks stay contiguous, and a
+   * `pipeline(failed)` on one branch only discards THAT branch's
+   * in-progress buffer (previously: shared buffer caused a failure on
+   * one branch to discard a peer's in-flight successful tokens).
+   * Insertion order in the Maps reflects which ask emitted its first
+   * token first, which is what `fullText` joins on.
    *
    * On `pipeline(status: 'committed')` for an ask, that ask's
    * in-progress entry flushes to its committed entry. On
@@ -6110,189 +6852,98 @@ var AxlStream = class _AxlStream extends import_node_stream.Readable {
   attemptByAsk = /* @__PURE__ */ new Map();
   committedByAsk = /* @__PURE__ */ new Map();
   result = void 0;
-  finished = false;
   promise;
-  eventQueue = [];
-  waiters = [];
-  constructor() {
+  resolvePromise;
+  rejectPromise;
+  constructor(options) {
     super({ objectMode: true, read() {
     } });
-    let resolvePromise;
-    let rejectPromise;
+    this.events = new AxlEventBus(options, () => this.destroy());
     this.promise = new Promise((resolve2, reject) => {
-      resolvePromise = resolve2;
-      rejectPromise = reject;
-    });
-    this.bus.on("__resolve", (value) => resolvePromise(value));
-    this.bus.on("__reject", (error) => rejectPromise(error));
-    this.bus.on("error", () => {
+      this.resolvePromise = resolve2;
+      this.rejectPromise = reject;
     });
     this.promise.catch(() => {
     });
   }
-  /** Wire-format event names callers can subscribe to via `.on(name, fn)`.
-   *  Derived from the canonical `AXL_EVENT_TYPES` tuple — adding a new
-   *  variant in `types.ts` automatically extends the subscribable set. */
-  static STREAM_EVENTS = new Set(AXL_EVENT_TYPES);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   on(event, handler) {
-    if (_AxlStream.STREAM_EVENTS.has(event)) {
-      this.bus.on(event, handler);
+    if (this.events.knowsEventName(event)) {
+      this.events.on(event, handler);
     } else {
       super.on(event, handler);
     }
     return this;
   }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   off(event, handler) {
-    if (_AxlStream.STREAM_EVENTS.has(event)) {
-      this.bus.off(event, handler);
+    if (this.events.knowsEventName(event)) {
+      this.events.off(event, handler);
     } else {
       super.off(event, handler);
     }
     return this;
   }
+  // Override Readable's [Symbol.asyncIterator] to delegate to the bus.
+  // No explicit return type — structural inference keeps it compatible
+  // with Readable's own signature while preserving the richer
+  // iterator-with-dispose shape for direct consumers.
   [Symbol.asyncIterator]() {
-    const self = this;
-    return {
-      next: () => {
-        if (self.eventQueue.length > 0) {
-          return Promise.resolve({ value: self.eventQueue.shift(), done: false });
-        }
-        if (self.finished && self.eventQueue.length === 0) {
-          return Promise.resolve({ value: void 0, done: true });
-        }
-        return new Promise((resolve2) => {
-          self.waiters.push(resolve2);
-        });
-      },
-      [Symbol.asyncIterator]() {
-        return this;
-      },
-      [Symbol.asyncDispose]() {
-        self.destroy();
-        return Promise.resolve();
-      }
-    };
+    return this.events[Symbol.asyncIterator]();
   }
   get text() {
-    const self = this;
-    return {
-      [Symbol.asyncIterator]() {
-        const iter = self[Symbol.asyncIterator]();
-        return {
-          async next() {
-            while (true) {
-              const { value, done } = await iter.next();
-              if (done) return { value: void 0, done: true };
-              if (value.type === "token" && isRootLevel(value)) {
-                return { value: value.data, done: false };
-              }
-            }
-          }
-        };
-      }
-    };
+    return this.events.text;
   }
-  /**
-   * Iterator over `{ askId, text }` pairs — one emission per token chunk,
-   * tagged with the ask frame that produced it. Complements `.text`
-   * (root-only stream): consumers building a split-pane UI that shows
-   * each sub-agent's output in its own lane can group by `askId`
-   * without iterating the raw stream and hand-filtering on `event.type`.
-   *
-   * Nested and root tokens both flow through. The `agent` field names
-   * the producing agent for UI labelling; it's undefined when the token
-   * was emitted outside any ask (rare — synthesized test fixtures).
-   */
   get textByAsk() {
-    const self = this;
-    return {
-      [Symbol.asyncIterator]() {
-        const iter = self[Symbol.asyncIterator]();
-        return {
-          async next() {
-            while (true) {
-              const { value, done } = await iter.next();
-              if (done) {
-                return {
-                  value: void 0,
-                  done: true
-                };
-              }
-              if (value.type === "token") {
-                return {
-                  value: { askId: value.askId, agent: value.agent, text: value.data },
-                  done: false
-                };
-              }
-            }
-          }
-        };
-      }
-    };
+    return this.events.textByAsk;
   }
-  /**
-   * Iterator over structural lifecycle events only — skips per-token chatter
-   * and progressive partial_object emissions. Useful for waterfall UIs and
-   * any consumer that wants the "what happened" timeline without per-chunk
-   * noise. Renamed from `.steps` in the unified-event-model migration
-   * because these are events, not pipeline steps.
-   */
   get lifecycle() {
-    const lifecycleTypes = /* @__PURE__ */ new Set([
-      "ask_start",
-      "ask_end",
-      "agent_call_start",
-      "agent_call_end",
-      "tool_call_start",
-      "tool_call_end",
-      "tool_approval",
-      "tool_denied",
-      "handoff_start",
-      "handoff_return",
-      "delegate",
-      "pipeline",
-      "verify",
-      "workflow_start",
-      "workflow_end",
-      // Durable-execution checkpoints — structural points in the timeline.
-      "checkpoint_save",
-      "checkpoint_replay",
-      // Human-in-the-loop — pause/resume are major timeline landmarks.
-      "await_human",
-      "await_human_resolved"
-    ]);
-    const self = this;
-    return {
-      [Symbol.asyncIterator]() {
-        const iter = self[Symbol.asyncIterator]();
-        return {
-          async next() {
-            while (true) {
-              const { value, done } = await iter.next();
-              if (done) return { value: void 0, done: true };
-              if (lifecycleTypes.has(value.type)) return { value, done: false };
-            }
-          }
-        };
-      }
-    };
+    return this.events.lifecycle;
+  }
+  /** Coalescing iterator over `partial_object` events — yields the latest
+   *  object payload per `askId`. Designed for streaming-structured-output
+   *  UIs: when the producer outpaces the consumer, intermediate snapshots
+   *  are silently superseded and the next `.next()` await sees only the
+   *  most recent state per ask. Listener-based, so does NOT race with the
+   *  main `for await (const e of stream)` iterator. See
+   *  `AxlEventBus.partialObjects` for full semantics. The yielded
+   *  `CoalescedPartialObject` shape is shared with the bus so the two
+   *  surfaces can never drift on the `attempt` field. */
+  get partialObjects() {
+    return this.events.partialObjects;
   }
   pipe(destination, options) {
     const shouldEnd = options?.end !== false;
-    this.bus.on("token", (event) => {
+    this.events.on("token", (event) => {
       if (event.type === "token") destination.write(event.data);
     });
-    this.bus.on("done", () => {
+    this.events.on("done", () => {
       if (shouldEnd) destination.end();
     });
-    this.bus.on("error", () => {
+    this.events.on("error", () => {
       if (shouldEnd) destination.end();
     });
     return destination;
   }
-  /** Push an event onto the stream. Called by the runtime. */
+  /** Push an event onto the stream. Called by the runtime.
+   *
+   *  Side-effect ordering: `accountForToken` (fullText buffers) →
+   *  `events._push` (bus.emit + iterator waiter/queue) → `Readable.push`
+   *  (object-mode buffer for `.pipe()` consumers and `'data'` listeners).
+   *  Pre-refactor the order was `bus.emit → Readable.push → waiter/queue`;
+   *  the new order resolves async iterators before Readable.push. The
+   *  difference is invisible to all in-tree consumers — `.pipe()` here
+   *  routes through the bus's `'token'` listener (line 129), and existing
+   *  tests pass — but it's intentional rather than accidental. */
   _push(event) {
-    if (this.finished) return;
+    if (this.events.isFinished) return;
+    this.accountForToken(event);
+    this.events._push(event);
+    this.push(event);
+  }
+  /** Token accumulation and pipeline commit/discard accounting for
+   *  `fullText`. Extracted from `_push` so the bus delegation reads cleanly. */
+  accountForToken(event) {
     if (event.type === "token" && isRootLevel(event)) {
       const key = event.askId ?? "";
       const attempt = this.attemptByAsk.get(key);
@@ -6301,6 +6952,7 @@ var AxlStream = class _AxlStream extends import_node_stream.Readable {
       } else {
         this.attemptByAsk.set(key, [event.data]);
       }
+      return;
     }
     if (event.type === "pipeline" && isRootLevel(event)) {
       const key = event.askId ?? "";
@@ -6314,18 +6966,11 @@ var AxlStream = class _AxlStream extends import_node_stream.Readable {
       } else if (event.status === "failed") {
         this.attemptByAsk.set(key, []);
       }
+      return;
     }
     if (event.type === "ask_end" && isRootLevel(event) && !event.outcome.ok) {
       this.attemptByAsk.set(event.askId ?? "", []);
     }
-    this.bus.emit(event.type, event);
-    this.push(event);
-    const waiter = this.waiters.shift();
-    if (waiter) {
-      waiter({ value: event, done: false });
-    } else {
-      this.eventQueue.push(event);
-    }
   }
   /**
    * Signal successful completion.
@@ -6336,8 +6981,7 @@ var AxlStream = class _AxlStream extends import_node_stream.Readable {
    * on error paths that threw before `execInfo` was assigned (review S4).
    */
   _done(result, executionId) {
-    if (this.finished) return;
-    this.finished = true;
+    if (this.events.isFinished) return;
     this.result = result;
     const doneEvent = {
       type: "done",
@@ -6346,27 +6990,17 @@ var AxlStream = class _AxlStream extends import_node_stream.Readable {
       timestamp: Date.now(),
       data: { result }
     };
-    this.bus.emit("done", doneEvent);
+    this.events._push(doneEvent);
     this.push(doneEvent);
     this.push(null);
-    const waiter = this.waiters.shift();
-    if (waiter) {
-      waiter({ value: doneEvent, done: false });
-    } else {
-      this.eventQueue.push(doneEvent);
-    }
-    for (const w of this.waiters) {
-      w({ value: void 0, done: true });
-    }
-    this.waiters.length = 0;
-    this.bus.emit("__resolve", result);
+    this.events._finish();
+    this.resolvePromise(result);
   }
   /** Signal an error. `executionId` is required for the same reason as
    *  `_done`: terminal events must carry a real id even when the
    *  failure happens before any real trace event fires (review S4). */
   _error(error, executionId) {
-    if (this.finished) return;
-    this.finished = true;
+    if (this.events.isFinished) return;
     const errorEvent = {
       type: "error",
       executionId,
@@ -6374,20 +7008,11 @@ var AxlStream = class _AxlStream extends import_node_stream.Readable {
       timestamp: Date.now(),
       data: { message: error.message, name: error.name }
     };
-    this.bus.emit("error", errorEvent);
+    this.events._push(errorEvent);
     this.push(errorEvent);
     this.push(null);
-    const waiter = this.waiters.shift();
-    if (waiter) {
-      waiter({ value: errorEvent, done: false });
-    } else {
-      this.eventQueue.push(errorEvent);
-    }
-    for (const w of this.waiters) {
-      w({ value: void 0, done: true });
-    }
-    this.waiters.length = 0;
-    this.bus.emit("__reject", error);
+    this.events._finish();
+    this.rejectPromise(error);
   }
   /** Concatenated root-only text from committed attempts plus the
    *  current in-flight attempt(s). Retried (gate-rejected) attempts
@@ -6987,6 +7612,18 @@ function pushEventBounded(execInfo, event, cap) {
   }
 }
 var costScopeStorage = new import_node_async_hooks2.AsyncLocalStorage();
+function forwardAbortSignal(external, internal) {
+  if (!external) return () => {
+  };
+  if (external.aborted) {
+    internal.abort();
+    return () => {
+    };
+  }
+  const onAbort = () => internal.abort();
+  external.addEventListener("abort", onAbort, { once: true });
+  return () => external.removeEventListener("abort", onAbort);
+}
 var AxlRuntime = class extends import_node_events2.EventEmitter {
   config;
   workflows = /* @__PURE__ */ new Map();
@@ -7003,12 +7640,23 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
   spanManager = new NoopSpanManager();
   historicalExecutions = /* @__PURE__ */ new Map();
   historicalExecutionsLoadPromise = null;
+  /** Per-session in-process serialization. Each entry is a chain of pending
+   *  work for that session id — `Session.send` / `Session.stream` await the
+   *  prior entry before reading history, so concurrent calls produce a
+   *  sequenced conversation log instead of last-writer-wins corruption.
+   *  Cross-process locking is NOT provided; use distinct session ids when
+   *  multiple processes share a store. */
+  sessionLocks = /* @__PURE__ */ new Map();
   evalHistory = [];
   evalHistoryLoadPromise = null;
   /** Resolved cap on `ExecutionInfo.events` per execution. Cached on
    *  the instance so per-event onTrace handlers don't reach into
    *  `this.config.state` on every emission. */
   maxEventsPerExecution;
+  /** Tracks executionIds for which we've already warned about a malformed
+   *  `events` field — keeps the log to one line per row instead of one per
+   *  rebuild tick. */
+  warnedMalformedExecutions = /* @__PURE__ */ new Set();
   constructor(config) {
     super();
     this.config = resolveConfig(config ?? {});
@@ -7094,8 +7742,9 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
    * Side effects on `execInfo`: sets `status` / `completedAt` /
    * `duration` / `result` (or `error`) before emitting `workflow_end`.
    * On throw: emits `workflow_end({status: 'failed', aborted?})` and
-   * persists before rethrowing. `abortControllers.delete` runs in
-   * `finally` regardless of outcome.
+   * persists before rethrowing. `abortControllers.delete` and
+   * `cleanupAbortForwarder` (if provided) both run in `finally`
+   * regardless of outcome.
    *
    * Caller responsibilities:
    * - Allocate `executionId` and register it in `abortControllers` map
@@ -7105,9 +7754,13 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
    * - Pass `span` if the call site is inside a tracer span — this
    *   helper sets `axl.workflow.cost` / `.duration` attributes on
    *   success.
+   * - Pass `cleanupAbortForwarder` (the cleanup fn returned from
+   *   `forwardAbortSignal`) so the listener on the user's external
+   *   signal is removed when the workflow completes — see the
+   *   helper's docstring for the leak this prevents.
    */
   async runWorkflowBody(args) {
-    const { workflow: workflow2, ctx, execInfo, validated, span } = args;
+    const { workflow: workflow2, ctx, execInfo, validated, span, cleanupAbortForwarder } = args;
     try {
       ctx._emitWorkflowStart(validated);
       const raw = await workflow2.handler(ctx);
@@ -7144,6 +7797,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       throw err;
     } finally {
       this.abortControllers.delete(execInfo.executionId);
+      cleanupAbortForwarder?.();
     }
   }
   /**
@@ -7296,12 +7950,31 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
     return result;
   }
   /** Get all execution info (running + completed + historical). */
+  /** Normalize an `ExecutionInfo` loaded from a `StateStore` so the
+   *  `events: AxlEvent[]` type contract holds for downstream consumers
+   *  (Studio aggregators, REST routes, redaction). Custom or legacy stores
+   *  may persist rows without `events` (or with a non-array value) — without
+   *  this guard, a single malformed row crashes every iterator over
+   *  `exec.events` and takes down dependent features. Mutates the row
+   *  in place; logs at most one warning per `executionId`. */
+  normalizeStoredExecution(exec) {
+    if (!Array.isArray(exec.events)) {
+      if (!this.warnedMalformedExecutions.has(exec.executionId)) {
+        this.warnedMalformedExecutions.add(exec.executionId);
+        console.warn(
+          `[axl] StateStore returned execution ${exec.executionId} with non-array events (got ${exec.events === null ? "null" : typeof exec.events}); coercing to []`
+        );
+      }
+      exec.events = [];
+    }
+    return exec;
+  }
   async getExecutions() {
     if (!this.historicalExecutionsLoadPromise && this.stateStore.listExecutions) {
       this.historicalExecutionsLoadPromise = this.stateStore.listExecutions().then((stored) => {
         for (const exec of stored) {
           if (!this.executions.has(exec.executionId) && !this.historicalExecutions.has(exec.executionId)) {
-            this.historicalExecutions.set(exec.executionId, exec);
+            this.historicalExecutions.set(exec.executionId, this.normalizeStoredExecution(exec));
           }
         }
       }).catch(() => {
@@ -7342,6 +8015,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       onToolCall: options?.onToolCall,
       onAgentStart: options?.onAgentStart,
       awaitHumanHandler: options?.awaitHumanHandler,
+      eventStreamOptions: options?.events,
       onTrace: (event) => {
         this.emit("trace", event);
         this.outputAxlEvent(event);
@@ -7374,6 +8048,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
     const executionId = (0, import_node_crypto3.randomUUID)();
     const controller = new AbortController();
     this.abortControllers.set(executionId, controller);
+    const cleanupAbortForwarder = forwardAbortSignal(options?.signal, controller);
     this.registerWithCostScope(executionId);
     const execInfo = {
       executionId,
@@ -7394,6 +8069,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       providerRegistry: this.providerRegistry,
       sessionHistory,
       signal: controller.signal,
+      eventStreamOptions: options?.events,
       onTrace: (event) => {
         pushEventBounded(execInfo, event, this.maxEventsPerExecution);
         execInfo.totalCost += eventCostContribution(event);
@@ -7455,15 +8131,17 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         ctx,
         execInfo,
         validated,
-        span
+        span,
+        cleanupAbortForwarder
       })
     );
   }
   /** Execute a workflow and return a stream. */
   stream(name, input, options) {
-    const axlStream = new AxlStream();
+    const axlStream = new AxlStream(options?.events);
     const controller = new AbortController();
     axlStream.on("close", () => controller.abort());
+    const cleanupAbortForwarder = forwardAbortSignal(options?.signal, controller);
     const executionId = (0, import_node_crypto3.randomUUID)();
     this.abortControllers.set(executionId, controller);
     let execInfo;
@@ -7491,6 +8169,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         providerRegistry: this.providerRegistry,
         sessionHistory,
         signal: controller.signal,
+        eventStreamOptions: options?.events,
         // Sentinel `onToken` so the streaming code path in WorkflowContext
         // is entered (it's gated on `this.onToken` being defined). The
         // actual `token` AxlEvents are emitted via `emitEvent` and reach
@@ -7559,7 +8238,8 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
           ctx: wfCtx,
           execInfo,
           validated,
-          span
+          span,
+          cleanupAbortForwarder
         })
       );
     };
@@ -7572,6 +8252,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         this.persistExecution(execInfo);
       }
       this.abortControllers.delete(executionId);
+      cleanupAbortForwarder();
       axlStream._error(err instanceof Error ? err : new Error(String(err)), executionId);
     });
     return axlStream;
@@ -7580,12 +8261,55 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
   session(id, options) {
     return new Session(id, this, this.stateStore, options);
   }
-  /** Gracefully shut down the runtime, aborting in-flight executions and closing state stores and MCP servers. */
+  /** @internal Serialize work per session id within this runtime instance.
+   *  Subsequent calls await the prior task's settlement (success or failure)
+   *  before running. Used by `Session.send` / `Session.stream` / `end` /
+   *  `fork` to eliminate read-modify-write races on `StateStore.saveSession`
+   *  (and on `delete`/`getSession` ordering vs in-flight saves).
+   *
+   *  ⚠️ NOT REENTRANT. Calling this from inside an `fn` already running
+   *  under `_serializeSession(sameId, ...)` will deadlock — the inner
+   *  call awaits the outer's settlement, the outer awaits the inner's
+   *  return. `Session.fork` deliberately calls with TWO different ids
+   *  (source and target) and never the same id twice. Any future caller
+   *  must follow the same rule. */
+  async _serializeSession(id, fn) {
+    const prev = this.sessionLocks.get(id);
+    if (prev !== void 0) {
+      this.emit("session_lock_contended", { sessionId: id });
+    }
+    const base = prev ?? Promise.resolve();
+    const ours = base.then(fn, fn);
+    const chained = ours.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    this.sessionLocks.set(id, chained);
+    void chained.finally(() => {
+      if (this.sessionLocks.get(id) === chained) {
+        this.sessionLocks.delete(id);
+      }
+    });
+    return ours;
+  }
+  /** Gracefully shut down the runtime, aborting in-flight executions and
+   *  closing state stores and MCP servers. Drains in-flight per-session
+   *  work (Session.send / Session.stream) before closing the state store.
+   *
+   *  This is a drain of EXISTING work, not a barrier against new calls —
+   *  callers should stop accepting work (e.g., close their HTTP server)
+   *  before invoking `shutdown()`. A `Session.send` invoked after the
+   *  drain snapshot is taken can still race a closed state store. */
   async shutdown() {
     for (const [, controller] of this.abortControllers) {
       controller.abort();
     }
     this.abortControllers.clear();
+    if (this.sessionLocks.size > 0) {
+      await Promise.allSettled([...this.sessionLocks.values()]);
+    }
     const errors = [];
     const safeClose = async (label, fn) => {
       try {
@@ -7621,8 +8345,9 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
     if (this.stateStore.getExecution) {
       const stored = await this.stateStore.getExecution(executionId);
       if (stored) {
-        this.historicalExecutions.set(executionId, stored);
-        return stored;
+        const normalized = this.normalizeStoredExecution(stored);
+        this.historicalExecutions.set(executionId, normalized);
+        return normalized;
       }
     }
     return void 0;
@@ -8112,7 +8837,14 @@ async function ensureTsxRegistered() {
   return tsxRegistered;
 }
 async function importModule(filePath, _parentURL) {
-  if (needsTsxLoader(filePath)) {
+  const url = (0, import_node_url.pathToFileURL)(filePath).href;
+  if (!needsTsxLoader(filePath)) {
+    return await import(url);
+  }
+  try {
+    return await import(url);
+  } catch (err) {
+    if (!isMissingLoaderError(err)) throw err;
     const registered = await ensureTsxRegistered();
     if (!registered) {
       throw new Error(
@@ -8122,8 +8854,14 @@ async function importModule(filePath, _parentURL) {
   disabled, install it explicitly: npm install -D tsx`
       );
     }
+    return await import(url);
   }
-  return await import((0, import_node_url.pathToFileURL)(filePath).href);
+}
+function isMissingLoaderError(err) {
+  if (!(err instanceof Error)) return false;
+  const code = err.code;
+  if (code === "ERR_UNKNOWN_FILE_EXTENSION") return true;
+  return /Cannot use import statement outside a module/i.test(err.message);
 }
 var MAX_GLOB_DEPTH = 20;
 function expandGlob(pattern, cwd) {
@@ -8536,11 +9274,13 @@ function cosineSimilarity2(a, b) {
   AXL_EVENT_TYPES,
   AnthropicProvider,
   AxlError,
+  AxlEventBus,
   AxlRuntime,
   AxlStream,
   BudgetExceededError,
   CONFIG_CANDIDATES,
   COST_BEARING_LEAF_TYPES,
+  EventStreamOverflowError,
   GeminiProvider,
   GuardrailError,
   InMemoryVectorStore,