@axlsdk/axl 0.18.2 → 0.19.0

package/dist/index.cjs

@@ -111,57 +111,87 @@ var init_span_manager = __esm({
 var index_exports = {};
 __export(index_exports, {
   AXL_EVENT_TYPES: () => AXL_EVENT_TYPES,
+  AZURE_PROFILE: () => AZURE_PROFILE,
   AnthropicProvider: () => AnthropicProvider,
   AxlError: () => AxlError,
   AxlEventBus: () => AxlEventBus,
   AxlRuntime: () => AxlRuntime,
   AxlStream: () => AxlStream,
+  BEDROCK_PROFILE: () => BEDROCK_PROFILE,
+  BUILTIN_PROFILES: () => BUILTIN_PROFILES,
   BudgetExceededError: () => BudgetExceededError,
   CONFIG_CANDIDATES: () => CONFIG_CANDIDATES,
   COST_BEARING_LEAF_TYPES: () => COST_BEARING_LEAF_TYPES,
+  DEEPSEEK_PROFILE: () => DEEPSEEK_PROFILE,
   EventStreamOverflowError: () => EventStreamOverflowError,
+  GROQ_PROFILE: () => GROQ_PROFILE,
   GeminiProvider: () => GeminiProvider,
   GuardrailError: () => GuardrailError,
   InMemoryVectorStore: () => InMemoryVectorStore,
+  LLAMACPP_PROFILE: () => LLAMACPP_PROFILE,
+  LMSTUDIO_PROFILE: () => LMSTUDIO_PROFILE,
+  MISTRAL_PROFILE: () => MISTRAL_PROFILE,
   MaxTurnsError: () => MaxTurnsError,
   McpManager: () => McpManager,
   MemoryManager: () => MemoryManager,
   MemoryStore: () => MemoryStore,
   NoConsensus: () => NoConsensus,
   NoopSpanManager: () => NoopSpanManager,
+  OLLAMA_PROFILE: () => OLLAMA_PROFILE,
+  OPENAI_PRICING: () => OPENAI_PRICING,
+  OPENAI_PROFILE: () => OPENAI_PROFILE,
+  OPENROUTER_PROFILE: () => OPENROUTER_PROFILE,
+  OpenAICompatibleProvider: () => OpenAICompatibleProvider,
   OpenAIEmbedder: () => OpenAIEmbedder,
   OpenAIProvider: () => OpenAIProvider,
   OpenAIResponsesProvider: () => OpenAIResponsesProvider,
+  ProviderError: () => ProviderError,
   ProviderRegistry: () => ProviderRegistry,
   QuorumNotMet: () => QuorumNotMet,
   REDACTED: () => REDACTED,
   REDACTION_RULES: () => REDACTION_RULES,
   RateLimiter: () => RateLimiter,
   RedisStore: () => RedisStore,
+  SGLANG_PROFILE: () => SGLANG_PROFILE,
   SQLiteStore: () => SQLiteStore,
   Session: () => Session,
   SqliteVectorStore: () => SqliteVectorStore,
+  ThinkTagScanner: () => ThinkTagScanner,
   TimeoutError: () => TimeoutError,
   ToolDenied: () => ToolDenied,
+  VLLM_PROFILE: () => VLLM_PROFILE,
   ValidationError: () => ValidationError,
   VerifyError: () => VerifyError,
   WorkflowContext: () => WorkflowContext,
+  XAI_PROFILE: () => XAI_PROFILE,
   agent: () => agent,
   createSpanManager: () => createSpanManager,
   defineConfig: () => defineConfig,
+  estimateOpenAICost: () => estimateOpenAICost,
   eventCostContribution: () => eventCostContribution,
   expandGlob: () => expandGlob,
   extractJson: () => extractJson,
+  extractThinkTags: () => extractThinkTags,
   findConfig: () => findConfig,
+  hasPositiveTokens: () => hasPositiveTokens,
   importModule: () => importModule,
   isCostBearingLeaf: () => isCostBearingLeaf,
+  isRetryableStatus: () => isRetryableStatus,
   isRootLevel: () => isRootLevel,
+  isUnpricedLeaf: () => isUnpricedLeaf,
+  isUsableCost: () => isUsableCost,
   needsTsxLoader: () => needsTsxLoader,
+  openaiReasoningEmit: () => openaiReasoningEmit,
   parsePartialJson: () => parsePartialJson,
   pickDefault: () => pickDefault,
   pickExport: () => pickExport,
+  priceFromTable: () => priceFromTable,
+  reasoningEffortEmit: () => reasoningEffortEmit,
+  reasoningObjectEmit: () => reasoningObjectEmit,
   redactEvent: () => redactEvent,
   registerConditions: () => registerConditions,
+  resolveApiKey: () => resolveApiKey,
+  resolvePerModel: () => resolvePerModel,
   resolveRuntime: () => resolveRuntime,
   resolveThinkingOptions: () => resolveThinkingOptions,
   stringStreamFromEvents: () => stringStreamFromEvents,
@@ -289,11 +319,218 @@ function resolveThinkingOptions(options) {
     hasBudgetOverride
   };
 }
+async function resolveApiKey(source) {
+  if (typeof source === "function") return await source() ?? "";
+  return source ?? "";
+}
+
+// src/errors.ts
+var AxlError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "AxlError";
+    this.code = code;
+  }
+};
+var VerifyError = class extends AxlError {
+  lastOutput;
+  zodError;
+  retries;
+  constructor(lastOutput, zodError, retries) {
+    super("VERIFY_ERROR", `Schema validation failed after ${retries} retries: ${zodError.message}`);
+    this.name = "VerifyError";
+    this.lastOutput = lastOutput;
+    this.zodError = zodError;
+    this.retries = retries;
+  }
+};
+var QuorumNotMet = class extends AxlError {
+  results;
+  constructor(required, actual, results) {
+    super("QUORUM_NOT_MET", `Quorum not met: needed ${required} successes, got ${actual}`);
+    this.name = "QuorumNotMet";
+    this.results = results;
+  }
+};
+var NoConsensus = class extends AxlError {
+  constructor(reason) {
+    super("NO_CONSENSUS", `No consensus: ${reason}`);
+    this.name = "NoConsensus";
+  }
+};
+var TimeoutError = class extends AxlError {
+  constructor(operation, timeoutMs) {
+    super("TIMEOUT", `${operation} exceeded timeout of ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+  }
+};
+function formatBudgetCost(cost) {
+  if (Number.isNaN(cost)) return "$NaN";
+  if (cost === Infinity) return "$Infinity";
+  if (cost === -Infinity) return "-$Infinity";
+  if (cost === 0) return "$0.00";
+  const sign = cost < 0 ? "-" : "";
+  const abs = Math.abs(cost);
+  if (abs < 1e-6) return `${sign}< $0.000001`;
+  if (abs < 1e-4) {
+    const [mantissa, exponent] = abs.toExponential(2).split("e");
+    return `${sign}$${mantissa}e${parseInt(exponent, 10)}`;
+  }
+  if (abs < 0.01) return `${sign}$${abs.toFixed(6)}`;
+  return `${sign}$${abs.toFixed(2)}`;
+}
+var BudgetExceededError = class extends AxlError {
+  limit;
+  spent;
+  policy;
+  constructor(limit, spent, policy) {
+    super(
+      "BUDGET_EXCEEDED",
+      `Budget exceeded: spent ${formatBudgetCost(spent)} of ${formatBudgetCost(
+        limit
+      )} limit (policy: ${policy})`
+    );
+    this.name = "BudgetExceededError";
+    this.limit = limit;
+    this.spent = spent;
+    this.policy = policy;
+  }
+};
+var MaxTurnsError = class extends AxlError {
+  maxTurns;
+  constructor(operation, maxTurns) {
+    super("MAX_TURNS", `${operation} exceeded maximum of ${maxTurns} turns`);
+    this.name = "MaxTurnsError";
+    this.maxTurns = maxTurns;
+  }
+};
+var GuardrailError = class extends AxlError {
+  guardrailType;
+  reason;
+  constructor(guardrailType, reason) {
+    super("GUARDRAIL_BLOCKED", `${guardrailType} guardrail blocked: ${reason}`);
+    this.name = "GuardrailError";
+    this.guardrailType = guardrailType;
+    this.reason = reason;
+  }
+};
+var ValidationError = class extends AxlError {
+  lastOutput;
+  reason;
+  retries;
+  constructor(lastOutput, reason, retries) {
+    super("VALIDATION_ERROR", `Validation failed after ${retries} retries: ${reason}`);
+    this.name = "ValidationError";
+    this.lastOutput = lastOutput;
+    this.reason = reason;
+    this.retries = retries;
+  }
+};
+var ToolDenied = class extends AxlError {
+  toolName;
+  agentName;
+  constructor(toolName, agentName) {
+    super(
+      "TOOL_DENIED",
+      `Agent "${agentName}" attempted to call tool "${toolName}" which is not in its ACL`
+    );
+    this.name = "ToolDenied";
+    this.toolName = toolName;
+    this.agentName = agentName;
+  }
+};
+
+// src/providers/errors.ts
+var ProviderError = class extends AxlError {
+  /** Adapter/profile name, e.g. `'openai'`, `'anthropic'`, `'google'`. */
+  provider;
+  /** HTTP status code; `0` for non-HTTP (network) failures. */
+  status;
+  /** Semantic failover hint (see module doc) — NOT the transport-retry set. */
+  retryable;
+  /** Parsed `Retry-After` delay in ms (RAW/unclamped), when the header was present. */
+  retryAfterMs;
+  /** Provider request id from response headers, when present. */
+  requestId;
+  /**
+   * 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`.
+   */
+  body;
+  constructor(args) {
+    super("PROVIDER_ERROR", args.message);
+    this.name = "ProviderError";
+    this.provider = args.provider;
+    this.status = args.status;
+    this.retryable = args.retryable;
+    this.retryAfterMs = args.retryAfterMs;
+    this.requestId = args.requestId;
+    this.body = args.body;
+  }
+};
+function isRetryableStatus(status) {
+  switch (status) {
+    case 0:
+      return true;
+    case 408:
+    // request timeout
+    case 429:
+    // rate limit
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+    case 529:
+      return true;
+    // Explicitly non-retryable (bad request / auth / not found / payload):
+    // 400, 401, 403, 404, 413, 422 fall through to the default.
+    default:
+      return false;
+  }
+}
+function parseRetryAfter(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return void 0;
+  const trimmed = raw.trim();
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const ms = Number(trimmed) * 1e3;
+    return ms > 0 ? ms : void 0;
+  }
+  const dateMs = Date.parse(trimmed);
+  if (Number.isNaN(dateMs)) return void 0;
+  const delta = dateMs - Date.now();
+  return delta > 0 ? delta : void 0;
+}
+var REQUEST_ID_HEADERS = ["x-request-id", "request-id"];
+function extractRequestId(headers) {
+  for (const name of REQUEST_ID_HEADERS) {
+    const value = headers.get(name);
+    if (value) return value;
+  }
+  return void 0;
+}
+function buildProviderError(args) {
+  return new ProviderError({
+    provider: args.provider,
+    status: args.status,
+    retryable: isRetryableStatus(args.status),
+    message: args.message,
+    retryAfterMs: args.headers ? parseRetryAfter(args.headers) : void 0,
+    requestId: args.headers ? extractRequestId(args.headers) : void 0,
+    body: args.body
+  });
+}
 
 // src/providers/retry.ts
 var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 503, 529]);
 var MAX_RETRIES = 2;
 var BASE_DELAY_MS = 1e3;
