@axlsdk/axl 0.15.0 → 0.16.0

package/dist/index.d.ts

@@ -274,96 +274,114 @@ type RaceOptions<T = unknown> = {
 };
 /** Execution status */
 type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
-/** Trace event type. See `TraceEvent` for per-type data shapes. */
-type TraceEventType = 'agent_call' | 'tool_call' | 'verify' | 'handoff' | 'delegate' | 'tool_denied' | 'tool_approval' | 'log' | 'workflow_start' | 'workflow_end' | 'guardrail' | 'schema_check' | 'validate';
-/** Data shape for `agent_call` trace events. Populated on every LLM call (pass or fail). */
-type AgentCallTraceData = {
+/**
+ * Canonical list of `AxlEvent.type` discriminators. Single source of truth —
+ * derive `AxlEventType` from this tuple and use it to validate stream filters,
+ * redaction tables, and exhaustiveness assertions.
+ */
+declare const AXL_EVENT_TYPES: readonly ["workflow_start", "workflow_end", "ask_start", "ask_end", "agent_call_start", "agent_call_end", "token", "tool_call_start", "tool_call_end", "tool_approval", "tool_denied", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "verify", "log", "memory_remember", "memory_recall", "memory_forget", "checkpoint_save", "checkpoint_replay", "await_human", "await_human_resolved", "guardrail", "schema_check", "validate", "done", "error"];
+/** Discriminator union derived from `AXL_EVENT_TYPES`. */
+type AxlEventType = (typeof AXL_EVENT_TYPES)[number];
+/** Resolved model parameters sent to the provider for an LLM call. */
+type AgentCallParams = {
+    temperature?: number;
+    maxTokens?: number;
+    effort?: Effort;
+    thinkingBudget?: number;
+    includeThoughts?: boolean;
+    toolChoice?: ToolChoice;
+    stop?: string[];
+};
+/**
+ * Data shape for `agent_call_start` events — the **request** side of the call.
+ * Everything here is known at the moment the call is dispatched, before the
+ * provider responds. Consumers can render "what's being asked" without waiting
+ * for completion.
+ */
+type AgentCallStartData = {
     /** Original user prompt passed to `ctx.ask()`. Does not include retry feedback or tool results. */
     prompt: string;
-    /** Final LLM response content for this turn. */
-    response: string;
     /** Resolved system prompt (after evaluating dynamic system selectors). */
     system?: string;
-    /** Reasoning/thinking content returned by the provider, when available. */
-    thinking?: string;
     /** Resolved model parameters sent to the provider for this call. */
-    params?: {
-        temperature?: number;
-        maxTokens?: number;
-        effort?: Effort;
-        thinkingBudget?: number;
-        includeThoughts?: boolean;
-        toolChoice?: ToolChoice;
-        stop?: string[];
-    };
+    params?: AgentCallParams;
     /** 1-indexed iteration of the tool-calling loop for this `ctx.ask()` call. */
-    turn?: number;
+    turn: number;
     /** When set, this call is a retry triggered by a failed gate check on the previous turn. */
     retryReason?: 'schema' | 'validate' | 'guardrail';
+    /** Names of tools exposed to the model on this call. Empty/omitted when no tools are bound. */
+    toolNames?: string[];
     /** Full ChatMessage[] sent to the provider this turn. Only populated when `trace.level === 'full'`. */
     messages?: ChatMessage[];
 };
-/** Data shape for `guardrail` trace events. */
-type GuardrailTraceData = {
-    guardrailType: 'input' | 'output';
-    blocked: boolean;
-    reason?: string;
-    /** 1-indexed attempt count (output guardrails only). */
-    attempt?: number;
-    /** Maximum attempts allowed before the guardrail throws. */
-    maxAttempts?: number;
-    /** The exact corrective message about to be injected into the conversation — only set when
-     *  this check failed and a retry is happening. Gives users visibility into what the LLM sees
-     *  between retry attempts. */
-    feedbackMessage?: string;
+/**
+ * Data shape for `agent_call_end` events — the **response** side of the call.
+ * Populated when the provider returns (success or recoverable failure). The
+ * companion request-side payload lives on the matching `agent_call_start`.
+ *
+ * Pair invariant: every `agent_call_start` is followed by exactly one
+ * `agent_call_end`, even on provider error. On the error path `response` is
+ * empty and `error` carries the provider's message; cost/tokens/duration are
+ * still emitted (top-level on the event) when partial usage is available.
+ */
+type AgentCallEndData = {
+    /** Final LLM response content for this turn. Empty string on error. */
+    response: string;
+    /** Reasoning/thinking content returned by the provider, when available. */
+    thinking?: string;
+    /** 1-indexed iteration of the tool-calling loop. Mirrors the matching `agent_call_start.data.turn`. */
+    turn: number;
+    /** Mirrors `agent_call_start.data.retryReason` so cost-attribution consumers
+     *  reading `agent_call_end` (cost lives here) can bucket without joining. */
+    retryReason?: 'schema' | 'validate' | 'guardrail';
+    /** Provider error message when the call threw (network failure, 4xx/5xx,
+     *  abort, etc). Mutually exclusive with `response` content. Subject to
+     *  `config.trace.redact` (vendor errors can echo prompt text). */
+    error?: string;
 };
-/** Data shape for `schema_check` trace events. Emitted on every schema parse (pass or fail). */
-type SchemaCheckTraceData = {
-    valid: boolean;
-    reason?: string;
-    attempt: number;
-    maxAttempts: number;
-    feedbackMessage?: string;
+/** Data shape for `tool_call_end` events. */
+type ToolCallData = {
+    args: unknown;
+    result: unknown;
+    callId?: string;
 };
-/** Data shape for `validate` trace events (post-schema business rule validation). */
-type ValidateTraceData = {
-    valid: boolean;
-    reason?: string;
-    attempt: number;
-    maxAttempts: number;
-    feedbackMessage?: string;
+/** Data shape for `tool_call_start` events. */
+type ToolCallStartData = {
+    args: unknown;
 };
-/** Data shape for `tool_approval` trace events. Emitted by the approval gate on both outcomes. */
-type ToolApprovalTraceData = {
+/** Data shape for `tool_approval` events. Emitted by the approval gate on both outcomes. */
+type ToolApprovalData = {
     approved: boolean;
     args: unknown;
     reason?: string;
 };
-/** Data shape for `tool_call` trace events. */
-type ToolCallTraceData = {
-    args: unknown;
-    result: unknown;
+/** Data shape for `tool_denied` events. Emitted when the LLM names a tool the agent doesn't expose. */
+type ToolDeniedData = {
+    args?: unknown;
+    reason?: string;
     callId?: string;
 };
-/** Data shape for `handoff` trace events. */
-type HandoffTraceData = {
+/** Data shape for `handoff_start` events (always emitted, pre-transition). */
+type HandoffStartData = {
+    source: string;
     target: string;
     mode: 'oneway' | 'roundtrip';
-    /** Wall-clock ms from handoff_to_X tool call to target agent completion.
-     *  Always emitted — the event only fires at the terminal point of the
-     *  handoff, so we always have a measurement. */
-    duration: number;
-    /** Source agent that initiated the handoff (mirrors the event's `agent` field
-     *  for convenience — lets consumers query the handoff chain without
-     *  stitching together event.agent and data.target). */
-    source?: string;
     /** The `message` arg the source agent passed when invoking `handoff_to_X`
-     *  (roundtrip mode only). Gives observability into *why* the source chose
-     *  to delegate. Subject to `config.trace.redact`. */
+     *  (roundtrip mode only). Subject to `config.trace.redact`. */
     message?: string;
 };
-/** Data shape for `delegate` trace events. */
-type DelegateTraceData = {
+/** Data shape for `handoff_return` events (roundtrip-only, post-return).
+ *  The returned value itself is observable via the target ask's
+ *  `ask_end.outcome`; this event marks the control transfer back to the
+ *  source agent and carries the round-trip duration. */
+type HandoffReturnData = {
+    source: string;
+    target: string;
+    /** Wall-clock ms from `handoff_start` emission to control returning. */
+    duration: number;
+};
+/** Data shape for `delegate` events. */
+type DelegateData = {
     candidates: string[];
     /** Set when the decision is known at emission time (single-agent short-circuit). */
     selected?: string;
@@ -372,20 +390,45 @@ type DelegateTraceData = {
     /** Why this delegate was emitted: 'routed' (multi-agent) or 'single_candidate'. */
     reason: 'routed' | 'single_candidate';
 };
-/** Data shape for `verify` trace events. */
-type VerifyTraceData = {
+/** Data shape for `verify` events. */
+type VerifyData = {
     attempts: number;
     passed: boolean;
     lastError?: string;
 };
-/** Data shape for `workflow_start` trace events. Emitted once per workflow execution. */
-type WorkflowStartTraceData = {
+/** Data shape for legacy `guardrail` events. Replaced by `pipeline` in PR 2. */
+type GuardrailData = {
+    guardrailType: 'input' | 'output';
+    blocked: boolean;
+    reason?: string;
+    attempt?: number;
+    maxAttempts?: number;
+    feedbackMessage?: string;
+};
+/** Data shape for legacy `schema_check` events. Replaced by `pipeline` in PR 2. */
+type SchemaCheckData = {
+    valid: boolean;
+    reason?: string;
+    attempt: number;
+    maxAttempts: number;
+    feedbackMessage?: string;
+};
+/** Data shape for legacy `validate` events. Replaced by `pipeline` in PR 2. */
+type ValidateData = {
+    valid: boolean;
+    reason?: string;
+    attempt: number;
+    maxAttempts: number;
+    feedbackMessage?: string;
+};
+/** Data shape for `workflow_start` events. Emitted once per workflow execution. */
+type WorkflowStartData = {
     /** The validated input passed to the workflow handler. */
     input: unknown;
 };
-/** Data shape for `workflow_end` trace events. Emitted once per workflow execution
+/** Data shape for `workflow_end` events. Emitted once per workflow execution
  *  on completion, failure, or cancellation. Distinguish cancellation via `aborted`. */
-type WorkflowEndTraceData = {
+type WorkflowEndData = {
     status: 'completed' | 'failed';
     duration: number;
     /** Workflow return value. Present on `status: 'completed'`. */
@@ -396,78 +439,328 @@ type WorkflowEndTraceData = {
      *  or consumer disconnect on streaming workflows). */
     aborted?: boolean;
 };
-/** Common fields carried by every `TraceEvent` regardless of `type`. */
-type TraceEventBase = {
+/** Data shape for `checkpoint_save` / `checkpoint_replay` events.
+ *  Emitted by `ctx.checkpoint(name, fn)` — `save` on first execution,
+ *  `replay` when a saved value short-circuits the function call. */
+type CheckpointEventData = {
+    /** Stable, caller-supplied identifier under which the checkpoint is
+     *  stored. Internal auto-checkpoints from ask/spawn/race/parallel/map
+     *  use names prefixed with `__auto/<primitive>/`. */
+    name: string;
+};
+/** Data shape for `await_human` events — emitted when execution suspends
+ *  for a human decision via `ctx.awaitHuman()`. The pending side of the
+ *  pair; `await_human_resolved` follows when the decision arrives. */
+type AwaitHumanData = {
+    /** Optional human-facing prompt describing the decision needed. */
+    prompt?: string;
+    /** Channel routing the decision (e.g., 'slack', 'email', custom). */
+    channel?: string;
+};
+/** Data shape for `await_human_resolved` events — paired terminal of an
+ *  `await_human` request. Carries the `HumanDecision` returned to the workflow. */
+type AwaitHumanResolvedData = {
+    channel?: string;
+    decision: HumanDecision;
+};
+/** Data shape for `memory_remember` / `memory_recall` / `memory_forget` events. */
+type MemoryEventData = {
+    scope: string;
+    key?: string;
+    /** Result count for `recall` (number of vectors returned). */
+    count?: number;
+    /** Embedder cost for semantic recall/remember. Mirrored at the top-level
+     *  `cost` on the event so cost rails (`trackExecution`) pick it up. */
+    cost?: number;
+    /** Embedder usage detail (tokens / model). */
+    usage?: {
+        tokens?: number;
+        cost?: number;
+        model?: string;
+    };
+    /** True when this memory op called the semantic recall path (vs. key-only). */
+    embed?: boolean;
+    /** True when a key-only recall returned a value / semantic call path. */
+    semantic?: boolean;
+    /** True when a key-only recall returned a value. */
+    hit?: boolean;
+    /** Result count for `recall` (alias for `count` retained for back-compat). */
+    resultCount?: number;
+    /** Error message when the operation failed on the partial-failure path. */
+    error?: string;
+};
+/** Common fields carried by every `AxlEvent` regardless of `type`. */
+type AxlEventBase = {
     executionId: string;
+    /** Monotonic per-execution step counter, shared across nested asks via ALS. */
     step: number;
+    /** Wall-clock ms. */
     timestamp: number;
+    /** Workflow this event belongs to. Auto-stamped by `emitEvent` from
+     *  `this.workflowName` when defined; callers may override. */
     workflow?: string;
+    /** Optional emitting-agent name. Variants that always have an agent
+     *  (e.g., `agent_call_start/end`) redeclare it as required so consumers
+     *  narrowing on those variants get a non-optional `agent`. Single-point
+     *  events that may or may not have an agent (`handoff`, gate events,
+     *  `log`) keep the optional. */
     agent?: string;
-    promptVersion?: string;
+    /** Optional model URI — set on agent-related events; ignored on others. */
     model?: string;
+    /** Optional prompt version stamped from `agent._config.version`. */
+    promptVersion?: string;
+    /**
+     * Cost (USD) contributed by this event.
+     *
+     * Two DIFFERENT semantics ship on this field and consumers must know
+     * which they're reading:
+     *
+     *   - **Leaf cost** (`agent_call_end`, `tool_call_end`, `memory_remember`,
+     *     `memory_recall`): the authoritative charge for this single
+     *     provider call / tool invocation / embedder call. Summing these
+     *     across an execution gives the true spend.
+     *
+     *   - **Per-ask rollup** (`ask_end`): the SUM of leaf costs emitted
+     *     within this ask's frame, EXCLUDING nested asks (which roll up
+     *     into their own `ask_end`). Spec/16 decision 10.
+     *
+     * **If you write your own accumulator, DO NOT do `total += event.cost`
+     * across all event types — you'll double-count every ask** because the
+     * leaves AND the rollup both carry `cost`. Use the exported
+     * `eventCostContribution(event)` helper from `@axlsdk/axl` instead:
+     * it encapsulates the "skip ask_end, finite-check, leaf-only" rule in
+     * one place so your accumulator stays in lockstep with the built-in
+     * `runtime.trackExecution`, `ExecutionInfo.totalCost`, and Studio's
+     * cost aggregator.
+     *
+     * Other variants may stamp `cost` optionally to flow into cost rails
+     * (e.g., memory ops mirror `usage.cost` here). Review UX-8.
+     */
     cost?: number;
+    /** Token counts. Required-by-narrowing on `agent_call_end`; optional on
+     *  any event that wishes to mirror an aggregate. Scope is agent prompt /
+     *  completion / reasoning tokens ONLY — embedder tokens live in
+     *  `memory_*.data.usage.tokens` and are deliberately NOT summed into
+     *  this field (different pricing, different model, different category). */
     tokens?: {
         input?: number;
         output?: number;
         reasoning?: number;
     };
+    /** Duration in ms (set on `_end` variants and a few single-point events). */
     duration?: number;
-    /** When set, this event was emitted from a child context spawned by a tool
-     *  handler. The value is the `callId` of the outer `tool_call` that invoked
-     *  the tool. Lets consumers reconstruct agent-as-tool call graphs by
-     *  joining nested events to their parent `tool_call`. Undefined on top-level
-     *  events. */
-    parentToolCallId?: string;
+};
+/** Fields on every event that originates within a specific `ctx.ask()` call. */
+type AskScoped = {
+    askId: string;
+    /** Absent on root ask. */
+    parentAskId?: string;
+    /** 0 = root ask; +1 per nested ask. */
+    depth: number;
+    /** Emitting agent's name. Absent on `ask_start` (pre-resolution) and on
+     *  events that predate agent resolution. */
+    agent?: string;
+};
+/**
+ * Meta carried alongside callback invocations (`onToken`, `onAgentStart`,
+ * `onToolCall`) so consumers can group/route by ask.
+ *
+ * Note: `agent` is **required** here (the callback is always invoked
+ * inside an ALS frame that has the agent name already resolved). On the
+ * event side (`AskScoped.agent`) the field is optional — events emitted
+ * before agent resolution (e.g., `ask_start` is fired before the
+ * dynamic agent selector runs) can land without it.
+ */
+type CallbackMeta = {
+    askId: string;
+    parentAskId?: string;
+    depth: number;
+    agent: string;
 };
 /**
- * Trace event. A discriminated union over `type` — consumers that narrow via
- * `type` get statically-typed access to `data` and event-specific fields.
- * When adding a new event type, extend this union AND the emitter in
- * `WorkflowContext.emitTrace()` together so the compiler catches drift.
+ * Unified event union. Replaces the old `TraceEvent` (rich, persisted) and
+ * `StreamEvent` (lean, wire) by emitting a single rich event from one site
+ * and consuming the same shape on both rails.
+ *
+ * - Streaming consumers iterate `AxlStream` (an `AsyncIterable<AxlEvent>`).
+ * - Non-streaming consumers read `ExecutionInfo.events: AxlEvent[]`.
+ *
+ * Tree reconstruction: group ask-scoped events by `askId`, parent-link via
+ * `parentAskId`, sort by `step`, render by `depth`. Tokens (high-volume) and
+ * `partial_object` events are stream-only — never persisted to
+ * `ExecutionInfo.events`.
+ *
+ * When adding a new variant, extend `AXL_EVENT_TYPES` AND the emitter in
+ * `WorkflowContext.emitEvent()` together so the compiler catches drift; the
+ * exhaustiveness fixture in `__tests__/axl-event-exhaustive.test-d.ts` will
+ * also fail until the new case is handled.
  */
-type TraceEvent = (TraceEventBase & {
-    type: 'agent_call';
-    data?: AgentCallTraceData;
-}) | (TraceEventBase & {
-    type: 'tool_call';
+type AxlEvent = (AxlEventBase & {
+    type: 'workflow_start';
+    workflow: string;
+    data: WorkflowStartData;
+}) | (AxlEventBase & {
+    type: 'workflow_end';
+    workflow: string;
+    data: WorkflowEndData;
+}) | (AxlEventBase & AskScoped & {
+    type: 'ask_start';
+    prompt: string;
+}) | (AxlEventBase & AskScoped & {
+    type: 'ask_end';
+    /** Discriminated outcome — narrow on `outcome.ok`. Ask-internal throws
+     *  surface here, NOT via the workflow-level `error` event. */
+    outcome: {
+        ok: true;
+        result: unknown;
+    } | {
+        ok: false;
+        error: string;
+    };
+    /** Sum of `agent_call_end.cost` + `tool_call_end.cost` WITHIN THIS ASK,
+     *  excluding nested asks. Nested asks contribute to their own ask_end. */
+    cost: number;
+    duration: number;
+}) | (AxlEventBase & AskScoped & {
+    type: 'agent_call_start';
+    agent: string;
+    model: string;
+    /** 1-indexed tool-calling loop iteration within the ask. */
+    turn: number;
+    /** Request-side payload — prompt, system, params, messages, retry context. */
+    data: AgentCallStartData;
+}) | (AxlEventBase & AskScoped & {
+    type: 'agent_call_end';
+    agent: string;
+    model: string;
+    /** Authoritative turn-level cost. */
+    cost: number;
+    duration: number;
+    tokens?: {
+        input?: number;
+        output?: number;
+        reasoning?: number;
+    };
+    /** Response-side payload — response text, thinking. */
+    data: AgentCallEndData;
+}) | (AxlEventBase & AskScoped & {
+    type: 'token';
+    data: string;
+}) | (AxlEventBase & AskScoped & {
+    type: 'tool_call_start';
     tool: string;
-    data?: ToolCallTraceData;
-}) | (TraceEventBase & {
+    callId: string;
+    data: ToolCallStartData;
+}) | (AxlEventBase & AskScoped & {
+    type: 'tool_call_end';
+    tool: string;
+    callId: string;
+    duration: number;
+    cost?: number;
+    data: ToolCallData;
+}) | (AxlEventBase & AskScoped & {
     type: 'tool_approval';
     tool: string;
-    data?: ToolApprovalTraceData;
-}) | (TraceEventBase & {
+    callId?: string;
+    data: ToolApprovalData;
+}) | (AxlEventBase & AskScoped & {
     type: 'tool_denied';
     tool: string;
-    data?: unknown;
-}) | (TraceEventBase & {
+    callId?: string;
+    data?: ToolDeniedData;
+}) | (AxlEventBase & AskScoped & {
+    type: 'delegate';
+    data: DelegateData;
+}) | (AxlEventBase & {
+    type: 'handoff_start';
+    fromAskId: string;
+    toAskId: string;
+    sourceDepth: number;
+    targetDepth: number;
+    data: HandoffStartData;
+}) | (AxlEventBase & {
+    type: 'handoff_return';
+    fromAskId: string;
+    toAskId: string;
+    sourceDepth: number;
+    targetDepth: number;
+    data: HandoffReturnData;
+}) | (AxlEventBase & AskScoped & {
+    type: 'pipeline';
+    status: 'start';
+    stage: 'initial' | 'schema' | 'validate' | 'guardrail';
+    attempt: number;
+    maxAttempts: number;
+}) | (AxlEventBase & AskScoped & {
+    type: 'pipeline';
+    status: 'failed';
+    stage: 'schema' | 'validate' | 'guardrail';
+    attempt: number;
+    maxAttempts: number;
+    /** Feedback message about to be injected into the conversation. */
+    reason: string;
+}) | (AxlEventBase & AskScoped & {
+    type: 'pipeline';
+    status: 'committed';
+    /** The stage of the most recent `pipeline(start)` — `'initial'` when
+     *  the ask committed on the first pass, otherwise the gate that last
+     *  retried before commit. Lets consumers tell "committed cleanly"
+     *  from "committed after a schema/validate/guardrail retry". */
+    stage: 'initial' | 'schema' | 'validate' | 'guardrail';
+    /** The final successful attempt. */
+    attempt: number;
+    maxAttempts: number;
+}) | (AxlEventBase & AskScoped & {
+    type: 'partial_object';
+    attempt: number;
+    /** DeepPartial<T>; consumers cast at the render site. */
+    data: {
+        object: unknown;
+    };
+}) | (AxlEventBase & AskScoped & {
+    type: 'verify';
+    data: VerifyData;
+}) | (AxlEventBase & Partial<AskScoped> & {
     type: 'guardrail';
-    data?: GuardrailTraceData;
-}) | (TraceEventBase & {
+    data?: GuardrailData;
+}) | (AxlEventBase & Partial<AskScoped> & {
     type: 'schema_check';
-    data?: SchemaCheckTraceData;
-}) | (TraceEventBase & {
+    data?: SchemaCheckData;
+}) | (AxlEventBase & Partial<AskScoped> & {
     type: 'validate';
-    data?: ValidateTraceData;
-}) | (TraceEventBase & {
-    type: 'delegate';
-    data?: DelegateTraceData;
-}) | (TraceEventBase & {
-    type: 'handoff';
-    data?: HandoffTraceData;
-}) | (TraceEventBase & {
-    type: 'verify';
-    data?: VerifyTraceData;
-}) | (TraceEventBase & {
+    data?: ValidateData;
+}) | (AxlEventBase & Partial<AskScoped> & {
     type: 'log';
-    data?: unknown;
-}) | (TraceEventBase & {
-    type: 'workflow_start';
-    data?: WorkflowStartTraceData;
-}) | (TraceEventBase & {
-    type: 'workflow_end';
-    data?: WorkflowEndTraceData;
+    data: unknown;
+}) | (AxlEventBase & Partial<AskScoped> & {
+    type: 'memory_remember' | 'memory_recall' | 'memory_forget';
+    data: MemoryEventData;
+}) | (AxlEventBase & Partial<AskScoped> & {
+    type: 'checkpoint_save' | 'checkpoint_replay';
+    data: CheckpointEventData;
+}) | (AxlEventBase & Partial<AskScoped> & {
+    type: 'await_human';
+    data: AwaitHumanData;
+}) | (AxlEventBase & Partial<AskScoped> & {
+    type: 'await_human_resolved';
+    data: AwaitHumanResolvedData;
+}) | (AxlEventBase & {
+    type: 'done';
+    data: {
+        result: unknown;
+    };
+}) | (AxlEventBase & Partial<AskScoped> & {
+    type: 'error';
+    data: {
+        message: string;
+        name?: string;
+        code?: string;
+    };
 });
+/** Convenience: extract the union member matching a given `type` discriminator. */
+type AxlEventOf<T extends AxlEventType> = Extract<AxlEvent, {
+    type: T;
+}>;
 /** Result of a guardrail check. */
 type GuardrailResult = {
     block: boolean;
@@ -509,7 +802,10 @@ type ExecutionInfo = {
     executionId: string;
     workflow: string;
     status: ExecutionStatus;
-    steps: TraceEvent[];
+    /** Full event timeline. Tokens and `partial_object` events are NOT persisted
+     *  here (stream-only); aggregate `tokens: { input, output, reasoning? }`
+     *  on `agent_call_end` is the persisted token representation. */
+    events: AxlEvent[];
     totalCost: number;
     startedAt: number;
     completedAt?: number;
@@ -517,57 +813,26 @@ type ExecutionInfo = {
     result?: unknown;
     error?: string;
 };
-type StreamEvent = {
-    type: 'token';
-    data: string;
-} | {
-    type: 'tool_call';
-    name: string;
-    args: unknown;
-    callId?: string;
-} | {
-    type: 'tool_result';
-    name: string;
-    result: unknown;
-    callId?: string;
-} | {
-    type: 'tool_approval';
-    name: string;
-    args: unknown;
-    approved: boolean;
-    reason?: string;
-} | {
-    type: 'agent_start';
-    agent: string;
-    model?: string;
-} | {
-    type: 'agent_end';
-    agent: string;
-    cost?: number;
-    duration?: number;
-} | {
-    type: 'handoff';
-    source: string;
-    target: string;
-    mode?: 'oneway' | 'roundtrip';
-} | {
-    type: 'step';
-    step: number;
-    data: unknown;
-} | {
-    type: 'done';
-    data: unknown;
-} | {
-    type: 'error';
-    message: string;
-};
-/** Record of an agent handoff event (persisted in session metadata). */
+/** Record of an agent handoff event (persisted in session metadata).
+ *
+ *  `duration` semantics:
+ *    - `oneway`:    target's full ask duration (start-to-completion).
+ *    - `roundtrip`: full round-trip wall-clock (handoff_start → handoff_return),
+ *                   includes the time to push the result back into the source's
+ *                   conversation. Both measurements are populated by the
+ *                   runtime once the corresponding event fires; if the target
+ *                   never completes (workflow aborted mid-handoff), `duration`
+ *                   stays undefined.
+ *
+ *  `toAskId` is the askId of the target frame — lets consumers correlate
+ *  the record to the target's `ask_end` event in the trace stream. */
 type HandoffRecord = {
     source: string;
     target: string;
     mode: 'oneway' | 'roundtrip';
     timestamp: number;
     duration?: number;
+    toAskId?: string;
 };
 /** Information about a completed agent call, emitted via onAgentCallComplete. */
 type AgentCallInfo = {
@@ -707,12 +972,8 @@ type ExecutionState = {
  * Redis (production).
  */
 interface StateStore {
-    saveCheckpoint(executionId: string, step: number, data: unknown): Promise<void>;
-    getCheckpoint(executionId: string, step: number): Promise<unknown | null>;
-    getLatestCheckpoint(executionId: string): Promise<{
-        step: number;
-        data: unknown;
-    } | null>;
+    saveCheckpoint(executionId: string, name: string, data: unknown): Promise<void>;
+    getCheckpoint(executionId: string, name: string): Promise<unknown | null>;
     saveSession(sessionId: string, history: ChatMessage[]): Promise<void>;
     getSession(sessionId: string): Promise<ChatMessage[]>;
     deleteSession(sessionId: string): Promise<void>;
@@ -905,6 +1166,27 @@ type StateConfig = {
     sqlite?: {
         path: string;
     };
+    /**
+     * Maximum number of events retained in `ExecutionInfo.events` per
+     * execution. Token and partial_object events are already excluded
+     * from the array (high-volume, stream-only); this cap bounds the
+     * remaining structural events (`agent_call_*`, `tool_call_*`, gate
+     * events, pipeline, etc).
+     *
+     * Pathological workloads (e.g., 50 nested asks × 20-turn tool loops)
+     * can otherwise accumulate tens of thousands of events totalling
+     * hundreds of MB before the terminal `done` event fires. When the
+     * cap is hit, further events are dropped from the array and a single
+     * `log` event with `data.event === 'events_truncated'` is appended
+     * recording the truncation. The trace channel (`runtime.on('trace')`)
+     * and WS broadcast continue to receive every event — only the
+     * in-memory `ExecutionInfo.events` array is bounded.
+     *
+     * Default: 50_000. Set to `Infinity` to disable the cap (legacy
+     * behavior; only safe for short-lived executions). Must be a positive
+     * integer or `Infinity`.
+     */
+    maxEventsPerExecution?: number;
 };
 /** Global defaults */
 type DefaultsConfig = {
@@ -1200,13 +1482,17 @@ type WorkflowContextInit = {
     config: AxlConfig;
     providerRegistry: ProviderRegistry;
     sessionHistory?: ChatMessage[];
-    onTrace?: (event: TraceEvent) => void;
-    onToken?: (token: string) => void;
+    onTrace?: (event: AxlEvent) => void;
+    /** Per-token streaming callback. `meta` carries `askId`/`parentAskId`/
+     *  `depth`/`agent` so consumers can route or filter (e.g., `meta.depth === 0`
+     *  for root-only chat UIs). */
+    onToken?: (token: string, meta: CallbackMeta) => void;
+    /** Pre-execution tool-call callback. `meta` carries the ask correlation. */
     onToolCall?: (call: {
         name: string;
         args: unknown;
         callId?: string;
-    }) => void;
+    }, meta: CallbackMeta) => void;
     pendingDecisions?: Map<string, (d: HumanDecision) => void>;
     budgetContext?: {
         totalCost: number;
@@ -1233,13 +1519,26 @@ type WorkflowContextInit = {
     onAgentStart?: (info: {
         agent: string;
         model: string;
-    }) => void;
+    }, meta: CallbackMeta) => void;
     /** Callback fired after each ctx.ask() completes (once per ask invocation). */
     onAgentCallComplete?: (call: AgentCallInfo) => void;
-    /** Set by `createChildContext(parentToolCallId)` — stamped on every trace event
-     *  emitted from this child so consumers can join nested agent calls back to
-     *  the outer tool call that spawned them. */
-    parentToolCallId?: string;
+    /** 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.
+     *
+     *  - `byAgent` — per-agent counter for `ctx.ask` auto-checkpoints; each
+     *    agent's first ask gets `0`, second gets `1`, etc. Composed name:
+     *    `__auto/<agent>/ask/<n>`. Reads naturally as "orchestrator's first
+     *    ask, second ask…" instead of a global ordinal.
+     *  - `root` — counter for `ctx.spawn` / `race` / `parallel` / `map`
+     *    wrappers, which don't have an agent context (they wrap arbitrary
+     *    fn callbacks). Composed name: `__auto/<primitive>/<n>`.
+     *
+     *  Root contexts default to a fresh `{ byAgent: new Map(), root: 0 }`. */
+    autoCheckpointCounters?: {
+        byAgent: Map<string, number>;
+        root: number;
+    };
 };
 /**
  * The central coordination object for all Axl primitives.
@@ -1264,8 +1563,34 @@ declare class WorkflowContext<TInput = unknown> {
     private pendingDecisions?;
     private budgetContext?;
     private stateStore?;
-    private stepCounter;
-    private checkpointCounter;
+    /** Root step counter for this execution. Inherited by every ctx.ask()
+     *  frame so all events from this WorkflowContext (root + nested) share
+     *  a single monotonic counter, even when concurrent branch primitives
+     *  fire asks before any single parent ask exists. Per-instance so
+     *  separate executions don't cross-talk. */
+    private stepRefRoot;
+    /**
+     * Auto-checkpoint counters for internal `_checkpoint` callers. Held by
+     * reference so child contexts created via `createChildContext` share
+     * the same number space — otherwise a tool handler's nested `ctx.ask()`
+     * (which auto-checkpoints) would collide with the parent's
+     * auto-checkpoints in the state store. See `WorkflowContextInit
+     * .autoCheckpointCounters` for the per-agent vs root split.
+     * User-facing `ctx.checkpoint(name, fn)` requires an explicit name and
+     * does NOT touch these counters — it goes straight to the store under
+     * the caller-supplied key.
+     */
+    private autoCheckpointCounters;
+    /** Idempotency guards for `workflow_start` / `workflow_end` emission.
+     *  Both `runtime.execute()` and `runtime.stream()` have paths where a
+     *  post-emit side-effect (checkpoint deletion, state-store persistence)
+     *  can throw AFTER `_emitWorkflowEnd({status: 'completed'})` has already
+     *  fired — the outer catch would then fire `_emitWorkflowEnd({status:
+     *  'failed'})` for a second time. These flags make both emitters
+     *  single-fire so consumers never see paired-then-conflicting terminal
+     *  events for one execution. */
+    private _workflowStartEmitted;
+    private _workflowEndEmitted;
     private signal?;
     private summaryCache?;
     private workflowName?;
@@ -1277,27 +1602,46 @@ declare class WorkflowContext<TInput = unknown> {
     private awaitHumanHandler?;
     private onAgentStart?;
     private onAgentCallComplete?;
-    private parentToolCallId?;
     constructor(init: WorkflowContextInit);
     /**
      * Create a child context for nested agent invocations (e.g., agent-as-tool).
      * Shares: budget tracking, abort signals, trace emission, provider registry,
      *         state store, span manager, memory manager, MCP manager, config,
-     *         awaitHuman handler, pending decisions, tool overrides.
-     * Isolates: session history, step counter, streaming callbacks (onToken, onAgentStart, onToolCall).
+     *         awaitHuman handler, pending decisions, tool overrides, AND the
+     *         streaming callbacks (onToken / onAgentStart / onToolCall).
+     * Isolates: session history.
+     *
+     * Streaming callbacks now propagate into nested asks because every callback
+     * invocation carries `meta.askId`/`meta.parentAskId`/`meta.depth` so
+     * consumers that want root-only behavior can filter on `meta.depth === 0`
+     * instead of relying on the runtime to drop nested events. This is the
+     * "nested ask visibility" fix from spec §3.2.
      *
-     * @param parentToolCallId - The `callId` of the outer `tool_call` that
-     *   spawned this child. When set, every trace event emitted by the child
-     *   will carry this id as `parentToolCallId`, so consumers can join nested
-     *   agent calls back to the outer tool call that invoked them.
+     * The shared step counter lives in `askStorage` (ALS), so there is no
+     * per-context counter to pass through anymore. Nested events are
+     * correlated to their parent via `parentAskId` (set on every nested ask
+     * by ALS frame allocation) — the deprecated `parentToolCallId` field
+     * was removed in 0.16.0.
      */
-    createChildContext(parentToolCallId?: string): WorkflowContext;
+    createChildContext(): WorkflowContext;
     /**
      * Resolve the current abort signal.
      * Branch-scoped signals (from race/spawn/map/budget) in AsyncLocalStorage
      * take priority over the instance-level signal.
      */
     private get currentSignal();
+    /**
+     * Build a `CallbackMeta` for the current ask frame. Used at every
+     * `onToken`/`onToolCall`/`onAgentStart` call site so consumers can
+     * route or filter by ask correlation (`meta.depth === 0` for root
+     * chat UIs, etc.).
+     *
+     * If the call is somehow outside an ask frame (e.g., a programmatic
+     * `tool.run()` test harness), falls back to a synthetic meta keyed off
+     * `executionId` so the type contract holds — consumers see `depth: 0`
+     * and can ignore those events.
+     */
+    private currentCallbackMeta;
     ask<T = string>(agent: Agent, prompt: string, options?: AskOptions<T>): Promise<T>;
     private executeAgentCall;
     /**
@@ -1314,16 +1658,49 @@ declare class WorkflowContext<TInput = unknown> {
     /**
      * Execute a function with checkpoint-replay semantics.
      *
-     * On first execution, runs `fn()`, saves the result, and returns it.
-     * On replay (resume after restart), returns the saved result without re-executing.
-     * This prevents duplicate side effects (double API calls, double refunds, etc.).
+     * On first execution, runs `fn()`, saves the result under `name`, and
+     * returns it. On replay (resume after restart), returns the saved result
+     * without re-executing. This prevents duplicate side effects (double API
+     * calls, double refunds, etc.).
+     *
+     * `name` must be a stable, caller-supplied identifier — the same call
+     * site MUST pass the same name across runs of the same execution for
+     * replay to work. Names are scoped to a single execution and must be
+     * unique within it; reusing a name (e.g. inside a loop) gives
+     * last-write-wins behavior. For loops, compose names from the iterator:
+     * `ctx.checkpoint(`process-${id}`, fn)`.
+     *
+     * Names starting with `__auto/` are reserved for runtime-internal
+     * auto-checkpointing of `ctx.ask` / spawn / race / parallel / map.
      */
-    checkpoint<T>(fn: () => Promise<T>): Promise<T>;
+    checkpoint<T>(name: string, fn: () => Promise<T>): Promise<T>;
     /**
-     * Internal checkpoint implementation shared by both the public checkpoint()
-     * and the automatic checkpointing in ask/spawn/race/parallel/map.
+     * Internal checkpoint implementation shared by both the public
+     * `checkpoint(name, fn)` and the automatic checkpointing in
+     * ask/spawn/race/parallel/map. Internal callers pass an `__auto/...`
+     * name composed by `_autoCheckpointName`.
+     *
+     * `agent` is the originating agent for ask auto-checkpoints — passing
+     * it explicitly stamps `event.agent` on the trace events even though
+     * the emit fires before/after `fn()` (where the ask's ALS frame
+     * either doesn't exist yet or has already torn down). Without this,
+     * post-fn `checkpoint_save` rows show no agent in the trace UI.
      */
     private _checkpoint;
+    /** Generate a stable auto-checkpoint name for an internal primitive.
+     *
+     *  For `ctx.ask`, the originating agent is known and gets a per-agent
+     *  counter — the resulting name reads as "orchestrator's first ask"
+     *  (`__auto/orchestrator-agent/ask/0`) instead of a global ordinal.
+     *  For `spawn` / `race` / `parallel` / `map`, no agent context is
+     *  available (those wrap arbitrary fn callbacks), so the name uses
+     *  the root counter: `__auto/spawn/0`, `__auto/race/3`, etc.
+     *
+     *  All counters live on a shared ref passed through `createChildContext`,
+     *  so a tool handler's nested `ctx.ask()` (which runs in a child
+     *  WorkflowContext) can never collide with the parent's auto-names in
+     *  the state store. */
+    private _autoCheckpointName;
     spawn<T>(n: number, fn: (index: number) => Promise<T>, options?: SpawnOptions): Promise<Result<T>[]>;
     private _spawnImpl;
     vote<T>(results: Result<T>[], options: VoteOptions<T>): T | Promise<T>;
@@ -1377,9 +1754,16 @@ declare class WorkflowContext<TInput = unknown> {
      * @internal
      */
     private _accumulateBudgetCost;
-    /** @internal */
+    /** @internal — idempotent; no-ops on second+ call within one ctx. */
     _emitWorkflowStart(input: unknown): void;
-    /** @internal */
+    /** @internal — idempotent; no-ops on second+ call within one ctx.
+     *  Protects against the post-emit-side-effect double-fire (reviewer
+     *  bug B1): `runtime.execute()` / `runtime.stream()` emit
+     *  `workflow_end(completed)`, then call `deleteCheckpoints` /
+     *  `persistExecution`. If either throws, the outer catch would
+     *  otherwise fire a second `workflow_end(failed)` with conflicting
+     *  status. First-wins semantics: the completed event stands, the
+     *  inner side-effect failure propagates as a normal thrown error. */
     _emitWorkflowEnd(info: {
         status: 'completed' | 'failed';
         duration: number;
@@ -1416,10 +1800,10 @@ declare class WorkflowContext<TInput = unknown> {
     /**
      * Internal emitter input — intentionally loose so call sites don't need to
      * build a perfectly-narrowed discriminated-union member. The resulting
-     * `TraceEvent` (exported type) remains strict, and TypeScript narrows it at
+     * `AxlEvent` (exported type) remains strict, and TypeScript narrows it at
      * consumer sites via the `type` discriminator.
      */
-    private emitTrace;
+    private emitEvent;
 }
 
 /** Retry policy for tool handlers */
@@ -1487,6 +1871,15 @@ type Workflow<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType =
     readonly outputSchema: TOutput | undefined;
     readonly handler: (ctx: WorkflowContext<z.infer<TInput>>) => Promise<z.infer<TOutput>>;
 };
+/**
+ * Bivariant-parameter alias for `Workflow<any, any>`. Function parameters
+ * are contravariant under strict types, so `Workflow<TInput=MsgType>` won't
+ * satisfy a `Workflow<unknown, unknown>` slot. The standard escape hatch is
+ * to widen to `any`. This alias gives that workaround a name so call sites
+ * (e.g. `AxlRuntime.register`, `AxlTestRuntime.WorkflowLike.handler`) don't
+ * each independently re-derive it.
+ */
+type AnyWorkflow = Workflow<any, any>;
 /**
  * Define a named workflow with Zod-validated input/output and an async handler.
  * Register workflows with `AxlRuntime.register()` to execute them.
@@ -1498,37 +1891,112 @@ declare function workflow<TInput extends z.ZodType, TOutput extends z.ZodType =
 /**
  * A streamable workflow execution.
  *
- * Extends Node's Readable and implements AsyncIterable<StreamEvent>.
- * Supports .on() events, for-await-of, .text iterator, and .pipe().
+ * 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()`.
+ *
+ * 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;
-    private tokens;
+    /**
+     * 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
+     * `pipeline(status: 'failed')` or `ask_end({ok:false})` for an ask,
+     * that ask's in-progress entry is discarded. Spec/16 §4.3.
+     *
+     * Tokens emitted outside any ask (synthesized test fixtures with no
+     * `askId`) fall back to an empty-string sentinel key — preserves the
+     * single-buffer behavior for that legacy case.
+     */
+    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;
     [Symbol.asyncIterator](): {
-        next: () => Promise<IteratorResult<StreamEvent>>;
+        next: () => Promise<IteratorResult<AxlEvent>>;
         [Symbol.asyncIterator](): /*elided*/ any;
         [Symbol.asyncDispose](): Promise<void>;
     };
     get text(): AsyncIterable<string>;
-    get steps(): AsyncIterable<StreamEvent>;
+    /**
+     * 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>;
     pipe<T extends NodeJS.WritableStream>(destination: T, options?: {
         end?: boolean;
     }): T;
-    /** Push a stream event. Called by the runtime. */
-    _push(event: StreamEvent): void;
-    /** Signal successful completion. */
-    _done(result: unknown): void;
-    /** Signal an error. */
-    _error(error: Error): void;
+    /** Push an event onto the stream. Called by the runtime. */
+    _push(event: AxlEvent): void;
+    /**
+     * Signal successful completion.
+     *
+     * `executionId` is required — the runtime must allocate it before
+     * calling `stream()` so terminal events always carry a real id.
+     * Previously the default-empty parameter surfaced blank executionIds
+     * on error paths that threw before `execInfo` was assigned (review S4).
+     */
+    _done(result: unknown, executionId: string): void;
+    /** 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: Error, executionId: string): void;
+    /** Concatenated root-only text from committed attempts plus the
+     *  current in-flight attempt(s). Retried (gate-rejected) attempts
+     *  are excluded — see spec/16 §4.3. Reading mid-attempt returns the
+     *  in-progress text; reading after `pipeline(committed)` (which
+     *  fires before `done`) returns the canonical winning text.
+     *
+     *  With concurrent root-level asks (`ctx.parallel`, `ctx.spawn`,
+     *  `ctx.race`, `ctx.map`), each branch's tokens are scoped per-`askId`
+     *  and emitted contiguously in the order each ask first started
+     *  emitting tokens. A `pipeline(failed)` or `ask_end({ok:false})` on
+     *  one branch only discards THAT branch's in-progress buffer —
+     *  sibling branches are unaffected. For UIs that want each sub-agent
+     *  in its own lane, prefer `textByAsk`. */
     get fullText(): string;
 }
 
@@ -1597,8 +2065,23 @@ type CreateContextOptions = {
     signal?: AbortSignal;
     /** Prior conversation history for multi-turn eval testing. */
     sessionHistory?: ChatMessage[];
-    /** Token streaming callback. */
-    onToken?: (token: string) => void;
+    /** Token streaming callback. `meta` carries `askId`/`parentAskId`/`depth`/`agent`
+     *  so consumers can route or filter by ask correlation (e.g.,
+     *  `meta.depth === 0` for root-only chat UIs). */
+    onToken?: (token: string, meta: CallbackMeta) => void;
+    /** Fires when an agent invokes a tool. `meta` carries the same ask
+     *  correlation shape as `onToken`. */
+    onToolCall?: (call: {
+        name: string;
+        args: unknown;
+        callId?: string;
+    }, meta: CallbackMeta) => void;
+    /** Fires when an agent begins processing a turn. `meta` carries the
+     *  same ask correlation shape as `onToken`. */
+    onAgentStart?: (info: {
+        agent: string;
+        model?: string;
+    }, meta: CallbackMeta) => void;
     /** Handler for tool approval requests. Called when an agent invokes a tool with requireApproval. */
     awaitHumanHandler?: (options: AwaitHumanOptions) => Promise<HumanDecision>;
 };
@@ -1626,6 +2109,10 @@ declare class AxlRuntime extends EventEmitter {
     private historicalExecutionsLoadPromise;
     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;
     constructor(config?: AxlConfig);
     /**
      * Whether `config.trace.redact` is enabled on this runtime. A narrow
@@ -1654,13 +2141,39 @@ declare class AxlRuntime extends EventEmitter {
     /** Get the MCP manager (if initialized). */
     getMcpManager(): McpManager | undefined;
     private createStateStore;
+    /**
+     * Run a workflow body inside an ALREADY-CONSTRUCTED `WorkflowContext`
+     * with full lifecycle invariants: emit `workflow_start` → run handler
+     * → parse output → emit `workflow_end` → delete checkpoints → persist.
+     *
+     * Shared between `execute()` and `stream()`. Centralizes the
+     * "start iff end" pairing invariant so a future emit path
+     * (e.g., `resumeExecution`) can inherit correct behavior by routing
+     * through this helper. Also factors out the AbortError detection.
+     *
+     * 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.
+     *
+     * Caller responsibilities:
+     * - Allocate `executionId` and register it in `abortControllers` map
+     *   BEFORE calling this helper (so early-throw paths still have a
+     *   correlation id available for terminal events).
+     * - Construct `execInfo` and `ctx` before calling.
+     * - Pass `span` if the call site is inside a tracer span — this
+     *   helper sets `axl.workflow.cost` / `.duration` attributes on
+     *   success.
+     */
+    private runWorkflowBody;
     /**
      * Persist a completed/failed execution to the state store (fire-and-forget)
      * and move it from the active executions map to the historical cache.
      */
     private persistExecution;
     /** Register a workflow with the runtime. */
-    register(workflow: Workflow<any, any>): void;
+    register(workflow: AnyWorkflow): void;
     /** Register standalone tools for Studio introspection and direct testing. */
     registerTool(...tools: Tool<any, any>[]): void;
     /** Register standalone agents for Studio playground and introspection. */
@@ -1716,7 +2229,7 @@ declare class AxlRuntime extends EventEmitter {
          * When `true`, populate `EvalItem.traces` on every item (success + failure
          * paths). Forwards to `runEval({ captureTraces: true })`, which wraps each
          * item's execution in `runtime.trackExecution({ captureTraces: true })`.
-         * Verbose-mode `agent_call.data.messages` snapshots are stripped from
+         * Verbose-mode `agent_call_start.data.messages` snapshots are stripped from
          * captured traces to keep memory bounded.
          */
         captureTraces?: boolean;
@@ -1841,11 +2354,11 @@ declare class AxlRuntime extends EventEmitter {
      *   need embedder token counts, subscribe to `runtime.on('trace', ...)` and
      *   read `data.usage.tokens` on `memory_remember` / `memory_recall` events.
      *
-     * Pass `{ captureTraces: true }` to also collect the raw `TraceEvent[]` observed
+     * Pass `{ captureTraces: true }` to also collect the raw `AxlEvent[]` observed
      * during `fn()`. This is opt-in because it keeps every event in memory for the
      * duration of the call — useful for eval per-item capture, debugging, and test
      * assertions, but overhead grows with trace volume. When enabled, verbose-mode
-     * `agent_call.data.messages` snapshots are omitted from captured events (still
+     * `agent_call_start.data.messages` snapshots are omitted from captured events (still
      * broadcast via onTrace) to keep memory bounded — callers who need the full
      * verbose snapshot should subscribe to `runtime.on('trace', ...)` directly.
      *
@@ -1856,7 +2369,7 @@ declare class AxlRuntime extends EventEmitter {
     }): Promise<{
         result: T;
         cost: number;
-        traces?: TraceEvent[];
+        traces?: AxlEvent[];
         metadata: {
             models: string[];
             modelCallCounts?: Record<string, number>;
@@ -1891,8 +2404,8 @@ declare class AxlRuntime extends EventEmitter {
      * The emit('trace', event) call happens before this method is called, so
      * programmatic subscribers always receive events regardless of trace config.
      */
-    private outputTraceEvent;
-    private logTraceEvent;
+    private outputAxlEvent;
+    private logAxlEvent;
     /**
      * Append a handoff record to session metadata.
      * Note: The read-modify-write is not atomic. Concurrent handoffs in the same
@@ -1901,8 +2414,177 @@ declare class AxlRuntime extends EventEmitter {
      * cross-execution concurrency on the same session, which is unlikely.
      */
     private appendHandoffRecord;
+    /**
+     * Patch `duration` on the handoff record matching `toAskId` (the target
+     * frame's askId, which the runtime stamps on `handoff_start` and which
+     * appears as `askId` on the target's `ask_end`).
+     *
+     * Called from two places per handoff:
+     *   - target's `ask_end` — first-write source for ONEWAY (no return event).
+     *   - `handoff_return`   — overwrites for ROUNDTRIP with the round-trip
+     *                          wall-clock figure (intentional: round-trip
+     *                          duration is the more useful metric for the
+     *                          source-paused-for-N-ms semantic).
+     *
+     * No-op if no record matches `toAskId` (e.g., stream subscribed mid-
+     * handoff, or session metadata got wiped) — `duration` stays undefined,
+     * which is the documented default for `HandoffRecord`.
+     */
+    private updateHandoffDuration;
 }
 
+/**
+ * Shared helpers for working with `AxlEvent` streams.
+ *
+ * Consumers writing their own accumulators / reducers reach for these so
+ * they don't have to re-derive spec invariants at every call site. The
+ * core runtime, AxlTestRuntime, and Studio's cost reducer ALL use these —
+ * keeping one source of truth for each invariant.
+ */
+
+/**
+ * Variants that directly carry an authoritative cost charge from the
+ * provider (or embedder). `ask_end` is a per-ask ROLLUP of these leaves
+ * — counting it alongside them would double-charge. Any future
+ * cost-emitting variant MUST be added here AND NOT be a rollup.
+ *
+ * Treated as a `Set` for O(1) membership checks; exported `as const`
+ * tuple so exhaustiveness fixtures can cross-check against
+ * `AXL_EVENT_TYPES`.
+ */
+declare const COST_BEARING_LEAF_TYPES: readonly ["agent_call_end", "tool_call_end", "memory_remember", "memory_recall"];
+/**
+ * Cost contribution of `event` to a running total.
+ *
+ * Returns the event's `cost` if it's a cost-bearing leaf; 0 otherwise.
+ * The key invariant (spec/16 decision 10): `ask_end` events carry a
+ * per-ask ROLLUP of leaf costs that already passed through consumer
+ * accumulators, so they contribute 0 here to avoid double-counting.
+ *
+ * Use this at every place you'd write `total += event.cost`:
+ *
+ *     for (const ev of info.events) total += eventCostContribution(ev);
+ *
+ * Consumers who want the authoritative per-ask rollup read
+ * `ask_end.cost` directly — that field is populated whether or not
+ * the leaf events were summed separately. Spec decision 10.
+ */
+declare function eventCostContribution(event: AxlEvent): number;
+/**
+ * True when the event is a cost-bearing leaf (contributes directly to
+ * totals) — used by internal emitters that need to know whether to
+ * bump per-frame askCost rollups.
+ *
+ * Distinct from `eventCostContribution(e) > 0`: an `agent_call_end`
+ * with `cost: 0` is still a leaf (produced by a free / cached turn),
+ * just one that happens to contribute zero.
+ */
+declare function isCostBearingLeaf(event: AxlEvent): boolean;
+/**
+ * True when the event originates from the root ask (`depth === 0`)
+ * or has no ask correlation at all (workflow / done / error / log).
+ *
+ * Used by consumers that want "just the chat bubble" tokens or
+ * "just the root ask" visuals. Nested-ask UIs drop this filter.
+ *
+ * `depth` is coerced through `?? 0` so events without the field
+ * (out-of-ask lifecycle events, synthesized terminals) are treated
+ * as root-level — they're never at depth ≥ 1.
+ */
+declare function isRootLevel(event: AxlEvent): boolean;
+
+/**
+ * Tolerant JSON parser for progressive structured-output streaming.
+ *
+ * Accepts partial / truncated JSON and returns the longest parseable prefix
+ * as a structured value. Used by `ctx.ask({ schema })` while streaming so
+ * consumers can render fields as they arrive — see `partial_object` AxlEvent.
+ *
+ * Scope (intentional minimum):
+ *   - Single-pass tokenizer + recursive-descent state machine.
+ *   - Only TRAILING truncation is tolerated. Mid-document malformed input
+ *     throws. (A consumer rendering progressive output sees one well-formed
+ *     subtree at a time, never bogus shape changes.)
+ *   - Supports objects, arrays, strings (with `\"` `\\` `\n` `\t` `\r` `\b`
+ *     `\f` `\/` `\uXXXX`), numbers (int/float/exp/negative), `true` /
+ *     `false` / `null`.
+ *   - Rejects: trailing commas, comments, unquoted keys.
+ *
+ * Truncation recovery:
+ *   - Unterminated string  → return content parsed so far.
+ *   - Unterminated number  → return valid prefix if it's a complete number;
+ *                            drop the key/value if the prefix is malformed
+ *                            (`-`, `1.`, `1e` → drop).
+ *   - Unclosed `[`         → array with parsed elements.
+ *   - Unclosed `{`         → object with parsed pairs. A key without a value
+ *                            is dropped.
+ *   - `,` or `:` at EOF    → ignored; the last complete value wins.
+ *
+ * Zero runtime deps. ~250 LOC.
+ */
+/** Parse a JSON-shaped string that may be truncated mid-stream. */
+declare function parsePartialJson(input: string): unknown;
+
+/**
+ * Per-variant redaction rules for `AxlEvent`.
+ *
+ * `config.trace.redact` is an observability-boundary filter that scrubs
+ * user/LLM content from events before they reach consumers. Two layers
+ * historically applied this filter independently:
+ *
+ *   1. Core: `WorkflowContext.emitEvent()` — emit-time scrub before `onTrace`.
+ *   2. Studio: `redactStreamEvent()` — wire-boundary scrub before WS broadcast
+ *      and again at REST serialization (`redactExecutionInfo`).
+ *
+ * Both layers walked the same `AxlEvent` discriminated union, with separate
+ * if/else and switch/case ladders. Adding a new variant required updating
+ * both. They had drifted: WS missed `workflow_start`/`workflow_end`,
+ * `log`, and the full `memory_*` walk that core applied. Defense-in-depth
+ * also broke for runtimes that flipped `redact` after emitting events —
+ * REST reads of stored `ExecutionInfo.events` would leak fields the WS
+ * layer didn't know to scrub.
+ *
+ * `REDACTION_RULES` is the single source of truth: a `Record<AxlEventType,
+ * RuleFor<...>>` so adding a new variant to `AXL_EVENT_TYPES` without a
+ * corresponding entry is a typecheck error. Every rule is pure (no
+ * mutation), so the same rule runs at emit time and at the wire boundary
+ * with identical results.
+ *
+ * Numeric/structural fields (`cost`, `tokens`, `duration`, `askId`,
+ * `parentAskId`, `depth`, `agent`, `executionId`, `step`, `timestamp`,
+ * `callId`, `tool`, `model`, `workflow`) are NEVER scrubbed — they're
+ * non-PII observability metadata and load-bearing for cost rails. Rules
+ * preserve these by spreading `{ ...event }` and only overriding the
+ * specific user-content field(s) for that variant.
+ */
+
+declare const REDACTED = "[redacted]";
+/** Type-safe rule signature: takes a specific event variant, returns the same variant. */
+type RuleFor<T extends AxlEventType> = (event: AxlEventOf<T>) => AxlEventOf<T>;
+/**
+ * Per-variant rule table. Adding a new variant to `AXL_EVENT_TYPES`
+ * without a corresponding entry here is a typecheck error — the
+ * `Record<AxlEventType, ...>` mapped type forces exhaustiveness.
+ *
+ * For variants that ship no user content today (`delegate`,
+ * `handoff_return`, `checkpoint_*`), the rule is `passthrough` — but
+ * that's still an explicit, reviewed decision rather than a
+ * silent omission.
+ */
+declare const REDACTION_RULES: {
+    [K in AxlEventType]: RuleFor<K>;
+};
+/**
+ * Apply the redaction rule for `event.type` and return a new event with
+ * user-content fields scrubbed. Pure: never mutates the input.
+ *
+ * Caller responsibility: only invoke when redaction is enabled. The rules
+ * unconditionally scrub — they don't gate on `config.trace.redact`. Both
+ * `WorkflowContext.emitEvent` (core) and `redactStreamEvent` (Studio)
+ * check the flag before calling this function.
+ */
+declare function redactEvent(event: AxlEvent): AxlEvent;
+
 /** Base error class for all Axl errors */
 declare class AxlError extends Error {
     readonly code: string;
@@ -2160,12 +2842,8 @@ declare class MemoryStore implements StateStore {
     private executionHistory;
     private evalHistory;
     constructor();
-    saveCheckpoint(executionId: string, step: number, data: unknown): Promise<void>;
-    getCheckpoint(executionId: string, step: number): Promise<unknown | null>;
-    getLatestCheckpoint(executionId: string): Promise<{
-        step: number;
-        data: unknown;
-    } | null>;
+    saveCheckpoint(executionId: string, name: string, data: unknown): Promise<void>;
+    getCheckpoint(executionId: string, name: string): Promise<unknown | null>;
     saveSession(sessionId: string, history: ChatMessage[]): Promise<void>;
     getSession(sessionId: string): Promise<ChatMessage[]>;
     deleteSession(sessionId: string): Promise<void>;
@@ -2209,13 +2887,44 @@ declare class MemoryStore implements StateStore {
 declare class SQLiteStore implements StateStore {
     private db;
     constructor(filePath: string);
+    /**
+     * Idempotent schema migration. Tracks version via `PRAGMA user_version`
+     * so reopens skip applied steps. Wrapped in `BEGIN IMMEDIATE` so
+     * concurrent `SQLiteStore` constructors serialize at the file level
+     * and rollback on failure leaves the DB in a clean pre-migration
+     * state.
+     *
+     * Migration history:
+     * - v1 (spec/16): rename `execution_history.steps` → `events`. The
+     *   JS-level `ExecutionInfo.steps` was renamed to `.events` in PR 1
+     *   commit 1; this brings the on-disk schema in line.
+     * - v2 (named checkpoints): rename `checkpoints.step` (INTEGER) →
+     *   `checkpoints.name` (TEXT). The runtime now requires
+     *   `ctx.checkpoint(name, fn)` so the per-context numeric counter is
+     *   gone — names are caller-supplied stable identifiers. Existing
+     *   numeric step values become stringified names ("0", "1", …) to
+     *   preserve replay continuity for in-flight executions across the
+     *   upgrade boundary.
+     *
+     * Applied BEFORE `initTables()` so the subsequent `CREATE TABLE
+     * IF NOT EXISTS` runs against the post-migration column name. Fresh
+     * installs just create the table with `events` directly and bump
+     * `user_version` to the current version.
+     *
+     * TOCTOU guard (review B-3): the initial `user_version` read is
+     * informational only — a concurrent process can complete the
+     * migration between that read and our `BEGIN IMMEDIATE`. We
+     * re-read `user_version` inside the transaction and short-circuit
+     * if it's already at target, so the non-idempotent half (writes
+     * that went beyond a simple ALTER) never double-applies under a
+     * race. The current v0→v1 step IS idempotent via the column-
+     * presence check, but future migrations may not be, and the
+     * transactional re-read costs nothing.
+     */
+    private migrate;
     private initTables;
-    saveCheckpoint(executionId: string, step: number, data: unknown): Promise<void>;
-    getCheckpoint(executionId: string, step: number): Promise<unknown | null>;
-    getLatestCheckpoint(executionId: string): Promise<{
-        step: number;
-        data: unknown;
-    } | null>;
+    saveCheckpoint(executionId: string, name: string, data: unknown): Promise<void>;
+    getCheckpoint(executionId: string, name: string): Promise<unknown | null>;
     saveSession(sessionId: string, history: ChatMessage[]): Promise<void>;
     getSession(sessionId: string): Promise<ChatMessage[]>;
     deleteSession(sessionId: string): Promise<void>;
@@ -2274,12 +2983,8 @@ declare class RedisStore implements StateStore {
     private execHistorySetKey;
     private evalHistoryKey;
     private evalHistorySetKey;
-    saveCheckpoint(executionId: string, step: number, data: unknown): Promise<void>;
-    getCheckpoint(executionId: string, step: number): Promise<unknown | null>;
-    getLatestCheckpoint(executionId: string): Promise<{
-        step: number;
-        data: unknown;
-    } | null>;
+    saveCheckpoint(executionId: string, name: string, data: unknown): Promise<void>;
+    getCheckpoint(executionId: string, name: string): Promise<unknown | null>;
     saveSession(sessionId: string, history: ChatMessage[]): Promise<void>;
     getSession(sessionId: string): Promise<ChatMessage[]>;
     deleteSession(sessionId: string): Promise<void>;
@@ -2369,4 +3074,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { type Agent, type AgentCallInfo, type AgentCallTraceData, type AgentConfig, AnthropicProvider, type AskOptions, type AwaitHumanOptions, type AxlConfig, AxlError, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, type ChatMessage, type ChatOptions, type CreateContextOptions, type DelegateOptions, type DelegateTraceData, type Effort, type EmbedResult, type EmbedUsage, type Embedder, type EvalHistoryEntry, type ExecuteOptions, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, GuardrailError, type GuardrailResult, type GuardrailTraceData, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffTraceData, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, type RaceOptions, type RecallOptions, type RecallResult, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, type SchemaCheckTraceData, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StreamEvent, type TelemetryConfig, TimeoutError, type Tool, type ToolApprovalTraceData, type ToolCallMessage, type ToolCallTraceData, type ToolChoice, type ToolConfig, ToolDenied, type ToolHooks, type TraceEvent, type TraceEventType, type ValidateResult, type ValidateTraceData, ValidationError, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VerifyRetry, type VerifyTraceData, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndTraceData, type WorkflowStartTraceData, agent, createSpanManager, defineConfig, extractJson, 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, type AxlEventOf, type AxlEventType, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, 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 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, extractJson, isCostBearingLeaf, isRootLevel, parsePartialJson, redactEvent, resolveThinkingOptions, tool, workflow, zodToJsonSchema };