@axlsdk/axl 0.22.2 → 0.23.0

package/dist/index.js

@@ -170,9 +170,15 @@ var NoConsensus = class extends AxlError {
   }
 };
 var TimeoutError = class extends AxlError {
-  constructor(operation, timeoutMs) {
-    super("TIMEOUT", `${operation} exceeded timeout of ${timeoutMs}ms`);
+  /** Latency attribution for the timed-out operation, when measurable. */
+  breakdown;
+  constructor(operation, timeoutMs, breakdown) {
+    super(
+      "TIMEOUT",
+      `${operation} exceeded timeout of ${timeoutMs}ms` + (breakdown ? ` (elapsed ${breakdown.elapsedMs}ms: queued ${breakdown.queuedMs}ms, retries ${breakdown.retryMs}ms, wire ${breakdown.wireMs}ms, other ${breakdown.otherMs}ms)` : "")
+    );
     this.name = "TimeoutError";
+    if (breakdown) this.breakdown = breakdown;
   }
 };
 function formatBudgetCost(cost) {
@@ -719,6 +725,7 @@ var ProviderError = class extends AxlError {
     this.retryAfterMs = args.retryAfterMs;
     this.requestId = args.requestId;
     this.body = args.body;
+    if (args.timing) this.timing = args.timing;
   }
 };
 function isRetryableStatus(status) {
@@ -770,7 +777,8 @@ function buildProviderError(args) {
     message: args.message,
     retryAfterMs: args.headers ? parseRetryAfter(args.headers) : void 0,
     requestId: args.headers ? extractRequestId(args.headers) : void 0,
-    body: args.body
+    body: args.body,
+    timing: args.timing
   });
 }
 
