@stigg/agent-sdk-js 0.0.0-stage → 0.2.0

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 {};

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

@@ -0,0 +1,324 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.databricksExternalRecipe = exports.databricksRecipe = void 0;
+/**
+ * The Databricks recipes - one platform, two payers, and no price on either.
+ *
+ * Databricks speaks the OpenAI wire, so `openAIRecipe` fits both clients by shape. What it cannot
+ * express is identity: on `/serving-endpoints` the `model` argument is a serving *endpoint* name
+ * the customer invented, so `"prod-chat"` may front DBRX, a hosted Llama, or somebody's OpenAI
+ * account - and metered generically it reports as `openai.*` with no dimensions at all. The
+ * response's `model` is what recovers that, and putting it on the ingest is most of why these
+ * recipes exist.
+ *
+ * ## Two recipes, because two parties are invoiced
+ *
+ * Foundation Model APIs are billed by Databricks in DBUs (`databricksRecipe`). An endpoint
+ * configured with your own OpenAI or Anthropic key is billed by that upstream
+ * (`databricksExternalRecipe`).
+ *
+ * **Nothing in the request or response tells them apart** - same host, same path, same wire. The
+ * difference lives in server-side endpoint config, so the split is not detected, it is *asserted*
+ * by naming the second recipe at `wrap`. Assert wrong and nothing throws: DBU traffic lands on
+ * your upstream meter, or upstream traffic on your Databricks one. The event name is the only
+ * durable record of which you asserted, which is why these are two vendors and not one vendor
+ * with a dimension - a meter filter can drop a dimension.
+ *
+ * Only `databricksRecipe` is registered by default; an assertion nobody made is not a default.
+ *
+ * ## No cost, on either route
+ *
+ * Databricks states no price on any response, body or header. DBUs reconcile into
+ * `system.billing.usage` and external spend into `system.ai_gateway.external_model_spend`, both
+ * asynchronously. So `metrics` has no `cost` rather than a zero a mapper would multiply.
+ *
+ * `extractUsage` never sees request parameters, so the endpoint *asked for* cannot be recorded -
+ * only the model that answered. Add it yourself where it matters:
+ * `stiggContext: { dimensions: { endpoint: 'prod-chat' } }`.
+ *
+ * ## Two clients, one recipe
+ *
+ * An `OpenAI` client at the workspace (`chat.completions.create`, `responses.create`, matched on
+ * the URL) and `@databricks/sdk-modelservingquery`, whose entire surface is `client.query(...)`
+ * (`databricks.query`, matched on client shape - see {@link isDatabricksQueryClient} for why, and why its
+ * failure mode is a loud throw).
+ *
+ * One Databricks account is billed whichever the application imported, so they share a vendor and
+ * differ only in event name. The native client is generated and hands the caller `promptTokens`
+ * where the wire said `prompt_tokens`, so it reads through `DATABRICKS_QUERY_METRIC_NAME_MAP` and
+ * reports the wire's names - otherwise one workspace would produce two feature ids from a choice
+ * that has nothing to do with billing. It reports three counters and no cache pair, absent rather
+ * than zero, and does not stream: `query` resolves to a parsed body whose schema rejects SSE.
+ */
+const meter_stream_1 = require("../../../shared/meter-stream");
+const openai_recipe_1 = require("../../providers/openai/openai-recipe");
+const token_usage_1 = require("../../../shared/token-usage");
+const base_url_1 = require("../../../shared/base-url");
+const registry_1 = require("../../core/registry");
+/**
+ * The three public workspace families, one per cloud.
+ *
+ * None is more canonical than the others, which is the difference from a single-host gateway like
+ * OpenRouter: the matcher needs the set. A PrivateLink or custom-DNS workspace is in none of them
+ * and supplies `baseUrl` instead.
+ */
+const WORKSPACE_HOSTS = ['cloud.databricks.com', 'azuredatabricks.net', 'gcp.databricks.com'];
+/**
+ * The two paths a serving endpoint is reached on.
+ *
+ * `/serving-endpoints` is the classic route; `/ai-gateway/mlflow/v1` is the newer Unity Gateway
+ * one. Checked as well as the host because the host families above are shared with every other
+ * Databricks API - a workspace URL alone says "Databricks", not "inference".
+ */
+const SERVING_PATHS = ['/serving-endpoints', '/ai-gateway/mlflow/v1'];
+/**
+ * Which served model answered, from wherever this deployment put it.
+ *
+ * `served-model-name` is documented as a response header and *also* appears in the body - the
+ * official JS client parses it off the payload, the REST reference calls it a header - so both are
+ * read rather than betting on one. It names the served entity behind a traffic-split endpoint,
+ * which is a finer thing than `model`, so it rides as its own dimension when present instead of
+ * overwriting the model identity.
+ */
+function servedEntity(result, response) {
+    const fromBody = result?.['served-model-name'] ?? result?.served_model_name ?? result?.servedModelName;
+    if (typeof fromBody === 'string' && fromBody !== '')
+        return fromBody;
+    const fromHeader = response?.headers?.get('served-model-name');
+    return fromHeader == null || fromHeader === '' ? undefined : fromHeader;
+}
+function measure(usage, model, id, served, modelDimension, keys = token_usage_1.DATABRICKS_PATHS) {
+    if (!usage)
+        return undefined;
+    // Databricks' own six names, verbatim. The first three are always there; the cache pair and
+    // `reasoning_tokens` are Foundation Model API extensions, and `pickMetrics` drops what a given
+    // endpoint did not report rather than reporting it as a zero.
+    const metrics = (0, token_usage_1.pickMetrics)(usage, keys);
+    const dimensions = {};
+    if (model)
+        dimensions[modelDimension] = model;
+    // A finer fact than the model, and only some endpoints have one: which served entity behind a
+    // traffic split answered. Absent for every endpoint that is not split, which is most of them.
+    if (served && served !== model)
+        dimensions.served_model_name = served;
+    return {
+        metrics,
+        usage: (0, token_usage_1.fromDatabricksUsage)(usage),
+        raw: usage,
+        dimensions: Object.keys(dimensions).length > 0 ? dimensions : undefined,
+        // The completion id. Databricks publishes no proxy-level request id on the response the way
+        // LiteLLM does, so this is the best stable key available - it is what a replayed response
+        // would carry again.
+        idempotencyKey: id,
+    };
+}
+/**
+ * The first-party client's one surface. One segment, which is why it is kept out of `GatedPath` -
+ * see `DatabricksGatedPath` in `src/types.ts`.
+ */
+const QUERY_PATH = ['query'];
+/**
+ * The marker that makes `query` safe to claim: the user agent this SDK builds at construction.
+ *
+ * `'sdk-js-' + pkgJson.name.replace(/^@[^/]+\/sdk-/, '')`, so the string names the package.
+ */
+const QUERY_CLIENT_MARKER = 'sdk-js-modelservingquery';
+/**
+ * Whether this is `@databricks/sdk-modelservingquery`'s client.
+ *
+ * Both halves are required. `query` alone is a database client - every Postgres, MySQL, Snowflake
+ * and BigQuery client has one, and claiming them would meter a database call as `databricks.query`.
+ * The marker alone is not callable.
+ *
+ * The awkward part is that this client publishes nothing else: its `.d.ts` declares exactly one
+ * public member, and `options`, `logger`, `userAgent` and `config` are all `private`. So any second
+ * marker is a field the SDK does not publish. `userAgent` is the one chosen because the constructor
+ * sets it unconditionally; `config` was rejected because it is memoised lazily and is `undefined`
+ * until the first request, so a fresh client would not match.
+ *
+ * A future version renaming that field breaks the match, and that cost is acceptable only because
+ * of how it fails: no recipe matches, and `wrap()` throws naming what it supports - loudly, before
+ * one call is metered. Nothing else here claims a bare `query` client, so there is no recipe to
+ * fall through to and no silent mismeter. A caller who hits it names the recipe instead.
+ *
+ * The false-positive direction is the silent one, and it is closed: the marker names the package,
+ * so a wrong claim needs an object exposing `query` *and* advertising this exact SDK.
+ *
+ * Note the two routes are matched on different evidence, deliberately. The OpenAI route is a base
+ * URL, because its client shape says nothing; the native route is shape, because its host sits in
+ * a private field that is often unset anyway - Databricks resolves it from `~/.databrickscfg` or
+ * `DATABRICKS_HOST`. So an `options.baseUrl` given for the OpenAI route does not constrain this
+ * one; there would be nothing to compare against.
+ */
+function isDatabricksQueryClient(client) {
+    if (!(0, registry_1.hasMethod)(client, QUERY_PATH))
+        return false;
+    const agent = client.userAgent;
+    return typeof agent === 'string' && agent.includes(QUERY_CLIENT_MARKER);
+}
+/**
+ * What a `query` response is worth, projected rather than passed through.
+ *
+ * `raw` is built from the renamed counters and **never** from the response, for a harder reason
+ * than Ollama's. `created` is a `bigint`, and `JSON.stringify` throws outright on one - "Do not
+ * know how to serialize a BigInt" - so letting the response reach `raw` or a dimension would not
+ * flatten a reply into event dimensions the way Ollama's would, it would fail the ingest. The
+ * counters are projected explicitly and nothing else crosses.
+ */
+function measureQuery(result, modelDimension) {
+    const usage = result?.usage;
+    if (!usage)
+        return undefined;
+    // Read camelCase, report the wire's snake_case - so this surface and the OpenAI one above
+    // produce the same feature ids for the same workspace. The whole point of the map.
+    const metrics = (0, token_usage_1.pickRenamedMetrics)(usage, token_usage_1.DATABRICKS_QUERY_METRIC_NAME_MAP);
+    if (Object.keys(metrics).length === 0)
+        return undefined;
+    const dimensions = {};
+    const model = typeof result?.model === 'string' ? result.model : undefined;
+    if (model)
+        dimensions[modelDimension] = model;
+    // The same served entity the OpenAI route reads off `served-model-name`; this client exposes it
+    // camelCased, which `servedEntity` already looks for.
+    const served = servedEntity(result, undefined);
+    if (served && served !== model)
+        dimensions.served_model_name = served;
+    // Which of the four workloads behind this one method ran. See the file header.
+    if (typeof result?.object === 'string' && result.object !== '')
+        dimensions.response_object = result.object;
+    return {
+        metrics,
+        usage: (0, token_usage_1.fromDatabricksQueryUsage)(usage),
+        raw: { ...metrics },
+        dimensions: Object.keys(dimensions).length > 0 ? dimensions : undefined,
+        // The completion id, as on the OpenAI route. A string here; `created` beside it is the bigint
+        // and is deliberately never read.
+        idempotencyKey: typeof result?.id === 'string' ? result.id : undefined,
+    };
+}
+/**
+ * One factory, two vendors.
+ *
+ * The recipes are identical in everything but the name they report under, because the traffic
+ * genuinely is identical - see the header. Sharing the body is the point: a divergence between
+ * them would be a claim about a difference the wire does not contain.
+ */
+function databricksRecipeFor(vendor, options) {
+    const estimate = options.estimate ?? (() => 1);
+    const modelDimension = options.modelDimension ?? 'model';
+    return {
+        vendor,
+        metrics: token_usage_1.DATABRICKS_METRICS,
+        // The OpenAI shape it speaks, so the OpenAI name for the total - and Databricks states one,
+        // so it is read rather than computed. Which matters more than usual here: the cache counters
+        // may or may not sit inside `prompt_tokens`, so a computed total could double-count.
+        totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+        // Two clients, two kinds of evidence - see the file header. The first-party client is known by
+        // its own shape; an OpenAI client's shape says nothing, so for that route the base URL is the
+        // discriminator. Neither can separate the two Databricks *routes* from each other - that is
+        // the caller's assertion, not a detection.
+        matches: (client) => isDatabricksQueryClient(client) || (openai_recipe_1.openAIRecipe.matches(client) && isDatabricks(client, options.baseUrl)),
+        // Built from the OpenAI recipe's own surfaces, for the same reason as the OpenRouter and
+        // LiteLLM ones: this recipe is matched ahead of it, so a surface it failed to declare would go
+        // ungated rather than being metered by something else.
+        methods: [
+            // The first-party client. No `attachStream`: `query` has no streamed form - see the header.
+            {
+                path: QUERY_PATH,
+                estimate,
+                extractUsage: (result) => measureQuery(result, modelDimension),
+            },
+            // The OpenAI-wire surfaces, built from the OpenAI recipe's own list.
+            ...openai_recipe_1.openAIRecipe.methods.map((base) => {
+                const { streamed } = (0, openai_recipe_1.openAISurface)(base.path);
+                // Chat Completions and Responses spell the same counters differently, so each surface
+                // reads its own list. Sharing one would leave a Responses call reporting `total_tokens`
+                // alone, with no breakdown under it.
+                const keys = base.path.join('.') === 'responses.create' ? token_usage_1.DATABRICKS_RESPONSES_PATHS : token_usage_1.DATABRICKS_PATHS;
+                return {
+                    path: base.path,
+                    estimate,
+                    extractUsage: (result, response) => measure(result?.usage, result?.model, result?.id, servedEntity(result, response), modelDimension, keys),
+                    // Usage arrives once, at the end, and only when the caller asked for it: Databricks honours
+                    // `stream_options: {include_usage: true}` and defaults it off. A caller who does not ask
+                    // gets a stream that states nothing, and the metrics are then absent rather than zero.
+                    attachStream: (stream, ingest, response) => {
+                        let usage;
+                        let model;
+                        let id;
+                        (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                            // Last write wins. Databricks' own docs disagree with themselves about whether usage
+                            // rides every chunk or only the final one, so this reads it wherever it appears and
+                            // keeps the last - which is correct under either reading.
+                            const seen = streamed(chunk);
+                            if (seen)
+                                usage = seen;
+                            // The Responses API nests its completion event - `{ response: { id, model, usage } }`
+                            // - where Chat Completions puts all three at the chunk root. `streamed()` already
+                            // reaches through for usage; the model and the id are read off the same envelope so
+                            // a streamed Responses turn keeps its attribution and its idempotency key instead
+                            // of falling back to a generated one.
+                            const payload = chunk?.response ?? chunk;
+                            if (payload?.model)
+                                model = payload.model;
+                            if (payload?.id)
+                                id = payload.id;
+                        }, () => {
+                            const measurement = measure(usage, model, id, servedEntity({}, response), modelDimension, keys);
+                            if (measurement)
+                                ingest(measurement);
+                        });
+                    },
+                };
+            }),
+        ],
+    };
+}
+/**
+ * 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.
+ */
+const databricksRecipe = (options = {}) => databricksRecipeFor('databricks', options);
+exports.databricksRecipe = databricksRecipe;
+/**
+ * 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.
+ */
+const databricksExternalRecipe = (options = {}) => databricksRecipeFor('databricks-external', options);
+exports.databricksExternalRecipe = databricksExternalRecipe;
+/**
+ * Whether this client points at a Databricks serving endpoint.
+ *
+ * Given a `baseUrl`, that endpoint and anything beneath it - nothing weaker, because a prefix
+ * match on the raw string lets `.../v1` claim `.../v10`.
+ *
+ * Without one, the guess is narrow on purpose and needs *both* halves: one of the three public
+ * workspace host families, and one of the two serving paths. The host alone is every Databricks
+ * API there is, most of which are not inference and must not be claimed; the path alone would let
+ * any unrelated service that happens to expose `/serving-endpoints` be metered as Databricks. A
+ * PrivateLink workspace satisfies neither half and takes `baseUrl`.
+ */
+function isDatabricks(client, baseUrl) {
+    const clientBase = (0, base_url_1.baseUrlOf)(client);
+    if (clientBase === undefined)
+        return false;
+    if (baseUrl)
+        return (0, base_url_1.withinBaseUrl)(baseUrl, clientBase);
+    if (!(0, base_url_1.matchesAnyHost)(clientBase, WORKSPACE_HOSTS))
+        return false;
+    const path = (0, base_url_1.pathOf)(clientBase);
+    return SERVING_PATHS.some((serving) => path === serving || path.startsWith(`${serving}/`));
+}