@stigg/agent-sdk-js 0.1.0 → 0.2.0

package/README.md

@@ -256,6 +256,9 @@ that vendor's API would have guessed — so these are what your meters filter on
 | Mistral                   | `mistral.chat.complete`, `mistral.chat.stream`, `mistral.chat.parse`, `mistral.chat.parseStream`, `mistral.fim.complete`, `mistral.fim.stream`, `mistral.agents.complete`, `mistral.agents.stream` | `prompt_tokens`, `completion_tokens`, `total_tokens` — the **wire's** names, not the camelCase its SDK renames them to |
 | Ollama                    | `ollama.chat`, `ollama.generate`                                    | `prompt_eval_count`, `eval_count`, `total_tokens` — self-hosted, so these measure tokens you served yourself rather than tokens anyone billed you for |
 | Bedrock                   | `bedrock.send`                                                      | `inputTokens`, `outputTokens`, `cacheReadInputTokens`, `cacheWriteInputTokens`, `totalTokens` — and no `cost`, because Bedrock states none |
+| Databricks                | `databricks.chat.completions.create`, `databricks.responses.create`, `databricks.query` | `prompt_tokens`, `completion_tokens`, `total_tokens`, `reasoning_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens` — and no `cost`, because Databricks states none on any response. `databricks.query` is the first-party client and reports the first three only; it camelCases the wire and is renamed back, so both clients report one vocabulary |
+| Databricks — external models | `databricks-external.chat.completions.create`, `databricks-external.responses.create`, `databricks-external.query` | the same six. A separate vendor name because a different party is invoiced, and it is **opt-in**: the two routes are indistinguishable from the client, so naming it asserts something the SDK cannot check |
+| Cloudflare                | `cloudflare.chat.completions.create`, `cloudflare.responses.create`, `cloudflare.messages.create`, `cloudflare.ai.run` | the OpenAI set plus `cache_read_input_tokens`, `cache_creation_input_tokens` — the union across every wire it serves, and a call reports only the names its own route sent. No `cost` and no neuron count: neither Workers AI nor AI Gateway states a price on any response, so `cf_aig_log_id` rides as a dimension instead. A gateway **cache hit meters nothing**, because nobody was billed for it |
 | TypeSafe                  | `typesafe.systemOne`                                                | `input_tokens`, `output_tokens`, `total_tokens`                                           |
 | Gemini                    | `gemini.models.generateContent`, `gemini.models.generateContentStream` | `promptTokenCount`, `candidatesTokenCount`, `cachedContentTokenCount`, `thoughtsTokenCount`, `toolUsePromptTokenCount`, `totalTokenCount` |
 | Gemini — a chat           | `gemini.chats.sendMessage`, `gemini.chats.sendMessageStream`        | the same five                                                                             |
@@ -372,6 +375,7 @@ both.**
 | OpenAI Responses | `input_tokens`  | **Yes**, includes `cached_tokens`                        |
 | LangChain        | `input_tokens`  | **Yes**, includes both cache keys                        |
 | Gemini           | `promptTokenCount` | **Yes**, includes `cachedContentTokenCount`           |
+| Databricks       | `prompt_tokens` | **Unverified** — Databricks documents neither direction. It spells the pair with Anthropic's names (`cache_read_input_tokens`), whose counters sit beside the input count, so this SDK does not subtract them. Its stated `total_tokens` is read rather than computed, so the total is right either way — price the total, or verify against your own endpoint before pricing the breakdown |
 
 Gemini overlaps in both directions at once, so it is worth stating separately: pricing
 `promptTokenCount` **and** `cachedContentTokenCount` double-bills the cached tokens, while
@@ -420,6 +424,7 @@ are recipes over the same wrapper. One you **operate** is the opposite binding a
 | Client                                           | `stigg.wrap(client, { stiggContext })`               | gates the recipe's methods on a copy, vendor matched by shape                            | Yes — when the context names an entitlement |
 | Client — a gateway you **call**                  | `wrap(client, { recipe: openrouterRecipe() })`       | same wrapper; the recipe bills `usage.cost` and attributes `response.model`              | Yes, same as any client                    |
 | Client — a gateway whose cost is in a **header** | `wrap(client, { recipe: litellmRecipe() })`          | same wrapper; the recipe bills `x-litellm-response-cost` and attributes `response.model` | Yes, same as any client                    |
+| Client — a gateway that states **no** price      | `wrap(client, { recipe: databricksRecipe() })`       | same wrapper; no `cost` metric at all, and the model that answered is attributed instead | Yes, same as any client                    |
 | Gateway you **operate** (`bindings/proxy`)       | `client.stigg.headers()` → `stigg.ingestFromHeaders(...)` | attribution travels as `x-stigg-*` headers; `vendor` names the shape it observed         | **No — ingest only**                       |
 
 A client run that names no `entitlement` lands in the same column as the gateway — metering
