@axlsdk/axl 0.17.3 → 0.17.5

package/dist/index.d.cts

@@ -279,7 +279,7 @@ type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
  * derive `AxlEventType` from this tuple and use it to validate stream filters,
  * redaction tables, and exhaustiveness assertions.
  */
-declare const AXL_EVENT_TYPES: readonly ["workflow_start", "workflow_end", "ask_start", "ask_end", "agent_call_start", "agent_call_end", "token", "tool_call_start", "tool_call_end", "tool_approval", "tool_denied", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "verify", "log", "memory_remember", "memory_recall", "memory_forget", "checkpoint_save", "checkpoint_replay", "await_human", "await_human_resolved", "guardrail", "schema_check", "validate", "done", "error"];
+declare const AXL_EVENT_TYPES: readonly ["workflow_start", "workflow_end", "ask_start", "ask_end", "agent_call_start", "agent_call_end", "token", "tool_call_start", "tool_call_end", "tool_approval", "tool_denied", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "string_delta", "verify", "log", "memory_remember", "memory_recall", "memory_forget", "checkpoint_save", "checkpoint_replay", "await_human", "await_human_resolved", "guardrail", "schema_check", "validate", "done", "error"];
 /** Discriminator union derived from `AXL_EVENT_TYPES`. */
 type AxlEventType = (typeof AXL_EVENT_TYPES)[number];
 /** Resolved model parameters sent to the provider for an LLM call. */
@@ -396,6 +396,39 @@ type VerifyData = {
     passed: boolean;
     lastError?: string;
 };
