Account for additive cache counts in the total_tokens guard

CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to this project will be documented here. Format follows [Kee
 
 ### Fixed
 
+- **A cached token on an OpenAI-compatible endpoint with additive cache semantics was billed twice, the second time at the output rate.** The `total_tokens` consistency guard folds any positive `total_tokens - (input + output + reasoning)` remainder into `output`, on the premise — verified at the time across all three surfaces this adapter served — that cache counts always sit INSIDE `prompt_tokens`, so they can never appear in that remainder. Snowflake Cortex breaks the premise: it answers on an OpenAI **wire** (`/api/v2/cortex/v1/chat/completions`) with Anthropic's **additive** convention. Measured live against the real endpoint on 2026-08-25: `prompt_tokens: 7`, `prompt_tokens_details.cached_tokens: 4805`, `completion_tokens: 6`, `total_tokens: 4818` — the cached block sits outside `prompt_tokens` and inside `total_tokens`. The adapter therefore read 4,805 tokens as unaccounted and folded them into `output`, reporting **4,811 output tokens for a call that generated 6**, while the same 4,805 also shipped as `cache_read`: 17,503 tokens billed for 8,758 consumed on the original capture (**2.0x**), with the output line inflated ~800x. The reconciliation now subtracts `cache_read` and the raw `prompt_tokens_details.cache_write_tokens` as well.
+  - **`cache_write_tokens` is accounted for without being mapped.** It is deliberately absent from `CanonicalUsage.cache_write` — for OpenAI it sits inside `prompt_tokens` and billing it separately over-charges 2.24x — so it has no canonical route into the arithmetic and is read straight off the payload instead. Without that, an additive cache *write* inflates `output` exactly the way the read did.
+  - **The correction cannot suppress a genuine fold.** On a subtractive surface the cache counts are already inside `input`, so removing them again only drives the delta further negative, where the existing `> 0` guard already no-ops. Re-verified across every captured OpenAI, Databricks and Cloudflare fixture — all still 0 — and a payload carrying both an additive cache block and hidden thinking tokens still folds the thinking remainder alone.
+  - **Reported in review and answered "unreachable" — correctly, at the time.** PR #14 (2026-08-17) raised that `reasoning` was not a priori the only field able to inflate `total_tokens`, and named the exact payload shape. The answer was a three-surface census returning `unaccounted = 0` everywhere, which held until an OpenAI-compatible surface with additive caching existed. The regression fixtures are captured from that surface (`11_snowflake_cortex_plain_chat.json`, `12_snowflake_cortex_cache_chat.json`, via `capture_snowflake_cortex.py`) so the census is now pinned by a live payload rather than by an argument.
 - **An explicitly-passed falsy `api_url` silently resolved to PRODUCTION Lago.** Preferring the config value over `""` is right — `requests` raises `MissingSchema`, which is not a `LagoApiError`, so the queue classified it transient, re-prepended the batch and retried at the 60s ceiling forever, stopping all billing with only a growing buffer as the symptom. But `LagoConfig`'s default is the production URL, so `api_url=os.environ.get("LAGO_API_URL", "")` with the var unset resolved to production with **no `on_error` and no log** — verified live: 0 reports, 0 log lines, and a client posting to `api.getlago.com`. For a CI job or a developer holding a real production key that writes live billing data, and ingested events cannot be un-ingested. The fallback is unchanged, so the original config-clobber bug stays fixed; it is now reported under `config.api_url` through the same log-plus-callback floor as every other drop path. An *unpassed* `api_url` stays silent — `None` means the caller never mentioned it, and reporting the common case would train customers to ignore the channel this fix depends on.
 - **`usage_metadata` from the Cloudflare gateway got no drift sweep, and had already lost two counters.** `extras` was a fixed three-key dict, so any counter the adapter does not map vanished with no error and no `on_error` — the one place violating the drift contract `test_drift.py` enforces for the native adapters. Not hypothetical: replaying the **14 captured fixtures** through the adapter drops **`neurons`** (Cloudflare's Workers AI billing unit) in 4 entries and **`input_text_tokens`** in 1, and a live Logs API pull also returns **`units`**, a cost quantity that appears in no fixture at all — the hand-maintained key enumeration in the module docstring had already drifted past reality, which is exactly the failure mode a snapshot invites. Unmapped keys are now swept into `extras["usage_metadata"]` against an explicit `_MAPPED_USAGE_KEYS` set, so a ninth spelling surfaces on its own instead of needing another 14-fixture audit. Deliberately **nested** rather than merged flat into `extras`: the poller reads `extras["cached"]` to decide whether to skip billing a request Cloudflare served for free, so a future `usage_metadata` key called `cached` or `step` must not be able to shadow it. The regression test iterates the fixture directory rather than a fixed key list, so a recapture that introduces a new counter fails it with no test edit. Closes #16.
 - **`prime()` re-downloaded the ~400-model OpenRouter catalogue regardless of the TTL.** It set `_openrouter_stale` unconditionally, and it is reached from `_auto_prime_pricing_for` on a matching `wrap()` and from `warm_pricing()` — both of which a server can run per request — so `pricing_ttl_seconds` never applied on that path at all, and the catalogue was refetched on essentially every flush tick, on the thread the queue drains events from. Measured with the shipped 1-hour TTL: **4 `prime()`+`maybe_refresh()` cycles produced 4 full downloads where 1 was correct; now 1.** Gated on the same "no table, or past the TTL" test `lookup()` already uses, so priming and looking up cannot disagree about what needs fetching — and a table that genuinely ages out is still re-primed, so prices do not freeze at the first fetch.

src/lago_agent_sdk/adapters/openai_native.py

@@ -254,10 +254,36 @@ def extract_openai_native(response: Any, model_id: str = "", provider_hint: str
     # breakdown at all (measured: prompt 57, completion 47, total 1253) — still
     # recovers its 1,149 tokens, because reasoning is 0 there.
     #
+    # The cache counts are subtracted for the SAME reason as reasoning, and this was
+    # the half that was missing. The guard assumed every OpenAI-shaped surface reports
+    # cache_read INSIDE prompt_tokens, which held for all three surfaces that existed
+    # when it was written (native OpenAI: zero deltas; Databricks: 112/112 rows with
+    # total == input + output; Cloudflare: cache outside `input` but outside `total`
+    # too, so it never inflated the delta). Snowflake Cortex is the surface that broke
+    # it — an OpenAI-WIRE endpoint with Anthropic's ADDITIVE convention: measured
+    # 2026-08-25, prompt_tokens=7, cached_tokens=4805, completion_tokens=6,
+    # total_tokens=4818, i.e. the cached block sits OUTSIDE prompt_tokens and INSIDE
+    # total_tokens. Accounting for only input+output+reasoning made those 4,805 cached
+    # tokens look unaccounted, so they were folded into `output` — 4,811 reported for a
+    # call that generated 6, while the same tokens also shipped as cache_read. 2.0x on
+    # the call, 800x on the output line. See 12_snowflake_cortex_cache_chat.json.
+    #
+    # `cache_write_tokens` is read straight from the payload rather than from a
+    # canonical field because it is deliberately NOT mapped to CanonicalUsage.cache_write
+    # (for OpenAI it sits inside prompt_tokens and billing it separately over-charges
+    # 2.24x — see _MAPPED_DETAIL_FIELDS). It still has to be accounted for here, or an
+    # additive cache WRITE would inflate `output` exactly the way the read did.
+    #
+    # Subtracting them cannot suppress a genuine fold on a subtractive surface: there
+    # the cache counts are already inside `input`, so removing them again only drives
+    # the delta further negative, where the `> 0` guard already no-ops. Verified against
+    # every captured OpenAI, Databricks and Cloudflare fixture — all still 0.
+    #
     # A no-op for real OpenAI either way: total always equals prompt + completion.
     declared_total = _safe_int(usage.get("total_tokens"))
     if declared_total:
-        unaccounted = declared_total - (input_tokens + output_tokens + reasoning)
+        cache_write = _safe_int(_safe_dict(usage.get("prompt_tokens_details")).get("cache_write_tokens"))
+        unaccounted = declared_total - (input_tokens + output_tokens + reasoning + cache_read + cache_write)
         if unaccounted > 0:
             output_tokens += unaccounted
             extras["unaccounted_output_tokens"] = unaccounted

tests/unit/adapters/fixtures/capture_snowflake_cortex.py

@@ -0,0 +1,124 @@
+"""Capture Snowflake Cortex responses off the OpenAI-compatible endpoint.
+
+Saves to:
+  tests/unit/adapters/fixtures/openai_native/11_snowflake_cortex_plain_chat.json
+  tests/unit/adapters/fixtures/openai_native/12_snowflake_cortex_cache_chat.json
+
+These live under `openai_native/` on purpose: Cortex answers on an OpenAI-wire
+endpoint, so `extract_openai_native` / `extractOpenAINative` is the adapter that
+serves them. They are the surface that proves the `total_tokens` reconciliation
+cannot assume OpenAI's subtractive cache convention — on Cortex, `cached_tokens`
+sits OUTSIDE `prompt_tokens` and INSIDE `total_tokens`.
+
+Two things about Cortex that this script encodes, both measured 2026-08-25:
+
+  * Caching only happens with an explicit Anthropic-style `cache_control` part.
+    The same 4,800-token prompt sent twice WITHOUT it reports `cached_tokens: 0`
+    both times, so the "call1 then call2" pattern the OpenAI cache fixtures use
+    captures nothing here.
+  * `max_tokens` is rejected outright ("deprecated in favor of
+    max_completion_tokens"), unlike OpenAI which still accepts it.
+
+Requires a Snowflake account with the Cortex REST endpoint entitled — it returns
+403 `003001` otherwise, which is an account-level grant no config can work around.
+
+  SNOWFLAKE_HOST=<org>-<account>.snowflakecomputing.com \
+  SNOWFLAKE_PAT=<programmatic access token> \
+  python3 capture_snowflake_cortex.py
+
+Idempotent: skips files that already exist. Re-run after deleting one to refresh it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import sys
+
+import requests
+
+MODEL = "claude-sonnet-4-5"
+OUT = pathlib.Path(__file__).parent / "openai_native"
+
+# Long enough to clear Anthropic's minimum cacheable prefix. Deliberately dull,
+# fixed text: the fixture must not carry anything account- or person-identifying.
+CACHEABLE_PREFIX = "Reference notes on widget calibration tolerances, revision seven. " * 400
+
+
+def call(host: str, pat: str, body: dict) -> dict:
+    r = requests.post(
+        f"https://{host}/api/v2/cortex/v1/chat/completions",
+        headers={
+            "Authorization": f"Bearer {pat}",
+            "X-Snowflake-Authorization-Token-Type": "PROGRAMMATIC_ACCESS_TOKEN",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+        json=body,
+        timeout=120,
+    )
+    if r.status_code != 200:
+        sys.exit(f"Cortex returned {r.status_code}: {r.text[:300]}")
+    return r.json()
+
+
+def save(name: str, response: dict) -> None:
+    path = OUT / name
+    if path.exists():
+        print(f"skip {name} (exists)")
+        return
+    path.write_text(json.dumps({"_model_id": MODEL, "_response": response}, indent=2) + "\n")
+    print(f"wrote {name}")
+
+
+def main() -> None:
+    host = os.environ.get("SNOWFLAKE_HOST")
+    pat = os.environ.get("SNOWFLAKE_PAT")
+    if not host or not pat:
+        sys.exit("set SNOWFLAKE_HOST and SNOWFLAKE_PAT")
+
+    save(
+        "11_snowflake_cortex_plain_chat.json",
+        call(
+            host,
+            pat,
+            {
+                "model": MODEL,
+                "messages": [{"role": "user", "content": "What is 2 + 2? Answer in one word."}],
+                "max_completion_tokens": 32,
+            },
+        ),
+    )
+
+    # The regression fixture. `cache_control` is what makes Cortex report a cached
+    # block at all, and the resulting payload is the one that used to inflate
+    # `output` by the whole cached count.
+    save(
+        "12_snowflake_cortex_cache_chat.json",
+        call(
+            host,
+            pat,
+            {
+                "model": MODEL,
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": CACHEABLE_PREFIX,
+                                "cache_control": {"type": "ephemeral"},
+                            },
+                            {"type": "text", "text": "Reply with one word."},
+                        ],
+                    }
+                ],
+                "max_completion_tokens": 32,
+            },
+        ),
+    )
+
+
+if __name__ == "__main__":
+    main()

tests/unit/adapters/fixtures/openai_native/11_snowflake_cortex_plain_chat.json

@@ -0,0 +1,50 @@
+{
+  "_model_id": "claude-sonnet-4-5",
+  "_response": {
+    "choices": [
+      {
+        "finish_reason": "",
+        "index": 0,
+        "message": {
+          "annotations": null,
+          "audio": {
+            "data": "",
+            "expires_at": 0,
+            "id": "",
+            "transcript": ""
+          },
+          "content": "Four",
+          "function_call": {
+            "arguments": "",
+            "name": ""
+          },
+          "refusal": "",
+          "role": "assistant",
+          "tool_calls": null
+        }
+      }
+    ],
+    "created": 1787679484,
+    "id": "",
+    "model": "claude-sonnet-4-5",
+    "object": "chat.completion",
+    "service_tier": "",
+    "system_fingerprint": "",
+    "usage": {
+      "completion_tokens": 4,
+      "completion_tokens_details": {
+        "accepted_prediction_tokens": 0,
+        "audio_tokens": 0,
+        "reasoning_tokens": 0,
+        "rejected_prediction_tokens": 0
+      },
+      "prompt_tokens": 21,
+      "prompt_tokens_details": {
+        "audio_tokens": 0,
+        "cache_write_tokens": 0,
+        "cached_tokens": 0
+      },
+      "total_tokens": 25
+    }
+  }
+}

tests/unit/adapters/fixtures/openai_native/12_snowflake_cortex_cache_chat.json

@@ -0,0 +1,50 @@
+{
+  "_model_id": "claude-sonnet-4-5",
+  "_response": {
+    "choices": [
+      {
+        "finish_reason": "",
+        "index": 0,
+        "message": {
+          "annotations": null,
+          "audio": {
+            "data": "",
+            "expires_at": 0,
+            "id": "",
+            "transcript": ""
+          },
+          "content": "Acknowledged.",
+          "function_call": {
+            "arguments": "",
+            "name": ""
+          },
+          "refusal": "",
+          "role": "assistant",
+          "tool_calls": null
+        }
+      }
+    ],
+    "created": 1787679488,
+    "id": "",
+    "model": "claude-sonnet-4-5",
+    "object": "chat.completion",
+    "service_tier": "",
+    "system_fingerprint": "",
+    "usage": {
+      "completion_tokens": 6,
+      "completion_tokens_details": {
+        "accepted_prediction_tokens": 0,
+        "audio_tokens": 0,
+        "reasoning_tokens": 0,
+        "rejected_prediction_tokens": 0
+      },
+      "prompt_tokens": 7,
+      "prompt_tokens_details": {
+        "audio_tokens": 0,
+        "cache_write_tokens": 0,
+        "cached_tokens": 4805
+      },
+      "total_tokens": 4818
+    }
+  }
+}