@@ -449,6 +454,9 @@ which recipe matches, and that decides what you can meter:
 | `https://openrouter.ai/api/v1`       | `openrouterRecipe` | `openrouter.*` (see below)        | tokens, `cost`, model that served |
 | the LiteLLM proxy URL you configured | `litellmRecipe`    | `litellm.*`                       | tokens, `cost`, model that served |
 | `https://api.groq.com/openai/v1`     | `groqRecipe`       | `groq.*`                          | tokens only                       |
+| a Databricks workspace `/serving-endpoints`  | `databricksRecipe` | `databricks.*`                    | tokens, model that answered       |
+| `https://api.cloudflare.com/client/v4/accounts/<id>/ai/v1` | `cloudflareRecipe` | `cloudflare.*`                    | tokens only                       |
+| `https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/<provider>` | `cloudflareRecipe` | `cloudflare.*`                    | tokens, model that served, log id |
 | anything else OpenAI-compatible      | `openAIRecipe`     | `openai.*`                        | tokens only                       |
 
 Each of those covers **both OpenAI surfaces**, and a surface is its own event: Chat Completions
@@ -521,9 +529,106 @@ name to match.
 > `for await` bypasses the meter, because the stream is your object and cannot be swapped for a
 > metered copy. Call the methods, and iterate the stream.
 
-> **Not covered yet:** OpenRouter's own `@openrouter/sdk` package is a different shape — its method
-> is `chat.send` and its counters are camelCase — so `wrap` does not recognise it and will refuse
-> the client rather than meter it silently. Use the OpenAI-compatible endpoint above.
+> **OpenRouter, both ways round.** OpenRouter's own `@openrouter/sdk` package is a different shape
+> — its methods are `chat.send` and `responses.send`, and its counters come back camelCased — but
+> `openrouterRecipe` declares those surfaces too, so `wrap` governs that client as well as an
+> `OpenAI` one pointed at `https://openrouter.ai/api/v1`. Four event names rather than two
+> (`openrouter.chat.send` beside `openrouter.chat.completions.create`), because a meter filtering
+> on one must not catch the other. Both report the **wire's** counter names: the SDK's camelCase is
+> a rename of the same block, and one account should not read as two vocabularies.
+
+> **Databricks, as two recipes over one wire.** Databricks model serving is OpenAI-compatible, so
+> an `OpenAI` client pointed at `https://<workspace>/serving-endpoints` is all the application
+> holds. Two things make it worth a recipe rather than the `openAIRecipe` row above.
+>
+> The first is that **the request does not say what model is being used.** On the classic route the
+> `model` argument is a serving *endpoint* name the customer chose — `prod-chat` is legal, and it
+> may front DBRX, a Llama that Databricks hosts, or somebody's OpenAI account. The response's
+> `model` field is what recovers that, and `databricksRecipe` puts it on the ingest as a dimension.
+> Metered as `openai.*` the whole workspace is one undifferentiated stream.
+>
+> The second is **who gets invoiced**, and this one is a decision you have to make rather than one
+> the SDK can make for you. Foundation Model API traffic (`databricks-claude-*`, `databricks-llama-*`,
+> DBRX) is billed to your Databricks account in DBUs. An endpoint configured as an *external model*
+> carries your own OpenAI or Anthropic key, and that provider invoices your account with them —
+> Databricks only estimates the figure, into `system.ai_gateway.external_model_spend`, and says it
+> is not liable for the difference. Same host, same path, same request, same response: **nothing on
+> the client side distinguishes them.** So the split is an assertion, not a detection —
+>
+> ```ts
+> stigg.wrap(client, { recipe: databricksExternalRecipe() });
+> ```
+>
+> — and `databricksExternalRecipe` is deliberately not registered by default, because an assertion
+> nobody made is not a default. Assert wrongly and nothing throws: DBU traffic lands on the meter
+> you keep for upstream spend, or vice versa. If one workspace serves both kinds, wrap one client
+> per kind.
+>
+> **Neither recipe reports a `cost`**, on either route — Databricks states no price on any
+> response, in the body or in a header. Reconcile spend against its system tables out of band.
+>
+> Recognised by workspace host **and** serving path: the three public families
+> (`cloud.databricks.com`, `azuredatabricks.net`, `gcp.databricks.com`) crossed with
+> `/serving-endpoints` or `/ai-gateway/mlflow/v1`. The host alone is every Databricks API there is,
+> most of which are not inference. A PrivateLink or custom-DNS workspace matches neither half —
+> give the recipe its base URL: `databricksRecipe({ baseUrl })`.
+>
+> **Both clients, one recipe.** `@databricks/sdk-modelservingquery` is Databricks' own JS client,
+> and its whole surface is one method — `client.query({ name, messages })`, reported as
+> `databricks.query`. It is a second *surface* rather than a second vendor, because one Databricks
+> account is billed whichever client the application imported; splitting it would split one bill
+> across two meters. It is recognised automatically, so `wrap(client)` governs it with no recipe
+> named.
+>
+> Three things are worth knowing before you choose it. It **camelCases the wire** — its generated
+> parser turns `prompt_tokens` into `promptTokens` — so this SDK renames the counters back, and
+> both clients report `prompt_tokens` for the same workspace. It reports **three counters, not
+> six**: its usage type has no cache pair and no `reasoning_tokens`, which are absent rather than
+> zero. And it **cannot stream**, and its request carries no `tools`, `response_format` or
+> `stream_options` — so for real work the OpenAI-compatible route above is still the richer one,
+> and it is what the Databricks docs show.
+>
+> One method serves chat, completions, embeddings and custom-model predictions, so the event name
+> cannot say which ran. The response's own `object` field rides as a `response_object` dimension
+> so a meter can tell them apart.
+
+> **Cloudflare Workers AI is a provider, not a gateway.** Cloudflare runs these models on its own
+> GPUs and invoices them to your Cloudflare account, which is the test this package applies. The
+> `@cf/<author>/<model>` ids look like a reseller's catalogue and are not one — `<author>` is who
+> *made* the weights, not who bills for running them, and `@cf/openai/gpt-oss-120b` is OpenAI's
+> open-weights release at Cloudflare's own per-token rate rather than OpenAI API pricing. (`@hf/…`
+> ids are Workers AI too, and about an eighth of the catalogue, so anything keying on the `@cf/`
+> prefix alone is wrong.)
+>
+> Two clients reach it and both report under `cloudflare`, because one account is billed
+> whichever is held: an `OpenAI` client pointed at
+> `https://api.cloudflare.com/client/v4/accounts/<id>/ai/v1`, and the `cloudflare` package's own
+> client, whose method is `ai.run(model, inputs)`. Two event names, so a meter can tell the wires
+> apart.
+>
+> **It publishes no cost and no neuron count.** Cloudflare bills Workers AI in Neurons and puts a
+> neuron figure on no response at all — not the binding's, not either REST route's — so converting
+> tokens to Neurons needs Cloudflare's per-model rate table, which this SDK does not hold and will
+> not guess at. Tokens are what the response states and tokens are what it reports.
+>
+> ⚠️ **A streamed `ai.run` is gated but not metered.** Asked for a stream, that method hands back
+> the raw SSE byte stream rather than parsed chunks, so there is no object with a `usage` block to
+> read — and the recipe attaches no reader rather than one that would find nothing and report a
+> zero. The call is still checked before it leaves; the measurement afterwards is what is missing.
+> Stream through the OpenAI-compatible route instead, where usage arrives on the final chunk, or
+> call `ai.run` buffered.
+>
+> `ai.run` also carries **no model dimension**, because the model is that method's first argument
+> and an extractor only ever sees the result. Nothing is lost that matters — Workers AI does not
+> route, so what was asked for is what ran — but a meter that wants it can have it from
+> `stiggContext: { dimensions: { model: '@cf/meta/llama-3.1-8b-instruct' } }`.
+>
+> One wrinkle about that hostname: `…/ai/v1` also serves **third-party** models (a bare
+> `author/model` id like `openai/gpt-4.1`) routed through AI Gateway and paid out of Cloudflare
+> credits under Unified Billing. Those land on this recipe, which is defensible rather than a
+> mistake — Cloudflare is the payer either way — and the model is on the response, so a meter that
+> wants them apart can split on it. AI Gateway proper lives on `gateway.ai.cloudflare.com` and has
+> its own recipe.
 
 Client recipes are data — method paths and usage extractors — so the factory wires the built-in
 ones with no vendor package loaded. Nothing in `src/index.ts` pulls a vendor package in at