+var MAX_BACKOFF_MS = 6e4;
+function jitter(ms) {
+  return ms * (0.75 + Math.random() * 0.5);
+}
 function sleep2(ms, signal) {
   return new Promise((resolve2) => {
     if (signal?.aborted) {
@@ -311,9 +548,14 @@ function sleep2(ms, signal) {
     );
   });
 }
+function isAbortError(err, signal) {
+  if (signal?.aborted) return true;
+  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
 async function fetchWithRetry(input, init, opts) {
   const maxRetries = opts?.maxRetries ?? MAX_RETRIES;
   const governor = opts?.governor;
+  const provider = opts?.provider ?? "unknown";
   let acquired = false;
   if (governor) {
     await governor.acquire(init?.signal ?? void 0);
@@ -321,7 +563,21 @@ async function fetchWithRetry(input, init, opts) {
   }
   try {
     for (let attempt = 0; ; attempt++) {
-      const res = await fetch(input, init);
+      let res;
+      try {
+        res = await fetch(input, init);
+      } catch (err) {
+        if (isAbortError(err, init?.signal ?? void 0)) throw err;
+        if (attempt >= maxRetries) {
+          throw buildProviderError({
+            provider,
+            status: 0,
+            message: err instanceof Error ? err.message : String(err)
+          });
+        }
+        await sleep2(jitter(BASE_DELAY_MS * 2 ** attempt), init?.signal ?? void 0);
+        continue;
+      }
       governor?.observe(res);
       if (res.ok || !RETRYABLE_STATUS_CODES.has(res.status) || attempt >= maxRetries) {
         return res;
@@ -329,15 +585,9 @@ async function fetchWithRetry(input, init, opts) {
       if (init?.signal?.aborted) {
         return res;
       }
-      const retryAfter = res.headers.get("retry-after");
-      let delay;
-      if (retryAfter && !isNaN(Number(retryAfter))) {
-        delay = Number(retryAfter) * 1e3;
-      } else {
-        delay = BASE_DELAY_MS * 2 ** attempt;
-      }
-      delay *= 0.75 + Math.random() * 0.5;
-      await sleep2(delay, init?.signal ?? void 0);
+      const retryAfterMs = parseRetryAfter(res.headers);
+      const baseDelay = retryAfterMs !== void 0 ? Math.min(retryAfterMs, MAX_BACKOFF_MS) : BASE_DELAY_MS * 2 ** attempt;
+      await sleep2(jitter(baseDelay), init?.signal ?? void 0);
     }
   } finally {
     if (acquired) governor.release();
@@ -485,254 +735,467 @@ var RateLimiter = class {
   }
 };
 
-// src/providers/openai.ts
-var OPENAI_PRICING = {
-  // gpt-4o era — cache reads at 50% of input rate
-  "gpt-4o": [25e-7, 1e-5, 0.5],
-  "gpt-4o-mini": [15e-8, 6e-7, 0.5],
-  "gpt-4-turbo": [1e-5, 3e-5, 0.5],
-  "gpt-4": [3e-5, 6e-5, 0.5],
-  "gpt-3.5-turbo": [5e-7, 15e-7, 0.5],
-  o1: [15e-6, 6e-5, 0.5],
-  "o1-mini": [3e-6, 12e-6, 0.5],
-  "o1-pro": [15e-5, 6e-4, 0.5],
-  // gpt-4.1 / o3 / o4 era — cache reads at 25% of input rate
-  "gpt-4.1": [2e-6, 8e-6, 0.25],
-  "gpt-4.1-mini": [4e-7, 16e-7, 0.25],
-  "gpt-4.1-nano": [1e-7, 4e-7, 0.25],
-  o3: [1e-5, 4e-5, 0.25],
-  "o3-mini": [11e-7, 44e-7, 0.25],
-  "o3-pro": [2e-5, 8e-5, 0.25],
-  "o4-mini": [11e-7, 44e-7, 0.25],
-  // gpt-5 era — cache reads at 10% of input rate
-  "gpt-5": [125e-8, 1e-5, 0.1],
-  "gpt-5-mini": [25e-8, 2e-6, 0.1],
-  "gpt-5-nano": [5e-8, 4e-7, 0.1],
-  "gpt-5.1": [125e-8, 1e-5, 0.1],
-  "gpt-5.2": [175e-8, 14e-6, 0.1],
-  "gpt-5.3": [175e-8, 14e-6, 0.1],
-  "gpt-5.4": [25e-7, 15e-6, 0.1],
-  "gpt-5.4-pro": [3e-5, 18e-5, 0.1],
-  // gpt-5.5 era (flagship released 2026-04) — cache reads at 10% of input rate
-  "gpt-5.5": [5e-6, 3e-5, 0.1],
-  "gpt-5.5-pro": [3e-5, 18e-5, 0.1]
-};
-var PRICING_KEYS_BY_LENGTH = Object.keys(OPENAI_PRICING).sort((a, b) => b.length - a.length);
-function estimateOpenAICost(model, promptTokens, completionTokens, cachedTokens) {
-  let pricing = OPENAI_PRICING[model];
+// src/providers/openai-compatible.ts
+function resolvePerModel(value, model, fallback) {
+  if (value === void 0) return fallback;
+  return typeof value === "function" ? value(model) : value;
+}
+var SORTED_KEYS_CACHE = /* @__PURE__ */ new WeakMap();
+function sortedKeys(table) {
+  let keys = SORTED_KEYS_CACHE.get(table);
+  if (!keys) {
+    keys = Object.keys(table).sort((a, b) => b.length - a.length);
+    SORTED_KEYS_CACHE.set(table, keys);
+  }
+  return keys;
+}
+function priceFromTable(table, model, promptTokens, completionTokens, cachedTokens) {
+  let pricing = table[model];
   if (!pricing) {
-    for (const key of PRICING_KEYS_BY_LENGTH) {
+    for (const key of sortedKeys(table)) {
       if (model.startsWith(key)) {
-        pricing = OPENAI_PRICING[key];
+        pricing = table[key];
         break;
       }
     }
   }
-  if (!pricing) return 0;
+  if (!pricing) return void 0;
   const [inputRate, outputRate, cacheMultiplier] = pricing;
   const cached = cachedTokens ?? 0;
   const inputCost = (promptTokens - cached) * inputRate + cached * inputRate * cacheMultiplier;
   return inputCost + completionTokens * outputRate;
 }
-function isOSeriesModel(model) {
-  return /^(o1|o3|o4-mini)/.test(model);
+var THINK_OPEN = "<think>";
+var THINK_CLOSE = "</think>";
+function partialTagSuffixLen(s, tag) {
+  const max = Math.min(s.length, tag.length - 1);
+  for (let n = max; n > 0; n--) {
+    if (tag.startsWith(s.slice(s.length - n))) return n;
+  }
+  return 0;
 }
-function supportsReasoningEffort(model) {
-  return isOSeriesModel(model) || /^gpt-5/.test(model);
-}
-function supportsReasoningNone(model) {
-  return /^gpt-5\.[1-9]/.test(model);
+var ThinkTagScanner = class {
+  buffer = "";
+  inside = false;
+  push(chunk) {
+    this.buffer += chunk;
+    let text = "";
+    let thinking = "";
+    for (; ; ) {
+      const tag = this.inside ? THINK_CLOSE : THINK_OPEN;
+      const idx = this.buffer.indexOf(tag);
+      if (idx === -1) {
+        const hold = partialTagSuffixLen(this.buffer, tag);
+        const emit = this.buffer.slice(0, this.buffer.length - hold);
+        if (this.inside) thinking += emit;
+        else text += emit;
+        this.buffer = this.buffer.slice(this.buffer.length - hold);
+        break;
+      }
+      const before = this.buffer.slice(0, idx);
+      if (this.inside) thinking += before;
+      else text += before;
+      this.buffer = this.buffer.slice(idx + tag.length);
+      this.inside = !this.inside;
+    }
+    return { text, thinking };
+  }
+  /** Flush any residual buffer at stream end (treat as the current channel). */
+  flush() {
+    const rest = this.buffer;
+    this.buffer = "";
+    return this.inside ? { text: "", thinking: rest } : { text: rest, thinking: "" };
+  }
+};
+function extractThinkTags(content) {
+  const scanner = new ThinkTagScanner();
+  const a = scanner.push(content);
+  const b = scanner.flush();
+  return { content: a.text + b.text, thinking: a.thinking + b.thinking };
 }
-function supportsXhigh(model) {
-  return /^gpt-5\.([2-9]|\d{2,})/.test(model);
+function reasoningEffortEmit(map) {
+  return (body, resolved, model) => {
+    const value = map(resolved, model);
+    if (value) body.reasoning_effort = value;
+  };
 }
-function clampReasoningEffort(model, effort) {
-  if (model.startsWith("gpt-5-pro")) return "high";
-  if (effort === "none" && !supportsReasoningNone(model)) return "minimal";
-  if (effort === "xhigh" && !supportsXhigh(model)) return "high";
-  return effort;
+function reasoningObjectEmit(mapEffort) {
+  return (body, resolved, model) => {
+    if (resolved.hasBudgetOverride) {
+      body.reasoning = { max_tokens: resolved.thinkingBudget };
+    } else if (resolved.activeEffort) {
+      body.reasoning = { effort: mapEffort(resolved.activeEffort, model) };
+    } else if (resolved.thinkingDisabled) {
+      body.reasoning = { enabled: false };
+    }
+  };
 }
-function effortToReasoningEffort(effort) {
-  return effort === "max" ? "xhigh" : effort;
+var ROUND_TRIP_FIELDS = ["reasoning_content", "reasoning", "reasoning_details"];
+function isRoundTripField(field) {
+  return typeof field === "string" && ROUND_TRIP_FIELDS.includes(field);
 }
-function budgetToReasoningEffort(budget) {
-  if (budget <= 1024) return "low";
-  if (budget <= 8192) return "medium";
-  return "high";
+function normalizeMessageContent(content) {
+  if (typeof content === "string") return content;
+  if (content == null) return "";
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => {
+    if (typeof part === "string") return part;
+    if (!part || typeof part !== "object") return "";
+    if (typeof part.text === "string") return part.text;
+    if (typeof part.content === "string") return part.content;
+    return "";
+  }).join("");
 }
-var OpenAIProvider = class {
-  name = "openai";
+var OpenAICompatibleProvider = class {
+  name;
+  /** `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) {
+    const supportsSchema = resolvePerModel(
+      this.profile.capabilities?.supportsJsonSchema,
+      model,
+      true
+    );
+    return supportsSchema ? "schema" : "downgraded";
+  }
+  profile;
   baseUrl;
-  apiKey;
+  /** A key string, or a resolver invoked per request (expiring tokens). */
+  apiKeySource;
+  authHeader;
   governor;
-  constructor(options = {}) {
-    this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
-    this.baseUrl = (options.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+  constructor(options) {
+    const p = options.profile;
+    this.profile = p;
+    this.name = p.name;
+    this.apiKeySource = options.apiKey ?? (p.envApiKey ? process.env[p.envApiKey] : void 0) ?? "";
+    this.authHeader = options.authHeader;
+    const envBase = p.envBaseUrl ? process.env[p.envBaseUrl] : void 0;
+    const explicitBase = options.baseUrl ?? envBase;
+    this.baseUrl = (explicitBase ?? p.defaultBaseUrl).replace(/\/$/, "");
     this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
-    if (!this.apiKey) {
-      throw new Error("OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey in options.");
+    const label = p.label ?? p.name;
+    if (p.requireExplicitBaseUrl && explicitBase === void 0) {
+      const env = p.envBaseUrl ? ` or ${p.envBaseUrl}` : "";
+      throw new Error(
+        `${label} requires a base URL. Set providers.${p.name}.baseUrl${env} (it is resource-specific and has no default).`
+      );
+    }
+    if (typeof this.apiKeySource === "string" && !this.apiKeySource && !p.allowMissingApiKey) {
+      const env = p.envApiKey ?? "the API key env var";
+      throw new Error(`${label} API key is required. Set ${env} or pass apiKey in options.`);
     }
   }
-  // ---------------------------------------------------------------------------
-  // chat - non-streaming completion
-  // ---------------------------------------------------------------------------
+  /** Resolve the API key for one request, validating against allowMissingApiKey. */
+  async resolveKey() {
+    const key = await resolveApiKey(this.apiKeySource);
+    if (!key && !this.profile.allowMissingApiKey) {
+      const label = this.profile.label ?? this.profile.name;
+      const env = this.profile.envApiKey ?? "the API key env var";
+      throw new Error(`${label} API key is required. Set ${env} or pass apiKey in options.`);
+    }
+    return key;
+  }
   async chat(messages, options) {
+    const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, false);
     const res = await fetchWithRetry(
       `${this.baseUrl}/chat/completions`,
       {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`
-        },
+        headers,
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor }
+      { governor: this.governor, provider: this.name }
     );
     if (!res.ok) {
       const errorBody = await res.text();
-      const message = this.extractErrorMessage(errorBody, res.status);
-      throw new Error(message);
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message: this.extractErrorMessage(errorBody, res.status),
+        body: errorBody
+      });
     }
     const json = await res.json();
-    const choice = json.choices[0];
-    const usage = json.usage ? {
-      prompt_tokens: json.usage.prompt_tokens,
-      completion_tokens: json.usage.completion_tokens,
-      total_tokens: json.usage.total_tokens,
-      reasoning_tokens: json.usage.completion_tokens_details?.reasoning_tokens,
-      cached_tokens: json.usage.prompt_tokens_details?.cached_tokens
-    } : void 0;
-    const cost = usage ? estimateOpenAICost(
-      options.model,
-      usage.prompt_tokens,
-      usage.completion_tokens,
-      usage.cached_tokens
-    ) : void 0;
-    return {
-      content: choice.message.content ?? "",
-      tool_calls: choice.message.tool_calls?.map((tc) => ({
-        id: tc.id,
-        type: "function",
-        function: {
-          name: tc.function.name,
-          arguments: tc.function.arguments
-        }
-      })),
-      usage,
-      cost
-    };
+    return this.parseResponse(json, options.model);
   }
-  // ---------------------------------------------------------------------------
-  // stream - SSE streaming completion
-  // ---------------------------------------------------------------------------
   async *stream(messages, options) {
+    const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, true);
     const res = await fetchWithRetry(
       `${this.baseUrl}/chat/completions`,
       {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`
-        },
+        headers,
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor }
+      { governor: this.governor, provider: this.name }
     );
     if (!res.ok) {
       const errorBody = await res.text();
-      const message = this.extractErrorMessage(errorBody, res.status);
-      throw new Error(message);
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message: this.extractErrorMessage(errorBody, res.status),
+        body: errorBody
+      });
     }
     if (!res.body) {
-      throw new Error("OpenAI stream response has no body");
+      throw new Error(`${this.profile.label ?? this.profile.name} stream response has no body`);
     }
     yield* this.parseSSEStream(res.body, options.model);
   }
   // ---------------------------------------------------------------------------
-  // Internal helpers
+  // Request building
   // ---------------------------------------------------------------------------
-  buildRequestBody(messages, options, stream) {
-    const oSeries = isOSeriesModel(options.model);
-    const reasoningCapable = supportsReasoningEffort(options.model);
-    const { thinkingBudget, thinkingDisabled, activeEffort, hasBudgetOverride } = resolveThinkingOptions(options);
-    let wireEffort;
-    if (reasoningCapable) {
-      if (hasBudgetOverride) {
-        wireEffort = clampReasoningEffort(options.model, budgetToReasoningEffort(thinkingBudget));
-      } else if (!thinkingDisabled && activeEffort) {
-        wireEffort = clampReasoningEffort(options.model, effortToReasoningEffort(activeEffort));
-      } else if (thinkingDisabled) {
-        wireEffort = clampReasoningEffort(options.model, "none");
-      }
+  buildHeaders(apiKey) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.profile.headers ?? {}
+    };
+    if (apiKey) {
+      const auth = this.authHeader ?? this.profile.authHeader ?? "bearer";
+      if (auth === "bearer") headers.Authorization = `Bearer ${apiKey}`;
+      else if (auth === "api-key") headers["api-key"] = apiKey;
+      else headers[auth.header] = auth.scheme ? `${auth.scheme} ${apiKey}` : apiKey;
     }
-    const stripTemp = oSeries || reasoningCapable && wireEffort !== void 0;
+    return headers;
+  }
+  buildRequestBody(messages, options, stream) {
+    const profile = this.profile;
+    const resolved = resolveThinkingOptions(options);
     const body = {
       model: options.model,
-      messages: messages.map((m) => this.formatMessage(m, oSeries)),
+      messages: messages.map((m) => this.formatMessage(m, options.model)),
       stream
     };
-    if (options.temperature !== void 0 && !stripTemp) {
+    const emitResult = profile.reasoning.emit(body, resolved, options.model) ?? {};
+    const stripTemperature = emitResult.stripTemperature ?? false;
+    if (options.temperature !== void 0 && !stripTemperature) {
       body.temperature = options.temperature;
     }
     if (options.maxTokens !== void 0) {
-      body.max_completion_tokens = options.maxTokens;
+      body[profile.maxTokensField ?? "max_completion_tokens"] = options.maxTokens;
     }
     if (options.stop) body.stop = options.stop;
     if (options.tools && options.tools.length > 0) {
       body.tools = options.tools;
-      if (!oSeries) {
+      if (resolvePerModel(profile.parallelToolCalls, options.model, false)) {
         body.parallel_tool_calls = true;
       }
     }
-    if (options.toolChoice !== void 0) {
-      body.tool_choice = options.toolChoice;
-    }
+    if (options.toolChoice !== void 0) body.tool_choice = options.toolChoice;
     if (options.responseFormat) {
-      body.response_format = options.responseFormat;
+      const supportsSchema = resolvePerModel(
+        profile.capabilities?.supportsJsonSchema,
+        options.model,
+        true
+      );
+      body.response_format = options.responseFormat.type === "json_schema" && !supportsSchema ? { type: "json_object" } : options.responseFormat;
     }
-    if (wireEffort) body.reasoning_effort = wireEffort;
-    if (stream) {
+    if (stream && (profile.capabilities?.supportsStreamUsage ?? true)) {
       body.stream_options = { include_usage: true };
     }
-    if (options.providerOptions) {
-      Object.assign(body, options.providerOptions);
+    if (profile.requestDefaults) Object.assign(body, profile.requestDefaults);
+    const userKeys = options.providerOptions ? Object.keys(options.providerOptions) : [];
+    if (options.providerOptions) Object.assign(body, options.providerOptions);
+    const forbidden = resolvePerModel(profile.capabilities?.forbiddenParams, options.model, []);
+    for (const key of forbidden) {
+      if (!userKeys.includes(key)) delete body[key];
     }
     return body;
   }
-  /** Extract a human-readable message from an API error response body. */
+  formatMessage(msg, model) {
+    const out = {
+      role: this.profile.roleFor ? this.profile.roleFor(msg.role, model) : msg.role,
+      content: msg.content
+    };
+    if (msg.name && (this.profile.capabilities?.emitsMessageName ?? true)) out.name = msg.name;
+    if (msg.tool_calls) out.tool_calls = msg.tool_calls;
+    if (msg.tool_call_id) out.tool_call_id = msg.tool_call_id;
+    if (this.profile.reasoning.roundTrip === "on-tool-call-turns" && msg.role === "assistant" && msg.tool_calls && msg.tool_calls.length > 0) {
+      const rt = msg.providerMetadata?.openaiCompatReasoning;
+      if (rt && rt.provider === this.name && isRoundTripField(rt.field) && rt.value !== void 0 && rt.value !== null) {
+        out[rt.field] = rt.value;
+      }
+    }
+    return out;
+  }
+  // ---------------------------------------------------------------------------
+  // Response parsing
+  // ---------------------------------------------------------------------------
   extractErrorMessage(body, status) {
+    const label = this.profile.label ?? this.profile.name;
     try {
       const json = JSON.parse(body);
-      if (json.error?.message) {
-        return `OpenAI API error (${status}): ${json.error.message}`;
-      }
+      const message = json.error?.message ?? json.message ?? json.detail;
+      if (message) return `${label} API error (${status}): ${message}`;
     } catch {
     }
-    return `OpenAI API error (${status}): ${body}`;
+    return `${label} API error (${status}): ${body}`;
   }
-  formatMessage(msg, oSeries) {
-    const out = {
-      role: msg.role === "system" && oSeries ? "developer" : msg.role,
-      content: msg.content
+  toUsage(raw) {
+    if (!raw) return void 0;
+    return {
+      prompt_tokens: raw.prompt_tokens,
+      completion_tokens: raw.completion_tokens,
+      total_tokens: raw.total_tokens,
+      reasoning_tokens: raw.completion_tokens_details?.reasoning_tokens,
+      cached_tokens: raw.prompt_tokens_details?.cached_tokens
     };
-    if (msg.name) out.name = msg.name;
-    if (msg.tool_calls) out.tool_calls = msg.tool_calls;
-    if (msg.tool_call_id) out.tool_call_id = msg.tool_call_id;
-    return out;
   }
+  computeCost(model, usage, reportedCost) {
+    const p = this.profile.pricing;
+    if (p.kind === "zero") return 0;
+    if (!usage) return void 0;
+    switch (p.kind) {
+      case "unknown":
+        return void 0;
+      case "from-response":
+        return typeof reportedCost === "number" && Number.isFinite(reportedCost) ? reportedCost : void 0;
+      case "table": {
+        const c = priceFromTable(
+          p.table,
+          model,
+          usage.prompt_tokens,
+          usage.completion_tokens,
+          usage.cached_tokens
+        );
+        return c !== void 0 && Number.isFinite(c) ? c : void 0;
+      }
+      default: {
+        const _exhaustive = p;
+        throw new Error(`Unhandled pricing source: ${JSON.stringify(_exhaustive)}`);
+      }
+    }
+  }
+  parseResponse(json, model) {
+    const message = json.choices?.[0]?.message ?? {};
+    let content = normalizeMessageContent(message.content);
+    let thinking;
+    let roundTrip;
+    switch (this.profile.reasoning.capture) {
+      case "reasoning_content":
+        if (typeof message.reasoning_content === "string") {
+          thinking = message.reasoning_content;
+          roundTrip = {
+            provider: this.name,
+            field: "reasoning_content",
+            value: message.reasoning_content
+          };
+        }
+        break;
+      case "reasoning":
+        if (typeof message.reasoning === "string") {
+          thinking = message.reasoning;
+          roundTrip = { provider: this.name, field: "reasoning", value: message.reasoning };
+        }
+        break;
+      case "reasoning_details":
+        if (typeof message.reasoning === "string") thinking = message.reasoning;
+        if (message.reasoning_details !== void 0) {
+          roundTrip = {
+            provider: this.name,
+            field: "reasoning_details",
+            value: message.reasoning_details
+          };
+        }
+        break;
+      case "think_tags": {
+        const ex = extractThinkTags(content);
+        content = ex.content;
+        if (ex.thinking) thinking = ex.thinking;
+        break;
+      }
+      case "none":
+        break;
+      default: {
+        const _exhaustive = this.profile.reasoning.capture;
+        throw new Error(`Unhandled reasoning capture: ${String(_exhaustive)}`);
+      }
+    }
+    const usage = this.toUsage(json.usage);
+    const cost = this.computeCost(model, usage, json.usage?.cost);
+    return {
+      content,
+      thinking_content: thinking || void 0,
+      tool_calls: message.tool_calls?.map((tc) => ({
+        id: tc.id,
+        type: "function",
+        function: { name: tc.function.name, arguments: tc.function.arguments }
+      })),
+      usage,
+      cost,
+      providerMetadata: this.roundTripMetadata(roundTrip)
+    };
+  }
+  roundTripMetadata(rt) {
+    if (!rt || this.profile.reasoning.roundTrip === void 0 || this.profile.reasoning.roundTrip === "none") {
+      return void 0;
+    }
+    return rt.value === void 0 || rt.value === null ? void 0 : { openaiCompatReasoning: rt };
+  }
+  // ---------------------------------------------------------------------------
+  // SSE streaming
+  // ---------------------------------------------------------------------------
   async *parseSSEStream(body, model) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
     let usageData;
+    const capture = this.profile.reasoning.capture;
+    const thinkScanner = capture === "think_tags" ? new ThinkTagScanner() : void 0;
+    let reasoningText = "";
+    const reasoningDetails = [];
     const indexToId = /* @__PURE__ */ new Map();
+    const pendingToolCalls = /* @__PURE__ */ new Map();
+    const flushPendingToolCalls = () => {
+      const out = [];
+      for (const [index, buf] of pendingToolCalls) {
+        out.push({
+          type: "tool_call_delta",
+          id: `__toolcall_${index}`,
+          name: buf.name,
+          arguments: buf.arguments
+        });
+      }
+      pendingToolCalls.clear();
+      return out;
+    };
+    const makeDone = () => {
+      const usage = this.toUsage(usageData);
+      let providerMetadata;
+      if (this.profile.reasoning.roundTrip === "on-tool-call-turns") {
+        if (capture === "reasoning_details" && reasoningDetails.length > 0) {
+          providerMetadata = {
+            openaiCompatReasoning: {
+              provider: this.name,
+              field: "reasoning_details",
+              value: reasoningDetails
+            }
+          };
+        } else if ((capture === "reasoning_content" || capture === "reasoning") && reasoningText) {
+          providerMetadata = {
+            openaiCompatReasoning: { provider: this.name, field: capture, value: reasoningText }
+          };
+        }
+      }
+      return {
+        type: "done",
+        usage,
+        cost: this.computeCost(model, usage, usageData?.cost),
+        providerMetadata
+      };
+    };
     try {
-      while (true) {
+      for (; ; ) {
         const { done, value } = await reader.read();
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
@@ -742,47 +1205,76 @@ var OpenAIProvider = class {
           const trimmed = line.trim();
           if (!trimmed || trimmed.startsWith(":")) continue;
           if (trimmed === "data: [DONE]") {
-            yield {
-              type: "done",
-              usage: usageData,
-              cost: usageData ? estimateOpenAICost(
-                model,
-                usageData.prompt_tokens,
-                usageData.completion_tokens,
-                usageData.cached_tokens
-              ) : void 0
-            };
+            if (thinkScanner) {
+              const flushed = thinkScanner.flush();
+              if (flushed.text) yield { type: "text_delta", content: flushed.text };
+              if (flushed.thinking) yield { type: "thinking_delta", content: flushed.thinking };
+            }
+            yield* flushPendingToolCalls();
+            yield makeDone();
             return;
           }
-          if (trimmed.startsWith("data: ")) {
-            const jsonStr = trimmed.slice(6);
-            let parsed;
-            try {
-              parsed = JSON.parse(jsonStr);
-            } catch {
-              continue;
-            }
-            if (parsed.usage) {
-              usageData = {
-                prompt_tokens: parsed.usage.prompt_tokens,
-                completion_tokens: parsed.usage.completion_tokens,
-                total_tokens: parsed.usage.total_tokens,
-                reasoning_tokens: parsed.usage.completion_tokens_details?.reasoning_tokens,
-                cached_tokens: parsed.usage.prompt_tokens_details?.cached_tokens
-              };
-              continue;
-            }
-            const delta = parsed.choices?.[0]?.delta;
-            if (!delta) continue;
-            if (delta.content) {
+          if (!trimmed.startsWith("data: ")) continue;
+          let parsed;
+          try {
+            parsed = JSON.parse(trimmed.slice(6));
+          } catch {
+            continue;
+          }
+          if (parsed.error) {
+            const message = typeof parsed.error.message === "string" ? parsed.error.message : `${this.profile.label ?? this.profile.name} stream error`;
+            throw new ProviderError({
+              provider: this.name,
+              status: 0,
+              retryable: false,
+              message,
+              body: JSON.stringify(parsed.error)
+            });
+          }
+          if (parsed.usage) {
+            usageData = parsed.usage;
+            if (!parsed.choices || parsed.choices.length === 0) continue;
+          }
+          const delta = parsed.choices?.[0]?.delta;
+          if (!delta) continue;
+          const deltaReasoning = capture === "reasoning_content" ? delta.reasoning_content : capture === "reasoning" || capture === "reasoning_details" ? delta.reasoning : void 0;
+          if (typeof deltaReasoning === "string" && deltaReasoning.length > 0) {
+            reasoningText += deltaReasoning;
+            yield { type: "thinking_delta", content: deltaReasoning };
+          }
+          if (capture === "reasoning_details" && Array.isArray(delta.reasoning_details)) {
+            reasoningDetails.push(...delta.reasoning_details);
+          }
+          if (typeof delta.content === "string" && delta.content.length > 0) {
+            if (thinkScanner) {
+              const { text, thinking } = thinkScanner.push(delta.content);
+              if (text) yield { type: "text_delta", content: text };
+              if (thinking) yield { type: "thinking_delta", content: thinking };
+            } else {
               yield { type: "text_delta", content: delta.content };
             }
-            if (delta.tool_calls) {
-              for (const tc of delta.tool_calls) {
-                if (tc.id) {
-                  indexToId.set(tc.index, tc.id);
-                }
-                const id = indexToId.get(tc.index) ?? `__pending_${tc.index}`;
+          }
+          if (delta.tool_calls) {
+            for (const tc of delta.tool_calls) {
+              if (tc.id) indexToId.set(tc.index, tc.id);
+              const id = indexToId.get(tc.index);
+              if (id === void 0) {
+                const buf2 = pendingToolCalls.get(tc.index) ?? { arguments: "" };
+                if (tc.function?.name) buf2.name = tc.function.name;
+                if (tc.function?.arguments) buf2.arguments += tc.function.arguments;
+                pendingToolCalls.set(tc.index, buf2);
+                continue;
+              }
+              const buf = pendingToolCalls.get(tc.index);
+              if (buf) {
+                pendingToolCalls.delete(tc.index);
+                yield {
+                  type: "tool_call_delta",
+                  id,
+                  name: buf.name ?? tc.function?.name,
+                  arguments: buf.arguments + (tc.function?.arguments ?? "")
+                };
+              } else {
                 yield {
                   type: "tool_call_delta",
                   id,
@@ -794,58 +1286,176 @@ var OpenAIProvider = class {
           }
         }
       }
-      yield {
-        type: "done",
-        usage: usageData,
-        cost: usageData ? estimateOpenAICost(
-          model,
-          usageData.prompt_tokens,
-          usageData.completion_tokens,
-          usageData.cached_tokens
-        ) : void 0
-      };
+      if (thinkScanner) {
+        const flushed = thinkScanner.flush();
+        if (flushed.text) yield { type: "text_delta", content: flushed.text };
+        if (flushed.thinking) yield { type: "thinking_delta", content: flushed.thinking };
+      }
+      yield* flushPendingToolCalls();
+      throw new ProviderError({
+        provider: this.name,
+        status: 0,
+        retryable: true,
+        message: `${this.profile.label ?? this.profile.name} stream ended before [DONE]`
+      });
     } finally {
       reader.releaseLock();
     }
   }
 };
 
+// src/providers/openai.ts
+var OPENAI_PRICING = {
+  // gpt-4o era — cache reads at 50% of input rate
+  "gpt-4o": [25e-7, 1e-5, 0.5],
+  "gpt-4o-mini": [15e-8, 6e-7, 0.5],
+  "gpt-4-turbo": [1e-5, 3e-5, 0.5],
+  "gpt-4": [3e-5, 6e-5, 0.5],
+  "gpt-3.5-turbo": [5e-7, 15e-7, 0.5],
+  o1: [15e-6, 6e-5, 0.5],
+  "o1-mini": [3e-6, 12e-6, 0.5],
+  "o1-pro": [15e-5, 6e-4, 0.5],
+  // gpt-4.1 / o3 / o4 era — cache reads at 25% of input rate
+  "gpt-4.1": [2e-6, 8e-6, 0.25],
+  "gpt-4.1-mini": [4e-7, 16e-7, 0.25],
+  "gpt-4.1-nano": [1e-7, 4e-7, 0.25],
+  o3: [1e-5, 4e-5, 0.25],
+  "o3-mini": [11e-7, 44e-7, 0.25],
+  "o3-pro": [2e-5, 8e-5, 0.25],
+  "o4-mini": [11e-7, 44e-7, 0.25],
+  // gpt-5 era — cache reads at 10% of input rate
+  "gpt-5": [125e-8, 1e-5, 0.1],
+  "gpt-5-mini": [25e-8, 2e-6, 0.1],
+  "gpt-5-nano": [5e-8, 4e-7, 0.1],
+  "gpt-5.1": [125e-8, 1e-5, 0.1],
+  "gpt-5.2": [175e-8, 14e-6, 0.1],
+  "gpt-5.3": [175e-8, 14e-6, 0.1],
+  "gpt-5.4": [25e-7, 15e-6, 0.1],
+  "gpt-5.4-pro": [3e-5, 18e-5, 0.1],
+  // gpt-5.5 era (flagship released 2026-04) — cache reads at 10% of input rate
+  "gpt-5.5": [5e-6, 3e-5, 0.1],
+  "gpt-5.5-pro": [3e-5, 18e-5, 0.1]
+};
+function estimateOpenAICost(model, promptTokens, completionTokens, cachedTokens) {
+  return priceFromTable(OPENAI_PRICING, model, promptTokens, completionTokens, cachedTokens);
+}
+function isOSeriesModel(model) {
+  return /^(o1|o3|o4-mini)/.test(model);
+}
+function supportsReasoningEffort(model) {
+  return isOSeriesModel(model) || /^gpt-5/.test(model);
+}
+function supportsReasoningNone(model) {
+  return /^gpt-5\.[1-9]/.test(model);
+}
+function supportsXhigh(model) {
+  return /^gpt-5\.([2-9]|\d{2,})/.test(model);
+}
+function clampReasoningEffort(model, effort) {
+  if (model.startsWith("gpt-5-pro")) return "high";
+  if (effort === "none" && !supportsReasoningNone(model)) return "minimal";
+  if (effort === "xhigh" && !supportsXhigh(model)) return "high";
+  return effort;
+}
+function effortToReasoningEffort(effort) {
+  return effort === "max" ? "xhigh" : effort;
+}
+function budgetToReasoningEffort(budget) {
+  if (budget <= 1024) return "low";
+  if (budget <= 8192) return "medium";
+  return "high";
+}
+var openaiReasoningEmit = (body, resolved, model) => {
+  const oSeries = isOSeriesModel(model);
+  const reasoningCapable = supportsReasoningEffort(model);
+  const { thinkingBudget, thinkingDisabled, activeEffort, hasBudgetOverride } = resolved;
+  let wireEffort;
+  if (reasoningCapable) {
+    if (hasBudgetOverride) {
+      wireEffort = clampReasoningEffort(model, budgetToReasoningEffort(thinkingBudget));
+    } else if (!thinkingDisabled && activeEffort) {
+      wireEffort = clampReasoningEffort(model, effortToReasoningEffort(activeEffort));
+    } else if (thinkingDisabled) {
+      wireEffort = clampReasoningEffort(model, "none");
+    }
+  }
+  if (wireEffort) body.reasoning_effort = wireEffort;
+  return { stripTemperature: oSeries || reasoningCapable && wireEffort !== void 0 };
+};
+var OPENAI_PROFILE = {
+  name: "openai",
+  label: "OpenAI",
+  defaultBaseUrl: "https://api.openai.com/v1",
+  envApiKey: "OPENAI_API_KEY",
+  envBaseUrl: "OPENAI_BASE_URL",
+  pricing: { kind: "table", table: OPENAI_PRICING },
+  reasoning: { emit: openaiReasoningEmit, capture: "none" },
+  roleFor: (role, model) => role === "system" && isOSeriesModel(model) ? "developer" : role,
+  maxTokensField: "max_completion_tokens",
+  parallelToolCalls: (model) => !isOSeriesModel(model)
+};
+var OpenAIProvider = class extends OpenAICompatibleProvider {
+  constructor(options = {}) {
+    super({ profile: OPENAI_PROFILE, ...options });
+  }
+};
+
 // src/providers/openai-responses.ts
 var OpenAIResponsesProvider = class {
   name = "openai-responses";
+  /** The Responses API honors `json_schema` (structured outputs) natively. */
+  nativeStructuredOutputSupport() {
+    return "schema";
+  }
   baseUrl;
-  apiKey;
+  apiKeySource;
   governor;
   constructor(options = {}) {
-    this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
+    this.apiKeySource = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
     this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
-    if (!this.apiKey) {
+    if (typeof this.apiKeySource === "string" && !this.apiKeySource) {
       throw new Error("OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey in options.");
     }
   }
+  /** Resolve the API key for one request (supports an expiring-token callback). */
+  async resolveKey() {
+    const key = await resolveApiKey(this.apiKeySource);
+    if (!key) {
+      throw new Error("OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey in options.");
+    }
+    return key;
+  }
+  /** Build request headers from a resolved key (used by both chat and stream). */
+  buildHeaders(apiKey) {
+    return { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` };
+  }
   // ---------------------------------------------------------------------------
   // chat - non-streaming
   // ---------------------------------------------------------------------------
   async chat(messages, options) {
+    const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, false);
     const res = await fetchWithRetry(
       `${this.baseUrl}/responses`,
       {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`
-        },
+        headers,
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor }
+      { governor: this.governor, provider: this.name }
     );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
-      throw new Error(message);
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message,
+        body: errorBody
+      });
     }
     const json = await res.json();
     return this.parseResponse(json, options.model);
@@ -854,24 +1464,28 @@ var OpenAIResponsesProvider = class {
   // stream - SSE streaming
   // ---------------------------------------------------------------------------
   async *stream(messages, options) {
+    const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, true);
     const res = await fetchWithRetry(
       `${this.baseUrl}/responses`,
       {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`
-        },
+        headers,
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor }
+      { governor: this.governor, provider: this.name }
     );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
-      throw new Error(message);
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message,
+        body: errorBody
+      });
     }
     if (!res.body) {
       throw new Error("OpenAI Responses stream has no body");
@@ -1160,7 +1774,12 @@ var OpenAIResponsesProvider = class {
       }
       case "response.failed": {
         const errorMsg = data.response?.error?.message ?? data.response?.status_details?.error?.message ?? "Unknown error";
-        throw new Error(`OpenAI Responses API error: ${errorMsg}`);
+        throw new ProviderError({
+          provider: this.name,
+          status: 0,
+          retryable: false,
+          message: `OpenAI Responses API error: ${errorMsg}`
+        });
       }
       default:
         return null;
@@ -1214,7 +1833,7 @@ function estimateAnthropicCost(model, inputTokens, outputTokens, cacheReadTokens
       }
     }
   }
-  if (!pricing) return 0;
+  if (!pricing) return void 0;
   const [inputRate, outputRate] = pricing;
   const cacheRead = cacheReadTokens ?? 0;
   const cacheWrite = cacheWriteTokens ?? 0;
@@ -1248,63 +1867,90 @@ function clampAnthropicEffort(model, effort) {
 }
 var AnthropicProvider = class {
   name = "anthropic";
+  /** Anthropic ignores native `json_schema` structurally — Axl uses a system
+   *  prompt JSON instruction + client-side Zod validation (see buildRequest). */
+  nativeStructuredOutputSupport() {
+    return "unsupported";
+  }
   baseUrl;
-  apiKey;
-  currentModel;
+  apiKeySource;
   governor;
   constructor(options = {}) {
-    this.apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? "";
+    this.apiKeySource = options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? "https://api.anthropic.com/v1").replace(/\/$/, "");
     this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
-    if (!this.apiKey) {
+    if (typeof this.apiKeySource === "string" && !this.apiKeySource) {
+      throw new Error(
+        "Anthropic API key is required. Set ANTHROPIC_API_KEY or pass apiKey in options."
+      );
+    }
+  }
+  /** Resolve the API key for one request (supports an expiring-token callback). */
+  async resolveKey() {
+    const key = await resolveApiKey(this.apiKeySource);
+    if (!key) {
       throw new Error(
         "Anthropic API key is required. Set ANTHROPIC_API_KEY or pass apiKey in options."
       );
     }
+    return key;
   }
   // ---------------------------------------------------------------------------
   // chat - non-streaming completion
   // ---------------------------------------------------------------------------
   async chat(messages, options) {
-    this.currentModel = options.model;
+    const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, false);
     const res = await fetchWithRetry(
       `${this.baseUrl}/messages`,
       {
         method: "POST",
-        headers: this.buildHeaders(),
+        headers,
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor }
+      { governor: this.governor, provider: this.name }
     );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
-      throw new Error(message);
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message,
+        body: errorBody
+      });
     }
     const json = await res.json();
-    return this.parseResponse(json);
+    return this.parseResponse(json, options.model);
   }
   // ---------------------------------------------------------------------------
   // stream - SSE streaming completion
   // ---------------------------------------------------------------------------
   async *stream(messages, options) {
+    const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, true);
     const res = await fetchWithRetry(
       `${this.baseUrl}/messages`,
       {
         method: "POST",
-        headers: this.buildHeaders(),
+        headers,
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor }
+      { governor: this.governor, provider: this.name }
     );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
-      throw new Error(message);
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message,
+        body: errorBody
+      });
     }
     if (!res.body) {
       throw new Error("Anthropic stream response has no body");
@@ -1314,10 +1960,10 @@ var AnthropicProvider = class {
   // ---------------------------------------------------------------------------
   // Internal: request building
   // ---------------------------------------------------------------------------
-  buildHeaders() {
+  buildHeaders(apiKey) {
     return {
       "Content-Type": "application/json",
-      "x-api-key": this.apiKey,
+      "x-api-key": apiKey,
       "anthropic-version": ANTHROPIC_API_VERSION
     };
   }
@@ -1502,7 +2148,7 @@ ${jsonInstruction}` : jsonInstruction;
   // ---------------------------------------------------------------------------
   // Internal: response parsing
   // ---------------------------------------------------------------------------
-  parseResponse(json) {
+  parseResponse(json, model) {
     let content = "";
     let thinkingContent = "";
     const toolCalls = [];
@@ -1531,13 +2177,7 @@ ${jsonInstruction}` : jsonInstruction;
       total_tokens: totalInput + json.usage.output_tokens,
       cached_tokens: cacheRead > 0 ? cacheRead : void 0
     } : void 0;
-    const cost = json.usage ? estimateAnthropicCost(
-      this.currentModel ?? "",
-      totalInput,
-      json.usage.output_tokens,
-      cacheRead,
-      cacheWrite
-    ) : void 0;
+    const cost = json.usage ? estimateAnthropicCost(model, totalInput, json.usage.output_tokens, cacheRead, cacheWrite) : void 0;
     return {
       content,
       thinking_content: thinkingContent || void 0,
@@ -1739,7 +2379,7 @@ function estimateGeminiCost(model, inputTokens, outputTokens, cachedTokens) {
       }
     }
   }
-  if (!pricing) return 0;
+  if (!pricing) return void 0;
   const [inputRate, outputRate] = pricing;
   const cached = cachedTokens ?? 0;
   const inputCost = (inputTokens - cached) * inputRate + cached * inputRate * 0.1;
@@ -1784,40 +2424,61 @@ function warnGemini3xEffortNone(model) {
 }
 var GeminiProvider = class {
   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() {
+    return "lossy";
+  }
   baseUrl;
-  apiKey;
+  apiKeySource;
   callCounter = 0;
   governor;
   constructor(options = {}) {
-    this.apiKey = options.apiKey ?? process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY ?? "";
+    this.apiKeySource = options.apiKey ?? process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta").replace(
       /\/$/,
       ""
     );
     this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
-    if (!this.apiKey) {
+    if (typeof this.apiKeySource === "string" && !this.apiKeySource) {
+      throw new Error("Google API key is required. Set GOOGLE_API_KEY or pass apiKey in options.");
+    }
+  }
+  /** Resolve the API key for one request (supports an expiring-token callback). */
+  async resolveKey() {
+    const key = await resolveApiKey(this.apiKeySource);
+    if (!key) {
       throw new Error("Google API key is required. Set GOOGLE_API_KEY or pass apiKey in options.");
     }
+    return key;
   }
   // ---------------------------------------------------------------------------
   // chat - non-streaming completion
   // ---------------------------------------------------------------------------
   async chat(messages, options) {
+    const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options);
     const res = await fetchWithRetry(
       `${this.baseUrl}/models/${options.model}:generateContent`,
       {
         method: "POST",
-        headers: this.buildHeaders(),
+        headers,
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor }
+      { governor: this.governor, provider: this.name }
     );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
-      throw new Error(message);
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message,
+        body: errorBody
+      });
     }
     const json = await res.json();
     return this.parseResponse(json, options.model);
@@ -1826,21 +2487,28 @@ var GeminiProvider = class {
   // stream - SSE streaming completion
   // ---------------------------------------------------------------------------
   async *stream(messages, options) {
+    const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options);
     const res = await fetchWithRetry(
       `${this.baseUrl}/models/${options.model}:streamGenerateContent?alt=sse`,
       {
         method: "POST",
-        headers: this.buildHeaders(),
+        headers,
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor }
+      { governor: this.governor, provider: this.name }
     );
     if (!res.ok) {
       const errorBody = await res.text();
       const message = this.extractErrorMessage(errorBody, res.status);
-      throw new Error(message);
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message,
+        body: errorBody
+      });
     }
     if (!res.body) {
       throw new Error("Gemini stream response has no body");
@@ -1850,10 +2518,10 @@ var GeminiProvider = class {
   // ---------------------------------------------------------------------------
   // Internal: request building
   // ---------------------------------------------------------------------------
-  buildHeaders() {
+  buildHeaders(apiKey) {
     return {
       "Content-Type": "application/json",
-      "x-goog-api-key": this.apiKey
+      "x-goog-api-key": apiKey
     };
   }
   extractErrorMessage(body, status) {
@@ -2210,6 +2878,203 @@ var GeminiProvider = class {
   }
 };
 
+// src/providers/profiles/openrouter.ts
+var OPENROUTER_PROFILE = {
+  name: "openrouter",
+  label: "OpenRouter",
+  defaultBaseUrl: "https://openrouter.ai/api/v1",
+  envApiKey: "OPENROUTER_API_KEY",
+  envBaseUrl: "OPENROUTER_BASE_URL",
+  pricing: { kind: "from-response" },
+  // Ask OpenRouter to report per-call cost in usage.cost.
+  requestDefaults: { usage: { include: true } },
+  reasoning: {
+    // OpenRouter's effort vocabulary is low|medium|high; xhigh/max clamp to high.
+    emit: reasoningObjectEmit(
+      (effort) => effort === "xhigh" || effort === "max" ? "high" : effort
+    ),
+    capture: "reasoning_details",
+    roundTrip: "on-tool-call-turns"
+  },
+  // OpenRouter normalizes to max_tokens across its backends.
+  maxTokensField: "max_tokens"
+};
+
+// src/providers/profiles/azure.ts
+var AZURE_PROFILE = {
+  name: "azure",
+  label: "Azure OpenAI",
+  // Never actually used — requireExplicitBaseUrl forces a real value first.
+  defaultBaseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1",
+  requireExplicitBaseUrl: true,
+  envApiKey: "AZURE_OPENAI_API_KEY",
+  envBaseUrl: "AZURE_OPENAI_BASE_URL",
+  authHeader: "api-key",
+  pricing: { kind: "table", table: OPENAI_PRICING },
+  reasoning: { emit: openaiReasoningEmit, capture: "none" },
+  roleFor: (role, model) => role === "system" && isOSeriesModel(model) ? "developer" : role,
+  maxTokensField: "max_completion_tokens",
+  parallelToolCalls: (model) => !isOSeriesModel(model)
+};
+
+// src/providers/profiles/xai.ts
+var acceptsReasoningEffort = (model) => model.startsWith("grok-3-mini");
+var isReasoningModel = (model) => /^grok-(3-mini|4)/.test(model);
+var XAI_PROFILE = {
+  name: "xai",
+  label: "xAI",
+  defaultBaseUrl: "https://api.x.ai/v1",
+  envApiKey: "XAI_API_KEY",
+  envBaseUrl: "XAI_BASE_URL",
+  pricing: { kind: "unknown" },
+  reasoning: {
+    emit: reasoningEffortEmit((resolved, model) => {
+      if (!acceptsReasoningEffort(model)) return void 0;
+      if (resolved.thinkingDisabled || !resolved.activeEffort) return void 0;
+      return resolved.activeEffort === "low" ? "low" : "high";
+    }),
+    capture: "reasoning"
+  },
+  capabilities: {
+    forbiddenParams: (model) => isReasoningModel(model) ? ["stop", "presence_penalty", "frequency_penalty"] : []
+  }
+};
+
+// src/providers/profiles/deepseek.ts
+var isReasoner = (model) => /reasoner|v4/i.test(model);
+var deepseekEmit = (_body, _resolved, model) => ({
+  stripTemperature: isReasoner(model)
+});
+var DEEPSEEK_PROFILE = {
+  name: "deepseek",
+  label: "DeepSeek",
+  defaultBaseUrl: "https://api.deepseek.com/v1",
+  envApiKey: "DEEPSEEK_API_KEY",
+  envBaseUrl: "DEEPSEEK_BASE_URL",
+  pricing: { kind: "unknown" },
+  reasoning: {
+    emit: deepseekEmit,
+    capture: "reasoning_content",
+    roundTrip: "on-tool-call-turns"
+  },
+  capabilities: {
+    supportsJsonSchema: false,
+    forbiddenParams: (model) => isReasoner(model) ? ["top_p", "presence_penalty", "frequency_penalty"] : []
+  }
+};
+
+// src/providers/profiles/mistral.ts
+var acceptsReasoningEffort2 = (model) => /^mistral-(small|medium)/i.test(model);
+var MISTRAL_PROFILE = {
+  name: "mistral",
+  label: "Mistral",
+  defaultBaseUrl: "https://api.mistral.ai/v1",
+  envApiKey: "MISTRAL_API_KEY",
+  envBaseUrl: "MISTRAL_BASE_URL",
+  pricing: { kind: "unknown" },
+  reasoning: {
+    emit: reasoningEffortEmit((resolved, model) => {
+      if (!acceptsReasoningEffort2(model)) return void 0;
+      if (resolved.thinkingDisabled || !resolved.activeEffort) return void 0;
+      return "high";
+    }),
+    capture: "reasoning_content"
+  }
+};
+
+// src/providers/profiles/groq.ts
+var isGptOss = (model) => /gpt-oss/i.test(model);
+var GROQ_PROFILE = {
+  name: "groq",
+  label: "Groq",
+  defaultBaseUrl: "https://api.groq.com/openai/v1",
+  envApiKey: "GROQ_API_KEY",
+  envBaseUrl: "GROQ_BASE_URL",
+  pricing: { kind: "unknown" },
+  reasoning: {
+    emit: reasoningEffortEmit((resolved, model) => {
+      if (!isGptOss(model) || resolved.thinkingDisabled || !resolved.activeEffort) {
+        return void 0;
+      }
+      const e = resolved.activeEffort;
+      return e === "xhigh" || e === "max" ? "high" : e;
+    }),
+    capture: "reasoning"
+  },
+  capabilities: {
+    emitsMessageName: false,
+    // Groq's `response_format: json_schema` is supported only on a subset of
+    // models — the `openai/gpt-oss-*` family accepts it; llama/gemma/etc 400
+    // with "This model does not support response format `json_schema`".
+    // Per-model so `nativeStructuredOutput` engages the native path only where
+    // it works and otherwise downgrades cleanly to `json_object` (verified live).
+    supportsJsonSchema: isGptOss
+  }
+};
+
+// src/providers/profiles/bedrock.ts
+var isGptOss2 = (model) => /gpt-oss/i.test(model);
+var BEDROCK_PROFILE = {
+  name: "bedrock",
+  label: "AWS Bedrock",
+  // Never used — requireExplicitBaseUrl forces a real (region-specific) value first.
+  defaultBaseUrl: "https://bedrock-mantle.us-east-1.api.aws/v1",
+  requireExplicitBaseUrl: true,
+  envApiKey: "AWS_BEARER_TOKEN_BEDROCK",
+  envBaseUrl: "BEDROCK_BASE_URL",
+  pricing: { kind: "unknown" },
+  reasoning: {
+    emit: reasoningEffortEmit((resolved, model) => {
+      if (!isGptOss2(model) || resolved.thinkingDisabled || !resolved.activeEffort) {
+        return void 0;
+      }
+      const e = resolved.activeEffort;
+      return e === "xhigh" || e === "max" ? "high" : e;
+    }),
+    capture: "reasoning"
+  }
+};
+
+// src/providers/profiles/local.ts
+function localProfile(name, label, port, envApiKey) {
+  return {
+    name,
+    label,
+    defaultBaseUrl: `http://localhost:${port}/v1`,
+    envApiKey,
+    envBaseUrl: `${envApiKey.replace(/_API_KEY$/, "")}_BASE_URL`,
+    allowMissingApiKey: true,
+    pricing: { kind: "zero" },
+    reasoning: { emit: () => {
+    }, capture: "think_tags" },
+    maxTokensField: "max_tokens"
+  };
+}
+var OLLAMA_PROFILE = localProfile("ollama", "Ollama", 11434, "OLLAMA_API_KEY");
+var VLLM_PROFILE = localProfile("vllm", "vLLM", 8e3, "VLLM_API_KEY");
+var LMSTUDIO_PROFILE = localProfile("lmstudio", "LM Studio", 1234, "LMSTUDIO_API_KEY");
+var LLAMACPP_PROFILE = localProfile("llamacpp", "llama.cpp", 8080, "LLAMACPP_API_KEY");
+var SGLANG_PROFILE = localProfile("sglang", "SGLang", 3e4, "SGLANG_API_KEY");
+var LOCAL_PROFILES = [
+  OLLAMA_PROFILE,
+  VLLM_PROFILE,
+  LMSTUDIO_PROFILE,
+  LLAMACPP_PROFILE,
+  SGLANG_PROFILE
+];
+
+// src/providers/profiles/index.ts
+var BUILTIN_PROFILES = [
+  OPENROUTER_PROFILE,
+  AZURE_PROFILE,
+  XAI_PROFILE,
+  DEEPSEEK_PROFILE,
+  MISTRAL_PROFILE,
+  GROQ_PROFILE,
+  BEDROCK_PROFILE,
+  ...LOCAL_PROFILES
+];
+
 // src/providers/registry.ts
 var builtinFactories = {
   openai: (config) => {
@@ -2249,6 +3114,23 @@ var builtinFactories = {
     });
   }
 };
+function presetFactory(profile) {
+  return (config) => {
+    const opts = config.providers?.[profile.name] ?? {};
+    return new OpenAICompatibleProvider({
+      profile,
+      apiKey: opts.apiKey,
+      baseUrl: opts.baseUrl,
+      authHeader: opts.authHeader,
+      rateLimit: opts.rateLimit
+    });
+  };
+}
+for (const profile of BUILTIN_PROFILES) {
+  if (!(profile.name in builtinFactories)) {
+    builtinFactories[profile.name] = presetFactory(profile);
+  }
+}
 var ProviderRegistry = class {
   /** Cached provider instances, keyed by provider name */
   instances = /* @__PURE__ */ new Map();
@@ -2366,123 +3248,6 @@ var import_node_async_hooks = require("async_hooks");
 var import_node_crypto = require("crypto");
 var import_zod = require("zod");
 
-// src/errors.ts
-var AxlError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "AxlError";
-    this.code = code;
-  }
-};
-var VerifyError = class extends AxlError {
-  lastOutput;
-  zodError;
-  retries;
-  constructor(lastOutput, zodError, retries) {
-    super("VERIFY_ERROR", `Schema validation failed after ${retries} retries: ${zodError.message}`);
-    this.name = "VerifyError";
-    this.lastOutput = lastOutput;
-    this.zodError = zodError;
-    this.retries = retries;
-  }
-};
-var QuorumNotMet = class extends AxlError {
-  results;
-  constructor(required, actual, results) {
-    super("QUORUM_NOT_MET", `Quorum not met: needed ${required} successes, got ${actual}`);
-    this.name = "QuorumNotMet";
-    this.results = results;
-  }
-};
-var NoConsensus = class extends AxlError {
-  constructor(reason) {
-    super("NO_CONSENSUS", `No consensus: ${reason}`);
-    this.name = "NoConsensus";
-  }
-};
-var TimeoutError = class extends AxlError {
-  constructor(operation, timeoutMs) {
-    super("TIMEOUT", `${operation} exceeded timeout of ${timeoutMs}ms`);
-    this.name = "TimeoutError";
-  }
-};
-function formatBudgetCost(cost) {
-  if (Number.isNaN(cost)) return "$NaN";
-  if (cost === Infinity) return "$Infinity";
-  if (cost === -Infinity) return "-$Infinity";
-  if (cost === 0) return "$0.00";
-  const sign = cost < 0 ? "-" : "";
-  const abs = Math.abs(cost);
-  if (abs < 1e-6) return `${sign}< $0.000001`;
-  if (abs < 1e-4) {
-    const [mantissa, exponent] = abs.toExponential(2).split("e");
-    return `${sign}$${mantissa}e${parseInt(exponent, 10)}`;
-  }
-  if (abs < 0.01) return `${sign}$${abs.toFixed(6)}`;
-  return `${sign}$${abs.toFixed(2)}`;
-}
-var BudgetExceededError = class extends AxlError {
-  limit;
-  spent;
-  policy;
-  constructor(limit, spent, policy) {
-    super(
-      "BUDGET_EXCEEDED",
-      `Budget exceeded: spent ${formatBudgetCost(spent)} of ${formatBudgetCost(
-        limit
-      )} limit (policy: ${policy})`
-    );
-    this.name = "BudgetExceededError";
-    this.limit = limit;
-    this.spent = spent;
-    this.policy = policy;
-  }
-};
-var MaxTurnsError = class extends AxlError {
-  maxTurns;
-  constructor(operation, maxTurns) {
-    super("MAX_TURNS", `${operation} exceeded maximum of ${maxTurns} turns`);
-    this.name = "MaxTurnsError";
-    this.maxTurns = maxTurns;
-  }
-};
-var GuardrailError = class extends AxlError {
-  guardrailType;
-  reason;
-  constructor(guardrailType, reason) {
-    super("GUARDRAIL_BLOCKED", `${guardrailType} guardrail blocked: ${reason}`);
-    this.name = "GuardrailError";
-    this.guardrailType = guardrailType;
-    this.reason = reason;
-  }
-};
-var ValidationError = class extends AxlError {
-  lastOutput;
-  reason;
-  retries;
-  constructor(lastOutput, reason, retries) {
-    super("VALIDATION_ERROR", `Validation failed after ${retries} retries: ${reason}`);
-    this.name = "ValidationError";
-    this.lastOutput = lastOutput;
-    this.reason = reason;
-    this.retries = retries;
-  }
-};
-var ToolDenied = class extends AxlError {
-  toolName;
-  agentName;
-  constructor(toolName, agentName) {
-    super(
-      "TOOL_DENIED",
-      `Agent "${agentName}" attempted to call tool "${toolName}" which is not in its ACL`
-    );
-    this.name = "ToolDenied";
-    this.toolName = toolName;
-    this.agentName = agentName;
-  }
-};
-
 // src/partial-json.ts
 var MAX_DEPTH = 256;
 function parsePartialJson(input) {
@@ -3057,6 +3822,14 @@ var COST_BEARING_LEAF_TYPES = [
   "memory_recall"
 ];
 var COST_LEAF_SET = new Set(COST_BEARING_LEAF_TYPES);
+function hasPositiveTokens(event) {
+  const t = event.tokens;
+  if (!t) return false;
+  return (t.input ?? 0) + (t.output ?? 0) + (t.reasoning ?? 0) > 0;
+}
+function isUsableCost(cost) {
+  return typeof cost === "number" && Number.isFinite(cost) && cost >= 0;
+}
 function eventCostContribution(event) {
   if (event.type === "ask_end") return 0;
   const c = event.cost;
@@ -3065,6 +3838,9 @@ function eventCostContribution(event) {
 function isCostBearingLeaf(event) {
   return COST_LEAF_SET.has(event.type);
 }
+function isUnpricedLeaf(event) {
+  return event.type !== void 0 && COST_LEAF_SET.has(event.type) && !isUsableCost(event.cost) && hasPositiveTokens(event);
+}
 function isRootLevel(event) {
   const d = event.depth;
   return (d ?? 0) === 0;
@@ -3113,6 +3889,10 @@ var AXL_EVENT_TYPES = [
   "string_delta",
   // Verification
   "verify",
+  // Schema capability diagnostics (spec 22, Problem E) — surface the silent
+  // structured-output cliffs (oversized appended schema, dropped refinements,
+  // streaming disabled, zero-guidance `schemaPrompt:'none'`).
+  "schema_diagnostic",
   // Observability
   "log",
   "memory_remember",
@@ -3155,6 +3935,7 @@ var LIFECYCLE_TYPES = /* @__PURE__ */ new Set([
   "delegate",
   "pipeline",
   "verify",
+  "schema_diagnostic",
   "workflow_start",
   "workflow_end",
   "checkpoint_save",
@@ -3959,6 +4740,11 @@ var REDACTION_RULES = {
   // Scrub only the delta — preserving path keeps "which fields stream" telemetry.
   string_delta: (e) => ({ ...e, data: { ...e.data, delta: REDACTED } }),
   verify: (e) => e.data.lastError !== void 0 ? { ...e, data: { ...e.data, lastError: REDACTED } } : e,
+  // `schema_diagnostic` carries only structural schema metadata — token counts,
+  // thresholds, JSON-Schema field paths, a root type name, a tool name — none of
+  // which is user content or PII (field paths are schema-shape, preserved like
+  // `string_delta.path`). Passthrough, as an explicit reviewed decision.
+  schema_diagnostic: passthrough,
   log: (e) => {
     if (!e.data || typeof e.data !== "object" || Array.isArray(e.data)) return e;
     return { ...e, data: walkObjectOneLevel(e.data, LOG_PRESERVE_KEYS) };
@@ -3991,6 +4777,80 @@ function redactEvent(event) {
   return rule(event);
 }
 
+// src/schema-diagnostics.ts
+var DEFAULT_SCHEMA_OVERSIZED_TOKENS = 4e3;
+var refinementCache = /* @__PURE__ */ new WeakMap();
+function detectDroppedRefinements(schema) {
+  const cached = refinementCache.get(schema);
+  if (cached) return cached;
+  const paths = /* @__PURE__ */ new Set();
+  let count = 0;
+  const visited = /* @__PURE__ */ new WeakSet();
+  const walk = (node, path) => {
+    if (node === null || typeof node !== "object") return;
+    if (visited.has(node)) return;
+    visited.add(node);
+    const def = node._zod?.def;
+    if (!def) return;
+    const here = () => paths.add(path === "" ? "<root>" : path);
+    const checks = def.checks;
+    if (Array.isArray(checks)) {
+      for (const check of checks) {
+        const kind = check?._zod?.def?.check;
+        if (kind === "custom") {
+          count += 1;
+          here();
+        }
+      }
+    }
+    if (def.check === "custom") {
+      count += 1;
+      here();
+    }
+    const join2 = (child) => path === "" ? child : `${path}.${child}`;
+    const shape = def.shape;
+    if (shape && typeof shape === "object") {
+      for (const [key, child] of Object.entries(shape)) walk(child, join2(key));
+    }
+    if ("element" in def) walk(def.element, `${path}[]`);
+    if (Array.isArray(def.options)) {
+      for (const opt of def.options) walk(opt, path);
+    }
+    if ("innerType" in def) walk(def.innerType, path);
+    if (Array.isArray(def.items)) {
+      def.items.forEach((item, i) => walk(item, `${path}[${i}]`));
+    }
+    if ("rest" in def && def.rest) walk(def.rest, `${path}[]`);
+    if ("catchall" in def && def.catchall) walk(def.catchall, `${path}[*]`);
+    if ("keyType" in def) walk(def.keyType, `${path}[key]`);
+    if ("valueType" in def) walk(def.valueType, `${path}[*]`);
+    if ("in" in def) walk(def.in, path);
+    if ("out" in def) walk(def.out, path);
+    if ("left" in def) walk(def.left, path);
+    if ("right" in def) walk(def.right, path);
+    if (typeof def.getter === "function") {
+      try {
+        walk(def.getter(), path);
+      } catch {
+      }
+    }
+  };
+  walk(schema, "");
+  const result = { count, paths: [...paths] };
+  refinementCache.set(schema, result);
+  return result;
+}
+var DOCS_URL = "docs/observability.md#schema-diagnostics";
+var MAX_WARNED_KEYS = 2048;
+var warnedDiagnosticKeys = /* @__PURE__ */ new Set();
+function warnSchemaDiagnosticOnce(key, message, silent) {
+  if (silent || process.env.AXL_DIAGNOSTICS_SILENT === "true") return;
+  if (warnedDiagnosticKeys.has(key)) return;
+  if (warnedDiagnosticKeys.size >= MAX_WARNED_KEYS) warnedDiagnosticKeys.clear();
+  warnedDiagnosticKeys.add(key);
+  console.warn(`[axl] ${message} See ${DOCS_URL}.`);
+}
+
 // src/config.ts
 function defineConfig(config) {
   return config;
@@ -4069,11 +4929,47 @@ function resolveConfig(config) {
 // src/context.ts
 var signalStorage = new import_node_async_hooks.AsyncLocalStorage();
 var askStorage = new import_node_async_hooks.AsyncLocalStorage();
+var inlineSchemaCache = /* @__PURE__ */ new WeakMap();
 function zodToJsonSchema(schema) {
+  const cached = inlineSchemaCache.get(schema);
+  if (cached !== void 0) return cached;
   const result = import_zod.z.toJSONSchema(schema, { unrepresentable: "any" });
   delete result.$schema;
+  Object.freeze(result);
+  inlineSchemaCache.set(schema, result);
   return result;
 }
+var promptSchemaCache = /* @__PURE__ */ new WeakMap();
+var inlineSchemaTokenCache = /* @__PURE__ */ new WeakMap();
+function estimateInlineSchemaTokens(schema) {
+  const cached = inlineSchemaTokenCache.get(schema);
+  if (cached !== void 0) return cached;
+  const tokens = estimateTokens(JSON.stringify(zodToJsonSchema(schema)));
+  inlineSchemaTokenCache.set(schema, tokens);
+  return tokens;
+}
+var nativeSchemaCache = /* @__PURE__ */ new WeakMap();
+function deriveNativeSchema(schema) {
+  const cached = nativeSchemaCache.get(schema);
+  if (cached !== void 0) return cached;
+  const json = import_zod.z.toJSONSchema(schema, { unrepresentable: "any", io: "input" });
+  delete json.$schema;
+  nativeSchemaCache.set(schema, json);
+  return json;
+}
+function renderSchemaForPrompt(schema) {
+  const cached = promptSchemaCache.get(schema);
+  if (cached !== void 0) return cached;
+  const json = import_zod.z.toJSONSchema(schema, {
+    unrepresentable: "any",
+    io: "input",
+    reused: "ref"
+  });
+  delete json.$schema;
+  const rendered = JSON.stringify(json);
+  promptSchemaCache.set(schema, rendered);
+  return rendered;
+}
 function estimateTokens(text) {
   return Math.ceil(text.length / 4);
 }
@@ -4454,12 +5350,14 @@ var WorkflowContext = class _WorkflowContext {
           depth,
           agent: agent2._name,
           stepRef,
-          askCost: { value: 0 }
+          askCost: { value: 0 },
+          askUnpriced: false
         };
         return askStorage.run(frame, async () => {
           const askStart = Date.now();
           this.emitEvent({ type: "ask_start", prompt });
           const costBefore = this.budgetContext?.totalCost ?? 0;
+          const unpricedCountBefore = this.budgetContext?.unpricedCount ?? 0;
           const resolveCtx = options?.metadata ? { metadata: { ...this.metadata, ...options.metadata } } : { metadata: this.metadata };
           const usageCapture = {};
           const doCall = async () => {
@@ -4505,6 +5403,7 @@ var WorkflowContext = class _WorkflowContext {
             ) : await doCall();
             outcome = { ok: true, result };
             const costAfter = this.budgetContext?.totalCost ?? 0;
+            const unpricedCountAfter = this.budgetContext?.unpricedCount ?? 0;
             if (this.onAgentCallComplete) {
               try {
                 this.onAgentCallComplete({
@@ -4513,6 +5412,7 @@ var WorkflowContext = class _WorkflowContext {
                   response: typeof result === "string" ? result : JSON.stringify(result),
                   model: agent2.resolveModel(resolveCtx),
                   cost: costAfter - costBefore,
+                  unpriced: frame.askUnpriced || unpricedCountAfter > unpricedCountBefore,
                   duration: Date.now() - askStart,
                   promptVersion: agent2._config.version,
                   temperature: options?.temperature ?? agent2._config.temperature,
@@ -4547,6 +5447,7 @@ var WorkflowContext = class _WorkflowContext {
                   error: "ask_end emitted without outcome \u2014 internal bug"
                 },
                 cost: frame.askCost.value,
+                ...frame.askUnpriced ? { unpriced: true } : {},
                 duration: Date.now() - askStart
               });
             } catch (emitErr) {
@@ -4630,15 +5531,32 @@ var WorkflowContext = class _WorkflowContext {
         messages.push(msg);
       }
     }
+    const schemaPromptMode = options?.schemaPrompt ?? agent2._config.schemaPrompt ?? "json-schema";
     let userContent = prompt;
+    let appendedSchemaText;
     if (options?.schema) {
-      const jsonSchema = zodToJsonSchema(options.schema);
-      userContent += `
+      const schema = options.schema;
+      if (schemaPromptMode === "none") {
+      } else if (schemaPromptMode === "json-schema") {
+        appendedSchemaText = renderSchemaForPrompt(schema);
+        userContent += `
 
 Respond with valid JSON matching this schema:
-${JSON.stringify(jsonSchema, null, 2)}`;
+${appendedSchemaText}`;
+      } else {
+        appendedSchemaText = typeof schemaPromptMode.render === "function" ? schemaPromptMode.render(schema) : schemaPromptMode.render;
+        userContent += `
+
+${appendedSchemaText}`;
+      }
     }
     messages.push({ role: "user", content: userContent });
+    this.emitSchemaDiagnostics(agent2, options, toolDefs, {
+      mode: schemaPromptMode,
+      appendedSchemaText,
+      provider,
+      model
+    });
     if (handoffMessages && handoffMessages.length > 0) {
       const handoffContext = handoffMessages.filter(
         (m) => m.role === "assistant" || m.role === "tool"
@@ -4751,7 +5669,17 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         signal: this.currentSignal
       };
       if (options?.schema && toolDefs.length === 0) {
-        chatOptions.responseFormat = { type: "json_object" };
+        const nativeOut = options?.nativeStructuredOutput ?? agent2._config.nativeStructuredOutput ?? false;
+        chatOptions.responseFormat = nativeOut ? {
+          type: "json_schema",
+          json_schema: {
+            name: "response",
+            // Input-side rendering — see `deriveNativeSchema`. Keeps the
+            // native schema consistent with the prompt and non-empty for
+            // `.transform()` schemas.
+            schema: deriveNativeSchema(options.schema)
+          }
+        } : { type: "json_object" };
       }
       const callbackMeta = this.currentCallbackMeta(agent2._name);
       const callParams = {
@@ -4869,10 +5797,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
               }
             });
           }
-          response ??= {
-            content: content2,
-            usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
-          };
+          response ??= { content: content2 };
           if (toolCalls.length > 0) {
             response.tool_calls = toolCalls;
           }
@@ -4896,7 +5821,11 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
             response: "",
             turn: turns,
             ...retryReason ? { retryReason } : {},
-            error: err instanceof Error ? err.message : String(err)
+            error: err instanceof Error ? err.message : String(err),
+            // Enrich with typed-error metadata when available. `body` is
+            // deliberately NOT emitted — it's redaction-eligible (see
+            // docs/security.md). `data.error` already carries the message.
+            ...err instanceof ProviderError ? { status: err.status, retryable: err.retryable } : {}
           }
         });
         throw err;
@@ -4960,10 +5889,13 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                 depth: handoffTargetDepth,
                 agent: descriptor.agent._name,
                 stepRef: sourceFrame?.stepRef ?? this.stepRefRoot,
-                askCost: { value: 0 }
+                askCost: { value: 0 },
+                askUnpriced: false
               };
               const handoffOptions = options ? {
                 schema: options.schema,
+                schemaPrompt: options.schemaPrompt,
+                nativeStructuredOutput: options.nativeStructuredOutput,
                 retries: options.retries,
                 metadata: options.metadata,
                 validate: options.validate,
@@ -4984,6 +5916,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                     type: "ask_end",
                     outcome: { ok: true, result },
                     cost: targetFrame.askCost.value,
+                    ...targetFrame.askUnpriced ? { unpriced: true } : {},
                     duration: Date.now() - targetAskStart
                   });
                   return result;
@@ -4995,6 +5928,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                       error: err instanceof Error ? err.message : String(err)
                     },
                     cost: targetFrame.askCost.value,
+                    ...targetFrame.askUnpriced ? { unpriced: true } : {},
                     duration: Date.now() - targetAskStart
                   });
                   throw err;
@@ -5533,6 +6467,148 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       ...providerMetadata ? { providerMetadata } : {}
     });
   }
+  /**
+   * 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).
+   */
+  emitSchemaDiagnostics(agent2, options, toolDefs, ctx) {
+    const silent = this.config.diagnostics?.silent;
+    const threshold = this.config.diagnostics?.schemaOversizedTokens ?? DEFAULT_SCHEMA_OVERSIZED_TOKENS;
+    const schema = options?.schema;
+    if (schema) {
+      if (ctx.mode === "none") {
+        this.emitEvent({
+          type: "schema_diagnostic",
+          agent: agent2._name,
+          data: { kind: "schema_prompt_none_no_guidance" }
+        });
+        warnSchemaDiagnosticOnce(
+          `${agent2._name}\0schema_prompt_none`,
+          `schemaPrompt:'none' is set on agent '${agent2._name}' with an output schema and no custom guidance \u2014 the model receives zero shape hints while the reply is still parsed against the schema, which invites a parse-failure retry loop. Provide a custom { render } or drop 'none'.`,
+          silent
+        );
+      } else {
+        const promptTokens = estimateTokens(ctx.appendedSchemaText ?? "");
+        if (promptTokens > threshold) {
+          this.emitEvent({
+            type: "schema_diagnostic",
+            agent: agent2._name,
+            data: {
+              kind: "prompt_schema_oversized",
+              estimatedTokens: promptTokens,
+              threshold,
+              site: "prompt"
+            }
+          });
+        }
+        if (ctx.mode === "json-schema") {
+          const dropped = detectDroppedRefinements(schema);
+          if (dropped.count > 0) {
+            this.emitEvent({
+              type: "schema_diagnostic",
+              agent: agent2._name,
+              data: {
+                kind: "dropped_refinements",
+                count: dropped.count,
+                paths: dropped.paths,
+                site: "prompt"
+              }
+            });
+            warnSchemaDiagnosticOnce(
+              `${agent2._name}\0dropped_refinements\0prompt\0${dropped.count}\0${dropped.paths.join(",")}`,
+              `${dropped.count} refinement(s) on the output schema for agent '${agent2._name}' (at ${dropped.paths.join(", ")}) are dropped from the model-facing JSON Schema \u2014 the model is never told the rule, then parsing rejects it. Surface it in the prompt (schemaPrompt) or repair with ctx.verify.`,
+              silent
+            );
+          }
+        }
+      }
+      const nativeOut = options?.nativeStructuredOutput ?? agent2._config.nativeStructuredOutput;
+      if (nativeOut && toolDefs.length === 0) {
+        const support = ctx.provider.nativeStructuredOutputSupport?.(ctx.model) ?? "schema";
+        if (support !== "schema") {
+          this.emitEvent({
+            type: "schema_diagnostic",
+            agent: agent2._name,
+            data: {
+              kind: "native_output_unsupported",
+              ...ctx.provider.name ? { provider: ctx.provider.name } : {},
+              support
+            }
+          });
+          warnSchemaDiagnosticOnce(
+            `${agent2._name}\0native_output_unsupported\0${ctx.provider.name ?? ctx.model}`,
+            `nativeStructuredOutput is set on agent '${agent2._name}' but provider '${ctx.provider.name ?? ctx.model}' ${support === "downgraded" ? "downgrades it to plain JSON mode" : support === "lossy" ? "sanitizes the schema lossily" : "ignores it structurally"} \u2014 the schema shape is not natively enforced. The prompt text remains the parse contract; the call proceeds.`,
+            silent
+          );
+        }
+      }
+      const rootIsObject = schema instanceof import_zod.z.ZodObject;
+      const hasTools = toolDefs.length > 0;
+      if (this._streamingEnabled && (!rootIsObject || hasTools)) {
+        const cause = !rootIsObject ? "non-object" : "tools";
+        const rootType = schema.constructor?.name ?? "unknown";
+        this.emitEvent({
+          type: "schema_diagnostic",
+          agent: agent2._name,
+          data: { kind: "streaming_disabled", rootType, cause }
+        });
+        if (cause === "non-object") {
+          warnSchemaDiagnosticOnce(
+            `${agent2._name}\0streaming_disabled\0${rootType}`,
+            `Progressive object streaming is disabled for agent '${agent2._name}' because the output schema root is ${rootType}, not a ZodObject. Wrap it \u2014 z.object({ result: <yourSchema> }) \u2014 to re-enable partial_object streaming.`,
+            silent
+          );
+        }
+      }
+    }
+    for (const tool2 of agent2._config.tools ?? []) {
+      const toolTokens = estimateInlineSchemaTokens(tool2.inputSchema);
+      if (toolTokens > threshold) {
+        this.emitEvent({
+          type: "schema_diagnostic",
+          agent: agent2._name,
+          data: {
+            kind: "prompt_schema_oversized",
+            estimatedTokens: toolTokens,
+            threshold,
+            site: "tool",
+            tool: tool2.name
+          }
+        });
+      }
+      const droppedTool = detectDroppedRefinements(tool2.inputSchema);
+      if (droppedTool.count > 0) {
+        this.emitEvent({
+          type: "schema_diagnostic",
+          agent: agent2._name,
+          data: {
+            kind: "dropped_refinements",
+            count: droppedTool.count,
+            paths: droppedTool.paths,
+            site: "tool",
+            tool: tool2.name
+          }
+        });
+        warnSchemaDiagnosticOnce(
+          `${agent2._name}\0dropped_refinements\0tool\0${tool2.name}\0${droppedTool.count}`,
+          `${droppedTool.count} refinement(s) on tool '${tool2.name}' input schema (at ${droppedTool.paths.join(", ")}) are dropped from the tool definition \u2014 the model is never told the constraint. Validate inside the tool handler instead.`,
+          silent
+        );
+      }
+    }
+  }
   buildToolDefs(agent2, resolvedHandoffs) {
     const defs = [];
     if (agent2._config.tools) {
@@ -6025,24 +7101,44 @@ ${summaryResponse.content}`
       limit,
       exceeded: false,
       policy,
-      abortController: controller
+      abortController: controller,
+      unpriced: false,
+      unpricedCount: 0,
+      unpricedWarned: false
     };
     const executeBudget = async () => {
       try {
         const value = budgetSignal ? await signalStorage.run(budgetSignal, fn) : await fn();
         const totalCost = this.budgetContext.totalCost;
         const exceeded = this.budgetContext.exceeded;
-        return { value, budgetExceeded: exceeded, totalCost };
+        const unpriced = this.budgetContext.unpriced;
+        return { value, budgetExceeded: exceeded, totalCost, unpriced };
       } catch (err) {
         if (this.budgetContext.exceeded) {
-          return { value: null, budgetExceeded: true, totalCost: this.budgetContext.totalCost };
+          return {
+            value: null,
+            budgetExceeded: true,
+            totalCost: this.budgetContext.totalCost,
+            unpriced: this.budgetContext.unpriced
+          };
         }
         if (err instanceof DOMException && err.name === "AbortError" && controller) {
-          return { value: null, budgetExceeded: true, totalCost: this.budgetContext.totalCost };
+          return {
+            value: null,
+            budgetExceeded: true,
+            totalCost: this.budgetContext.totalCost,
+            unpriced: this.budgetContext.unpriced
+          };
         }
         throw err;
       } finally {
-        if (parentBudget) parentBudget.totalCost += this.budgetContext.totalCost;
+        if (parentBudget) {
+          parentBudget.totalCost += this.budgetContext.totalCost;
+          if (this.budgetContext.unpriced) {
+            parentBudget.unpriced = true;
+            parentBudget.unpricedCount += this.budgetContext.unpricedCount;
+          }
+        }
         this.budgetContext = parentBudget;
       }
     };
@@ -6063,13 +7159,22 @@ ${summaryResponse.content}`
     }
     return executeBudget();
   }
-  /** 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() {
     if (!this.budgetContext) return null;
     return {
       spent: this.budgetContext.totalCost,
       limit: this.budgetContext.limit,
-      remaining: Math.max(0, this.budgetContext.limit - this.budgetContext.totalCost)
+      remaining: Math.max(0, this.budgetContext.limit - this.budgetContext.totalCost),
+      unpriced: this.budgetContext.unpriced
     };
   }
   // ── ctx.race() ────────────────────────────────────────────────────────
@@ -6651,6 +7756,8 @@ ${summaryResponse.content}`
       });
       return this.ask(agents[0], prompt, {
         schema: options?.schema,
+        schemaPrompt: options?.schemaPrompt,
+        nativeStructuredOutput: options?.nativeStructuredOutput,
         retries: options?.retries,
         metadata: options?.metadata,
         validate: options?.validate,
@@ -6695,6 +7802,8 @@ ${summaryResponse.content}`
     });
     return this.ask(routerAgent, prompt, {
       schema: options?.schema,
+      schemaPrompt: options?.schemaPrompt,
+      nativeStructuredOutput: options?.nativeStructuredOutput,
       retries: options?.retries,
       metadata: options?.metadata,
       validate: options?.validate,
@@ -6713,8 +7822,25 @@ ${summaryResponse.content}`
     const frame = askStorage.getStore();
     const step = (frame?.stepRef ?? this.stepRefRoot).value++;
     const cost = partial.cost;
-    if (frame && typeof cost === "number" && Number.isFinite(cost) && cost >= 0 && COST_BEARING_LEAF_TYPES.includes(partial.type)) {
-      frame.askCost.value += cost;
+    if (COST_BEARING_LEAF_TYPES.includes(partial.type)) {
+      const usable = isUsableCost(cost);
+      const unpriced = !usable && hasPositiveTokens(
+        partial
+      );
+      if (frame) {
+        if (usable) frame.askCost.value += cost;
+        else if (unpriced) frame.askUnpriced = true;
+      }
+      if (unpriced && this.budgetContext) {
+        this.budgetContext.unpriced = true;
+        this.budgetContext.unpricedCount += 1;
+        if (!this.budgetContext.unpricedWarned && Number.isFinite(this.budgetContext.limit)) {
+          this.budgetContext.unpricedWarned = true;
+          console.warn(
+            "Budget honesty: unpriced work detected \u2014 this budget's cost limit is a lower bound and is NOT enforced on unpriced models. See docs/observability.md#budget-honesty."
+          );
+        }
+      }
     }
     const event = {
       executionId: this.executionId,
@@ -8541,7 +9667,7 @@ var StreamingFlusher = class {
     await Promise.allSettled(pendings);
   }
 };
-function isAbortError(err) {
+function isAbortError2(err) {
   return typeof err === "object" && err !== null && err.name === "AbortError";
 }
 function pushEventBounded(execInfo, event, cap) {
@@ -8804,7 +9930,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       this.persistExecution(execInfo);
       return result;
     } catch (err) {
-      const aborted = isAbortError(err);
+      const aborted = isAbortError2(err);
       execInfo.status = "failed";
       execInfo.completedAt = Date.now();
       execInfo.duration = execInfo.completedAt - execInfo.startedAt;
@@ -9078,7 +10204,10 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         totalCost: 0,
         limit: budgetLimit,
         exceeded: false,
-        policy: "finish_and_stop"
+        policy: "finish_and_stop",
+        unpriced: false,
+        unpricedCount: 0,
+        unpricedWarned: false
       }
     });
   }
@@ -9113,6 +10242,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       status: "running",
       events: [],
       totalCost: 0,
+      unpriced: false,
       startedAt: Date.now(),
       duration: 0,
       metadata: liftPersistedMetadata(options?.metadata)
@@ -9131,6 +10261,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       onTrace: (event) => {
         pushEventBounded(execInfo, event, this.maxEventsPerExecution);
         execInfo.totalCost += eventCostContribution(event);
+        if (isUnpricedLeaf(event)) execInfo.unpriced = true;
         if (this.streamableExecutionIds.has(executionId)) {
           this.streamingFlusher?.append(executionId, event);
         }
@@ -9177,7 +10308,10 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         totalCost: 0,
         limit: Infinity,
         exceeded: false,
-        policy: "finish_and_stop"
+        policy: "finish_and_stop",
+        unpriced: false,
+        unpricedCount: 0,
+        unpricedWarned: false
       }
     });
     return this.spanManager.withSpanAsync(
@@ -9221,6 +10355,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         status: "running",
         events: [],
         totalCost: 0,
+        unpriced: false,
         startedAt: Date.now(),
         duration: 0,
         metadata: liftPersistedMetadata(options?.metadata)
@@ -9244,6 +10379,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         onTrace: (event) => {
           pushEventBounded(execInfo, event, this.maxEventsPerExecution);
           execInfo.totalCost += eventCostContribution(event);
+          if (isUnpricedLeaf(event)) execInfo.unpriced = true;
           if (this.streamableExecutionIds.has(executionId)) {
             this.streamingFlusher?.append(executionId, event);
           }
@@ -9291,7 +10427,10 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
           totalCost: 0,
           limit: Infinity,
           exceeded: false,
-          policy: "finish_and_stop"
+          policy: "finish_and_stop",
+          unpriced: false,
+          unpricedCount: 0,
+          unpricedWarned: false
         }
       });
       return this.spanManager.withSpanAsync(
@@ -9453,12 +10592,14 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       const completedAt = lastEvent.timestamp ?? startedAt;
       const workflowName = workflowStartEvent?.workflow ?? RECOVERED_UNKNOWN_WORKFLOW;
       const totalCost = boundedEvents.reduce((sum, e) => sum + eventCostContribution(e), 0);
+      const unpriced = boundedEvents.some(isUnpricedLeaf);
       const synthesized = {
         executionId: id,
         workflow: workflowName,
         status: "failed",
         events: boundedEvents,
         totalCost,
+        unpriced,
         startedAt,
         completedAt,
         duration: completedAt - startedAt,
@@ -9760,8 +10901,8 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
    * Works with both `createContext()` and `execute()` calls inside `fn`.
    */
   async trackCost(fn) {
-    const { result, cost } = await this.trackExecution(fn);
-    return { result, cost };
+    const { result, cost, unpriced } = await this.trackExecution(fn);
+    return { result, cost, unpriced };
   }
   /**
    * Track cost and execution metadata across any runtime operations within the given function.
@@ -9806,10 +10947,12 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
     const workflowCalls = /* @__PURE__ */ new Map();
     const tokens = { input: 0, output: 0, reasoning: 0 };
     let agentCalls = 0;
+    let unpriced = false;
     const capturedTraces = options?.captureTraces ? [] : void 0;
     const listener = (event) => {
       if (!scope.trackedIds.has(event.executionId)) return;
       scope.totalCost += eventCostContribution(event);
+      if (isUnpricedLeaf(event)) unpriced = true;
       if (event.type === "agent_call_end") {
         if (event.model) modelCalls.set(event.model, (modelCalls.get(event.model) ?? 0) + 1);
         agentCalls++;
@@ -9847,6 +10990,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       return {
         result,
         cost: scope.totalCost,
+        unpriced,
         ...capturedTraces ? { traces: capturedTraces } : {},
         metadata: {
           models: [...modelCalls.keys()],
@@ -10741,22 +11885,40 @@ var OpenAIEmbedder = class {
     this.dimensions = options.dimensions ?? 1536;
   }
   async embed(texts, signal) {
-    const response = await fetchWithRetry(`${this.baseUrl}/v1/embeddings`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`
+    const response = await fetchWithRetry(
+      `${this.baseUrl}/v1/embeddings`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          model: this.model,
+          input: texts,
+          dimensions: this.dimensions
+        }),
+        signal
       },
-      body: JSON.stringify({
-        model: this.model,
-        input: texts,
-        dimensions: this.dimensions
-      }),
-      signal
-    });
+      // Participate in the same typed-error contract as the provider adapters: a
+      // thrown network failure normalizes to ProviderError{status:0,provider:'openai'}.
+      { provider: "openai" }
+    );
     if (!response.ok) {
       const body = await response.text();
-      throw new Error(`OpenAI embeddings API error (${response.status}): ${body}`);
+      let detail = body;
+      try {
+        const json2 = JSON.parse(body);
+        detail = json2.error?.message ?? json2.message ?? body;
+      } catch {
+      }
+      throw buildProviderError({
+        provider: "openai",
+        status: response.status,
+        headers: response.headers,
+        message: `OpenAI embeddings API error (${response.status}): ${detail}`,
+        body
+      });
     }
     const json = await response.json();
     const vectors = json.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
@@ -10898,57 +12060,87 @@ function cosineSimilarity2(a, b) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AXL_EVENT_TYPES,
+  AZURE_PROFILE,
   AnthropicProvider,
   AxlError,
   AxlEventBus,
   AxlRuntime,
   AxlStream,
+  BEDROCK_PROFILE,
+  BUILTIN_PROFILES,
   BudgetExceededError,
   CONFIG_CANDIDATES,
   COST_BEARING_LEAF_TYPES,
+  DEEPSEEK_PROFILE,
   EventStreamOverflowError,
+  GROQ_PROFILE,
   GeminiProvider,
   GuardrailError,
   InMemoryVectorStore,
+  LLAMACPP_PROFILE,
+  LMSTUDIO_PROFILE,
+  MISTRAL_PROFILE,
   MaxTurnsError,
   McpManager,
   MemoryManager,
   MemoryStore,
   NoConsensus,
   NoopSpanManager,
+  OLLAMA_PROFILE,
+  OPENAI_PRICING,
+  OPENAI_PROFILE,
+  OPENROUTER_PROFILE,
+  OpenAICompatibleProvider,
   OpenAIEmbedder,
   OpenAIProvider,
   OpenAIResponsesProvider,
+  ProviderError,
   ProviderRegistry,
   QuorumNotMet,
   REDACTED,
   REDACTION_RULES,
   RateLimiter,
   RedisStore,
+  SGLANG_PROFILE,
   SQLiteStore,
   Session,
   SqliteVectorStore,
+  ThinkTagScanner,
   TimeoutError,
   ToolDenied,
+  VLLM_PROFILE,
   ValidationError,
   VerifyError,
   WorkflowContext,
+  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,