@axlsdk/axl 0.22.2 → 0.23.0

package/dist/index.d.ts

@@ -128,6 +128,12 @@ type ChatOptions = {
      *  '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 +193,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.
@@ -228,7 +240,56 @@ 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.
+     *
+     * Adapters clamp `effort` to what each model actually accepts (Gemini 3.x
+     * cannot disable thinking; OpenAI Chat Completions caps `'max'` at `'xhigh'`;
+     * Anthropic models that always think fall back to adaptive `'low'`). That
+     * clamp used to be invisible to run provenance. The runtime calls this once
+     * per ask, right after provider resolution, and emits a
+     * `provider_diagnostic { kind: 'effort_clamped' }` event plus a deduped
+     * `console.warn` when `clamped` is true — the adapter only *reports*, the
+     * runtime decides how to surface it (only the runtime can see
+     * `AxlConfig.diagnostics.silent`).
+     *
+     * The adapter applies its own `providerOptions.model` override before
+     * resolving, so the report describes the model actually sent.
+     *
+     * Optional, and optional to answer: return `undefined` when there is nothing
+     * to report (no effort requested, the model is unknown, or the effort is
+     * honored verbatim). An adapter MAY also report an honored resolution with
+     * `clamped: false`; the runtime stays silent for those.
+     */
+    effortResolution?(options: Pick<ChatOptions, 'model' | 'effort' | 'thinkingBudget' | 'includeThoughts' | 'providerOptions'>): EffortResolution | undefined;
 }
+/**
+ * An adapter's report of how it resolved the unified `effort` for one request.
+ *
+ * `effective` is a provider-NATIVE level string rather than an `Effort` because
+ * not every effective value maps back onto the unified union (Gemini's
+ * `'minimal'`, OpenAI's `'minimal'`, Anthropic's adaptive `'low'`).
+ */
+type EffortResolution = {
+    /** The unified effort the caller asked for. */
+    requested: Effort;
+    /** The provider-native level actually sent (e.g. `'minimal'`, `'xhigh'`, `'low'`). */
+    effective: string;
+    /** True when `effective` is not what `requested` asked for. */
+    clamped: boolean;
+    /** Human-readable reason, surfaced verbatim on the diagnostic event. */
+    cause?: string;
+};
 /**
  * Alias for Provider. Used for backward compatibility with index.ts exports.
  */
