@axlsdk/axl 0.14.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
@@ -1965,6 +2003,21 @@ var TimeoutError = class extends AxlError {
     this.name = "TimeoutError";
   }
 };
+function formatBudgetCost(cost) {
+  if (Number.isNaN(cost)) return "$NaN";
+  if (cost === Infinity) return "$Infinity";
+  if (cost === -Infinity) return "-$Infinity";
+  if (cost === 0) return "$0.00";
+  const sign = cost < 0 ? "-" : "";
+  const abs = Math.abs(cost);
+  if (abs < 1e-6) return `${sign}< $0.000001`;
+  if (abs < 1e-4) {
+    const [mantissa, exponent] = abs.toExponential(2).split("e");
+    return `${sign}$${mantissa}e${parseInt(exponent, 10)}`;
+  }
+  if (abs < 0.01) return `${sign}$${abs.toFixed(6)}`;
+  return `${sign}$${abs.toFixed(2)}`;
+}
 var BudgetExceededError = class extends AxlError {
   limit;
   spent;
@@ -1972,7 +2025,9 @@ var BudgetExceededError = class extends AxlError {
   constructor(limit, spent, policy) {
     super(
       "BUDGET_EXCEEDED",
-      `Budget exceeded: spent $${spent.toFixed(4)} of $${limit.toFixed(4)} limit (policy: ${policy})`
+      `Budget exceeded: spent ${formatBudgetCost(spent)} of ${formatBudgetCost(
+        limit
+      )} limit (policy: ${policy})`
     );
     this.name = "BudgetExceededError";
     this.limit = limit;
@@ -2024,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;
@@ -2101,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;
@@ -2160,6 +2642,14 @@ function extractBalanced(str, start, openChar, closeChar) {
   }
   return null;
 }
+function appendRetryMessages(messages, content, feedbackMessage, providerMetadata) {
+  messages.push({
+    role: "assistant",
+    content,
+    ...providerMetadata ? { providerMetadata } : {}
+  });
+  messages.push({ role: "system", content: feedbackMessage });
+}
 function estimateMessagesTokens(messages) {
   let total = 0;
   for (const msg of messages) {
@@ -2194,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;
@@ -2230,6 +2746,10 @@ var WorkflowContext = class _WorkflowContext {
     this.awaitHumanHandler = init.awaitHumanHandler;
     this.onAgentStart = init.onAgentStart;
     this.onAgentCallComplete = init.onAgentCallComplete;
+    this.autoCheckpointCounters = init.autoCheckpointCounters ?? {
+      byAgent: /* @__PURE__ */ new Map(),
+      root: 0
+    };
     if (init.metadata?.summaryCache) {
       this.summaryCache = init.metadata.summaryCache;
     }
@@ -2238,8 +2758,21 @@ 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.
+   *
+   * 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() {
     return new _WorkflowContext({
@@ -2255,14 +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
-      // Isolated: sessionHistory (empty), stepCounter (0),
-      // onToken (null), onAgentStart (null), onToolCall (null)
+      workflowName: this.workflowName,
+      // 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)
     });
   }
   /**
@@ -2273,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 }
         });
@@ -2427,14 +3044,25 @@ ${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: { guardrailType: "input", blocked: inputResult.block, reason: inputResult.reason }
+        data: {
+          guardrailType: "input",
+          blocked: inputResult.block,
+          ...inputResult.reason ? { reason: inputResult.reason } : {},
+          // Input guardrails can't retry (prompt is user-supplied), so attempt
+          // and maxAttempts are always 1 — emit them for shape consistency with
+          // output guardrails so consumers don't need two narrowers.
+          attempt: 1,
+          maxAttempts: 1
+        }
       });
       this.spanManager?.addEventToActiveSpan("axl.guardrail.check", {
         "axl.guardrail.type": "input",
         "axl.guardrail.blocked": inputResult.block,
+        "axl.guardrail.attempt": 1,
+        "axl.guardrail.maxAttempts": 1,
         ...inputResult.reason ? { "axl.guardrail.reason": inputResult.reason } : {}
       });
       if (inputResult.block) {
@@ -2450,22 +3078,51 @@ ${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;
     let schemaRetries = 0;
     let validateRetries = 0;
+    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,
         temperature: options?.temperature ?? agent2._config.temperature,
@@ -2482,82 +3139,172 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       if (options?.schema && toolDefs.length === 0) {
         chatOptions.responseFormat = { type: "json_object" };
       }
-      this.onAgentStart?.({ agent: agent2._name, model: modelUri });
+      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 {
+          messagesSnapshot = structuredClone(currentMessages);
+        } catch (err) {
+          console.warn(
+            "[axl] verbose trace messages snapshot failed to clone; emitting shallow copy:",
+            err instanceof Error ? err.message : String(err)
+          );
+          messagesSnapshot = [...currentMessages];
+        }
+      }
+      const retryReason = pendingRetryReason;
+      pendingRetryReason = void 0;
+      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;
-      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
-              };
+      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);
         }
-        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) {
-        if (this.budgetContext) {
-          this.budgetContext.totalCost += response.cost;
-          if (this.budgetContext.totalCost >= this.budgetContext.limit) {
-            this.budgetContext.exceeded = true;
-            if (this.budgetContext.policy === "hard_stop" && this.budgetContext.abortController) {
-              this.budgetContext.abortController.abort();
-            }
-          }
-        }
+        this._accumulateBudgetCost(response.cost);
       }
-      this.emitTrace({
-        type: "agent_call",
+      this.emitEvent({
+        type: "agent_call_end",
         agent: agent2._name,
         model: modelUri,
         promptVersion: agent2._config.version,
@@ -2567,8 +3314,13 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
           output: response.usage.completion_tokens,
           reasoning: response.usage.reasoning_tokens
         } : void 0,
-        duration: Date.now() - startTime,
-        data: { prompt, response: response.content }
+        duration: Date.now() - turnStart,
+        data: {
+          response: response.content,
+          ...response.thinking_content ? { thinking: response.thinking_content } : {},
+          turn: turns,
+          ...retryReason ? { retryReason } : {}
+        }
       });
       if (response.tool_calls && response.tool_calls.length > 0) {
         currentMessages.push({
@@ -2593,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,
@@ -2600,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();
@@ -2627,24 +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 }
-                      });
-                      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 }
-                  });
+                  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;
               }
@@ -2658,24 +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 }
-                    });
+                    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 }
-              });
-              return onewayResult;
+              return await handoffFn();
             }
           }
           const toolOverride = this.toolOverrides?.get(toolName);
@@ -2691,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;
@@ -2719,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,
@@ -2736,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"}`,
@@ -2755,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 () => {
@@ -2766,24 +3589,18 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
               });
               if (!decision.approved) {
                 const reason = decision.reason ?? "Denied by human";
-                this.emitTrace({
-                  type: "tool_denied",
-                  agent: agent2._name,
-                  tool: toolName,
-                  data: { denied: true, reason, args: toolArgs }
-                });
                 currentMessages.push({
                   role: "tool",
                   content: JSON.stringify({ error: `Tool denied by human: ${reason}` }),
                   tool_call_id: toolCall.id
                 });
-                return false;
+                return { approved: false, reason };
               }
-              return true;
+              return { approved: true };
             };
-            let approved;
+            let approvalOutcome;
             if (this.spanManager) {
-              approved = await this.spanManager.withSpanAsync(
+              approvalOutcome = await this.spanManager.withSpanAsync(
                 "axl.tool.approval",
                 {
                   "axl.tool.name": toolName,
@@ -2791,20 +3608,24 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                 },
                 async (span) => {
                   const result = await approvalFn();
-                  span.setAttribute("axl.tool.approval.approved", result);
+                  span.setAttribute("axl.tool.approval.approved", result.approved);
                   return result;
                 }
               );
             } else {
-              approved = await approvalFn();
+              approvalOutcome = await approvalFn();
             }
-            if (!approved) continue;
-            this.emitTrace({
-              type: "tool_denied",
+            this.emitEvent({
+              type: "tool_approval",
               agent: agent2._name,
               tool: toolName,
-              data: { denied: false, args: toolArgs }
+              data: {
+                approved: approvalOutcome.approved,
+                args: toolArgs,
+                ...approvalOutcome.reason ? { reason: approvalOutcome.reason } : {}
+              }
             });
+            if (!approvalOutcome.approved) continue;
           }
           if (tool2 && tool2.hooks?.before) {
             try {
@@ -2879,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,
@@ -2897,37 +3718,52 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       const content = response.content;
       if (guardrails?.output) {
         const outputResult = await guardrails.output(content, { metadata: this.metadata });
-        this.emitTrace({
+        const attempt = guardrailOutputRetries + 1;
+        const maxAttempts = maxGuardrailRetries + 1;
+        const onBlock = guardrails.onBlock ?? "throw";
+        let feedbackMessage;
+        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.emitEvent({
           type: "guardrail",
           agent: agent2._name,
           data: {
             guardrailType: "output",
             blocked: outputResult.block,
-            reason: outputResult.reason
+            ...outputResult.reason ? { reason: outputResult.reason } : {},
+            attempt,
+            maxAttempts,
+            ...feedbackMessage ? { feedbackMessage } : {}
           }
         });
         this.spanManager?.addEventToActiveSpan("axl.guardrail.check", {
           "axl.guardrail.type": "output",
           "axl.guardrail.blocked": outputResult.block,
+          "axl.guardrail.attempt": attempt,
+          "axl.guardrail.maxAttempts": maxAttempts,
           ...outputResult.reason ? { "axl.guardrail.reason": outputResult.reason } : {}
         });
         if (outputResult.block) {
-          const onBlock = guardrails.onBlock ?? "throw";
-          if (onBlock === "retry") {
-            const maxGuardrailRetries = guardrails.maxRetries ?? 2;
-            if (guardrailOutputRetries < maxGuardrailRetries) {
-              guardrailOutputRetries++;
-              currentMessages.push({
-                role: "assistant",
-                content,
-                ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
-              });
-              currentMessages.push({
-                role: "system",
-                content: `Your previous response was blocked by a safety guardrail: ${outputResult.reason ?? "Output blocked"}. Please provide a different response that complies with the guidelines.`
-              });
-              continue;
-            }
+          if (feedbackMessage) {
+            this.emitEvent({
+              type: "pipeline",
+              agent: agent2._name,
+              status: "failed",
+              stage: "guardrail",
+              attempt: guardrailOutputRetries + 1,
+              maxAttempts: maxGuardrailRetries + 1,
+              reason: feedbackMessage
+            });
+            guardrailOutputRetries++;
+            appendRetryMessages(
+              currentMessages,
+              content,
+              feedbackMessage,
+              response.providerMetadata
+            );
+            pendingRetryReason = "guardrail";
+            continue;
           }
           if (typeof onBlock === "function") {
             return onBlock(outputResult.reason ?? "Output blocked by guardrail", {
@@ -2939,30 +3775,67 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       }
       let validated = void 0;
       if (options?.schema) {
+        const maxSchemaRetries = options.retries ?? 3;
+        const schemaAttempt = schemaRetries + 1;
+        const schemaMaxAttempts = maxSchemaRetries + 1;
+        let schemaValid = false;
+        let schemaReason;
+        let schemaFeedback;
+        let schemaErr;
         try {
           const parsed = JSON.parse(extractJson(content));
           validated = options.schema.parse(parsed);
+          schemaValid = true;
         } catch (err) {
-          const maxSchemaRetries = options.retries ?? 3;
+          schemaErr = err;
+          schemaReason = err instanceof Error ? err.message : String(err);
           if (schemaRetries < maxSchemaRetries) {
+            schemaFeedback = `Your response was not valid JSON or did not match the required schema: ${schemaReason}. Please fix and try again.`;
+          }
+        }
+        this.emitEvent({
+          type: "schema_check",
+          agent: agent2._name,
+          data: {
+            valid: schemaValid,
+            ...schemaReason ? { reason: schemaReason } : {},
+            attempt: schemaAttempt,
+            maxAttempts: schemaMaxAttempts,
+            ...schemaFeedback ? { feedbackMessage: schemaFeedback } : {}
+          }
+        });
+        this.spanManager?.addEventToActiveSpan("axl.schema.check", {
+          "axl.schema.valid": schemaValid,
+          "axl.schema.attempt": schemaAttempt,
+          "axl.schema.maxAttempts": schemaMaxAttempts,
+          ...schemaReason ? { "axl.schema.reason": schemaReason } : {}
+        });
+        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++;
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            currentMessages.push({
-              role: "assistant",
+            appendRetryMessages(
+              currentMessages,
               content,
-              ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
-            });
-            currentMessages.push({
-              role: "system",
-              content: `Your response was not valid JSON or did not match the required schema: ${errorMsg}. Please fix and try again.`
-            });
+              schemaFeedback,
+              response.providerMetadata
+            );
+            pendingRetryReason = "schema";
             continue;
           }
-          const zodErr = err instanceof ZodError ? err : new ZodError([
+          const zodErr = schemaErr instanceof ZodError ? schemaErr : new ZodError([
             {
               code: "custom",
               path: [],
-              message: err instanceof Error ? err.message : String(err)
+              message: schemaReason ?? "Schema parse failed"
             }
           ]);
           throw new VerifyError(content, zodErr, maxSchemaRetries);
@@ -2978,31 +3851,49 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
           const reason = err instanceof Error ? err.message : String(err);
           validateResult = { valid: false, reason: `Validator error: ${reason}` };
         }
-        this.emitTrace({
+        const maxValidateRetries = options.validateRetries ?? 2;
+        const validateAttempt = validateRetries + 1;
+        const validateMaxAttempts = maxValidateRetries + 1;
+        let validateFeedback;
+        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.emitEvent({
           type: "validate",
           agent: agent2._name,
           data: {
             valid: validateResult.valid,
-            ...validateResult.reason ? { reason: validateResult.reason } : {}
+            ...validateResult.reason ? { reason: validateResult.reason } : {},
+            attempt: validateAttempt,
+            maxAttempts: validateMaxAttempts,
+            ...validateFeedback ? { feedbackMessage: validateFeedback } : {}
           }
         });
         this.spanManager?.addEventToActiveSpan("axl.validate.check", {
           "axl.validate.valid": validateResult.valid,
+          "axl.validate.attempt": validateAttempt,
+          "axl.validate.maxAttempts": validateMaxAttempts,
           ...validateResult.reason ? { "axl.validate.reason": validateResult.reason } : {}
         });
         if (!validateResult.valid) {
-          const maxValidateRetries = options.validateRetries ?? 2;
-          if (validateRetries < maxValidateRetries) {
+          if (validateFeedback) {
+            this.emitEvent({
+              type: "pipeline",
+              agent: agent2._name,
+              status: "failed",
+              stage: "validate",
+              attempt: validateRetries + 1,
+              maxAttempts: (options.validateRetries ?? 2) + 1,
+              reason: validateFeedback
+            });
             validateRetries++;
-            currentMessages.push({
-              role: "assistant",
+            appendRetryMessages(
+              currentMessages,
               content,
-              ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
-            });
-            currentMessages.push({
-              role: "system",
-              content: `Your response parsed correctly but failed validation: ${validateResult.reason ?? "Validation failed"}. Previous attempts are visible above. Please fix and try again.`
-            });
+              validateFeedback,
+              response.providerMetadata
+            );
+            pendingRetryReason = "validate";
             continue;
           }
           throw new ValidationError(
@@ -3012,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;
     }
@@ -3140,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",
@@ -3371,6 +4327,17 @@ ${summaryResponse.content}`
   async verify(fn, schema, options) {
     const maxRetries = options?.retries ?? 3;
     let lastRetry = void 0;
+    const emitVerifyOutcome = (passed, attempts, lastError) => {
+      this.emitEvent({
+        type: "verify",
+        agent: void 0,
+        data: {
+          passed,
+          attempts,
+          ...lastError ? { lastError } : {}
+        }
+      });
+    };
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       let rawOutput;
       try {
@@ -3389,12 +4356,14 @@ ${summaryResponse.content}`
             const errorMsg = validateResult.reason ?? "Validation failed";
             lastRetry = { error: errorMsg, output: rawOutput, parsed };
             if (attempt === maxRetries) {
+              emitVerifyOutcome(false, attempt + 1, errorMsg);
               if (options?.fallback !== void 0) return options.fallback;
               throw new ValidationError(parsed, errorMsg, maxRetries);
             }
             continue;
           }
         }
+        emitVerifyOutcome(true, attempt + 1);
         return parsed;
       } catch (err) {
         if (err instanceof ValidationError) {
@@ -3404,6 +4373,7 @@ ${summaryResponse.content}`
             parsed: err.lastOutput
           };
           if (attempt === maxRetries) {
+            emitVerifyOutcome(false, attempt + 1, err.reason);
             if (options?.fallback !== void 0) return options.fallback;
             throw err;
           }
@@ -3412,6 +4382,7 @@ ${summaryResponse.content}`
         if (err instanceof VerifyError) {
           lastRetry = { error: err.message, output: rawOutput ?? err.lastOutput };
           if (attempt === maxRetries) {
+            emitVerifyOutcome(false, attempt + 1, err.message);
             if (options?.fallback !== void 0) return options.fallback;
             throw err;
           }
@@ -3420,12 +4391,14 @@ ${summaryResponse.content}`
         const errorMsg = err instanceof ZodError ? err.message : err instanceof Error ? err.message : String(err);
         lastRetry = { error: errorMsg, output: rawOutput };
         if (attempt === maxRetries) {
+          emitVerifyOutcome(false, attempt + 1, errorMsg);
           if (options?.fallback !== void 0) return options.fallback;
           const zodErr = err instanceof ZodError ? err : new ZodError([{ code: "custom", path: [], message: errorMsg }]);
           throw new VerifyError(rawOutput, zodErr, maxRetries);
         }
       }
     }
+    emitVerifyOutcome(false, maxRetries + 1, lastRetry?.error ?? "Verify failed");
     if (options?.fallback !== void 0) return options.fallback;
     throw new VerifyError(
       lastRetry?.output,
@@ -3495,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",
@@ -3600,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;
@@ -3682,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;
     }
@@ -3705,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,
@@ -3714,26 +4697,111 @@ ${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"
       });
     }
     return decision;
   }
+  /**
+   * Compose an `AbortSignal` for a memory operation's underlying embedder
+   * fetch. Combines the parent context signal (user cancellation,
+   * `runtime.execute({ signal })`) with the budget hard_stop abort so
+   * that either cause correctly aborts an in-flight embed call.
+   *
+   * Returns `undefined` if there's nothing to cancel on — the embedder
+   * runs without a signal in that case, matching its prior behavior.
+   *
+   * @internal
+   */
+  _composeMemorySignal() {
+    const budgetSignal = this.budgetContext?.abortController?.signal;
+    if (this.signal && budgetSignal) return AbortSignal.any([this.signal, budgetSignal]);
+    return this.signal ?? budgetSignal;
+  }
+  /**
+   * Accumulate a cost amount into the active `budgetContext` and trip the
+   * `exceeded` flag if we've crossed the limit. On `hard_stop` policy,
+   * also fires the abort controller so in-flight operations cancel.
+   *
+   * Called from every code path that spends money: the `agent_call` loop,
+   * semantic memory operations (`ctx.remember({embed:true})`, `ctx.recall({query})`),
+   * and any future cost-emitting primitive. Centralizing the logic here
+   * means `ctx.budget({ limit, policy })` accurately enforces the limit
+   * across ALL cost sources — not just agent calls.
+   *
+   * @internal
+   */
+  _accumulateBudgetCost(amount) {
+    if (!this.budgetContext) return;
+    if (!Number.isFinite(amount) || amount <= 0) return;
+    this.budgetContext.totalCost += amount;
+    if (this.budgetContext.totalCost >= this.budgetContext.limit) {
+      this.budgetContext.exceeded = true;
+      if (this.budgetContext.policy === "hard_stop" && this.budgetContext.abortController) {
+        this.budgetContext.abortController.abort();
+      }
+    }
+  }
+  // ── workflow lifecycle trace emission ──────────────────────────────────
+  //
+  // These are called by the runtime at execution boundaries. They emit
+  // first-class `workflow_start` / `workflow_end` trace events instead of
+  // 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 — idempotent; no-ops on second+ call within one ctx. */
+  _emitWorkflowStart(input) {
+    if (this._workflowStartEmitted) return;
+    this._workflowStartEmitted = true;
+    this.emitEvent({
+      type: "workflow_start",
+      workflow: this.workflowName,
+      data: { input }
+    });
+  }
+  /** @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) {
+    if (this._workflowEndEmitted) return;
+    this._workflowEndEmitted = true;
+    this.emitEvent({
+      type: "workflow_end",
+      workflow: this.workflowName,
+      duration: info.duration,
+      data: {
+        status: info.status,
+        duration: info.duration,
+        ...info.result !== void 0 ? { result: info.result } : {},
+        ...info.error !== void 0 ? { error: info.error } : {},
+        ...info.aborted ? { aborted: true } : {}
+      }
+    });
+  }
   // ── ctx.log() ─────────────────────────────────────────────────────────
   log(event, data) {
-    this.emitTrace({
+    this.emitEvent({
       type: "log",
       data: {
         event,
@@ -3766,8 +4834,57 @@ ${summaryResponse.content}`
     if (!this.stateStore) {
       throw new Error("A state store is required for memory operations.");
     }
+    if (this.budgetContext?.exceeded) {
+      const { limit, totalCost: spent, policy } = this.budgetContext;
+      if (policy !== "warn") {
+        throw new BudgetExceededError(limit, spent, policy);
+      }
+    }
     const sessionId = this.metadata?.sessionId;
-    await this.memoryManager.remember(key, value, this.stateStore, sessionId, options);
+    const scope = options?.scope ?? (sessionId ? "session" : "global");
+    try {
+      const memorySignal = this._composeMemorySignal();
+      const { usage } = await this.memoryManager.remember(
+        key,
+        value,
+        this.stateStore,
+        sessionId,
+        options,
+        memorySignal
+      );
+      if (usage?.cost != null) {
+        this._accumulateBudgetCost(usage.cost);
+      }
+      this.emitEvent({
+        type: "memory_remember",
+        ...usage?.cost != null ? { cost: usage.cost } : {},
+        ...usage?.tokens != null ? { tokens: { input: usage.tokens } } : {},
+        data: {
+          key,
+          scope,
+          embed: options?.embed === true,
+          ...usage ? { usage } : {}
+        }
+      });
+    } catch (err) {
+      const partialUsage = err.axlEmbedUsage;
+      if (partialUsage?.cost != null) {
+        this._accumulateBudgetCost(partialUsage.cost);
+      }
+      this.emitEvent({
+        type: "memory_remember",
+        ...partialUsage?.cost != null ? { cost: partialUsage.cost } : {},
+        ...partialUsage?.tokens != null ? { tokens: { input: partialUsage.tokens } } : {},
+        data: {
+          key,
+          scope,
+          embed: options?.embed === true,
+          ...partialUsage ? { usage: partialUsage } : {},
+          error: err instanceof Error ? err.message : String(err)
+        }
+      });
+      throw err;
+    }
   }
   /**
    * Recall a value from memory by key, or perform semantic search if query option is provided.
@@ -3781,8 +4898,62 @@ ${summaryResponse.content}`
     if (!this.stateStore) {
       throw new Error("A state store is required for memory operations.");
     }
+    if (this.budgetContext?.exceeded) {
+      const { limit, totalCost: spent, policy } = this.budgetContext;
+      if (policy !== "warn") {
+        throw new BudgetExceededError(limit, spent, policy);
+      }
+    }
     const sessionId = this.metadata?.sessionId;
-    return this.memoryManager.recall(key, this.stateStore, sessionId, options);
+    const scope = options?.scope ?? (sessionId ? "session" : "global");
+    const semantic = options?.query !== void 0;
+    try {
+      const memorySignal = this._composeMemorySignal();
+      const { data, usage } = await this.memoryManager.recall(
+        key,
+        this.stateStore,
+        sessionId,
+        options,
+        memorySignal
+      );
+      let hit;
+      let resultCount;
+      if (semantic) {
+        resultCount = Array.isArray(data) ? data.length : 0;
+        hit = resultCount > 0;
+      } else {
+        hit = data !== null && data !== void 0;
+      }
+      if (usage?.cost != null) {
+        this._accumulateBudgetCost(usage.cost);
+      }
+      this.emitEvent({
+        type: "memory_recall",
+        ...usage?.cost != null ? { cost: usage.cost } : {},
+        ...usage?.tokens != null ? { tokens: { input: usage.tokens } } : {},
+        data: {
+          key,
+          scope,
+          semantic,
+          hit,
+          ...resultCount !== void 0 ? { resultCount, count: resultCount } : {},
+          ...usage ? { usage } : {}
+        }
+      });
+      return data;
+    } catch (err) {
+      this.emitEvent({
+        type: "memory_recall",
+        data: {
+          key,
+          scope,
+          semantic,
+          hit: false,
+          error: err instanceof Error ? err.message : String(err)
+        }
+      });
+      throw err;
+    }
   }
   /** Delete a memory entry by key. */
   async forget(key, options) {
@@ -3795,7 +4966,24 @@ ${summaryResponse.content}`
       throw new Error("A state store is required for memory operations.");
     }
     const sessionId = this.metadata?.sessionId;
-    await this.memoryManager.forget(key, this.stateStore, sessionId, options);
+    const scope = options?.scope ?? (sessionId ? "session" : "global");
+    try {
+      await this.memoryManager.forget(key, this.stateStore, sessionId, options);
+      this.emitEvent({
+        type: "memory_forget",
+        data: { key, scope }
+      });
+    } catch (err) {
+      this.emitEvent({
+        type: "memory_forget",
+        data: {
+          key,
+          scope,
+          error: err instanceof Error ? err.message : String(err)
+        }
+      });
+      throw err;
+    }
   }
   // ── ctx.delegate() ──────────────────────────────────────────────────
   /**
@@ -3823,6 +5011,15 @@ ${summaryResponse.content}`
       names.add(a._name);
     }
     if (agents.length === 1) {
+      this.emitEvent({
+        type: "delegate",
+        agent: agents[0]._name,
+        data: {
+          candidates: [agents[0]._name],
+          selected: agents[0]._name,
+          reason: "single_candidate"
+        }
+      });
       return this.ask(agents[0], prompt, {
         schema: options?.schema,
         retries: options?.retries,
@@ -3858,12 +5055,13 @@ ${summaryResponse.content}`
       resolveModel: () => routerModelUri,
       resolveSystem: () => routerSystem
     };
-    this.emitTrace({
+    this.emitEvent({
       type: "delegate",
       agent: "_delegate_router",
       data: {
         candidates: agents.map((a) => a._name),
-        routerModel: routerModelUri
+        routerModel: routerModelUri,
+        reason: "routed"
       }
     });
     return this.ask(routerAgent, prompt, {
@@ -3875,24 +5073,57 @@ ${summaryResponse.content}`
     });
   }
   // ── Private ───────────────────────────────────────────────────────────
-  emitTrace(partial) {
-    let data = partial.data;
-    if (this.config.trace?.redact && partial.type === "agent_call" && data) {
-      data = { ...data, prompt: "[redacted]", response: "[redacted]" };
+  /**
+   * Internal emitter input — intentionally loose so call sites don't need to
+   * build a perfectly-narrowed discriminated-union member. The resulting
+   * `AxlEvent` (exported type) remains strict, and TypeScript narrows it at
+   * consumer sites via the `type` discriminator.
+   */
+  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 } : {},
+      // 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
     };
-    this.onTrace?.(event);
+    const finalEvent = this.config.trace?.redact ? redactEvent(event) : event;
+    if (this.onTrace) {
+      try {
+        this.onTrace(finalEvent);
+      } catch (err) {
+        console.error(
+          "[axl] onTrace handler threw; trace event dropped:",
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
   }
 };
 
 // src/agent.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 var agentCounter = 0;
 function agent(config) {
   agentCounter++;
@@ -3912,7 +5143,7 @@ function agent(config) {
       const registry = new ProviderRegistry();
       const ctx = new WorkflowContext({
         input: prompt,
-        executionId: randomUUID(),
+        executionId: randomUUID2(),
         config: {},
         providerRegistry: registry
       });
@@ -3936,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";
@@ -3959,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));
   }
@@ -4154,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 {
@@ -4170,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 (
@@ -4227,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 (
@@ -4242,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(
@@ -4355,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,
@@ -4365,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) {
@@ -4539,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,
@@ -4581,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;
@@ -4605,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);
@@ -4666,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 {
@@ -4691,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 };
             }
           }
         };
@@ -4711,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();
@@ -4724,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);
@@ -4745,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);
@@ -4765,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;
   }
 };
 
@@ -5129,6 +6611,18 @@ var McpManager = class {
 };
 
 // src/memory/manager.ts
+function assertEmbedResult(result) {
+  if (Array.isArray(result)) {
+    throw new Error(
+      "Embedder.embed() returned a bare number[][] (legacy shape). As of @axlsdk/axl 0.15, Embedder.embed() must return { vectors: number[][]; usage?: { tokens?, cost?, model? } }. Wrap your existing return value: `return { vectors: await old() }`."
+    );
+  }
+  if (!result || typeof result !== "object" || !Array.isArray(result.vectors)) {
+    throw new Error(
+      `Embedder.embed() must return { vectors: number[][]; usage?: EmbedUsage }. Got ${result === null ? "null" : typeof result}.`
+    );
+  }
+}
 var MemoryManager = class {
   vectorStore;
   embedder;
@@ -5143,8 +6637,11 @@ var MemoryManager = class {
    * Store a key-value pair in memory.
    * If a vector store and embedder are configured and embed is true,
    * also embeds the value for semantic search.
+   *
+   * Returns `{ usage }` when embedding happened, carrying the embedder's
+   * cost/token reporting out to the caller for cost attribution.
    */
-  async remember(key, value, stateStore, sessionId, options) {
+  async remember(key, value, stateStore, sessionId, options, signal) {
     const scope = options?.scope ?? "session";
     if (scope === "session" && !sessionId) {
       throw new Error(
@@ -5163,23 +6660,44 @@ var MemoryManager = class {
     }
     if (options?.embed === true && this.vectorStore && this.embedder) {
       const text = typeof value === "string" ? value : JSON.stringify(value);
-      const [embedding] = await this.embedder.embed([text]);
-      await this.vectorStore.upsert([
-        {
-          id: `${storeScope}:${key}`,
-          content: text,
-          embedding,
-          metadata: { key, scope, ...options?.metadata }
+      const raw = await this.embedder.embed([text], signal);
+      assertEmbedResult(raw);
+      const { vectors, usage } = raw;
+      try {
+        await this.vectorStore.upsert([
+          {
+            id: `${storeScope}:${key}`,
+            content: text,
+            embedding: vectors[0],
+            metadata: { key, scope, ...options?.metadata }
+          }
+        ]);
+      } catch (err) {
+        if (usage && typeof err === "object" && err !== null) {
+          Object.defineProperty(err, "axlEmbedUsage", {
+            value: usage,
+            enumerable: false,
+            writable: true,
+            configurable: true
+          });
         }
-      ]);
+        throw err;
+      }
+      return usage ? { usage } : {};
     }
+    return {};
   }
   /**
    * Recall a value from memory by key, or perform semantic search if query is provided.
+   *
+   * Always returns `{ data }`; semantic recalls additionally include
+   * `usage` from the embedder (when the embedder reported it).
    */
-  async recall(key, stateStore, sessionId, options) {
+  async recall(key, stateStore, sessionId, options, signal) {
     if (options?.query && this.vectorStore && this.embedder) {
-      const [embedding] = await this.embedder.embed([options.query]);
+      const raw = await this.embedder.embed([options.query], signal);
+      assertEmbedResult(raw);
+      const { vectors, usage } = raw;
       const topK = options?.topK ?? 5;
       const searchScope = options?.scope ?? "session";
       if (searchScope === "session" && !sessionId) {
@@ -5187,13 +6705,14 @@ var MemoryManager = class {
           'sessionId is required for session-scoped memory. Use { scope: "global" } or provide a sessionId in metadata.'
         );
       }
-      const rawResults = await this.vectorStore.search(embedding, topK * 3);
+      const rawResults = await this.vectorStore.search(vectors[0], topK * 3);
       const filtered = rawResults.filter((r) => {
         if (r.id.startsWith("global:")) return true;
         if (searchScope === "session") return r.id.startsWith(`session:${sessionId}:`);
         return true;
       });
-      return filtered.slice(0, topK);
+      const data = filtered.slice(0, topK);
+      return usage ? { data, usage } : { data };
     }
     const scope = options?.scope ?? "session";
     if (scope === "session" && !sessionId) {
@@ -5203,10 +6722,10 @@ var MemoryManager = class {
     }
     const storeScope = scope === "session" ? `session:${sessionId}` : "global";
     if (stateStore.getMemory) {
-      return stateStore.getMemory(storeScope, key);
+      return { data: await stateStore.getMemory(storeScope, key) };
     }
     const storeKey = `memory:${storeScope}:${key}`;
-    return stateStore.getSessionMeta(storeKey, "value");
+    return { data: await stateStore.getSessionMeta(storeKey, "value") };
   }
   /** Delete a memory entry. If a vector store is configured, also removes the embedding. */
   async forget(key, stateStore, sessionId, options) {
@@ -5275,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;
@@ -5294,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,
@@ -5306,6 +6867,22 @@ var AxlRuntime = class extends EventEmitter2 {
       });
     }
   }
+  /**
+   * Whether `config.trace.redact` is enabled on this runtime. A narrow
+   * boolean getter is preferred over exposing the full config because:
+   * (a) `Readonly<AxlConfig>` is shallow so the config would be mutable
+   * at runtime through sub-objects, subverting any compliance guarantee;
+   * (b) observability consumers like Studio only need the boolean, not
+   * the whole config tree; (c) if future observability config needs to
+   * expand, each new flag gets its own narrow getter.
+   *
+   * Studio's server-side redaction helpers (executions, memory, sessions,
+   * evals, decisions, tools, playground, workflows) all route through
+   * this accessor to decide whether to scrub response payloads.
+   */
+  isRedactEnabled() {
+    return this.config.trace?.redact === true;
+  }
   /**
    * Initialize MCP servers configured in the config.
    * Call this before executing workflows that use MCP tools.
@@ -5338,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.
@@ -5353,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);
   }
@@ -5455,10 +7096,19 @@ var AxlRuntime = class extends EventEmitter2 {
           metadata: result2.metadata ?? metadata
         };
       };
-      result = await runEvalFn(entry.config, wrappedExecuteFn, this);
+      result = await runEvalFn(entry.config, wrappedExecuteFn, this, {
+        onProgress: options?.onProgress,
+        signal: options?.signal,
+        captureTraces: options?.captureTraces
+      });
     } else {
       result = await this.eval(
-        entry.config
+        entry.config,
+        {
+          onProgress: options?.onProgress,
+          signal: options?.signal,
+          captureTraces: options?.captureTraces
+        }
       );
     }
     const resultObj = result;
@@ -5470,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)
@@ -5507,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({
@@ -5523,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,
@@ -5553,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);
@@ -5561,7 +7213,7 @@ var AxlRuntime = class extends EventEmitter2 {
       executionId,
       workflow: name,
       status: "running",
-      steps: [],
+      events: [],
       totalCost: 0,
       startedAt: Date.now(),
       duration: 0
@@ -5577,25 +7229,41 @@ 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
             });
           }
         }
       },
       pendingDecisions: this.pendingDecisionResolvers,
+      awaitHumanHandler: options?.awaitHumanHandler,
       stateStore: this.stateStore,
       workflowName: name,
       mcpManager: this.mcpManager,
@@ -5609,7 +7277,6 @@ var AxlRuntime = class extends EventEmitter2 {
         policy: "finish_and_stop"
       }
     });
-    ctx.log("workflow_start", { workflow: name, executionId });
     return this.spanManager.withSpanAsync(
       "axl.workflow.execute",
       {
@@ -5617,39 +7284,13 @@ var AxlRuntime = class extends EventEmitter2 {
         "axl.execution.id": executionId,
         "axl.workflow.input_hash": hashInput(validated)
       },
-      async (span) => {
-        try {
-          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.log("workflow_end", {
-            workflow: name,
-            status: "completed",
-            duration: execInfo.duration,
-            cost: execInfo.totalCost
-          });
-          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) {
-          execInfo.status = "failed";
-          execInfo.completedAt = Date.now();
-          execInfo.duration = execInfo.completedAt - execInfo.startedAt;
-          execInfo.error = err instanceof Error ? err.message : String(err);
-          ctx.log("workflow_end", { workflow: name, status: "failed", error: execInfo.error });
-          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. */
@@ -5657,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
@@ -5685,79 +7325,49 @@ 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 === "tool_denied") {
-            const data = event.data;
-            if (data?.denied === false) {
-              axlStream._push({
-                type: "tool_approval",
-                name: event.tool ?? "",
-                args: data?.args,
-                approved: true
+          } else if (event.type === "handoff_return") {
+            const sessionId = options?.metadata?.sessionId;
+            if (sessionId) {
+              this.updateHandoffDuration(sessionId, {
+                toAskId: event.toAskId,
+                duration: event.data.duration
               });
-            } else {
-              axlStream._push({
-                type: "tool_approval",
-                name: event.tool ?? "",
-                args: data?.args,
-                approved: false,
-                reason: data?.reason ?? void 0
+            }
+          } 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 === "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,
         stateStore: this.stateStore,
         workflowName: name,
         mcpManager: this.mcpManager,
@@ -5771,7 +7381,6 @@ var AxlRuntime = class extends EventEmitter2 {
           policy: "finish_and_stop"
         }
       });
-      ctx = wfCtx;
       return this.spanManager.withSpanAsync(
         "axl.workflow.execute",
         {
@@ -5779,47 +7388,25 @@ var AxlRuntime = class extends EventEmitter2 {
           "axl.execution.id": executionId,
           "axl.workflow.input_hash": hashInput(validated)
         },
-        async (span) => {
-          try {
-            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.log("workflow_end", {
-              workflow: name,
-              status: "completed",
-              duration: execInfo.duration,
-              cost: execInfo.totalCost
-            });
-            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) {
+    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?.log("workflow_end", {
-          workflow: name,
-          status: "failed",
-          error: execInfo.error
-        });
         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;
   }
@@ -5880,6 +7467,7 @@ var AxlRuntime = class extends EventEmitter2 {
     if (this.stateStore.saveEvalResult) {
       await this.stateStore.saveEvalResult(entry);
     }
+    this.emit("eval_result", entry);
   }
   /**
    * Delete an eval history entry by id. Removes from in-memory cache and
@@ -6011,7 +7599,7 @@ var AxlRuntime = class extends EventEmitter2 {
    *
    * @see Spec Section 13.5
    */
-  async eval(config) {
+  async eval(config, options) {
     let runEvalFn;
     try {
       ({ runEval: runEvalFn } = await import("@axlsdk/eval"));
@@ -6026,7 +7614,7 @@ var AxlRuntime = class extends EventEmitter2 {
       });
       return { output: result, cost, metadata };
     };
-    return runEvalFn(config, executeWorkflow, this);
+    return runEvalFn(config, executeWorkflow, this, options);
   }
   /**
    * Compare two evaluation results to detect regressions and improvements.
@@ -6064,9 +7652,31 @@ var AxlRuntime = class extends EventEmitter2 {
    * Returns cost (same as `trackCost`) plus metadata extracted from trace events:
    * models (unique URIs), tokens (input/output/reasoning sums), and agent call count.
    *
+   * ## Cost vs tokens semantics
+   *
+   * - `cost` is the full aggregate across EVERY event with a top-level
+   *   `event.cost` set: agent calls, tool calls, semantic memory ops, etc.
+   *   This is the number to reconcile against your provider bill.
+   *
+   * - `metadata.tokens` is narrowly scoped to **agent** prompt/completion/
+   *   reasoning tokens. Embedder tokens from semantic `ctx.remember({embed:true})`
+   *   / `ctx.recall({query})` are deliberately NOT summed here — they're a
+   *   different category (input-only, different pricing, different model).
+   *   Conflating them would make "prompt tokens" misleading in the UI. If you
+   *   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 `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_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.
+   *
    * Works with both `createContext()` and `execute()` calls inside `fn`.
    */
-  async trackExecution(fn) {
+  async trackExecution(fn, options) {
     const parentScope = costScopeStorage.getStore();
     const scope = {
       totalCost: 0,
@@ -6077,10 +7687,11 @@ var AxlRuntime = class extends EventEmitter2 {
     const workflowCalls = /* @__PURE__ */ new Map();
     const tokens = { input: 0, output: 0, reasoning: 0 };
     let agentCalls = 0;
+    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) {
@@ -6089,17 +7700,23 @@ var AxlRuntime = class extends EventEmitter2 {
           tokens.reasoning += event.tokens.reasoning ?? 0;
         }
       }
-      let workflowName;
       if (event.type === "workflow_start" && event.workflow) {
-        workflowName = event.workflow;
-      } else if (event.type === "log" && event.data && typeof event.data === "object") {
-        const d = event.data;
-        if (d.event === "workflow_start" && typeof d.workflow === "string") {
-          workflowName = d.workflow;
-        }
+        workflowCalls.set(event.workflow, (workflowCalls.get(event.workflow) ?? 0) + 1);
       }
-      if (workflowName) {
-        workflowCalls.set(workflowName, (workflowCalls.get(workflowName) ?? 0) + 1);
+      if (capturedTraces) {
+        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 = {};
+            for (const k of Object.keys(d)) {
+              if (k !== "messages") rest[k] = d[k];
+            }
+            capturedTraces.push({ ...event, data: rest });
+            return;
+          }
+        }
+        capturedTraces.push(event);
       }
     };
     this.setMaxListeners(this.getMaxListeners() + 1);
@@ -6109,6 +7726,7 @@ var AxlRuntime = class extends EventEmitter2 {
       return {
         result,
         cost: scope.totalCost,
+        ...capturedTraces ? { traces: capturedTraces } : {},
         metadata: {
           models: [...modelCalls.keys()],
           modelCallCounts: modelCalls.size > 0 ? Object.fromEntries(modelCalls) : void 0,
@@ -6118,6 +7736,16 @@ var AxlRuntime = class extends EventEmitter2 {
           workflowCallCounts: workflowCalls.size > 0 ? Object.fromEntries(workflowCalls) : void 0
         }
       };
+    } catch (err) {
+      if (capturedTraces && typeof err === "object" && err !== null) {
+        Object.defineProperty(err, "axlCapturedTraces", {
+          value: capturedTraces,
+          enumerable: false,
+          writable: true,
+          configurable: true
+        });
+      }
+      throw err;
     } finally {
       this.off("trace", listener);
       this.setMaxListeners(this.getMaxListeners() - 1);
@@ -6142,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";
@@ -6166,18 +7794,20 @@ 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}`];
-    const data = event.data;
     if (event.type === "workflow_start") {
-      parts.push(`${workflowPrefix}workflow:${data?.workflow ?? "unknown"} | started`);
+      parts.push(`${workflowPrefix}started`);
     } else if (event.type === "workflow_end") {
-      parts.push(`${workflowPrefix}workflow:${data?.workflow ?? "unknown"} | completed`);
-    } else if (event.type === "agent_call") {
+      const d = event.data;
+      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_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}`);
@@ -6187,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`);
@@ -6204,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(" | "));
@@ -6225,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
@@ -6287,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));
@@ -6412,6 +8058,16 @@ var RedisStore = class _RedisStore {
 };
 
 // src/memory/embedder-openai.ts
+var EMBEDDING_PRICE_PER_1M_TOKENS = {
+  "text-embedding-3-small": 0.02,
+  "text-embedding-3-large": 0.13,
+  "text-embedding-ada-002": 0.1
+};
+function computeCost(model, tokens) {
+  const pricePerMillion = EMBEDDING_PRICE_PER_1M_TOKENS[model];
+  if (pricePerMillion == null) return void 0;
+  return tokens / 1e6 * pricePerMillion;
+}
 var OpenAIEmbedder = class {
   apiKey;
   model;
@@ -6426,8 +8082,8 @@ var OpenAIEmbedder = class {
     this.baseUrl = options.baseUrl ?? "https://api.openai.com";
     this.dimensions = options.dimensions ?? 1536;
   }
-  async embed(texts) {
-    const response = await fetch(`${this.baseUrl}/v1/embeddings`, {
+  async embed(texts, signal) {
+    const response = await fetchWithRetry(`${this.baseUrl}/v1/embeddings`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -6437,14 +8093,28 @@ var OpenAIEmbedder = class {
         model: this.model,
         input: texts,
         dimensions: this.dimensions
-      })
+      }),
+      signal
     });
     if (!response.ok) {
       const body = await response.text();
       throw new Error(`OpenAI embeddings API error (${response.status}): ${body}`);
     }
     const json = await response.json();
-    return json.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+    const vectors = json.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+    const tokens = json.usage?.prompt_tokens ?? json.usage?.total_tokens;
+    const cost = tokens != null ? computeCost(this.model, tokens) : void 0;
+    if (tokens == null && cost == null) {
+      return { vectors };
+    }
+    return {
+      vectors,
+      usage: {
+        ...tokens != null ? { tokens } : {},
+        ...cost != null ? { cost } : {},
+        model: this.model
+      }
+    };
   }
 };
 
@@ -6568,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,
@@ -6587,6 +8259,8 @@ export {
   OpenAIResponsesProvider,
   ProviderRegistry,
   QuorumNotMet,
+  REDACTED,
+  REDACTION_RULES,
   RedisStore,
   SQLiteStore,
   Session,
@@ -6599,7 +8273,12 @@ export {
   agent,
   createSpanManager,
   defineConfig,
+  eventCostContribution,
   extractJson,
+  isCostBearingLeaf,
+  isRootLevel,
+  parsePartialJson,
+  redactEvent,
   resolveThinkingOptions,
   tool,
   workflow,