@@ -807,14 +815,33 @@ async function fetchWithRetry(input, init, opts) {
   const maxRetries = opts?.maxRetries ?? MAX_RETRIES;
   const governor = opts?.governor;
   const provider = opts?.provider ?? "unknown";
+  const observer = opts?.timing;
   let acquired = false;
+  let queuedMs = 0;
   if (governor) {
+    const acquireStart = Date.now();
     await governor.acquire(init?.signal ?? void 0);
     acquired = true;
-  }
+    queuedMs = Date.now() - acquireStart;
+  }
+  let firstDispatchedAt = 0;
+  let dispatchedAt = 0;
+  let headersAt = 0;
+  const reportComplete = (attempts) => {
+    observer?.onComplete?.({
+      queuedMs,
+      attempts,
+      retryMs: dispatchedAt - firstDispatchedAt,
+      dispatchedAt,
+      headersAt
+    });
+  };
   try {
     for (let attempt = 0; ; attempt++) {
       let res;
+      dispatchedAt = Date.now();
+      if (attempt === 0) firstDispatchedAt = dispatchedAt;
+      observer?.onDispatch?.(attempt + 1, dispatchedAt);
       try {
         res = await fetch(input, { ...init, redirect: "manual" });
       } catch (err) {
@@ -829,11 +856,14 @@ async function fetchWithRetry(input, init, opts) {
         await sleep2(jitter(BASE_DELAY_MS * 2 ** attempt), init?.signal ?? void 0);
         continue;
       }
+      headersAt = Date.now();
       governor?.observe(res);
       if (res.ok || !RETRYABLE_STATUS_CODES.has(res.status) || attempt >= maxRetries) {
+        reportComplete(attempt + 1);
         return res;
       }
       if (init?.signal?.aborted) {
+        reportComplete(attempt + 1);
         return res;
       }
       const retryAfterMs = parseRetryAfter(res.headers);
@@ -845,6 +875,86 @@ async function fetchWithRetry(input, init, opts) {
   }
 }
 
+// src/providers/call-timing.ts
+var CallTimingRecorder = class {
+  fetchTiming;
+  firstTokenAt;
+  /** Cumulative time awaiting `reader.read()`, i.e. transport, not consumer. */
+  readWaitMs = 0;
+  /** Pass as `timing` in the `fetchWithRetry` options object. */
+  observer = {
+    onComplete: (timing) => {
+      this.fetchTiming = timing;
+    }
+  };
+  /**
+   * Await one body read, charging only the wait itself to `wireMs`. Time the
+   * consumer spends between reads is excluded because it elapses outside this
+   * call.
+   */
+  async read(reader) {
+    const start = Date.now();
+    try {
+      return await reader.read();
+    } finally {
+      this.readWaitMs += Date.now() - start;
+    }
+  }
+  /** Stamp the first content delta. Idempotent — only the first call counts. */
+  markFirstToken() {
+    this.firstTokenAt ??= Date.now();
+  }
+  /**
+   * Timing for a non-streaming call. Call once the response body is parsed.
+   *
+   * Also the right reading at an adapter's `!res.ok` throw site on BOTH
+   * transports: headers have arrived, no body will be streamed, so
+   * dispatch → now is the whole of what the provider cost us.
+   */
+  chatTiming() {
+    const t = this.fetchTiming;
+    if (!t) return void 0;
+    return {
+      queuedMs: t.queuedMs,
+      attempts: t.attempts,
+      retryMs: t.retryMs,
+      ttfbMs: Math.max(0, t.headersAt - t.dispatchedAt),
+      wireMs: Math.max(0, Date.now() - t.dispatchedAt)
+    };
+  }
+  /** Timing for a streamed call. Call when building the terminal `done` chunk. */
+  streamTiming() {
+    const t = this.fetchTiming;
+    if (!t) return void 0;
+    const ttfbMs = Math.max(0, t.headersAt - t.dispatchedAt);
+    return {
+      queuedMs: t.queuedMs,
+      attempts: t.attempts,
+      retryMs: t.retryMs,
+      ttfbMs,
+      ...this.firstTokenAt !== void 0 ? { firstTokenMs: Math.max(0, this.firstTokenAt - t.dispatchedAt) } : {},
+      wireMs: ttfbMs + this.readWaitMs
+    };
+  }
+};
+async function* withCallTiming(recorder, source) {
+  for await (const chunk of source) {
+    if (chunk.type === "text_delta" || chunk.type === "thinking_delta") {
+      recorder.markFirstToken();
+      yield chunk;
+    } else if (chunk.type === "done") {
+      const timing = recorder.streamTiming();
+      yield timing ? { ...chunk, timing } : chunk;
+    } else {
+      yield chunk;
+    }
+  }
+}
+function withChatTiming(recorder, response) {
+  const timing = recorder.chatTiming();
+  return timing ? { ...response, timing } : response;
+}
+
 // src/providers/rate-limiter.ts
 function abortError() {
   return Object.assign(new Error("The operation was aborted"), { name: "AbortError" });
@@ -1297,6 +1407,7 @@ var OpenAICompatibleProvider = class {
   async chat(messages, options) {
     const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, false);
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/chat/completions`,
       {
@@ -1305,7 +1416,7 @@ var OpenAICompatibleProvider = class {
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -1314,15 +1425,20 @@ var OpenAICompatibleProvider = class {
         status: res.status,
         headers: res.headers,
         message: this.extractErrorMessage(errorBody, res.status),
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     const json = await res.json();
-    return this.parseResponse(json, this.requestModel(body, options.model), body);
+    return withChatTiming(
+      recorder,
+      this.parseResponse(json, this.requestModel(body, options.model), body)
+    );
   }
   async *stream(messages, options) {
     const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, true);
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/chat/completions`,
       {
@@ -1331,7 +1447,7 @@ var OpenAICompatibleProvider = class {
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -1340,13 +1456,17 @@ var OpenAICompatibleProvider = class {
         status: res.status,
         headers: res.headers,
         message: this.extractErrorMessage(errorBody, res.status),
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     if (!res.body) {
       throw new Error(`${this.profile.label ?? this.profile.name} stream response has no body`);
     }
-    yield* this.parseSSEStream(res.body, this.requestModel(body, options.model), body);
+    yield* withCallTiming(
+      recorder,
+      this.parseSSEStream(res.body, this.requestModel(body, options.model), body, recorder)
+    );
   }
   // ---------------------------------------------------------------------------
   // Request building
@@ -1573,7 +1693,21 @@ var OpenAICompatibleProvider = class {
   // ---------------------------------------------------------------------------
   // SSE streaming
   // ---------------------------------------------------------------------------
-  async *parseSSEStream(body, model, request) {
+  /**
+   * PRIVATE, and deliberately not an extension point. It was `protected`, but
+   * nothing in or out of this repo overrides it, and `protected` could not
+   * carry the guarantee it appeared to: TypeScript checks an override for
+   * assignability, and a function type with fewer parameters is assignable to
+   * one with more — so an override that simply dropped the recorder still
+   * compiled and then reported `wireMs === ttfbMs` for the whole subclass. Its
+   * type is not exported from the barrel either, so a subclass author could not
+   * name what they were required to accept.
+   *
+   * A provider with a different wire format implements `Provider` (see
+   * docs/providers.md); an OpenAI-compatible one adds a `ProviderProfile`.
+   * Neither needs to reach in here.
+   */
+  async *parseSSEStream(body, model, request, timing) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
@@ -1633,7 +1767,7 @@ var OpenAICompatibleProvider = class {
     };
     try {
       for (; ; ) {
-        const { done, value } = await reader.read();
+        const { done, value } = await timing.read(reader);
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");
@@ -1665,7 +1799,8 @@ var OpenAICompatibleProvider = class {
               status: 0,
               retryable: false,
               message,
-              body: JSON.stringify(parsed.error)
+              body: JSON.stringify(parsed.error),
+              timing: timing.streamTiming()
             });
           }
           if (parsed.model !== void 0 || parsed.service_tier !== void 0 || parsed.serviceTier !== void 0) {
@@ -1737,7 +1872,8 @@ var OpenAICompatibleProvider = class {
         provider: this.name,
         status: 0,
         retryable: true,
-        message: `${this.profile.label ?? this.profile.name} stream ended before [DONE]`
+        message: `${this.profile.label ?? this.profile.name} stream ended before [DONE]`,
+        timing: timing.streamTiming()
       });
     } finally {
       reader.releaseLock();
@@ -1776,12 +1912,12 @@ var DIRECT_OPENAI_CATALOG = [
   {
     aliases: ["gpt-5.6", "gpt-5.6-sol"],
     snapshotBase: "gpt-5.6-sol",
-    short: { input: 5 / M, cachedInput: 0.5 / M, cacheWrite: 6.25 / M, output: 30 / M },
+    short: { input: 4 / M, cachedInput: 0.4 / M, cacheWrite: 5 / M, output: 20 / M },
     long: withLongContext({
-      input: 5 / M,
-      cachedInput: 0.5 / M,
-      cacheWrite: 6.25 / M,
-      output: 30 / M
+      input: 4 / M,
+      cachedInput: 0.4 / M,
+      cacheWrite: 5 / M,
+      output: 20 / M
     }),
     contextBoundary: LONG_CONTEXT_BOUNDARY
   },
@@ -2118,17 +2254,22 @@ function resolveOpenAIReasoningEffort(model, resolved) {
   }
   return resolved.thinkingDisabled ? clampReasoningEffort(model, "none") : void 0;
 }
-var warnedChatMaxDowngrades = /* @__PURE__ */ new Set();
 function resolveOpenAIChatReasoningEffort(model, resolved) {
   const effort = resolveOpenAIReasoningEffort(model, resolved);
-  if (effort !== "max") return effort;
-  if (resolved.activeEffort === "max" && !warnedChatMaxDowngrades.has(model)) {
-    warnedChatMaxDowngrades.add(model);
-    console.warn(
-      `[axl] OpenAI Chat Completions does not accept effort "max" for ${model}; using "xhigh". Use the OpenAI Responses provider for native "max".`
-    );
-  }
-  return "xhigh";
+  return effort === "max" ? "xhigh" : effort;
+}
+function resolveOpenAIEffortResolution(options, resolveWireEffort, endpoint) {
+  const resolved = resolveThinkingOptions(options);
+  if (resolved.effort === void 0 || resolved.hasBudgetOverride) return void 0;
+  const model = typeof options.providerOptions?.model === "string" ? options.providerOptions.model : options.model;
+  const effective = resolveWireEffort(model, resolved);
+  if (effective === void 0 || effective === resolved.effort) return void 0;
+  return {
+    requested: resolved.effort,
+    effective,
+    clamped: true,
+    cause: `${endpoint} does not accept reasoning effort '${resolved.effort}' for ${model}; using '${effective}'`
+  };
 }
 var openaiReasoningEmit = (body, resolved, model) => {
   const oSeries = isOSeriesModel(model);
@@ -2153,6 +2294,15 @@ var OpenAIProvider = class extends OpenAICompatibleProvider {
   constructor(options = {}) {
     super({ profile: OPENAI_PROFILE, ...options });
   }
+  /** Report a clamped `effort` — Chat Completions caps `'max'` at `'xhigh'` and
+   *  rejects `'none'` before gpt-5.1 (clamped to `'minimal'`). */
+  effortResolution(options) {
+    return resolveOpenAIEffortResolution(
+      options,
+      resolveOpenAIChatReasoningEffort,
+      "OpenAI Chat Completions"
+    );
+  }
   computeCost(model, usage, _reportedCost, context) {
     return usage ? estimateDirectOpenAICost(model, usage, { ...context, baseUrl: this.baseUrl }) : void 0;
   }
@@ -2199,6 +2349,12 @@ var OpenAIResponsesProvider = class {
   inputCapabilities(model) {
     return model.trim().length > 0 ? { image: { sources: ["url", "bytes", "base64", "provider-file"] } } : {};
   }
+  /** Report a clamped `effort`. Responses accepts the native `'max'` tier that
+   *  Chat Completions caps, but still clamps `'none'` before gpt-5.1, `'xhigh'`
+   *  below gpt-5.2, and everything to `'high'` on gpt-5-pro. */
+  effortResolution(options) {
+    return resolveOpenAIEffortResolution(options, resolveOpenAIReasoningEffort, "OpenAI Responses");
+  }
   validateInput(request) {
     const modelOverride = request.providerOptions?.model;
     const effectiveModel = typeof modelOverride === "string" ? modelOverride : request.model;
@@ -2276,6 +2432,7 @@ var OpenAIResponsesProvider = class {
   async chat(messages, options) {
     const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, false);
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/responses`,
       {
@@ -2284,7 +2441,7 @@ var OpenAIResponsesProvider = class {
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -2294,11 +2451,15 @@ var OpenAIResponsesProvider = class {
         status: res.status,
         headers: res.headers,
         message,
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     const json = await res.json();
-    return this.parseResponse(json, this.requestModel(body, options.model), body);
+    return withChatTiming(
+      recorder,
+      this.parseResponse(json, this.requestModel(body, options.model), body)
+    );
   }
   // ---------------------------------------------------------------------------
   // stream - SSE streaming
@@ -2306,6 +2467,7 @@ var OpenAIResponsesProvider = class {
   async *stream(messages, options) {
     const headers = this.buildHeaders(await this.resolveKey());
     const body = this.buildRequestBody(messages, options, true);
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/responses`,
       {
@@ -2314,7 +2476,7 @@ var OpenAIResponsesProvider = class {
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -2324,13 +2486,17 @@ var OpenAIResponsesProvider = class {
         status: res.status,
         headers: res.headers,
         message,
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     if (!res.body) {
       throw new Error("OpenAI Responses stream has no body");
     }
-    yield* this.parseSSEStream(res.body, this.requestModel(body, options.model), body);
+    yield* withCallTiming(
+      recorder,
+      this.parseSSEStream(res.body, this.requestModel(body, options.model), body, recorder)
+    );
   }
   // ---------------------------------------------------------------------------
   // Internal: build request body
@@ -2532,7 +2698,7 @@ var OpenAIResponsesProvider = class {
   // ---------------------------------------------------------------------------
   // Internal: parse SSE stream
   // ---------------------------------------------------------------------------
-  async *parseSSEStream(body, model, request) {
+  async *parseSSEStream(body, model, request, timing) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
@@ -2540,7 +2706,7 @@ var OpenAIResponsesProvider = class {
     let eventType = "";
     try {
       while (true) {
-        const { done, value } = await reader.read();
+        const { done, value } = await timing.read(reader);
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");
@@ -2560,7 +2726,14 @@ var OpenAIResponsesProvider = class {
             } catch {
               continue;
             }
-            const chunk = this.handleStreamEvent(eventType, data, model, callIdMap, request);
+            const chunk = this.handleStreamEvent(
+              eventType,
+              data,
+              model,
+              callIdMap,
+              request,
+              timing
+            );
             if (chunk) {
               yield chunk;
               if (chunk.type === "done") return;
@@ -2574,7 +2747,7 @@ var OpenAIResponsesProvider = class {
       reader.releaseLock();
     }
   }
-  handleStreamEvent(eventType, data, model, callIdMap, request) {
+  handleStreamEvent(eventType, data, model, callIdMap, request, timing) {
     switch (eventType) {
       case "response.output_text.delta":
         return { type: "text_delta", content: data.delta ?? "" };
@@ -2630,7 +2803,8 @@ var OpenAIResponsesProvider = class {
           provider: this.name,
           status: 0,
           retryable: false,
-          message: `OpenAI Responses API error: ${errorMsg}`
+          message: `OpenAI Responses API error: ${errorMsg}`,
+          timing: timing.streamTiming()
         });
       }
       default:
@@ -2698,6 +2872,12 @@ function hasAnthropicProviderFileImage(messages) {
   );
 }
 var CLAUDE_CAPABILITIES = {
+  "claude-fable-5-1": {
+    thinking: "adaptive-always-on",
+    effortLevels: ["low", "medium", "high", "xhigh", "max"],
+    manualBudget: false,
+    stripTemperature: true
+  },
   "claude-fable-5": {
     thinking: "adaptive-always-on",
     effortLevels: ["low", "medium", "high", "xhigh", "max"],
@@ -2788,10 +2968,18 @@ var PRE_INFERENCE_GEO_MODELS = /* @__PURE__ */ new Set([
 function resolveClaudeCapability(model) {
   return CLAUDE_CAPABILITIES[model] ?? (LEGACY_CLAUDE_MODELS.has(model) ? LEGACY_CLAUDE_CAPABILITY : void 0);
 }
+var DEFAULT_CACHE_READ_MULTIPLIER = 0.1;
 var ANTHROPIC_RATES = {
+  "claude-fable-5-1": { input: 1e-5, output: 5e-5, cacheReadMultiplier: 0.025 },
   "claude-fable-5": { input: 1e-5, output: 5e-5 },
+  // Limited availability (Glasswing). Priced from the public pricing table; no
+  // CLAUDE_CAPABILITIES entry, because their thinking semantics are not
+  // documented per-model and an unverified capability would send the wrong
+  // request shape. Unknown IDs pass through unmodified, which is the safe side.
+  "claude-mythos-5-1": { input: 1e-5, output: 5e-5, cacheReadMultiplier: 0.025 },
+  "claude-mythos-5": { input: 1e-5, output: 5e-5 },
   "claude-opus-5": { input: 5e-6, output: 25e-6 },
-  "claude-sonnet-5": { input: 3e-6, output: 15e-6, sonnet5Intro: true },
+  "claude-sonnet-5": { input: 2e-6, output: 1e-5 },
   "claude-opus-4-8": { input: 5e-6, output: 25e-6 },
   "claude-opus-4-7": { input: 5e-6, output: 25e-6 },
   "claude-opus-4-6": { input: 5e-6, output: 25e-6 },
@@ -2830,7 +3018,7 @@ function anthropicStreamErrorStatus(type) {
       return 0;
   }
 }
-function estimateAnthropicCost(model, usage, now = /* @__PURE__ */ new Date()) {
+function estimateAnthropicCost(model, usage) {
   if (!model || !isValidTokenCount(usage.inputTokens) || !isValidTokenCount(usage.outputTokens)) {
     return void 0;
   }
@@ -2849,8 +3037,9 @@ function estimateAnthropicCost(model, usage, now = /* @__PURE__ */ new Date()) {
   if (usage.aggregateCacheWriteTokens !== void 0 && (!isValidTokenCount(usage.aggregateCacheWriteTokens) || usage.aggregateCacheWriteTokens !== cacheWriteTotal)) {
     return void 0;
   }
-  const { input, output } = rate.sonnet5Intro && now < /* @__PURE__ */ new Date("2026-09-01T00:00:00Z") ? { input: 2e-6, output: 1e-5 } : rate;
-  return usage.inputTokens * input + cacheRead * input * 0.1 + cacheWrite5m * input * 1.25 + cacheWrite1h * input * 2 + usage.outputTokens * output;
+  const { input, output } = rate;
+  const cacheReadRate = input * (rate.cacheReadMultiplier ?? DEFAULT_CACHE_READ_MULTIPLIER);
+  return usage.inputTokens * input + cacheRead * cacheReadRate + cacheWrite5m * input * 1.25 + cacheWrite1h * input * 2 + usage.outputTokens * output;
 }
 var THINKING_BUDGETS = {
   low: 1024,
@@ -2874,14 +3063,6 @@ function budgetToClaudeEffort(budget) {
   if (budget <= THINKING_BUDGETS.xhigh) return "xhigh";
   return "max";
 }
-var warnedFableDisable = /* @__PURE__ */ new Set();
-function warnFableDisable(model) {
-  if (warnedFableDisable.has(model)) return;
-  warnedFableDisable.add(model);
-  console.warn(
-    `[axl] thinking cannot be disabled on Anthropic ${model}; using adaptive thinking at effort 'low'.`
-  );
-}
 function resolveClaudeThinking(model, resolved) {
   const capability = resolveClaudeCapability(model);
   if (!capability) return { stripTemperature: false };
@@ -2901,11 +3082,14 @@ function resolveClaudeThinking(model, resolved) {
     }
     if (resolved.thinkingDisabled) {
       if (capability.thinking === "adaptive-always-on") {
-        warnFableDisable(model);
         return {
           thinking: { type: "adaptive" },
           outputConfig: { effort: "low" },
-          stripTemperature: true
+          stripTemperature: true,
+          clamp: {
+            effective: "low",
+            cause: `thinking cannot be disabled on Anthropic ${model}; using adaptive thinking at effort 'low'`
+          }
         };
       }
       if (activeEffort && capability.disableAt && !isEffortAtOrBelow(activeEffort, capability.disableAt)) {
@@ -2967,7 +3151,16 @@ function resolveClaudeThinking(model, resolved) {
     return {
       thinking: { type: "enabled", budget_tokens: budget },
       manualBudget: budget,
-      stripTemperature: true
+      stripTemperature: true,
+      // Legacy models take `budget_tokens`, not an effort level, and have no
+      // `effortLevels` — so `clampAnthropicEffort` folds 'max'/'xhigh' down to
+      // the 'high' tier and the request silently carries that tier's budget.
+      // Report it: an unreported budget-tier downgrade is exactly the silent
+      // clamp this capability exists to expose.
+      clamp: activeEffort === resolved.activeEffort ? void 0 : {
+        effective: activeEffort,
+        cause: `Anthropic ${model} takes thinking budget_tokens rather than an effort level, and its ceiling tier is '${activeEffort}'; effort '${resolved.activeEffort}' sends budget_tokens ${budget}`
+      }
     };
   }
   return { stripTemperature: capability.stripTemperature ?? false };
@@ -3078,6 +3271,34 @@ function mergeAnthropicUsage(initial, update) {
 }
 var AnthropicProvider = class {
   name = "anthropic";
+  /** Report a clamped `effort`. Anthropic clamps to each model's supported
+   *  `output_config.effort` levels, and models that always think fall back to
+   *  adaptive `'low'` when asked to disable thinking. Only reported when the
+   *  effective level is what the request body actually carries; an explicit
+   *  `thinkingBudget` is documented to override `effort`, so it is not a clamp. */
+  effortResolution(options) {
+    const resolved = resolveThinkingOptions(options);
+    if (resolved.effort === void 0 || resolved.hasBudgetOverride) return void 0;
+    const model = typeof options.providerOptions?.model === "string" ? options.providerOptions.model : options.model;
+    if (ANTHROPIC_RATES[model] && !resolveClaudeCapability(model)) {
+      return {
+        requested: resolved.effort,
+        effective: "unset",
+        clamped: true,
+        cause: `Axl has no capability entry for Anthropic ${model}, so no reasoning control was sent and effort '${resolved.effort}' had no effect`
+      };
+    }
+    const config = resolveClaudeThinking(model, resolved);
+    const wireEffort = typeof config.outputConfig?.effort === "string" ? config.outputConfig.effort : void 0;
+    const effective = config.clamp?.effective ?? wireEffort;
+    if (effective === void 0 || effective === resolved.effort) return void 0;
+    return {
+      requested: resolved.effort,
+      effective,
+      clamped: true,
+      cause: config.clamp?.cause ?? `Anthropic ${model} does not support effort '${resolved.effort}'; using '${effective}'`
+    };
+  }
   inputCapabilities(model) {
     return model.trim().length > 0 ? { image: { sources: ["url", "bytes", "base64", "provider-file"] } } : {};
   }
@@ -3122,6 +3343,10 @@ var AnthropicProvider = class {
   }
   /** Anthropic ignores native `json_schema` structurally — Axl uses a system
    *  prompt JSON instruction + client-side Zod validation (see buildRequest). */
+  /** The only built-in adapter that honors `promptCache` (see buildBody). */
+  realizesPromptCache() {
+    return true;
+  }
   nativeStructuredOutputSupport() {
     return "unsupported";
   }
@@ -3163,6 +3388,7 @@ var AnthropicProvider = class {
     );
     const body = this.buildRequestBody(messages, options, false);
     const pricingContext = pricingContextFromBody(body);
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/messages`,
       {
@@ -3171,7 +3397,7 @@ var AnthropicProvider = class {
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -3181,11 +3407,12 @@ var AnthropicProvider = class {
         status: res.status,
         headers: res.headers,
         message,
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     const json = await res.json();
-    return this.parseResponse(json, pricingContext);
+    return withChatTiming(recorder, this.parseResponse(json, pricingContext));
   }
   // ---------------------------------------------------------------------------
   // stream - SSE streaming completion
@@ -3197,6 +3424,7 @@ var AnthropicProvider = class {
     );
     const body = this.buildRequestBody(messages, options, true);
     const pricingContext = pricingContextFromBody(body);
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/messages`,
       {
@@ -3205,7 +3433,7 @@ var AnthropicProvider = class {
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -3215,13 +3443,17 @@ var AnthropicProvider = class {
         status: res.status,
         headers: res.headers,
         message,
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     if (!res.body) {
       throw new Error("Anthropic stream response has no body");
     }
-    yield* this.parseSSEStream(res.body, pricingContext, res.headers);
+    yield* withCallTiming(
+      recorder,
+      this.parseSSEStream(res.body, pricingContext, res.headers, recorder)
+    );
   }
   // ---------------------------------------------------------------------------
   // Internal: request building
@@ -3256,14 +3488,31 @@ var AnthropicProvider = class {
       max_tokens: options.maxTokens ?? 4096,
       stream
     };
-    if (systemText) {
+    const po = options.providerOptions;
+    const callerOwnsPrefix = po !== void 0 && (po.cache_control !== void 0 || po.system !== void 0 || po.tools !== void 0);
+    const promptCache = options.promptCache === true && !callerOwnsPrefix;
+    const anchorOnSystem = promptCache && systemMessages.length > 0 && systemMessages[0].origin !== "runtime";
+    if (anchorOnSystem) {
+      body.system = systemMessages.map((m, index) => ({
+        type: "text",
+        text: typeof m.content === "string" ? m.content : "",
+        ...index === 0 ? { cache_control: { type: "ephemeral" } } : {}
+      }));
+    } else if (systemText) {
       body.system = systemText;
     }
     if (options.stop) {
       body.stop_sequences = options.stop;
     }
     if (options.tools && options.tools.length > 0) {
-      body.tools = options.tools.map((t) => this.mapToolDefinition(t));
+      const tools = options.tools.map((t) => this.mapToolDefinition(t));
+      if (promptCache && !anchorOnSystem) {
+        tools[tools.length - 1] = {
+          ...tools[tools.length - 1],
+          cache_control: { type: "ephemeral" }
+        };
+      }
+      body.tools = tools;
     }
     if (options.toolChoice !== void 0) {
       body.tool_choice = this.mapToolChoice(options.toolChoice);
@@ -3282,9 +3531,13 @@ var AnthropicProvider = class {
     }
     if (options.responseFormat && options.responseFormat.type !== "text") {
       const jsonInstruction = "You must respond with valid JSON only. No markdown fences, no extra text.";
-      body.system = body.system ? `${body.system}
+      if (Array.isArray(body.system)) {
+        body.system = [...body.system, { type: "text", text: jsonInstruction }];
+      } else {
+        body.system = body.system ? `${body.system}
 
 ${jsonInstruction}` : jsonInstruction;
+      }
     }
     if (options.providerOptions) {
       Object.assign(body, options.providerOptions);
@@ -3464,7 +3717,7 @@ ${jsonInstruction}` : jsonInstruction;
   // ---------------------------------------------------------------------------
   // Internal: SSE stream parsing
   // ---------------------------------------------------------------------------
-  async *parseSSEStream(body, pricingContext, responseHeaders) {
+  async *parseSSEStream(body, pricingContext, responseHeaders, timing) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
@@ -3493,7 +3746,7 @@ ${jsonInstruction}` : jsonInstruction;
     });
     try {
       while (true) {
-        const { done, value } = await reader.read();
+        const { done, value } = await timing.read(reader);
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");
@@ -3516,7 +3769,8 @@ ${jsonInstruction}` : jsonInstruction;
                 provider: this.name,
                 status,
                 headers: responseHeaders,
-                message: event.error?.message ?? "Anthropic stream failed"
+                message: event.error?.message ?? "Anthropic stream failed",
+                timing: timing.streamTiming()
               });
             }
             case "content_block_start": {
@@ -3752,7 +4006,6 @@ var GEMINI_PRICING = {
   },
   "gemini-2.5-flash": { input: 3e-7, cached: 3e-8, output: 25e-7 },
   "gemini-2.5-flash-lite": { input: 1e-7, cached: 1e-8, output: 4e-7 },
-  "gemini-3-flash-preview": { input: 5e-7, cached: 5e-8, output: 3e-6 },
   "gemini-3.1-pro-preview": {
     input: 2e-6,
     cached: 2e-7,
@@ -3768,7 +4021,9 @@ var GEMINI_PRICING = {
   "gemini-3.1-flash-lite": { input: 25e-8, cached: 25e-9, output: 15e-7 },
   "gemini-3.5-flash": { input: 15e-7, cached: 15e-8, output: 9e-6 },
   "gemini-3.5-flash-lite": { input: 3e-7, cached: 3e-8, output: 25e-7 },
-  "gemini-3.6-flash": { input: 15e-7, cached: 15e-8, output: 75e-7 }
+  "gemini-3.6-flash": { input: 75e-8, cached: 75e-9, output: 375e-8 },
+  "gemini-3.7-flash": { input: 75e-8, cached: 75e-9, output: 375e-8 },
+  "gemini-3.8-flash": { input: 75e-8, cached: 75e-9, output: 375e-8 }
 };
 function isValidTokenCount2(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -3928,13 +4183,71 @@ function budgetToThinkingLevel(budgetTokens) {
 function minThinkingLevel(model) {
   return GEMINI_3X_MIN_THINKING_LEVEL.get(model) ?? "minimal";
 }
-var _warned3xEffortNone = /* @__PURE__ */ new Set();
-function warnGemini3xEffortNone(model) {
-  if (_warned3xEffortNone.has(model)) return;
-  _warned3xEffortNone.add(model);
-  console.warn(
-    `[axl] effort: 'none' on Gemini 3.x (${model}) maps to the model's minimum thinking level ('${minThinkingLevel(model)}'), not fully disabled. Gemini 3.x models cannot disable thinking entirely.`
-  );
+function resolveGeminiThinking(model, resolved) {
+  const is3x = isGemini3x(model);
+  if (resolved.thinkingDisabled) {
+    const minLevel = minThinkingLevel(model);
+    if (is3x) {
+      return {
+        interactionLevel: minLevel,
+        thinkingLevel: minLevel,
+        thinkingBudget: void 0,
+        attachThoughts: false,
+        // A `thinkingBudget: 0` disable has no unified effort to report against;
+        // only an explicit `effort: 'none'` is a clamp of a requested value.
+        clamp: resolved.effort === "none" ? {
+          effective: minLevel,
+          cause: `Gemini 3.x models cannot disable thinking; using the model minimum thinking level '${minLevel}'`
+        } : void 0
+      };
+    }
+    return {
+      interactionLevel: "minimal",
+      thinkingLevel: void 0,
+      thinkingBudget: 0,
+      attachThoughts: false
+    };
+  }
+  if (resolved.hasBudgetOverride) {
+    const budget = resolved.thinkingBudget;
+    const level = budgetToThinkingLevel(budget);
+    return {
+      interactionLevel: level,
+      thinkingLevel: is3x ? level : void 0,
+      thinkingBudget: is3x ? void 0 : budget,
+      attachThoughts: resolved.includeThoughts
+    };
+  }
+  if (resolved.activeEffort) {
+    const effort = resolved.activeEffort;
+    const budget = THINKING_BUDGETS2[effort] ?? 5e3;
+    if (is3x) {
+      const level = THINKING_LEVELS[effort] ?? "medium";
+      return {
+        interactionLevel: level,
+        thinkingLevel: level,
+        thinkingBudget: void 0,
+        attachThoughts: resolved.includeThoughts,
+        clamp: level === effort ? void 0 : {
+          effective: level,
+          cause: `Gemini 3.x thinking levels cap at 'high'; effort '${effort}' maps to '${level}'`
+        }
+      };
+    }
+    return {
+      interactionLevel: budgetToThinkingLevel(budget),
+      thinkingLevel: void 0,
+      // 2.5 Pro supports a higher max budget (32768) than other 2.5 models (24576).
+      thinkingBudget: effort === "max" && model === "gemini-2.5-pro" ? 32768 : budget,
+      attachThoughts: resolved.includeThoughts
+    };
+  }
+  return {
+    interactionLevel: void 0,
+    thinkingLevel: void 0,
+    thinkingBudget: void 0,
+    attachThoughts: resolved.includeThoughts
+  };
 }
 var GeminiProvider = class {
   name = "google";
@@ -4003,6 +4316,21 @@ var GeminiProvider = class {
   nativeStructuredOutputSupport() {
     return "lossy";
   }
+  /** Report a clamped `effort` (R7a). Gemini 3.x cannot disable thinking and
+   *  caps at `'high'`, so `'none'`, `'xhigh'` and `'max'` are not honored
+   *  verbatim there. Everything else — including 2.x disabled thinking — is
+   *  sent as asked, so there is nothing to report. */
+  effortResolution(options) {
+    const resolved = resolveThinkingOptions(options);
+    if (resolved.effort === void 0) return void 0;
+    const clamp = resolveGeminiThinking(this.requestModel(options), resolved).clamp;
+    return clamp ? {
+      requested: resolved.effort,
+      effective: clamp.effective,
+      clamped: true,
+      cause: clamp.cause
+    } : void 0;
+  }
   baseUrl;
   apiKeySource;
   callCounter = 0;
@@ -4040,6 +4368,7 @@ var GeminiProvider = class {
     const pricingContext = this.pricingContext(this.requestModel(options), body);
     this.assertSafeGemini3Continuation(messages, pricingContext.model);
     const headers = this.buildHeaders(await this.resolveKey());
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/models/${pricingContext.model}:generateContent`,
       {
@@ -4048,7 +4377,7 @@ var GeminiProvider = class {
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -4058,11 +4387,12 @@ var GeminiProvider = class {
         status: res.status,
         headers: res.headers,
         message,
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     const json = await res.json();
-    return this.parseResponse(json, pricingContext);
+    return withChatTiming(recorder, this.parseResponse(json, pricingContext));
   }
   // ---------------------------------------------------------------------------
   // stream - SSE streaming completion
@@ -4076,6 +4406,7 @@ var GeminiProvider = class {
     const pricingContext = this.pricingContext(this.requestModel(options), body);
     this.assertSafeGemini3Continuation(messages, pricingContext.model);
     const headers = this.buildHeaders(await this.resolveKey());
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/models/${pricingContext.model}:streamGenerateContent?alt=sse`,
       {
@@ -4084,7 +4415,7 @@ var GeminiProvider = class {
         body: JSON.stringify(body),
         signal: options.signal
       },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -4094,13 +4425,14 @@ var GeminiProvider = class {
         status: res.status,
         headers: res.headers,
         message,
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     if (!res.body) {
       throw new Error("Gemini stream response has no body");
     }
-    yield* this.parseSSEStream(res.body, pricingContext);
+    yield* withCallTiming(recorder, this.parseSSEStream(res.body, pricingContext, recorder));
   }
   // ---------------------------------------------------------------------------
   // Rich image requests use Gemini Interactions. It is deliberately stateless:
@@ -4111,10 +4443,11 @@ var GeminiProvider = class {
     this.assertSafeInteractionOptions(options);
     const body = this.buildInteractionRequestBody(messages, options, false);
     const headers = this.buildHeaders(await this.resolveKey());
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/interactions`,
       { method: "POST", headers, body: JSON.stringify(body), signal: options.signal },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -4123,19 +4456,24 @@ var GeminiProvider = class {
         status: res.status,
         headers: res.headers,
         message: this.extractErrorMessage(errorBody, res.status),
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
-    return this.parseInteractionResponse(await res.json());
+    return withChatTiming(
+      recorder,
+      this.parseInteractionResponse(await res.json())
+    );
   }
   async *streamInteraction(messages, options) {
     this.assertSafeInteractionOptions(options);
     const body = this.buildInteractionRequestBody(messages, options, true);
     const headers = this.buildHeaders(await this.resolveKey());
+    const recorder = new CallTimingRecorder();
     const res = await fetchWithRetry(
       `${this.baseUrl}/interactions?alt=sse`,
       { method: "POST", headers, body: JSON.stringify(body), signal: options.signal },
-      { governor: this.governor, provider: this.name }
+      { governor: this.governor, provider: this.name, timing: recorder.observer }
     );
     if (!res.ok) {
       const errorBody = await res.text();
@@ -4144,11 +4482,15 @@ var GeminiProvider = class {
         status: res.status,
         headers: res.headers,
         message: this.extractErrorMessage(errorBody, res.status),
-        body: errorBody
+        body: errorBody,
+        timing: recorder.chatTiming()
       });
     }
     if (!res.body) throw new Error("Gemini Interactions stream has no body");
-    yield* this.parseInteractionSSEStream(res.body, res.headers);
+    yield* withCallTiming(
+      recorder,
+      this.parseInteractionSSEStream(res.body, res.headers, recorder)
+    );
   }
   buildInteractionRequestBody(messages, options, stream) {
     const model = this.requestModel(options);
@@ -4177,12 +4519,9 @@ var GeminiProvider = class {
       generationConfig.tool_choice = typeof options.toolChoice === "string" ? options.toolChoice === "required" ? "any" : options.toolChoice : { allowed_tools: { mode: "any", tools: [options.toolChoice.function.name] } };
     }
     const thinking = resolveThinkingOptions(options);
-    if (thinking.thinkingDisabled) {
-      generationConfig.thinking_level = isGemini3x(model) ? minThinkingLevel(model) : "minimal";
-    } else if (thinking.hasBudgetOverride) {
-      generationConfig.thinking_level = budgetToThinkingLevel(thinking.thinkingBudget);
-    } else if (thinking.activeEffort) {
-      generationConfig.thinking_level = isGemini3x(model) ? THINKING_LEVELS[thinking.activeEffort] ?? "medium" : budgetToThinkingLevel(THINKING_BUDGETS2[thinking.activeEffort] ?? 5e3);
+    const thinkingPlan = resolveGeminiThinking(model, thinking);
+    if (thinkingPlan.interactionLevel !== void 0) {
+      generationConfig.thinking_level = thinkingPlan.interactionLevel;
     }
     if (thinking.includeThoughts) generationConfig.thinking_summaries = "auto";
     if (Object.keys(generationConfig).length) body.generation_config = generationConfig;
@@ -4307,7 +4646,7 @@ var GeminiProvider = class {
       providerMetadata: json.steps?.length ? { geminiInteractionSteps: json.steps.filter(isGeminiInteractionStep) } : void 0
     };
   }
-  async *parseInteractionSSEStream(body, responseHeaders) {
+  async *parseInteractionSSEStream(body, responseHeaders, timing) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
@@ -4317,7 +4656,7 @@ var GeminiProvider = class {
     let completed = false;
     try {
       while (true) {
-        const { done, value } = await reader.read();
+        const { done, value } = await timing.read(reader);
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");
@@ -4340,14 +4679,16 @@ var GeminiProvider = class {
                 provider: this.name,
                 status,
                 headers: responseHeaders,
-                message
+                message,
+                timing: timing.streamTiming()
               });
             }
             throw new ProviderError({
               provider: this.name,
               status: 0,
               retryable: false,
-              message
+              message,
+              timing: timing.streamTiming()
             });
           }
           if (event.event_type === "step.start" && event.step) {
@@ -4618,50 +4959,17 @@ var GeminiProvider = class {
     if (Object.keys(generationConfig).length > 0) {
       body.generationConfig = generationConfig;
     }
-    const {
-      effort,
-      thinkingBudget,
-      includeThoughts,
-      thinkingDisabled,
-      activeEffort,
-      hasBudgetOverride
-    } = resolveThinkingOptions(options);
-    if (thinkingDisabled) {
-      if (isGemini3x(requestModel)) {
-        if (effort === "none") {
-          warnGemini3xEffortNone(requestModel);
-        }
-        generationConfig.thinkingConfig = { thinkingLevel: minThinkingLevel(requestModel) };
-      } else {
-        generationConfig.thinkingConfig = { thinkingBudget: 0 };
-      }
-      if (!body.generationConfig) body.generationConfig = generationConfig;
-    } else if (hasBudgetOverride) {
-      const config = {};
-      if (isGemini3x(requestModel)) {
-        config.thinkingLevel = budgetToThinkingLevel(thinkingBudget);
-      } else {
-        config.thinkingBudget = thinkingBudget;
-      }
-      if (includeThoughts) config.includeThoughts = true;
-      generationConfig.thinkingConfig = config;
-      if (!body.generationConfig) body.generationConfig = generationConfig;
-    } else if (activeEffort) {
-      const config = {};
-      if (isGemini3x(requestModel)) {
-        config.thinkingLevel = THINKING_LEVELS[activeEffort] ?? "medium";
-      } else {
-        if (activeEffort === "max" && requestModel === "gemini-2.5-pro") {
-          config.thinkingBudget = 32768;
-        } else {
-          config.thinkingBudget = THINKING_BUDGETS2[activeEffort] ?? 5e3;
-        }
-      }
-      if (includeThoughts) config.includeThoughts = true;
-      generationConfig.thinkingConfig = config;
-      if (!body.generationConfig) body.generationConfig = generationConfig;
-    } else if (includeThoughts) {
-      generationConfig.thinkingConfig = { includeThoughts: true };
+    const thinkingPlan = resolveGeminiThinking(requestModel, resolveThinkingOptions(options));
+    const thinkingConfig = {};
+    if (thinkingPlan.thinkingLevel !== void 0) {
+      thinkingConfig.thinkingLevel = thinkingPlan.thinkingLevel;
+    }
+    if (thinkingPlan.thinkingBudget !== void 0) {
+      thinkingConfig.thinkingBudget = thinkingPlan.thinkingBudget;
+    }
+    if (thinkingPlan.attachThoughts) thinkingConfig.includeThoughts = true;
+    if (Object.keys(thinkingConfig).length > 0) {
+      generationConfig.thinkingConfig = thinkingConfig;
       if (!body.generationConfig) body.generationConfig = generationConfig;
     }
     if (options.toolChoice !== void 0) {
@@ -4858,7 +5166,7 @@ var GeminiProvider = class {
   // ---------------------------------------------------------------------------
   // Internal: SSE stream parsing
   // ---------------------------------------------------------------------------
-  async *parseSSEStream(body, pricingContext) {
+  async *parseSSEStream(body, pricingContext, timing) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
@@ -4871,7 +5179,7 @@ var GeminiProvider = class {
     const accumulatedParts = [];
     try {
       while (true) {
-        const { done, value } = await reader.read();
+        const { done, value } = await timing.read(reader);
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");
@@ -7296,6 +7604,9 @@ var AXL_EVENT_TYPES = [
   // structured-output cliffs (oversized appended schema, dropped refinements,
   // streaming disabled, zero-guidance `schemaPrompt:'none'`).
   "schema_diagnostic",
+  // Provider capability diagnostics — the resolved provider could not honor a
+  // portable request knob verbatim (first kind: a clamped `effort`).
+  "provider_diagnostic",
   // Observability
   "log",
   "memory_remember",
@@ -7345,6 +7656,7 @@ var LIFECYCLE_TYPES = /* @__PURE__ */ new Set([
   "pipeline",
   "verify",
   "schema_diagnostic",
+  "provider_diagnostic",
   "workflow_start",
   "workflow_end",
   "transcription_start",
@@ -8273,6 +8585,10 @@ var LEGACY_REDACTION_RULES = {
   // 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,
+  // `provider_diagnostic` carries only provider capability metadata — a provider
+  // name, a model id, and two effort level strings. No application data or user
+  // content ever reaches it. Passthrough, as an explicit reviewed decision.
+  provider_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) };
@@ -8403,6 +8719,7 @@ var COMMON_V2_REDACTION_RULES = {
   string_delta: reuseLegacyRule("string_delta"),
   verify: reuseLegacyRule("verify"),
   schema_diagnostic: reuseLegacyRule("schema_diagnostic"),
+  provider_diagnostic: reuseLegacyRule("provider_diagnostic"),
   log: reuseLegacyRule("log"),
   memory_remember: reuseLegacyRule("memory_remember"),
   memory_recall: reuseLegacyRule("memory_recall"),
@@ -8498,13 +8815,14 @@ function detectDroppedRefinements(schema) {
 var DOCS_URL = "docs/observability.md#schema-diagnostics";
 var MAX_WARNED_KEYS = 2048;
 var warnedDiagnosticKeys = /* @__PURE__ */ new Set();
-function warnSchemaDiagnosticOnce(key, message, silent) {
+function warnDiagnosticOnce(key, message, silent, docs = DOCS_URL) {
   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}.`);
+  console.warn(`[axl] ${message} See ${docs}.`);
 }
+var warnSchemaDiagnosticOnce = warnDiagnosticOnce;
 
 // src/config.ts
 function defineConfig(config) {
@@ -9354,7 +9672,29 @@ function appendRetryMessages(messages, content, feedbackMessage, providerMetadat
     content,
     ...providerMetadata ? { providerMetadata } : {}
   });
-  messages.push({ role: "system", content: feedbackMessage });
+  messages.push({ role: "user", content: feedbackMessage });
+}
+function isRetryAbort(value) {
+  return typeof value === "object" && value !== null && value.retry === false;
+}
+function describeValue(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `an array of length ${value.length}`;
+  if (typeof value === "object") {
+    const keys = Object.keys(value);
+    return keys.length > 0 ? `an object with keys [${keys.join(", ")}]` : "an empty object";
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return `the ${typeof value} ${JSON.stringify(value)}`;
+  }
+  return `a value of type ${typeof value}`;
+}
+var PROMPT_CACHE_COLD_WRITE_WARN_AFTER = 2;
+function nextUserTurn(history, from) {
+  for (let i = Math.max(0, from); i < history.length; i++) {
+    if (history[i].role === "user") return i;
+  }
+  return void 0;
 }
 function estimateMessagesTokens(messages) {
   let total = 0;
@@ -9495,6 +9835,13 @@ var WorkflowContext = class _WorkflowContext {
   workflowLifecycleState;
   signal;
   summaryCache;
+  /** Consecutive provider calls with promptCache on that wrote to the cache
+   *  without reading from it (prefix changes per call), and consecutive calls
+   *  with no cache activity at all (prefix below the model's minimum, which
+   *  Anthropic silently ignores). Either reports once per context. */
+  promptCacheColdWrites = 0;
+  promptCacheInactive = 0;
+  promptCacheWarned = false;
   workflowName;
   mcpManager;
   spanManager;
@@ -10027,6 +10374,17 @@ var WorkflowContext = class _WorkflowContext {
                 const costAfter2 = this.budgetContext?.totalCost ?? 0;
                 span.setAttribute("axl.agent.cost", costAfter2 - costBefore);
                 span.setAttribute("axl.agent.duration", Date.now() - askStart);
+                if (usageCapture.timing) {
+                  const t = usageCapture.timing;
+                  span.setAttribute("axl.agent.queued_ms", t.queuedMs);
+                  span.setAttribute("axl.agent.retry_ms", t.retryMs);
+                  span.setAttribute("axl.agent.attempts", t.attempts);
+                  span.setAttribute("axl.agent.ttfb_ms", t.ttfbMs);
+                  span.setAttribute("axl.agent.wire_ms", t.wireMs);
+                  if (t.firstTokenMs !== void 0) {
+                    span.setAttribute("axl.agent.first_token_ms", t.firstTokenMs);
+                  }
+                }
                 if (usageCapture.value) {
                   span.setAttribute(
                     "axl.agent.prompt_tokens",
@@ -10234,6 +10592,14 @@ var WorkflowContext = class _WorkflowContext {
       const toolTokens = toolDefs.length > 0 ? estimateTokens(JSON.stringify(toolDefs)) : 0;
       const overhead = systemTokens + toolTokens + reserveTokens;
       const availableForHistory = maxContext - overhead;
+      if (availableForHistory <= 0) {
+        this.emitEvent({
+          type: "log",
+          data: {
+            warning: `Agent '${agent2._name}' maxContext (${maxContext}) is at or below its fixed overhead (${overhead} = system ${systemTokens} + tools ${toolTokens} + reserve ${reserveTokens}); no session history can fit, so every ask summarizes, retaining at most the most recent exchange and sometimes none of it verbatim. The current input is always sent. Raise maxContext or lower contextManagement.reserveTokens.`
+          }
+        });
+      }
       const historyEstimate = estimateMessagesTokens(sessionHistory);
       if (historyEstimate.unmeasured) {
         this.emitEvent({
@@ -10291,6 +10657,7 @@ ${appendedSchemaText}`;
       provider,
       model
     });
+    this.emitProviderDiagnostics(agent2, options, { provider, model, providerOptions });
     if (handoffMessages && handoffMessages.length > 0) {
       const handoffContext = handoffMessages.filter(
         (m) => m.role === "assistant" || m.role === "tool"
@@ -10298,6 +10665,7 @@ ${appendedSchemaText}`;
       if (handoffContext.length > 0) {
         messages.push({
           role: "system",
+          origin: "runtime",
           content: "The following is the conversation history from the previous agent that handed off to you:"
         });
         for (const msg of handoffContext) {
@@ -10347,6 +10715,7 @@ ${appendedSchemaText}`;
     const maxTurns = agent2._config.maxTurns ?? 25;
     const timeoutMs = parseDuration(agent2._config.timeout ?? "60s");
     const startTime = Date.now();
+    const timingTotals = { turns: 0, queuedMs: 0, retryMs: 0, wireMs: 0 };
     const currentMessages = [...messages];
     let turns = 0;
     let guardrailOutputRetries = 0;
@@ -10360,8 +10729,22 @@ ${appendedSchemaText}`;
     let lastStartMaxAttempts = 1;
     while (turns < maxTurns) {
       this.currentSignal?.throwIfAborted();
-      if (Date.now() - startTime > timeoutMs) {
-        throw new TimeoutError("ctx.ask()", timeoutMs);
+      const elapsedMs = Date.now() - startTime;
+      if (elapsedMs > timeoutMs) {
+        throw new TimeoutError(
+          "ctx.ask()",
+          timeoutMs,
+          timingTotals.turns > 0 ? {
+            elapsedMs,
+            queuedMs: timingTotals.queuedMs,
+            retryMs: timingTotals.retryMs,
+            wireMs: timingTotals.wireMs,
+            otherMs: Math.max(
+              0,
+              elapsedMs - timingTotals.queuedMs - timingTotals.retryMs - timingTotals.wireMs
+            )
+          } : void 0
+        );
       }
       turns++;
       const isFirstTurn = turns === 1;
@@ -10401,6 +10784,7 @@ ${appendedSchemaText}`;
         effort: options?.effort ?? agent2._config.effort,
         thinkingBudget: options?.thinkingBudget ?? agent2._config.thinkingBudget,
         includeThoughts: options?.includeThoughts ?? agent2._config.includeThoughts,
+        promptCache: options?.promptCache ?? agent2._config.promptCache,
         toolChoice: options?.toolChoice ?? agent2._config.toolChoice,
         stop: options?.stop ?? agent2._config.stop,
         providerOptions,
@@ -10478,6 +10862,7 @@ ${appendedSchemaText}`;
           const toolCalls = [];
           const toolCallBuffers = /* @__PURE__ */ new Map();
           let streamProviderMetadata;
+          let streamTiming;
           let thinkingContent = "";
           const streamingObjectEnabled = !!options?.schema && toolDefs.length === 0 && options.schema instanceof z.ZodObject;
           const currentAttempt = schemaRetries + 1;
@@ -10529,6 +10914,7 @@ ${appendedSchemaText}`;
               if (chunk.arguments) buffer.arguments += chunk.arguments;
             } else if (chunk.type === "done") {
               streamProviderMetadata = chunk.providerMetadata;
+              streamTiming = chunk.timing;
               if (chunk.usage) {
                 response = {
                   content: content2,
@@ -10556,6 +10942,9 @@ ${appendedSchemaText}`;
           if (streamProviderMetadata) {
             response.providerMetadata = streamProviderMetadata;
           }
+          if (streamTiming) {
+            response.timing = streamTiming;
+          }
           if (thinkingContent) {
             response.thinking_content = thinkingContent;
           }
@@ -10564,12 +10953,15 @@ ${appendedSchemaText}`;
         }
       } catch (err) {
         if (richRequest) this.recordRichFailure(err);
+        const failureTiming = err instanceof ProviderError ? err.timing : void 0;
         this.emitEvent({
           type: "agent_call_end",
           agent: agent2._name,
           model: effectiveModelUri,
           promptVersion: agent2._config.version,
           duration: Date.now() - turnStart,
+          // Top-level beside `duration`, exactly as on the success path.
+          ...failureTiming ? { timing: failureTiming } : {},
           data: {
             response: "",
             turn: turns,
@@ -10586,9 +10978,41 @@ ${appendedSchemaText}`;
       if (usageCapture && response.usage) {
         usageCapture.value = response.usage;
       }
+      if (usageCapture && response.timing) {
+        usageCapture.timing = response.timing;
+      }
+      if (chatOptions.promptCache && provider.realizesPromptCache?.(model) === true && response.usage && !this.promptCacheWarned) {
+        const wrote = (response.usage.cache_write_tokens ?? 0) > 0;
+        const read = (response.usage.cached_tokens ?? 0) > 0;
+        if (read) {
+          this.promptCacheColdWrites = 0;
+          this.promptCacheInactive = 0;
+        } else if (wrote) {
+          this.promptCacheColdWrites += 1;
+          this.promptCacheInactive = 0;
+        } else {
+          this.promptCacheInactive += 1;
+        }
+        let warning;
+        if (this.promptCacheColdWrites >= PROMPT_CACHE_COLD_WRITE_WARN_AFTER) {
+          warning = `Agent '${agent2._name}' has promptCache on, but its prefix was written to the cache ${this.promptCacheColdWrites} times in a row with no cache reads. Each write bills 1.25x input. If this agent's system prompt or tool set changes per call, set promptCache: false for it.`;
+        } else if (this.promptCacheInactive >= PROMPT_CACHE_COLD_WRITE_WARN_AFTER) {
+          warning = `Agent '${agent2._name}' has promptCache on, but ${this.promptCacheInactive} calls in a row showed no cache writes or reads. Anthropic silently ignores a breakpoint below the model's minimum cacheable length (4,096 tokens on Haiku 4.5; 1,024 or 512 on others) -- the system prompt plus tools may be too short to cache on this model, or the provider may not support prompt caching.`;
+        }
+        if (warning) {
+          this.promptCacheWarned = true;
+          this.emitEvent({ type: "log", agent: agent2._name, data: { warning } });
+        }
+      }
       if (response.cost) {
         this._accumulateBudgetCost(response.cost);
       }
+      if (response.timing) {
+        timingTotals.turns += 1;
+        timingTotals.queuedMs += response.timing.queuedMs;
+        timingTotals.retryMs += response.timing.retryMs;
+        timingTotals.wireMs += response.timing.wireMs;
+      }
       this.emitEvent({
         type: "agent_call_end",
         agent: agent2._name,
@@ -10603,6 +11027,8 @@ ${appendedSchemaText}`;
           cacheWrite: response.usage.cache_write_tokens
         } : void 0,
         duration: Date.now() - turnStart,
+        // Additive beside `duration`, which keeps its turn-wall-clock meaning.
+        ...response.timing ? { timing: response.timing } : {},
         data: {
           response: response.content,
           ...response.thinking_content ? { thinking: response.thinking_content } : {},
@@ -10655,7 +11081,11 @@ ${appendedSchemaText}`;
                 retries: options.retries,
                 metadata: options.metadata,
                 validate: options.validate,
-                validateRetries: options.validateRetries
+                validateRetries: options.validateRetries,
+                // This seam serves both callers of a handoff: a plain `ctx.ask()` on an
+                // agent with `handoffs`, and the routed `ctx.delegate()` path, whose
+                // terminal ask is the handoff target. The hook travels like `validate`.
+                retryFeedback: options.retryFeedback
               } : void 0;
               const handoffFn = () => askStorage.run(targetFrame, async () => {
                 const delegateOriginal = agent2._delegateOriginalInput;
@@ -10804,9 +11234,10 @@ ${appendedSchemaText}`;
         const attempt = guardrailOutputRetries + 1;
         const maxAttempts = maxGuardrailRetries + 1;
         const onBlock = guardrails.onBlock ?? "throw";
+        const blockReason = outputResult.reason ?? "Output blocked by guardrail";
         let feedbackMessage;
         if (outputResult.block && onBlock === "retry" && guardrailOutputRetries < maxGuardrailRetries) {
-          feedbackMessage = `Your previous response was blocked by a safety guardrail: ${outputResult.reason ?? "Output blocked"}. Please provide a different response that complies with the guidelines.`;
+          feedbackMessage = `Your previous response was blocked by a safety guardrail: ${blockReason}. Please provide a different response that complies with the guidelines.`;
         }
         this.emitEvent({
           type: "guardrail",
@@ -10829,31 +11260,43 @@ ${appendedSchemaText}`;
         });
         if (outputResult.block) {
           if (feedbackMessage) {
-            this.emitEvent({
-              type: "pipeline",
-              agent: agent2._name,
-              status: "failed",
+            const decision = await this.resolveRetryFeedback(options?.retryFeedback, {
               stage: "guardrail",
-              attempt: guardrailOutputRetries + 1,
-              maxAttempts: maxGuardrailRetries + 1,
-              reason: feedbackMessage
+              attempt,
+              maxAttempts,
+              output: content,
+              reason: blockReason,
+              defaultMessage: feedbackMessage
             });
-            guardrailOutputRetries++;
-            appendRetryMessages(
-              currentMessages,
-              content,
-              feedbackMessage,
-              response.providerMetadata
-            );
-            pendingRetryReason = "guardrail";
-            continue;
+            if (decision.retry) {
+              this.emitEvent({
+                type: "pipeline",
+                agent: agent2._name,
+                status: "failed",
+                stage: "guardrail",
+                attempt,
+                maxAttempts,
+                reason: decision.message
+              });
+              guardrailOutputRetries++;
+              appendRetryMessages(
+                currentMessages,
+                content,
+                decision.message,
+                response.providerMetadata
+              );
+              pendingRetryReason = "guardrail";
+              continue;
+            }
+            this.currentSignal?.throwIfAborted();
+            throw new GuardrailError("output", blockReason);
           }
           if (typeof onBlock === "function") {
-            return onBlock(outputResult.reason ?? "Output blocked by guardrail", {
+            return onBlock(blockReason, {
               metadata: this.metadata
             });
           }
-          throw new GuardrailError("output", outputResult.reason ?? "Output blocked by guardrail");
+          throw new GuardrailError("output", blockReason);
         }
       }
       let validated = void 0;
@@ -10873,7 +11316,7 @@ ${appendedSchemaText}`;
           schemaErr = err;
           schemaReason = err instanceof Error ? err.message : String(err);
           if (schemaRetries < maxSchemaRetries) {
-            schemaFeedback = `Your response was not valid JSON or did not match the required schema: ${schemaReason}. Please fix and try again.`;
+            schemaFeedback = `Your response was not valid JSON or did not match the required schema: ${schemaReason}. Return a corrected response that matches the required schema.`;
           }
         }
         this.emitEvent({
@@ -10895,24 +11338,36 @@ ${appendedSchemaText}`;
         });
         if (!schemaValid) {
           if (schemaFeedback) {
-            this.emitEvent({
-              type: "pipeline",
-              agent: agent2._name,
-              status: "failed",
+            const decision = await this.resolveRetryFeedback(options.retryFeedback, {
               stage: "schema",
-              attempt: schemaRetries + 1,
-              maxAttempts: (options.retries ?? 3) + 1,
-              reason: schemaFeedback
+              attempt: schemaAttempt,
+              maxAttempts: schemaMaxAttempts,
+              output: content,
+              reason: schemaReason ?? "Schema parse failed",
+              ...schemaErr !== void 0 ? { error: schemaErr } : {},
+              defaultMessage: schemaFeedback
             });
-            schemaRetries++;
-            appendRetryMessages(
-              currentMessages,
-              content,
-              schemaFeedback,
-              response.providerMetadata
-            );
-            pendingRetryReason = "schema";
-            continue;
+            if (decision.retry) {
+              this.emitEvent({
+                type: "pipeline",
+                agent: agent2._name,
+                status: "failed",
+                stage: "schema",
+                attempt: schemaAttempt,
+                maxAttempts: schemaMaxAttempts,
+                reason: decision.message
+              });
+              schemaRetries++;
+              appendRetryMessages(
+                currentMessages,
+                content,
+                decision.message,
+                response.providerMetadata
+              );
+              pendingRetryReason = "schema";
+              continue;
+            }
+            this.currentSignal?.throwIfAborted();
           }
           const zodErr = schemaErr instanceof ZodError2 ? schemaErr : new ZodError2([
             {
@@ -10926,12 +11381,14 @@ ${appendedSchemaText}`;
       }
       if (options?.schema && options.validate) {
         let validateResult;
+        let validateErr;
         try {
           validateResult = await options.validate(validated, {
             metadata: this.metadata
           });
         } catch (err) {
           rethrowEventStreamOverflow(err);
+          validateErr = err;
           const reason = err instanceof Error ? err.message : String(err);
           validateResult = { valid: false, reason: `Validator error: ${reason}` };
         }
@@ -10940,7 +11397,7 @@ ${appendedSchemaText}`;
         const validateMaxAttempts = maxValidateRetries + 1;
         let validateFeedback;
         if (!validateResult.valid && validateRetries < maxValidateRetries) {
-          validateFeedback = `Your response parsed correctly but failed validation: ${validateResult.reason ?? "Validation failed"}. Previous attempts are visible above. Please fix and try again.`;
+          validateFeedback = `Your previous response failed validation: ${validateResult.reason ?? "Validation failed"}. Return a corrected response that satisfies the required schema and this rule.`;
         }
         this.emitEvent({
           type: "validate",
@@ -10961,24 +11418,37 @@ ${appendedSchemaText}`;
         });
         if (!validateResult.valid) {
           if (validateFeedback) {
-            this.emitEvent({
-              type: "pipeline",
-              agent: agent2._name,
-              status: "failed",
+            const decision = await this.resolveRetryFeedback(options.retryFeedback, {
               stage: "validate",
-              attempt: validateRetries + 1,
-              maxAttempts: (options.validateRetries ?? 2) + 1,
-              reason: validateFeedback
+              attempt: validateAttempt,
+              maxAttempts: validateMaxAttempts,
+              output: content,
+              parsed: validated,
+              reason: validateResult.reason ?? "Validation failed",
+              ...validateErr !== void 0 ? { error: validateErr } : {},
+              defaultMessage: validateFeedback
             });
-            validateRetries++;
-            appendRetryMessages(
-              currentMessages,
-              content,
-              validateFeedback,
-              response.providerMetadata
-            );
-            pendingRetryReason = "validate";
-            continue;
+            if (decision.retry) {
+              this.emitEvent({
+                type: "pipeline",
+                agent: agent2._name,
+                status: "failed",
+                stage: "validate",
+                attempt: validateAttempt,
+                maxAttempts: validateMaxAttempts,
+                reason: decision.message
+              });
+              validateRetries++;
+              appendRetryMessages(
+                currentMessages,
+                content,
+                decision.message,
+                response.providerMetadata
+              );
+              pendingRetryReason = "validate";
+              continue;
+            }
+            this.currentSignal?.throwIfAborted();
           }
           throw new ValidationError(
             validated,
@@ -11000,6 +11470,31 @@ ${appendedSchemaText}`;
     }
     throw new MaxTurnsError("ctx.ask()", maxTurns);
   }
+  /**
+   * Resolve the corrective feedback text for one rejected attempt, giving an optional
+   * caller-supplied `retryFeedback` hook the chance to replace it or to stop retrying.
+   *
+   * Called by all three output gates, only while a retry is still permitted (never on the
+   * exhausting attempt) and only after the gate's own event has been emitted, so a hook that
+   * throws or aborts can never erase the evidence that the gate rejected. A non-empty string
+   * replaces `defaultMessage` verbatim; `undefined` / `''` keeps it; `{ retry: false }` asks
+   * the gate to throw its typed terminal error. Hook exceptions propagate — a bug in caller
+   * code is not a model failure and must not be retried into silence, and neither is a
+   * return value outside the contract: an unrecognized shape throws instead of silently
+   * degrading to the default text, which would hide the defect behind extra token spend.
+   */
+  async resolveRetryFeedback(hook, info) {
+    if (!hook) return { retry: true, message: info.defaultMessage };
+    const result = await hook(info, { metadata: this.metadata });
+    if (result === void 0 || result === "") {
+      return { retry: true, message: info.defaultMessage };
+    }
+    if (typeof result === "string") return { retry: true, message: result };
+    if (isRetryAbort(result)) return { retry: false };
+    throw new TypeError(
+      `retryFeedback must return a string, undefined, or { retry: false }; received ${describeValue(result)}.`
+    );
+  }
   /**
    * Push the final assistant message into session history, preserving providerMetadata
    * (e.g., Gemini thought signatures needed for multi-turn reasoning context) and
@@ -11155,6 +11650,57 @@ ${appendedSchemaText}`;
       }
     }
   }
+  /**
+   * Emit a `provider_diagnostic` when the resolved provider reports that it
+   * could not honor the unified `effort` verbatim (P3/R6/R7).
+   *
+   * The adapter only *resolves* — it returns the requested and effective levels
+   * from the same pure resolver its request builder uses. The runtime decides
+   * how to surface that, because only the runtime can see the event bus and
+   * `AxlConfig.diagnostics.silent` (adapters receive `ProviderConfig` only).
+   *
+   * Called once per ask, so a tool loop with N provider round trips still emits
+   * one event; the `console.warn` dedupes once per process per distinct clamp.
+   * A throwing `effortResolution` is a provider bug and propagates.
+   */
+  emitProviderDiagnostics(agent2, options, ctx) {
+    if (!ctx.provider.effortResolution) return;
+    const resolution = ctx.provider.effortResolution({
+      model: ctx.model,
+      effort: options?.effort ?? agent2._config.effort,
+      thinkingBudget: options?.thinkingBudget ?? agent2._config.thinkingBudget,
+      includeThoughts: options?.includeThoughts ?? agent2._config.includeThoughts,
+      providerOptions: ctx.providerOptions
+    });
+    if (!resolution?.clamped) return;
+    if (typeof resolution.effective !== "string" || resolution.effective.length === 0 || typeof resolution.requested !== "string" || resolution.requested.length === 0) {
+      throw new TypeError(
+        `Provider '${ctx.provider.name ?? "unknown"}' returned a malformed EffortResolution for model '${ctx.model}': 'requested' and 'effective' must be non-empty strings when 'clamped' is true. Received ${JSON.stringify(resolution)}.`
+      );
+    }
+    const cause = resolution.cause ?? `effort '${resolution.requested}' is not supported as asked`;
+    this.emitEvent({
+      type: "provider_diagnostic",
+      agent: agent2._name,
+      data: {
+        kind: "effort_clamped",
+        ...ctx.provider.name ? { provider: ctx.provider.name } : {},
+        model: ctx.model,
+        requested: resolution.requested,
+        effective: resolution.effective,
+        cause
+      }
+    });
+    warnDiagnosticOnce(
+      // One warning per distinct clamp, not per ask: the same clamp across 500
+      // asks is one process-level surprise, while a different requested/effective
+      // pair is a genuinely new one.
+      `effort_clamped\0${ctx.provider.name ?? ""}\0${ctx.model}\0${resolution.requested}\0${resolution.effective}`,
+      `effort '${resolution.requested}' was clamped to '${resolution.effective}' on ${ctx.provider.name ? `${ctx.provider.name} ` : ""}${ctx.model} \u2014 ${cause}. A 'provider_diagnostic' event carries the same detail per ask.`,
+      this.config.diagnostics?.silent,
+      "docs/observability.md#provider-diagnostics"
+    );
+  }
   buildToolDefs(agent2, resolvedHandoffs) {
     const defs = [];
     if (agent2._config.tools) {
@@ -11201,6 +11747,7 @@ ${appendedSchemaText}`;
     if (this.summaryCache) {
       const summaryMsg2 = {
         role: "system",
+        origin: "runtime",
         content: `Summary of earlier conversation:
 ${this.summaryCache}`
       };
@@ -11214,6 +11761,7 @@ ${this.summaryCache}`
         recentTokens2 += msgTokens;
         splitIdx2 = i;
       }
+      splitIdx2 = nextUserTurn(history, splitIdx2) ?? history.length;
       if (splitIdx2 < history.length) {
         return [summaryMsg2, ...history.slice(splitIdx2)];
       }
@@ -11227,6 +11775,19 @@ ${this.summaryCache}`
       recentTokens += msgTokens;
       splitIdx = i;
     }
+    const anchored = nextUserTurn(history, splitIdx);
+    if (anchored !== void 0) {
+      splitIdx = anchored;
+    } else if (splitIdx === history.length && history.length > 1) {
+      for (let i = history.length - 1; i > 0; i--) {
+        if (history[i].role === "user") {
+          splitIdx = i;
+          break;
+        }
+      }
+    } else {
+      splitIdx = history.length;
+    }
     if (splitIdx === 0) return history;
     const oldMessages = history.slice(0, splitIdx);
     const summaryModelUri = this.config.contextManagement?.summaryModel;
@@ -11258,6 +11819,7 @@ ${this.summaryCache}`
     }
     const summaryMsg = {
       role: "system",
+      origin: "runtime",
       content: `Summary of earlier conversation:
 ${summaryResponse.content}`
     };
@@ -12435,7 +12997,8 @@ ${summaryResponse.content}`
         retries: options?.retries,
         metadata: options?.metadata,
         validate: options?.validate,
-        validateRetries: options?.validateRetries
+        validateRetries: options?.validateRetries,
+        retryFeedback: options?.retryFeedback
       });
     }
     const resolveCtx = options?.metadata ? { metadata: { ...this.metadata, ...options.metadata } } : { metadata: this.metadata };
@@ -12483,7 +13046,8 @@ ${summaryResponse.content}`
       retries: options?.retries,
       metadata: options?.metadata,
       validate: options?.validate,
-      validateRetries: options?.validateRetries
+      validateRetries: options?.validateRetries,
+      retryFeedback: options?.retryFeedback
     });
   }
   /** Transcribe recorded audio through the dedicated transcription registry.
@@ -16031,6 +16595,8 @@ var AxlRuntime = class extends EventEmitter2 {
       parent: parentScope
     };
     const modelCalls = /* @__PURE__ */ new Map();
+    const modelTiming = /* @__PURE__ */ new Map();
+    const captureTimingSamples = options?.captureTimingSamples === true;
     const workflowCalls = /* @__PURE__ */ new Map();
     const tokens = { input: 0, output: 0, reasoning: 0 };
     let agentCalls = 0;
@@ -16048,6 +16614,30 @@ var AxlRuntime = class extends EventEmitter2 {
           tokens.output += event.tokens.output ?? 0;
           tokens.reasoning += event.tokens.reasoning ?? 0;
         }
+        const failed2 = event.data?.error != null;
+        if (event.model && event.timing && !failed2) {
+          const t = event.timing;
+          let bucket = modelTiming.get(event.model);
+          if (!bucket) {
+            bucket = {
+              calls: 0,
+              queuedMs: 0,
+              retryMs: 0,
+              wireMs: 0,
+              ...captureTimingSamples ? { samples: [] } : {}
+            };
+            modelTiming.set(event.model, bucket);
+          }
+          bucket.calls++;
+          bucket.samples?.push(t);
+          bucket.queuedMs += t.queuedMs;
+          bucket.retryMs += t.retryMs;
+          bucket.wireMs += t.wireMs;
+          if (t.firstTokenMs != null) {
+            bucket.firstTokenMs = (bucket.firstTokenMs ?? 0) + t.firstTokenMs;
+            bucket.firstTokenCalls = (bucket.firstTokenCalls ?? 0) + 1;
+          }
+        }
       }
       if (event.type === "workflow_start" && event.workflow) {
         workflowCalls.set(event.workflow, (workflowCalls.get(event.workflow) ?? 0) + 1);
@@ -16078,6 +16668,7 @@ var AxlRuntime = class extends EventEmitter2 {
         result,
         cost: scope.totalCost,
         unpriced,
+        ...modelTiming.size > 0 ? { modelTiming: Object.fromEntries(modelTiming) } : {},
         ...capturedTraces ? { traces: capturedTraces } : {},
         metadata: {
           models: [...modelCalls.keys()],