modelrig 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -10,8 +10,187 @@ published package diverge.
 This project adheres to [Semantic Versioning](https://semver.org/). Dates are
 UTC.
 
+Every `[Unreleased]` entry adds its symbols to `release-manifest.json` (rule P17
+in `docs/ModelRig/development-rules.md`; enforced by `release-parity.test.ts`).
+
 ## [Unreleased]
 
+## [0.10.0] — 2026-10-19
+
+**Behaviour change (raw lane) — migration note.** A `rig.runRaw` call on Gemini
+that passed a non-empty `systemPrompt` alongside `cache.key` used to have the
+system prompt silently DROPPED (the adapter could not place it beside
+`cachedContent`). It is now delivered in the user turn — ahead of `userPrompt`,
+separated by a blank line — and is therefore billed as input tokens on every
+such call. If the cache resource already holds that text, pass
+`systemPrompt: ""` to keep the request byte-identical to before (apps/api's raw
+lane already does). A call with an empty `systemPrompt`, or without a handle, is
+unchanged.
+
+**Per-call user turn (`prompt.user`) + the Gemini cache-handle delivery rule**
+(GitLab issue #5, R1). A route may now declare `prompt.user: <path>` — a second
+template rendered with the same `variables`, capability conditionals and
+`x-trust` rules as `prompt.system` — whose rendered text **is** the user turn of
+every primary attempt (replacing the fixed trigger sentence) and rides ahead of
+the directive on a same-model repair. `prompt.system` may be omitted when
+`prompt.user` is declared. Absent ⇒ the fixed trigger ⇒ byte-identical
+behaviour and an unchanged `bundle_sha`; declaring it changes the `bundle_sha`,
+and `userTemplate` rides the resolved (mirror) bundle. **Cache rule:** a Gemini
+dispatch carrying a cache handle (`cachedContent`) may not carry
+`systemInstruction`; before this release the adapter silently DROPPED the
+rendered template on such a dispatch (the `caching-lifecycle.md` "you do not
+need to empty your template" reassurance was a trap). Now **with a handle,
+everything rendered is delivered as the user turn** — the system prompt (if
+any), a blank line, the user turn — on both lanes, and nothing is dropped. Every
+Gemini attempt that reached the provider stamps `inferences.meta.prompt_delivery`
+(`system` | `user` | `user+cache`, exported as `PromptDelivery`) so the control
+plane can prove what was sent; a transport-error row (no response) carries none.
+The loader warns on a `cache:` route with a Gemini candidate, a non-empty
+`prompt.system` and no `prompt.user`. Docs: `caching-lifecycle.md` → *A cache
+handle changes where the template is delivered*; `route-bundles.md` → *Per-call
+user turn*.
+
+**Prose on the route lane — `output: text`** (GitLab issue #1; incident
+2026-10-11). A route can now declare that its output is prose/markdown rather
+than JSON: `output: text` in the bundle YAML (or `output: { kind: text,
+min_chars: N }` for the one declared length check). The response is returned
+**verbatim** as `result.output` (a string): no `JSON.parse`, no schema, no
+json-mode coaching, and the JSON repair rung is never entered — so a prose route
+is never rejected `content_invalid` for not being JSON. The default is unchanged
+(`json`; `output: json` may be written explicitly and is identical to absent):
+every existing route behaves byte-identically and keeps its `bundle_sha`. A
+text route's `bundle_sha` differs from its JSON twin, and `outputKind` rides the
+resolved bundle, so the hosted mirror lane and call-config pins honour the prose
+contract too. The loader refuses `output: text` combined with `schema:`,
+`require: schema_conformant`, or `repair:` with a teaching error. A JSON route
+that receives prose keeps today's `content_invalid` and now carries a
+`fixHint` pointing at `output: text`. Every dispatched route-lane attempt stamps
+`inferences.meta.output_kind` (`json` | `text`, the contract it was held to);
+raw-lane rows carry no such key. `OutputKind` is exported. Docs:
+`route-bundles.md` → *Prose and markdown output*.
+
+**`responseSchema` on the raw lane (R2, GitLab #6).** `rig.runRaw` accepts a
+JSON Schema object and forwards it as the provider's *native* structured-output
+directive — gemini `responseJsonSchema` + JSON mime, openai/grok strict
+`json_schema` (a non-object root is warned pre-dispatch), anthropic a forced
+tool call — then validates the returned text client-side with the same Ajv the
+routed lane uses. A miss is a **billed, terminal `content_invalid`**: one
+`lane: "raw"` row with that class and a thrown `RigFailureError` whose `fixHint`
+names the first errors; nothing is repaired, retried, or fallen through, so
+`meta.validated` stays `false` (boundary B2 is narrowed from "no structure" to
+"no repair"). Providers without a native schema path on this lane — deepseek and
+the OpenAI-compat hosts (deepinfra / fireworks / zai) — fail closed
+pre-dispatch, as does a schema that is not a plain object, does not compile, or
+is declared alongside `responseFormat`. The row's `meta.schema_sha` is
+`sha256:` of the canonical (sorted-key) schema JSON, so declared-vs-served drift
+is queryable; the schema joins `input_hash` exactly as a route schema does. The
+knob is one more cell of `RAW_KNOB_SUPPORT` — the guard, the published matrix,
+`RAW_DEFAULTS`, and `llms.txt` all derive from it. Zero DDL (`meta` is jsonb).
+
+**The generated tables now ship in the committed docs.** `route-bundles.md`
+(raw-lane defaults, provider × knob matrix) and `routing-reliability.md`
+(failure classes, the boundary) — and the nine use-case template pages — used
+to carry a bare HTML-comment marker that only the modelrig.dev build filled in,
+so GitLab, the OSS mirror and any offline agent reading the repo saw an empty
+line where the table belonged. Every marker is now a fence around its current
+render; the docs build refreshes the fenced body from the same renderer on every
+run (the `docs/llms.txt` rule applied to the docs) and fails on a bare
+placeholder, and a tripwire test asserts each committed body is byte-identical
+to its renderer. Regenerate with `tsx scripts/build-docs-site.ts` and commit.
+
+**Cost rows are priced at the SERVED tier, and Gemini has a `flex` tier
+(GitLab #2).** `attemptCost` / `costComponents` now read `usage.servedTier`
+(both lanes, every attempt — serving, failed, repair) and price `flex` /
+`priority` from the model's published `pricing_v2` tiers instead of always
+billing the standard base. `ServingTiers` gains `flex`, and a tier multiplier
+may now be **per component** (`{ input: 0.5, output: 0.5, cache_read: 1.0 }`
+beside the scalar form; an absent component is exempt, i.e. the standard
+rate) — Google's flex/batch halve input + output but leave cache read "Same as
+Standard", which one scalar cannot say. `gemini/gemini-3.1-pro-preview` (and
+`-customtools`) carry `tiers.flex`, `tiers.priority: 1.8` and the >200k
+context band, verified against the Gemini pricing page 2026-10-11. On the
+InferWealth flex batch this recorded $1.11 where Google's list is ≈$0.68
+(1,357,697 in / 1,289,855 cached / 59,625 out: in $0.068 + cache $0.258 + out
+$0.358). A model that publishes no rate for a served tier still bills at base
+(fail-closed, never a guessed multiplier); `standard` rows are byte-identical.
+Known gap, stated: the >200k context band is **listed, not applied** — rows
+whose prompt exceeds 200k tokens still price at the ≤200k rates and under-state
+Google's list (follow-up issue). `meta.served_tier_source` (`provider` |
+`requested_fallback`) now says whether the served tier came from the provider's
+response or fell back to the requested tier, so a fallback-priced row is
+identifiable. **Scope of the claim:** attempt cost rows (`cost_estimate_usd`)
+and `meta.cost` price at the served tier; the server's managed re-pricing
+(`modelrig-server` `compute-fee.ts` `listPriceCents`, the `/costs` rollup and
+settlement draw) still prices at base — that money path is untouched here and
+tracked for the next money-path MR. Zero DDL.
+
+**Managed serving is released at the SDK/capability layer** (`destination:
+modelrig-served`). The serving cells of the capability table and the published
+`llms.txt` matrix drop their UNRELEASED tags; `config.managedServing` is
+unchanged (set in code, default `false`, so an absent/`direct` route stays
+byte-identical). New customer page `docs/managed-serving.md` — declare the
+destination, enable it in code, mint a `serve`-scoped key, opt the organization
+in (Account settings → Managed serving, or `PATCH /v1/orgs/:org/settings
+{managed_serving_enabled}`), fund the prepaid balance, and what each 401/402/
+403/502/503 refusal teaches; `route-bundles.md` documents the `destination`
+field. The SDK side of the hosted keyless transport (K1/K1b) is in this package
+(it is not in 0.9.0, where a served run uses the local seam). Hosted serving
+also needs the org opt-in, a `serve`-scoped key and a funded prepaid balance.
+
+Routes are visible — and pinnable — before their first call (RV-1). A rig
+created with a `routesDir` and a control-plane export now registers each route
+the moment `createRig()` runs: its metadata (route, version, candidates,
+capture flag) plus its declared resolved bundle and `bundle_sha`, through the
+same `/v1/ingest` call telemetry uses (the `ingest` scope is enough). The
+hosted ingest now stores that bundle (it used to drop it in api mode), so a
+call-config pin passes the eligibility gate instead of failing with "no
+servable bundle". The bundle is route configuration (the authored prompt
+template, never per-call values); it is stored even for a posture-`off` org.
+A prompt version promoted in ModelRig keeps precedence over the YAML template.
+Registration is fire-and-forget and fail-open: never awaited, never throws,
+warns once on failure, and never changes what this process serves. The
+exporter's first-flush routes mirror (which now also lands its bundle in api
+mode) remains the retry path. Pair it with `GET /v1/routes/:route/call-config?include=effective`
+(or MCP `get_call_config`) to see what a route will serve and why — pin vs your
+YAML default — and whether recent calls drifted from a pin. A bundle that
+arrives over `/v1/ingest` is stored as route configuration only: pins, the
+effective view and bake-offs use it, but the hosted gateway keeps serving only
+bundles from a trusted sync, so an `ingest` key cannot change what the gateway
+serves. `stampBatch` now writes routes with and without a bundle as two
+separate writes (a bulk insert needs every row to carry the same columns).
+
+Silent telemetry drops are now loud — **no configuration required**. When an
+ingest POST is rejected with `401`/`403` (a wrong, revoked, or wrong-org key),
+the api sink emits ONE loud, legible warning — `[modelrig] AUTH FAILED —
+telemetry is being DROPPED (401 at <host>, key …5WMM) …` — naming the host and
+the redacted key and pointing at `app.modelrig.ai` and `modelrig doctor`. It
+fires once per failure streak (a later successful send re-arms it), rides the
+POST that is already failing (no extra request), and never prints the key or the
+response body. This is the automatic safety net — the one key a customer already
+sets is enough; there is no boot-preflight env var.
+
+`modelrig doctor` — a new CLI command that confirms, in one line, which org your
+`MODELRIG_API_KEY` resolves to (via the server's `GET /v1/whoami`): prints
+`key …5WMM → org «YourOrg» ✓` on success, a loud `AUTH FAILED (401)` line on a
+rejected key, and exits non-zero when the key is bad — so CI / a deploy step /
+setup can gate on it before any traffic runs. Never prints the key (last-four
+only).
+
+**Which org am I exporting to? — the wrong-org signal (REL-1, M5).** A valid key
+minted in the wrong org used to fail silently: every ingest POST is a 200 and the
+runs land in another org's console. Now, on the first successful flush in each
+process, the api sink calls `GET /v1/whoami` once (the same helper `modelrig
+doctor` uses) and logs `[modelrig] exporting to org «Name» (slug) as key «name»
+rig_sk_…last4`. It runs in the background, never blocks or drops a batch, and is
+silent if whoami fails (a rejected key already has its own `AUTH FAILED` line).
+New code option `createRig({ expectOrg: "<slug>" })`: when the key resolves to a
+different org it logs `[modelrig] ORG MISMATCH: key resolves to «a», expectOrg is
+«b» — telemetry is landing in «a»` loudly on every flush. The whoami call is
+aborted after 5 s, so it never holds a process open. It never throws and never drops telemetry. It is a code option, not an
+env var (P15). `modelrig doctor --expect-org <slug>` exits 1 and prints both
+slugs on a mismatch, so a deploy or CI step can gate on it. Docs:
+`instrumentation.md` → *Which org am I exporting to?*
+
 ## [0.9.0] — 2026-09-01
 
 **Breaking** (the reason this is 0.9.0, not 0.8.2): the temporary `rig.feedback` /

package/README.md

@@ -89,10 +89,11 @@ import { createRig, loadConfigFromEnv } from "modelrig";
 const rig = createRig(loadConfigFromEnv());        // keys from GEMINI_API_KEY etc.
 const result = await rig.run("example.support_summarize", {
   input: { ticket, product, priorContext },        // template variables
-  tags: { run_id, step: "summarize" },
-  budget: { envelope: run_id },                    // hard-stop cost envelope
+  tags: { subject: customer, feature: "summarize" },
+  budget: { envelope: ticketId },                  // hard-stop cost envelope
 });
-// result.output  — schema-validated JSON (ajv), regardless of serving model
+// result.output  — schema-validated JSON (ajv), regardless of serving model;
+//                  the verbatim string on an `output: text` (prose) route
 // result.meta    — servedCandidate, tokens (in/out/cached), cost, tiers,
 //                  validation status, attempts by failure class
 rig.close();
@@ -123,15 +124,23 @@ without it. ModelRig carries the handle and prices the hits — it never creates
 refreshes, or deletes the resource, so a long job needs your own TTL heartbeat
 (see the [caching lifecycle](https://modelrig.dev/caching-lifecycle.html) doc).
 The Lane-B `rig.runRaw({ provider, model, apiKey, …, cache: { key } })` seam takes
-the same field.
+the same field. A Gemini handle forbids a system instruction on the request, so
+**with a handle everything the route rendered is delivered as the user turn**
+(never dropped); declare the per-call delta in a `prompt.user` template and let
+the cache hold the shared prefix — every attempt stamps `meta.prompt_delivery`
+(`system` | `user` | `user+cache`) so you can prove what was sent.
 
 `rig.runRaw` also accepts
 provider knobs, each additive — absent ⇒ byte-identical dispatch:
 `grounding: { mode: "native" }` (native provider web grounding —
 gemini; grok fail-closed until CE-9b), `serviceTier: "standard" | "flex" | "priority"`,
 `reasoning: { level: "minimal" | "low" | "medium" | "high" }` (reasoning effort¹),
-and `responseFormat: "json_object"` (syntactic-JSON forcing¹ — MIME-shaping, NOT
-schema enforcement, so `meta.validated` stays `false`). A declared directive a
+`responseFormat: "json_object"` (syntactic-JSON forcing¹ — MIME-shaping, NOT
+schema enforcement, so `meta.validated` stays `false`), and `responseSchema`
+(a JSON Schema object² — forwarded as the provider's native structured-output
+directive AND Ajv-checked client-side; a miss is a billed, terminal
+`content_invalid` — never repaired or retried — and the row carries
+`meta.schema_sha`). A declared directive a
 provider cannot honor FAILS CLOSED — a thrown `RigFailureError` with class
 `invariant_violation`, pre-dispatch (no meter, no provider call) — never a silent
 drop. **Which provider honors which knob is one table** — the runtime guard and
@@ -144,8 +153,10 @@ you don't duplicate the thinking-model set). A grounded step that also passes a
 cache resource at creation (ModelRig sends `cachedContent` without tools, which
 the provider requires).
 
-_¹ Multi-provider `reasoning` and `responseFormat` ship in
-0.4.0; on the published package `reasoning`/`grounding` are gemini-only._
+_¹ Which provider honors `reasoning`, `grounding` and `responseFormat` is the
+knob matrix — generated from the same table the runtime guard reads._
+_² `responseSchema` needs 0.10.0 or newer (gemini / openai / grok / anthropic;
+deepseek and the compat hosts fail closed) — see the knob matrix._
 
 **runRaw — a BYOK passthrough (Lane B).** When you don't need a route — no
 schema, no validation, no retries — call a `provider/model` directly with your
@@ -248,6 +259,10 @@ lines up with the console's built-ins:
 | `session` | the conversation/session the call belongs to |
 | `cost_center` | the team/budget to attribute spend to |
 
+These five are the keys **you** set. `run_id` and `step` are stamped by the SDK
+inside a run (don't set `run_id` yourself), and ModelRig owns a few more; the one
+complete list is in the [instrumentation guide](./docs/instrumentation.md#reserved-tag-keys-the-one-list).
+
 `modelrig validate` warns on near-misses — a declared `rig.yaml` dimension named
 `customer`, `tenant`, `user_id`, `team`, … is nudged toward the reserved key it
 resembles. They stay ordinary tags; nothing is required.
@@ -260,33 +275,40 @@ one **step** per model-call family, and **save the work products** as artifacts;
 the console's **Runs** tab then shows the run → step → artifact chain you click
 through, and `/projects` groups it by your tags.
 
+<!-- BLOCK:RUN_WRAP -->
+**Wrap one pipeline execution in a run.** Every pipeline execution is a run. Wrap each execution in `run.scope` (or `run.start` / `run.end`), name one step per model call with `stepKey`, `artifact.save` the work products, and pass `environment` so the Env column on /runs is filled. Inside the run the SDK stamps `run_id` and `step` on every call. `run_id` is reserved: don't set it yourself.
+
 ```ts
 import { createRig, loadConfigFromEnv } from "modelrig";
 
 const rig = createRig(loadConfigFromEnv());
 
-// One run per pipeline execution. run.scope isolates concurrent runs; use
-// run.start()/run.end() for one run at a time on a request path.
+// Every pipeline execution is a run. Inside the scope the SDK records each
+// rig.run / rig.runRaw call as a step and stamps run_id and step on every row.
+// run_id is reserved: don't set it yourself (put your own attempt id in a tag of
+// your own, such as pipeline_attempt_id).
 await rig.artifacts.run.scope(
-  { pipeline: "support", episodeKey: ticketId },
+  { pipeline: "support", episodeKey: ticketId, environment: process.env.NODE_ENV ?? "development" },
   async () => {
     const result = await rig.run("example.support_summarize", {
       input: { ticket, product, priorContext },
-      tags: { subject: customer, feature: "summarize" }, // run_id auto-stamped
-      stepKey: "summarize",                              // names this step on /runs
+      tags: { subject: customer, feature: "summarize" },
+      stepKey: "summarize", // names this step on /runs
     });
-    // Save the work product — prompt / raw / parsed all save the same way.
-    rig.artifacts.artifact.save(result.output, { name: "summary", type: "step_output" });
+    rig.artifacts.artifact.save(result.output, { name: "summary", type: "step_output", stepKey: "summarize" });
   },
 );
-rig.close();
+
+await rig.close(); // flushes the exporter — call once at shutdown
 ```
+<!-- /BLOCK:RUN_WRAP -->
 
 - **Tags:** carry `subject` (what the run is *about* — an opaque id) and
   `feature`. Inside a run context the SDK stamps `tags.run_id` (the run's
   `episodeKey`, else its id) and `tags.step` (the current step key) on every
-  attempt row of both lanes — a value you pass always wins, and outside a run
-  context nothing is stamped, so the row is byte-identical.
+  attempt row of both lanes; outside a run context nothing is stamped, so the row
+  is byte-identical. `run_id` is reserved: don't set it yourself — the full
+  reserved-key list is in the [instrumentation guide](./docs/instrumentation.md#reserved-tag-keys-the-one-list).
 - **Raw lane too:** a `rig.runRaw` call inside a run context records a
   ground-truth step (since 0.5.0), so grounded/cached BYOK pipelines fill the
   same graph.
@@ -297,8 +319,7 @@ rig.close();
 
 **On by default under a control plane.** The run/artifact namespace is **on by
 default once a control plane is configured** — set `MODELRIG_API_KEY=rig_sk_…`
-(or the self-host Supabase pair) and runs record automatically, metadata and
-hashes only. A **pure local-only rig** (no sink to ship to) stays off; force it
+(or the self-host Supabase pair) and runs record automatically. A **pure local-only rig** (no sink to ship to) stays off; force it
 on there with `MODELRIG_ARTIFACTS=1`. To **opt out of capture**, set posture
 `off` in your account settings (the console or the `set_org_settings` MCP tool) —
 the account posture is the customer control, not a deployment env var. With the
@@ -306,11 +327,12 @@ namespace off (a local-only rig) it is inert — `run.start` is a
 no-op, `artifact.save` returns null, zero rows are written, and your pipeline
 behaves byte-for-byte as before. `modelrig status` prints the current posture.
 
-> **Metadata and hashes only, this release.** Content custody (holding the
-> serialized bytes) is early access; today the value you save is hashed (sha256)
-> and the bytes are discarded — the metadata row and its integrity hash are what
-> persist. A `zeroRetention` run refuses every artifact fail-closed at the SDK
-> gate.
+> **What is kept.** Every saved artifact records a metadata row with a sha256
+> integrity hash. Whether the serialized bytes are kept as well is your
+> organization's [content custody](https://modelrig.dev/content-custody.html)
+> posture: new organizations are created `managed` (bytes kept in your managed
+> store); `metadata` keeps hashes only and `off` captures nothing. A
+> `zeroRetention` run refuses every artifact fail-closed at the SDK gate.
 
 The full artifact API — lineage (`link`), evaluations (`evaluate`), the reusable
 per-step seam, and `run.scope` vs `run.start` — is the
@@ -345,8 +367,10 @@ on the quickstart:
 
 ## Honest limits
 
-- **Prepaid balances and managed billing are not built yet.** This release is
-  the gateway and the self-host lane; the hosted control plane has one customer.
+- **Managed serving is opt-in and prepaid.** It draws from a prepaid balance your
+  organization funds in the console ([Managed serving](https://modelrig.dev/managed-serving.html));
+  with no balance, every call runs on your own provider keys (`destination: direct`,
+  the default).
 - **`0.x` means the shape may still move.** Route and config contracts are
   stable enough to build on, not frozen.
 - **`modelrig serve` needs the `modelrig-server` package** — it is not bundled

package/data/PROVENANCE.md

@@ -13,6 +13,20 @@ this snapshot was copied by hand per implementation-plan §9. Replace this manua
 copy with the sync script's output when Phase 0 tooling lands; until then, any
 pin bump must re-copy this file and update this note.
 
+HAND-ADDED `pricing_v2` BLOCKS (must survive a pin bump — re-apply after any
+re-copy): `gemini/gemini-3.1-pro-preview` and `…-customtools` carry an additive
+`pricing_v2` (GitLab issue #2, 2026-10-11, verified against
+https://ai.google.dev/gemini-api/docs/pricing): `tiers.flex = { input: 0.5,
+output: 0.5, cache_read: 1.0 }` (flex/batch halve input + output; cache read is
+"Same as Standard"), `tiers.priority = 1.8` (every component), and the >200k
+context band. The snapshot wins on shared keys and never carries `pricing_v2`
+upstream, so the block lives on the snapshot entry itself; `getPricingV2` reads
+it and the served-tier cost path (`src/run/cost.ts`) prices flex/priority rows
+from it. Flat fields are untouched (base is byte-identical). `scripts/sync-upstream.ts
+--apply` RE-GRAFTS every `pricing_v2` block from the current map onto the new
+snapshot (and refuses to apply if upstream dropped an entry that carries one), so a
+pin bump cannot silently drop them; the manual re-copy path above must do the same.
+
 Key naming (verified against the snapshot):
 - Gemini API models: `gemini/<model>` (bare ids resolve to vertex_ai pricing — do not use)
 - OpenAI models: bare `<model>`

package/data/pricing-map.json

@@ -20338,6 +20338,19 @@
         "tpm": 800000
     },
     "gemini/gemini-3.1-pro-preview": {
+        "pricing_v2": {
+            "base": { "input": 2e-06, "output": 1.2e-05, "cache_read": 2e-07 },
+            "tiers": {
+                "priority": 1.8,
+                "flex": { "input": 0.5, "output": 0.5, "cache_read": 1.0 }
+            },
+            "context_bands": [
+                { "above_tokens": 200000, "rates": { "input": 4e-06, "output": 1.8e-05, "cache_read": 4e-07 } }
+            ],
+            "source": "https://ai.google.dev/gemini-api/docs/pricing (Gemini 3.1 Pro Preview, verified 2026-10-11: flex/batch 0.5x input+output, cache read 'Same as Standard'; priority 1.8x every component incl. cache read; >200k band doubles input, output and cache read)",
+            "as_of": "2026-10-11",
+            "basis": "base · standard tier · text · prompts ≤ 200k tokens (the >200k context band is listed; cost rows price at the SERVED tier)"
+        },
         "cache_read_input_token_cost": 2e-07,
         "cache_read_input_token_cost_above_200k_tokens": 4e-07,
         "input_cost_per_token": 2e-06,
@@ -20395,6 +20408,19 @@
         "web_search_billing_unit": "per_query"
     },
     "gemini/gemini-3.1-pro-preview-customtools": {
+        "pricing_v2": {
+            "base": { "input": 2e-06, "output": 1.2e-05, "cache_read": 2e-07 },
+            "tiers": {
+                "priority": 1.8,
+                "flex": { "input": 0.5, "output": 0.5, "cache_read": 1.0 }
+            },
+            "context_bands": [
+                { "above_tokens": 200000, "rates": { "input": 4e-06, "output": 1.8e-05, "cache_read": 4e-07 } }
+            ],
+            "source": "https://ai.google.dev/gemini-api/docs/pricing (Gemini 3.1 Pro Preview, verified 2026-10-11: flex/batch 0.5x input+output, cache read 'Same as Standard'; priority 1.8x every component incl. cache read; >200k band doubles input, output and cache read)",
+            "as_of": "2026-10-11",
+            "basis": "base · standard tier · text · prompts ≤ 200k tokens (the >200k context band is listed; cost rows price at the SERVED tier)"
+        },
         "cache_read_input_token_cost": 2e-07,
         "cache_read_input_token_cost_above_200k_tokens": 4e-07,
         "input_cost_per_token": 2e-06,

package/dist/adapters/attempt-meta-map.d.ts

@@ -14,7 +14,7 @@
  *  - gemini: `finishReason` is `SAFETY` / `PROHIBITED_CONTENT` / `RECITATION`.
  * The refusal TEXT itself is never carried (content) — only the boolean.
  */
-import type { AttemptMetaV1, FinishReason } from "../telemetry/attempt-meta";
+import type { AttemptMetaV1, FinishReason, PromptDelivery, ServedTierSource } from "../telemetry/attempt-meta";
 import type { AdapterRequest, ProviderId, ToolCall } from "../types/provider";
 /** Map a provider's native finish/stop reason to the `FinishReason` enum
  * (spec §2). Unknown/absent ⇒ undefined (never inferred); an unrecognised
@@ -51,6 +51,13 @@ export interface AdapterMetaSignals {
     };
     /** true = the run loop streamed deltas (stream()); false/absent = buffered. */
     readonly streaming?: boolean;
+    /** Issue #5 (R1): how the rendered prompt reached the model on this call —
+     * reported by the adapter that shaped the request (today: gemini, where a
+     * cache handle moves delivery). Absent ⇒ no `prompt_delivery` key. */
+    readonly promptDelivery?: PromptDelivery;
+    /** Issue #2 (L6 F5): did the provider ECHO the served tier, or did the adapter
+     * fall back to the requested tier? Stamped as `meta.served_tier_source`. */
+    readonly servedTierSource?: ServedTierSource;
 }
 /** Build one adapter's NATIVE `meta` (spec §2). Only defined signals appear —
  * everything else is unknown and omitted. The producer takes it from here. */

package/dist/adapters/attempt-meta-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attempt-meta-map.d.ts","sourceRoot":"","sources":["../../src/adapters/attempt-meta-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;kCAEkC;AAClC,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,YAAY,GAAG,SAAS,CA6C1B;AAED;;;oDAGoD;AACpD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,cAAc,GAClB;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOlF;AAED;0EAC0E;AAC1E,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,GACzC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,SAAS,CAQ/C;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;8EAC8E;AAC9E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,CAAC,EAAE,kBAAkB,GACpB,OAAO,CAAC,aAAa,CAAC,CAyBxB;AAED;;;uDAGuD;AACvD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CASzE"}
+{"version":3,"file":"attempt-meta-map.d.ts","sourceRoot":"","sources":["../../src/adapters/attempt-meta-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC/G,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;kCAEkC;AAClC,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,YAAY,GAAG,SAAS,CA6C1B;AAED;;;oDAGoD;AACpD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,cAAc,GAClB;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOlF;AAED;0EAC0E;AAC1E,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,GACzC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,SAAS,CAQ/C;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;0EAEsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;gFAC4E;IAC5E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C;AAED;8EAC8E;AAC9E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,CAAC,EAAE,kBAAkB,GACpB,OAAO,CAAC,aAAa,CAAC,CA2BxB;AAED;;;uDAGuD;AACvD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CASzE"}

package/dist/adapters/attempt-meta-map.js

@@ -134,6 +134,10 @@ function buildAdapterMeta(provider, s) {
     }
     if (typeof s.streaming === "boolean")
         meta.streaming = s.streaming;
+    if (s.promptDelivery !== undefined)
+        meta.prompt_delivery = s.promptDelivery;
+    if (s.servedTierSource !== undefined)
+        meta.served_tier_source = s.servedTierSource;
     return meta;
 }
 /** A transport/SDK error's coarse envelope (spec §2 `http_status`/`error_code`).

package/dist/adapters/build-adapters.js

@@ -27,8 +27,8 @@ function buildAdapters(config, registryFacts, compatStatic) {
     }
     if (config.keys.grok)
         adapters.set("grok", (0, grok_1.createGrokAdapter)({ apiKey: config.keys.grok }));
-    // A1 aggregator hosts behind the generic openai-compatible adapter.
-    for (const hostId of ["deepinfra", "fireworks"]) {
+    // A1 aggregator hosts + Z.ai (B4a) behind the generic openai-compatible adapter.
+    for (const hostId of ["deepinfra", "fireworks", "zai"]) {
         const apiKey = config.keys[hostId];
         if (!apiKey)
             continue;

package/dist/adapters/gemini.d.ts

@@ -13,8 +13,9 @@
  * Copyright (c) 2023 Berri AI, MIT License — retain this notice if LiteLLM's
  * gemini transformation logic is consulted during the port.
  */
-import type { AdapterRequest, CapabilityFlag, ProviderAdapter } from "../types/provider";
+import type { AdapterRequest, CapabilityFlag, ProviderAdapter, ServiceTier } from "../types/provider";
 import type { FailureClass } from "../types/failures";
+import type { PromptDelivery, ServedTierSource } from "../telemetry/attempt-meta";
 export interface GeminiAdapterConfig {
     readonly apiKey: string;
 }
@@ -53,9 +54,35 @@ export interface GeminiShapedRequest {
     readonly model: string;
     readonly contents: string;
     readonly config: Record<string, unknown>;
+    /** Issue #5 (R1): how the rendered prompt was delivered — stamped on the
+     * attempt's `meta.prompt_delivery` so the control plane can prove it. */
+    readonly promptDelivery: PromptDelivery;
 }
+/**
+ * THE CACHE-HANDLE DELIVERY RULE (GitLab issue #5, R1). A request that sets
+ * `cachedContent` may not set `systemInstruction` (Google rejects both — the
+ * system instruction and tools are baked into the cache at creation). Before
+ * R1 the adapter silently DROPPED a non-empty system prompt here, so a route
+ * whose template held the per-call delta lost it whenever a handle was passed
+ * (caching-lifecycle.md's "you do not need to empty your template" was a trap).
+ * The rule now: **with a cache handle, everything rendered is delivered as the
+ * user turn** — the system prompt (when non-empty), a blank line, then the user
+ * turn — and nothing is dropped. The cache holds the shared prefix; the user
+ * turn carries what changes per call. Pure; exported for the adapter tests.
+ */
+export declare function cachedUserTurn(systemPrompt: string, userPrompt: string): string;
 /** Pure request shaping — everything except the abort signal. */
 export declare function buildGeminiRequest(model: string, req: ShapingInput): GeminiShapedRequest;
+/** Best-effort served-tier extraction (ported): response.serviceTier, then
+ * usageMetadata.trafficType (Vertex path), else assume the requested tier —
+ * production bills flex when a flex request was accepted without a tier echo.
+ * Issue #2 (L6 F5): now that cost rows PRICE at the served tier, the fallback
+ * is disclosed — `source` lands on `meta.served_tier_source`. Pure; exported
+ * for the unit test. No behaviour change in the tier itself. */
+export declare function extractGeminiServedTier(rawServiceTier: string | undefined, trafficType: string | undefined, requested: ServiceTier): {
+    readonly tier: ServiceTier;
+    readonly source: ServedTierSource;
+};
 /** A candidate's parts as we read them post-response — `functionCall`, `text`,
  * and (if `includeThoughts` were ever set) a `thought`-flagged text part may all
  * appear on the same candidate (a grounded / thinking turn). */

package/dist/adapters/gemini.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EACV,cAAc,EAGd,cAAc,EACd,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAQlE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;mCAImC;AACnC,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAI7D,CAAC;AA0BH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG9E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAyCxE;AAED;6EAC6E;AAC7E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;AAE7D;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,iBAAiB,GAAG,IAAI,CAQrG;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,mBAAmB,CAqDxF;AA0BD;;gEAEgE;AAChE,KAAK,mBAAmB,GAAG;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AACF,KAAK,oBAAoB,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAA;KAAE,CAAA;CAAE,CAAC;AAEvG;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,oBAAoB,GAAG,SAAS,GAAG,MAAM,CAM9F;AAED;;qEAEqE;AACrE,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,oBAAoB,GAAG,SAAS,GAAG,OAAO,CAInG;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,oBAAoB,GAAG,SAAS,EAC3C,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,QAAQ,EAAE,OAAO,GAChB,MAAM,CAGR;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,eAAe,CA4MhF"}
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"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"}

package/dist/adapters/gemini.js

@@ -19,7 +19,9 @@ exports.GEMINI_THINKING_CAPABLE_MODELS = void 0;
 exports.geminiSupports = geminiSupports;
 exports.classifyGeminiFailure = classifyGeminiFailure;
 exports.geminiReasoningUnsupported = geminiReasoningUnsupported;
+exports.cachedUserTurn = cachedUserTurn;
 exports.buildGeminiRequest = buildGeminiRequest;
+exports.extractGeminiServedTier = extractGeminiServedTier;
 exports.extractGeminiCandidateText = extractGeminiCandidateText;
 exports.geminiCandidateHasFunctionCall = geminiCandidateHasFunctionCall;
 exports.resolveGeminiText = resolveGeminiText;
@@ -126,6 +128,21 @@ function geminiReasoningUnsupported(model, req) {
     }
     return null;
 }
+/**
+ * THE CACHE-HANDLE DELIVERY RULE (GitLab issue #5, R1). A request that sets
+ * `cachedContent` may not set `systemInstruction` (Google rejects both — the
+ * system instruction and tools are baked into the cache at creation). Before
+ * R1 the adapter silently DROPPED a non-empty system prompt here, so a route
+ * whose template held the per-call delta lost it whenever a handle was passed
+ * (caching-lifecycle.md's "you do not need to empty your template" was a trap).
+ * The rule now: **with a cache handle, everything rendered is delivered as the
+ * user turn** — the system prompt (when non-empty), a blank line, then the user
+ * turn — and nothing is dropped. The cache holds the shared prefix; the user
+ * turn carries what changes per call. Pure; exported for the adapter tests.
+ */
+function cachedUserTurn(systemPrompt, userPrompt) {
+    return systemPrompt === "" ? userPrompt : `${systemPrompt}\n\n${userPrompt}`;
+}
 /** Pure request shaping — everything except the abort signal. */
 function buildGeminiRequest(model, req) {
     const usingCache = req.cache?.key !== undefined && req.cache.key !== "";
@@ -156,11 +173,18 @@ function buildGeminiRequest(model, req) {
     }
     // cachedContent excludes systemInstruction and tools — the API rejects
     // requests setting both (they are baked into the cache at creation time,
-    // including the googleSearch tool for cached grounded steps).
+    // including the googleSearch tool for cached grounded steps). Issue #5 (R1):
+    // the rendered system prompt is therefore delivered AS the user turn (see
+    // cachedUserTurn) rather than dropped; `promptDelivery` records which.
+    let contents = req.userPrompt;
+    let promptDelivery;
     if (usingCache) {
         config.cachedContent = req.cache?.key;
+        contents = cachedUserTurn(req.systemPrompt, req.userPrompt);
+        promptDelivery = "user+cache";
     }
     else {
+        promptDelivery = req.systemPrompt !== "" ? "system" : "user";
         if (req.systemPrompt !== "") {
             config.systemInstruction = req.systemPrompt;
         }
@@ -179,20 +203,23 @@ function buildGeminiRequest(model, req) {
     if (req.requestedTier === "flex") {
         config.serviceTier = "flex";
     }
-    return { model, contents: req.userPrompt, config };
+    return { model, contents, config, promptDelivery };
 }
 /** Best-effort served-tier extraction (ported): response.serviceTier, then
  * usageMetadata.trafficType (Vertex path), else assume the requested tier —
- * production bills flex when a flex request was accepted without a tier echo. */
-function extractServedTier(rawServiceTier, trafficType, requested) {
+ * production bills flex when a flex request was accepted without a tier echo.
+ * Issue #2 (L6 F5): now that cost rows PRICE at the served tier, the fallback
+ * is disclosed — `source` lands on `meta.served_tier_source`. Pure; exported
+ * for the unit test. No behaviour change in the tier itself. */
+function extractGeminiServedTier(rawServiceTier, trafficType, requested) {
     if (rawServiceTier === "flex" || trafficType === "ON_DEMAND_FLEX")
-        return "flex";
+        return { tier: "flex", source: "provider" };
     if (rawServiceTier === "standard" || rawServiceTier === "default" || trafficType === "ON_DEMAND") {
-        return "standard";
+        return { tier: "standard", source: "provider" };
     }
     if (rawServiceTier === "priority" || trafficType === "ON_DEMAND_PRIORITY")
-        return "priority";
-    return requested;
+        return { tier: "priority", source: "provider" };
+    return { tier: requested, source: "requested_fallback" };
 }
 /**
  * #245 secondary — concatenate the answer `text` parts of a Gemini candidate's
@@ -277,7 +304,7 @@ function createGeminiAdapter(config) {
                 const ttfbMs = Date.now() - dispatchedAt;
                 const usageMetadata = (response.usageMetadata ?? {});
                 const respWithTier = response;
-                const servedTier = extractServedTier(respWithTier.serviceTier, usageMetadata.trafficType, req.requestedTier);
+                const { tier: servedTier, source: servedTierSource } = extractGeminiServedTier(respWithTier.serviceTier, usageMetadata.trafficType, req.requestedTier);
                 const tokensIn = usageMetadata.promptTokenCount ?? 0;
                 // Thinking tokens are billed as output and count against
                 // maxOutputTokens — include them in tokensOut for honest accounting.
@@ -303,6 +330,8 @@ function createGeminiAdapter(config) {
                     toolCalls,
                     grounding: req.grounding === true ? { searchProvider: "google" } : undefined,
                     streaming: false,
+                    promptDelivery: shaped.promptDelivery, // issue #5 (R1): prove what was sent
+                    servedTierSource,
                 });
                 // Tool-call turn (spec §4.4): collect functionCall parts. When present,
                 // surface normalized calls and skip the text/empty/truncation guards.