@axlsdk/axl 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -354,9 +354,13 @@ type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
  * 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", "string_delta", "verify", "schema_diagnostic", "log", "memory_remember", "memory_recall", "memory_forget", "checkpoint_save", "checkpoint_replay", "await_human", "await_human_resolved", "guardrail", "schema_check", "validate", "done", "error"];
+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_call_rejected", "tool_approval", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "string_delta", "verify", "schema_diagnostic", "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];
+/** Backward-compatible name for the canonical v2 writer discriminator list. */
+declare const AXL_EVENT_TYPES_V2: readonly ["workflow_start", "workflow_end", "ask_start", "ask_end", "agent_call_start", "agent_call_end", "token", "tool_call_start", "tool_call_end", "tool_call_rejected", "tool_approval", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "string_delta", "verify", "schema_diagnostic", "log", "memory_remember", "memory_recall", "memory_forget", "checkpoint_save", "checkpoint_replay", "await_human", "await_human_resolved", "guardrail", "schema_check", "validate", "done", "error"];
+/** Accepted/rejected tool lifecycle discriminators in event schema v2. */
+declare const AXL_TOOL_LIFECYCLE_TYPES_V2: readonly ["tool_call_start", "tool_call_end", "tool_call_rejected"];
 /** Resolved model parameters sent to the provider for an LLM call. */
 type AgentCallParams = {
     temperature?: number;
@@ -431,18 +435,142 @@ type ToolCallData = {
 type ToolCallStartData = {
     args: unknown;
 };
+/** Data shape for a v2 tool start. The event's `tool` is canonical; this field
+ * retains the provider-visible request name only when it differs. */
+type ToolCallStartDataV2 = {
+    args: unknown;
+    requestedTool?: string;
+};
 /** 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_denied` events. Emitted when the LLM names a tool the agent doesn't expose. */
+/** Historical v1 data shape for `tool_denied` events. V2 writers emit
+ * `tool_call_rejected` for unavailable provider requests instead. */
 type ToolDeniedData = {
     args?: unknown;
     reason?: string;
     callId?: string;
 };
+/** A validation issue for a provider-issued tool invocation.
+ *
+ * Values are deliberately omitted: paths and validator codes are sufficient
+ * for correction without copying application data into diagnostic channels.
+ */
+type ToolArgumentIssue = {
+    path: readonly (string | number)[];
+    code: string;
+    message?: string;
+};
+/** Data shape for a v2 tool request rejected before execution starts. */
+type ToolCallRejectedData = {
+    reason: 'unavailable';
+    requestedTool: string;
+    availableTools: string[];
+} | {
+    reason: 'invalid_json';
+    requestedTool: string;
+    message: string;
+} | {
+    reason: 'invalid_arguments';
+    requestedTool: string;
+    args: unknown;
+    issues: readonly ToolArgumentIssue[];
+};
+/** Host-observable error details for a terminal tool outcome. */
+type ToolEventError = {
+    name: string;
+    message: string;
+    code?: string;
+    /** Optional host-only diagnostic cause. Redaction removes this at every
+     * untrusted observation boundary. */
+    cause?: unknown;
+};
+/** Constructor input for the next-major model-safe thrown tool failure. */
+type ToolFailureOptions = {
+    message: string;
+    modelMessage: string;
+    code?: string;
+    cause?: unknown;
+};
+/** Failure details for an accepted v2 tool invocation. */
+type ToolCallFailure = {
+    phase: 'approval';
+    kind: 'infrastructure';
+    disposition: 'abort';
+    error: ToolEventError;
+} | {
+    phase: 'before_hook';
+    kind: 'tool_failure';
+    disposition: 'continue';
+    error: ToolEventError;
+} | {
+    phase: 'before_hook';
+    kind: 'unexpected';
+    disposition: 'abort';
+    error: ToolEventError;
+} | {
+    phase: 'handler';
+    kind: 'tool_failure' | 'mcp_error';
+    disposition: 'continue';
+    error: ToolEventError;
+    attempts: number;
+} | {
+    phase: 'handler';
+    kind: 'unexpected';
+    disposition: 'abort';
+    error: ToolEventError;
+    attempts: number;
+} | {
+    phase: 'after_hook';
+    kind: 'tool_failure';
+    disposition: 'continue';
+    error: ToolEventError;
+    result: unknown;
+} | {
+    phase: 'after_hook';
+    kind: 'unexpected';
+    disposition: 'abort';
+    error: ToolEventError;
+    result: unknown;
+} | {
+    phase: 'projection' | 'serialization';
+    kind: 'output';
+    disposition: 'abort';
+    error: ToolEventError;
+    result: unknown;
+};
+/** Cancellation details for an accepted v2 tool invocation. */
+type ToolCallCancellation = {
+    phase: 'approval' | 'before_hook' | 'handler';
+    reason?: string;
+} | {
+    phase: 'after_handler' | 'after_hook' | 'projection' | 'serialization';
+    result: unknown;
+    reason?: string;
+};
+/** Terminal state of an accepted v2 tool invocation. */
+type ToolCallOutcome = {
+    status: 'succeeded';
+    result: unknown;
+} | {
+    status: 'failed';
+    failure: ToolCallFailure;
+} | {
+    status: 'denied';
+    reason?: string;
+} | {
+    status: 'cancelled';
+    cancellation: ToolCallCancellation;
+};
+/** Data shape for a v2 `tool_call_end` event. */
+type ToolCallEndData = {
+    args: unknown;
+    requestedTool?: string;
+    outcome: ToolCallOutcome;
+};
 /** Data shape for `handoff_start` events (always emitted, pre-transition). */
 type HandoffStartData = {
     source: string;
@@ -586,6 +714,26 @@ type WorkflowStartData = {
     /** The validated input passed to the workflow handler. */
     input: unknown;
 };
+/** Machine-readable completeness of an observation surface or execution trace. */
+type ObservationStatus = {
+    complete: true;
+} | {
+    complete: false;
+    reason: 'queue_overflow';
+    droppedEvents: number;
+} | {
+    complete: false;
+    reason: 'branch_drain_timeout';
+    pendingContinuations: number;
+    timeoutMs: number;
+} | {
+    complete: false;
+    reason: 'persistence_truncated';
+    maxEvents: number;
+} | {
+    complete: false;
+    reason: 'process_interrupted';
+};
 /** Data shape for `workflow_end` events. Emitted once per workflow execution
  *  on completion, failure, or cancellation. Distinguish cancellation via `aborted`. */
 type WorkflowEndData = {
@@ -598,6 +746,9 @@ type WorkflowEndData = {
     /** True when the failure was an `AbortError` (user cancellation, budget hard_stop,
      *  or consumer disconnect on streaming workflows). */
     aborted?: boolean;
+    /** Completeness of the terminal trace. Present on new executions; absent
+     *  on historical events written before completeness signaling shipped. */
+    observation?: ObservationStatus;
 };
 /** Data shape for `checkpoint_save` / `checkpoint_replay` events.
  *  Emitted by `ctx.checkpoint(name, fn)` — `save` on first execution,
@@ -723,22 +874,6 @@ type AskScoped = {
      *  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;
-};
 /**
  * Unified event union. Replaces the old `TraceEvent` (rich, persisted) and
  * `StreamEvent` (lean, wire) by emitting a single rich event from one site
@@ -757,7 +892,7 @@ type CallbackMeta = {
  * exhaustiveness fixture in `__tests__/axl-event-exhaustive.test-d.ts` will
  * also fail until the new case is handled.
  */
-type AxlEvent = (AxlEventBase & {
+type LegacyAxlEventPayloadV1 = (AxlEventBase & {
     type: 'workflow_start';
     workflow: string;
     data: WorkflowStartData;
@@ -934,6 +1069,59 @@ type AxlEvent = (AxlEventBase & {
         code?: string;
     };
 });
+/** Tool lifecycle variants written by the v2 event schema. */
+type ToolLifecycleEventV2 = (AxlEventBase & AskScoped & {
+    schemaVersion: 2;
+    type: 'tool_call_start';
+    agent: string;
+    tool: string;
+    callId: string;
+    data: ToolCallStartDataV2;
+}) | (AxlEventBase & AskScoped & {
+    schemaVersion: 2;
+    type: 'tool_call_end';
+    agent: string;
+    tool: string;
+    callId: string;
+    duration: number;
+    cost?: number;
+    data: ToolCallEndData;
+}) | (AxlEventBase & AskScoped & {
+    schemaVersion: 2;
+    type: 'tool_call_rejected';
+    agent: string;
+    tool: string;
+    callId: string;
+    data: ToolCallRejectedData;
+});
+/** Event persisted by the legacy unversioned writer. Readers may normalize the
+ * absent marker to an explicit `1` without reinterpreting its payload. */
+type LegacyAxlEventV1 = LegacyAxlEventPayloadV1 & {
+    schemaVersion?: 1;
+};
+/** Named v2 rejection event for consumers that do not need the full union. */
+type ToolCallRejectedEvent = Extract<ToolLifecycleEventV2, {
+    type: 'tool_call_rejected';
+}>;
+/** Event contract written by the next breaking runtime.
+ *
+ * This additive prototype lets consumers and type tests lock the schema before
+ * the runtime writer switches. Every v2 event carries the version directly;
+ * `tool_denied` and the v1 tool end shape cannot be represented.
+ */
+type AxlEventV2 = ToolLifecycleEventV2 | (Exclude<LegacyAxlEventPayloadV1, {
+    type: 'tool_call_start' | 'tool_call_end' | 'tool_denied';
+}> & {
+    schemaVersion: 2;
+});
+/** Current live event contract. Every emitted event is explicitly v2. */
+type AxlEvent = AxlEventV2;
+/** Event returned by state-store and recovery readers during the migration. */
+type HistoricalAxlEvent = LegacyAxlEventV1 | AxlEventV2;
+/** Convenience: extract a v2 union member by discriminator. */
+type AxlEventV2Of<T extends AxlEventV2['type']> = Extract<AxlEventV2, {
+    type: T;
+}>;
 /** Convenience: extract the union member matching a given `type` discriminator. */
 type AxlEventOf<T extends AxlEventType> = Extract<AxlEvent, {
     type: T;
@@ -975,14 +1163,14 @@ type OutputValidator<T = unknown> = (output: T, ctx: {
     metadata: Record<string, unknown>;
 }) => ValidateResult | Promise<ValidateResult>;
 /** Execution info */
-type ExecutionInfo = {
+type ExecutionInfoV1 = {
     executionId: string;
     workflow: string;
     status: ExecutionStatus;
     /** 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[];
+    events: LegacyAxlEventV1[];
     /** Total spend for the execution. A LOWER BOUND when an unpriced model ran
      *  (those calls contribute nothing) — read {@link ExecutionInfo.unpriced} to
      *  know whether it's exact, rather than scanning the event timeline. */
@@ -999,6 +1187,9 @@ type ExecutionInfo = {
     duration: number;
     result?: unknown;
     error?: string;
+    /** Completeness of the persisted event timeline. Absent on historical
+     *  rows written before completeness signaling shipped. */
+    observation?: ObservationStatus;
     /** Caller-supplied metadata threaded verbatim from `ExecuteOptions.metadata`
      *  (or `runtime.stream()`'s `options.metadata`). Persisted as part of the
      *  `ExecutionInfo` snapshot so callers have a stable, queryable surface for
@@ -1008,6 +1199,19 @@ type ExecutionInfo = {
      *  provided — `StateStore` is a persistence boundary, not a query engine. */
     metadata?: Record<string, unknown>;
 };
+/** Stored execution written before explicit event schema versioning. */
+type LegacyExecutionInfoV1 = ExecutionInfoV1 & {
+    eventSchemaVersion?: 1;
+};
+/** Stored or live execution written by the v2 event writer. */
+type ExecutionInfoV2 = Omit<ExecutionInfoV1, 'events'> & {
+    eventSchemaVersion: 2;
+    events: AxlEventV2[];
+};
+/** Current live execution contract. Historical reads retain their explicit union. */
+type ExecutionInfo = ExecutionInfoV2;
+/** Honest state-store read contract: missing version metadata means v1. */
+type HistoricalExecutionInfo = LegacyExecutionInfoV1 | ExecutionInfoV2;
 /** Record of an agent handoff event (persisted in session metadata).
  *
  *  `duration` semantics:
@@ -1098,6 +1302,82 @@ type ProviderResponse = {
     providerMetadata?: Record<string, unknown>;
 };
 
+/** Base error class for all Axl errors */
+declare class AxlError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Strict observation overflow. Kept in the shared error module so every
+ * recovery boundary can identify the same non-recoverable control error.
+ * Thrown at the producer when an event queue configured with
+ * `onOverflow: 'throw'` exceeds `maxQueued`.
+ */
+declare class EventStreamOverflowError extends Error {
+    readonly maxQueued: number;
+    readonly eventType: string;
+    readonly cause?: unknown;
+    constructor(maxQueued: number, eventType: string, cause?: unknown);
+}
+/** A known tool failure whose author-provided model message is safe to expose. */
+declare class ToolFailure extends AxlError {
+    readonly modelMessage: string;
+    readonly cause?: unknown;
+    constructor(options: ToolFailureOptions);
+}
+type ToolFailureConstructor = typeof ToolFailure;
+/** Thrown when a tool's model-facing output cannot be projected safely. */
+declare class ToolModelOutputError extends AxlError {
+    readonly toolName: string;
+    readonly cause: unknown;
+    constructor(toolName: string, cause: unknown);
+}
+/** Thrown when schema validation fails after all retries exhausted */
+declare class VerifyError extends AxlError {
+    readonly lastOutput: unknown;
+    readonly zodError: ZodError;
+    readonly retries: number;
+    constructor(lastOutput: unknown, zodError: ZodError, retries: number);
+}
+/** Thrown when quorum is not met in spawn */
+declare class QuorumNotMet extends AxlError {
+    readonly results: Result<unknown>[];
+    constructor(required: number, actual: number, results: Result<unknown>[]);
+}
+/** Thrown when vote cannot reach consensus */
+declare class NoConsensus extends AxlError {
+    constructor(reason: string);
+}
+/** Thrown when an operation exceeds its timeout */
+declare class TimeoutError extends AxlError {
+    constructor(operation: string, timeoutMs: number);
+}
+/** Thrown when a budget limit is exceeded */
+declare class BudgetExceededError extends AxlError {
+    readonly limit: number;
+    readonly spent: number;
+    readonly policy: string;
+    constructor(limit: number, spent: number, policy: string);
+}
+/** Thrown when an agent exceeds its maximum number of tool-calling turns */
+declare class MaxTurnsError extends AxlError {
+    readonly maxTurns: number;
+    constructor(operation: string, maxTurns: number);
+}
+/** Thrown when a guardrail blocks a request/response and the policy is 'throw'. */
+declare class GuardrailError extends AxlError {
+    readonly guardrailType: 'input' | 'output';
+    readonly reason: string;
+    constructor(guardrailType: 'input' | 'output', reason: string);
+}
+/** Thrown when post-schema business rule validation fails after all retries exhausted */
+declare class ValidationError extends AxlError {
+    readonly lastOutput: unknown;
+    readonly reason: string;
+    readonly retries: number;
+    constructor(lastOutput: unknown, reason: string, retries: number);
+}
+
 /** Descriptor for a handoff target agent with optional description. */
 type HandoffDescriptor = {
     agent: Agent;
@@ -1165,11 +1445,13 @@ 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. */
+ *  `ctx.events`). Controls the overflow safety net on the main iterator queue
+ *  and each listener-based `stringStream()` subscriber 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.
+    /** Soft cap on the number of events held while waiting for a consumer,
+     *  including distinct pending fields in each `stringStream()` subscriber.
+     *  Terminal events (`done`, `error`, `workflow_end`) are exempt from the
+     *  main iterator cap and always pass through. Default 10_000.
      *
      *  Set to `Infinity` to disable the cap (matches pre-0.x behavior). */
     maxQueued?: number;
@@ -1216,7 +1498,8 @@ type CoalescedPartialObject = {
 /**
  * The shape yielded by `AxlEventBus.stringStream` (and `AxlStream.stringStream`).
  *
- * A live `string_delta` event carries `delta` (the new chars from this chunk)
+ * A live `string_delta` event carries `delta` (the new chars since this
+ * subscriber's previous yield; slow subscribers may coalesce source chunks)
  * and `accumulated` (every char emitted so far for this ask + path,
  * i.e. `delta1 + delta2 + ...`). Consumers rendering full-field state set
  * their UI text to `accumulated`; consumers rendering incrementally use
@@ -1240,8 +1523,9 @@ type StringStreamEvent = {
     agent?: string;
     /** RFC 6901 JSON Pointer; matches the source `string_delta.data.path`. */
     path: string;
-    /** Chars added in this delta. For seeded synthetic events on subscribe,
-     *  equals `accumulated` (the full text-so-far). */
+    /** Chars added since this subscriber's previous yield. May combine several
+     *  source chunks when the subscriber is slow. For seeded events, equals
+     *  `accumulated` (the full text-so-far). */
     delta: string;
     /** Concatenation of every delta this ask + path has emitted in the
      *  current attempt. Cleared on `pipeline(failed)` and `ask_end`. */
@@ -1266,29 +1550,6 @@ type StringStreamFilter = {
     path?: string;
     askId?: string;
 };
-/**
- * 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`.
  *
@@ -1319,6 +1580,7 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
     private readonly maxQueued;
     private readonly onOverflow;
     private overflowWarned;
+    private droppedEvents;
     /** 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. */
@@ -1364,6 +1626,10 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
      * can be 4 KB+ each, hence the more aggressive cleanup here).
      */
     private stringStreamByAsk;
+    /** Internal fan-out for `stringStream()` subscribers. Kept separate from
+     *  the public EventEmitter so strict curated-view overflow is a runtime
+     *  signal, not mistaken for (and swallowed as) a buggy user listener. */
+    private stringStreamSubscribers;
     /**
      * Hook fired when an iterator obtained from `[Symbol.asyncIterator]`
      * is `await using`-disposed. Set via the second constructor argument.
@@ -1385,6 +1651,10 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
      *   Used by `AxlStream` to forward to `Readable.destroy()`.
      */
     constructor(options?: EventStreamOptions, onIteratorDispose?: () => void);
+    /** Machine-readable completeness across this bus's bounded iterable views.
+     *  EventEmitter listener delivery is independent and is not described by
+     *  this status. */
+    get observationStatus(): ObservationStatus;
     private unknownEventWarned;
     /** Subscribe to an `AxlEvent` variant by type. Names outside
      *  `AXL_EVENT_TYPES` are dropped (the bus only emits those names) but
@@ -1519,6 +1789,7 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
      *  non-terminal event arrives. Terminal events bypass this path entirely
      *  (checked by the caller). */
     private handleOverflow;
+    private warnOverflow;
     /**
      * Mark the bus as finished. Wakes any pending iterators with `done: true`
      * and drops further `_push` calls. Idempotent.
@@ -1928,7 +2199,8 @@ type PendingDecision = {
     metadata?: Record<string, unknown>;
     createdAt: string;
 };
-/** Persisted execution state for suspend/resume. */
+/** Legacy application-managed execution state. Axl does not automatically
+ * resume workflow continuations from this record. */
 type ExecutionState = {
     workflow: string;
     input: unknown;
@@ -1968,11 +2240,11 @@ interface StateStore {
     /** Delete a memory entry by key. */
     deleteMemory?(scope: string, key: string): Promise<void>;
     /** Save a completed/failed execution to history. */
-    saveExecution?(execution: ExecutionInfo): Promise<void>;
+    saveExecution?(execution: HistoricalExecutionInfo): Promise<void>;
     /** Get a specific execution by ID from history. */
-    getExecution?(executionId: string): Promise<ExecutionInfo | null>;
+    getExecution?(executionId: string): Promise<HistoricalExecutionInfo | null>;
     /** List recent executions (most recent first). */
-    listExecutions?(limit?: number): Promise<ExecutionInfo[]>;
+    listExecutions?(limit?: number): Promise<HistoricalExecutionInfo[]>;
     /**
      * Delete an execution from history by ID. Returns `true` if an entry was
      * deleted, `false` if the ID didn't exist. Used for GDPR right-to-be-
@@ -2029,7 +2301,7 @@ interface StateStore {
      * Read the events accumulated in the streaming buffer for an execution.
      * Returns `[]` if no buffer exists.
      */
-    getStreamingEvents?(executionId: string): Promise<AxlEvent[]>;
+    getStreamingEvents?(executionId: string): Promise<HistoricalAxlEvent[]>;
     close?(): Promise<void>;
     deleteCheckpoints?(executionId: string): Promise<void>;
 }
@@ -2054,7 +2326,7 @@ type TelemetryConfig = {
 interface SpanHandle {
     setAttribute(key: string, value: string | number | boolean): void;
     addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
-    setStatus(code: 'ok' | 'error', message?: string): void;
+    setStatus(code: 'unset' | 'ok' | 'error', message?: string): void;
     end(): void;
 }
 /** Manages span creation and context propagation. */
@@ -2214,7 +2486,8 @@ type StateConfig = {
      * `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.
+     * in-memory `ExecutionInfo.events` array is bounded. The execution's
+     * `observation` becomes `persistence_truncated`.
      *
      * Default: 50_000. Set to `Infinity` to disable the cap (legacy
      * behavior; only safe for short-lived executions). Must be a positive
@@ -2235,7 +2508,8 @@ type StateConfig = {
      *   terminal exit. If the process crashes mid-run, call
      *   `runtime.recoverIncompleteStreams()` on the next process to reconstruct
      *   the partial `ExecutionInfo` from the streaming buffer (status: `'failed'`,
-     *   error: `'process terminated'`). Use this in production when you need to
+     *   error: `'process terminated'`, observation: `process_interrupted`). Use
+     *   this in production when you need to
      *   know "what did the workflow do up to the crash."
      *
      * Excluded from streaming flush even in `'streaming'` mode: `token`,
@@ -2554,6 +2828,16 @@ declare class MemoryManager {
     close(): Promise<void>;
 }
 
+type BranchDrainState = {
+    pending: Set<Promise<unknown>>;
+    overflow?: EventStreamOverflowError;
+    timeoutMs: number;
+    deadline?: number;
+};
+type WorkflowLifecycleState = {
+    startEmitted: boolean;
+    endEmitted: boolean;
+};
 /** Convert a Zod schema to JSON Schema. Exported for Studio tool introspection.
  *  Wraps Zod v4's built-in `z.toJSONSchema()`, stripping the `$schema` key
  *  since tool parameter schemas are embedded objects, not standalone documents.
@@ -2599,6 +2883,15 @@ type BudgetContextState = {
     /** Dedup guard so the unpriced warning fires at most once per budget block. */
     unpricedWarned: boolean;
 };
+/** Structured host signal emitted when approval compensation cannot remove a
+ * persisted pending request. This is deliberately a runtime event rather than
+ * an `AxlEvent`: it describes control-plane store health, not workflow work. */
+type DecisionCleanupFailedEvent = {
+    executionId: string;
+    workflow?: string;
+    operation: 'resolveDecision_compensation';
+    error: unknown;
+};
 type WorkflowContextInit = {
     input: unknown;
     executionId: string;
@@ -2607,17 +2900,10 @@ type WorkflowContextInit = {
     providerRegistry: ProviderRegistry;
     sessionHistory?: ChatMessage[];
     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;
-    }, meta: CallbackMeta) => void;
-    pendingDecisions?: Map<string, (d: HumanDecision) => void>;
+    pendingDecisions?: Map<string, PendingDecisionResolver>;
+    /** Internal: root-shared guard because pending decisions are currently
+     *  keyed by executionId rather than requestId. */
+    awaitHumanClaims?: Map<string, AbortController>;
     budgetContext?: BudgetContextState;
     stateStore?: StateStore;
     signal?: AbortSignal;
@@ -2627,19 +2913,14 @@ type WorkflowContextInit = {
     spanManager?: SpanManager;
     /** MemoryManager for ctx.remember() / ctx.recall() operations. */
     memoryManager?: MemoryManager;
-    /** When true, the context replays from checkpoints before executing. */
-    resumeMode?: boolean;
     /** Override tool handlers by name. Bypasses normal tool lookup in executeAgentCall. */
     toolOverrides?: Map<string, (args: unknown) => Promise<unknown>>;
     /** Handler for awaitHuman — when set, returns immediately instead of waiting for pendingDecisions. */
     awaitHumanHandler?: (options: AwaitHumanOptions) => HumanDecision | Promise<HumanDecision>;
-    /** Callback fired when an agent LLM call is about to start. */
-    onAgentStart?: (info: {
-        agent: string;
-        model: string;
-    }, meta: CallbackMeta) => void;
     /** Callback fired after each ctx.ask() completes (once per ask invocation). */
     onAgentCallComplete?: (call: AgentCallInfo) => void;
+    /** Internal: reports approval compensation failures to the owning runtime. */
+    _onDecisionCleanupFailed?: (event: DecisionCleanupFailedEvent) => 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,
@@ -2656,6 +2937,9 @@ type WorkflowContextInit = {
     _busRef?: {
         current: AxlEventBus | undefined;
     };
+    /** Internal: force provider streaming for runtime.stream(). Inherited by
+     * child contexts. */
+    _forceStreaming?: boolean;
     /** 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.
@@ -2673,6 +2957,31 @@ type WorkflowContextInit = {
         byAgent: Map<string, number>;
         root: number;
     };
+    /** Internal: root-shared state for branch continuations that must settle
+     *  before the runtime emits the workflow terminal and snapshots cost. */
+    branchDrainState?: BranchDrainState;
+    /** Internal: root-shared lifecycle state. Prevents child contexts from
+     *  emitting trace events after the workflow terminal. */
+    workflowLifecycleState?: WorkflowLifecycleState;
+    /** Runtime terminal barrier for abort-ignoring race/quorum branches. */
+    branchDrainTimeoutMs?: number;
+};
+/** @internal Coordination gate shared between WorkflowContext and AxlRuntime. */
+type PendingDecisionResolver = {
+    resolve: (decision: HumanDecision) => void;
+    ready: Promise<void>;
+    state: 'preparing' | 'pending' | 'resolving' | 'resolved' | 'failed';
+    /** Set synchronously by the abort listener so no new public resolution can
+     *  claim the request while cleanup remains discoverable to deleteExecution. */
+    cancelled: boolean;
+    /** Present while runtime.resolveDecision owns the durable store mutation.
+     *  Cancellation waits for this result before deciding whether compensation
+     *  is still needed, so custom stores never receive contradictory writes in
+     *  parallel for the same request. */
+    resolution?: Promise<boolean>;
+    /** Resolves after cancellation compensation and resolver cleanup finish.
+     *  deleteExecution joins this barrier before its total store sweep. */
+    cleanupFinished: Promise<void>;
 };
 /**
  * The central coordination object for all Axl primitives.
@@ -2692,9 +3001,8 @@ declare class WorkflowContext<TInput = unknown> {
     private providerRegistry;
     private sessionHistory;
     private onTrace?;
-    private onToken?;
-    private onToolCall?;
     private pendingDecisions?;
+    private readonly awaitHumanClaims;
     private budgetContext?;
     private stateStore?;
     /** Root step counter for this execution. Inherited by every ctx.ask()
@@ -2715,27 +3023,27 @@ declare class WorkflowContext<TInput = unknown> {
      * the caller-supplied key.
      */
     private autoCheckpointCounters;
-    /** Idempotency guards for `workflow_start` / `workflow_end` emission.
+    private readonly branchDrainState;
+    /** Root-shared idempotency guards for workflow lifecycle 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;
+     *  events for one execution. Sharing the state with child contexts also
+     *  suppresses late branch events after bounded finalization. */
+    private readonly workflowLifecycleState;
     private signal?;
     private summaryCache?;
     private workflowName?;
     private mcpManager?;
     private spanManager?;
     private memoryManager?;
-    private resumeMode;
     private toolOverrides?;
     private awaitHumanHandler?;
-    private onAgentStart?;
     private onAgentCallComplete?;
+    private _onDecisionCleanupFailed?;
     /** 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
@@ -2744,6 +3052,7 @@ declare class WorkflowContext<TInput = unknown> {
      *  contexts that never observe). */
     private readonly _busRef;
     private readonly _eventStreamOptions?;
+    private readonly _forceStreaming;
     /** 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()` /
@@ -2763,8 +3072,7 @@ declare class WorkflowContext<TInput = unknown> {
      *    *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.
+     *    iterable provides typed per-context observation.
      *  - **Cross-execution**: prefer `runtime.on('trace', …)` instead — that
      *    fans out across all executions, while `ctx.events` is per-context.
      *
@@ -2779,9 +3087,9 @@ declare class WorkflowContext<TInput = unknown> {
      *
      * **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
+     * present at the time the ask starts (`_streamingEnabled` — an explicit
+     * runtime streaming mode or allocated `ctx.events`). 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
@@ -2809,11 +3117,9 @@ declare class WorkflowContext<TInput = unknown> {
      *  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
+    /** True when asks should use provider streaming: `runtime.stream()` set an
+     *  explicit internal mode or `ctx.events` has been allocated. `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`
@@ -2825,16 +3131,9 @@ declare class WorkflowContext<TInput = unknown> {
      * 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, AND the
-     *         streaming callbacks (onToken / onAgentStart / onToolCall).
+     *         awaitHuman handler, pending decisions, tool overrides, and event bus.
      * 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.
-     *
      * 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
@@ -2848,18 +3147,15 @@ declare class WorkflowContext<TInput = unknown> {
      * 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;
+    private _registerBranchDrain;
+    /** Wait for race/quorum losers (including nested branch work) to settle.
+     *  Primitive calls still resolve as soon as their winner/quorum is known;
+     *  this is only the runtime's terminal/persistence barrier. */
+    _drainBranchWork(): Promise<ObservationStatus>;
+    /** Resolve, execute, and observe one non-handoff tool request. Rejections
+     * never start. Every accepted request emits one terminal event before a
+     * continuation message or abort escapes this coordinator. */
+    private observeToolInvocation;
     ask<T = string>(agent: Agent, prompt: string, options?: AskOptions<T>): Promise<T>;
     private executeAgentCall;
     /**
@@ -2895,12 +3191,12 @@ declare class WorkflowContext<TInput = unknown> {
      * Execute a function with checkpoint-replay semantics.
      *
      * 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.).
+     * returns it. A later evaluation in the same explicit execution scope
+     * returns the saved result without re-executing. Axl does not restart or
+     * resume workflow continuations across processes.
      *
      * `name` must be a stable, caller-supplied identifier — the same call
-     * site MUST pass the same name across runs of the same execution for
+     * site MUST pass the same name across evaluations 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:
@@ -3015,6 +3311,7 @@ declare class WorkflowContext<TInput = unknown> {
         result?: unknown;
         error?: string;
         aborted?: boolean;
+        observation?: ObservationStatus;
     }): void;
     log(event: string, data?: unknown): void;
     /**
@@ -3066,6 +3363,10 @@ type ToolHooks<TInput = unknown, TOutput = unknown> = {
     /** Transform output after the handler runs. Receives handler result and workflow context. */
     after?(output: TOutput, ctx: WorkflowContext): TOutput | Promise<TOutput>;
 };
+/** JSON-compatible content that a tool may explicitly expose to the model. */
+type ToolModelOutput = string | number | boolean | null | readonly ToolModelOutput[] | {
+    readonly [key: string]: ToolModelOutput | undefined;
+};
 /** Tool configuration */
 type ToolConfig<TInput extends z.ZodType, TOutput = unknown> = {
     name: string;
@@ -3080,6 +3381,8 @@ type ToolConfig<TInput extends z.ZodType, TOutput = unknown> = {
     requireApproval?: boolean;
     /** Lifecycle hooks: before/after the handler. */
     hooks?: ToolHooks<z.infer<TInput>, TOutput>;
+    /** Select the subset of a successful result that is sent back to the model. */
+    toModelOutput?(this: void, output: Readonly<TOutput>): ToolModelOutput;
 };
 /** A defined tool instance */
 type Tool<TInput extends z.ZodType = z.ZodType, TOutput = unknown> = {
@@ -3090,6 +3393,8 @@ type Tool<TInput extends z.ZodType = z.ZodType, TOutput = unknown> = {
     readonly retry: RetryPolicy;
     readonly requireApproval: boolean;
     readonly hooks?: ToolHooks<z.infer<TInput>, TOutput>;
+    /** Select the subset of a successful result that is sent back to the model. */
+    toModelOutput?(this: void, output: Readonly<TOutput>): ToolModelOutput;
     /** Run the tool directly from workflow code */
     run(ctx: WorkflowContext, input: z.infer<TInput>): Promise<TOutput>;
     /** Execute the handler (internal use — includes retry logic) */
@@ -3202,6 +3507,9 @@ declare class AxlStream extends Readable implements AsyncIterable<AxlEvent> {
         text: string;
     }>;
     get lifecycle(): AsyncIterable<AxlEvent>;
+    /** Completeness of this stream's iterator queue. Check after consumption
+     *  before treating an unmatched lifecycle event as a producer defect. */
+    get observationStatus(): ObservationStatus;
     /** 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
@@ -3375,6 +3683,9 @@ type ExecuteOptions = {
      *  defaults are `maxQueued: 10_000` and `onOverflow:
      *  'drop-oldest-non-terminal'`. */
     events?: EventStreamOptions;
+    /** Maximum terminal wait for abort-ignoring race/quorum branches. Once
+     *  exceeded, finalization proceeds with observation.complete=false. */
+    branchDrainTimeoutMs?: number;
 };
 /**
  * Shape of events forwarded to an eval `onProgress` callback. Mirrors
@@ -3418,23 +3729,6 @@ type CreateContextOptions = {
     signal?: AbortSignal;
     /** Prior conversation history for multi-turn eval testing. */
     sessionHistory?: ChatMessage[];
-    /** 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>;
     /** Configuration for the lazy `ctx.events` bus on the returned context.
@@ -3539,9 +3833,7 @@ declare class AxlRuntime extends EventEmitter {
      * → 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.
+     * "start iff end" pairing invariant and AbortError detection.
      *
      * Side effects on `execInfo`: sets `status` / `completedAt` /
      * `duration` / `result` (or `error`) before emitting `workflow_end`.
@@ -3631,15 +3923,15 @@ 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
+    /** Normalize an execution loaded from a `StateStore` so the
+     *  historical event union 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`. */
+     *  `exec.events` and takes down dependent features. Returns a normalized
+     *  copy; logs at most one warning per `executionId`. */
     private normalizeStoredExecution;
-    getExecutions(): Promise<ExecutionInfo[]>;
+    getExecutions(): Promise<HistoricalExecutionInfo[]>;
     /**
      * Create a WorkflowContext for ad-hoc use (evals, tool testing, prototyping).
      * The context has access to the runtime's providers, state store, MCP manager,
@@ -3700,11 +3992,11 @@ declare class AxlRuntime extends EventEmitter {
      * finalize. The implementation checks the historical store before
      * synthesizing, so a re-run is safe.
      */
-    recoverIncompleteStreams(): Promise<ExecutionInfo[]>;
+    recoverIncompleteStreams(): Promise<HistoricalExecutionInfo[]>;
     /** Abort a running execution by its ID. */
     abort(executionId: string): void;
     /** Get execution details by ID. */
-    getExecution(executionId: string): Promise<ExecutionInfo | undefined>;
+    getExecution(executionId: string): Promise<HistoricalExecutionInfo | undefined>;
     /** Save an eval result to history. */
     saveEvalResult(entry: EvalHistoryEntry): Promise<void>;
     /**
@@ -3759,18 +4051,6 @@ declare class AxlRuntime extends EventEmitter {
     getPendingDecisions(): Promise<PendingDecision[]>;
     /** Resolve a pending human decision. */
     resolveDecision(executionId: string, decision: HumanDecision): Promise<void>;
-    /**
-     * Resume a specific execution that was waiting for a human decision.
-     * Re-runs the workflow from scratch; the workflow should use checkpoint-replay
-     * to skip already-completed steps and pick up from the awaitHuman point.
-     */
-    resumeExecution(executionId: string): Promise<unknown>;
-    /**
-     * Resume all pending executions that were waiting for human decisions.
-     * Call this on startup to resume workflows that were interrupted by a restart.
-     * Returns the execution IDs that were resumed.
-     */
-    resumePending(): Promise<string[]>;
     /**
      * Summarize a list of chat messages into a concise summary string.
      * Used by Session to summarize dropped messages when history.summarize is enabled.
@@ -4207,7 +4487,7 @@ declare function isUsableCost(cost: unknown): cost is number;
  * `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;
+declare function eventCostContribution(event: HistoricalAxlEvent): number;
 /**
  * True when the event is a cost-bearing leaf (contributes directly to
  * totals) — used by internal emitters that need to know whether to
@@ -4217,7 +4497,7 @@ declare function eventCostContribution(event: AxlEvent): number;
  * 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;
+declare function isCostBearingLeaf(event: HistoricalAxlEvent): boolean;
 /**
  * True when the event is the "unpriced lower-bound" signal: a cost-bearing leaf
  * that did measurable, billable work (POSITIVE tokens) but produced no usable
@@ -4257,7 +4537,7 @@ declare function isUnpricedLeaf(event: {
  * (out-of-ask lifecycle events, synthesized terminals) are treated
  * as root-level — they're never at depth ≥ 1.
  */
-declare function isRootLevel(event: AxlEvent): boolean;
+declare function isRootLevel(event: HistoricalAxlEvent): boolean;
 
 /**
  * Tolerant JSON parser for progressive structured-output streaming.
@@ -4291,6 +4571,25 @@ declare function isRootLevel(event: AxlEvent): boolean;
 /** Parse a JSON-shaped string that may be truncated mid-stream. */
 declare function parsePartialJson(input: string): unknown;
 
+declare class UnsupportedEventSchemaVersionError extends Error {
+    readonly version: unknown;
+    constructor(version: unknown);
+}
+/** Missing event metadata is the documented v1 sentinel. */
+declare function getEventSchemaVersion(event: {
+    schemaVersion?: unknown;
+}): 1 | 2;
+/** Missing execution metadata is the documented v1 sentinel. */
+declare function getExecutionEventSchemaVersion(execution: {
+    eventSchemaVersion?: unknown;
+}): 1 | 2;
+/**
+ * Normalize one state-store row without reinterpreting event payloads.
+ * Every event must agree with the execution carrier; mixed-version traces fail
+ * loudly instead of being guessed into either reducer.
+ */
+declare function normalizeStoredExecution(execution: HistoricalExecutionInfo): HistoricalExecutionInfo;
+
 /**
  * Per-variant redaction rules for `AxlEvent`.
  *
@@ -4325,88 +4624,52 @@ declare function parsePartialJson(input: string): unknown;
  */
 
 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.
- */
+type V2ToolEventType = ToolLifecycleEventV2['type'];
+type V2ToolRule<T extends V2ToolEventType> = (event: Extract<ToolLifecycleEventV2, {
+    type: T;
+}>) => Extract<ToolLifecycleEventV2, {
+    type: T;
+}>;
+/** Current-writer redaction rules. The mapped type makes every live event
+ * discriminator an explicit compile-time redaction decision. */
 declare const REDACTION_RULES: {
-    [K in AxlEventType]: RuleFor<K>;
+    tool_call_start: V2ToolRule<"tool_call_start">;
+    tool_call_end: V2ToolRule<"tool_call_end">;
+    tool_call_rejected: V2ToolRule<"tool_call_rejected">;
+    workflow_start: RuleFor<"workflow_start">;
+    workflow_end: RuleFor<"workflow_end">;
+    ask_start: RuleFor<"ask_start">;
+    ask_end: RuleFor<"ask_end">;
+    agent_call_start: RuleFor<"agent_call_start">;
+    agent_call_end: RuleFor<"agent_call_end">;
+    token: RuleFor<"token">;
+    tool_approval: RuleFor<"tool_approval">;
+    delegate: RuleFor<"delegate">;
+    handoff_start: RuleFor<"handoff_start">;
+    handoff_return: RuleFor<"handoff_return">;
+    pipeline: RuleFor<"pipeline">;
+    partial_object: RuleFor<"partial_object">;
+    string_delta: RuleFor<"string_delta">;
+    verify: RuleFor<"verify">;
+    schema_diagnostic: RuleFor<"schema_diagnostic">;
+    log: RuleFor<"log">;
+    memory_remember: RuleFor<"memory_remember">;
+    memory_recall: RuleFor<"memory_recall">;
+    memory_forget: RuleFor<"memory_forget">;
+    checkpoint_save: RuleFor<"checkpoint_save">;
+    checkpoint_replay: RuleFor<"checkpoint_replay">;
+    await_human: RuleFor<"await_human">;
+    await_human_resolved: RuleFor<"await_human_resolved">;
+    guardrail: RuleFor<"guardrail">;
+    schema_check: RuleFor<"schema_check">;
+    validate: RuleFor<"validate">;
+    done: RuleFor<"done">;
+    error: RuleFor<"error">;
 };
-/**
- * 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;
-    constructor(code: string, message: string);
-}
-/** Thrown when schema validation fails after all retries exhausted */
-declare class VerifyError extends AxlError {
-    readonly lastOutput: unknown;
-    readonly zodError: ZodError;
-    readonly retries: number;
-    constructor(lastOutput: unknown, zodError: ZodError, retries: number);
-}
-/** Thrown when quorum is not met in spawn */
-declare class QuorumNotMet extends AxlError {
-    readonly results: Result<unknown>[];
-    constructor(required: number, actual: number, results: Result<unknown>[]);
-}
-/** Thrown when vote cannot reach consensus */
-declare class NoConsensus extends AxlError {
-    constructor(reason: string);
-}
-/** Thrown when an operation exceeds its timeout */
-declare class TimeoutError extends AxlError {
-    constructor(operation: string, timeoutMs: number);
-}
-/** Thrown when a budget limit is exceeded */
-declare class BudgetExceededError extends AxlError {
-    readonly limit: number;
-    readonly spent: number;
-    readonly policy: string;
-    constructor(limit: number, spent: number, policy: string);
-}
-/** Thrown when an agent exceeds its maximum number of tool-calling turns */
-declare class MaxTurnsError extends AxlError {
-    readonly maxTurns: number;
-    constructor(operation: string, maxTurns: number);
-}
-/** Thrown when a guardrail blocks a request/response and the policy is 'throw'. */
-declare class GuardrailError extends AxlError {
-    readonly guardrailType: 'input' | 'output';
-    readonly reason: string;
-    constructor(guardrailType: 'input' | 'output', reason: string);
-}
-/** Thrown when post-schema business rule validation fails after all retries exhausted */
-declare class ValidationError extends AxlError {
-    readonly lastOutput: unknown;
-    readonly reason: string;
-    readonly retries: number;
-    constructor(lastOutput: unknown, reason: string, retries: number);
-}
-/** Internal: thrown when an agent tries to call a tool not in its ACL */
-declare class ToolDenied extends AxlError {
-    readonly toolName: string;
-    readonly agentName: string;
-    constructor(toolName: string, agentName: string);
-}
+/** Redact either persisted schema without reinterpreting its lifecycle. */
+declare function redactHistoricalEvent(event: HistoricalAxlEvent): HistoricalAxlEvent;
 
 /**
  * Typed provider errors + shared HTTP-failure classification.
@@ -4838,9 +5101,9 @@ declare class MemoryStore implements StateStore {
         value: unknown;
     }>>;
     deleteMemory(scope: string, key: string): Promise<void>;
-    saveExecution(execution: ExecutionInfo): Promise<void>;
-    getExecution(executionId: string): Promise<ExecutionInfo | null>;
-    listExecutions(limit?: number): Promise<ExecutionInfo[]>;
+    saveExecution(execution: HistoricalExecutionInfo): Promise<void>;
+    getExecution(executionId: string): Promise<HistoricalExecutionInfo | null>;
+    listExecutions(limit?: number): Promise<HistoricalExecutionInfo[]>;
     deleteExecution(executionId: string): Promise<boolean>;
     saveEvalResult(entry: EvalHistoryEntry): Promise<void>;
     listEvalResults(limit?: number): Promise<EvalHistoryEntry[]>;
@@ -4850,7 +5113,7 @@ declare class MemoryStore implements StateStore {
     appendStreamingEvents(executionId: string, events: AxlEvent[]): Promise<void>;
     finalizeStreamingEvents(executionId: string): Promise<void>;
     listStreamingExecutions(): Promise<string[]>;
-    getStreamingEvents(executionId: string): Promise<AxlEvent[]>;
+    getStreamingEvents(executionId: string): Promise<HistoricalAxlEvent[]>;
     close(): Promise<void>;
     deleteCheckpoints(executionId: string): Promise<void>;
     private persistAwaitHumanState;
@@ -4891,6 +5154,10 @@ declare class SQLiteStore implements StateStore {
      *   column (TEXT, nullable, JSON-serialized) so caller-supplied
      *   `ExecuteOptions.metadata` round-trips through history. Existing
      *   rows get `NULL`, deserialized as `metadata: undefined`.
+     * - v4 (event schema): add `execution_history.event_schema_version`.
+     *   Existing rows remain `NULL`, the documented v1 sentinel.
+     * - v5 (observation completeness): add `execution_history.observation`.
+     *   Existing rows remain `NULL`, meaning they predate the contract.
      *
      * Applied BEFORE `initTables()` so the subsequent `CREATE TABLE
      * IF NOT EXISTS` runs against the post-migration column name. Fresh
@@ -4922,9 +5189,9 @@ declare class SQLiteStore implements StateStore {
     saveExecutionState(executionId: string, state: ExecutionState): Promise<void>;
     getExecutionState(executionId: string): Promise<ExecutionState | null>;
     listPendingExecutions(): Promise<string[]>;
-    saveExecution(execution: ExecutionInfo): Promise<void>;
-    getExecution(executionId: string): Promise<ExecutionInfo | null>;
-    listExecutions(limit?: number): Promise<ExecutionInfo[]>;
+    saveExecution(execution: HistoricalExecutionInfo): Promise<void>;
+    getExecution(executionId: string): Promise<HistoricalExecutionInfo | null>;
+    listExecutions(limit?: number): Promise<HistoricalExecutionInfo[]>;
     deleteExecution(executionId: string): Promise<boolean>;
     saveEvalResult(entry: EvalHistoryEntry): Promise<void>;
     listEvalResults(limit?: number): Promise<EvalHistoryEntry[]>;
@@ -5153,9 +5420,9 @@ declare class RedisStore implements StateStore {
         value: unknown;
     }>>;
     deleteMemory(scope: string, key: string): Promise<void>;
-    saveExecution(execution: ExecutionInfo): Promise<void>;
-    getExecution(executionId: string): Promise<ExecutionInfo | null>;
-    listExecutions(limit?: number): Promise<ExecutionInfo[]>;
+    saveExecution(execution: HistoricalExecutionInfo): Promise<void>;
+    getExecution(executionId: string): Promise<HistoricalExecutionInfo | null>;
+    listExecutions(limit?: number): Promise<HistoricalExecutionInfo[]>;
     deleteExecution(executionId: string): Promise<boolean>;
     saveEvalResult(entry: EvalHistoryEntry): Promise<void>;
     listEvalResults(limit?: number): Promise<EvalHistoryEntry[]>;
@@ -5172,7 +5439,7 @@ declare class RedisStore implements StateStore {
     appendStreamingEvents(executionId: string, events: AxlEvent[]): Promise<void>;
     finalizeStreamingEvents(executionId: string): Promise<void>;
     listStreamingExecutions(): Promise<string[]>;
-    getStreamingEvents(executionId: string): Promise<AxlEvent[]>;
+    getStreamingEvents(executionId: string): Promise<HistoricalAxlEvent[]>;
     /** Close the Redis connection. */
     close(): Promise<void>;
     deleteCheckpoints(executionId: string): Promise<void>;
@@ -5244,4 +5511,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { AXL_EVENT_TYPES, AZURE_PROFILE, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type ApiKeySource, type AskOptions, type AskScoped, type AuthHeader, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, AxlRuntime, AxlStream, BEDROCK_PROFILE, BUILTIN_PROFILES, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallbackMeta, type CapabilityFlags, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, DEEPSEEK_PROFILE, 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, GROQ_PROFILE, GeminiProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HumanDecision, InMemoryVectorStore, type InputGuardrail, LLAMACPP_PROFILE, LMSTUDIO_PROFILE, MISTRAL_PROFILE, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OLLAMA_PROFILE, OPENAI_PRICING, OPENAI_PROFILE, OPENROUTER_PROFILE, type OpenAICompatibleOptions, OpenAICompatibleProvider, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type PerModel, type PricingSource, type PricingTable, type Provider, type ProviderAdapter, ProviderError, type ProviderProfile, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RateLimitConfig, RateLimiter, type ReasoningCapture, type ReasoningEmit, type ReasoningProfile, type ReasoningRoundTrip, type RecallOptions, type RecallResult, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryPolicy, SGLANG_PROFILE, SQLiteStore, type SchemaCheckData, type SchemaDiagnosticData, type SchemaPromptOption, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StringDeltaData, type StringStreamEvent, type StringStreamFilter, type TelemetryConfig, ThinkTagScanner, TimeoutError, type Tool, type ToolApprovalData, type ToolCallData, type ToolCallMessage, type ToolCallStartData, type ToolChoice, type ToolConfig, ToolDenied, type ToolDeniedData, type ToolHooks, VLLM_PROFILE, 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, XAI_PROFILE, agent, createSpanManager, defineConfig, estimateOpenAICost, eventCostContribution, expandGlob, extractJson, extractThinkTags, findConfig, hasPositiveTokens, importModule, isCostBearingLeaf, isRetryableStatus, isRootLevel, isUnpricedLeaf, isUsableCost, needsTsxLoader, openaiReasoningEmit, parsePartialJson, pickDefault, pickExport, priceFromTable, reasoningEffortEmit, reasoningObjectEmit, redactEvent, registerConditions, resolveApiKey, resolvePerModel, resolveRuntime, resolveThinkingOptions, stringStreamFromEvents, tool, workflow, zodToJsonSchema };
+export { AXL_EVENT_TYPES, AXL_EVENT_TYPES_V2, AXL_TOOL_LIFECYCLE_TYPES_V2, AZURE_PROFILE, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type ApiKeySource, type AskOptions, type AskScoped, type AuthHeader, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, type AxlEventV2, type AxlEventV2Of, AxlRuntime, AxlStream, BEDROCK_PROFILE, BUILTIN_PROFILES, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CapabilityFlags, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, DEEPSEEK_PROFILE, type DecisionCleanupFailedEvent, type DelegateData, type DelegateOptions, type Effort, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type EventStreamOptions, EventStreamOverflowError, type ExecuteOptions, type ExecutionInfo, type ExecutionInfoV1, type ExecutionInfoV2, type ExecutionState, GROQ_PROFILE, GeminiProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HistoricalAxlEvent, type HistoricalExecutionInfo, type HumanDecision, InMemoryVectorStore, type InputGuardrail, LLAMACPP_PROFILE, LMSTUDIO_PROFILE, type LegacyAxlEventV1, type LegacyExecutionInfoV1, MISTRAL_PROFILE, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OLLAMA_PROFILE, OPENAI_PRICING, OPENAI_PROFILE, OPENROUTER_PROFILE, type ObservationStatus, type OpenAICompatibleOptions, OpenAICompatibleProvider, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type PerModel, type PricingSource, type PricingTable, type Provider, type ProviderAdapter, ProviderError, type ProviderProfile, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RateLimitConfig, RateLimiter, type ReasoningCapture, type ReasoningEmit, type ReasoningProfile, type ReasoningRoundTrip, type RecallOptions, type RecallResult, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryPolicy, SGLANG_PROFILE, SQLiteStore, type SchemaCheckData, type SchemaDiagnosticData, type SchemaPromptOption, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StringDeltaData, type StringStreamEvent, type StringStreamFilter, type TelemetryConfig, ThinkTagScanner, TimeoutError, type Tool, type ToolApprovalData, type ToolArgumentIssue, type ToolCallCancellation, type ToolCallData, type ToolCallEndData, type ToolCallFailure, type ToolCallMessage, type ToolCallOutcome, type ToolCallRejectedData, type ToolCallRejectedEvent, type ToolCallStartData, type ToolCallStartDataV2, type ToolChoice, type ToolConfig, type ToolDeniedData, type ToolEventError, ToolFailure, type ToolFailureConstructor, type ToolFailureOptions, type ToolHooks, type ToolLifecycleEventV2, type ToolModelOutput, ToolModelOutputError, UnsupportedEventSchemaVersionError, VLLM_PROFILE, 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, XAI_PROFILE, agent, createSpanManager, defineConfig, estimateOpenAICost, eventCostContribution, expandGlob, extractJson, extractThinkTags, findConfig, getEventSchemaVersion, getExecutionEventSchemaVersion, hasPositiveTokens, importModule, isCostBearingLeaf, isRetryableStatus, isRootLevel, isUnpricedLeaf, isUsableCost, needsTsxLoader, normalizeStoredExecution, openaiReasoningEmit, parsePartialJson, pickDefault, pickExport, priceFromTable, reasoningEffortEmit, reasoningObjectEmit, redactEvent, redactHistoricalEvent, registerConditions, resolveApiKey, resolvePerModel, resolveRuntime, resolveThinkingOptions, stringStreamFromEvents, tool, workflow, zodToJsonSchema };