@@ -980,6 +1085,13 @@ there (or exporting it in your shell) overrides the fixture without editing `dem
 | `AGENT_SDK_BEDROCK_REGION`             | `us-east-1` (falls back to `AWS_REGION`) | Region the Bedrock model is called in. There is no Bedrock key variable: AWS authenticates through its own credential chain, and the example asks that chain rather than looking for one |
 | `AGENT_SDK_BEDROCK_MODEL`              | `anthropic.claude-sonnet-4-5-20250929-v1:0` | Bedrock model id. Names one model exactly — Bedrock does not route, so there is no fallback list                                   |
 | `AGENT_SDK_LITELLM_API_KEY`            | — (falls back to `LITELLM_API_KEY`)      | Layer 2. Blank ⇒ the offline mock                                                                                                    |
+| `AGENT_SDK_CLOUDFLARE_API_KEY`         | none                                     | Cloudflare API token with Workers AI read access (falls back to `CLOUDFLARE_API_TOKEN`)                                              |
+| `AGENT_SDK_CLOUDFLARE_ACCOUNT_ID`      | none                                     | Required by every `ai.run` call — it is part of the URL path, not the body                                                           |
+| `AGENT_SDK_CLOUDFLARE_MODEL`            | `@cf/meta/llama-3.1-8b-instruct`         | A Workers AI model id. `@hf/…` ids are Workers AI too, so a matcher keyed on `@cf/` alone misses about an eighth of the catalogue    |
+| `AGENT_SDK_DATABRICKS_API_KEY`         | — (falls back to `DATABRICKS_TOKEN`)     | A workspace token — a PAT, or an OAuth M2M token. Blank ⇒ the offline mock. Read by both Databricks examples |
+| `AGENT_SDK_DATABRICKS_BASE_URL`        | none                                     | Your workspace — customer-specific, so there is no default that could be right. `/serving-endpoints` is appended if you leave it off, and a PrivateLink workspace works because the recipe is handed this URL rather than recognising the host |
+| `AGENT_SDK_DATABRICKS_MODEL`           | `databricks-claude-sonnet-4-6`           | A serving **endpoint** name, not a model id — which is why the served model has to be read off the response. Read by both Databricks examples |
+| `AGENT_SDK_DATABRICKS_EXTERNAL`        | unset                                    | `1` asserts the endpoint carries your own upstream key, so that provider invoices it rather than Databricks. An assertion the SDK cannot check — it switches both Databricks examples to `databricks-external.*` |
 | `AGENT_SDK_LITELLM_BASE_URL`           | `http://localhost:4000`                  | Your own proxy — self-hosted, so there is no public default                                                                          |
 | `AGENT_SDK_LITELLM_MODEL`              | `gpt-5`                                  | A model **group** from the proxy's config, not a provider slug                                                                       |
 | `STIGG_API_KEY`                        | —                                        | **Server** key (`server-…`). A publishable `client-…` key fails every call with `IdentityForbidden`. Blank ⇒ the built-in Stigg mock |