+/**
+ * Data shape for `string_delta` events.
+ *
+ * Emitted while the streaming walker is inside a string VALUE (not a key)
+ * during a schema-mode response. Each event carries the unescaped chars
+ * appended within a single text-delta chunk for one path; consumers
+ * concatenate `delta` per (`askId`, `path`) to reconstruct the running text.
+ *
+ * Splitting an escape sequence across chunks is supported — the walker
+ * holds escape state across chunks, so a `\\u00` in chunk N and `41` in
+ * chunk N+1 produces a single `A` in the chunk-N+1 delta.
+ */
+type StringDeltaData = {
+    /**
+     * RFC 6901 JSON Pointer to the string value. Examples:
+     *   - `/summary` (root-level field)
+     *   - `/sources/0/title` (nested through array)
+     *   - keys containing `~` or `/` are escaped to `~0`/`~1` per RFC.
+     *
+     * Path is structural metadata (preserved under `trace.redact`).
+     */
+    path: string;
+    /**
+     * Unescaped characters appended this chunk. JSON escapes are translated:
+     * `\\n` → "\n", `\\t` → "\t", `\\"` → '"', `\\\\` → "\\", `\\uXXXX` → the
+     * corresponding UTF-16 code unit. Surrogate pairs (e.g. `\\uD83D\\uDE00`)
+     * are emitted as two code units in the order they parse — matches what
+     * `JSON.parse` produces.
+     *
+     * Subject to `config.trace.redact` (always scrubbed when redaction is on).
+     */
+    delta: string;
+};
 /** Data shape for legacy `guardrail` events. Replaced by `pipeline` in PR 2. */
 type GuardrailData = {
     guardrailType: 'input' | 'output';
@@ -717,6 +750,11 @@ type AxlEvent = (AxlEventBase & {
     data: {
         object: unknown;
     };
+}) | (AxlEventBase & AskScoped & {
+    type: 'string_delta';
+    /** 1-indexed schema-retry attempt; mirrors `partial_object.attempt`. */
+    attempt: number;
+    data: StringDeltaData;
 }) | (AxlEventBase & AskScoped & {
     type: 'verify';
     data: VerifyData;
@@ -1010,6 +1048,59 @@ type CoalescedPartialObject = {
     object: unknown;
     attempt: number;
 };
+/**
+ * The shape yielded by `AxlEventBus.stringStream` (and `AxlStream.stringStream`).
+ *
+ * A live `string_delta` event carries `delta` (the new chars from this chunk)
+ * and `accumulated` (every char emitted so far for this ask + path,
+ * i.e. `delta1 + delta2 + ...`). Consumers rendering full-field state set
+ * their UI text to `accumulated`; consumers rendering incrementally use
+ * `delta` and append themselves.
+ *
+ * For LATE SUBSCRIBERS — those who attach `stringStream(...)` after one or
+ * more `string_delta` events have already fired for an askId/path —
+ * one synthetic event is yielded at subscribe time with `delta` ===
+ * `accumulated` === the full text-so-far. This guarantees the consumer's
+ * first render reflects the current state of the field, with no manual
+ * catch-up logic.
+ *
+ * `attempt` matches the underlying `string_delta.attempt` (1-indexed
+ * schema-retry counter). `pipeline(failed)` drops the accumulator AND
+ * any pending events for that ask before they reach the consumer, so a
+ * UI subscribed during attempt-N never sees stale text after attempt-N+1
+ * begins.
+ */
+type StringStreamEvent = {
+    askId: string;
+    agent?: string;
+    /** RFC 6901 JSON Pointer; matches the source `string_delta.data.path`. */
+    path: string;
+    /** Chars added in this delta. For seeded synthetic events on subscribe,
+     *  equals `accumulated` (the full text-so-far). */
+    delta: string;
+    /** Concatenation of every delta this ask + path has emitted in the
+     *  current attempt. Cleared on `pipeline(failed)` and `ask_end`. */
+    accumulated: string;
+    /** 1-indexed schema-retry attempt; mirrors the source event. */
+    attempt: number;
+};
+/**
+ * Optional filter applied at subscribe time. Filtering happens in the bus's
+ * listener so non-matching events neither buffer nor wake the consumer's
+ * waiter — cheaper than filtering in the consumer.
+ *
+ * - `path`: yield only events for this exact JSON Pointer. The walker
+ *   produces RFC 6901-encoded paths, so callers binding to a key with
+ *   special chars must encode (`a/b` → `/a~1b`).
+ * - `askId`: yield only events from this ask. Useful when watching a
+ *   specific ask in a fan-out workflow.
+ *
+ * Both fields are AND-combined when both are set. Omit a field to wildcard.
+ */
+type StringStreamFilter = {
+    path?: string;
+    askId?: string;
+};
 /**
  * Thrown when an `AxlEventBus` queue exceeds `maxQueued` and `onOverflow`
  * is set to `'throw'`. Surfaced as a typed error so the runtime's emit
@@ -1087,6 +1178,27 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
      * number of distinct askIds that emitted at least one partial.
      */
     private latestPartialByAsk;
+    /**
+     * 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).
+     */
+    private stringStreamByAsk;
     /**
      * Hook fired when an iterator obtained from `[Symbol.asyncIterator]`
      * is `await using`-disposed. Set via the second constructor argument.
@@ -1191,6 +1303,38 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
      * once the bus is finished (via `_finish()`).
      */
     get partialObjects(): AsyncIterable<CoalescedPartialObject>;
+    /**
+     * 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?: StringStreamFilter): AsyncIterable<StringStreamEvent>;
     /** 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. */
@@ -2364,6 +2508,18 @@ declare class AxlStream extends Readable implements AsyncIterable<AxlEvent> {
      *  `CoalescedPartialObject` shape is shared with the bus so the two
      *  surfaces can never drift on the `attempt` field. */
     get partialObjects(): AsyncIterable<CoalescedPartialObject>;
+    /** 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?: StringStreamFilter): AsyncIterable<StringStreamEvent>;
     pipe<T extends NodeJS.WritableStream>(destination: T, options?: {
         end?: boolean;
     }): T;
@@ -2597,6 +2753,10 @@ declare class AxlRuntime extends EventEmitter {
      *  the instance so per-event onTrace handlers don't reach into
      *  `this.config.state` on every emission. */
     private readonly 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. */
+    private warnedMalformedExecutions;
     constructor(config?: AxlConfig);
     /**
      * Whether `config.trace.redact` is enabled on this runtime. A narrow
@@ -2717,6 +2877,14 @@ declare class AxlRuntime extends EventEmitter {
         captureTraces?: boolean;
     }): Promise<unknown>;
     /** Get all execution info (running + completed + historical). */
+    /** Normalize an `ExecutionInfo` loaded from a `StateStore` so the
+     *  `events: AxlEvent[]` type contract holds for downstream consumers
+     *  (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`. */
+    private normalizeStoredExecution;
     getExecutions(): Promise<ExecutionInfo[]>;
     /**
      * Create a WorkflowContext for ad-hoc use (evals, tool testing, prototyping).
@@ -3082,6 +3250,94 @@ declare function expandGlob(pattern: string, cwd: string): string[];
  */
 declare function registerConditions(conditions: string[]): Promise<void>;
 
+/**
+ * Browser-safe wire-side reconstructor for the `stringStream` view.
+ *
+ * Lives in its own module — separate from `event-stream.ts` which
+ * imports `node:events`'s `EventEmitter` for `AxlEventBus` — so a
+ * browser SPA importing only `stringStreamFromEvents` from
+ * `@axlsdk/axl` cannot pull `EventEmitter` into the bundle even under
+ * conservative bundler settings (webpack default is "assume side
+ * effects unless `sideEffects: false` is set"). This is
+ * defense-in-depth alongside `sideEffects: false` in `package.json`:
+ * the module split guarantees tree-shaking at the *file* level (no
+ * dead-code elimination required), so bundle size stays predictable
+ * regardless of bundler configuration.
+ *
+ * All imports here are type-only (`import type`) and resolve against
+ * `types.ts` and `event-stream.ts` — both erased at compile time, no
+ * runtime edge.
+ */
+
+/**
+ * Reconstruct a `stringStream`-shaped view from a raw `AxlEvent` source.
+ *
+ * Use this when consuming events on the wire (WebSocket / SSE) rather
+ * than from a live `AxlStream` / `AxlEventBus` you own. The browser-side
+ * SPA has no access to the bus's per-ask accumulator, so each
+ * `string_delta` event arrives carrying only the new chars — without
+ * the running text. This helper maintains the accumulator client-side,
+ * yielding `StringStreamEvent`s with the same `{ delta, accumulated }`
+ * shape the server-side `stringStream` view produces.
+ *
+ * Pure ECMAScript — zero Node dependencies. Safe to bundle for the
+ * browser; lives in its own module so even bundlers that don't honor
+ * `sideEffects: false` won't pull `node:events` from the AxlEventBus
+ * file.
+ *
+ * Differences from the live-bus view:
+ *
+ *  - **No late-subscriber seeding.** The function starts accumulating
+ *    when iteration begins; if the source has already produced
+ *    `string_delta` events before then, those are missed. Server-side
+ *    operators wanting cross-reconnect recovery should re-emit current
+ *    state on subscribe (out of scope here — the wire transport is the
+ *    caller's responsibility).
+ *  - **No race-with-bus-iterator concern.** This is a stateless
+ *    consumer of an iterable; iterating it twice on the same source
+ *    consumes events twice (fork the source first if you need that).
+ *  - **No retroactive pending-drop on retry.** The bus view splices
+ *    pending events on `pipeline(failed)` to hide attempt-N text from
+ *    a buffered consumer. The wire helper has no buffer, so attempt-N
+ *    deltas that already yielded stay yielded. The accumulator clear
+ *    on `pipeline(failed)` still fires, so the next yielded event has
+ *    `accumulated === delta` — a UI re-rendering `event.accumulated`
+ *    per yield naturally overwrites stale text in place. Customers
+ *    appending `event.delta` to a manual buffer instead must reset the
+ *    buffer when `attempt` increases.
+ *
+ * Same filter / clear semantics as the bus view:
+ *
+ *  - `opts.path` / `opts.askId` filter at yield time.
+ *  - `pipeline(failed)` clears the per-ask accumulator (so
+ *    attempt-N text never leaks into attempt-N+1).
+ *  - `ask_end` clears the per-ask accumulator (memory hygiene).
+ *
+ * Example (browser, consuming Studio's WS firehose):
+ *
+ * ```ts
+ * import { stringStreamFromEvents } from '@axlsdk/axl';
+ *
+ * async function* readWs(ws: WebSocket): AsyncIterable<AxlEvent> {
+ *   const queue: AxlEvent[] = [];
+ *   let resolver: (() => void) | null = null;
+ *   ws.addEventListener('message', (m) => {
+ *     queue.push(JSON.parse(m.data).data);
+ *     resolver?.();
+ *   });
+ *   while (true) {
+ *     while (queue.length) yield queue.shift()!;
+ *     await new Promise<void>((r) => (resolver = r));
+ *   }
+ * }
+ *
+ * for await (const e of stringStreamFromEvents(readWs(ws), { path: '/summary' })) {
+ *   setText(e.accumulated);
+ * }
+ * ```
+ */
+declare function stringStreamFromEvents(source: AsyncIterable<AxlEvent>, opts?: StringStreamFilter): AsyncIterable<StringStreamEvent>;
+
 /**
  * Shared helpers for working with `AxlEvent` streams.
  *
@@ -3723,4 +3979,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { AXL_EVENT_TYPES, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type AskOptions, type AskScoped, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallbackMeta, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, type DelegateData, type DelegateOptions, type Effort, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type EventStreamOptions, EventStreamOverflowError, type ExecuteOptions, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RecallOptions, type RecallResult, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, type SchemaCheckData, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type TelemetryConfig, TimeoutError, type Tool, type ToolApprovalData, type ToolCallData, type ToolCallMessage, type ToolCallStartData, type ToolChoice, type ToolConfig, ToolDenied, type ToolDeniedData, type ToolHooks, type ValidateData, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, type VerifyData, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndData, type WorkflowStartData, agent, createSpanManager, defineConfig, eventCostContribution, expandGlob, extractJson, findConfig, importModule, isCostBearingLeaf, isRootLevel, needsTsxLoader, parsePartialJson, pickDefault, pickExport, redactEvent, registerConditions, resolveRuntime, resolveThinkingOptions, tool, workflow, zodToJsonSchema };
+export { AXL_EVENT_TYPES, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type AskOptions, type AskScoped, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallbackMeta, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, type DelegateData, type DelegateOptions, type Effort, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type EventStreamOptions, EventStreamOverflowError, type ExecuteOptions, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RecallOptions, type RecallResult, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, type SchemaCheckData, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StringDeltaData, type StringStreamEvent, type StringStreamFilter, type TelemetryConfig, TimeoutError, type Tool, type ToolApprovalData, type ToolCallData, type ToolCallMessage, type ToolCallStartData, type ToolChoice, type ToolConfig, ToolDenied, type ToolDeniedData, type ToolHooks, type ValidateData, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, type VerifyData, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndData, type WorkflowStartData, agent, createSpanManager, defineConfig, eventCostContribution, expandGlob, extractJson, findConfig, importModule, isCostBearingLeaf, isRootLevel, needsTsxLoader, parsePartialJson, pickDefault, pickExport, redactEvent, registerConditions, resolveRuntime, resolveThinkingOptions, stringStreamFromEvents, tool, workflow, zodToJsonSchema };