@axlsdk/axl 0.17.3 → 0.17.5

package/dist/index.js

@@ -2337,6 +2337,314 @@ var PartialParser = class {
   }
 };
 
+// src/streaming-walker.ts
+var MAX_DEPTH2 = 256;
+function encodeSegment(s) {
+  if (typeof s === "number") return String(s);
+  return s.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function computePath(stack) {
+  let path = "";
+  for (const frame of stack) {
+    if (frame.type === "object") {
+      path += "/" + encodeSegment(frame.currentKey ?? "");
+    } else {
+      path += "/" + encodeSegment(frame.currentIndex);
+    }
+  }
+  return path;
+}
+var StreamingWalker = class {
+  constructor(callbacks) {
+    this.callbacks = callbacks;
+  }
+  state = "pre-json";
+  stack = [];
+  // String parsing state — survives across chunks so escapes can split.
+  escaped = false;
+  /** When > 0, we're collecting `\\uXXXX` hex digits. 4→0 as digits arrive. */
+  unicodePending = 0;
+  /** Accumulator for `\\uXXXX` digits. Cleared when the escape resolves. */
+  unicodeBuf = "";
+  // Per-string accumulators.
+  keyBuf = "";
+  deltaBuf = "";
+  /** Cached JSON Pointer to the value currently being read. Recomputed
+   *  on entry to `read-value-string` (the only state that needs it). */
+  currentPath = "";
+  /** Set true when a structural boundary lands. Caller reads via
+   *  `consumeBoundary()` after each chunk to decide on partial_object emit. */
+  boundaryPending = false;
+  /** Walk `text` char-by-char, advancing state and accumulating deltas.
+   *  Calls `onStringDelta` at end-of-chunk for any pending value text. */
+  processChunk(text) {
+    for (let i = 0; i < text.length; i++) {
+      if (this.state === "done") return;
+      this.processChar(text[i]);
+    }
+    if (this.deltaBuf.length > 0 && this.state === "read-value-string") {
+      this.callbacks.onStringDelta?.(this.currentPath, this.deltaBuf);
+      this.deltaBuf = "";
+    }
+  }
+  /** Read-and-clear the structural-boundary flag. Caller checks this
+   *  after `processChunk` to decide whether to emit `partial_object`. */
+  consumeBoundary() {
+    const v = this.boundaryPending;
+    this.boundaryPending = false;
+    return v;
+  }
+  /** True when the walker has decided it's done with this stream
+   *  (root closed or fatal malformed input). Caller may use this to
+   *  short-circuit further work. */
+  get isDone() {
+    return this.state === "done";
+  }
+  // ── Per-char dispatch ───────────────────────────────────────────────────
+  processChar(ch) {
+    switch (this.state) {
+      case "pre-json":
+        if (ch === "{") {
+          if (!this.pushFrame({ type: "object" })) return;
+          this.state = "expect-key-or-close";
+        }
+        return;
+      case "expect-key-or-close":
+        if (isWhitespace(ch)) return;
+        if (ch === "}") {
+          this.popFrame();
+          return;
+        }
+        if (ch === '"') {
+          this.keyBuf = "";
+          this.escaped = false;
+          this.unicodePending = 0;
+          this.unicodeBuf = "";
+          this.state = "read-key";
+          return;
+        }
+        this.state = "done";
+        return;
+      case "read-key":
+        this.processStringChar(
+          ch,
+          /* isValue */
+          false
+        );
+        return;
+      case "expect-colon":
+        if (isWhitespace(ch)) return;
+        if (ch === ":") {
+          this.state = "expect-value";
+          return;
+        }
+        this.state = "done";
+        return;
+      case "expect-value":
+        if (isWhitespace(ch)) return;
+        if (ch === "{") {
+          if (!this.pushFrame({ type: "object" })) return;
+          this.state = "expect-key-or-close";
+          return;
+        }
+        if (ch === "[") {
+          if (!this.pushFrame({ type: "array", currentIndex: 0 })) return;
+          this.state = "expect-value";
+          return;
+        }
+        if (ch === "]") {
+          this.popFrame();
+          return;
+        }
+        if (ch === '"') {
+          this.currentPath = computePath(this.stack);
+          this.deltaBuf = "";
+          this.escaped = false;
+          this.unicodePending = 0;
+          this.unicodeBuf = "";
+          this.state = "read-value-string";
+          return;
+        }
+        if (isValueStartChar(ch)) {
+          this.state = "read-value-other";
+          return;
+        }
+        this.state = "done";
+        return;
+      case "read-value-string":
+        this.processStringChar(
+          ch,
+          /* isValue */
+          true
+        );
+        return;
+      case "read-value-other":
+        if (ch === "," || ch === "}" || ch === "]" || isWhitespace(ch)) {
+          this.state = "expect-comma-close";
+          this.processChar(ch);
+          return;
+        }
+        return;
+      case "expect-comma-close":
+        if (isWhitespace(ch)) return;
+        if (ch === ",") {
+          this.boundaryPending = true;
+          const top = this.stack[this.stack.length - 1];
+          if (!top) {
+            this.state = "done";
+            return;
+          }
+          if (top.type === "object") {
+            top.currentKey = void 0;
+            this.state = "expect-key-or-close";
+          } else {
+            top.currentIndex += 1;
+            this.state = "expect-value";
+          }
+          return;
+        }
+        if (ch === "}" || ch === "]") {
+          this.popFrame();
+          return;
+        }
+        this.state = "done";
+        return;
+      case "done":
+        return;
+    }
+  }
+  // ── String state machine (shared between key and value reads) ───────────
+  /**
+   * One char inside a string. Translates JSON escapes, accumulates
+   * `\\uXXXX` digits across chunks, and routes the resolved char to
+   * either `keyBuf` (when reading a key) or `deltaBuf` (when reading a
+   * value).
+   */
+  processStringChar(ch, isValue) {
+    if (this.unicodePending > 0) {
+      if (isHex(ch)) {
+        this.unicodeBuf += ch;
+        this.unicodePending -= 1;
+        if (this.unicodePending === 0) {
+          const code = parseInt(this.unicodeBuf, 16);
+          this.unicodeBuf = "";
+          this.appendChar(String.fromCharCode(code), isValue);
+        }
+      } else {
+        this.state = "done";
+      }
+      return;
+    }
+    if (this.escaped) {
+      this.escaped = false;
+      switch (ch) {
+        case '"':
+          this.appendChar('"', isValue);
+          return;
+        case "\\":
+          this.appendChar("\\", isValue);
+          return;
+        case "/":
+          this.appendChar("/", isValue);
+          return;
+        case "b":
+          this.appendChar("\b", isValue);
+          return;
+        case "f":
+          this.appendChar("\f", isValue);
+          return;
+        case "n":
+          this.appendChar("\n", isValue);
+          return;
+        case "r":
+          this.appendChar("\r", isValue);
+          return;
+        case "t":
+          this.appendChar("	", isValue);
+          return;
+        case "u":
+          this.unicodePending = 4;
+          this.unicodeBuf = "";
+          return;
+        default:
+          this.state = "done";
+          return;
+      }
+    }
+    if (ch === "\\") {
+      this.escaped = true;
+      return;
+    }
+    if (ch === '"') {
+      if (isValue) {
+        if (this.deltaBuf.length > 0) {
+          this.callbacks.onStringDelta?.(this.currentPath, this.deltaBuf);
+          this.deltaBuf = "";
+        }
+        this.state = "expect-comma-close";
+      } else {
+        const top = this.stack[this.stack.length - 1];
+        if (!top || top.type !== "object") {
+          this.state = "done";
+          return;
+        }
+        top.currentKey = this.keyBuf;
+        this.keyBuf = "";
+        this.state = "expect-colon";
+      }
+      return;
+    }
+    this.appendChar(ch, isValue);
+  }
+  appendChar(c, isValue) {
+    if (isValue) {
+      this.deltaBuf += c;
+    } else {
+      this.keyBuf += c;
+    }
+  }
+  // ── Frame stack ─────────────────────────────────────────────────────────
+  /** Push a frame onto the stack. Returns false if the stack is at the
+   *  depth cap — in which case the walker is also moved to `done` so the
+   *  caller's subsequent state assignment must be guarded. */
+  pushFrame(frame) {
+    if (this.stack.length >= MAX_DEPTH2) {
+      this.state = "done";
+      return false;
+    }
+    this.stack.push(frame);
+    return true;
+  }
+  /** Pop a frame on `}` or `]`, fire boundary, transition to next state.
+   *  Defensive on empty stack — the state machine never invokes this
+   *  without an enclosing container today (callers gate on state, and
+   *  state transitions out of `pre-json` / `done` only after pushing),
+   *  but a future state-machine bug could land us here with nothing to
+   *  pop. Fail closed (move to `done`, no spurious boundary fire). */
+  popFrame() {
+    if (this.stack.length === 0) {
+      this.state = "done";
+      return;
+    }
+    this.stack.pop();
+    this.boundaryPending = true;
+    if (this.stack.length === 0) {
+      this.state = "done";
+    } else {
+      this.state = "expect-comma-close";
+    }
+  }
+};
+function isWhitespace(ch) {
+  return ch === " " || ch === "	" || ch === "\n" || ch === "\r";
+}
+function isHex(ch) {
+  return ch >= "0" && ch <= "9" || ch >= "a" && ch <= "f" || ch >= "A" && ch <= "F";
+}
+function isValueStartChar(ch) {
+  return ch === "-" || ch >= "0" && ch <= "9" || ch === "t" || ch === "f" || ch === "n";
+}
+
 // src/event-utils.ts
 var COST_BEARING_LEAF_TYPES = [
   "agent_call_end",
@@ -2393,6 +2701,12 @@ var AXL_EVENT_TYPES = [
   "pipeline",
   // Progressive structured output — added in PR 2; reserved here.
   "partial_object",
+  // Character-level deltas inside string values of progressive structured
+  // output. Same gating as `partial_object` (schema set, no tools, root is
+  // ZodObject); fires per text-delta chunk when the walker is inside a
+  // string value at a known JSON Pointer path. Designed for chat-style
+  // typewriter rendering of long string fields.
+  "string_delta",
   // Verification
   "verify",
   // Observability
@@ -2490,6 +2804,27 @@ var AxlEventBus = class {
    * number of distinct askIds that emitted at least one partial.
    */
   latestPartialByAsk = /* @__PURE__ */ new Map();
+  /**
+   * Per-ask, per-path running accumulator for `string_delta` events,
+   * updated on every `_push(string_delta)` regardless of consumer state.
+   * Used to seed late `stringStream` subscribers with the current text-
+   * so-far per (askId, path) pair, so a UI binding to `/summary` mid-
+   * stream renders the field's current state on first event instead of
+   * waiting for the next chunk.
+   *
+   * Cleared per-askId on `pipeline(failed)` (discarded attempt — old
+   * deltas must not leak into the next attempt's view) and on `ask_end`
+   * (frees memory; stream-event accumulators don't outlive the ask).
+   *
+   * Memory bound: O(active asks × distinct paths × total chars per
+   * field). For typical chat workflows (1 ask, 1-3 streaming string
+   * fields) this is a few KB. The clear-on-`ask_end` cap keeps a
+   * long-running runtime from accumulating per-ask entries forever
+   * (the way `latestPartialByAsk` does — partial snapshots are tiny by
+   * comparison so that map's growth is acceptable; string accumulators
+   * can be 4 KB+ each, hence the more aggressive cleanup here).
+   */
+  stringStreamByAsk = /* @__PURE__ */ new Map();
   /**
    * Hook fired when an iterator obtained from `[Symbol.asyncIterator]`
    * is `await using`-disposed. Set via the second constructor argument.
@@ -2793,6 +3128,141 @@ var AxlEventBus = class {
       }
     };
   }
+  /**
+   * Listener-based view over `string_delta` events with optional
+   * filtering by `path` and/or `askId`. Yields `StringStreamEvent`s
+   * carrying `delta` (the new chars) and `accumulated` (the full text-
+   * so-far for that ask + path).
+   *
+   * Designed for chat-style typewriter rendering of long string fields:
+   * a React component binding to `path: '/summary'` sets its text to
+   * `event.accumulated` on every yield, getting smooth char-by-char
+   * progression with no parser of its own.
+   *
+   * Late-subscriber seeding: at subscribe time, the bus's per-ask
+   * accumulator is walked and one synthetic `StringStreamEvent` is
+   * yielded per matching (askId, path) entry, with `delta ===
+   * accumulated === <full text-so-far>`. After that, live deltas flow
+   * normally. A consumer who attaches mid-ask sees the field's current
+   * state on first iteration, then incremental updates.
+   *
+   * Like `partialObjects`, this view is listener-based — it does NOT
+   * race the main async iterator (`for await (const e of bus)`).
+   * Running both concurrently each receives every matching event.
+   *
+   * Schema-retry awareness: on `pipeline(status: 'failed')`, the
+   * accumulator and any pending events for the affected ask are
+   * dropped, so a consumer iterating during attempt-N never observes
+   * stale text after attempt-N+1 begins. Mirrors `partialObjects`'
+   * per-attempt reset.
+   *
+   * Termination: yields any pending events first (live + seeded), then
+   * `done: true` once the bus is finished via `_finish()`.
+   */
+  stringStream(opts) {
+    const self = this;
+    const filterPath = opts?.path;
+    const filterAskId = opts?.askId;
+    if (filterPath !== void 0 && filterPath !== "" && !filterPath.startsWith("/")) {
+      throw new Error(
+        `AxlEventBus.stringStream({ path }) \u2014 path must start with '/' (RFC 6901 JSON Pointer); got ${JSON.stringify(filterPath)}. Examples: '/summary', '/sources/0/title'.`
+      );
+    }
+    return {
+      [Symbol.asyncIterator]() {
+        const pending = [];
+        let resolveWaiter = null;
+        let finished = self.finished;
+        let unsubscribed = false;
+        const wakeWaiter = () => {
+          const r = resolveWaiter;
+          resolveWaiter = null;
+          r?.();
+        };
+        const matchesFilter = (askId, path) => {
+          if (filterAskId !== void 0 && askId !== filterAskId) return false;
+          if (filterPath !== void 0 && path !== filterPath) return false;
+          return true;
+        };
+        for (const [askId, paths] of self.stringStreamByAsk) {
+          for (const [path, acc] of paths) {
+            if (!matchesFilter(askId, path)) continue;
+            pending.push({
+              askId,
+              agent: acc.agent,
+              path,
+              delta: acc.text,
+              accumulated: acc.text,
+              attempt: acc.attempt
+            });
+          }
+        }
+        const handler = (event) => {
+          if (event.type !== "string_delta") return;
+          const askId = event.askId ?? "";
+          if (!matchesFilter(askId, event.data.path)) return;
+          const paths = self.stringStreamByAsk.get(askId);
+          const acc = paths?.get(event.data.path);
+          const accumulated = acc?.text ?? event.data.delta;
+          pending.push({
+            askId,
+            agent: event.agent,
+            path: event.data.path,
+            delta: event.data.delta,
+            accumulated,
+            attempt: event.attempt
+          });
+          wakeWaiter();
+        };
+        self.bus.on("string_delta", handler);
+        const pipelineHandler = (event) => {
+          if (event.type !== "pipeline") return;
+          if (event.status !== "failed") return;
+          const askId = event.askId ?? "";
+          for (let i = pending.length - 1; i >= 0; i--) {
+            if (pending[i].askId === askId) pending.splice(i, 1);
+          }
+        };
+        self.bus.on("pipeline", pipelineHandler);
+        const unsubscribe = () => {
+          if (unsubscribed) return;
+          unsubscribed = true;
+          self.bus.off("string_delta", handler);
+          self.bus.off("pipeline", pipelineHandler);
+          unsubscribeFinish();
+        };
+        const unsubscribeFinish = self._onFinish(() => {
+          finished = true;
+          self.bus.off("string_delta", handler);
+          self.bus.off("pipeline", pipelineHandler);
+          wakeWaiter();
+        });
+        return {
+          async next() {
+            while (true) {
+              if (pending.length > 0) {
+                return { value: pending.shift(), done: false };
+              }
+              if (finished) {
+                unsubscribe();
+                return { value: void 0, done: true };
+              }
+              await new Promise((res) => {
+                resolveWaiter = res;
+              });
+            }
+          },
+          async return() {
+            unsubscribe();
+            return { value: void 0, done: true };
+          },
+          [Symbol.asyncIterator]() {
+            return this;
+          }
+        };
+      }
+    };
+  }
   /** 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. */
@@ -2829,14 +3299,6 @@ var AxlEventBus = class {
    */
   _push(event) {
     if (this.finished) return;
-    try {
-      this.bus.emit(event.type, event);
-    } catch (err) {
-      console.error(
-        `[axl] AxlEventBus listener for "${event.type}" threw; ignoring:`,
-        err instanceof Error ? err.message : String(err)
-      );
-    }
     if (event.type === "partial_object" && event.data?.object !== void 0) {
       const askId = event.askId ?? "";
       this.latestPartialByAsk.set(askId, {
@@ -2845,8 +3307,33 @@ var AxlEventBus = class {
         object: event.data.object,
         attempt: event.attempt
       });
+    } else if (event.type === "string_delta") {
+      const askId = event.askId ?? "";
+      let paths = this.stringStreamByAsk.get(askId);
+      if (!paths) {
+        paths = /* @__PURE__ */ new Map();
+        this.stringStreamByAsk.set(askId, paths);
+      }
+      const existing = paths.get(event.data.path);
+      paths.set(event.data.path, {
+        agent: event.agent,
+        text: (existing?.text ?? "") + event.data.delta,
+        attempt: event.attempt
+      });
     } else if (event.type === "pipeline" && event.status === "failed") {
-      this.latestPartialByAsk.delete(event.askId ?? "");
+      const askId = event.askId ?? "";
+      this.latestPartialByAsk.delete(askId);
+      this.stringStreamByAsk.delete(askId);
+    } else if (event.type === "ask_end") {
+      this.stringStreamByAsk.delete(event.askId ?? "");
+    }
+    try {
+      this.bus.emit(event.type, event);
+    } catch (err) {
+      console.error(
+        `[axl] AxlEventBus listener for "${event.type}" threw; ignoring:`,
+        err instanceof Error ? err.message : String(err)
+      );
     }
     const waiter = this.waiters.shift();
     if (waiter) {
@@ -3064,6 +3551,9 @@ var REDACTION_RULES = {
   handoff_return: passthrough,
   pipeline: (e) => e.status === "failed" ? { ...e, reason: REDACTED } : e,
   partial_object: (e) => ({ ...e, data: { ...e.data, object: REDACTED } }),
+  // `path` is structural (schema-shape, no PII); `delta` is user content.
+  // Scrub only the delta — preserving path keeps "which fields stream" telemetry.
+  string_delta: (e) => ({ ...e, data: { ...e.data, delta: 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;
@@ -3907,36 +4397,26 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
           const toolCallBuffers = /* @__PURE__ */ new Map();
           let streamProviderMetadata;
           let thinkingContent = "";
-          const partialObjectEnabled = !!options?.schema && toolDefs.length === 0 && options.schema instanceof z.ZodObject;
+          const streamingObjectEnabled = !!options?.schema && toolDefs.length === 0 && options.schema instanceof z.ZodObject;
           const currentAttempt = schemaRetries + 1;
-          let inString = false;
-          let escaped = false;
-          let boundaryPending = false;
+          const walker = streamingObjectEnabled ? new StreamingWalker({
+            onStringDelta: (path, delta) => {
+              this.emitEvent({
+                type: "string_delta",
+                agent: agent2._name,
+                attempt: currentAttempt,
+                data: { path, delta }
+              });
+            }
+          }) : void 0;
           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;
+              if (walker) {
+                walker.processChunk(chunk.content);
+                if (walker.consumeBoundary()) {
                   let parsed;
                   try {
                     parsed = parsePartialJson(extractJson(content2));
@@ -6745,6 +7225,20 @@ var AxlStream = class extends Readable {
   get partialObjects() {
     return this.events.partialObjects;
   }
+  /** Listener-based view over `string_delta` events, with optional filter
+   *  on `path` and/or `askId`. Yields `StringStreamEvent`s carrying the new
+   *  `delta` and full text-so-far `accumulated`. Designed for chat-style
+   *  typewriter rendering of long string fields — bind a UI component to
+   *  one path and set its text to `event.accumulated` per yield.
+   *
+   *  Late subscribers receive a synthetic event seeded from the bus's
+   *  per-ask accumulator (so the field's current state renders on the
+   *  first iteration, not after the next char arrives). Doesn't race the
+   *  main async iterator. See `AxlEventBus.stringStream` for full
+   *  semantics. */
+  stringStream(opts) {
+    return this.events.stringStream(opts);
+  }
   pipe(destination, options) {
     const shouldEnd = options?.end !== false;
     this.events.on("token", (event) => {
@@ -7404,8 +7898,8 @@ async function createSpanManager(config) {
   if (!config?.enabled) {
     return new NoopSpanManager();
   }
-  const { OTelSpanManager: OTelSpanManager2 } = await import("./span-manager-3IKXXUTZ.js");
-  return OTelSpanManager2.create(config);
+  const { OTelSpanManager } = await import("./span-manager-3IKXXUTZ.js");
+  return OTelSpanManager.create(config);
 }
 
 // src/runtime.ts
@@ -7485,6 +7979,10 @@ var AxlRuntime = class extends EventEmitter2 {
    *  the instance so per-event onTrace handlers don't reach into
    *  `this.config.state` on every emission. */
   maxEventsPerExecution;
+  /** Tracks executionIds for which we've already warned about a malformed
+   *  `events` field — keeps the log to one line per row instead of one per
+   *  rebuild tick. */
+  warnedMalformedExecutions = /* @__PURE__ */ new Set();
   constructor(config) {
     super();
     this.config = resolveConfig(config ?? {});
@@ -7778,12 +8276,31 @@ var AxlRuntime = class extends EventEmitter2 {
     return result;
   }
   /** Get all execution info (running + completed + historical). */
+  /** Normalize an `ExecutionInfo` loaded from a `StateStore` so the
+   *  `events: AxlEvent[]` type contract holds for downstream consumers
+   *  (Studio aggregators, REST routes, redaction). Custom or legacy stores
+   *  may persist rows without `events` (or with a non-array value) — without
+   *  this guard, a single malformed row crashes every iterator over
+   *  `exec.events` and takes down dependent features. Mutates the row
+   *  in place; logs at most one warning per `executionId`. */
+  normalizeStoredExecution(exec) {
+    if (!Array.isArray(exec.events)) {
+      if (!this.warnedMalformedExecutions.has(exec.executionId)) {
+        this.warnedMalformedExecutions.add(exec.executionId);
+        console.warn(
+          `[axl] StateStore returned execution ${exec.executionId} with non-array events (got ${exec.events === null ? "null" : typeof exec.events}); coercing to []`
+        );
+      }
+      exec.events = [];
+    }
+    return exec;
+  }
   async getExecutions() {
     if (!this.historicalExecutionsLoadPromise && this.stateStore.listExecutions) {
       this.historicalExecutionsLoadPromise = this.stateStore.listExecutions().then((stored) => {
         for (const exec of stored) {
           if (!this.executions.has(exec.executionId) && !this.historicalExecutions.has(exec.executionId)) {
-            this.historicalExecutions.set(exec.executionId, exec);
+            this.historicalExecutions.set(exec.executionId, this.normalizeStoredExecution(exec));
           }
         }
       }).catch(() => {
@@ -8154,8 +8671,9 @@ var AxlRuntime = class extends EventEmitter2 {
     if (this.stateStore.getExecution) {
       const stored = await this.stateStore.getExecution(executionId);
       if (stored) {
-        this.historicalExecutions.set(executionId, stored);
-        return stored;
+        const normalized = this.normalizeStoredExecution(stored);
+        this.historicalExecutions.set(executionId, normalized);
+        return normalized;
       }
     }
     return void 0;
@@ -8403,7 +8921,9 @@ var AxlRuntime = class extends EventEmitter2 {
         workflowCalls.set(event.workflow, (workflowCalls.get(event.workflow) ?? 0) + 1);
       }
       if (capturedTraces) {
-        if (event.type === "token" || event.type === "partial_object") return;
+        if (event.type === "token" || event.type === "partial_object" || event.type === "string_delta") {
+          return;
+        }
         if (event.type === "agent_call_start" && event.data) {
           const d = event.data;
           if ("messages" in d) {
@@ -8727,6 +9247,49 @@ async function registerConditions(conditions) {
   }
 }
 
+// src/string-stream-from-events.ts
+async function* stringStreamFromEvents(source, opts) {
+  const filterPath = opts?.path;
+  const filterAskId = opts?.askId;
+  if (filterPath !== void 0 && filterPath !== "" && !filterPath.startsWith("/")) {
+    throw new Error(
+      `stringStreamFromEvents({ path }) \u2014 path must start with '/' (RFC 6901 JSON Pointer); got ${JSON.stringify(filterPath)}. Examples: '/summary', '/sources/0/title'.`
+    );
+  }
+  const acc = /* @__PURE__ */ new Map();
+  for await (const event of source) {
+    if (event.type === "string_delta") {
+      const askId = event.askId ?? "";
+      let paths = acc.get(askId);
+      if (!paths) {
+        paths = /* @__PURE__ */ new Map();
+        acc.set(askId, paths);
+      }
+      const existing = paths.get(event.data.path);
+      const accumulated = (existing?.text ?? "") + event.data.delta;
+      paths.set(event.data.path, {
+        agent: event.agent,
+        text: accumulated,
+        attempt: event.attempt
+      });
+      if (filterAskId !== void 0 && askId !== filterAskId) continue;
+      if (filterPath !== void 0 && event.data.path !== filterPath) continue;
+      yield {
+        askId,
+        agent: event.agent,
+        path: event.data.path,
+        delta: event.data.delta,
+        accumulated,
+        attempt: event.attempt
+      };
+    } else if (event.type === "pipeline" && event.status === "failed") {
+      acc.delete(event.askId ?? "");
+    } else if (event.type === "ask_end") {
+      acc.delete(event.askId ?? "");
+    }
+  }
+}
+
 // src/state/redis.ts
 var RedisStore = class _RedisStore {
   constructor(client) {
@@ -9131,6 +9694,7 @@ export {
   registerConditions,
   resolveRuntime,
   resolveThinkingOptions,
+  stringStreamFromEvents,
   tool,
   workflow,
   zodToJsonSchema