@@ -1051,11 +1163,14 @@ Stigg account.
 | `example-client-ollama`     | [`client/ollama.ts`](./examples/client/ollama.ts)                     | A self-hosted engine that bills nobody: a flat client, counters flat on the response, and capacity rather than spend        |
 | `example-client-openrouter` | [`client/openrouter.ts`](./examples/client/openrouter.ts)             | `openrouterRecipe()` billing the credits actually charged instead of a token count                          |
 | `example-client-litellm`    | [`client/litellm.ts`](./examples/client/litellm.ts)                   | The same script against a self-hosted proxy. Streams, so it meters tokens — see the gateway example for why |
+| `example-client-databricks` | [`client/databricks.ts`](./examples/client/databricks.ts)             | An `OpenAI` client pointed at a workspace `/serving-endpoints`. The request names an **endpoint**, not a model, so the served model on the way back is the thing to watch. `AGENT_SDK_DATABRICKS_EXTERNAL=1` asserts the external-model route |
 | `example-client-typesafe`   | [`client/typesafe.ts`](./examples/client/typesafe.ts)                 | A non-chat client: typed questions, batched or one per call. **Needs a real TypeSafe key**                  |
 | `example-two-agents`        | [`client/two-agents.ts`](./examples/client/two-agents.ts)             | Two agents, one team: a sibling denied by its own cap, then the survivor denied by the team above it        |
 | `example-gateway-openrouter`| [`gateway/openrouter.ts`](./examples/gateway/openrouter.ts)           | The two gateway topologies: calling one gates, operating one only ingests. `example-gateway` runs this one  |
 | `example-gateway-litellm`   | [`gateway/litellm.ts`](./examples/gateway/litellm.ts)                 | The same two topologies when the cost is in a header: real spend, then tokens, from one request             |
 | `example-gateway-bedrock`   | [`gateway/bedrock.ts`](./examples/gateway/bedrock.ts)                 | A gateway that states no price: tokens are all there is to meter, and nothing proxies it                    |
+| `example-gateway-databricks` | [`gateway/databricks.ts`](./examples/gateway/databricks.ts)          | Databricks' **own** client, `@databricks/sdk-modelservingquery` — one method, `client.query(…)`, governed by the same recipe as the row above and reported as `databricks.query`. Shows the camelCase counters renamed back to the wire's, and a budget draining until it refuses |
+| `example-gateway-cloudflare` | [`gateway/cloudflare.ts`](./examples/gateway/cloudflare.ts)           | Cloudflare's own client (`ai.run`). The one example that does not stream — a streamed `ai.run` hands back raw SSE bytes, so there is no usage block to meter |
 | `example-setup`             | [`shared/setup-governance.ts`](./examples/shared/setup-governance.ts) | Seeds a customer, a pool and per-entity budgets. Idempotent                                                 |
 
 `example-client` is an alias for the Anthropic one. Prefix any of them with `AGENT_SDK_OFFLINE=1`

package/dist/bindings/client/core/types.d.ts

