@axlsdk/axl 0.18.2 → 0.19.0

package/dist/index.d.ts

@@ -132,6 +132,28 @@ interface Provider {
      * Stream a chat completion, yielding chunks as they arrive.
      */
     stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
+    /**
+     * How this provider honors a `responseFormat: { type: 'json_schema' }` derived
+     * from the caller's Zod schema, for `model` (spec 22, Problem B / R10). Used by
+     * the runtime to warn — via a `schema_diagnostic` — when `nativeStructuredOutput`
+     * can't be honored, WITHOUT failing the call (portable multi-provider code must
+     * still run). Optional: an adapter that omits it is assumed to honor the schema
+     * fully (`'schema'`), so unknown adapters simply opt out of the warning.
+     *
+     *  - `'schema'` — accepts a `json_schema` response format for this model (the
+     *    strongest tier; e.g. OpenAI/Responses). Note: Axl currently sends
+     *    NON-strict `json_schema` (it does not set `strict: true`), so on OpenAI
+     *    this is schema-as-guidance, not hard constrained decoding — true strict
+     *    mode needs an OpenAI-strict-subset schema transform and is a follow-up.
+     *  - `'downgraded'` — accepted but downgraded to plain `json_object`; the schema
+     *    shape is NOT enforced structurally (e.g. an OpenAI-compatible profile with
+     *    `supportsJsonSchema: false`).
+     *  - `'lossy'` — accepted but the schema is sanitized and may lose keywords
+     *    (e.g. Gemini strips `$ref`/`$defs`/`additionalProperties`).
+     *  - `'unsupported'` — ignored structurally; the provider relies on the prompt
+     *    JSON instruction instead (e.g. Anthropic).
+     */
+    nativeStructuredOutputSupport?(model: string): 'schema' | 'downgraded' | 'lossy' | 'unsupported';
 }
 /**
  * Alias for Provider. Used for backward compatibility with index.ts exports.
@@ -155,6 +177,15 @@ type ResolvedThinkingOptions = {
 /** Resolve effort/thinkingBudget/includeThoughts into normalized form.
  *  Validates inputs and computes derived flags used by all provider adapters. */
 declare function resolveThinkingOptions(options: Pick<ChatOptions, 'effort' | 'thinkingBudget' | 'includeThoughts'>): ResolvedThinkingOptions;
