@axlsdk/axl 0.17.2 → 0.17.4

package/dist/index.d.cts

@@ -863,6 +863,18 @@ type ChatMessage = {
     tool_call_id?: string;
     /** Provider-specific opaque metadata that must round-trip through conversation history. */
     providerMetadata?: Record<string, unknown>;
+    /** Name of the agent that produced this message. Populated on `assistant`
+     *  messages committed via `ctx.ask()`; absent on `user` messages and on
+     *  assistant messages pushed by external callers (e.g., the
+     *  `Session.send` fallback when no agent context is available).
+     *
+     *  This is observability metadata only — it is NOT sent on the wire to
+     *  any provider. Provider adapters cherry-pick the fields they need
+     *  (`role`, `content`, `name`, `tool_calls`, `tool_call_id`) and ignore
+     *  the rest. Future per-agent history filtering may consume this field
+     *  (the option name and shape are not yet stable); today it is purely
+     *  informational. */
+    agent?: string;
 };
 type ToolCallMessage = {
     id: string;
@@ -949,6 +961,290 @@ type Agent = {
  */
 declare function agent(config: AgentConfig): Agent;
 
+/** Options shared between `AxlEventBus` (and therefore `AxlStream` and
+ *  `ctx.events`). Controls the overflow safety net on the iterator queue. */
+interface EventStreamOptions {
+    /** Soft cap on the number of events held in the iterator queue while
+     *  waiting for a consumer. Terminal events (`done`, `error`,
+     *  `workflow_end`) are exempt and always pass through. Default 10_000.
+     *
+     *  Set to `Infinity` to disable the cap (matches pre-0.x behavior). */
+    maxQueued?: number;
+    /** Policy when an event arrives and the queue is at `maxQueued`.
+     *
+     *  - `'drop-oldest-non-terminal'` (default): scan the queue head-to-tail,
+     *    splice out the oldest non-terminal event, push the new one. The first
+     *    drop per bus instance fires a one-shot `console.warn` so saturating
+     *    consumers see the signal without log spam.
+     *  - `'throw'`: throw an `EventStreamOverflowError` at the producer call
+     *    site. **This will fail the active workflow** — `_push` is called
+     *    from `WorkflowContext.emitEvent`, which runs inside `ctx.ask()` /
+     *    `runtime.execute()`. The throw unwinds the agent loop and the
+     *    `runtime.execute()` (or `runtime.stream()`) promise rejects with
+     *    the typed error. Useful in tests or strict environments where
+     *    silent drop would mask a problem; not the right default for
+     *    production where a slow consumer should degrade gracefully rather
+     *    than abort the workflow. Catch with `instanceof
+     *    EventStreamOverflowError` to distinguish from other workflow
+     *    errors.
+     *
+     *  `'block'` is intentionally absent: `_push` is synchronous and there's no
+     *  producer to suspend. To bound queue growth via backpressure, the
+     *  producer side has to model it explicitly (out of scope for v1). */
+    onOverflow?: 'drop-oldest-non-terminal' | 'throw';
+}
+/**
+ * The shape yielded by `AxlEventBus.partialObjects` (and `AxlStream.partialObjects`).
+ * Coalesced latest-per-`askId` snapshot of a `partial_object` event.
+ *
+ * `attempt` is the 1-indexed attempt number from the underlying
+ * `partial_object` event — pinned in the public type so consumers can
+ * conditionally render a "regenerating" indicator when it jumps from 1
+ * to 2. Failed attempts are dropped from the view via the
+ * `pipeline(failed)` listener before they leak across the retry
+ * boundary.
+ */
+type CoalescedPartialObject = {
+    askId: string;
+    agent?: string;
+    object: unknown;
+    attempt: number;
+};
+/**
+ * Thrown when an `AxlEventBus` queue exceeds `maxQueued` and `onOverflow`
+ * is set to `'throw'`. Surfaced as a typed error so the runtime's emit
+ * pipeline can distinguish a legitimate overflow signal (which must
+ * propagate to fail the workflow) from a buggy trace-listener exception
+ * (which gets swallowed).
+ *
+ * Consumers using `instanceof` to handle overflow specifically:
+ * ```typescript
+ * try {
+ *   await runtime.execute('wf', input, { events: { onOverflow: 'throw' } });
+ * } catch (err) {
+ *   if (err instanceof EventStreamOverflowError) {
+ *     // overflow — back off, retry, or surface to user
+ *   }
+ * }
+ * ```
+ */
+declare class EventStreamOverflowError extends Error {
+    readonly maxQueued: number;
+    readonly eventType: string;
+    constructor(maxQueued: number, eventType: string);
+}
+/**
+ * Iterable + EventEmitter event bus carrying `AxlEvent`.
+ *
+ * Public observation surface for `ctx.events` and the underlying machinery
+ * for `AxlStream`. Provides:
+ *
+ *  - `for await (const e of bus)` — sequential iteration over every pushed event
+ *  - `.on('agent_call_end', fn)` / `.off(...)` — EventEmitter style, gated on
+ *    `AXL_EVENT_TYPES` so unknown event names cannot be subscribed
+ *  - Curated views: `.text` (root-only token chunks), `.lifecycle` (structural
+ *    events only), `.textByAsk` (per-ask token chunks)
+ *
+ * Multiple async iterators on the same bus race for the same FIFO queue —
+ * iterating both `bus` and `bus.text` (or `bus.lifecycle` / `bus.textByAsk`)
+ * concurrently will see each event at most once because the views pull from
+ * the same underlying iterator. For two independent observers, attach
+ * `.on(type, handler)` listeners instead — those each receive every event.
+ *
+ * Multiple `.on()` listeners on the same event type each receive every
+ * matching event. Subscriptions to non-`AxlEventType` names are silently
+ * dropped (the bus emits no other event names).
+ */
+declare class AxlEventBus implements AsyncIterable<AxlEvent> {
+    protected readonly bus: EventEmitter<any>;
+    protected eventQueue: AxlEvent[];
+    protected waiters: Array<(value: IteratorResult<AxlEvent>) => void>;
+    protected finished: boolean;
+    private readonly maxQueued;
+    private readonly onOverflow;
+    private overflowWarned;
+    /** 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. */
+    private 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.
+     */
+    private latestPartialByAsk;
+    /**
+     * 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
+     */
+    protected readonly onIteratorDispose?: () => void;
+    /**
+     * @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?: EventStreamOptions, onIteratorDispose?: () => void);
+    private unknownEventWarned;
+    /** Subscribe to an `AxlEvent` variant by type. Names outside
+     *  `AXL_EVENT_TYPES` are dropped (the bus only emits those names) but
+     *  the first such call per bus instance fires a one-shot
+     *  `console.warn` so a typo (`'agent_call_ended'`) doesn't silently
+     *  vanish. Subclasses (e.g., `AxlStream`) pre-filter via
+     *  `knowsEventName` so their own routing for non-`AxlEvent` names
+     *  like `'close'` doesn't trip the warn. */
+    on<T extends AxlEventType>(event: T, handler: (e: AxlEventOf<T>) => void): this;
+    on(event: string, handler: (event: any) => void): this;
+    off<T extends AxlEventType>(event: T, handler: (e: AxlEventOf<T>) => void): this;
+    off(event: string, handler: (event: any) => void): 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. */
+    private warnUnknownEventName;
+    [Symbol.asyncIterator](): {
+        next: () => Promise<IteratorResult<AxlEvent>>;
+        return: () => Promise<IteratorResult<AxlEvent>>;
+        [Symbol.asyncIterator](): /*elided*/ any;
+        [Symbol.asyncDispose]: () => Promise<void>;
+    };
+    /** 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. */
+    protected _disposeIterator(): Promise<void>;
+    /** 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(): AsyncIterable<string>;
+    /** 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(): AsyncIterable<{
+        askId: string;
+        agent?: string;
+        text: string;
+    }>;
+    /**
+     * 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(): AsyncIterable<CoalescedPartialObject>;
+    /** 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(): AsyncIterable<AxlEvent>;
+    /**
+     * 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: AxlEvent): void;
+    /** 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). */
+    private handleOverflow;
+    /**
+     * 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(): void;
+    /** 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: () => void): () => void;
+    /** 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: string): boolean;
+    /** Whether `_finish()` has been called. */
+    get isFinished(): boolean;
+}
+
 /** A pending human decision awaiting resolution. */
 type PendingDecision = {
     executionId: string;
@@ -1522,6 +1818,22 @@ type WorkflowContextInit = {
     }, meta: CallbackMeta) => void;
     /** Callback fired after each ctx.ask() completes (once per ask invocation). */
     onAgentCallComplete?: (call: AgentCallInfo) => void;
+    /** Options for the lazy `ctx.events` `AxlEventBus`. Forwarded by
+     *  `runtime.createContext({ events })` / `runtime.execute(name, input,
+     *  { events })` / `runtime.stream(name, input, { events })`. If unset,
+     *  the bus uses its built-in defaults (`maxQueued: 10_000`,
+     *  `onOverflow: 'drop-oldest-non-terminal'`). Child contexts share the
+     *  parent's bus instance, so this option has no effect on
+     *  `createChildContext()` callers. */
+    eventStreamOptions?: EventStreamOptions;
+    /** Internal: shared mutable holder for the lazy `AxlEventBus`. Set by
+     *  `createChildContext` so parent + children read and write the same
+     *  slot — late allocation in the parent (after children exist) is
+     *  visible to those children, and child allocation is visible to the
+     *  parent. Direct callers should not pass this. */
+    _busRef?: {
+        current: AxlEventBus | undefined;
+    };
     /** Internal: shared auto-checkpoint counters. Set by `createChildContext`
      *  so parent + child share the same number space, preventing checkpoint
      *  store key collisions across nested `WorkflowContext` instances.
@@ -1602,6 +1914,90 @@ declare class WorkflowContext<TInput = unknown> {
     private awaitHumanHandler?;
     private onAgentStart?;
     private 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). */
+    private readonly _busRef;
+    private readonly _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). */
+    private 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(): AxlEventBus;
+    /** 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(): void;
+    /** 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. */
+    private get _streamingEnabled();
     constructor(init: WorkflowContextInit);
     /**
      * Create a child context for nested agent invocations (e.g., agent-as-tool).
@@ -1646,7 +2042,8 @@ declare class WorkflowContext<TInput = unknown> {
     private executeAgentCall;
     /**
      * 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.
      */
     private pushAssistantToSessionHistory;
     private buildToolDefs;
@@ -1891,27 +2288,38 @@ declare function workflow<TInput extends z.ZodType, TOutput extends z.ZodType =
 /**
  * A streamable workflow execution.
  *
- * Extends Node's Readable and implements `AsyncIterable<AxlEvent>`. Supports
- * `.on()` events, `for-await-of`, the `.text` iterator (root-only tokens),
- * the `.lifecycle` iterator (structural events only), and `.pipe()`.
+ * Extends Node's `Readable` and implements `AsyncIterable<AxlEvent>` via a
+ * composed `AxlEventBus`. Supports `.on()` events, `for-await-of`, the
+ * `.text` iterator (root-only tokens), the `.lifecycle` iterator (structural
+ * events only), the `.textByAsk` iterator (per-ask token chunks), and `.pipe()`.
  *
  * The wire carries `AxlEvent` directly — there is no per-stream synthesized
  * shape. Consumers narrow on `event.type` and use `AskScoped` fields
  * (`askId`, `parentAskId`, `depth`) for routing/filtering.
- */
-declare class AxlStream extends Readable {
-    private bus;
-    /**
-     * 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.
+ *
+ * The underlying `AxlEventBus` is shared with `ctx.events` — both surfaces
+ * expose the same iterator/EventEmitter contract over the same `AxlEvent`
+ * union. AxlStream layers on top: Readable backpressure shape, terminal
+ * `done`/`error` synthesis, `.pipe()`, and per-ask `fullText` token
+ * accounting (which is stream-specific because the runtime emits the
+ * structured `pipeline` events that drive commit/discard).
+ */
+declare class AxlStream extends Readable implements AsyncIterable<AxlEvent> {
+    /** Composed event bus — owns iterator queue, EventEmitter gating, and
+     *  curated views (`.text`, `.lifecycle`, `.textByAsk`). Private; the
+     *  public surface is via the delegating methods below. */
+    private readonly 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.
      *
      * On `pipeline(status: 'committed')` for an ask, that ask's
      * in-progress entry flushes to its committed entry. On
@@ -1925,52 +2333,54 @@ declare class AxlStream extends Readable {
     private attemptByAsk;
     private committedByAsk;
     private result;
-    private finished;
     readonly promise: Promise<unknown>;
-    private eventQueue;
-    private waiters;
-    constructor();
-    /** 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. */
-    private static readonly STREAM_EVENTS;
-    on(event: string, handler: (...args: unknown[]) => void): this;
-    off(event: string, handler: (...args: unknown[]) => void): this;
+    private resolvePromise;
+    private rejectPromise;
+    constructor(options?: EventStreamOptions);
+    on<T extends AxlEventType>(event: T, handler: (e: AxlEventOf<T>) => void): this;
+    on(event: string, handler: (...args: any[]) => void): this;
+    off<T extends AxlEventType>(event: T, handler: (e: AxlEventOf<T>) => void): this;
+    off(event: string, handler: (...args: any[]) => void): this;
     [Symbol.asyncIterator](): {
         next: () => Promise<IteratorResult<AxlEvent>>;
+        return: () => Promise<IteratorResult<AxlEvent>>;
         [Symbol.asyncIterator](): /*elided*/ any;
-        [Symbol.asyncDispose](): Promise<void>;
+        [Symbol.asyncDispose]: () => Promise<void>;
     };
     get text(): AsyncIterable<string>;
-    /**
-     * 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(): AsyncIterable<{
         askId: string;
         agent?: string;
         text: string;
     }>;
-    /**
-     * 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(): AsyncIterable<AxlEvent>;
+    /** 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(): AsyncIterable<CoalescedPartialObject>;
     pipe<T extends NodeJS.WritableStream>(destination: T, options?: {
         end?: boolean;
     }): T;
-    /** 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: AxlEvent): void;
+    /** Token accumulation and pipeline commit/discard accounting for
+     *  `fullText`. Extracted from `_push` so the bus delegation reads cleanly. */
+    private accountForToken;
     /**
      * Signal successful completion.
      *
@@ -2017,6 +2427,18 @@ type SessionOptions = {
 /**
  * A stateful conversation session.
  * Persists message history across multiple interactions.
+ *
+ * **Concurrency contract:** `send`, `stream`, `end`, and `fork` are
+ * serialized per session id within one runtime instance. Two
+ * `runtime.session('x')` handles share the same lock (it lives on
+ * `AxlRuntime`, not the `Session` instance). `history()` and
+ * `handoffs()` bypass the lock and return the last persisted snapshot.
+ *
+ * **⚠️ Cross-process locking is NOT provided.** Multiple Node workers
+ * behind a load balancer hitting the same Redis-backed `sessionId`
+ * will still race. Pin sessions to workers (sticky routing) or use
+ * distinct ids per request. See `docs/api-reference.md` →
+ * Sessions → Concurrency.
  */
 declare class Session {
     private sessionId;
@@ -2026,13 +2448,36 @@ declare class Session {
     private options;
     constructor(sessionId: string, runtime: AxlRuntime, store: StateStore, options?: SessionOptions);
     get id(): string;
-    send(workflowName: string, input: unknown): Promise<unknown>;
-    stream(workflowName: string, input: unknown): Promise<AxlStream>;
+    send(workflowName: string, input: unknown, options?: {
+        signal?: AbortSignal;
+        events?: EventStreamOptions;
+    }): Promise<unknown>;
+    private sendImpl;
+    /** 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. */
+    private prepareHistory;
+    /** 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. */
+    private commitHistory;
+    stream(workflowName: string, input: unknown, options?: {
+        signal?: AbortSignal;
+        events?: EventStreamOptions;
+    }): Promise<AxlStream>;
+    private streamImpl;
     history(): Promise<ChatMessage[]>;
     /** Get the handoff history for this session. */
     handoffs(): Promise<HandoffRecord[]>;
     end(): Promise<void>;
-    fork(newId: string): Promise<Session>;
+    fork(newId: string, options?: {
+        overwrite?: boolean;
+    }): Promise<Session>;
 }
 
 /**
@@ -2059,6 +2504,17 @@ type ExecuteOptions = {
      *  Useful for in-process testing and ad-hoc invocations where you don't want to poll
      *  `runtime.getPendingDecisions()` and call `runtime.resolveDecision()`. */
     awaitHumanHandler?: (options: AwaitHumanOptions) => Promise<HumanDecision>;
+    /** External AbortSignal. When fired, aborts the workflow exactly as
+     *  `runtime.abort(executionId)` would. Lets callers use the standard
+     *  JS cancellation pattern (e.g., AbortController from a UI's "stop"
+     *  button) without having to track the execution id. */
+    signal?: AbortSignal;
+    /** Configuration for the workflow context's `ctx.events` bus and the
+     *  `AxlStream` returned by `runtime.stream()`. Both consume the same
+     *  `EventStreamOptions` (queue cap + overflow policy). When omitted,
+     *  defaults are `maxQueued: 10_000` and `onOverflow:
+     *  'drop-oldest-non-terminal'`. */
+    events?: EventStreamOptions;
 };
 /**
  * Shape of events forwarded to an eval `onProgress` callback. Mirrors
@@ -2101,6 +2557,10 @@ type CreateContextOptions = {
     }, meta: CallbackMeta) => void;
     /** Handler for tool approval requests. Called when an agent invokes a tool with requireApproval. */
     awaitHumanHandler?: (options: AwaitHumanOptions) => Promise<HumanDecision>;
+    /** Configuration for the lazy `ctx.events` bus on the returned context.
+     *  Defaults: `maxQueued: 10_000`, `onOverflow:
+     *  'drop-oldest-non-terminal'`. */
+    events?: EventStreamOptions;
 };
 /**
  * The main entry point for executing Axl workflows.
@@ -2124,12 +2584,23 @@ declare class AxlRuntime extends EventEmitter {
     private spanManager;
     private historicalExecutions;
     private historicalExecutionsLoadPromise;
+    /** 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. */
+    private sessionLocks;
     private evalHistory;
     private evalHistoryLoadPromise;
     /** 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. */
     private readonly 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. */
+    private warnedMalformedExecutions;
     constructor(config?: AxlConfig);
     /**
      * Whether `config.trace.redact` is enabled on this runtime. A narrow
@@ -2171,8 +2642,9 @@ declare class AxlRuntime extends 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
@@ -2182,6 +2654,10 @@ declare class AxlRuntime extends 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.
      */
     private runWorkflowBody;
     /**
@@ -2245,6 +2721,14 @@ declare class AxlRuntime extends EventEmitter {
         captureTraces?: boolean;
     }): Promise<unknown>;
     /** 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`. */
+    private normalizeStoredExecution;
     getExecutions(): Promise<ExecutionInfo[]>;
     /**
      * Create a WorkflowContext for ad-hoc use (evals, tool testing, prototyping).
@@ -2265,7 +2749,27 @@ declare class AxlRuntime extends EventEmitter {
     stream(name: string, input: unknown, options?: ExecuteOptions): AxlStream;
     /** Create or resume a session. */
     session(id: string, options?: SessionOptions): Session;
-    /** 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. */
+    _serializeSession<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    /** 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. */
     shutdown(): Promise<void>;
     /** Abort a running execution by its ID. */
     abort(executionId: string): void;
@@ -3231,4 +3735,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { AXL_EVENT_TYPES, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type AskOptions, type AskScoped, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, type AxlEventOf, type AxlEventType, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallbackMeta, type ChatMessage, type ChatOptions, type CheckpointEventData, type CreateContextOptions, type DelegateData, type DelegateOptions, type Effort, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type ExecuteOptions, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RecallOptions, type RecallResult, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, type SchemaCheckData, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type TelemetryConfig, TimeoutError, type Tool, type ToolApprovalData, type ToolCallData, type ToolCallMessage, type ToolCallStartData, type ToolChoice, type ToolConfig, ToolDenied, type ToolDeniedData, type ToolHooks, type ValidateData, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, type VerifyData, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndData, type WorkflowStartData, agent, createSpanManager, defineConfig, eventCostContribution, expandGlob, extractJson, findConfig, importModule, isCostBearingLeaf, isRootLevel, needsTsxLoader, parsePartialJson, pickDefault, pickExport, redactEvent, registerConditions, resolveRuntime, resolveThinkingOptions, tool, workflow, zodToJsonSchema };
+export { AXL_EVENT_TYPES, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type AskOptions, type AskScoped, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallbackMeta, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, type DelegateData, type DelegateOptions, type Effort, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type EventStreamOptions, EventStreamOverflowError, type ExecuteOptions, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RecallOptions, type RecallResult, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, type SchemaCheckData, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type TelemetryConfig, TimeoutError, type Tool, type ToolApprovalData, type ToolCallData, type ToolCallMessage, type ToolCallStartData, type ToolChoice, type ToolConfig, ToolDenied, type ToolDeniedData, type ToolHooks, type ValidateData, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, type VerifyData, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndData, type WorkflowStartData, agent, createSpanManager, defineConfig, eventCostContribution, expandGlob, extractJson, findConfig, importModule, isCostBearingLeaf, isRootLevel, needsTsxLoader, parsePartialJson, pickDefault, pickExport, redactEvent, registerConditions, resolveRuntime, resolveThinkingOptions, tool, workflow, zodToJsonSchema };