@@ -32,6 +32,15 @@ export type MethodRecipe = {
      * shape offers beyond a promise.
      */
     path: readonly string[];
+    /**
+     * Which argument carries `stiggContext`, when it is not the first.
+     *
+     * Most vendor methods take one options object, so the context rides in argument 0 and this is
+     * left alone. A method whose first argument is not that object needs to say so - Cloudflare's
+     * `ai.run(model, inputs)` names the model first - or a caller's per-call context is forwarded
+     * to the vendor as an unknown field and the gate silently uses the wrap-time one instead.
+     */
+    contextArg?: number;
     /**
      * True when this call is an internal leg of another wrapped method and must not be gated
      * twice. Vendors mark these differently, so only the recipe can tell.

package/dist/bindings/client/core/wrap-client.js

@@ -105,7 +105,10 @@ function patch(copy, source, session, base, method, eventName) {
     owner[key] = function gated(...args) {
         // Whatever the vendor's own signature takes. Naming the first two and forwarding only those
         // would quietly drop the rest of a call the recipe never claimed to reshape.
-        let [params] = args;
+        // Argument 0 unless the method says otherwise: a vendor whose first argument is not its
+        // options object would otherwise have a caller's context forwarded to it verbatim.
+        const contextArg = method.contextArg ?? 0;
+        let params = args[contextArg];
         let context = defaults;
         // The context rides inside the vendor's own parameter object, so it has to come back out
         // before anything - the recipe's own hooks included - ever sees those parameters. Both the
@@ -113,7 +116,7 @@ function patch(copy, source, session, base, method, eventName) {
         if (params?.stiggContext !== undefined) {
             const { stiggContext, ...rest } = params;
             params = rest;
-            args = [rest, ...args.slice(1)];
+            args = args.map((arg, i) => (i === contextArg ? rest : arg));
             context = (0, context_1.overrideContext)(defaults, stiggContext);
         }
         const callOptions = args[1];

package/dist/bindings/client/gateways/cloudflare/cloudflare-recipe.d.ts

@@ -0,0 +1,10 @@
+import { CLOUDFLARE_METRICS } from '../../../shared/token-usage';
+import type { CloudflareRecipeOptions } from './types';
+import type { ClientRecipe, MetricsFor, MetricsOf } from '../../core/types';
+type CloudflareMetric = (typeof CLOUDFLARE_METRICS)[number];
+export declare function cloudflareRecipe(options?: CloudflareRecipeOptions): ClientRecipe<CloudflareMetric>;
+/** One of the metric names Cloudflare can report, across every wire it serves. */
+export type CloudflareMetricName = MetricsOf<ReturnType<typeof cloudflareRecipe>>;
+/** What a mapper reads off a Cloudflare call: those names, each possibly absent. */
+export type CloudflareMetrics = MetricsFor<ReturnType<typeof cloudflareRecipe>>;
+export {};

package/dist/bindings/client/gateways/cloudflare/cloudflare-recipe.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloudflareRecipe = cloudflareRecipe;
+/**
+ * The Cloudflare recipe - one vendor over two products.
+ *
+ * **Workers AI** runs open-weight models on Cloudflare's GPUs, reached as `client.ai.run(...)` or
+ * as an `OpenAI` client at `api.cloudflare.com`. **AI Gateway** fronts somebody else's provider at
+ * `gateway.ai.cloudflare.com/v1/<account>/<gateway>/<provider>` and forwards that provider's body
+ * back untouched. One recipe, because one payer: Cloudflare invoices either way, and the vendor is
+ * whoever bills. Two vendor names would split one account across two meters.
+ *
+ * Filed under gateways although Workers AI alone looks provider-shaped - the same shape
+ * `groqRecipe` is argued from. That is deliberate: the category follows how a platform is sold,
+ * not how it is built. See the positioning section of the `govern-new-platform` skill.
+ *
+ * Two things follow from the gateway forwarding bodies verbatim, and both surprise people:
+ *
+ *  - **Two counter vocabularies under one vendor.** `/openai` reports `prompt_tokens` and
+ *    `/anthropic` reports `input_tokens`, so a meter watching one misses the other. Nothing is
+ *    renamed - a counter has to reconcile against its own upstream's dashboard - so price both,
+ *    or use `normalizedMetrics`. `metrics` is the union, which is what `metrics` is defined to be.
+ *  - **A cache hit is a free call carrying a full `usage` block.** See {@link isCacheHit}: metered
+ *    generically, every hit bills as real usage, and caching is this gateway's headline feature.
+ *
+ * Neither product states a price anywhere, so no `cost` metric is declared and `cf-aig-log-id`
+ * rides as a dimension for out-of-band reconciliation.
+ */
+const meter_stream_1 = require("../../../shared/meter-stream");
+const token_usage_1 = require("../../../shared/token-usage");
+const base_url_1 = require("../../../shared/base-url");
+const registry_1 = require("../../core/registry");
+const openai_recipe_1 = require("../../providers/openai/openai-recipe");
+const anthropic_recipe_1 = require("../../providers/anthropic/anthropic-recipe");
+const types_1 = require("../../../../types");
+/** Workers AI, both of its routes. */
+const CLOUDFLARE_API_HOST = 'api.cloudflare.com';
+/** AI Gateway's public endpoint. A custom domain needs `options.baseUrl` instead. */
+const GATEWAY_HOST = 'gateway.ai.cloudflare.com';
+/** `HIT` means the upstream was never called, so nobody was billed for this. */
+const CACHE_STATUS_HEADER = 'cf-aig-cache-status';
+/** The gateway's own log record, where its (estimated) cost figure can be read afterwards. */
+const LOG_ID_HEADER = 'cf-aig-log-id';
+/** Auto Router's choice, which can differ from the model the request named. */
+const ROUTED_MODEL_HEADER = 'cf-aig-routed-model';
+/** Which fallback step served: `0` is the first provider, anything higher means one failed over. */
+const STEP_HEADER = 'cf-aig-step';
+/** The gateway's own request id, stable across its retries - unlike a local step counter. */
+const REQUEST_ID_HEADER = 'cf-aig-request-id';
+const headerOf = (response, name) => {
+    const raw = response?.headers?.get(name);
+    return raw == null || raw === '' ? undefined : raw;
+};
+/**
+ * Whether the gateway served this from its cache.
+ *
+ * Readable on a streamed response as well as a buffered one, unlike a header-borne *cost*: whether
+ * the cache will answer is known before any token is produced, so this header is on the wire in
+ * time either way. That is the difference between this and `x-litellm-response-cost`, and it is why
+ * the streaming branch below checks it rather than giving up.
+ *
+ * Absent on the Workers AI routes, which have no cache in front of them - so this reads `false`
+ * there and the surfaces behave as ordinary metered calls.
+ */
+const isCacheHit = (response) => headerOf(response, CACHE_STATUS_HEADER)?.toUpperCase() === 'HIT';
+/** What only the gateway knows, folded onto whatever the upstream's own reader produced. */
+function withGatewayFacts(measured, result, response, modelDimension) {
+    const dimensions = { ...measured.dimensions };
+    // The model that actually served: the router's own word for it, falling back to whatever the
+    // forwarded body said. Anthropic's Messages body carries `model` too, so this works on both wires.
+    const served = headerOf(response, ROUTED_MODEL_HEADER) ?? (typeof result?.model === 'string' ? result.model : undefined);
+    if (served)
+        dimensions[modelDimension] = served;
+    // The substitute for a cost metric: the key to the gateway's own record of what this call cost.
+    const logId = headerOf(response, LOG_ID_HEADER);
+    if (logId)
+        dimensions.cf_aig_log_id = logId;
+    // Only when a fallback actually happened. Step `0` is the ordinary case and tagging every event
+    // with it would add a dimension to all of them for no information.
+    const step = headerOf(response, STEP_HEADER);
+    if (step !== undefined && step !== '0')
+        dimensions.cf_aig_step = step;
+    return {
+        ...measured,
+        dimensions: Object.keys(dimensions).length > 0 ? dimensions : undefined,
+        idempotencyKey: headerOf(response, REQUEST_ID_HEADER) ?? measured.idempotencyKey ?? result?.id,
+    };
+}
+/** The Workers AI reader: the three counters it states, under its own (OpenAI's) names. */
+function measure(usage, model, id, modelDimension, keys = token_usage_1.WORKERS_AI_PATHS) {
+    if (!usage)
+        return undefined;
+    return {
+        // Anything absent is absent: a model that reported no counters meters nothing rather than a
+        // row of zeroes.
+        metrics: (0, token_usage_1.pickMetrics)(usage, keys),
+        // The OpenAI reader, because these are the OpenAI counters - and it finds no nested cache
+        // detail here, which is correct, because Workers AI sends none.
+        usage: (0, token_usage_1.fromOpenAIUsage)(usage),
+        raw: usage,
+        dimensions: model ? { [modelDimension]: model } : undefined,
+        idempotencyKey: id,
+    };
+}
+function cloudflareRecipe(options = {}) {
+    const estimate = options.estimate ?? (() => 1);
+    const modelDimension = options.modelDimension ?? 'model';
+    /**
+     * One upstream surface, wrapped.
+     *
+     * The upstream recipes' own extractors are reused rather than reimplemented, which is the point:
+     * AI Gateway forwards the provider's body untouched, so the provider's reader is by definition
+     * the right one - and Anthropic's streamed usage in particular accumulates across two event
+     * types, which is not logic worth having a second copy of. Off the gateway the wrapper is inert:
+     * no `cf-aig-*` header is present, so no cache hit is seen and no gateway dimension is added.
+     */
+    const surfaceOf = (base) => ({
+        // Spread first so anything the base declares and this wrapper does not know about - like
+        // `contextArg`, which says where `stiggContext` rides - survives being wrapped. Rebuilding
+        // the object field by field silently dropped it.
+        ...base,
+        path: base.path,
+        estimate,
+        extractUsage: (result, response) => {
+            // Nobody was invoiced for a cache hit, so nothing is reported for one. Checked before the
+            // body is read at all, because the body of a hit looks exactly like the body of a real call.
+            if (isCacheHit(response))
+                return undefined;
+            const measured = base.extractUsage?.(result, response);
+            return measured === undefined
+                ? undefined
+                : withGatewayFacts((0, types_1.toMeasurement)(measured), result, response, modelDimension);
+        },
+        attachStream: base.attachStream
+            ? (stream, ingest, response) => {
+                // A cached reply can be streamed back too, and the cache header arrives in time to say so.
+                // Nothing is attached at all in that case: the consumer's stream is left untouched and no
+                // measurement is produced, which is what a free call should report.
+                if (isCacheHit(response))
+                    return;
+                // A second tap, purely for attribution. The upstream recipes' stream readers carry out
+                // counters and nothing else, so without this the streamed path had no `result` to fall
+                // back on and a turn with no `cf-aig-routed-model` header lost its model entirely -
+                // where the buffered path reads it straight off the body. Each wire states it in its own
+                // envelope: Anthropic on `message_start.message`, the Responses API on `response`, Chat
+                // Completions at the chunk root. `meterStream` captures what it patches before patching,
+                // so stacking two observers is safe and each sees every chunk exactly once.
+                let seen = {};
+                (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                    const envelope = chunk?.message ?? chunk?.response ?? chunk;
+                    if (envelope?.model)
+                        seen = { ...seen, model: envelope.model };
+                    if (envelope?.id)
+                        seen = { ...seen, id: envelope.id };
+                }, () => { });
+                base.attachStream(stream, (measurement) => ingest(withGatewayFacts((0, types_1.toMeasurement)(measurement), seen, response, modelDimension)), response);
+            }
+            : undefined,
+    });
+    /**
+     * Chat Completions, which both products answer on - Workers AI's OpenAI-compatible route and the
+     * gateway's `/openai` one.
+     *
+     * Its own reader rather than `openAIRecipe`'s, for one reason: the model has to be tracked
+     * across the chunks of a *streamed* turn. The generic reader does not carry it, and off the
+     * gateway there is no `cf-aig-routed-model` header to recover it from - so reusing that reader
+     * would silently drop model attribution on every streamed Workers AI call. The key list is the
+     * full OpenAI one so a gateway-forwarded `cached_tokens` is not dropped either; Workers AI sends
+     * none of those, and absent stays absent.
+     */
+    const chatSurface = {
+        path: ['chat', 'completions', 'create'],
+        extractUsage: (result) => measure(result?.usage, result?.model, result?.id, modelDimension, token_usage_1.METRIC_PATHS.openaiChat),
+        attachStream: (stream, ingest) => {
+            let usage;
+            let model;
+            let id;
+            // The OpenAI recipe's own chunk reader, not a copy of it. AI Gateway forwards whatever the
+            // upstream sent, and an upstream can hide its usage somewhere other than the chunk root -
+            // Groq puts it on `x_groq` and sends no top-level `usage` at all - so reading `chunk.usage`
+            // here would meter a streamed Groq call through this gateway at nothing. Borrowing the
+            // reader keeps every upstream that recipe learns about working through this one too.
+            const readStreamedUsage = (0, openai_recipe_1.openAISurface)(['chat', 'completions', 'create']).streamed;
+            (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                // Stated once and whole on the final chunk rather than as deltas, so the last wins.
+                const streamedUsage = readStreamedUsage(chunk);
+                if (streamedUsage)
+                    usage = streamedUsage;
+                if (chunk?.model)
+                    model = chunk.model;
+                if (chunk?.id)
+                    id = chunk.id;
+            }, () => {
+                const measurement = measure(usage, model, id, modelDimension, token_usage_1.METRIC_PATHS.openaiChat);
+                if (measurement)
+                    ingest(measurement);
+            });
+        },
+    };
+    /**
+     * The `cloudflare` package's own method.
+     *
+     * Two limits live here rather than in the file header, because they are facts about this method.
+     *
+     * It resolves to a **bare promise with no response object**, so no `cf-aig-*` header is reachable
+     * on this route - cache status included. A Workers AI call made this way through a gateway is
+     * metered as an ordinary call even when the gateway served it free. The `OpenAI`-client route
+     * has the headers and does not have this gap.
+     *
+     * And no `attachStream`, deliberately. A streamed `ai.run` resolves to raw SSE bytes
+     * rather than parsed chunks, and a reader attached to those would collect nothing and report it
+     * as a measurement of zero, which is the one failure shape nothing downstream can notice. Gated
+     * and unmetered is the honest outcome, and it is documented rather than discovered.
+     */
+    const aiRun = {
+        path: ['ai', 'run'],
+        // `ai.run(model, inputs)` - the model is argument 0, so the context rides in argument 1. Left
+        // at the default this surface would forward a caller's `stiggContext` to Cloudflare as an
+        // unknown input and gate on the wrap-time context instead, which is the quiet kind of wrong.
+        contextArg: 1,
+        // No model: it was the first argument, and an extractor is handed only the result. No id
+        // either - this surface returns neither, so idempotency falls back to the caller's.
+        extractUsage: (result) => measure(result?.usage, undefined, undefined, modelDimension),
+    };
+    return {
+        vendor: 'cloudflare',
+        metrics: token_usage_1.CLOUDFLARE_METRICS,
+        // Every wire here spells its total `total_tokens` - Anthropic's is computed from its disjoint
+        // counters by the reader this reuses, OpenAI's and Workers AI's are stated.
+        totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+        // The host decides, because shape cannot: an `OpenAI` client and an `Anthropic` client pointed
+        // at either product look exactly like direct clients. `ai.run` is checked as well as the two
+        // shapes because the `cloudflare` package's client has no `chat.completions`.
+        matches: (client) => {
+            const baseUrl = (0, base_url_1.baseUrlOf)(client);
+            if (baseUrl === undefined)
+                return false;
+            const onCloudflare = options.baseUrl
+                ? (0, base_url_1.withinBaseUrl)(options.baseUrl, baseUrl)
+                : (0, base_url_1.matchesHost)(baseUrl, CLOUDFLARE_API_HOST) || (0, base_url_1.matchesHost)(baseUrl, GATEWAY_HOST);
+            if (!onCloudflare)
+                return false;
+            return (0, registry_1.hasMethod)(client, ['ai', 'run']) || openai_recipe_1.openAIRecipe.matches(client) || anthropic_recipe_1.anthropicRecipe.matches(client);
+        },
+        // Every wire it serves. A surface left undeclared here is not metered by something else - it is
+        // ungated, because this recipe is matched ahead of both of the ones that would have claimed it.
+        methods: [
+            surfaceOf(chatSurface),
+            ...openai_recipe_1.openAIRecipe.methods.filter((m) => m.path.join('.') !== 'chat.completions.create').map(surfaceOf),
+            ...anthropic_recipe_1.anthropicRecipe.methods.map(surfaceOf),
+            surfaceOf(aiRun),
+        ],
+    };
+}

