@axlsdk/axl 0.22.3 → 0.23.1

package/dist/index.d.ts

@@ -124,10 +124,23 @@ type ChatOptions = {
     responseFormat?: ResponseFormat;
     stop?: string[];
     signal?: AbortSignal;
+    /** @internal Runtime observer for the actual adapter transport lifecycle. */
+    requestLifecycle?: {
+        /** The request was actually dispatched, after limiter queue and retry backoff. */
+        onDispatch?(): void;
+        /** A retryable response was received; SDK retry backoff is about to begin. */
+        onRetry?(): void;
+    };
     /** How hard should the model try? Primary param for cost/quality tradeoff.
      *  'none' disables thinking/reasoning (Gemini 3.x: maps to minimal).
      *  Omit to use provider defaults. */
     effort?: Effort;
+    /** Opt in to provider prompt caching of the stable request prefix (system
+     *  prompt + tool definitions). Anthropic requires an explicit `cache_control`
+     *  breakpoint; OpenAI and Gemini cache automatically, so this is a no-op
+     *  there. Off by default: a prefix that changes every call (a system prompt
+     *  built from `ctx.metadata`) pays the cache-write premium with no reads. */
+    promptCache?: boolean;
     /** Precise thinking token budget (advanced). When set alongside `effort`, overrides the
      *  thinking/reasoning allocation. On Anthropic 4.6, `effort` still controls output quality
      *  independently. On all other providers, `thinkingBudget` fully overrides `effort` for
@@ -187,6 +200,12 @@ type StreamChunk = {
     cost?: number;
     /** Provider-specific opaque metadata (e.g. raw Gemini parts with thought signatures). */
     providerMetadata?: Record<string, unknown>;
+    /**
+     * Per-call latency breakdown. The `done` chunk is the only channel a
+     * stream has back to the runtime, so every terminal `done` must carry it
+     * — including the usage-less fallbacks, or a $0 stream loses its timing.
+     */
+    timing?: CallTiming;
 };
 /**
  * Core provider interface. Every LLM adapter must implement this.
@@ -194,6 +213,8 @@ type StreamChunk = {
 interface Provider {
     /** Human-readable name for the provider (e.g. "openai", "anthropic") */
     readonly name?: string;
+    /** @internal Built-in adapters set this when `ChatOptions.requestLifecycle` reports fetch dispatch. */
+    readonly reportsRequestLifecycle?: true;
     /** Coarse, model-aware input metadata for UI/documentation. */
     inputCapabilities?(model: string): InputModalitySupport;
     /** Authoritative request-scoped rich-input validation. Omission means text-only. */
@@ -228,6 +249,16 @@ interface Provider {
      *    JSON instruction instead (e.g. Anthropic).
      */
     nativeStructuredOutputSupport?(model: string): 'schema' | 'downgraded' | 'lossy' | 'unsupported';
+    /**
+     * Whether this adapter realizes `ChatOptions.promptCache` for this model --
+     * i.e. actually places a cache breakpoint on the request. The runtime only
+     * emits the promptCache diagnostics (cold writes with no reads; no cache
+     * activity at all) for adapters that declare this, because on providers
+     * that cache automatically the absence of cache fields is not a signal.
+     * Adapters that omit this method opt out; the built-in Anthropic adapter is
+     * the only one that declares it today.
+     */
+    realizesPromptCache?(model: string): boolean;
     /**
      * How this provider resolved the unified `effort` knob for this request.
      *
@@ -314,11 +345,10 @@ type BudgetResult<T> = {
     budgetExceeded: boolean;
     totalCost: number;
     /**
-     * True when the block ran a model with no usable cost (unpriced / pricing-table
-     * miss) that did measurable work. `totalCost` is then a LOWER BOUND — the unknown
-     * component is omitted. NOTE: this is observability only; cost limits / `hard_stop`
-     * are NOT enforced on unpriced spend (the enforcement rail never sees it). Token
-     * budgets are the future fix for governing unpriced models.
+     * True when the block included work with no usable cost (for example, an
+     * unpriced model or an abandoned dispatched call). `totalCost` is then a LOWER
+     * BOUND — the unknown component is omitted. Cost limits / `hard_stop` are NOT
+     * enforced on unknown spend because the enforcement rail never sees it.
      */
     unpriced: boolean;
 };
