@axlsdk/axl 0.15.0 → 0.16.0

package/dist/index.js

@@ -1316,6 +1316,41 @@ ${jsonInstruction}` : jsonInstruction;
 };
 
 // src/providers/gemini.ts
+var GEMINI_DISALLOWED_SCHEMA_KEYS = /* @__PURE__ */ new Set([
+  "additionalProperties",
+  "$schema",
+  "$ref",
+  "$defs",
+  "definitions",
+  "not",
+  "allOf",
+  "patternProperties",
+  "unevaluatedProperties",
+  "unevaluatedItems"
+]);
+function sanitizeSchemaForGemini(schema) {
+  if (Array.isArray(schema)) {
+    return schema.map((item) => sanitizeSchemaForGemini(item));
+  }
+  if (schema === null || typeof schema !== "object") {
+    return schema;
+  }
+  const src = schema;
+  const out = {};
+  for (const [key, value] of Object.entries(src)) {
+    if (GEMINI_DISALLOWED_SCHEMA_KEYS.has(key)) continue;
+    if (key === "oneOf") {
+      out.anyOf = sanitizeSchemaForGemini(value);
+      continue;
+    }
+    if (key === "const") {
+      if (!("enum" in src)) out.enum = [value];
+      continue;
+    }
+    out[key] = sanitizeSchemaForGemini(value);
+  }
+  return out;
+}
 var GEMINI_PRICING = {
   "gemini-2.5-pro": [125e-8, 1e-5],
   "gemini-2.5-flash": [3e-7, 25e-7],
@@ -1486,7 +1521,9 @@ var GeminiProvider = class {
     if (options.responseFormat && options.responseFormat.type !== "text") {
       generationConfig.responseMimeType = "application/json";
       if (options.responseFormat.type === "json_schema" && options.responseFormat.json_schema?.schema) {
-        generationConfig.responseSchema = options.responseFormat.json_schema.schema;
+        generationConfig.responseSchema = sanitizeSchemaForGemini(
+          options.responseFormat.json_schema.schema
+        );
       }
     }
     if (Object.keys(generationConfig).length > 0) {
@@ -1663,7 +1700,7 @@ var GeminiProvider = class {
     return {
       name: tool2.function.name,
       description: tool2.function.description,
-      parameters: tool2.function.parameters
+      parameters: sanitizeSchemaForGemini(tool2.function.parameters)
     };
   }
   // ---------------------------------------------------------------------------
@@ -1922,6 +1959,7 @@ var defaultRegistry = new ProviderRegistry();
 
 // src/context.ts
 import { AsyncLocalStorage } from "async_hooks";
+import { randomUUID } from "crypto";
 import { z, ZodError } from "zod";
 
 // src/errors.ts
@@ -2041,6 +2079,432 @@ var ToolDenied = class extends AxlError {
   }
 };
 
+// src/partial-json.ts
+var MAX_DEPTH = 256;
+function parsePartialJson(input) {
+  const parser = new PartialParser(input);
+  parser.skipWhitespace();
+  if (parser.eof()) return void 0;
+  const result = parser.parseValue();
+  return result.value;
+}
+var PartialParser = class {
+  constructor(src) {
+    this.src = src;
+  }
+  pos = 0;
+  depth = 0;
+  eof() {
+    return this.pos >= this.src.length;
+  }
+  peek() {
+    return this.src[this.pos];
+  }
+  advance() {
+    return this.src[this.pos++];
+  }
+  skipWhitespace() {
+    while (!this.eof()) {
+      const c = this.peek();
+      if (c === " " || c === "\n" || c === "	" || c === "\r") {
+        this.pos++;
+      } else {
+        break;
+      }
+    }
+  }
+  parseValue() {
+    this.skipWhitespace();
+    if (this.eof()) return { value: void 0, complete: false };
+    const c = this.peek();
+    if (c === "{" || c === "[") {
+      if (++this.depth > MAX_DEPTH) {
+        throw new SyntaxError(
+          `Maximum nesting depth exceeded (${MAX_DEPTH}) at position ${this.pos}`
+        );
+      }
+      try {
+        return c === "{" ? this.parseObject() : this.parseArray();
+      } finally {
+        this.depth--;
+      }
+    }
+    if (c === '"') return this.parseString();
+    if (c === "t" || c === "f") return this.parseBool();
+    if (c === "n") return this.parseNull();
+    if (c === "-" || c >= "0" && c <= "9") return this.parseNumber();
+    throw new SyntaxError(`Unexpected character '${c}' at position ${this.pos}`);
+  }
+  parseObject() {
+    this.advance();
+    const obj = {};
+    this.skipWhitespace();
+    if (this.eof()) return { value: obj, complete: false };
+    if (this.peek() === "}") {
+      this.advance();
+      return { value: obj, complete: true };
+    }
+    while (!this.eof()) {
+      this.skipWhitespace();
+      if (this.eof()) return { value: obj, complete: false };
+      if (this.peek() === "}") {
+        this.advance();
+        return { value: obj, complete: true };
+      }
+      if (this.peek() !== '"') {
+        throw new SyntaxError(`Expected '"' at position ${this.pos}, got '${this.peek()}'`);
+      }
+      const keyResult = this.parseString();
+      if (!keyResult.complete) {
+        return { value: obj, complete: false };
+      }
+      const key = keyResult.value;
+      this.skipWhitespace();
+      if (this.eof()) return { value: obj, complete: false };
+      if (this.peek() !== ":") {
+        return { value: obj, complete: false };
+      }
+      this.advance();
+      this.skipWhitespace();
+      if (this.eof()) return { value: obj, complete: false };
+      const valueResult = this.parseValue();
+      if (valueResult.value !== void 0 || valueResult.complete) {
+        obj[key] = valueResult.value;
+      }
+      if (!valueResult.complete) {
+        return { value: obj, complete: false };
+      }
+      this.skipWhitespace();
+      if (this.eof()) return { value: obj, complete: false };
+      const next = this.peek();
+      if (next === ",") {
+        this.advance();
+        continue;
+      }
+      if (next === "}") {
+        this.advance();
+        return { value: obj, complete: true };
+      }
+      throw new SyntaxError(`Expected ',' or '}' at position ${this.pos}, got '${next}'`);
+    }
+    return { value: obj, complete: false };
+  }
+  parseArray() {
+    this.advance();
+    const arr = [];
+    this.skipWhitespace();
+    if (this.eof()) return { value: arr, complete: false };
+    if (this.peek() === "]") {
+      this.advance();
+      return { value: arr, complete: true };
+    }
+    while (!this.eof()) {
+      this.skipWhitespace();
+      if (this.eof()) return { value: arr, complete: false };
+      if (this.peek() === "]") {
+        this.advance();
+        return { value: arr, complete: true };
+      }
+      const elemResult = this.parseValue();
+      if (elemResult.value !== void 0 || elemResult.complete) {
+        arr.push(elemResult.value);
+      }
+      if (!elemResult.complete) {
+        return { value: arr, complete: false };
+      }
+      this.skipWhitespace();
+      if (this.eof()) return { value: arr, complete: false };
+      const next = this.peek();
+      if (next === ",") {
+        this.advance();
+        continue;
+      }
+      if (next === "]") {
+        this.advance();
+        return { value: arr, complete: true };
+      }
+      throw new SyntaxError(`Expected ',' or ']' at position ${this.pos}, got '${next}'`);
+    }
+    return { value: arr, complete: false };
+  }
+  parseString() {
+    this.advance();
+    let result = "";
+    while (!this.eof()) {
+      const c = this.advance();
+      if (c === '"') return { value: result, complete: true };
+      if (c === "\\") {
+        if (this.eof()) {
+          return { value: result, complete: false };
+        }
+        const esc = this.advance();
+        switch (esc) {
+          case '"':
+            result += '"';
+            break;
+          case "\\":
+            result += "\\";
+            break;
+          case "/":
+            result += "/";
+            break;
+          case "b":
+            result += "\b";
+            break;
+          case "f":
+            result += "\f";
+            break;
+          case "n":
+            result += "\n";
+            break;
+          case "r":
+            result += "\r";
+            break;
+          case "t":
+            result += "	";
+            break;
+          case "u": {
+            if (this.pos + 4 > this.src.length) {
+              return { value: result, complete: false };
+            }
+            const hex = this.src.slice(this.pos, this.pos + 4);
+            if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+              throw new SyntaxError(`Invalid \\u escape '${hex}' at position ${this.pos}`);
+            }
+            this.pos += 4;
+            result += String.fromCharCode(parseInt(hex, 16));
+            break;
+          }
+          default:
+            throw new SyntaxError(`Invalid escape '\\${esc}' at position ${this.pos - 1}`);
+        }
+      } else {
+        result += c;
+      }
+    }
+    return { value: result, complete: false };
+  }
+  parseNumber() {
+    const start = this.pos;
+    if (this.peek() === "-") this.advance();
+    while (!this.eof() && this.peek() >= "0" && this.peek() <= "9") this.advance();
+    if (!this.eof() && this.peek() === ".") {
+      this.advance();
+      while (!this.eof() && this.peek() >= "0" && this.peek() <= "9") this.advance();
+    }
+    if (!this.eof() && (this.peek() === "e" || this.peek() === "E")) {
+      this.advance();
+      if (!this.eof() && (this.peek() === "+" || this.peek() === "-")) this.advance();
+      while (!this.eof() && this.peek() >= "0" && this.peek() <= "9") this.advance();
+    }
+    const text = this.src.slice(start, this.pos);
+    if (text === "" || text === "-" || /\.$/.test(text) || /[eE][+-]?$/.test(text)) {
+      return { value: void 0, complete: false };
+    }
+    const n = Number(text);
+    if (Number.isNaN(n)) {
+      return { value: void 0, complete: false };
+    }
+    return { value: n, complete: true };
+  }
+  parseBool() {
+    const remaining = this.src.slice(this.pos);
+    if (remaining.startsWith("true")) {
+      this.pos += 4;
+      return { value: true, complete: true };
+    }
+    if (remaining.startsWith("false")) {
+      this.pos += 5;
+      return { value: false, complete: true };
+    }
+    if ("true".startsWith(remaining) || "false".startsWith(remaining)) {
+      this.pos = this.src.length;
+      return { value: void 0, complete: false };
+    }
+    throw new SyntaxError(`Expected 'true' or 'false' at position ${this.pos}`);
+  }
+  parseNull() {
+    const remaining = this.src.slice(this.pos);
+    if (remaining.startsWith("null")) {
+      this.pos += 4;
+      return { value: null, complete: true };
+    }
+    if ("null".startsWith(remaining)) {
+      this.pos = this.src.length;
+      return { value: void 0, complete: false };
+    }
+    throw new SyntaxError(`Expected 'null' at position ${this.pos}`);
+  }
+};
+
+// src/event-utils.ts
+var COST_BEARING_LEAF_TYPES = [
+  "agent_call_end",
+  "tool_call_end",
+  "memory_remember",
+  "memory_recall"
+];
+var COST_LEAF_SET = new Set(COST_BEARING_LEAF_TYPES);
+function eventCostContribution(event) {
+  if (event.type === "ask_end") return 0;
+  const c = event.cost;
+  return typeof c === "number" && Number.isFinite(c) && c >= 0 ? c : 0;
+}
+function isCostBearingLeaf(event) {
+  return COST_LEAF_SET.has(event.type);
+}
+function isRootLevel(event) {
+  const d = event.depth;
+  return (d ?? 0) === 0;
+}
+
+// src/redaction.ts
+var REDACTED = "[redacted]";
+function walkObjectOneLevel(obj, preserveKeys) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (preserveKeys.has(k) || typeof v === "number" || typeof v === "boolean") {
+      out[k] = v;
+    } else if (typeof v === "string") {
+      out[k] = REDACTED;
+    } else if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+      const inner = v;
+      const innerOut = {};
+      for (const [ik, iv] of Object.entries(inner)) {
+        if (typeof iv === "number" || typeof iv === "boolean") {
+          innerOut[ik] = iv;
+        } else {
+          innerOut[ik] = REDACTED;
+        }
+      }
+      out[k] = innerOut;
+    } else {
+      out[k] = REDACTED;
+    }
+  }
+  return out;
+}
+var LOG_PRESERVE_KEYS = /* @__PURE__ */ new Set(["event"]);
+var MEMORY_PRESERVE_KEYS = /* @__PURE__ */ new Set(["scope"]);
+function redactGate(event) {
+  const d = event.data;
+  if (!d) return event;
+  if (d.reason === void 0 && d.feedbackMessage === void 0) return event;
+  return {
+    ...event,
+    data: {
+      ...d,
+      ...d.reason !== void 0 ? { reason: REDACTED } : {},
+      ...d.feedbackMessage !== void 0 ? { feedbackMessage: REDACTED } : {}
+    }
+  };
+}
+function redactMemory(event) {
+  const d = event.data;
+  if (!d || typeof d !== "object") return event;
+  return {
+    ...event,
+    data: walkObjectOneLevel(d, MEMORY_PRESERVE_KEYS)
+  };
+}
+var passthrough = (e) => e;
+var REDACTION_RULES = {
+  workflow_start: (e) => e.data.input !== void 0 ? { ...e, data: { ...e.data, input: REDACTED } } : e,
+  workflow_end: (e) => {
+    const d = e.data;
+    if (d.result === void 0 && d.error === void 0) return e;
+    return {
+      ...e,
+      data: {
+        ...d,
+        ...d.result !== void 0 ? { result: REDACTED } : {},
+        ...d.error !== void 0 ? { error: REDACTED } : {}
+      }
+    };
+  },
+  ask_start: (e) => ({ ...e, prompt: REDACTED }),
+  ask_end: (e) => ({
+    ...e,
+    outcome: e.outcome.ok ? { ok: true, result: REDACTED } : { ok: false, error: REDACTED }
+  }),
+  agent_call_start: (e) => {
+    const d = e.data;
+    const out = { ...d, prompt: REDACTED };
+    if (d.system !== void 0) out.system = REDACTED;
+    if (Array.isArray(d.messages)) {
+      out.messages = [{ role: "system", content: `[${d.messages.length} messages redacted]` }];
+    }
+    return { ...e, data: out };
+  },
+  agent_call_end: (e) => {
+    const d = e.data;
+    const out = { ...d, response: REDACTED };
+    if (d.thinking !== void 0) out.thinking = REDACTED;
+    if (d.error !== void 0) out.error = REDACTED;
+    return { ...e, data: out };
+  },
+  token: (e) => ({ ...e, data: REDACTED }),
+  tool_call_start: (e) => ({ ...e, data: { ...e.data, args: REDACTED } }),
+  tool_call_end: (e) => ({ ...e, data: { ...e.data, args: REDACTED, result: REDACTED } }),
+  tool_approval: (e) => ({
+    ...e,
+    data: {
+      ...e.data,
+      args: REDACTED,
+      ...e.data.reason !== void 0 ? { reason: REDACTED } : {}
+    }
+  }),
+  tool_denied: (e) => {
+    if (!e.data) return e;
+    const d = e.data;
+    if (d.args === void 0 && d.reason === void 0) return e;
+    return {
+      ...e,
+      data: {
+        ...d,
+        ...d.args !== void 0 ? { args: REDACTED } : {},
+        ...d.reason !== void 0 ? { reason: REDACTED } : {}
+      }
+    };
+  },
+  delegate: passthrough,
+  handoff_start: (e) => e.data.message !== void 0 ? { ...e, data: { ...e.data, message: REDACTED } } : e,
+  handoff_return: passthrough,
+  pipeline: (e) => e.status === "failed" ? { ...e, reason: REDACTED } : e,
+  partial_object: (e) => ({ ...e, data: { ...e.data, object: REDACTED } }),
+  verify: (e) => e.data.lastError !== void 0 ? { ...e, data: { ...e.data, lastError: REDACTED } } : e,
+  log: (e) => {
+    if (!e.data || typeof e.data !== "object" || Array.isArray(e.data)) return e;
+    return { ...e, data: walkObjectOneLevel(e.data, LOG_PRESERVE_KEYS) };
+  },
+  memory_remember: redactMemory,
+  memory_recall: redactMemory,
+  memory_forget: redactMemory,
+  checkpoint_save: passthrough,
+  checkpoint_replay: passthrough,
+  await_human: (e) => e.data.prompt !== void 0 ? { ...e, data: { ...e.data, prompt: REDACTED } } : e,
+  await_human_resolved: (e) => {
+    const dec = e.data.decision;
+    if (!dec) return e;
+    const hasData = "data" in dec && dec.data !== void 0;
+    const hasReason = "reason" in dec && dec.reason !== void 0;
+    if (!hasData && !hasReason) return e;
+    const scrubbed = { ...dec };
+    if (hasData) scrubbed.data = REDACTED;
+    if (hasReason) scrubbed.reason = REDACTED;
+    return { ...e, data: { ...e.data, decision: scrubbed } };
+  },
+  guardrail: redactGate,
+  schema_check: redactGate,
+  validate: redactGate,
+  done: (e) => ({ ...e, data: { result: REDACTED } }),
+  error: (e) => ({ ...e, data: { ...e.data, message: REDACTED } })
+};
+function redactEvent(event) {
+  const rule = REDACTION_RULES[event.type];
+  return rule(event);
+}
+
 // src/config.ts
 function defineConfig(config) {
   return config;
@@ -2118,6 +2582,7 @@ function resolveConfig(config) {
 
 // src/context.ts
 var signalStorage = new AsyncLocalStorage();
+var askStorage = new AsyncLocalStorage();
 function zodToJsonSchema(schema) {
   const result = z.toJSONSchema(schema, { unrepresentable: "any" });
   delete result.$schema;
@@ -2219,8 +2684,34 @@ var WorkflowContext = class _WorkflowContext {
   pendingDecisions;
   budgetContext;
   stateStore;
-  stepCounter = 0;
-  checkpointCounter = 0;
+  /** 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. */
+  stepRefRoot = { value: 0 };
+  /**
+   * 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.
+   */
+  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. */
+  _workflowStartEmitted = false;
+  _workflowEndEmitted = false;
   signal;
   summaryCache;
   workflowName;
@@ -2232,7 +2723,6 @@ var WorkflowContext = class _WorkflowContext {
   awaitHumanHandler;
   onAgentStart;
   onAgentCallComplete;
-  parentToolCallId;
   constructor(init) {
     this.input = init.input;
     this.executionId = init.executionId;
@@ -2256,7 +2746,10 @@ var WorkflowContext = class _WorkflowContext {
     this.awaitHumanHandler = init.awaitHumanHandler;
     this.onAgentStart = init.onAgentStart;
     this.onAgentCallComplete = init.onAgentCallComplete;
-    this.parentToolCallId = init.parentToolCallId;
+    this.autoCheckpointCounters = init.autoCheckpointCounters ?? {
+      byAgent: /* @__PURE__ */ new Map(),
+      root: 0
+    };
     if (init.metadata?.summaryCache) {
       this.summaryCache = init.metadata.summaryCache;
     }
@@ -2265,15 +2758,23 @@ var WorkflowContext = class _WorkflowContext {
    * 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) {
+  createChildContext() {
     return new _WorkflowContext({
       input: this.input,
       executionId: this.executionId,
@@ -2287,18 +2788,20 @@ var WorkflowContext = class _WorkflowContext {
       spanManager: this.spanManager,
       memoryManager: this.memoryManager,
       onTrace: this.onTrace,
+      onToken: this.onToken,
+      onToolCall: this.onToolCall,
+      onAgentStart: this.onAgentStart,
       onAgentCallComplete: this.onAgentCallComplete,
       awaitHumanHandler: this.awaitHumanHandler,
       pendingDecisions: this.pendingDecisions,
       toolOverrides: this.toolOverrides,
       signal: this.signal,
       workflowName: this.workflowName,
-      // Join key for nested event correlation. Inherit the parent's
-      // `parentToolCallId` when this child is itself nested inside another
-      // child — so grand-children still point to the outermost tool call.
-      parentToolCallId: parentToolCallId ?? this.parentToolCallId
-      // Isolated: sessionHistory (empty), stepCounter (0),
-      // onToken (null), onAgentStart (null), onToolCall (null)
+      // Share the parent's auto-checkpoint counters so internal checkpoints
+      // emitted from `ctx.ask` / spawn / race / parallel / map in this
+      // child context don't collide with the parent's in the state store.
+      autoCheckpointCounters: this.autoCheckpointCounters
+      // Isolated: sessionHistory (empty)
     });
   }
   /**
@@ -2309,72 +2812,150 @@ var WorkflowContext = class _WorkflowContext {
   get currentSignal() {
     return signalStorage.getStore() ?? this.signal;
   }
+  /**
+   * 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.
+   */
+  currentCallbackMeta(agentName) {
+    const frame = askStorage.getStore();
+    if (frame) {
+      return {
+        askId: frame.askId,
+        ...frame.parentAskId ? { parentAskId: frame.parentAskId } : {},
+        depth: frame.depth,
+        agent: agentName
+      };
+    }
+    return { askId: this.executionId, depth: 0, agent: agentName };
+  }
   // ── ctx.ask() ─────────────────────────────────────────────────────────
   async ask(agent2, prompt, options) {
-    return this._checkpoint(async () => {
-      const costBefore = this.budgetContext?.totalCost ?? 0;
-      const startTime = Date.now();
-      const resolveCtx = options?.metadata ? { metadata: { ...this.metadata, ...options.metadata } } : { metadata: this.metadata };
-      const usageCapture = {};
-      const doCall = async () => {
-        const result2 = await this.executeAgentCall(
-          agent2,
-          prompt,
-          options,
-          void 0,
-          usageCapture
-        );
-        return result2;
-      };
-      const result = this.spanManager ? await this.spanManager.withSpanAsync(
-        "axl.agent.ask",
-        {
-          "axl.agent.name": agent2._name,
-          "axl.agent.model": agent2.resolveModel(resolveCtx)
-        },
-        async (span) => {
-          const r = await doCall();
-          const costAfter2 = this.budgetContext?.totalCost ?? 0;
-          span.setAttribute("axl.agent.cost", costAfter2 - costBefore);
-          span.setAttribute("axl.agent.duration", Date.now() - startTime);
-          if (usageCapture.value) {
-            span.setAttribute("axl.agent.prompt_tokens", usageCapture.value.prompt_tokens);
-            span.setAttribute(
-              "axl.agent.completion_tokens",
-              usageCapture.value.completion_tokens
+    const agentName = agent2._name;
+    return this._checkpoint(
+      this._autoCheckpointName("ask", agentName),
+      async () => {
+        const parentFrame = askStorage.getStore();
+        const askId = randomUUID();
+        const depth = (parentFrame?.depth ?? -1) + 1;
+        const stepRef = parentFrame?.stepRef ?? this.stepRefRoot;
+        const frame = {
+          askId,
+          parentAskId: parentFrame?.askId,
+          depth,
+          agent: agent2._name,
+          stepRef,
+          askCost: { value: 0 }
+        };
+        return askStorage.run(frame, async () => {
+          const askStart = Date.now();
+          this.emitEvent({ type: "ask_start", prompt });
+          const costBefore = this.budgetContext?.totalCost ?? 0;
+          const resolveCtx = options?.metadata ? { metadata: { ...this.metadata, ...options.metadata } } : { metadata: this.metadata };
+          const usageCapture = {};
+          const doCall = async () => {
+            const result = await this.executeAgentCall(
+              agent2,
+              prompt,
+              options,
+              void 0,
+              usageCapture
             );
-            if (usageCapture.value.cached_tokens)
-              span.setAttribute("axl.agent.cached_tokens", usageCapture.value.cached_tokens);
+            return result;
+          };
+          let outcome;
+          try {
+            const result = this.spanManager ? await this.spanManager.withSpanAsync(
+              "axl.agent.ask",
+              {
+                "axl.agent.name": agent2._name,
+                "axl.agent.model": agent2.resolveModel(resolveCtx)
+              },
+              async (span) => {
+                const r = await doCall();
+                const costAfter2 = this.budgetContext?.totalCost ?? 0;
+                span.setAttribute("axl.agent.cost", costAfter2 - costBefore);
+                span.setAttribute("axl.agent.duration", Date.now() - askStart);
+                if (usageCapture.value) {
+                  span.setAttribute(
+                    "axl.agent.prompt_tokens",
+                    usageCapture.value.prompt_tokens
+                  );
+                  span.setAttribute(
+                    "axl.agent.completion_tokens",
+                    usageCapture.value.completion_tokens
+                  );
+                  if (usageCapture.value.cached_tokens)
+                    span.setAttribute(
+                      "axl.agent.cached_tokens",
+                      usageCapture.value.cached_tokens
+                    );
+                }
+                return r;
+              }
+            ) : await doCall();
+            outcome = { ok: true, result };
+            const costAfter = this.budgetContext?.totalCost ?? 0;
+            if (this.onAgentCallComplete) {
+              try {
+                this.onAgentCallComplete({
+                  agent: agent2._name,
+                  prompt,
+                  response: typeof result === "string" ? result : JSON.stringify(result),
+                  model: agent2.resolveModel(resolveCtx),
+                  cost: costAfter - costBefore,
+                  duration: Date.now() - askStart,
+                  promptVersion: agent2._config.version,
+                  temperature: options?.temperature ?? agent2._config.temperature,
+                  maxTokens: options?.maxTokens ?? agent2._config.maxTokens ?? 4096,
+                  effort: options?.effort ?? agent2._config.effort,
+                  thinkingBudget: options?.thinkingBudget ?? agent2._config.thinkingBudget,
+                  includeThoughts: options?.includeThoughts ?? agent2._config.includeThoughts,
+                  toolChoice: options?.toolChoice ?? agent2._config.toolChoice,
+                  stop: options?.stop ?? agent2._config.stop,
+                  providerOptions: options?.providerOptions ?? agent2._config.providerOptions
+                });
+              } catch (hookErr) {
+                console.error(
+                  "[axl] onAgentCallComplete hook threw; ask outcome unchanged:",
+                  hookErr instanceof Error ? hookErr.message : String(hookErr)
+                );
+              }
+            }
+            return result;
+          } catch (err) {
+            outcome = {
+              ok: false,
+              error: err instanceof Error ? err.message : String(err)
+            };
+            throw err;
+          } finally {
+            this.emitEvent({
+              type: "ask_end",
+              outcome: outcome ?? {
+                ok: false,
+                error: "ask_end emitted without outcome \u2014 internal bug"
+              },
+              cost: frame.askCost.value,
+              duration: Date.now() - askStart
+            });
           }
-          return r;
-        }
-      ) : await doCall();
-      const costAfter = this.budgetContext?.totalCost ?? 0;
-      this.onAgentCallComplete?.({
-        agent: agent2._name,
-        prompt,
-        response: typeof result === "string" ? result : JSON.stringify(result),
-        model: agent2.resolveModel(resolveCtx),
-        cost: costAfter - costBefore,
-        duration: Date.now() - startTime,
-        promptVersion: agent2._config.version,
-        temperature: options?.temperature ?? agent2._config.temperature,
-        maxTokens: options?.maxTokens ?? agent2._config.maxTokens ?? 4096,
-        effort: options?.effort ?? agent2._config.effort,
-        thinkingBudget: options?.thinkingBudget ?? agent2._config.thinkingBudget,
-        includeThoughts: options?.includeThoughts ?? agent2._config.includeThoughts,
-        toolChoice: options?.toolChoice ?? agent2._config.toolChoice,
-        stop: options?.stop ?? agent2._config.stop,
-        providerOptions: options?.providerOptions ?? agent2._config.providerOptions
-      });
-      return result;
-    });
+        });
+      },
+      { agent: agentName }
+    );
   }
   async executeAgentCall(agent2, prompt, options, handoffMessages, usageCapture) {
     if (this.budgetContext?.exceeded) {
       const { limit, totalCost: spent, policy } = this.budgetContext;
       if (policy === "warn") {
-        this.emitTrace({
+        this.emitEvent({
           type: "log",
           data: { warning: "Budget exceeded", limit, spent, policy }
         });
@@ -2463,7 +3044,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
     const guardrails = agent2._config.guardrails;
     if (guardrails?.input) {
       const inputResult = await guardrails.input(prompt, { metadata: this.metadata });
-      this.emitTrace({
+      this.emitEvent({
         type: "guardrail",
         agent: agent2._name,
         data: {
@@ -2497,12 +3078,6 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
     const maxTurns = agent2._config.maxTurns ?? 25;
     const timeoutMs = parseDuration(agent2._config.timeout ?? "60s");
     const startTime = Date.now();
-    if (this.onToken && options?.validate) {
-      throw new AxlError(
-        "INVALID_CONFIG",
-        "Cannot use validate with streaming. Validate requires schema (JSON output) which does not benefit from token streaming. Use a non-streaming call instead."
-      );
-    }
     const currentMessages = [...messages];
     let turns = 0;
     let guardrailOutputRetries = 0;
@@ -2511,11 +3086,42 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
     const maxGuardrailRetries = guardrails?.maxRetries ?? 2;
     let pendingRetryReason;
     const verboseTrace = this.config.trace?.level === "full";
+    let lastStartStage = "initial";
+    let lastStartAttempt = 1;
+    let lastStartMaxAttempts = 1;
     while (turns < maxTurns) {
       if (Date.now() - startTime > timeoutMs) {
         throw new TimeoutError("ctx.ask()", timeoutMs);
       }
       turns++;
+      const isFirstTurn = turns === 1;
+      const isRetryTurn = pendingRetryReason !== void 0;
+      if (isFirstTurn || isRetryTurn) {
+        const stage = pendingRetryReason ?? "initial";
+        let pipelineAttempt = 1;
+        let pipelineMaxAttempts = 1;
+        if (stage === "guardrail") {
+          pipelineAttempt = guardrailOutputRetries + 1;
+          pipelineMaxAttempts = maxGuardrailRetries + 1;
+        } else if (stage === "schema") {
+          pipelineAttempt = schemaRetries + 1;
+          pipelineMaxAttempts = (options?.retries ?? 3) + 1;
+        } else if (stage === "validate") {
+          pipelineAttempt = validateRetries + 1;
+          pipelineMaxAttempts = (options?.validateRetries ?? 2) + 1;
+        }
+        lastStartStage = stage;
+        lastStartAttempt = pipelineAttempt;
+        lastStartMaxAttempts = pipelineMaxAttempts;
+        this.emitEvent({
+          type: "pipeline",
+          agent: agent2._name,
+          status: "start",
+          stage,
+          attempt: pipelineAttempt,
+          maxAttempts: pipelineMaxAttempts
+        });
+      }
       const turnStart = Date.now();
       const chatOptions = {
         model,
@@ -2533,72 +3139,16 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       if (options?.schema && toolDefs.length === 0) {
         chatOptions.responseFormat = { type: "json_object" };
       }
-      this.onAgentStart?.({ agent: agent2._name, model: modelUri });
-      let response;
-      if (this.onToken) {
-        let content2 = "";
-        const toolCalls = [];
-        const toolCallBuffers = /* @__PURE__ */ new Map();
-        let streamProviderMetadata;
-        let thinkingContent = "";
-        for await (const chunk of provider.stream(currentMessages, chatOptions)) {
-          if (chunk.type === "text_delta") {
-            content2 += chunk.content;
-            this.onToken(chunk.content);
-          } else if (chunk.type === "thinking_delta") {
-            thinkingContent += chunk.content;
-          } else if (chunk.type === "tool_call_delta") {
-            let buffer = toolCallBuffers.get(chunk.id);
-            if (!buffer) {
-              buffer = { id: chunk.id, name: "", arguments: "" };
-              toolCallBuffers.set(chunk.id, buffer);
-            }
-            if (chunk.name) buffer.name = chunk.name;
-            if (chunk.arguments) buffer.arguments += chunk.arguments;
-          } else if (chunk.type === "done") {
-            streamProviderMetadata = chunk.providerMetadata;
-            if (chunk.usage) {
-              response = {
-                content: content2,
-                tool_calls: void 0,
-                usage: chunk.usage,
-                cost: chunk.cost
-              };
-            }
-          }
-        }
-        for (const buffer of toolCallBuffers.values()) {
-          toolCalls.push({
-            id: buffer.id,
-            type: "function",
-            function: {
-              name: buffer.name,
-              arguments: buffer.arguments
-            }
-          });
-        }
-        response ??= {
-          content: content2,
-          usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
-        };
-        if (toolCalls.length > 0) {
-          response.tool_calls = toolCalls;
-        }
-        if (streamProviderMetadata) {
-          response.providerMetadata = streamProviderMetadata;
-        }
-        if (thinkingContent) {
-          response.thinking_content = thinkingContent;
-        }
-      } else {
-        response = await provider.chat(currentMessages, chatOptions);
-      }
-      if (usageCapture && response.usage) {
-        usageCapture.value = response.usage;
-      }
-      if (response.cost) {
-        this._accumulateBudgetCost(response.cost);
-      }
+      const callbackMeta = this.currentCallbackMeta(agent2._name);
+      const callParams = {
+        ...chatOptions.temperature !== void 0 ? { temperature: chatOptions.temperature } : {},
+        maxTokens: chatOptions.maxTokens,
+        ...chatOptions.effort !== void 0 ? { effort: chatOptions.effort } : {},
+        ...chatOptions.thinkingBudget !== void 0 ? { thinkingBudget: chatOptions.thinkingBudget } : {},
+        ...chatOptions.includeThoughts !== void 0 ? { includeThoughts: chatOptions.includeThoughts } : {},
+        ...chatOptions.toolChoice !== void 0 ? { toolChoice: chatOptions.toolChoice } : {},
+        ...chatOptions.stop !== void 0 ? { stop: chatOptions.stop } : {}
+      };
       let messagesSnapshot;
       if (verboseTrace) {
         try {
@@ -2613,8 +3163,148 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       }
       const retryReason = pendingRetryReason;
       pendingRetryReason = void 0;
-      this.emitTrace({
-        type: "agent_call",
+      this.emitEvent({
+        type: "agent_call_start",
+        agent: agent2._name,
+        model: modelUri,
+        turn: turns,
+        data: {
+          prompt,
+          ...systemPrompt ? { system: systemPrompt } : {},
+          params: callParams,
+          turn: turns,
+          ...retryReason ? { retryReason } : {},
+          ...toolDefs.length > 0 ? { toolNames: toolDefs.map((t) => t.function.name) } : {},
+          ...messagesSnapshot ? { messages: messagesSnapshot } : {}
+        }
+      });
+      this.onAgentStart?.({ agent: agent2._name, model: modelUri }, callbackMeta);
+      let response;
+      try {
+        if (this.onToken) {
+          let content2 = "";
+          const toolCalls = [];
+          const toolCallBuffers = /* @__PURE__ */ new Map();
+          let streamProviderMetadata;
+          let thinkingContent = "";
+          const partialObjectEnabled = !!options?.schema && toolDefs.length === 0 && options.schema instanceof z.ZodObject;
+          const currentAttempt = schemaRetries + 1;
+          let inString = false;
+          let escaped = false;
+          let boundaryPending = false;
+          for await (const chunk of provider.stream(currentMessages, chatOptions)) {
+            if (chunk.type === "text_delta") {
+              content2 += chunk.content;
+              this.emitEvent({ type: "token", data: chunk.content });
+              this.onToken(chunk.content, callbackMeta);
+              if (partialObjectEnabled) {
+                for (const ch of chunk.content) {
+                  if (escaped) {
+                    escaped = false;
+                    continue;
+                  }
+                  if (ch === "\\") {
+                    escaped = true;
+                    continue;
+                  }
+                  if (ch === '"') {
+                    inString = !inString;
+                    continue;
+                  }
+                  if (!inString && (ch === "," || ch === "}" || ch === "]")) {
+                    boundaryPending = true;
+                  }
+                }
+                if (boundaryPending) {
+                  boundaryPending = false;
+                  let parsed;
+                  try {
+                    parsed = parsePartialJson(extractJson(content2));
+                  } catch {
+                    parsed = void 0;
+                  }
+                  if (parsed !== void 0) {
+                    this.emitEvent({
+                      type: "partial_object",
+                      agent: agent2._name,
+                      attempt: currentAttempt,
+                      data: { object: parsed }
+                    });
+                  }
+                }
+              }
+            } else if (chunk.type === "thinking_delta") {
+              thinkingContent += chunk.content;
+            } else if (chunk.type === "tool_call_delta") {
+              let buffer = toolCallBuffers.get(chunk.id);
+              if (!buffer) {
+                buffer = { id: chunk.id, name: "", arguments: "" };
+                toolCallBuffers.set(chunk.id, buffer);
+              }
+              if (chunk.name) buffer.name = chunk.name;
+              if (chunk.arguments) buffer.arguments += chunk.arguments;
+            } else if (chunk.type === "done") {
+              streamProviderMetadata = chunk.providerMetadata;
+              if (chunk.usage) {
+                response = {
+                  content: content2,
+                  tool_calls: void 0,
+                  usage: chunk.usage,
+                  cost: chunk.cost
+                };
+              }
+            }
+          }
+          for (const buffer of toolCallBuffers.values()) {
+            toolCalls.push({
+              id: buffer.id,
+              type: "function",
+              function: {
+                name: buffer.name,
+                arguments: buffer.arguments
+              }
+            });
+          }
+          response ??= {
+            content: content2,
+            usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
+          };
+          if (toolCalls.length > 0) {
+            response.tool_calls = toolCalls;
+          }
+          if (streamProviderMetadata) {
+            response.providerMetadata = streamProviderMetadata;
+          }
+          if (thinkingContent) {
+            response.thinking_content = thinkingContent;
+          }
+        } else {
+          response = await provider.chat(currentMessages, chatOptions);
+        }
+      } catch (err) {
+        this.emitEvent({
+          type: "agent_call_end",
+          agent: agent2._name,
+          model: modelUri,
+          promptVersion: agent2._config.version,
+          duration: Date.now() - turnStart,
+          data: {
+            response: "",
+            turn: turns,
+            ...retryReason ? { retryReason } : {},
+            error: err instanceof Error ? err.message : String(err)
+          }
+        });
+        throw err;
+      }
+      if (usageCapture && response.usage) {
+        usageCapture.value = response.usage;
+      }
+      if (response.cost) {
+        this._accumulateBudgetCost(response.cost);
+      }
+      this.emitEvent({
+        type: "agent_call_end",
         agent: agent2._name,
         model: modelUri,
         promptVersion: agent2._config.version,
@@ -2626,22 +3316,10 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         } : void 0,
         duration: Date.now() - turnStart,
         data: {
-          prompt,
           response: response.content,
-          ...systemPrompt ? { system: systemPrompt } : {},
           ...response.thinking_content ? { thinking: response.thinking_content } : {},
-          params: {
-            ...chatOptions.temperature !== void 0 ? { temperature: chatOptions.temperature } : {},
-            maxTokens: chatOptions.maxTokens,
-            ...chatOptions.effort !== void 0 ? { effort: chatOptions.effort } : {},
-            ...chatOptions.thinkingBudget !== void 0 ? { thinkingBudget: chatOptions.thinkingBudget } : {},
-            ...chatOptions.includeThoughts !== void 0 ? { includeThoughts: chatOptions.includeThoughts } : {},
-            ...chatOptions.toolChoice !== void 0 ? { toolChoice: chatOptions.toolChoice } : {},
-            ...chatOptions.stop !== void 0 ? { stop: chatOptions.stop } : {}
-          },
           turn: turns,
-          ...retryReason ? { retryReason } : {},
-          ...messagesSnapshot ? { messages: messagesSnapshot } : {}
+          ...retryReason ? { retryReason } : {}
         }
       });
       if (response.tool_calls && response.tool_calls.length > 0) {
@@ -2667,6 +3345,19 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                 }
               }
               const handoffStart = Date.now();
+              const sourceFrame = askStorage.getStore();
+              const handoffFromAskId = sourceFrame?.askId ?? this.executionId;
+              const handoffSourceDepth = sourceFrame?.depth ?? 0;
+              const handoffToAskId = randomUUID();
+              const handoffTargetDepth = handoffSourceDepth + 1;
+              const targetFrame = {
+                askId: handoffToAskId,
+                parentAskId: handoffFromAskId,
+                depth: handoffTargetDepth,
+                agent: descriptor.agent._name,
+                stepRef: sourceFrame?.stepRef ?? this.stepRefRoot,
+                askCost: { value: 0 }
+              };
               const handoffOptions = options ? {
                 schema: options.schema,
                 retries: options.retries,
@@ -2674,13 +3365,51 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                 validate: options.validate,
                 validateRetries: options.validateRetries
               } : void 0;
-              const handoffFn = () => this.executeAgentCall(
-                descriptor.agent,
-                handoffPrompt,
-                handoffOptions,
-                currentMessages,
-                usageCapture
-              );
+              const handoffFn = () => askStorage.run(targetFrame, async () => {
+                this.emitEvent({ type: "ask_start", prompt: handoffPrompt });
+                const targetAskStart = Date.now();
+                try {
+                  const result = await this.executeAgentCall(
+                    descriptor.agent,
+                    handoffPrompt,
+                    handoffOptions,
+                    currentMessages,
+                    usageCapture
+                  );
+                  this.emitEvent({
+                    type: "ask_end",
+                    outcome: { ok: true, result },
+                    cost: targetFrame.askCost.value,
+                    duration: Date.now() - targetAskStart
+                  });
+                  return result;
+                } catch (err) {
+                  this.emitEvent({
+                    type: "ask_end",
+                    outcome: {
+                      ok: false,
+                      error: err instanceof Error ? err.message : String(err)
+                    },
+                    cost: targetFrame.askCost.value,
+                    duration: Date.now() - targetAskStart
+                  });
+                  throw err;
+                }
+              });
+              this.emitEvent({
+                type: "handoff_start",
+                agent: agent2._name,
+                fromAskId: handoffFromAskId,
+                toAskId: handoffToAskId,
+                sourceDepth: handoffSourceDepth,
+                targetDepth: handoffTargetDepth,
+                data: {
+                  source: agent2._name,
+                  target: targetName,
+                  mode,
+                  ...mode === "roundtrip" && handoffPrompt !== prompt ? { message: handoffPrompt } : {}
+                }
+              });
               if (mode === "roundtrip") {
                 const executeRoundtrip = async () => {
                   const result = await handoffFn();
@@ -2701,36 +3430,41 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                       "axl.handoff.mode": mode
                     },
                     async (span) => {
-                      const result = await executeRoundtrip();
-                      const duration = Date.now() - handoffStart;
-                      span.setAttribute("axl.handoff.duration", duration);
-                      this.emitTrace({
-                        type: "handoff",
-                        agent: agent2._name,
-                        data: {
-                          target: targetName,
-                          mode,
-                          duration,
-                          source: agent2._name,
-                          ...handoffPrompt !== prompt ? { message: handoffPrompt } : {}
-                        }
-                      });
-                      return result;
+                      try {
+                        return await executeRoundtrip();
+                      } finally {
+                        const duration = Date.now() - handoffStart;
+                        span.setAttribute("axl.handoff.duration", duration);
+                        this.emitEvent({
+                          type: "handoff_return",
+                          agent: agent2._name,
+                          fromAskId: handoffFromAskId,
+                          toAskId: handoffToAskId,
+                          sourceDepth: handoffSourceDepth,
+                          targetDepth: handoffTargetDepth,
+                          data: { source: agent2._name, target: targetName, duration }
+                        });
+                      }
                     }
                   );
                 } else {
-                  await executeRoundtrip();
-                  this.emitTrace({
-                    type: "handoff",
-                    agent: agent2._name,
-                    data: {
-                      target: targetName,
-                      mode,
-                      duration: Date.now() - handoffStart,
-                      source: agent2._name,
-                      ...handoffPrompt !== prompt ? { message: handoffPrompt } : {}
-                    }
-                  });
+                  try {
+                    await executeRoundtrip();
+                  } finally {
+                    this.emitEvent({
+                      type: "handoff_return",
+                      agent: agent2._name,
+                      fromAskId: handoffFromAskId,
+                      toAskId: handoffToAskId,
+                      sourceDepth: handoffSourceDepth,
+                      targetDepth: handoffTargetDepth,
+                      data: {
+                        source: agent2._name,
+                        target: targetName,
+                        duration: Date.now() - handoffStart
+                      }
+                    });
+                  }
                 }
                 continue;
               }
@@ -2744,29 +3478,12 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                   },
                   async (span) => {
                     const result = await handoffFn();
-                    const duration = Date.now() - handoffStart;
-                    span.setAttribute("axl.handoff.duration", duration);
-                    this.emitTrace({
-                      type: "handoff",
-                      agent: agent2._name,
-                      data: { target: targetName, mode, duration, source: agent2._name }
-                    });
+                    span.setAttribute("axl.handoff.duration", Date.now() - handoffStart);
                     return result;
                   }
                 );
               }
-              const onewayResult = await handoffFn();
-              this.emitTrace({
-                type: "handoff",
-                agent: agent2._name,
-                data: {
-                  target: targetName,
-                  mode,
-                  duration: Date.now() - handoffStart,
-                  source: agent2._name
-                }
-              });
-              return onewayResult;
+              return await handoffFn();
             }
           }
           const toolOverride = this.toolOverrides?.get(toolName);
@@ -2782,7 +3499,16 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
               });
               continue;
             }
-            this.onToolCall?.({ name: toolName, args: toolArgs2, callId: toolCall.id });
+            this.emitEvent({
+              type: "tool_call_start",
+              tool: toolName,
+              callId: toolCall.id,
+              data: { args: toolArgs2 }
+            });
+            this.onToolCall?.(
+              { name: toolName, args: toolArgs2, callId: toolCall.id },
+              callbackMeta
+            );
             const toolStart2 = Date.now();
             const executeOverride = async () => {
               let toolResult3;
@@ -2810,8 +3536,8 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
               }
             ) : await executeOverride();
             const resultContent2 = JSON.stringify(toolResult2);
-            this.emitTrace({
-              type: "tool_call",
+            this.emitEvent({
+              type: "tool_call_end",
               agent: agent2._name,
               tool: toolName,
               duration: Date.now() - toolStart2,
@@ -2827,7 +3553,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
           const tool2 = agent2._config.tools?.find((t) => t.name === toolName);
           const isMcpTool = !tool2 && this.mcpManager?.isMcpTool(toolName);
           if (!tool2 && !isMcpTool) {
-            this.emitTrace({ type: "tool_denied", agent: agent2._name, tool: toolName });
+            this.emitEvent({ type: "tool_denied", agent: agent2._name, tool: toolName });
             currentMessages.push({
               role: "tool",
               content: `Tool "${toolName}" is not available. Available tools: ${agent2._config.tools?.map((t) => t.name).join(", ") ?? "none"}`,
@@ -2846,7 +3572,13 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
             });
             continue;
           }
-          this.onToolCall?.({ name: toolName, args: toolArgs, callId: toolCall.id });
+          this.emitEvent({
+            type: "tool_call_start",
+            tool: toolName,
+            callId: toolCall.id,
+            data: { args: toolArgs }
+          });
+          this.onToolCall?.({ name: toolName, args: toolArgs, callId: toolCall.id }, callbackMeta);
           const toolStart = Date.now();
           if (tool2 && tool2.requireApproval) {
             const approvalFn = async () => {
@@ -2883,7 +3615,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
             } else {
               approvalOutcome = await approvalFn();
             }
-            this.emitTrace({
+            this.emitEvent({
               type: "tool_approval",
               agent: agent2._name,
               tool: toolName,
@@ -2926,7 +3658,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                 resultContent2 = JSON.stringify(toolResult2);
               }
             } else if (tool2) {
-              const childCtx = this.createChildContext(toolCall.id);
+              const childCtx = this.createChildContext();
               try {
                 toolResult2 = await tool2._execute(toolArgs, childCtx);
               } catch (err) {
@@ -2968,8 +3700,8 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
               return r;
             }
           ) : await executeTool();
-          this.emitTrace({
-            type: "tool_call",
+          this.emitEvent({
+            type: "tool_call_end",
             agent: agent2._name,
             tool: traceName,
             duration: Date.now() - toolStart,
@@ -2993,7 +3725,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         if (outputResult.block && onBlock === "retry" && guardrailOutputRetries < maxGuardrailRetries) {
           feedbackMessage = `Your previous response was blocked by a safety guardrail: ${outputResult.reason ?? "Output blocked"}. Please provide a different response that complies with the guidelines.`;
         }
-        this.emitTrace({
+        this.emitEvent({
           type: "guardrail",
           agent: agent2._name,
           data: {
@@ -3014,6 +3746,15 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         });
         if (outputResult.block) {
           if (feedbackMessage) {
+            this.emitEvent({
+              type: "pipeline",
+              agent: agent2._name,
+              status: "failed",
+              stage: "guardrail",
+              attempt: guardrailOutputRetries + 1,
+              maxAttempts: maxGuardrailRetries + 1,
+              reason: feedbackMessage
+            });
             guardrailOutputRetries++;
             appendRetryMessages(
               currentMessages,
@@ -3052,7 +3793,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
             schemaFeedback = `Your response was not valid JSON or did not match the required schema: ${schemaReason}. Please fix and try again.`;
           }
         }
-        this.emitTrace({
+        this.emitEvent({
           type: "schema_check",
           agent: agent2._name,
           data: {
@@ -3071,6 +3812,15 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         });
         if (!schemaValid) {
           if (schemaFeedback) {
+            this.emitEvent({
+              type: "pipeline",
+              agent: agent2._name,
+              status: "failed",
+              stage: "schema",
+              attempt: schemaRetries + 1,
+              maxAttempts: (options.retries ?? 3) + 1,
+              reason: schemaFeedback
+            });
             schemaRetries++;
             appendRetryMessages(
               currentMessages,
@@ -3108,7 +3858,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         if (!validateResult.valid && validateRetries < maxValidateRetries) {
           validateFeedback = `Your response parsed correctly but failed validation: ${validateResult.reason ?? "Validation failed"}. Previous attempts are visible above. Please fix and try again.`;
         }
-        this.emitTrace({
+        this.emitEvent({
           type: "validate",
           agent: agent2._name,
           data: {
@@ -3127,6 +3877,15 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         });
         if (!validateResult.valid) {
           if (validateFeedback) {
+            this.emitEvent({
+              type: "pipeline",
+              agent: agent2._name,
+              status: "failed",
+              stage: "validate",
+              attempt: validateRetries + 1,
+              maxAttempts: (options.validateRetries ?? 2) + 1,
+              reason: validateFeedback
+            });
             validateRetries++;
             appendRetryMessages(
               currentMessages,
@@ -3144,6 +3903,14 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
           );
         }
       }
+      this.emitEvent({
+        type: "pipeline",
+        agent: agent2._name,
+        status: "committed",
+        stage: lastStartStage,
+        attempt: lastStartAttempt,
+        maxAttempts: lastStartMaxAttempts
+      });
       this.pushAssistantToSessionHistory(content, response.providerMetadata);
       return validated ?? content;
     }
@@ -3272,43 +4039,100 @@ ${summaryResponse.content}`
   /**
    * 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.
    */