package/dist/bindings/client/gateways/cloudflare/types.d.ts

@@ -0,0 +1,35 @@
+export type CloudflareRecipeOptions = {
+    /**
+     * How much to ask permission for before the call, in whatever unit `meter` bills.
+     *
+     * The default asks for 1 - "is there any budget left at all?" - and lets the ingest afterwards
+     * settle the balance. No `unitsPer…` beside it, because there is nothing fractional to
+     * denominate: Cloudflare publishes no price on any response, on either route, so a run here
+     * bills token counters, which arrive whole.
+     *
+     * Worth knowing that a cache hit passes the gate and then meters nothing. That is the right way
+     * round - whether a call will hit the gateway's cache cannot be known before it is made, and a
+     * free call should not be billed afterwards.
+     */
+    estimate?: (params: any) => number;
+    /**
+     * Dimension the model that actually served is attributed to.
+     *
+     * Which model that is depends on the route. Workers AI does not route, so what was asked for is
+     * what ran - and `ai.run` takes the model as its first *argument* and echoes nothing back, so a
+     * turn made that way carries no model dimension at all. Through AI Gateway it really can differ:
+     * Auto Router picks from a candidate pool and names its choice in `cf-aig-routed-model`, and a
+     * fallback chain can serve from a different provider entirely.
+     */
+    modelDimension?: string;
+    /**
+     * The Cloudflare endpoint, when it is not one of the two public ones.
+     *
+     * Workers AI is served from `api.cloudflare.com` and AI Gateway from
+     * `gateway.ai.cloudflare.com/v1/<account>/<gateway>/<provider>`; the matcher recognises both
+     * without being told. The case that needs this is a **custom domain**: a gateway served from
+     * `ai.example.com` has the account and gateway ids stripped out of the path, so nothing in the
+     * URL identifies Cloudflare at all.
+     */
+    baseUrl?: string;
+};