@@ -429,12 +459,20 @@ type AskOptions<T = unknown> = {
     thinkingBudget?: number;
     /** Show reasoning summaries in responses. */
     includeThoughts?: boolean;
+    /** Override prompt caching of the stable prefix for this call. */
+    promptCache?: boolean;
     /** Tool choice strategy for this call. */
     toolChoice?: ToolChoice;
     /** Stop sequences for this call. */
     stop?: string[];
     /** Provider-specific options merged into API requests. Not portable across providers. */
     providerOptions?: Record<string, unknown>;
+    /** Graceful overall budget for this ask. The in-flight provider turn is allowed to finish. */
+    timeout?: string;
+    /** Abort an in-flight provider request that makes no streaming progress. Unset by default. */
+    stallTimeout?: string;
+    /** Per-ask hard cancellation signal. It is composed with the context signal and inherited by nested asks. */
+    signal?: AbortSignal;
 };
 /** Delegate options */
 type DelegateOptions<T = unknown> = {
@@ -999,7 +1037,7 @@ type AxlEventBase = {
      *     `memory_recall`): the authoritative charge for this single
      *     provider call / tool invocation / embedder call. Summing these
      *     across an execution gives the spend — a LOWER BOUND when any call
-     *     used an unpriced model (its `cost` is `undefined` and contributes
+     *     included unknown-cost work (its `cost` is `undefined` and contributes
      *     nothing; the owning `ask_end` sets `unpriced: true`).
      *
      *   - **Per-ask rollup** (`ask_end`): the SUM of leaf costs emitted
@@ -1089,11 +1127,10 @@ type LegacyAxlEventPayloadV1 = (AxlEventBase & {
     /** Sum of `agent_call_end.cost` + `tool_call_end.cost` WITHIN THIS ASK,
      *  excluding nested asks. Nested asks contribute to their own ask_end. */
     cost: number;
-    /** True when a cost-bearing leaf in this ask did measurable work but had
-     *  no usable cost (unpriced model / pricing-table miss). When set, `cost`
+    /** True when a cost-bearing leaf in this ask had no usable cost. When set, `cost`
      *  is a LOWER BOUND — the unknown component is not included. Absent ⇒
      *  `cost` is exact. Surfaced so dashboards don't render a misleading
-     *  exact `$0.00` for an ask that used an unpriced model. */
+     *  exact `$0.00` for an ask with unknown-cost work. */
     unpriced?: boolean;
     duration: number;
 }) | (AxlEventBase & AskScoped & {
@@ -1111,6 +1148,10 @@ type LegacyAxlEventPayloadV1 = (AxlEventBase & {
     /** Authoritative turn-level cost. `undefined` for an unpriced model
      *  (pricing-table miss) and absent on the error path (no usage). */
     cost?: number;
+    /** Explicit lower-bound marker when a dispatched request was abandoned
+     *  without usage/cost (for example, a non-cooperative stalled provider).
+     *  The work may still be billed after this terminal event. */
+    unpriced?: boolean;
     duration: number;
     tokens?: {
         input?: number;
@@ -1119,6 +1160,12 @@ type LegacyAxlEventPayloadV1 = (AxlEventBase & {
         cached?: number;
         cacheWrite?: number;
     };
+    /** Per-call latency breakdown when the provider reported one. Additive
+     *  beside `duration`, which keeps its turn-wall-clock meaning (queue,
+     *  retries, gates and all). Present on the error path too when the
+     *  provider returned a response (any non-2xx); absent when the call
+     *  never reached one (network failure, abort, non-provider throw). */
+    timing?: CallTiming;
     /** Response-side payload — response text, thinking. */
     data: AgentCallEndData;
 }) | (AxlEventBase & AskScoped & {
@@ -1442,12 +1489,12 @@ type ExecutionInfoV1 = {
      *  here (stream-only); aggregate `tokens: { input, output, reasoning? }`
      *  on `agent_call_end` is the persisted token representation. */
     events: LegacyAxlEventV1[];
-    /** Total spend for the execution. A LOWER BOUND when an unpriced model ran
+    /** Total known spend for the execution. A LOWER BOUND when unknown-cost work ran
      *  (those calls contribute nothing) — read {@link ExecutionInfo.unpriced} to
      *  know whether it's exact, rather than scanning the event timeline. */
     totalCost: number;
-    /** True when any cost-bearing leaf in this execution did billable work but had
-     *  no usable cost (unpriced model / pricing-table miss): `totalCost` is then a
+    /** True when any cost-bearing leaf in this execution had no usable cost:
+     *  `totalCost` is then a
      *  LOWER BOUND, not exact. `false` means every cost-bearing call was priced.
      *  The aggregate counterpart of `ask_end.unpriced` / `BudgetResult.unpriced`,
      *  computed via `isUnpricedLeaf`. `undefined` only on executions recorded
@@ -1548,6 +1595,13 @@ type ChatMessage = {
      *  (the option name and shape are not yet stable); today it is purely
      *  informational. */
     agent?: string;
+    /** Provenance of a message the Axl runtime synthesized rather than the caller
+     *  authored: the rolling conversation summary and the handoff header. Like
+     *  `agent`, never sent on the wire. Adapters use it to avoid treating
+     *  runtime-injected text as the caller's stable prompt -- the Anthropic
+     *  adapter will not place its prompt-cache breakpoint on a system message
+     *  with `origin: 'runtime'`. */
+    origin?: 'runtime';
 };
 type ToolCallMessage = {
     id: string;
@@ -1557,6 +1611,52 @@ type ToolCallMessage = {
         arguments: string;
     };
 };
+/**
+ * Per-call latency breakdown, reported by adapters that route through
+ * `fetchWithRetry`. Every figure is a non-negative integer count of
+ * milliseconds derived from `Date.now()` deltas — the same clock
+ * `agent_call_end.duration` uses.
+ *
+ * Entirely optional and additive: a custom `Provider` that omits `timing` stays
+ * valid, and consumers must treat every field as possibly absent.
+ *
+ * The buckets separate the three things that `duration` conflates — the SDK's
+ * own pacing, the provider's throttling, and the model's actual latency:
+ */
+type CallTiming = {
+    /**
+     * Time parked in Axl's own opt-in `RateLimiter` (concurrency cap plus
+     * `minIntervalMs` spacing) before the request was allowed out. `0` when the
+     * provider has no `rateLimit` configured. This is self-imposed wait, not
+     * provider latency.
+     */
+    queuedMs: number;
+    /** `fetch` attempts made for this call, including the final one (≥ 1). */
+    attempts: number;
+    /**
+     * First attempt's dispatch → final attempt's dispatch, i.e. everything spent
+     * on failed attempts and their backoff sleeps. `0` for a single attempt.
+     */
+    retryMs: number;
+    /** Final dispatch → response headers. Time to first byte. */
+    ttfbMs: number;
+    /**
+     * Final dispatch → first `text_delta`/`thinking_delta`, excluding consumer
+     * suspension after an earlier non-content chunk. Streaming only, and absent
+     * on a stream that ends without any content delta. This is the model-
+     * discriminating figure: headers arrive at roughly one round trip regardless
+     * of model, first token does not.
+     */
+    firstTokenMs?: number;
+    /**
+     * Time attributable to the provider. For `chat()`, final dispatch → response
+     * body parsed. For `stream()`, `ttfbMs` plus cumulative body-read waits,
+     * floored at `firstTokenMs` when content arrives. Parsing needed to deliver
+     * first content is included; consumer suspension between yielded chunks is
+     * excluded, so two models stay comparable under different listener loads.
+     */
+    wireMs: number;
+};
 /** Provider response */
 type ProviderResponse = {
     content: string;
@@ -1574,6 +1674,8 @@ type ProviderResponse = {
     cost?: number;
     /** Provider-specific opaque metadata that needs to round-trip through conversation history. */
     providerMetadata?: Record<string, unknown>;
+    /** Per-call latency breakdown. Absent on providers that don't instrument it. */
+    timing?: CallTiming;
 };
 
 /** Base error class for all Axl errors */
@@ -1694,9 +1796,33 @@ declare class QuorumNotMet extends AxlError {
 declare class NoConsensus extends AxlError {
     constructor(reason: string);
 }
+/**
+ * Where a timed-out ask's elapsed budget went, summed over the turns that
+ * completed before the timeout fired. Present only when at least one of those
+ * turns reported provider `timing` — an all-zero breakdown on an uninstrumented
+ * provider would falsely blame tools and gates.
+ */
+type TimeoutBreakdown = {
+    /** Wall clock consumed by the operation when it timed out. */
+    elapsedMs: number;
+    /** Sum of `CallTiming.queuedMs` — self-imposed rate-limiter wait. */
+    queuedMs: number;
+    /** Sum of `CallTiming.retryMs` — failed provider attempts and their backoff. */
+    retryMs: number;
+    /** Sum of `CallTiming.wireMs` — provider time. */
+    wireMs: number;
+    /** `elapsedMs` minus the three sums: tools, gates, and runtime work. */
+    otherMs: number;
+};
 /** Thrown when an operation exceeds its timeout */
 declare class TimeoutError extends AxlError {
-    constructor(operation: string, timeoutMs: number);
+    /** Latency attribution for the timed-out operation, when measurable. */
+    readonly breakdown?: TimeoutBreakdown;
+    constructor(operation: string, timeoutMs: number, breakdown?: TimeoutBreakdown, agent?: string);
+}
+/** Thrown when a dispatched provider request stops making progress. */
+declare class StallTimeoutError extends TimeoutError {
+    constructor(operation: string, timeoutMs: number, agent?: string);
 }
 /** Thrown when a budget limit is exceeded */
 declare class BudgetExceededError extends AxlError {
@@ -1753,6 +1879,9 @@ type AgentConfig = {
     includeThoughts?: boolean;
     toolChoice?: ToolChoice;
     stop?: string[];
+    /** Opt in to prompt caching of this agent's stable prefix (system prompt +
+     *  tools). Only Anthropic needs it; off by default. See `docs/providers.md`. */
+    promptCache?: boolean;
     /** Provider-specific options merged into API requests. Not portable across providers. */
     providerOptions?: Record<string, unknown>;
     /** Default rendering of a `ctx.ask` output schema into this agent's prompt.
@@ -1763,6 +1892,7 @@ type AgentConfig = {
     nativeStructuredOutput?: boolean;
     maxTurns?: number;
     timeout?: string;
+    stallTimeout?: string;
     maxContext?: number;
     version?: string;
     guardrails?: GuardrailsConfig;
@@ -2183,11 +2313,14 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
  * shared API key can storm a provider's rate limit; a governor smooths that.
  *
  * ## Scope & caveats (v1)
- * - **Caps request concurrency, not token throughput (TPM).** Streaming `chat()`
- *   releases the permit at *headers* (the adapter gets the `Response` from
- *   `fetchWithRetry`, then iterates the body separately), so a slow stream does
- *   NOT hold a permit for its whole lifetime. Non-streaming `chat()` holds the
- *   permit through `res.json()`. Neither bounds tokens/min.
+ * - **Caps request concurrency, not token throughput (TPM).** The permit is
+ *   released at response *headers* on BOTH transports: `fetchWithRetry`
+ *   releases in its `finally` as it returns the `Response`, and every adapter
+ *   reads the body only afterwards — so `res.json()` and stream iteration alike
+ *   run outside the permit. A slow stream therefore does not hold a permit for
+ *   its whole lifetime. Non-streaming calls still hold it across generation in
+ *   practice, because a provider sends no headers until the completion is
+ *   finished. Neither bounds tokens/min.
  * - **Per provider instance.** Providers are singletons per (runtime, provider
  *   type), so one governor governs all calls through that adapter — but NOT
  *   embedder calls (the embedder is constructed outside the registry) and NOT
@@ -2477,6 +2610,7 @@ type OpenAICompatibleOptions = {
  */
 declare class OpenAICompatibleProvider implements Provider {
     readonly name: string;
+    readonly reportsRequestLifecycle: true;
     inputCapabilities(model: string): {
         image?: {
             sources: readonly InputMediaSource['type'][];
@@ -2517,7 +2651,21 @@ declare class OpenAICompatibleProvider implements Provider {
     }): number | undefined;
     protected parseResponse(json: OpenAIChatResponse, model: string, request?: Record<string, unknown>): ProviderResponse;
     private roundTripMetadata;
-    protected parseSSEStream(body: ReadableStream<Uint8Array>, model: string, request?: Record<string, unknown>): AsyncGenerator<StreamChunk>;
+    /**
+     * PRIVATE, and deliberately not an extension point. It was `protected`, but
+     * nothing in or out of this repo overrides it, and `protected` could not
+     * carry the guarantee it appeared to: TypeScript checks an override for
+     * assignability, and a function type with fewer parameters is assignable to
+     * one with more — so an override that simply dropped the recorder still
+     * compiled and then reported `wireMs === ttfbMs` for the whole subclass. Its
+     * type is not exported from the barrel either, so a subclass author could not
+     * name what they were required to accept.
+     *
+     * A provider with a different wire format implements `Provider` (see
+     * docs/providers.md); an OpenAI-compatible one adds a `ProviderProfile`.
+     * Neither needs to reach in here.
+     */
+    private parseSSEStream;
 }
 type OpenAIUsage = {
     prompt_tokens: number;
@@ -2956,6 +3104,7 @@ type StateConfig = {
 /** Global defaults */
 type DefaultsConfig = {
     timeout?: string;
+    stallTimeout?: string;
     maxRetries?: number;
     budgetPolicy?: 'finish_and_stop' | 'hard_stop' | 'warn';
 };
@@ -3522,6 +3671,13 @@ declare class WorkflowContext<TInput = unknown> {
     private readonly workflowLifecycleState;
     private signal?;
     private summaryCache?;
+    /** Consecutive provider calls with promptCache on that wrote to the cache
+     *  without reading from it (prefix changes per call), and consecutive calls
+     *  with no cache activity at all (prefix below the model's minimum, which
+     *  Anthropic silently ignores). Either reports once per context. */
+    private promptCacheColdWrites;
+    private promptCacheInactive;
+    private promptCacheWarned;
     private workflowName?;
     private mcpManager?;
     private spanManager?;
@@ -3648,6 +3804,7 @@ declare class WorkflowContext<TInput = unknown> {
     private observeToolInvocation;
     ask<T = string>(agent: Agent, prompt: ModelInput, options?: AskOptions<T>): Promise<T>;
     private executeAgentCall;
+    private executeAgentCallImpl;
     /**
      * Resolve the corrective feedback text for one rejected attempt, giving an optional
      * caller-supplied `retryFeedback` hook the chance to replace it or to stop retrying.
@@ -4646,12 +4803,62 @@ declare class AxlRuntime extends EventEmitter {
      */
     trackExecution<T>(fn: () => Promise<T>, options?: {
         captureTraces?: boolean;
+        captureTimingSamples?: boolean;
     }): Promise<{
         result: T;
         cost: number;
         /** True when any tracked call was unpriced — `cost` is then a LOWER BOUND.
          *  Aggregate counterpart of `ExecutionInfo.unpriced`, via `isUnpricedLeaf`. */
         unpriced: boolean;
+        /**
+         * Per-model sums of `agent_call_end.timing`, keyed by the same effective
+         * model URI as `metadata.modelCallCounts`. Present only when at least one
+         * tracked call reported timing, so absence means "nothing was instrumented"
+         * rather than "everything took zero ms".
+         *
+         * `calls` counts the SUCCESSFUL timed calls only — it can be lower than the
+         * same model's `modelCallCounts` entry when a provider omits `timing` or a
+         * call failed. Divide a sum by `calls`, never by `modelCallCounts`.
+         *
+         * Failed calls are excluded even though they now report timing: a non-2xx
+         * response is a measured round trip, but a rollup blending answers with
+         * failures describes neither, and a fast 429 would improve a model's
+         * apparent latency. The failures stay on the events themselves.
+         *
+         * `firstTokenMs` is streaming-only and is summed across the calls that
+         * reported it; it is omitted entirely when no call did, so a non-streaming
+         * model never reports a misleading `0`. Its denominator is `firstTokenCalls`,
+         * NOT `calls` — the two travel together and are present or absent together,
+         * so a mixed streaming/non-streaming model still yields an exact mean.
+         *
+         * Sums are per-call totals, so `wireMs` across concurrent calls can exceed
+         * the wall clock of `fn` — that is expected under fan-out and is why
+         * nothing in the core sums timing at the ask level.
+         *
+         * `samples` carries the raw per-call `CallTiming` blocks behind the sums, in
+         * `agent_call_end` order, so a caller that needs a DISTRIBUTION (percentiles,
+         * min/max) rather than a mean can compute one over real per-call values. It
+         * is the same data the sums were built from — `samples.length === calls` —
+         * and is deliberately not something callers should persist per item: the
+         * sums are the compact form, `samples` is the working form.
+         *
+         * It is **opt-in** via `captureTimingSamples` and the key is absent
+         * otherwise. Retaining it is O(calls) in memory for the lifetime of `fn`,
+         * which no caller should pay for a figure it never reads — the sums alone
+         * are O(models).
+         */
+        modelTiming?: Record<string, {
+            calls: number;
+            queuedMs: number;
+            retryMs: number;
+            wireMs: number;
+            firstTokenMs?: number;
+            /** Timed calls that reported a `firstTokenMs` — the denominator for it. */
+            firstTokenCalls?: number;
+            /** The per-call blocks the sums were built from, in event order.
+             *  `length === calls`. Present only under `captureTimingSamples`. */
+            samples?: CallTiming[];
+        }>;
         traces?: AxlEvent[];
         metadata: {
             models: string[];
@@ -4980,9 +5187,9 @@ declare function stringStreamFromEvents(source: AsyncIterable<AxlEvent>, opts?:
 declare const COST_BEARING_LEAF_TYPES: readonly ["agent_call_end", "tool_call_end", "memory_remember", "memory_recall", "transcription_end"];
 /**
  * True when an event reports a POSITIVE token count — i.e. it did measurable,
- * billable work. This is the discriminator the unpriced-cost signal (T2.5) uses:
- * a cost-bearing leaf with positive tokens but no usable cost is an unpriced
- * model / pricing-table miss, whereas a failed call (no usage) or a no-usage
+ * billable work. This is one discriminator the unpriced-cost signal uses:
+ * a cost-bearing leaf with positive tokens but no usable cost is unknown-cost
+ * work, whereas a failed call (no usage) or a no-usage
  * streamed `done` (zero tokens) is NOT "unpriced". Used by the core ask-cost
  * rollup AND the Studio aggregators, so the per-ask flag and the dashboard count
  * stay in lockstep.
@@ -5045,16 +5252,17 @@ declare function eventCostContribution(event: HistoricalAxlEvent): number;
 declare function isCostBearingLeaf(event: HistoricalAxlEvent): boolean;
 /**
  * True when the event is the "unpriced lower-bound" signal: a cost-bearing leaf
- * that did measurable, billable work (POSITIVE tokens) but produced no usable
- * cost (an unpriced model / pricing-table miss). This is the SINGLE source of
- * truth for that discriminator — the core ask-cost rollup, the runtime's
+ * that either explicitly reports unknown cost (for example, an abandoned
+ * dispatched request) or did measurable, billable work (POSITIVE tokens) but
+ * produced no usable cost (an unpriced model / pricing-table miss). This is the
+ * SINGLE source of truth for that discriminator — the core ask-cost rollup, the runtime's
  * `ExecutionInfo.unpriced` / `trackExecution().unpriced` aggregation, and
  * Studio's `unpricedCalls` count + cost reducer ALL route through it, so they
  * cannot drift.
  *
- * It is the conjunction of the three primitives:
- *   `isCostBearingLeaf` ∧ `!isUsableCost(cost)` ∧ `hasPositiveTokens`.
- * The positive-token term is what distinguishes an unpriced model from a FAILED
+ * It is the conjunction of the first two primitives and either uncertainty signal:
+ *   `isCostBearingLeaf` ∧ `!isUsableCost(cost)` ∧ (`unpriced === true` ∨ `hasPositiveTokens`).
+ * The positive-token term is what distinguishes ordinary unpriced work from a FAILED
  * call (no usage) or a no-usage streamed `done` (zero tokens) — neither is
  * "unpriced". An `ask_end` rollup carries a numeric cost, and `tool_call_end`
  * carries no tokens, so both are naturally excluded.
@@ -5065,6 +5273,7 @@ declare function isCostBearingLeaf(event: HistoricalAxlEvent): boolean;
 declare function isUnpricedLeaf(event: {
     type?: string;
     cost?: unknown;
+    unpriced?: boolean;
     tokens?: {
         input?: number;
         output?: number;
@@ -5354,6 +5563,16 @@ declare class ProviderError extends AxlError {
      * and is redaction-eligible). See `docs/security.md`.
      */
     readonly body?: string;
+    /**
+     * Per-call latency breakdown for the failed call, when the transport reached
+     * the provider and a `Response` came back (any non-2xx, streamed or not).
+     * Absent — the KEY itself, not `undefined` — when there is nothing to
+     * report: a network-level failure (`status: 0`) never got a response, and a
+     * custom transport may not instrument timing at all. `declare` keeps the
+     * property from being defined as `undefined` under `useDefineForClassFields`,
+     * so `'timing' in err` distinguishes "not measured" from "measured as zero".
+     */
+    readonly timing?: CallTiming;
     constructor(args: {
         provider: string;
         status: number;
@@ -5362,6 +5581,7 @@ declare class ProviderError extends AxlError {
         retryAfterMs?: number;
         requestId?: string;
         body?: string;
+        timing?: CallTiming;
     });
 }
 /**
@@ -5430,6 +5650,7 @@ declare class OpenAIProvider extends OpenAICompatibleProvider {
  */
 declare class OpenAIResponsesProvider implements Provider {
     readonly name = "openai-responses";
+    readonly reportsRequestLifecycle: true;
     inputCapabilities(model: string): {
         image?: {
             sources: readonly InputMediaSource['type'][];
@@ -5492,6 +5713,7 @@ declare class OpenAIResponsesProvider implements Provider {
  */
 declare class AnthropicProvider implements Provider {
     readonly name = "anthropic";
+    readonly reportsRequestLifecycle: true;
     /** Report a clamped `effort`. Anthropic clamps to each model's supported
      *  `output_config.effort` levels, and models that always think fall back to
      *  adaptive `'low'` when asked to disable thinking. Only reported when the
@@ -5506,6 +5728,8 @@ declare class AnthropicProvider implements Provider {
     validateInput(request: ProviderInputValidationRequest): ProviderInputValidationResult;
     /** Anthropic ignores native `json_schema` structurally — Axl uses a system
      *  prompt JSON instruction + client-side Zod validation (see buildRequest). */
+    /** The only built-in adapter that honors `promptCache` (see buildBody). */
+    realizesPromptCache(): boolean;
     nativeStructuredOutputSupport(): 'unsupported';
     private baseUrl;
     private apiKeySource;
@@ -5574,6 +5798,7 @@ declare class AnthropicProvider implements Provider {
  */
 declare class GeminiProvider implements Provider {
     readonly name = "google";
+    readonly reportsRequestLifecycle: true;
     inputCapabilities(model: string): {
         image?: {
             sources: readonly InputMediaSource['type'][];
@@ -6270,4 +6495,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { AXL_EVENT_TYPES, AXL_EVENT_TYPES_V2, AXL_TOOL_LIFECYCLE_TYPES_V2, AZURE_PROFILE, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type ApiKeySource, type AskOptions, type AskScoped, type AuthHeader, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, type AxlEventV2, type AxlEventV2Of, AxlRuntime, AxlStream, BEDROCK_PROFILE, BUILTIN_PROFILES, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CapabilityFlags, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, DEEPSEEK_PROFILE, type DecisionCleanupFailedEvent, type DelegateData, type DelegateOptions, type Effort, type EffortResolution, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type EventStreamOptions, EventStreamOverflowError, type ExecuteOptions, type ExecutionInfo, type ExecutionInfoV1, type ExecutionInfoV2, type ExecutionState, GROQ_PROFILE, GeminiProvider, GeminiTranscriptionProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HistoricalAxlEvent, type HistoricalExecutionInfo, type HumanDecision, InMemoryVectorStore, type InputContentPart, type InputGuardrail, type InputImagePart, type InputMediaSource, type InputModalitySupport, type InputTextPart, InvalidModelInputError, InvalidTranscriptionInputError, LLAMACPP_PROFILE, LMSTUDIO_PROFILE, type LegacyAxlEventV1, type LegacyExecutionInfoV1, MAX_INLINE_MODEL_INPUT_BYTES, MAX_INLINE_TRANSCRIPTION_BYTES, MISTRAL_PROFILE, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, type ModelInput, type ModelInputDescriptor, NoConsensus, NoopSpanManager, OLLAMA_PROFILE, OPENAI_PRICING, OPENAI_PROFILE, OPENROUTER_PROFILE, type ObservationStatus, type OpenAICompatibleOptions, OpenAICompatibleProvider, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, OpenAITranscriptionProvider, OpenRouterTranscriptionProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type PerModel, type PricingSource, type PricingTable, type Provider, type ProviderAdapter, type ProviderDiagnosticData, ProviderError, type ProviderInputValidationRequest, type ProviderInputValidationResult, type ProviderProfile, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RateLimitConfig, RateLimiter, type ReasoningCapture, type ReasoningEmit, type ReasoningProfile, type ReasoningRoundTrip, type RecallOptions, type RecallResult, type RecordedAudioSource, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryFeedbackHook, type RetryFeedbackInfo, type RetryFeedbackResult, type RetryPolicy, SGLANG_PROFILE, SQLiteStore, type SchemaCheckData, type SchemaDiagnosticData, type SchemaPromptOption, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StringDeltaData, type StringStreamEvent, type StringStreamFilter, type TelemetryConfig, ThinkTagScanner, TimeoutError, type Tool, type ToolApprovalData, type ToolArgumentIssue, type ToolCallCancellation, type ToolCallData, type ToolCallEndData, type ToolCallFailure, type ToolCallMessage, type ToolCallOutcome, type ToolCallRejectedData, type ToolCallRejectedEvent, type ToolCallStartData, type ToolCallStartDataV2, type ToolChoice, type ToolConfig, type ToolDeniedData, type ToolEventError, ToolFailure, type ToolFailureConstructor, type ToolFailureOptions, type ToolHooks, type ToolLifecycleEventV2, type ToolModelOutput, ToolModelOutputError, type Transcript, type TranscriptionCapabilities, TranscriptionOperationError, type TranscriptionProvider, TranscriptionProviderRegistry, type TranscriptionProviderRequest, type TranscriptionProviderResult, type TranscriptionRequest, UnsupportedEventSchemaVersionError, UnsupportedModelInputError, UnsupportedTranscriptionInputError, VLLM_PROFILE, type ValidateData, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, type VerifyData, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndData, type WorkflowStartData, XAI_PROFILE, agent, createSpanManager, defineConfig, estimateOpenAICost, eventCostContribution, expandGlob, extractJson, extractThinkTags, findConfig, getEventSchemaVersion, getExecutionEventSchemaVersion, hasPositiveBillableWork, hasPositiveTokens, importModule, inputText, isCostBearingLeaf, isRetryableStatus, isRootLevel, isUnpricedLeaf, isUsableCost, needsTsxLoader, normalizeStoredExecution, openaiReasoningEmit, parsePartialJson, pickDefault, pickExport, priceFromTable, reasoningEffortEmit, reasoningObjectEmit, redactEvent, redactHistoricalEvent, registerConditions, resolveApiKey, resolvePerModel, resolveRuntime, resolveThinkingOptions, stringStreamFromEvents, tool, workflow, zodToJsonSchema };
+export { AXL_EVENT_TYPES, AXL_EVENT_TYPES_V2, AXL_TOOL_LIFECYCLE_TYPES_V2, AZURE_PROFILE, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type ApiKeySource, type AskOptions, type AskScoped, type AuthHeader, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, type AxlEventV2, type AxlEventV2Of, AxlRuntime, AxlStream, BEDROCK_PROFILE, BUILTIN_PROFILES, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallTiming, type CapabilityFlags, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, DEEPSEEK_PROFILE, type DecisionCleanupFailedEvent, type DelegateData, type DelegateOptions, type Effort, type EffortResolution, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type EventStreamOptions, EventStreamOverflowError, type ExecuteOptions, type ExecutionInfo, type ExecutionInfoV1, type ExecutionInfoV2, type ExecutionState, GROQ_PROFILE, GeminiProvider, GeminiTranscriptionProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HistoricalAxlEvent, type HistoricalExecutionInfo, type HumanDecision, InMemoryVectorStore, type InputContentPart, type InputGuardrail, type InputImagePart, type InputMediaSource, type InputModalitySupport, type InputTextPart, InvalidModelInputError, InvalidTranscriptionInputError, LLAMACPP_PROFILE, LMSTUDIO_PROFILE, type LegacyAxlEventV1, type LegacyExecutionInfoV1, MAX_INLINE_MODEL_INPUT_BYTES, MAX_INLINE_TRANSCRIPTION_BYTES, MISTRAL_PROFILE, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, type ModelInput, type ModelInputDescriptor, NoConsensus, NoopSpanManager, OLLAMA_PROFILE, OPENAI_PRICING, OPENAI_PROFILE, OPENROUTER_PROFILE, type ObservationStatus, type OpenAICompatibleOptions, OpenAICompatibleProvider, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, OpenAITranscriptionProvider, OpenRouterTranscriptionProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type PerModel, type PricingSource, type PricingTable, type Provider, type ProviderAdapter, type ProviderDiagnosticData, ProviderError, type ProviderInputValidationRequest, type ProviderInputValidationResult, type ProviderProfile, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RateLimitConfig, RateLimiter, type ReasoningCapture, type ReasoningEmit, type ReasoningProfile, type ReasoningRoundTrip, type RecallOptions, type RecallResult, type RecordedAudioSource, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryFeedbackHook, type RetryFeedbackInfo, type RetryFeedbackResult, type RetryPolicy, SGLANG_PROFILE, SQLiteStore, type SchemaCheckData, type SchemaDiagnosticData, type SchemaPromptOption, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, StallTimeoutError, type StateStore, type StreamChunk, type StringDeltaData, type StringStreamEvent, type StringStreamFilter, type TelemetryConfig, ThinkTagScanner, type TimeoutBreakdown, TimeoutError, type Tool, type ToolApprovalData, type ToolArgumentIssue, type ToolCallCancellation, type ToolCallData, type ToolCallEndData, type ToolCallFailure, type ToolCallMessage, type ToolCallOutcome, type ToolCallRejectedData, type ToolCallRejectedEvent, type ToolCallStartData, type ToolCallStartDataV2, type ToolChoice, type ToolConfig, type ToolDeniedData, type ToolEventError, ToolFailure, type ToolFailureConstructor, type ToolFailureOptions, type ToolHooks, type ToolLifecycleEventV2, type ToolModelOutput, ToolModelOutputError, type Transcript, type TranscriptionCapabilities, TranscriptionOperationError, type TranscriptionProvider, TranscriptionProviderRegistry, type TranscriptionProviderRequest, type TranscriptionProviderResult, type TranscriptionRequest, UnsupportedEventSchemaVersionError, UnsupportedModelInputError, UnsupportedTranscriptionInputError, VLLM_PROFILE, type ValidateData, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, type VerifyData, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndData, type WorkflowStartData, XAI_PROFILE, agent, createSpanManager, defineConfig, estimateOpenAICost, eventCostContribution, expandGlob, extractJson, extractThinkTags, findConfig, getEventSchemaVersion, getExecutionEventSchemaVersion, hasPositiveBillableWork, hasPositiveTokens, importModule, inputText, isCostBearingLeaf, isRetryableStatus, isRootLevel, isUnpricedLeaf, isUsableCost, needsTsxLoader, normalizeStoredExecution, openaiReasoningEmit, parsePartialJson, pickDefault, pickExport, priceFromTable, reasoningEffortEmit, reasoningObjectEmit, redactEvent, redactHistoricalEvent, registerConditions, resolveApiKey, resolvePerModel, resolveRuntime, resolveThinkingOptions, stringStreamFromEvents, tool, workflow, zodToJsonSchema };