@axlsdk/axl 0.22.3 → 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
   },
@@ -2296,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`,
       {
@@ -2304,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();
@@ -2314,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
@@ -2326,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`,
       {
@@ -2334,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();
@@ -2344,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
@@ -2552,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 = "";
@@ -2560,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");
@@ -2580,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;
@@ -2594,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 ?? "" };
@@ -2650,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:
@@ -2718,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"],
@@ -2808,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 },
@@ -2850,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;
   }
@@ -2869,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,
@@ -3111,6 +3280,14 @@ var AnthropicProvider = class {
     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;
@@ -3166,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";
   }
@@ -3207,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`,
       {
@@ -3215,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();
@@ -3225,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
@@ -3241,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`,
       {
@@ -3249,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();
@@ -3259,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
@@ -3300,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);
@@ -3326,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);
@@ -3508,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 = "";
@@ -3537,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");
@@ -3560,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": {
@@ -3796,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,
@@ -3812,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;
@@ -4157,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`,
       {
@@ -4165,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();
@@ -4175,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
@@ -4193,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`,
       {
@@ -4201,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();
@@ -4211,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:
@@ -4228,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();
@@ -4240,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();
@@ -4261,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);
@@ -4421,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 = "";
@@ -4431,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");
@@ -4454,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) {
@@ -4939,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 = "";
@@ -4952,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");
@@ -9462,6 +9689,13 @@ function describeValue(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;
   let unmeasured = false;
@@ -9601,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;
@@ -10133,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",
@@ -10340,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({
@@ -10405,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) {
@@ -10454,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;
@@ -10467,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;
@@ -10508,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,
@@ -10585,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;
@@ -10636,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,
@@ -10663,6 +10942,9 @@ ${appendedSchemaText}`;
           if (streamProviderMetadata) {
             response.providerMetadata = streamProviderMetadata;
           }
+          if (streamTiming) {
+            response.timing = streamTiming;
+          }
           if (thinkingContent) {
             response.thinking_content = thinkingContent;
           }
@@ -10671,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,
@@ -10693,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,
@@ -10710,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 } : {},
@@ -11428,6 +11747,7 @@ ${appendedSchemaText}`;
     if (this.summaryCache) {
       const summaryMsg2 = {
         role: "system",
+        origin: "runtime",
         content: `Summary of earlier conversation:
 ${this.summaryCache}`
       };
@@ -11441,6 +11761,7 @@ ${this.summaryCache}`
         recentTokens2 += msgTokens;
         splitIdx2 = i;
       }
+      splitIdx2 = nextUserTurn(history, splitIdx2) ?? history.length;
       if (splitIdx2 < history.length) {
         return [summaryMsg2, ...history.slice(splitIdx2)];
       }
@@ -11454,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;
@@ -11485,6 +11819,7 @@ ${this.summaryCache}`
     }
     const summaryMsg = {
       role: "system",
+      origin: "runtime",
       content: `Summary of earlier conversation:
 ${summaryResponse.content}`
     };
@@ -16260,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;
@@ -16277,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);
@@ -16307,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()],