package/dist/bindings/client/gateways/cloudflare/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/bindings/client/gateways/databricks/databricks-recipe.d.ts

@@ -0,0 +1,32 @@
+import { DATABRICKS_METRICS } from '../../../shared/token-usage';
+import type { DatabricksRecipeOptions } from './types';
+import type { ClientRecipe, MetricsFor, MetricsOf } from '../../core/types';
+type DatabricksMetric = (typeof DATABRICKS_METRICS)[number];
+/**
+ * Databricks-hosted inference - Foundation Model APIs, billed to your Databricks account in DBUs.
+ *
+ * Registered by default and matched on the workspace URL, because reading a richer response is not
+ * a pricing decision anyone needs to opt into. What it adds over `openAIRecipe` is a vendor name
+ * and the model that answered, which on this platform is the only thing that says what an endpoint
+ * name meant.
+ */
+export declare const databricksRecipe: (options?: DatabricksRecipeOptions) => ClientRecipe<DatabricksMetric>;
+/**
+ * The external-model route - Databricks proxies, your upstream provider invoices.
+ *
+ * Not registered by default: which route an endpoint serves is server-side configuration, so this
+ * is the caller asserting something about their own workspace rather than the SDK detecting it.
+ * Name it at `wrap(client, { recipe: databricksExternalRecipe() })`, and see the file header for
+ * what a wrong assertion costs.
+ *
+ * `databricks-external` rather than something further from `databricks`: the two sort together in
+ * a meter list, which is what you want when you are reading one account's traffic split across
+ * them, and `external` is Databricks' own word - an endpoint of this kind is configured under an
+ * `external_model` block.
+ */
+export declare const databricksExternalRecipe: (options?: DatabricksRecipeOptions) => ClientRecipe<DatabricksMetric>;
+/** One of the metric names Databricks reports. */
+export type DatabricksMetricName = MetricsOf<ReturnType<typeof databricksRecipe>>;
+/** What a mapper reads off a Databricks call: those names, each possibly absent. */
+export type DatabricksMetrics = MetricsFor<ReturnType<typeof databricksRecipe>>;
+export {};