@@ -374,6 +435,10 @@ type AskOptions<T = unknown> = {
     validate?: OutputValidator<T>;
     /** Maximum retries for validate failures (default: 2). */
     validateRetries?: number;
+    /** Rewrite the corrective feedback the model sees when the guardrail, schema, or validate
+     *  gate rejects an attempt — or abort the retry with `{ retry: false }`. See
+     *  `RetryFeedbackHook`. */
+    retryFeedback?: RetryFeedbackHook<T>;
     /** Per-call metadata passed to dynamic model/system selector functions. */
     metadata?: Record<string, unknown>;
     /** Override temperature for this call. */
@@ -386,6 +451,8 @@ 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. */
@@ -415,6 +482,9 @@ type DelegateOptions<T = unknown> = {
     validate?: OutputValidator<T>;
     /** Maximum retries for validate failures (default: 2). Passed through to the final `ctx.ask()` call. */
     validateRetries?: number;
+    /** Custom gate-retry feedback. Passed through to the final `ctx.ask()` call on both the
+     *  single-candidate and the routed path. See `RetryFeedbackHook`. */
+    retryFeedback?: RetryFeedbackHook<T>;
 };
 /** Race options */
 type RaceOptions<T = unknown> = {
@@ -430,11 +500,11 @@ 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", "transcription_start", "transcription_end", "ask_start", "ask_end", "agent_call_start", "agent_call_end", "token", "tool_call_start", "tool_call_end", "tool_call_rejected", "tool_approval", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "string_delta", "verify", "schema_diagnostic", "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", "transcription_start", "transcription_end", "ask_start", "ask_end", "agent_call_start", "agent_call_end", "token", "tool_call_start", "tool_call_end", "tool_call_rejected", "tool_approval", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "string_delta", "verify", "schema_diagnostic", "provider_diagnostic", "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];
 /** Backward-compatible name for the canonical v2 writer discriminator list. */
-declare const AXL_EVENT_TYPES_V2: readonly ["workflow_start", "workflow_end", "transcription_start", "transcription_end", "ask_start", "ask_end", "agent_call_start", "agent_call_end", "token", "tool_call_start", "tool_call_end", "tool_call_rejected", "tool_approval", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "string_delta", "verify", "schema_diagnostic", "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_V2: readonly ["workflow_start", "workflow_end", "transcription_start", "transcription_end", "ask_start", "ask_end", "agent_call_start", "agent_call_end", "token", "tool_call_start", "tool_call_end", "tool_call_rejected", "tool_approval", "delegate", "handoff_start", "handoff_return", "pipeline", "partial_object", "string_delta", "verify", "schema_diagnostic", "provider_diagnostic", "log", "memory_remember", "memory_recall", "memory_forget", "checkpoint_save", "checkpoint_replay", "await_human", "await_human_resolved", "guardrail", "schema_check", "validate", "done", "error"];
 /** Accepted/rejected tool lifecycle discriminators in event schema v2. */
 declare const AXL_TOOL_LIFECYCLE_TYPES_V2: readonly ["tool_call_start", "tool_call_end", "tool_call_rejected"];
 /** Resolved model parameters sent to the provider for an LLM call. */
@@ -779,6 +849,34 @@ type SchemaDiagnosticData = {
     provider?: string;
     support: 'downgraded' | 'lossy' | 'unsupported';
 };
+/**
+ * Data for the `provider_diagnostic` event — a `kind`-discriminated payload
+ * (like `SchemaDiagnosticData`) reporting that the resolved provider could not
+ * honor a portable request knob verbatim.
+ *
+ *  - `effort_clamped` — the adapter clamped the unified `effort` to what the
+ *    model actually accepts (Gemini 3.x cannot disable thinking; OpenAI Chat
+ *    Completions caps `'max'` at `'xhigh'`; Anthropic models that always think
+ *    fall back to adaptive `'low'`). `requested` is the unified value the caller
+ *    asked for; `effective` is the provider-native level actually sent, which is
+ *    deliberately a free string because not every native level maps back onto
+ *    `Effort`. One per ask, emitted before the first `agent_call_start` — join it
+ *    to `agent_call_start` (which keeps reporting the *requested* effort) by
+ *    `askId` for full provenance.
+ *
+ * The union is `kind`-discriminated so later provider cliffs can join without a
+ * new event type.
+ */
+type ProviderDiagnosticData = {
+    kind: 'effort_clamped';
+    /** Provider name (`provider.name`), when the adapter exposes one. */
+    provider?: string;
+    /** The model the request is actually sent to (after any `providerOptions.model`). */
+    model: string;
+    requested: Effort;
+    effective: string;
+    cause: string;
+};
 /** Data shape for legacy `guardrail` events. Replaced by `pipeline` in PR 2. */
 type GuardrailData = {
     guardrailType: 'input' | 'output';
@@ -1045,6 +1143,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 & {
@@ -1132,6 +1236,9 @@ type LegacyAxlEventPayloadV1 = (AxlEventBase & {
 }) | (AxlEventBase & AskScoped & {
     type: 'schema_diagnostic';
     data: SchemaDiagnosticData;
+}) | (AxlEventBase & AskScoped & {
+    type: 'provider_diagnostic';
+    data: ProviderDiagnosticData;
 }) | (AxlEventBase & Partial<AskScoped> & {
     type: 'guardrail';
     data?: GuardrailData;
@@ -1319,6 +1426,43 @@ type ValidateResult = {
 type OutputValidator<T = unknown> = (output: T, ctx: {
     metadata: Record<string, unknown>;
 }) => ValidateResult | Promise<ValidateResult>;
+/** What a rejecting output gate tells a `retryFeedback` hook about the attempt it is
+ *  about to retry. One shape for all three gates — `stage` discriminates. */
+type RetryFeedbackInfo<T = unknown> = {
+    /** Which gate rejected: JSON/Zod parse, post-schema `validate`, or output guardrail. */
+    stage: 'schema' | 'validate' | 'guardrail';
+    /** 1-based index of the attempt that was just rejected. */
+    attempt: number;
+    /** Total attempts this gate allows (`retries` + 1). */
+    maxAttempts: number;
+    /** Raw model output that was rejected. */
+    output: string;
+    /** The parsed, schema-valid object, typed by the ask's `schema`. Present only for
+     *  `stage: 'validate'` — the other gates run before or without a parsed value. */
+    parsed?: T;
+    /** The gate's own reason (Zod message, `ValidateResult.reason`, guardrail reason). */
+    reason: string;
+    /** The `ZodError` (or non-Zod parse error) for `schema`; the validator's thrown error for
+     *  `validate` when it threw. Absent for `guardrail` and for a clean `validate` rejection. */
+    error?: unknown;
+    /** The feedback text the runtime would send if the hook did not intervene. */
+    defaultMessage: string;
+};
+/** A non-empty string replaces `defaultMessage` verbatim; `undefined` (or `''`) keeps it;
+ *  `{ retry: false }` stops retrying and makes the gate throw its typed terminal error. */
+type RetryFeedbackResult = string | undefined | {
+    retry: false;
+};
+/** Rewrites (or aborts) the corrective turn the model sees after an output gate rejects an
+ *  attempt. Runs only while a retry is still permitted — never on the exhausting attempt —
+ *  and after the gate's own event is emitted. Exceptions propagate to the caller.
+ *
+ *  `void` is accepted alongside `RetryFeedbackResult` so a hook used purely for logging or
+ *  inspection — a block body that never returns — type-checks; it keeps the default text.
+ *  Any other return value is a contract violation and throws a `TypeError`. */
+type RetryFeedbackHook<T = unknown> = (info: RetryFeedbackInfo<T>, ctx: {
+    metadata: Record<string, unknown>;
+}) => RetryFeedbackResult | void | Promise<RetryFeedbackResult | void>;
 /** Execution info */
 type ExecutionInfoV1 = {
     executionId: string;
@@ -1434,6 +1578,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;
@@ -1443,6 +1594,51 @@ 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`. 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 the cumulative time spent
+     * *awaiting* body reads — time the runtime spends between reads (event
+     * fan-out, tool-call buffering, a slow `ctx.events` consumer) is excluded by
+     * construction, so two models stay comparable under different listener loads.
+     */
+    wireMs: number;
+};
 /** Provider response */
 type ProviderResponse = {
     content: string;
@@ -1460,6 +1656,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 */
@@ -1580,9 +1778,29 @@ 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);
 }
 /** Thrown when a budget limit is exceeded */
 declare class BudgetExceededError extends AxlError {
@@ -1639,6 +1857,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.
@@ -2069,11 +2290,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
@@ -2403,7 +2627,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;
@@ -3408,6 +3646,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?;
@@ -3534,6 +3779,20 @@ declare class WorkflowContext<TInput = unknown> {
     private observeToolInvocation;
     ask<T = string>(agent: Agent, prompt: ModelInput, options?: AskOptions<T>): Promise<T>;
     private executeAgentCall;
+    /**
+     * 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.
+     *
+     * Called by all three output gates, only while a retry is still permitted (never on the
+     * exhausting attempt) and only after the gate's own event has been emitted, so a hook that
+     * throws or aborts can never erase the evidence that the gate rejected. A non-empty string
+     * replaces `defaultMessage` verbatim; `undefined` / `''` keeps it; `{ retry: false }` asks
+     * the gate to throw its typed terminal error. Hook exceptions propagate — a bug in caller
+     * code is not a model failure and must not be retried into silence, and neither is a
+     * return value outside the contract: an unrecognized shape throws instead of silently
+     * degrading to the default text, which would hide the defect behind extra token spend.
+     */
+    private resolveRetryFeedback;
     /**
      * Push the final assistant message into session history, preserving providerMetadata
      * (e.g., Gemini thought signatures needed for multi-turn reasoning context) and
@@ -3557,6 +3816,20 @@ declare class WorkflowContext<TInput = unknown> {
      * (expected behavior for any tool-using agent, not a surprise).
      */
     private emitSchemaDiagnostics;
+    /**
+     * Emit a `provider_diagnostic` when the resolved provider reports that it
+     * could not honor the unified `effort` verbatim (P3/R6/R7).
+     *
+     * The adapter only *resolves* — it returns the requested and effective levels
+     * from the same pure resolver its request builder uses. The runtime decides
+     * how to surface that, because only the runtime can see the event bus and
+     * `AxlConfig.diagnostics.silent` (adapters receive `ProviderConfig` only).
+     *
+     * Called once per ask, so a tool loop with N provider round trips still emits
+     * one event; the `console.warn` dedupes once per process per distinct clamp.
+     * A throwing `effortResolution` is a provider bug and propagates.
+     */
+    private emitProviderDiagnostics;
     private buildToolDefs;
     /**
      * Summarize old messages to fit within context window.
@@ -4504,12 +4777,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[];
@@ -5145,6 +5468,7 @@ declare const REDACTION_RULES: {
     string_delta: RuleFor<"string_delta">;
     verify: RuleFor<"verify">;
     schema_diagnostic: RuleFor<"schema_diagnostic">;
+    provider_diagnostic: RuleFor<"provider_diagnostic">;
     log: RuleFor<"log">;
     memory_remember: RuleFor<"memory_remember">;
     memory_recall: RuleFor<"memory_recall">;
@@ -5211,6 +5535,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;
@@ -5219,6 +5553,7 @@ declare class ProviderError extends AxlError {
         retryAfterMs?: number;
         requestId?: string;
         body?: string;
+        timing?: CallTiming;
     });
 }
 /**
@@ -5272,6 +5607,9 @@ declare class OpenAIProvider extends OpenAICompatibleProvider {
         dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
+    /** Report a clamped `effort` — Chat Completions caps `'max'` at `'xhigh'` and
+     *  rejects `'none'` before gpt-5.1 (clamped to `'minimal'`). */
+    effortResolution(options: Pick<ChatOptions, 'model' | 'effort' | 'thinkingBudget' | 'includeThoughts' | 'providerOptions'>): EffortResolution | undefined;
     protected computeCost(model: string, usage: ProviderResponse['usage'], _reportedCost: number | undefined, context?: DirectOpenAIPricingContext): number | undefined;
 }
 
@@ -5289,6 +5627,10 @@ declare class OpenAIResponsesProvider implements Provider {
             sources: readonly InputMediaSource['type'][];
         };
     };
+    /** Report a clamped `effort`. Responses accepts the native `'max'` tier that
+     *  Chat Completions caps, but still clamps `'none'` before gpt-5.1, `'xhigh'`
+     *  below gpt-5.2, and everything to `'high'` on gpt-5-pro. */
+    effortResolution(options: Pick<ChatOptions, 'model' | 'effort' | 'thinkingBudget' | 'includeThoughts' | 'providerOptions'>): EffortResolution | undefined;
     validateInput(request: ProviderInputValidationRequest): ProviderInputValidationResult;
     /** The Responses API honors `json_schema` (structured outputs) natively. */
     nativeStructuredOutputSupport(): 'schema';
@@ -5342,6 +5684,12 @@ declare class OpenAIResponsesProvider implements Provider {
  */
 declare class AnthropicProvider implements Provider {
     readonly name = "anthropic";
+    /** 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
+     *  effective level is what the request body actually carries; an explicit
+     *  `thinkingBudget` is documented to override `effort`, so it is not a clamp. */
+    effortResolution(options: Pick<ChatOptions, 'model' | 'effort' | 'thinkingBudget' | 'includeThoughts' | 'providerOptions'>): EffortResolution | undefined;
     inputCapabilities(model: string): {
         image?: {
             sources: readonly InputMediaSource['type'][];
@@ -5350,6 +5698,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;
@@ -5428,6 +5778,11 @@ declare class GeminiProvider implements Provider {
      *  keywords it doesn't support (`$ref`/`$defs`/`additionalProperties`/…), so a
      *  derived schema can lose constraints — lossy, not faithful. */
     nativeStructuredOutputSupport(): 'lossy';
+    /** Report a clamped `effort` (R7a). Gemini 3.x cannot disable thinking and
+     *  caps at `'high'`, so `'none'`, `'xhigh'` and `'max'` are not honored
+     *  verbatim there. Everything else — including 2.x disabled thinking — is
+     *  sent as asked, so there is nothing to report. */
+    effortResolution(options: Pick<ChatOptions, 'model' | 'effort' | 'thinkingBudget' | 'includeThoughts' | 'providerOptions'>): EffortResolution | undefined;
     private baseUrl;
     private apiKeySource;
     private callCounter;
@@ -6109,4 +6464,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 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, 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 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, 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 };