-  async checkpoint(fn) {
-    return this._checkpoint(fn);
+  async checkpoint(name, fn) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new Error("ctx.checkpoint name must be a non-empty string.");
+    }
+    if (name !== name.trim()) {
+      throw new Error(
+        `ctx.checkpoint name "${name}" has leading/trailing whitespace \u2014 trim before passing.`
+      );
+    }
+    if (name.toLowerCase().startsWith("__auto/")) {
+      throw new Error(
+        `ctx.checkpoint name "${name}" is reserved \u2014 names starting with "__auto/" (case-insensitive) are used by the runtime for ask/spawn/race/parallel/map auto-checkpointing.`
+      );
+    }
+    return this._checkpoint(name, fn);
   }
   /**
-   * 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.
    */
-  async _checkpoint(fn) {
-    const step = this.checkpointCounter++;
+  async _checkpoint(name, fn, options) {
     if (!this.stateStore) {
       return fn();
     }
-    const saved = await this.stateStore.getCheckpoint(this.executionId, step);
+    const agentStamp = options?.agent ? { agent: options.agent } : {};
+    const saved = await this.stateStore.getCheckpoint(this.executionId, name);
     if (saved !== null) {
-      this.emitTrace({
-        type: "log",
-        data: { event: "checkpoint_replay", step }
+      this.emitEvent({
+        type: "checkpoint_replay",
+        ...agentStamp,
+        data: { name }
       });
-      this.spanManager?.addEventToActiveSpan("axl.checkpoint.hit", { "axl.checkpoint.step": step });
+      this.spanManager?.addEventToActiveSpan("axl.checkpoint.hit", { "axl.checkpoint.name": name });
       return saved;
     }
     const result = await fn();
-    await this.stateStore.saveCheckpoint(this.executionId, step, result);
-    this.emitTrace({
-      type: "log",
-      data: { event: "checkpoint_save", step }
+    await this.stateStore.saveCheckpoint(this.executionId, name, result);
+    this.emitEvent({
+      type: "checkpoint_save",
+      ...agentStamp,
+      data: { name }
     });
-    this.spanManager?.addEventToActiveSpan("axl.checkpoint.miss", { "axl.checkpoint.step": step });
+    this.spanManager?.addEventToActiveSpan("axl.checkpoint.miss", { "axl.checkpoint.name": name });
     return result;
   }
+  /** 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. */
+  _autoCheckpointName(primitive, agent2) {
+    const counters = this.autoCheckpointCounters;
+    if (primitive === "ask" && agent2) {
+      const n2 = counters.byAgent.get(agent2) ?? 0;
+      counters.byAgent.set(agent2, n2 + 1);
+      return `__auto/${agent2}/ask/${n2}`;
+    }
+    const n = counters.root++;
+    return `__auto/${primitive}/${n}`;
+  }
   // ── ctx.spawn() ───────────────────────────────────────────────────────
   async spawn(n, fn, options) {
-    return this._checkpoint(() => {
+    return this._checkpoint(this._autoCheckpointName("spawn"), () => {
       if (this.spanManager) {
         return this.spanManager.withSpanAsync(
           "axl.ctx.spawn",
@@ -3504,7 +4328,7 @@ ${summaryResponse.content}`
     const maxRetries = options?.retries ?? 3;
     let lastRetry = void 0;
     const emitVerifyOutcome = (passed, attempts, lastError) => {
-      this.emitTrace({
+      this.emitEvent({
         type: "verify",
         agent: void 0,
         data: {
@@ -3644,7 +4468,7 @@ ${summaryResponse.content}`
   }
   // ── ctx.race() ────────────────────────────────────────────────────────
   async race(fns, options) {
-    return this._checkpoint(() => {
+    return this._checkpoint(this._autoCheckpointName("race"), () => {
       if (this.spanManager) {
         return this.spanManager.withSpanAsync(
           "axl.ctx.race",
@@ -3749,11 +4573,17 @@ ${summaryResponse.content}`
   }
   // ── ctx.parallel() ────────────────────────────────────────────────────
   async parallel(fns) {
-    return this._checkpoint(() => Promise.all(fns.map((fn) => fn())));
+    return this._checkpoint(
+      this._autoCheckpointName("parallel"),
+      () => Promise.all(fns.map((fn) => fn()))
+    );
   }
   // ── ctx.map() ─────────────────────────────────────────────────────────
   async map(items, fn, options) {
-    return this._checkpoint(() => this._mapImpl(items, fn, options));
+    return this._checkpoint(
+      this._autoCheckpointName("map"),
+      () => this._mapImpl(items, fn, options)
+    );
   }
   async _mapImpl(items, fn, options) {
     const concurrency = options?.concurrency ?? 5;
@@ -3831,10 +4661,14 @@ ${summaryResponse.content}`
   }
   async _awaitHumanImpl(options) {
     if (this.awaitHumanHandler) {
+      this.emitEvent({
+        type: "await_human",
+        data: { channel: options.channel, prompt: options.prompt }
+      });
       const decision2 = await this.awaitHumanHandler(options);
-      this.emitTrace({
-        type: "log",
-        data: { event: "await_human_resolved", channel: options.channel, decision: decision2 }
+      this.emitEvent({
+        type: "await_human_resolved",
+        data: { channel: options.channel, decision: decision2 }
       });
       return decision2;
     }
@@ -3854,7 +4688,7 @@ ${summaryResponse.content}`
       await this.stateStore.saveExecutionState(this.executionId, {
         workflow: this.workflowName ?? "unknown",
         input: this.input,
-        step: this.stepCounter,
+        step: this.stepRefRoot.value,
         status: "waiting",
         metadata: {
           ...this.metadata,
@@ -3863,18 +4697,22 @@ ${summaryResponse.content}`
         }
       });
     }
-    this.emitTrace({
-      type: "log",
-      data: { event: "await_human", channel: options.channel, prompt: options.prompt }
+    this.emitEvent({
+      type: "await_human",
+      data: { channel: options.channel, prompt: options.prompt }
     });
     const decision = await new Promise((resolve) => {
       this.pendingDecisions.set(this.executionId, resolve);
     });
+    this.emitEvent({
+      type: "await_human_resolved",
+      data: { channel: options.channel, decision }
+    });
     if (this.stateStore) {
       await this.stateStore.saveExecutionState(this.executionId, {
         workflow: this.workflowName ?? "unknown",
         input: this.input,
-        step: this.stepCounter,
+        step: this.stepRefRoot.value,
         status: "running"
       });
     }
@@ -3927,17 +4765,28 @@ ${summaryResponse.content}`
   // the previous `ctx.log('workflow_start', ...)` indirection — so consumers
   // that narrow via `event.type === 'workflow_start'` actually see them.
   // Internal: the runtime is the only caller, user workflows never call these.
-  /** @internal */
+  /** @internal — idempotent; no-ops on second+ call within one ctx. */
   _emitWorkflowStart(input) {
-    this.emitTrace({
+    if (this._workflowStartEmitted) return;
+    this._workflowStartEmitted = true;
+    this.emitEvent({
       type: "workflow_start",
       workflow: this.workflowName,
       data: { input }
     });
   }
-  /** @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) {
-    this.emitTrace({
+    if (this._workflowEndEmitted) return;
+    this._workflowEndEmitted = true;
+    this.emitEvent({
       type: "workflow_end",
       workflow: this.workflowName,
       duration: info.duration,
@@ -3952,7 +4801,7 @@ ${summaryResponse.content}`
   }
   // ── ctx.log() ─────────────────────────────────────────────────────────
   log(event, data) {
-    this.emitTrace({
+    this.emitEvent({
       type: "log",
       data: {
         event,
@@ -4006,12 +4855,11 @@ ${summaryResponse.content}`
       if (usage?.cost != null) {
         this._accumulateBudgetCost(usage.cost);
       }
-      this.emitTrace({
-        type: "log",
+      this.emitEvent({
+        type: "memory_remember",
         ...usage?.cost != null ? { cost: usage.cost } : {},
         ...usage?.tokens != null ? { tokens: { input: usage.tokens } } : {},
         data: {
-          event: "memory_remember",
           key,
           scope,
           embed: options?.embed === true,
@@ -4023,12 +4871,11 @@ ${summaryResponse.content}`
       if (partialUsage?.cost != null) {
         this._accumulateBudgetCost(partialUsage.cost);
       }
-      this.emitTrace({
-        type: "log",
+      this.emitEvent({
+        type: "memory_remember",
         ...partialUsage?.cost != null ? { cost: partialUsage.cost } : {},
         ...partialUsage?.tokens != null ? { tokens: { input: partialUsage.tokens } } : {},
         data: {
-          event: "memory_remember",
           key,
           scope,
           embed: options?.embed === true,
@@ -4080,26 +4927,24 @@ ${summaryResponse.content}`
       if (usage?.cost != null) {
         this._accumulateBudgetCost(usage.cost);
       }
-      this.emitTrace({
-        type: "log",
+      this.emitEvent({
+        type: "memory_recall",
         ...usage?.cost != null ? { cost: usage.cost } : {},
         ...usage?.tokens != null ? { tokens: { input: usage.tokens } } : {},
         data: {
-          event: "memory_recall",
           key,
           scope,
           semantic,
           hit,
-          ...resultCount !== void 0 ? { resultCount } : {},
+          ...resultCount !== void 0 ? { resultCount, count: resultCount } : {},
           ...usage ? { usage } : {}
         }
       });
       return data;
     } catch (err) {
-      this.emitTrace({
-        type: "log",
+      this.emitEvent({
+        type: "memory_recall",
         data: {
-          event: "memory_recall",
           key,
           scope,
           semantic,
@@ -4124,15 +4969,14 @@ ${summaryResponse.content}`
     const scope = options?.scope ?? (sessionId ? "session" : "global");
     try {
       await this.memoryManager.forget(key, this.stateStore, sessionId, options);
-      this.emitTrace({
-        type: "log",
-        data: { event: "memory_forget", key, scope }
+      this.emitEvent({
+        type: "memory_forget",
+        data: { key, scope }
       });
     } catch (err) {
-      this.emitTrace({
-        type: "log",
+      this.emitEvent({
+        type: "memory_forget",
         data: {
-          event: "memory_forget",
           key,
           scope,
           error: err instanceof Error ? err.message : String(err)
@@ -4167,7 +5011,7 @@ ${summaryResponse.content}`
       names.add(a._name);
     }
     if (agents.length === 1) {
-      this.emitTrace({
+      this.emitEvent({
         type: "delegate",
         agent: agents[0]._name,
         data: {
@@ -4211,7 +5055,7 @@ ${summaryResponse.content}`
       resolveModel: () => routerModelUri,
       resolveSystem: () => routerSystem
     };
-    this.emitTrace({
+    this.emitEvent({
       type: "delegate",
       agent: "_delegate_router",
       data: {
@@ -4232,107 +5076,42 @@ ${summaryResponse.content}`
   /**
    * 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.
    */
-  emitTrace(partial) {
-    let data = partial.data;
-    if (this.config.trace?.redact && data) {
-      if (partial.type === "agent_call") {
-        const d = data;
-        const redacted = {
-          ...d,
-          prompt: "[redacted]",
-          response: "[redacted]"
-        };
-        if (d.system !== void 0) redacted.system = "[redacted]";
-        if (d.thinking !== void 0) redacted.thinking = "[redacted]";
-        if (Array.isArray(d.messages)) {
-          redacted.messages = [
-            { role: "system", content: `[${d.messages.length} messages redacted]` }
-          ];
-        }
-        data = redacted;
-      } else if (partial.type === "guardrail" || partial.type === "schema_check" || partial.type === "validate") {
-        const d = data;
-        const needsRedact = d.feedbackMessage !== void 0 || d.reason !== void 0;
-        if (needsRedact) {
-          data = {
-            ...d,
-            ...d.reason !== void 0 ? { reason: "[redacted]" } : {},
-            ...d.feedbackMessage !== void 0 ? { feedbackMessage: "[redacted]" } : {}
-          };
-        }
-      } else if (partial.type === "tool_call") {
-        const d = data;
-        data = {
-          ...d,
-          args: "[redacted]",
-          result: "[redacted]"
-        };
-      } else if (partial.type === "tool_approval") {
-        const d = data;
-        data = {
-          ...d,
-          args: "[redacted]",
-          ...d.reason !== void 0 ? { reason: "[redacted]" } : {}
-        };
-      } else if (partial.type === "handoff") {
-        const d = data;
-        if (d.message !== void 0) {
-          data = { ...d, message: "[redacted]" };
-        }
-      } else if (partial.type === "workflow_start") {
-        const d = data;
-        if (d.input !== void 0) {
-          data = { ...d, input: "[redacted]" };
-        }
-      } else if (partial.type === "workflow_end") {
-        const d = data;
-        const redacted = { ...d };
-        if (d.result !== void 0) redacted.result = "[redacted]";
-        if (d.error !== void 0) redacted.error = "[redacted]";
-        data = redacted;
-      } else if (partial.type === "log") {
-        const d = data;
-        const redacted = {};
-        for (const [k, v] of Object.entries(d)) {
-          if (k === "event" || typeof v === "number" || typeof v === "boolean") {
-            redacted[k] = v;
-          } else if (typeof v === "string") {
-            redacted[k] = "[redacted]";
-          } else if (v !== null && typeof v === "object" && !Array.isArray(v)) {
-            const inner = v;
-            const innerRedacted = {};
-            for (const [ik, iv] of Object.entries(inner)) {
-              if (typeof iv === "number" || typeof iv === "boolean") {
-                innerRedacted[ik] = iv;
-              } else if (typeof iv === "string") {
-                innerRedacted[ik] = "[redacted]";
-              } else {
-                innerRedacted[ik] = "[redacted]";
-              }
-            }
-            redacted[k] = innerRedacted;
-          } else {
-            redacted[k] = "[redacted]";
-          }
-        }
-        data = redacted;
-      }
+  emitEvent(partial) {
+    const data = partial.data;
+    const frame = askStorage.getStore();
+    const step = (frame?.stepRef ?? this.stepRefRoot).value++;
+    const cost = partial.cost;
+    if (frame && typeof cost === "number" && Number.isFinite(cost) && cost >= 0 && COST_BEARING_LEAF_TYPES.includes(partial.type)) {
+      frame.askCost.value += cost;
     }
     const event = {
       executionId: this.executionId,
-      step: this.stepCounter++,
+      step,
       timestamp: Date.now(),
       ...this.workflowName ? { workflow: this.workflowName } : {},
-      ...this.parentToolCallId ? { parentToolCallId: this.parentToolCallId } : {},
+      // Stamp ask correlation from ALS. Variants like `workflow_start` /
+      // `workflow_end` and out-of-ask events (log/memory/checkpoint/await_human
+      // when emitted at workflow scope) may legitimately have no frame —
+      // they still get `depth: 0` so consumers can render them at root
+      // level without having to guess. `askId`/`parentAskId`/`agent` stay
+      // unset for non-ask-scoped events, matching the `Partial<AskScoped>`
+      // shape on those union members.
+      ...frame ? {
+        askId: frame.askId,
+        ...frame.parentAskId ? { parentAskId: frame.parentAskId } : {},
+        depth: frame.depth,
+        ...frame.agent ? { agent: frame.agent } : {}
+      } : { depth: 0 },
       ...partial,
       data
     };
+    const finalEvent = this.config.trace?.redact ? redactEvent(event) : event;
     if (this.onTrace) {
       try {
-        this.onTrace(event);
+        this.onTrace(finalEvent);
       } catch (err) {
         console.error(
           "[axl] onTrace handler threw; trace event dropped:",
@@ -4344,7 +5123,7 @@ ${summaryResponse.content}`
 };
 
 // src/agent.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 var agentCounter = 0;
 function agent(config) {
   agentCounter++;
@@ -4364,7 +5143,7 @@ function agent(config) {
       const registry = new ProviderRegistry();
       const ctx = new WorkflowContext({
         input: prompt,
-        executionId: randomUUID(),
+        executionId: randomUUID2(),
         config: {},
         providerRegistry: registry
       });
@@ -4388,7 +5167,7 @@ function workflow(config) {
 
 // src/runtime.ts
 import { EventEmitter as EventEmitter2 } from "events";
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
 import { appendFileSync, mkdirSync as mkdirSync2 } from "fs";
 import { dirname } from "path";
@@ -4411,29 +5190,20 @@ var MemoryStore = class {
   constructor() {
     this.loadPersistedState();
   }
-  async saveCheckpoint(executionId, step, data) {
-    let steps = this.checkpoints.get(executionId);
-    if (!steps) {
-      steps = /* @__PURE__ */ new Map();
-      this.checkpoints.set(executionId, steps);
+  async saveCheckpoint(executionId, name, data) {
+    let entries = this.checkpoints.get(executionId);
+    if (!entries) {
+      entries = /* @__PURE__ */ new Map();
+      this.checkpoints.set(executionId, entries);
     }
-    steps.set(step, structuredClone(data));
+    entries.set(name, structuredClone(data));
   }
-  async getCheckpoint(executionId, step) {
-    const steps = this.checkpoints.get(executionId);
-    if (!steps) return null;
-    const data = steps.get(step);
+  async getCheckpoint(executionId, name) {
+    const entries = this.checkpoints.get(executionId);
+    if (!entries) return null;
+    const data = entries.get(name);
     return data !== void 0 ? structuredClone(data) : null;
   }
-  async getLatestCheckpoint(executionId) {
-    const steps = this.checkpoints.get(executionId);
-    if (!steps || steps.size === 0) return null;
-    let maxStep = -1;
-    for (const step of steps.keys()) {
-      if (step > maxStep) maxStep = step;
-    }
-    return { step: maxStep, data: structuredClone(steps.get(maxStep)) };
-  }
   async saveSession(sessionId, history) {
     this.sessions.set(sessionId, structuredClone(history));
   }
@@ -4606,7 +5376,7 @@ function rowToExecutionInfo(row) {
     completedAt: row.completed_at ?? void 0,
     duration: row.duration,
     error: row.error ?? void 0,
-    steps: safeJsonParse(row.steps) ?? []
+    events: safeJsonParse(row.events) ?? []
   };
 }
 var SQLiteStore = class {
@@ -4622,15 +5392,80 @@ var SQLiteStore = class {
     }
     this.db = new BetterSqlite3(filePath);
     this.db.pragma("journal_mode = WAL");
+    this.migrate();
     this.initTables();
   }
+  /**
+   * 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.
+   */
+  migrate() {
+    const TARGET_VERSION = 2;
+    const current = this.db.pragma("user_version", { simple: true });
+    if (current >= TARGET_VERSION) return;
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const committed = this.db.pragma("user_version", { simple: true });
+      if (committed >= TARGET_VERSION) {
+        this.db.exec("COMMIT");
+        return;
+      }
+      if (committed < 1) {
+        const cols = this.db.pragma("table_info(execution_history)");
+        if (cols.some((c) => c.name === "steps") && !cols.some((c) => c.name === "events")) {
+          this.db.exec("ALTER TABLE execution_history RENAME COLUMN steps TO events");
+        }
+      }
+      if (committed < 2) {
+        const cols = this.db.pragma("table_info(checkpoints)");
+        if (cols.some((c) => c.name === "step") && !cols.some((c) => c.name === "name")) {
+          this.db.exec("ALTER TABLE checkpoints RENAME COLUMN step TO name");
+        }
+      }
+      this.db.pragma(`user_version = ${TARGET_VERSION}`);
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
   initTables() {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS checkpoints (
         execution_id TEXT NOT NULL,
-        step INTEGER NOT NULL,
+        name TEXT NOT NULL,
         data TEXT NOT NULL,
-        PRIMARY KEY (execution_id, step)
+        PRIMARY KEY (execution_id, name)
       );
 
       CREATE TABLE IF NOT EXISTS sessions (
@@ -4679,7 +5514,7 @@ var SQLiteStore = class {
         completed_at INTEGER,
         duration INTEGER NOT NULL DEFAULT 0,
         error TEXT,
-        steps TEXT NOT NULL
+        events TEXT NOT NULL
       );
 
       CREATE TABLE IF NOT EXISTS eval_history (
@@ -4694,26 +5529,19 @@ var SQLiteStore = class {
     `);
   }
   // ── Checkpoints ────────────────────────────────────────────────────────
-  async saveCheckpoint(executionId, step, data) {
+  async saveCheckpoint(executionId, name, data) {
     const stmt = this.db.prepare(
-      "INSERT OR REPLACE INTO checkpoints (execution_id, step, data) VALUES (?, ?, ?)"
+      "INSERT OR REPLACE INTO checkpoints (execution_id, name, data) VALUES (?, ?, ?)"
     );
-    stmt.run(executionId, step, JSON.stringify(data));
+    stmt.run(executionId, name, JSON.stringify(data));
   }
-  async getCheckpoint(executionId, step) {
+  async getCheckpoint(executionId, name) {
     const stmt = this.db.prepare(
-      "SELECT data FROM checkpoints WHERE execution_id = ? AND step = ?"
+      "SELECT data FROM checkpoints WHERE execution_id = ? AND name = ?"
     );
-    const row = stmt.get(executionId, step);
+    const row = stmt.get(executionId, name);
     return row ? safeJsonParse(row.data) : null;
   }
-  async getLatestCheckpoint(executionId) {
-    const stmt = this.db.prepare(
-      "SELECT step, data FROM checkpoints WHERE execution_id = ? ORDER BY step DESC LIMIT 1"
-    );
-    const row = stmt.get(executionId);
-    return row ? { step: row.step, data: safeJsonParse(row.data) } : null;
-  }
   // ── Sessions ────────────────────────────────────────────────────────────
   async saveSession(sessionId, history) {
     const stmt = this.db.prepare(
@@ -4807,7 +5635,7 @@ var SQLiteStore = class {
   // ── Execution History ────────────────────────────────────────────────────
   async saveExecution(execution) {
     this.db.prepare(
-      "INSERT OR REPLACE INTO execution_history (execution_id, workflow, status, total_cost, started_at, completed_at, duration, error, steps) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+      "INSERT OR REPLACE INTO execution_history (execution_id, workflow, status, total_cost, started_at, completed_at, duration, error, events) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
     ).run(
       execution.executionId,
       execution.workflow,
@@ -4817,7 +5645,7 @@ var SQLiteStore = class {
       execution.completedAt ?? null,
       execution.duration,
       execution.error ?? null,
-      JSON.stringify(execution.steps)
+      JSON.stringify(execution.events)
     );
   }
   async getExecution(executionId) {
@@ -4991,7 +5819,8 @@ var Session = class _Session {
       }
     };
     axlStream.on("done", (event) => {
-      updateHistory(event.data).catch((err) => {
+      const data = event.data;
+      updateHistory(data.result).catch((err) => {
         this.runtime.emit("error", {
           type: "session_history_save_failed",
           sessionId: this.sessionId,
@@ -5033,9 +5862,88 @@ var Session = class _Session {
 // src/stream.ts
 import { Readable } from "stream";
 import { EventEmitter } from "events";
+
+// src/types.ts
+var AXL_EVENT_TYPES = [
+  // Workflow lifecycle
+  "workflow_start",
+  "workflow_end",
+  // Ask boundary
+  "ask_start",
+  "ask_end",
+  // Agent turn lifecycle
+  "agent_call_start",
+  "agent_call_end",
+  // Content delivery (stream-only)
+  "token",
+  // Tool invocation lifecycle
+  "tool_call_start",
+  "tool_call_end",
+  // Single-point tool events
+  "tool_approval",
+  "tool_denied",
+  // Delegation
+  "delegate",
+  // Handoff (spans two asks; not AskScoped).
+  // `handoff_start` emits before the target ask begins; always fired.
+  // `handoff_return` emits when control returns to source; roundtrip only
+  // (oneway handoffs have no return trip — the target's `ask_end` IS the
+  // end of the chain).
+  "handoff_start",
+  "handoff_return",
+  // Pipeline (retry/validation lifecycle) — added in PR 2; reserved here.
+  "pipeline",
+  // Progressive structured output — added in PR 2; reserved here.
+  "partial_object",
+  // Verification
+  "verify",
+  // Observability
+  "log",
+  "memory_remember",
+  "memory_recall",
+  "memory_forget",
+  // Durable execution checkpoints (`ctx.checkpoint`)
+  "checkpoint_save",
+  "checkpoint_replay",
+  // Human-in-the-loop (`ctx.awaitHuman`)
+  "await_human",
+  "await_human_resolved",
+  // Legacy gate events — emitted by current code; collapsed into `pipeline`
+  // in PR 2 (spec/16-streaming-wire-reliability §4.2).
+  "guardrail",
+  "schema_check",
+  "validate",
+  // Terminal workflow markers
+  "done",
+  "error"
+];
+
+// src/stream.ts
 var AxlStream = class _AxlStream extends Readable {
   bus = new EventEmitter();
-  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.
+   */
+  attemptByAsk = /* @__PURE__ */ new Map();
+  committedByAsk = /* @__PURE__ */ new Map();
   result = void 0;
   finished = false;
   promise;
@@ -5057,18 +5965,10 @@ var AxlStream = class _AxlStream extends Readable {
     this.promise.catch(() => {
     });
   }
-  static STREAM_EVENTS = /* @__PURE__ */ new Set([
-    "token",
-    "tool_call",
-    "tool_result",
-    "tool_approval",
-    "agent_start",
-    "agent_end",
-    "handoff",
-    "step",
-    "done",
-    "error"
-  ]);
+  /** Wire-format event names callers can subscribe to via `.on(name, fn)`.
+   *  Derived from the canonical `AXL_EVENT_TYPES` tuple — adding a new
+   *  variant in `types.ts` automatically extends the subscribable set. */
+  static STREAM_EVENTS = new Set(AXL_EVENT_TYPES);
   on(event, handler) {
     if (_AxlStream.STREAM_EVENTS.has(event)) {
       this.bus.on(event, handler);
@@ -5118,21 +6018,83 @@ var AxlStream = class _AxlStream extends Readable {
             while (true) {
               const { value, done } = await iter.next();
               if (done) return { value: void 0, done: true };
-              if (value.type === "token") return { value: value.data, done: false };
+              if (value.type === "token" && isRootLevel(value)) {
+                return { value: value.data, done: false };
+              }
+            }
+          }
+        };
+      }
+    };
+  }
+  /**
+   * Iterator over `{ askId, text }` pairs — one emission per token chunk,
+   * tagged with the ask frame that produced it. Complements `.text`
+   * (root-only stream): consumers building a split-pane UI that shows
+   * each sub-agent's output in its own lane can group by `askId`
+   * without iterating the raw stream and hand-filtering on `event.type`.
+   *
+   * Nested and root tokens both flow through. The `agent` field names
+   * the producing agent for UI labelling; it's undefined when the token
+   * was emitted outside any ask (rare — synthesized test fixtures).
+   */
+  get textByAsk() {
+    const self = this;
+    return {
+      [Symbol.asyncIterator]() {
+        const iter = self[Symbol.asyncIterator]();
+        return {
+          async next() {
+            while (true) {
+              const { value, done } = await iter.next();
+              if (done) {
+                return {
+                  value: void 0,
+                  done: true
+                };
+              }
+              if (value.type === "token") {
+                return {
+                  value: { askId: value.askId, agent: value.agent, text: value.data },
+                  done: false
+                };
+              }
             }
           }
         };
       }
     };
   }
-  get steps() {
-    const stepTypes = /* @__PURE__ */ new Set([
-      "agent_start",
-      "agent_end",
-      "tool_call",
-      "tool_result",
+  /**
+   * Iterator over structural lifecycle events only — skips per-token chatter
+   * and progressive partial_object emissions. Useful for waterfall UIs and
+   * any consumer that wants the "what happened" timeline without per-chunk
+   * noise. Renamed from `.steps` in the unified-event-model migration
+   * because these are events, not pipeline steps.
+   */
+  get lifecycle() {
+    const lifecycleTypes = /* @__PURE__ */ new Set([
+      "ask_start",
+      "ask_end",
+      "agent_call_start",
+      "agent_call_end",
+      "tool_call_start",
+      "tool_call_end",
       "tool_approval",
-      "handoff"
+      "tool_denied",
+      "handoff_start",
+      "handoff_return",
+      "delegate",
+      "pipeline",
+      "verify",
+      "workflow_start",
+      "workflow_end",
+      // Durable-execution checkpoints — structural points in the timeline.
+      "checkpoint_save",
+      "checkpoint_replay",
+      // Human-in-the-loop — pause/resume are major timeline landmarks.
+      "await_human",
+      "await_human_resolved"
     ]);
     const self = this;
     return {
@@ -5143,7 +6105,7 @@ var AxlStream = class _AxlStream extends Readable {
             while (true) {
               const { value, done } = await iter.next();
               if (done) return { value: void 0, done: true };
-              if (stepTypes.has(value.type)) return { value, done: false };
+              if (lifecycleTypes.has(value.type)) return { value, done: false };
             }
           }
         };
@@ -5163,10 +6125,34 @@ var AxlStream = class _AxlStream extends Readable {
     });
     return destination;
   }
-  /** Push a stream event. Called by the runtime. */
+  /** Push an event onto the stream. Called by the runtime. */
   _push(event) {
     if (this.finished) return;
-    if (event.type === "token") this.tokens.push(event.data);
+    if (event.type === "token" && isRootLevel(event)) {
+      const key = event.askId ?? "";
+      const attempt = this.attemptByAsk.get(key);
+      if (attempt) {
+        attempt.push(event.data);
+      } else {
+        this.attemptByAsk.set(key, [event.data]);
+      }
+    }
+    if (event.type === "pipeline" && isRootLevel(event)) {
+      const key = event.askId ?? "";
+      if (event.status === "committed") {
+        const attempt = this.attemptByAsk.get(key);
+        if (attempt && attempt.length > 0) {
+          const prev = this.committedByAsk.get(key) ?? "";
+          this.committedByAsk.set(key, prev + attempt.join(""));
+          this.attemptByAsk.set(key, []);
+        }
+      } else if (event.status === "failed") {
+        this.attemptByAsk.set(key, []);
+      }
+    }
+    if (event.type === "ask_end" && isRootLevel(event) && !event.outcome.ok) {
+      this.attemptByAsk.set(event.askId ?? "", []);
+    }
     this.bus.emit(event.type, event);
     this.push(event);
     const waiter = this.waiters.shift();
@@ -5176,12 +6162,25 @@ var AxlStream = class _AxlStream extends Readable {
       this.eventQueue.push(event);
     }
   }
-  /** Signal successful completion. */
-  _done(result) {
+  /**
+   * 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, executionId) {
     if (this.finished) return;
     this.finished = true;
     this.result = result;
-    const doneEvent = { type: "done", data: result };
+    const doneEvent = {
+      type: "done",
+      executionId,
+      step: Number.MAX_SAFE_INTEGER,
+      timestamp: Date.now(),
+      data: { result }
+    };
     this.bus.emit("done", doneEvent);
     this.push(doneEvent);
     this.push(null);
@@ -5197,11 +6196,19 @@ var AxlStream = class _AxlStream extends Readable {
     this.waiters.length = 0;
     this.bus.emit("__resolve", result);
   }
-  /** Signal an error. */
-  _error(error) {
+  /** Signal an error. `executionId` is required for the same reason as
+   *  `_done`: terminal events must carry a real id even when the
+   *  failure happens before any real trace event fires (review S4). */
+  _error(error, executionId) {
     if (this.finished) return;
     this.finished = true;
-    const errorEvent = { type: "error", message: error.message };
+    const errorEvent = {
+      type: "error",
+      executionId,
+      step: Number.MAX_SAFE_INTEGER,
+      timestamp: Date.now(),
+      data: { message: error.message, name: error.name }
+    };
     this.bus.emit("error", errorEvent);
     this.push(errorEvent);
     this.push(null);
@@ -5217,8 +6224,31 @@ var AxlStream = class _AxlStream extends Readable {
     this.waiters.length = 0;
     this.bus.emit("__reject", error);
   }
+  /** 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() {
-    return this.tokens.join("");
+    let out = "";
+    for (const [key, committed] of this.committedByAsk) {
+      out += committed;
+      const attempt = this.attemptByAsk.get(key);
+      if (attempt && attempt.length > 0) out += attempt.join("");
+    }
+    for (const [key, attempt] of this.attemptByAsk) {
+      if (this.committedByAsk.has(key)) continue;
+      if (attempt.length > 0) out += attempt.join("");
+    }
+    return out;
   }
 };
 
@@ -5764,6 +6794,32 @@ function hashInput(input) {
   }
   return (hash >>> 0).toString(16);
 }
+var DEFAULT_MAX_EVENTS_PER_EXECUTION = 5e4;
+function isAbortError(err) {
+  return typeof err === "object" && err !== null && err.name === "AbortError";
+}
+function pushEventBounded(execInfo, event, cap) {
+  if (event.type === "token" || event.type === "partial_object") return;
+  if (cap === Infinity || execInfo.events.length < cap) {
+    execInfo.events.push(event);
+    return;
+  }
+  const last = execInfo.events[execInfo.events.length - 1];
+  const alreadyTruncated = last?.type === "log" && typeof last.data === "object" && last.data !== null && last.data.event === "events_truncated";
+  if (!alreadyTruncated) {
+    execInfo.events[execInfo.events.length - 1] = {
+      type: "log",
+      executionId: event.executionId,
+      step: event.step,
+      timestamp: Date.now(),
+      data: {
+        event: "events_truncated",
+        cap,
+        message: `ExecutionInfo.events truncated at ${cap} entries. Subsequent events are still delivered to runtime.on('trace') and the WS broadcast \u2014 only the in-memory array is bounded. Raise via config.state.maxEventsPerExecution.`
+      }
+    };
+  }
+}
 var costScopeStorage = new AsyncLocalStorage2();
 var AxlRuntime = class extends EventEmitter2 {
   config;
@@ -5783,11 +6839,27 @@ var AxlRuntime = class extends EventEmitter2 {
   historicalExecutionsLoadPromise = null;
   evalHistory = [];
   evalHistoryLoadPromise = null;
+  /** Resolved cap on `ExecutionInfo.events` per execution. Cached on
+   *  the instance so per-event onTrace handlers don't reach into
+   *  `this.config.state` on every emission. */
+  maxEventsPerExecution;
   constructor(config) {
     super();
     this.config = resolveConfig(config ?? {});
     this.providerRegistry = new ProviderRegistry();
     this.stateStore = this.createStateStore();
+    const requested = this.config.state?.maxEventsPerExecution;
+    if (requested === void 0) {
+      this.maxEventsPerExecution = DEFAULT_MAX_EVENTS_PER_EXECUTION;
+    } else if (requested === Infinity) {
+      this.maxEventsPerExecution = Infinity;
+    } else if (typeof requested !== "number" || !Number.isFinite(requested) || !Number.isInteger(requested) || requested < 1) {
+      throw new RangeError(
+        `config.state.maxEventsPerExecution must be a positive integer or Infinity; got ${requested}`
+      );
+    } else {
+      this.maxEventsPerExecution = requested;
+    }
     if (this.config.memory) {
       this.memoryManager = new MemoryManager({
         vectorStore: this.config.memory.vectorStore,
@@ -5843,6 +6915,71 @@ var AxlRuntime = class extends EventEmitter2 {
         return new MemoryStore();
     }
   }
+  /**
+   * 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.
+   */
+  async runWorkflowBody(args) {
+    const { workflow: workflow2, ctx, execInfo, validated, span } = args;
+    try {
+      ctx._emitWorkflowStart(validated);
+      const raw = await workflow2.handler(ctx);
+      const result = workflow2.outputSchema ? workflow2.outputSchema.parse(raw) : raw;
+      execInfo.status = "completed";
+      execInfo.completedAt = Date.now();
+      execInfo.duration = execInfo.completedAt - execInfo.startedAt;
+      execInfo.result = result;
+      ctx._emitWorkflowEnd({
+        status: "completed",
+        duration: execInfo.duration,
+        result
+      });
+      if (this.stateStore.deleteCheckpoints) {
+        await this.stateStore.deleteCheckpoints(execInfo.executionId);
+      }
+      span?.setAttribute("axl.workflow.cost", execInfo.totalCost);
+      span?.setAttribute("axl.workflow.duration", execInfo.duration);
+      this.persistExecution(execInfo);
+      return result;
+    } catch (err) {
+      const aborted = isAbortError(err);
+      execInfo.status = "failed";
+      execInfo.completedAt = Date.now();
+      execInfo.duration = execInfo.completedAt - execInfo.startedAt;
+      execInfo.error = err instanceof Error ? err.message : String(err);
+      ctx._emitWorkflowEnd({
+        status: "failed",
+        duration: execInfo.duration,
+        error: execInfo.error,
+        ...aborted ? { aborted: true } : {}
+      });
+      this.persistExecution(execInfo);
+      throw err;
+    } finally {
+      this.abortControllers.delete(execInfo.executionId);
+    }
+  }
   /**
    * Persist a completed/failed execution to the state store (fire-and-forget)
    * and move it from the active executions map to the historical cache.
@@ -5858,7 +6995,6 @@ var AxlRuntime = class extends EventEmitter2 {
     this.executions.delete(id);
   }
   /** Register a workflow with the runtime. */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   register(workflow2) {
     this.workflows.set(workflow2.name, workflow2);
   }
@@ -5984,7 +7120,7 @@ var AxlRuntime = class extends EventEmitter2 {
     }
     try {
       await this.saveEvalResult({
-        id: resultObj.id ?? randomUUID2(),
+        id: resultObj.id ?? randomUUID3(),
         eval: name,
         timestamp: Date.now(),
         data: structuredClone(result)
@@ -6021,7 +7157,7 @@ var AxlRuntime = class extends EventEmitter2 {
    * and automatically emits trace events and tracks cost.
    */
   createContext(options) {
-    const executionId = randomUUID2();
+    const executionId = randomUUID3();
     const budgetLimit = options?.budget ? parseCost(options.budget) : Infinity;
     this.registerWithCostScope(executionId);
     return new WorkflowContext({
@@ -6037,10 +7173,12 @@ var AxlRuntime = class extends EventEmitter2 {
       sessionHistory: options?.sessionHistory,
       signal: options?.signal,
       onToken: options?.onToken,
+      onToolCall: options?.onToolCall,
+      onAgentStart: options?.onAgentStart,
       awaitHumanHandler: options?.awaitHumanHandler,
       onTrace: (event) => {
         this.emit("trace", event);
-        this.outputTraceEvent(event);
+        this.outputAxlEvent(event);
       },
       budgetContext: {
         totalCost: 0,
@@ -6067,7 +7205,7 @@ var AxlRuntime = class extends EventEmitter2 {
       );
     }
     const validated = workflow2.inputSchema.parse(input);
-    const executionId = randomUUID2();
+    const executionId = randomUUID3();
     const controller = new AbortController();
     this.abortControllers.set(executionId, controller);
     this.registerWithCostScope(executionId);
@@ -6075,7 +7213,7 @@ var AxlRuntime = class extends EventEmitter2 {
       executionId,
       workflow: name,
       status: "running",
-      steps: [],
+      events: [],
       totalCost: 0,
       startedAt: Date.now(),
       duration: 0
@@ -6091,20 +7229,35 @@ var AxlRuntime = class extends EventEmitter2 {
       sessionHistory,
       signal: controller.signal,
       onTrace: (event) => {
-        execInfo.steps.push(event);
-        if (event.cost) execInfo.totalCost += event.cost;
+        pushEventBounded(execInfo, event, this.maxEventsPerExecution);
+        execInfo.totalCost += eventCostContribution(event);
         this.emit("trace", event);
-        this.outputTraceEvent(event);
-        if (event.type === "handoff") {
+        this.outputAxlEvent(event);
+        if (event.type === "handoff_start") {
           const sessionId = options?.metadata?.sessionId;
           if (sessionId) {
-            const data = event.data;
             this.appendHandoffRecord(sessionId, {
-              source: event.agent ?? "",
-              target: data?.target ?? "",
-              mode: data?.mode ?? "oneway",
+              source: event.data.source,
+              target: event.data.target,
+              mode: event.data.mode,
               timestamp: event.timestamp,
-              duration: data?.duration ?? void 0
+              toAskId: event.toAskId
+            });
+          }
+        } else if (event.type === "handoff_return") {
+          const sessionId = options?.metadata?.sessionId;
+          if (sessionId) {
+            this.updateHandoffDuration(sessionId, {
+              toAskId: event.toAskId,
+              duration: event.data.duration
+            });
+          }
+        } else if (event.type === "ask_end") {
+          const sessionId = options?.metadata?.sessionId;
+          if (sessionId && event.askId && typeof event.duration === "number") {
+            this.updateHandoffDuration(sessionId, {
+              toAskId: event.askId,
+              duration: event.duration
             });
           }
         }
@@ -6131,45 +7284,13 @@ var AxlRuntime = class extends EventEmitter2 {
         "axl.execution.id": executionId,
         "axl.workflow.input_hash": hashInput(validated)
       },
-      async (span) => {
-        try {
-          ctx._emitWorkflowStart(validated);
-          const result = await workflow2.handler(ctx);
-          const output = workflow2.outputSchema ? workflow2.outputSchema.parse(result) : result;
-          execInfo.status = "completed";
-          execInfo.completedAt = Date.now();
-          execInfo.duration = execInfo.completedAt - execInfo.startedAt;
-          execInfo.result = output;
-          ctx._emitWorkflowEnd({
-            status: "completed",
-            duration: execInfo.duration,
-            result: output
-          });
-          if (this.stateStore.deleteCheckpoints) {
-            await this.stateStore.deleteCheckpoints(executionId);
-          }
-          span.setAttribute("axl.workflow.cost", execInfo.totalCost);
-          span.setAttribute("axl.workflow.duration", execInfo.duration);
-          this.persistExecution(execInfo);
-          return output;
-        } catch (err) {
-          const aborted = typeof err === "object" && err !== null && err.name === "AbortError";
-          execInfo.status = "failed";
-          execInfo.completedAt = Date.now();
-          execInfo.duration = execInfo.completedAt - execInfo.startedAt;
-          execInfo.error = err instanceof Error ? err.message : String(err);
-          ctx._emitWorkflowEnd({
-            status: "failed",
-            duration: execInfo.duration,
-            error: execInfo.error,
-            ...aborted ? { aborted: true } : {}
-          });
-          this.persistExecution(execInfo);
-          throw err;
-        } finally {
-          this.abortControllers.delete(executionId);
-        }
-      }
+      (span) => this.runWorkflowBody({
+        workflow: workflow2,
+        ctx,
+        execInfo,
+        validated,
+        span
+      })
     );
   }
   /** Execute a workflow and return a stream. */
@@ -6177,21 +7298,20 @@ var AxlRuntime = class extends EventEmitter2 {
     const axlStream = new AxlStream();
     const controller = new AbortController();
     axlStream.on("close", () => controller.abort());
+    const executionId = randomUUID3();
+    this.abortControllers.set(executionId, controller);
     let execInfo;
-    let ctx;
     const run = async () => {
       const workflow2 = this.workflows.get(name);
       if (!workflow2) throw new Error(`Workflow "${name}" not registered`);
       const validated = workflow2.inputSchema.parse(input);
-      const executionId = randomUUID2();
-      this.abortControllers.set(executionId, controller);
       const sessionHistory = options?.metadata?.sessionHistory ?? void 0;
       this.registerWithCostScope(executionId);
       execInfo = {
         executionId,
         workflow: name,
         status: "running",
-        steps: [],
+        events: [],
         totalCost: 0,
         startedAt: Date.now(),
         duration: 0
@@ -6205,69 +7325,46 @@ var AxlRuntime = class extends EventEmitter2 {
         providerRegistry: this.providerRegistry,
         sessionHistory,
         signal: controller.signal,
+        // Sentinel `onToken` so the streaming code path in WorkflowContext
+        // is entered (it's gated on `this.onToken` being defined). The
+        // actual `token` AxlEvents are emitted via `emitEvent` and reach
+        // the wire through `onTrace` — this callback is just the gate.
+        onToken: () => {
+        },
         onTrace: (event) => {
-          execInfo.steps.push(event);
-          if (event.cost) execInfo.totalCost += event.cost;
+          pushEventBounded(execInfo, event, this.maxEventsPerExecution);
+          execInfo.totalCost += eventCostContribution(event);
           this.emit("trace", event);
-          this.outputTraceEvent(event);
-          if (event.type === "handoff") {
-            const data = event.data;
-            axlStream._push({
-              type: "handoff",
-              source: event.agent ?? "",
-              target: data?.target ?? "",
-              mode: data?.mode ?? void 0
-            });
+          this.outputAxlEvent(event);
+          axlStream._push(event);
+          if (event.type === "handoff_start") {
             const sessionId = options?.metadata?.sessionId;
             if (sessionId) {
               this.appendHandoffRecord(sessionId, {
-                source: event.agent ?? "",
-                target: data?.target ?? "",
-                mode: data?.mode ?? "oneway",
+                source: event.data.source,
+                target: event.data.target,
+                mode: event.data.mode,
                 timestamp: event.timestamp,
-                duration: data?.duration ?? void 0
+                toAskId: event.toAskId
+              });
+            }
+          } else if (event.type === "handoff_return") {
+            const sessionId = options?.metadata?.sessionId;
+            if (sessionId) {
+              this.updateHandoffDuration(sessionId, {
+                toAskId: event.toAskId,
+                duration: event.data.duration
+              });
+            }
+          } else if (event.type === "ask_end") {
+            const sessionId = options?.metadata?.sessionId;
+            if (sessionId && event.askId && typeof event.duration === "number") {
+              this.updateHandoffDuration(sessionId, {
+                toAskId: event.askId,
+                duration: event.duration
               });
             }
-          } else if (event.type === "tool_approval") {
-            const data = event.data;
-            axlStream._push({
-              type: "tool_approval",
-              name: event.tool ?? "",
-              args: data?.args,
-              approved: data?.approved === true,
-              ...data?.reason ? { reason: data.reason } : {}
-            });
-          } else if (event.type === "tool_denied") {
-          } else if (event.type === "agent_call") {
-            axlStream._push({
-              type: "agent_end",
-              agent: event.agent ?? "",
-              cost: event.cost,
-              duration: event.duration
-            });
-          } else if (event.type === "tool_call") {
-            axlStream._push({
-              type: "tool_result",
-              name: event.tool ?? "",
-              result: event.data?.result,
-              callId: event.data?.callId
-            });
           }
-          axlStream._push({ type: "step", step: event.step, data: event });
-        },
-        onToken: (token) => {
-          axlStream._push({ type: "token", data: token });
-        },
-        onToolCall: (call) => {
-          axlStream._push({
-            type: "tool_call",
-            name: call.name,
-            args: call.args,
-            callId: call.callId
-          });
-        },
-        onAgentStart: (info) => {
-          axlStream._push({ type: "agent_start", agent: info.agent, model: info.model });
         },
         pendingDecisions: this.pendingDecisionResolvers,
         awaitHumanHandler: options?.awaitHumanHandler,
@@ -6284,7 +7381,6 @@ var AxlRuntime = class extends EventEmitter2 {
           policy: "finish_and_stop"
         }
       });
-      ctx = wfCtx;
       return this.spanManager.withSpanAsync(
         "axl.workflow.execute",
         {
@@ -6292,49 +7388,25 @@ var AxlRuntime = class extends EventEmitter2 {
           "axl.execution.id": executionId,
           "axl.workflow.input_hash": hashInput(validated)
         },
-        async (span) => {
-          try {
-            wfCtx._emitWorkflowStart(validated);
-            const rawResult = await workflow2.handler(wfCtx);
-            const result = workflow2.outputSchema ? workflow2.outputSchema.parse(rawResult) : rawResult;
-            execInfo.status = "completed";
-            execInfo.completedAt = Date.now();
-            execInfo.duration = execInfo.completedAt - execInfo.startedAt;
-            execInfo.result = result;
-            wfCtx._emitWorkflowEnd({
-              status: "completed",
-              duration: execInfo.duration,
-              result
-            });
-            if (this.stateStore.deleteCheckpoints) {
-              await this.stateStore.deleteCheckpoints(executionId);
-            }
-            span.setAttribute("axl.workflow.cost", execInfo.totalCost);
-            span.setAttribute("axl.workflow.duration", execInfo.duration);
-            this.persistExecution(execInfo);
-            return result;
-          } finally {
-            this.abortControllers.delete(executionId);
-          }
-        }
+        (span) => this.runWorkflowBody({
+          workflow: workflow2,
+          ctx: wfCtx,
+          execInfo,
+          validated,
+          span
+        })
       );
     };
-    run().then((result) => axlStream._done(result)).catch((err) => {
-      if (execInfo) {
-        const aborted = typeof err === "object" && err !== null && err.name === "AbortError";
+    run().then((result) => axlStream._done(result, executionId)).catch((err) => {
+      if (execInfo && execInfo.status === "running") {
         execInfo.status = "failed";
         execInfo.completedAt = Date.now();
         execInfo.duration = execInfo.completedAt - execInfo.startedAt;
         execInfo.error = err instanceof Error ? err.message : String(err);
-        ctx?._emitWorkflowEnd({
-          status: "failed",
-          duration: execInfo.duration,
-          error: execInfo.error,
-          ...aborted ? { aborted: true } : {}
-        });
         this.persistExecution(execInfo);
       }
-      axlStream._error(err instanceof Error ? err : new Error(String(err)));
+      this.abortControllers.delete(executionId);
+      axlStream._error(err instanceof Error ? err : new Error(String(err)), executionId);
     });
     return axlStream;
   }
@@ -6594,11 +7666,11 @@ var AxlRuntime = class extends EventEmitter2 {
    *   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.
    *
@@ -6618,8 +7690,8 @@ var AxlRuntime = class extends EventEmitter2 {
     const capturedTraces = options?.captureTraces ? [] : void 0;
     const listener = (event) => {
       if (!scope.trackedIds.has(event.executionId)) return;
-      if (event.cost) scope.totalCost += event.cost;
-      if (event.type === "agent_call") {
+      scope.totalCost += eventCostContribution(event);
+      if (event.type === "agent_call_end") {
         if (event.model) modelCalls.set(event.model, (modelCalls.get(event.model) ?? 0) + 1);
         agentCalls++;
         if (event.tokens) {
@@ -6632,7 +7704,8 @@ var AxlRuntime = class extends EventEmitter2 {
         workflowCalls.set(event.workflow, (workflowCalls.get(event.workflow) ?? 0) + 1);
       }
       if (capturedTraces) {
-        if (event.type === "agent_call" && event.data) {
+        if (event.type === "token" || event.type === "partial_object") return;
+        if (event.type === "agent_call_start" && event.data) {
           const d = event.data;
           if ("messages" in d) {
             const rest = {};
@@ -6697,7 +7770,7 @@ var AxlRuntime = class extends EventEmitter2 {
    * The emit('trace', event) call happens before this method is called, so
    * programmatic subscribers always receive events regardless of trace config.
    */
-  outputTraceEvent(event) {
+  outputAxlEvent(event) {
     const traceConfig = this.config.trace;
     if (!traceConfig?.enabled) return;
     const level = traceConfig.level ?? "steps";
@@ -6721,9 +7794,9 @@ var AxlRuntime = class extends EventEmitter2 {
       }
       return;
     }
-    this.logTraceEvent(event);
+    this.logAxlEvent(event);
   }
-  logTraceEvent(event) {
+  logAxlEvent(event) {
     const level = this.config.trace?.level ?? "steps";
     const workflowPrefix = event.workflow ? `workflow:${event.workflow} | ` : "";
     const parts = [`[axl] execution:${event.executionId}`];
@@ -6734,7 +7807,7 @@ var AxlRuntime = class extends EventEmitter2 {
       const status = d?.aborted ? "aborted" : d?.status ?? "completed";
       parts.push(`${workflowPrefix}${status}`);
       if (event.duration != null) parts.push(`${(event.duration / 1e3).toFixed(1)}s`);
-    } else if (event.type === "agent_call") {
+    } else if (event.type === "agent_call_end") {
       parts.push(`${workflowPrefix}step:${event.step} agent_call`);
       if (event.agent) parts.push(`agent:${event.agent}`);
       if (event.promptVersion) parts.push(`version:${event.promptVersion}`);
@@ -6744,7 +7817,7 @@ var AxlRuntime = class extends EventEmitter2 {
       if (level === "full" && event.data) {
         parts.push(`data:${JSON.stringify(event.data)}`);
       }
-    } else if (event.type === "tool_call") {
+    } else if (event.type === "tool_call_end") {
       parts.push(`${workflowPrefix}step:${event.step} tool_call`);
       if (event.tool) parts.push(`tool:${event.tool}`);
       if (event.duration) parts.push(`${event.duration}ms`);
@@ -6761,8 +7834,9 @@ var AxlRuntime = class extends EventEmitter2 {
       parts.push(`${workflowPrefix}log: ${JSON.stringify(event.data)}`);
     } else {
       parts.push(`${workflowPrefix}${event.type}`);
-      if (level === "full" && event.data) {
-        parts.push(`data:${JSON.stringify(event.data)}`);
+      const data = event.data;
+      if (level === "full" && data !== void 0) {
+        parts.push(`data:${JSON.stringify(data)}`);
       }
     }
     console.log(parts.join(" | "));
@@ -6782,6 +7856,35 @@ var AxlRuntime = class extends EventEmitter2 {
     }).catch(() => {
     });
   }
+  /**
+   * 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`.
+   */
+  updateHandoffDuration(sessionId, match) {
+    this.stateStore.getSessionMeta(sessionId, "handoffHistory").then((existing) => {
+      const history = existing ?? [];
+      for (const r of history) {
+        if (r.toAskId === match.toAskId) {
+          r.duration = match.duration;
+          return this.stateStore.saveSessionMeta(sessionId, "handoffHistory", history);
+        }
+      }
+      return void 0;
+    }).catch(() => {
+    });
+  }
 };
 
 // src/state/redis.ts
@@ -6844,27 +7947,13 @@ var RedisStore = class _RedisStore {
     return "axl:eval-history-ids";
   }
   // ── Checkpoints ──────────────────────────────────────────────────────
-  async saveCheckpoint(executionId, step, data) {
-    await this.client.hSet(this.checkpointKey(executionId), String(step), JSON.stringify(data));
+  async saveCheckpoint(executionId, name, data) {
+    await this.client.hSet(this.checkpointKey(executionId), name, JSON.stringify(data));
   }
-  async getCheckpoint(executionId, step) {
-    const raw = await this.client.hGet(this.checkpointKey(executionId), String(step));
+  async getCheckpoint(executionId, name) {
+    const raw = await this.client.hGet(this.checkpointKey(executionId), name);
     return raw != null ? JSON.parse(raw) : null;
   }
-  async getLatestCheckpoint(executionId) {
-    const all = await this.client.hGetAll(this.checkpointKey(executionId));
-    if (!all || Object.keys(all).length === 0) return null;
-    let maxStep = -1;
-    let maxData = null;
-    for (const [stepStr, raw] of Object.entries(all)) {
-      const step = Number(stepStr);
-      if (step > maxStep) {
-        maxStep = step;
-        maxData = JSON.parse(raw);
-      }
-    }
-    return { step: maxStep, data: maxData };
-  }
   // ── Sessions ─────────────────────────────────────────────────────────
   async saveSession(sessionId, history) {
     await this.client.set(this.sessionKey(sessionId), JSON.stringify(history));
@@ -7149,11 +8238,13 @@ function cosineSimilarity2(a, b) {
   return denom === 0 ? 0 : dot / denom;
 }
 export {
+  AXL_EVENT_TYPES,
   AnthropicProvider,
   AxlError,
   AxlRuntime,
   AxlStream,
   BudgetExceededError,
+  COST_BEARING_LEAF_TYPES,
   GeminiProvider,
   GuardrailError,
   InMemoryVectorStore,
@@ -7168,6 +8259,8 @@ export {
   OpenAIResponsesProvider,
   ProviderRegistry,
   QuorumNotMet,
+  REDACTED,
+  REDACTION_RULES,
   RedisStore,
   SQLiteStore,
   Session,
@@ -7180,7 +8273,12 @@ export {
   agent,
   createSpanManager,
   defineConfig,
+  eventCostContribution,
   extractJson,
+  isCostBearingLeaf,
+  isRootLevel,
+  parsePartialJson,
+  redactEvent,
   resolveThinkingOptions,
   tool,
   workflow,