+/**
+ * An API key, or a function that produces one per request. The function form
+ * supports expiring credentials (Azure-Entra, Databricks/IBM OAuth, Bedrock
+ * short-term tokens): the caller's callback owns refresh/caching; Axl invokes it
+ * once per request and does not memoize. See `docs/providers.md`.
+ */
+type ApiKeySource = string | (() => string | Promise<string>);
+/** Resolve an {@link ApiKeySource} to a concrete key for a single request. */
+declare function resolveApiKey(source: ApiKeySource | undefined): Promise<string>;
 
 /** Result type for concurrent operations (spawn, map) */
 type Result<T> = {
@@ -169,6 +200,14 @@ type BudgetResult<T> = {
     value: T | null;
     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.
+     */
+    unpriced: boolean;
 };
 /** Human decision from awaitHuman */
 type HumanDecision = {
@@ -226,9 +265,34 @@ type AwaitHumanOptions = {
     prompt: string;
     metadata?: Record<string, unknown>;
 };
+/**
+ * Controls how the output `schema` is rendered into the MODEL-FACING prompt
+ * (spec 22, Problem B). Independent of the `.parse` gate — whichever mode you
+ * pick, the full Zod `schema` still validates the reply.
+ *
+ *  - `'json-schema'` (default) — append the compact, `$ref`-hoisted JSON-Schema
+ *    guidance (`Respond with valid JSON matching this schema: …`).
+ *  - `'none'` — append NOTHING; the schema is the parse gate only. Fires a
+ *    `schema_prompt_none_no_guidance` diagnostic (the model gets zero shape hint).
+ *  - `{ render }` — append exactly this string, or the string your function
+ *    returns from the schema. Object form (not a bare string) so custom text can
+ *    never collide with the `'none'` / `'json-schema'` sentinels.
+ */
+type SchemaPromptOption = 'json-schema' | 'none' | {
+    render: string | ((schema: z.ZodType<unknown>) => string);
+};
 /** Ask options */
 type AskOptions<T = unknown> = {
     schema?: z.ZodType<T>;
+    /** How the `schema` is rendered into the model-facing prompt. Default
+     *  `'json-schema'`. Does not affect the `.parse` gate. See `SchemaPromptOption`. */
+    schemaPrompt?: SchemaPromptOption;
+    /** Opt into the provider's NATIVE structured-output path (`json_schema`),
+     *  deriving the provider schema from `schema` (no second, contradictable
+     *  schema). Providers that can't honor it downgrade/ignore it and a
+     *  `schema_diagnostic` warns; the call still proceeds. Only takes effect when
+     *  a `schema` is set and no tools are registered. Default `false`. */
+    nativeStructuredOutput?: boolean;
     retries?: number;
     /** Post-schema business rule validation. Receives the parsed typed object after schema
      *  validation succeeds. Only runs when `schema` is set. Retries with accumulating context
@@ -259,6 +323,12 @@ type AskOptions<T = unknown> = {
 type DelegateOptions<T = unknown> = {
     /** Zod schema for structured output from the selected agent. */
     schema?: z.ZodType<T>;
+    /** How the `schema` is rendered into the selected agent's prompt. Forwarded to
+     *  the terminal `ctx.ask()`. See `SchemaPromptOption`. */
+    schemaPrompt?: SchemaPromptOption;
+    /** Opt the terminal `ctx.ask()` into the provider's native structured-output
+     *  path. Forwarded to the selected agent's ask. */
+    nativeStructuredOutput?: boolean;
     /** Model URI for the internal router agent (default: first candidate's model). */
     routerModel?: string;
     /** Additional metadata passed to the router and selected agent. */
@@ -284,7 +354,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", "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"];
+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", "schema_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];
 /** Resolved model parameters sent to the provider for an LLM call. */
@@ -343,6 +413,13 @@ type AgentCallEndData = {
      *  abort, etc). Mutually exclusive with `response` content. Subject to
      *  `config.trace.redact` (vendor errors can echo prompt text). */
     error?: string;
+    /** HTTP status when the thrown error was a `ProviderError` (`0` for network
+     *  failures). Omitted for non-provider errors. The raw error body is
+     *  intentionally NOT placed on the event (it's redaction-eligible). */
+    status?: number;
+    /** Semantic failover hint from a thrown `ProviderError` (see
+     *  `ProviderError.retryable`). Omitted for non-provider errors. */
+    retryable?: boolean;
 };
 /** Data shape for `tool_call_end` events. */
 type ToolCallData = {
@@ -434,6 +511,51 @@ type StringDeltaData = {
      */
     delta: string;
 };
+/**
+ * Data for the `schema_diagnostic` event (spec 22, Problem E) — a `kind`-
+ * discriminated payload mirroring `pipeline`'s two-level union. Each variant
+ * surfaces one silent structured-output cliff:
+ *
+ *  - `prompt_schema_oversized` — an appended prompt schema (or a tool-def
+ *    schema) exceeds the token threshold; the schema is a recurring input cost.
+ *  - `dropped_refinements` — the schema carries `.refine()`/`.superRefine()`
+ *    rules `z.toJSONSchema` drops, so the model is never told and `.parse` may
+ *    reject → wasted retries. `paths` are structural field paths (not PII).
+ *  - `streaming_disabled` — progressive `partial_object` streaming is off
+ *    because the schema root isn't a `ZodObject` (`non-object`) or tools are
+ *    present (`tools`).
+ *  - `schema_prompt_none_no_guidance` — `schemaPrompt:'none'` was set with a
+ *    schema and no override, so the model gets zero shape guidance (parse gate
+ *    only). Emitted from the Problem-B path (spec 22 §5.3).
+ */
+type SchemaDiagnosticData = {
+    kind: 'prompt_schema_oversized';
+    estimatedTokens: number;
+    threshold: number;
+    site: 'prompt' | 'tool';
+    tool?: string;
+} | {
+    kind: 'dropped_refinements';
+    count: number;
+    paths?: string[];
+    site: 'prompt' | 'tool';
+    tool?: string;
+} | {
+    kind: 'streaming_disabled';
+    rootType: string;
+    cause: 'non-object' | 'tools';
+} | {
+    kind: 'schema_prompt_none_no_guidance';
+} | {
+    /** `nativeStructuredOutput` was requested but the resolved provider can't
+     *  honor the derived schema — it downgrades it to plain JSON mode
+     *  (`downgraded`), sanitizes it lossily (`lossy`, e.g. Gemini strips
+     *  keywords), or ignores it structurally and relies on the prompt
+     *  (`unsupported`, e.g. Anthropic). The call proceeds regardless (O5). */
+    kind: 'native_output_unsupported';
+    provider?: string;
+    support: 'downgraded' | 'lossy' | 'unsupported';
+};
 /** Data shape for legacy `guardrail` events. Replaced by `pipeline` in PR 2. */
 type GuardrailData = {
     guardrailType: 'input' | 'output';
@@ -556,7 +678,9 @@ type AxlEventBase = {
      *   - **Leaf cost** (`agent_call_end`, `tool_call_end`, `memory_remember`,
      *     `memory_recall`): the authoritative charge for this single
      *     provider call / tool invocation / embedder call. Summing these
-     *     across an execution gives the true spend.
+     *     across an execution gives the spend — a LOWER BOUND when any call
+     *     used an unpriced model (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
      *     within this ask's frame, EXCLUDING nested asks (which roll up
@@ -658,6 +782,12 @@ type AxlEvent = (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`
+     *  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. */
+    unpriced?: boolean;
     duration: number;
 }) | (AxlEventBase & AskScoped & {
     type: 'agent_call_start';
@@ -671,8 +801,9 @@ type AxlEvent = (AxlEventBase & {
     type: 'agent_call_end';
     agent: string;
     model: string;
-    /** Authoritative turn-level cost. */
-    cost: number;
+    /** Authoritative turn-level cost. `undefined` for an unpriced model
+     *  (pricing-table miss) and absent on the error path (no usage). */
+    cost?: number;
     duration: number;
     tokens?: {
         input?: number;
@@ -763,6 +894,9 @@ type AxlEvent = (AxlEventBase & {
 }) | (AxlEventBase & AskScoped & {
     type: 'verify';
     data: VerifyData;
+}) | (AxlEventBase & AskScoped & {
+    type: 'schema_diagnostic';
+    data: SchemaDiagnosticData;
 }) | (AxlEventBase & Partial<AskScoped> & {
     type: 'guardrail';
     data?: GuardrailData;
@@ -849,7 +983,17 @@ type ExecutionInfo = {
      *  here (stream-only); aggregate `tokens: { input, output, reasoning? }`
      *  on `agent_call_end` is the persisted token representation. */
     events: AxlEvent[];
+    /** Total spend for the execution. A LOWER BOUND when an unpriced model 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
+     *  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
+     *  before this field existed (back-compat). */
+    unpriced?: boolean;
     startedAt: number;
     completedAt?: number;
     duration: number;
@@ -892,6 +1036,8 @@ type AgentCallInfo = {
     response: string;
     model: string;
     cost: number;
+    /** True when `cost` is a lower bound because the call tree included unpriced work. */
+    unpriced: boolean;
     duration: number;
     promptVersion?: string;
     temperature?: number;
@@ -983,6 +1129,12 @@ type AgentConfig = {
     stop?: string[];
     /** 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.
+     *  Overridable per-call via `AskOptions.schemaPrompt`. See `SchemaPromptOption`. */
+    schemaPrompt?: SchemaPromptOption;
+    /** Default opt-in to the provider's native structured-output path for this
+     *  agent. Overridable per-call via `AskOptions.nativeStructuredOutput`. */
+    nativeStructuredOutput?: boolean;
     maxTurns?: number;
     timeout?: string;
     maxContext?: number;
@@ -1496,6 +1648,278 @@ declare class RateLimiter {
     private clearWaiterTimers;
 }
 
+/**
+ * A profile value that may legitimately differ per model within one provider.
+ * Mirrors the model-aware shape of OpenAI's `clampReasoningEffort(model, …)`.
+ * Use a function ONLY where the provider's constraints are genuinely per-model
+ * (e.g. xAI reasoning vs chat variants, Mistral `magistral-*`); a plain value
+ * otherwise.
+ */
+type PerModel<T> = T | ((model: string) => T);
+/** Resolve a {@link PerModel} value against a concrete model id. */
+declare function resolvePerModel<T>(value: PerModel<T> | undefined, model: string, fallback: T): T;
+/**
+ * Auth header shape.
+ * - `'bearer'` → `Authorization: Bearer <key>` (OpenAI and most providers).
+ * - `'api-key'` → `api-key: <key>` (Azure OpenAI key auth — no scheme).
+ * - object → arbitrary header name + optional scheme prefix.
+ */
+type AuthHeader = 'bearer' | 'api-key' | {
+    header: string;
+    scheme?: string;
+};
+/** `[inputRatePerToken, outputRatePerToken, cachedInputMultiplier]`. */
+type PricingTable = Record<string, [number, number, number]>;
+/**
+ * How per-call cost is derived. A miss is **never** silently `0` — it surfaces
+ * as `undefined` ("unmeasured") so `ctx.budget()` doesn't treat paid models as
+ * free. See spec §6.
+ */
+type PricingSource = {
+    kind: 'table';
+    table: PricingTable;
+}
+/** Provider reports per-call cost in `usage.cost` (OpenRouter credits ≈ USD). */
+ | {
+    kind: 'from-response';
+}
+/** Local/self-hosted: cost is genuinely 0. */
+ | {
+    kind: 'zero';
+}
+/** Non-token billing (credits/DBU/neurons): cost is unknowable → `undefined`. */
+ | {
+    kind: 'unknown';
+};
+/** How reasoning/thinking text is captured from a response (chat + stream). */
+type ReasoningCapture = 
+/** None — OpenAI Chat Completions has no reasoning surface. */
+'none'
+/** `message.reasoning_content` / `delta.reasoning_content` (DeepSeek, Fireworks, Together…). */
+ | 'reasoning_content'
+/** `message.reasoning` / `delta.reasoning` (Groq, Cloudflare). */
+ | 'reasoning'
+/** OpenRouter: `message.reasoning` text + `reasoning_details[]` for round-tripping. */
+ | 'reasoning_details'
+/** Inline `<think>…</think>` tags inside content (local R1-style models). */
+ | 'think_tags';
+/**
+ * Stateful, TURN-AWARE round-trip of captured reasoning on the next request.
+ * `'on-tool-call-turns'`: echo the captured reasoning back (via
+ * `providerMetadata`) on an assistant message that carried `tool_calls`, and
+ * only then. DeepSeek's `deepseek-reasoner` 400s on a tool loop if reasoning is
+ * not echoed on the tool-call turn; on a plain turn it must NOT be echoed.
+ */
+type ReasoningRoundTrip = 'none' | 'on-tool-call-turns';
+/**
+ * Mutates the request body to encode the resolved effort/thinking options into
+ * this provider's wire vocabulary. Returns `{ stripTemperature }` when the
+ * provider rejects/ignores `temperature` while reasoning is active.
+ */
+type ReasoningEmit = (body: Record<string, unknown>, resolved: ResolvedThinkingOptions, model: string) => {
+    stripTemperature?: boolean;
+} | void;
+/** Per-profile reasoning behavior — decoupled from any model-name regex. */
+type ReasoningProfile = {
+    /** Write the unified `effort`/`thinkingBudget` into the request body. */
+    emit: ReasoningEmit;
+    /** Read reasoning text out of responses/streams. */
+    capture: ReasoningCapture;
+    /** Echo captured reasoning back on subsequent requests. Default `'none'`. */
+    roundTrip?: ReasoningRoundTrip;
+};
+/** Wire-quirk capability flags. Each defaults to the OpenAI-correct value. */
+type CapabilityFlags = {
+    /**
+     * Emit `messages[].name` when set on a ChatMessage. OpenAI: true. Groq 400s
+     * on it → false. Message-level (not reachable via `providerOptions`).
+     */
+    emitsMessageName?: boolean;
+    /**
+     * Engine-COMPUTED request params to strip before sending (provider rejects
+     * them). `PerModel` because constraints are often per-model (e.g. `stop`
+     * 400s only on Grok reasoning variants). Stripping runs AFTER the
+     * `providerOptions` merge but EXEMPTS keys the user set explicitly there —
+     * re-introducing a forbidden param via `providerOptions` is "you-asked-for-it".
+     */
+    forbiddenParams?: PerModel<string[]>;
+    /**
+     * Provider honors `response_format` `json_schema` strict mode. When false and
+     * a `json_schema` format is requested, fall back to `{ type: 'json_object' }`.
+     */
+    supportsJsonSchema?: PerModel<boolean>;
+    /**
+     * Provider returns usage in the final stream chunk via
+     * `stream_options.include_usage`. When false, don't request it.
+     */
+    supportsStreamUsage?: boolean;
+};
+/**
+ * A provider definition. The engine reads ONLY this — adding a provider is
+ * adding a profile, not new engine code.
+ */
+type ProviderProfile = {
+    /** Machine name = `Provider.name` and the `provider:` URI scheme key. */
+    name: string;
+    /** Human label used in error messages (defaults to {@link name}). */
+    label?: string;
+    /** Base URL used when neither a constructor arg nor env var is set. */
+    defaultBaseUrl: string;
+    /**
+     * Require an explicit base URL (config `baseUrl` or `envBaseUrl`) — throw at
+     * construction if neither is set. For providers like Azure whose base URL is
+     * account/resource-specific and has no usable default.
+     */
+    requireExplicitBaseUrl?: boolean;
+    /** Env var consulted for the base URL (after the constructor arg). */
+    envBaseUrl?: string;
+    /** Env var consulted for the API key (after the constructor arg). */
+    envApiKey?: string;
+    /** Auth header shape. Default `'bearer'`. */
+    authHeader?: AuthHeader;
+    /** Extra static headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Allow an empty API key (local servers) → no auth header. Default false. */
+    allowMissingApiKey?: boolean;
+    /** How cost is derived. */
+    pricing: PricingSource;
+    /** Reasoning behavior. */
+    reasoning: ReasoningProfile;
+    /** Wire-quirk capability flags. */
+    capabilities?: CapabilityFlags;
+    /** Map a message role → wire role for a model. Default identity. */
+    roleFor?: (role: ChatRole, model: string) => string;
+    /** Output-token field name. Default `'max_completion_tokens'`. */
+    maxTokensField?: 'max_completion_tokens' | 'max_tokens';
+    /** Send `parallel_tool_calls: true` when tools are present. Default off. */
+    parallelToolCalls?: PerModel<boolean>;
+    /**
+     * Static body fields merged BEFORE `providerOptions` (e.g. OpenRouter
+     * `usage: { include: true }`). Treated as engine-computed for forbiddenParams.
+     */
+    requestDefaults?: Record<string, unknown>;
+};
+/**
+ * Look up per-token pricing by exact match, then longest-prefix match (for
+ * versioned snapshots like `gpt-4o-2024-05-13`). Returns `undefined` on a miss —
+ * callers MUST treat that as "unknown cost", never as free.
+ */
+declare function priceFromTable(table: PricingTable, model: string, promptTokens: number, completionTokens: number, cachedTokens?: number): number | undefined;
+/**
+ * Incremental scanner that separates streamed content into visible text and
+ * `<think>…</think>` reasoning, tolerating tags split across chunks.
+ */
+declare class ThinkTagScanner {
+    private buffer;
+    private inside;
+    push(chunk: string): {
+        text: string;
+        thinking: string;
+    };
+    /** Flush any residual buffer at stream end (treat as the current channel). */
+    flush(): {
+        text: string;
+        thinking: string;
+    };
+}
+/** Strip `<think>…</think>` from a complete (non-streamed) content string. */
+declare function extractThinkTags(content: string): {
+    content: string;
+    thinking: string;
+};
+/**
+ * Build a {@link ReasoningEmit} that writes a top-level `reasoning_effort`
+ * string (OpenAI-style; used by xAI, Groq, Mistral). `map` returns the wire
+ * value for the resolved options + model, or `undefined` to emit nothing
+ * (e.g. reasoning disabled, or a model that rejects the field).
+ */
+declare function reasoningEffortEmit(map: (resolved: ResolvedThinkingOptions, model: string) => string | undefined): ReasoningEmit;
+/**
+ * Build a {@link ReasoningEmit} that writes OpenRouter/Vercel's nested
+ * `reasoning` object. effort and max_tokens are MUTUALLY EXCLUSIVE there, so a
+ * positive `thinkingBudget` emits `{ max_tokens }`, an active effort emits
+ * `{ effort }`, and disabled reasoning emits `{ enabled: false }`.
+ */
+declare function reasoningObjectEmit(mapEffort: (effort: Exclude<Effort, 'none'>, model: string) => string): ReasoningEmit;
+type OpenAICompatibleOptions = {
+    profile: ProviderProfile;
+    /** API key or a per-request resolver (expiring tokens). See {@link ApiKeySource}. */
+    apiKey?: ApiKeySource;
+    baseUrl?: string;
+    /** Override the profile's auth header shape (e.g. Azure Entra bearer tokens). */
+    authHeader?: AuthHeader;
+    rateLimit?: RateLimitConfig;
+};
+/**
+ * Generic provider over the OpenAI `/v1/chat/completions` wire format, raw
+ * `fetch`, zero SDK dependencies. Parameterized by a {@link ProviderProfile}.
+ */
+declare class OpenAICompatibleProvider implements Provider {
+    readonly name: string;
+    /** `json_schema` is honored natively when the profile's `supportsJsonSchema`
+     *  capability is true for this model (the default); otherwise the engine
+     *  downgrades the request to plain `json_object` (see `buildRequestBody`),
+     *  which does NOT enforce the schema shape. */
+    nativeStructuredOutputSupport(model: string): 'schema' | 'downgraded';
+    protected readonly profile: ProviderProfile;
+    protected readonly baseUrl: string;
+    /** A key string, or a resolver invoked per request (expiring tokens). */
+    protected readonly apiKeySource: ApiKeySource;
+    protected readonly authHeader?: AuthHeader;
+    protected readonly governor?: RateLimiter;
+    constructor(options: OpenAICompatibleOptions);
+    /** Resolve the API key for one request, validating against allowMissingApiKey. */
+    protected resolveKey(): Promise<string>;
+    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
+    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
+    protected buildHeaders(apiKey: string): Record<string, string>;
+    protected buildRequestBody(messages: ChatMessage[], options: ChatOptions, stream: boolean): Record<string, unknown>;
+    protected formatMessage(msg: ChatMessage, model: string): Record<string, unknown>;
+    protected extractErrorMessage(body: string, status: number): string;
+    private toUsage;
+    private computeCost;
+    protected parseResponse(json: OpenAIChatResponse, model: string): ProviderResponse;
+    private roundTripMetadata;
+    protected parseSSEStream(body: ReadableStream<Uint8Array>, model: string): AsyncGenerator<StreamChunk>;
+}
+type OpenAIUsage = {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+    /** OpenRouter / Vercel Gateway: per-call cost in USD. */
+    cost?: number;
+};
+type OpenAIChatMessage = {
+    content: string | null | Array<string | {
+        text?: string;
+        content?: string;
+    }>;
+    reasoning_content?: string;
+    reasoning?: string;
+    reasoning_details?: unknown;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+};
+type OpenAIChatResponse = {
+    choices: Array<{
+        message: OpenAIChatMessage;
+        finish_reason: string;
+    }>;
+    usage?: OpenAIUsage;
+};
+
 /** A pending human decision awaiting resolution. */
 type PendingDecision = {
     executionId: string;
@@ -1737,8 +2161,13 @@ type MemoryConfig = {
 
 /** Provider configuration */
 type ProviderConfig = {
-    apiKey?: string;
+    /** API key, or a function resolving one per request (for expiring tokens —
+     *  Azure-Entra, Databricks/IBM OAuth, Bedrock short-term). A plain string is
+     *  the common case. See {@link ApiKeySource}. */
+    apiKey?: ApiKeySource;
     baseUrl?: string;
+    /** OpenAI-compatible presets only: override the profile auth header shape. */
+    authHeader?: AuthHeader;
     /**
      * Opt-in client-side rate governor for this provider's HTTP calls (see
      * {@link RateLimitConfig}). Bounds in-flight request concurrency (and,
@@ -1842,6 +2271,22 @@ type ContextManagementConfig = {
     summaryModel?: string;
     reserveTokens?: number;
 };
+/** Schema-capability diagnostics configuration (spec 22, Problem E). */
+type DiagnosticsConfig = {
+    /**
+     * Token threshold above which an appended prompt schema — or a provider
+     * tool-definition schema — emits a `prompt_schema_oversized`
+     * `schema_diagnostic`. Measured with the same ~4-chars/token estimator used
+     * for context management. Default `4000`.
+     */
+    schemaOversizedTokens?: number;
+    /**
+     * Silence the one-time `console.warn` diagnostics (the structured
+     * `schema_diagnostic` events still fire). Also silenceable process-wide via
+     * `AXL_DIAGNOSTICS_SILENT=true`.
+     */
+    silent?: boolean;
+};
 
 /** Full Axl configuration */
 type AxlConfig = {
@@ -1855,6 +2300,7 @@ type AxlConfig = {
     trace?: TraceConfig;
     defaults?: DefaultsConfig;
     contextManagement?: ContextManagementConfig;
+    diagnostics?: DiagnosticsConfig;
     memory?: MemoryConfig;
     telemetry?: TelemetryConfig;
 };
@@ -2110,7 +2556,18 @@ declare class MemoryManager {
 
 /** Convert a Zod schema to JSON Schema. Exported for Studio tool introspection.
  *  Wraps Zod v4's built-in `z.toJSONSchema()`, stripping the `$schema` key
- *  since tool parameter schemas are embedded objects, not standalone documents. */
+ *  since tool parameter schemas are embedded objects, not standalone documents.
+ *
+ *  **Inline** rendering: shared subschemas are duplicated in place rather than
+ *  hoisted into `$defs`/`$ref`. This is the safe rendering for provider tool
+ *  definitions — notably Gemini's `sanitizeSchemaForGemini` strips `$ref`/`$defs`,
+ *  which would silently reduce a hoisted schema to a typeless `{}`. (Note: a
+ *  genuinely RECURSIVE schema still emits `$ref`/`$defs` even inline — recursion
+ *  can't be inlined — so such tool schemas remain lossy on Gemini regardless;
+ *  that's a pre-existing provider limitation, independent of this rendering.)
+ *  The extra `reused:'ref'` compaction lives in the private
+ *  `renderSchemaForPrompt` and is scoped to prompt text, where `$ref` is opaque
+ *  bytes on the wire. */
 declare function zodToJsonSchema(schema: z.ZodType): Record<string, unknown>;
 /**
  * Extract JSON from LLM response content.
@@ -2118,6 +2575,30 @@ declare function zodToJsonSchema(schema: z.ZodType): Record<string, unknown>;
  * and content with leading/trailing text around a JSON object/array.
  */
 declare function extractJson(content: string): string;
+/**
+ * Active `ctx.budget()` accounting state. One mutable object per budget block,
+ * shared by reference across the block's async branches (spawn/race/map).
+ */
+type BudgetContextState = {
+    totalCost: number;
+    limit: number;
+    exceeded: boolean;
+    policy: string;
+    abortController?: AbortController;
+    /**
+     * Set true when a cost-bearing leaf inside this budget did measurable work
+     * (positive tokens) but produced no usable cost (unpriced model / pricing-table
+     * miss). `totalCost` then UNDERSTATES real spend — it's a lower bound. The budget
+     * rail REPORTS this (via {@link BudgetResult.unpriced} / `getBudgetStatus`) but
+     * does NOT enforce on it: `_accumulateBudgetCost` never receives the unknown
+     * component, so a cost limit / hard_stop cannot trip on unpriced spend.
+     */
+    unpriced: boolean;
+    /** Monotonic count of unpriced leaves observed in this budget scope. */
+    unpricedCount: number;
+    /** Dedup guard so the unpriced warning fires at most once per budget block. */
+    unpricedWarned: boolean;
+};
 type WorkflowContextInit = {
     input: unknown;
     executionId: string;
@@ -2137,13 +2618,7 @@ type WorkflowContextInit = {
         callId?: string;
     }, meta: CallbackMeta) => void;
     pendingDecisions?: Map<string, (d: HumanDecision) => void>;
-    budgetContext?: {
-        totalCost: number;
-        limit: number;
-        exceeded: boolean;
-        policy: string;
-        abortController?: AbortController;
-    };
+    budgetContext?: BudgetContextState;
     stateStore?: StateStore;
     signal?: AbortSignal;
     workflowName?: string;
@@ -2393,6 +2868,23 @@ declare class WorkflowContext<TInput = unknown> {
      * stamping the agent name for observability + future per-agent scoping.
      */
     private pushAssistantToSessionHistory;
+    /**
+     * Emit `schema_diagnostic` events for the silent structured-output cliffs
+     * (spec 22, Problems B + E). Called once per ask. Covers:
+     *  - the appended **prompt** schema (oversized; dropped refinements; or the
+     *    zero-guidance `schemaPrompt:'none'` footgun),
+     *  - each user **tool-def** schema (oversized, dropped refinements),
+     *  - the **streaming** gate (disabled by a non-object root or by tools),
+     *  - **native structured output** the resolved provider can't honor (R10).
+     *
+     * The structured event always fires (persisted + streamed). For the genuinely
+     * surprising, low-frequency cliffs it ALSO fires a one-time deduped
+     * `console.warn` so the median consumer — who never wires up `ctx.events` and
+     * runs with the trace console off — still sees it. `oversized` is event-only
+     * (O3: it's tunable/noisy); the `tools` streaming cause is event-only too
+     * (expected behavior for any tool-using agent, not a surprise).
+     */
+    private emitSchemaDiagnostics;
     private buildToolDefs;
     /**
      * Summarize old messages to fit within context window.
@@ -2457,11 +2949,20 @@ declare class WorkflowContext<TInput = unknown> {
     private medianVote;
     verify<T>(fn: (retry?: VerifyRetry<T>) => Promise<unknown>, schema: z.ZodType<T>, options?: VerifyOptions<T>): Promise<T>;
     budget<T>(options: BudgetOptions, fn: () => Promise<T>): Promise<BudgetResult<T>>;
-    /** Get the current budget status, or null if not inside a budget block. */
+    /**
+     * Get the current budget status, or null if not inside a budget block. Inside
+     * nested budgets this reflects the **innermost active** block (the nested block's
+     * `finally` restores the parent before control returns to it).
+     *
+     * `unpriced` is true when this block ran a model with no usable cost (unpriced /
+     * pricing-table miss): `spent` is then a LOWER BOUND and `remaining` an upper bound —
+     * the limit cannot be enforced on the unmeasured spend. See {@link BudgetResult.unpriced}.
+     */
     getBudgetStatus(): {
         spent: number;
         limit: number;
         remaining: number;
+        unpriced: boolean;
     } | null;
     race<T>(fns: Array<() => Promise<T>>, options?: RaceOptions<T>): Promise<T>;
     private _raceImpl;
@@ -3305,6 +3806,7 @@ declare class AxlRuntime extends EventEmitter {
     trackCost<T>(fn: () => Promise<T>): Promise<{
         result: T;
         cost: number;
+        unpriced: boolean;
     }>;
     /**
      * Track cost and execution metadata across any runtime operations within the given function.
@@ -3343,6 +3845,9 @@ declare class AxlRuntime extends EventEmitter {
     }): 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;
         traces?: AxlEvent[];
         metadata: {
             models: string[];
@@ -3662,6 +4167,30 @@ declare function stringStreamFromEvents(source: AsyncIterable<AxlEvent>, opts?:
  * `AXL_EVENT_TYPES`.
  */
 declare const COST_BEARING_LEAF_TYPES: readonly ["agent_call_end", "tool_call_end", "memory_remember", "memory_recall"];
+/**
+ * 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
+ * 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.
+ */
+declare function hasPositiveTokens(event: {
+    tokens?: {
+        input?: number;
+        output?: number;
+        reasoning?: number;
+    } | null;
+}): boolean;
+/**
+ * True when a cost value is usable for accounting: a finite, non-negative
+ * number. A NON-usable cost (`undefined`, `NaN`, `Infinity`, negative) on a
+ * work-bearing leaf is what marks it "unpriced / unknown". Shared by the core
+ * ask-cost rollup and the Studio aggregators so their unpriced detection stays
+ * exactly in lockstep (incl. the non-finite edge).
+ */
+declare function isUsableCost(cost: unknown): cost is number;
 /**
  * Cost contribution of `event` to a running total.
  *
@@ -3689,6 +4218,34 @@ declare function eventCostContribution(event: AxlEvent): number;
  * just one that happens to contribute zero.
  */
 declare function isCostBearingLeaf(event: AxlEvent): 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
+ * `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
+ * 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.
+ *
+ * Structural param (like {@link hasPositiveTokens} / {@link isUsableCost}) so
+ * Studio's pre-typed trace-event shapes can pass through without casting.
+ */
+declare function isUnpricedLeaf(event: {
+    type?: string;
+    cost?: unknown;
+    tokens?: {
+        input?: number;
+        output?: number;
+        reasoning?: number;
+    } | null;
+}): boolean;
 /**
  * True when the event originates from the root ask (`depth === 0`)
  * or has no ask correlation at all (workflow / done / error / log).
@@ -3852,32 +4409,104 @@ declare class ToolDenied extends AxlError {
 }
 
 /**
- * OpenAI-compatible provider using raw fetch (no SDK dependency).
+ * Typed provider errors + shared HTTP-failure classification.
  *
- * Supports:
- * - Chat completions
- * - Tool calling
- * - Streaming via SSE
- * - Structured output via response_format (JSON mode / JSON schema)
- * - Reasoning models (o1/o3/o4-mini) with developer role and reasoning_effort
+ * Every adapter's `if (!res.ok)` site throws a {@link ProviderError} (built via
+ * {@link buildProviderError}) instead of a bare `Error`, and `fetchWithRetry`
+ * normalizes thrown network failures (DNS, reset, TLS) into a `ProviderError`
+ * with `status: 0`. The `.message` text is preserved verbatim from each
+ * adapter's own `extractErrorMessage`, so existing `.message` assertions keep
+ * working — only the thrown *type* changes.
+ *
+ * RETRY MODEL — two SEPARATE sets (do not conflate):
+ *  - `ProviderError.retryable` (here, via {@link isRetryableStatus}) is the
+ *    BROADER *semantic failover hint* for higher layers (e.g. "should I try a
+ *    different model/provider?"). It is NOT consulted by the transport loop.
+ *  - `retry.ts`'s `RETRYABLE_STATUS_CODES` ({429, 503, 529}) is the NARROW
+ *    *transport auto-retry* set. It stays narrow on purpose — widening it would
+ *    silently change auto-retry for every provider. See the cross-link comment
+ *    there.
+ *
+ * This module must NOT import `retry.ts` (retry.ts imports `parseRetryAfter`
+ * from here — keep the dependency one-way to avoid a cycle).
  */
-declare class OpenAIProvider implements Provider {
-    readonly name = "openai";
-    private baseUrl;
-    private apiKey;
-    private governor?;
+
+/**
+ * Error thrown by provider adapters on any non-2xx HTTP response, and by
+ * `fetchWithRetry` on an exhausted/normalized network failure (`status: 0`).
+ *
+ * `instanceof Error` and `instanceof AxlError` both hold; `code` is always
+ * `'PROVIDER_ERROR'`. The constructor message is passed through verbatim (no
+ * prefix) so callers asserting on the raw provider message are unaffected.
+ */
+declare class ProviderError extends AxlError {
+    /** Adapter/profile name, e.g. `'openai'`, `'anthropic'`, `'google'`. */
+    readonly provider: string;
+    /** HTTP status code; `0` for non-HTTP (network) failures. */
+    readonly status: number;
+    /** Semantic failover hint (see module doc) — NOT the transport-retry set. */
+    readonly retryable: boolean;
+    /** Parsed `Retry-After` delay in ms (RAW/unclamped), when the header was present. */
+    readonly retryAfterMs?: number;
+    /** Provider request id from response headers, when present. */
+    readonly requestId?: string;
+    /**
+     * Raw provider error body. Lives ONLY on the error object — it is
+     * intentionally never placed on the event stream (it can echo prompt text
+     * and is redaction-eligible). See `docs/security.md`.
+     */
+    readonly body?: string;
+    constructor(args: {
+        provider: string;
+        status: number;
+        retryable: boolean;
+        message: string;
+        retryAfterMs?: number;
+        requestId?: string;
+        body?: string;
+    });
+}
+/**
+ * Classify an HTTP status as a semantic failover hint (see {@link ProviderError}).
+ *
+ * Grounded in observed provider behavior. Unmapped codes default to `false`
+ * (conservative); add a row only for a status we've observed a real provider
+ * emit. Status `0` (non-HTTP / network failure) is retryable.
+ */
+declare function isRetryableStatus(status: number): boolean;
+
+declare const OPENAI_PRICING: PricingTable;
+/**
+ * Estimate OpenAI call cost from token usage. Exact match first, then
+ * longest-prefix match for versioned models (e.g. `gpt-4o-2024-05-13`).
+ *
+ * Returns `undefined` when the model is not in the table — callers must treat
+ * that as "unknown cost", never as free (a silent `0` would break
+ * `ctx.budget()` and mislead cost dashboards). See spec §6.
+ */
+declare function estimateOpenAICost(model: string, promptTokens: number, completionTokens: number, cachedTokens?: number): number | undefined;
+/**
+ * OpenAI Chat Completions reasoning emit. Computes `reasoning_effort` for
+ * o-series / GPT-5.x models from the unified effort/thinkingBudget knobs and
+ * signals when to strip `temperature` (always for o-series; for GPT-5.x only
+ * when reasoning is active). Non-reasoning models get neither.
+ */
+declare const openaiReasoningEmit: ReasoningEmit;
+/** Canonical OpenAI Chat Completions profile. */
+declare const OPENAI_PROFILE: ProviderProfile;
+/**
+ * OpenAI provider (Chat Completions) — the canonical {@link OpenAICompatibleProvider}
+ * profile. Preserved as a named export with its original constructor signature.
+ *
+ * Supports chat, tool calling, SSE streaming, structured output, and reasoning
+ * models (o1/o3/o4-mini + GPT-5.x) via `reasoning_effort`.
+ */
+declare class OpenAIProvider extends OpenAICompatibleProvider {
     constructor(options?: {
-        apiKey?: string;
+        apiKey?: ApiKeySource;
         baseUrl?: string;
         rateLimit?: RateLimitConfig;
     });
-    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
-    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
-    private buildRequestBody;
-    /** Extract a human-readable message from an API error response body. */
-    private extractErrorMessage;
-    private formatMessage;
-    private parseSSEStream;
 }
 
 /**
@@ -3889,14 +4518,20 @@ declare class OpenAIProvider implements Provider {
  */
 declare class OpenAIResponsesProvider implements Provider {
     readonly name = "openai-responses";
+    /** The Responses API honors `json_schema` (structured outputs) natively. */
+    nativeStructuredOutputSupport(): 'schema';
     private baseUrl;
-    private apiKey;
+    private apiKeySource;
     private governor?;
     constructor(options?: {
-        apiKey?: string;
+        apiKey?: ApiKeySource;
         baseUrl?: string;
         rateLimit?: RateLimitConfig;
     });
+    /** Resolve the API key for one request (supports an expiring-token callback). */
+    private resolveKey;
+    /** Build request headers from a resolved key (used by both chat and stream). */
+    private buildHeaders;
     chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
     stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
     private buildRequestBody;
@@ -3931,15 +4566,19 @@ declare class OpenAIResponsesProvider implements Provider {
  */
 declare class AnthropicProvider implements Provider {
     readonly name = "anthropic";
+    /** Anthropic ignores native `json_schema` structurally — Axl uses a system
+     *  prompt JSON instruction + client-side Zod validation (see buildRequest). */
+    nativeStructuredOutputSupport(): 'unsupported';
     private baseUrl;
-    private apiKey;
-    private currentModel?;
+    private apiKeySource;
     private governor?;
     constructor(options?: {
-        apiKey?: string;
+        apiKey?: ApiKeySource;
         baseUrl?: string;
         rateLimit?: RateLimitConfig;
     });
+    /** Resolve the API key for one request (supports an expiring-token callback). */
+    private resolveKey;
     chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
     stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
     private buildHeaders;
@@ -3995,15 +4634,21 @@ declare class AnthropicProvider implements Provider {
  */
 declare class GeminiProvider implements Provider {
     readonly name = "google";
+    /** Gemini accepts a `responseSchema` but `sanitizeSchemaForGemini` strips
+     *  keywords it doesn't support (`$ref`/`$defs`/`additionalProperties`/…), so a
+     *  derived schema can lose constraints — lossy, not faithful. */
+    nativeStructuredOutputSupport(): 'lossy';
     private baseUrl;
-    private apiKey;
+    private apiKeySource;
     private callCounter;
     private governor?;
     constructor(options?: {
-        apiKey?: string;
+        apiKey?: ApiKeySource;
         baseUrl?: string;
         rateLimit?: RateLimitConfig;
     });
+    /** Resolve the API key for one request (supports an expiring-token callback). */
+    private resolveKey;
     chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
     stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
     private buildHeaders;
@@ -4040,6 +4685,120 @@ declare class GeminiProvider implements Provider {
     private parseSSEStream;
 }
 
+/**
+ * OpenRouter — one key fronts 300+ models across vendors.
+ *
+ * - Reasoning is the unified `reasoning` object (`{ effort }` XOR `{ max_tokens }`,
+ *   or `{ enabled: false }`); reasoning text comes back in `message.reasoning`
+ *   with a structured `reasoning_details[]` we round-trip on tool-call turns.
+ * - Cost is provider-reported: `usage: { include: true }` makes OpenRouter return
+ *   `usage.cost` (USD), so Axl keeps cost-as-a-primitive working across the whole
+ *   catalog where a static table never could.
+ * - Model ids are `vendor/model` slugs (e.g. `anthropic/claude-opus-4.7`); the
+ *   registry's first-colon split keeps `openrouter:anthropic/claude-…` intact.
+ *
+ * Capability (json_schema, tool calling) is per-MODEL on a marketplace — the
+ * profile defaults are optimistic; use `providerOptions` for per-call overrides.
+ */
+declare const OPENROUTER_PROFILE: ProviderProfile;
+
+/**
+ * Azure OpenAI (v1 API).
+ *
+ * The mid-2026 v1 surface drops the old `/deployments/{id}/` path and
+ * `api-version` query param: the deployment name goes in the `model` field and
+ * the base URL is `https://{resource}.openai.azure.com/openai/v1`. It is
+ * resource-specific, so `requireExplicitBaseUrl` makes the constructor throw if
+ * neither `providers.azure.baseUrl` nor `AZURE_OPENAI_BASE_URL` is set.
+ *
+ * Auth: API-key auth uses the `api-key` header (NOT `Authorization: Bearer`).
+ * Entra/AAD bearer-token auth uses the async key callback plus an `authHeader:
+ * 'bearer'` override.
+ *
+ * Azure serves OpenAI models, so the OpenAI reasoning logic and pricing table
+ * are reused. Caveat: deployment names are arbitrary, so o-series/GPT-5
+ * detection and pricing only fire when the deployment is named after the model;
+ * otherwise effort is a no-op and cost is `undefined` (honest, not a fake $0).
+ */
+declare const AZURE_PROFILE: ProviderProfile;
+
+/**
+ * xAI (Grok). OpenAI-compatible at `https://api.x.ai/v1`.
+ *
+ * - `reasoning_effort` (`low` for effort `low`, else `high`) for grok-3-mini;
+ *   omitted for grok-4* (auto-reasoning) and non-reasoning models.
+ * - `stop` + penalty params are stripped on reasoning models (they 400).
+ *   Penalties aren't engine-computed, so they only matter if a user adds them.
+ */
+declare const XAI_PROFILE: ProviderProfile;
+
+/**
+ * DeepSeek. OpenAI-compatible at `https://api.deepseek.com/v1`.
+ *
+ * - Reasoning text arrives in `message.reasoning_content` (captured to
+ *   thinking) and MUST be echoed back on tool-call turns or the API 400s mid
+ *   tool-loop — the turn-aware `on-tool-call-turns` round-trip handles that.
+ * - No strict `json_schema`; falls back to `json_object`.
+ * - Reasoner models reject sampling params (temperature stripped; `top_p` and
+ *   penalties stripped if engine-set — they are user-only here, so listed for
+ *   intent + future-proofing).
+ */
+declare const DEEPSEEK_PROFILE: ProviderProfile;
+
+/**
+ * Mistral. OpenAI-compatible at `https://api.mistral.ai/v1`.
+ *
+ * `reasoning_effort` is emitted as `'high'` for the small/medium families when
+ * effort is active, and omitted otherwise (other models 422; `magistral-*`
+ * always-reason and reject the field).
+ */
+declare const MISTRAL_PROFILE: ProviderProfile;
+
+/**
+ * Groq — fastest inference (LPU), OpenAI-compatible at
+ * `https://api.groq.com/openai/v1`. Open-weight models only.
+ *
+ * - 400s on `messages[].name` → not emitted.
+ * - `reasoning_effort` (low/medium/high; `xhigh`/`max`→`high`) for gpt-oss only;
+ *   a no-op on other models (whose vocab differs / who reject the field).
+ * - Reasoning text comes back in `message.reasoning` (gpt-oss).
+ */
+declare const GROQ_PROFILE: ProviderProfile;
+
+/**
+ * AWS Bedrock — OpenAI-compatible surface (gpt-oss), bearer-token auth.
+ *
+ * - Base URL is region-specific, so `requireExplicitBaseUrl` forces a real value
+ *   (`providers.bedrock.baseUrl` or `BEDROCK_BASE_URL`). Prefer the current
+ *   `bedrock-mantle` endpoint: `https://bedrock-mantle.{region}.api.aws/v1`
+ *   (alternative, SigV4-capable runtime: `https://bedrock-runtime.{region}.amazonaws.com/openai/v1`).
+ * - Auth: a bearer API key (`AWS_BEARER_TOKEN_BEDROCK`); short-term tokens can use
+ *   the async `apiKey` callback (T2.2). No SigV4.
+ * - Model ids are AWS-namespaced. The **mantle** endpoint uses UNSUFFIXED ids
+ *   (`bedrock:openai.gpt-oss-120b`, `bedrock:openai.gpt-oss-20b`); the runtime
+ *   endpoint uses the version-suffixed form (`openai.gpt-oss-120b-1:0`). Match the
+ *   id to your endpoint. (The registry splits the URI on the first colon, so a
+ *   suffixed id round-trips fine.)
+ * - Pricing: `unknown` — Bedrock returns the standard OpenAI usage object with no
+ *   `cost` field, so per-call cost can't be derived (surfaced honestly, never $0).
+ *
+ * Scope: gpt-oss for Tier 2. Claude-on-Bedrock is a Tier-3 native-adapter mode.
+ */
+declare const BEDROCK_PROFILE: ProviderProfile;
+
+declare const OLLAMA_PROFILE: ProviderProfile;
+declare const VLLM_PROFILE: ProviderProfile;
+declare const LMSTUDIO_PROFILE: ProviderProfile;
+declare const LLAMACPP_PROFILE: ProviderProfile;
+declare const SGLANG_PROFILE: ProviderProfile;
+
+/**
+ * Built-in OpenAI-compatible presets, each served by the generic
+ * {@link OpenAICompatibleProvider}. The registry registers one factory per
+ * profile under `profile.name` (the `provider:` URI key).
+ */
+declare const BUILTIN_PROFILES: ProviderProfile[];
+
 /**
  * In-memory implementation of StateStore.
  * Fast for development and testing, but lost on process restart.
@@ -4485,4 +5244,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 RateLimitConfig, RateLimiter, 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 };
+export { AXL_EVENT_TYPES, 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, AxlRuntime, AxlStream, BEDROCK_PROFILE, BUILTIN_PROFILES, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallbackMeta, type CapabilityFlags, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, DEEPSEEK_PROFILE, 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, GROQ_PROFILE, GeminiProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HumanDecision, InMemoryVectorStore, type InputGuardrail, LLAMACPP_PROFILE, LMSTUDIO_PROFILE, MISTRAL_PROFILE, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OLLAMA_PROFILE, OPENAI_PRICING, OPENAI_PROFILE, OPENROUTER_PROFILE, type OpenAICompatibleOptions, OpenAICompatibleProvider, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type PerModel, type PricingSource, type PricingTable, type Provider, type ProviderAdapter, ProviderError, 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, 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 ToolCallData, type ToolCallMessage, type ToolCallStartData, type ToolChoice, type ToolConfig, ToolDenied, type ToolDeniedData, type ToolHooks, 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, hasPositiveTokens, importModule, isCostBearingLeaf, isRetryableStatus, isRootLevel, isUnpricedLeaf, isUsableCost, needsTsxLoader, openaiReasoningEmit, parsePartialJson, pickDefault, pickExport, priceFromTable, reasoningEffortEmit, reasoningObjectEmit, redactEvent, registerConditions, resolveApiKey, resolvePerModel, resolveRuntime, resolveThinkingOptions, stringStreamFromEvents, tool, workflow, zodToJsonSchema };