@stigg/agent-sdk-js 0.1.0 → 0.2.0

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}/`));
+}

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

@@ -0,0 +1,30 @@
+export type DatabricksRecipeOptions = {
+    /**
+     * 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. There is no `unitsPer…` beside it because there is nothing fractional to
+     * denominate: Databricks states no price on any response, so a run here bills token counters,
+     * which arrive as whole numbers already.
+     */
+    estimate?: (params: any) => number;
+    /**
+     * Dimension the model that actually served is attributed to.
+     *
+     * Worth more here than at most gateways. The request names a serving *endpoint*, which on the
+     * classic route is a string the customer chose and which need not resemble any model id - so
+     * the response's `model` field is frequently the only thing in the whole exchange that says
+     * what answered.
+     */
+    modelDimension?: string;
+    /**
+     * The workspace this recipe is for, as a base URL.
+     *
+     * A Databricks workspace hostname is customer-specific - `<workspace>.cloud.databricks.com`,
+     * `adb-<id>.<n>.azuredatabricks.net`, `<id>.<n>.gcp.databricks.com`, or whatever a PrivateLink
+     * or custom-DNS deployment resolves to. The matcher recognises the three public families and
+     * the two serving paths without being told; a deployment on a private hostname is invisible to
+     * that guess and needs this. Give it the same base URL the client was built with.
+     */
+    baseUrl?: string;
+};

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

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

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

@@ -23,6 +23,7 @@ exports.litellmRecipe = litellmRecipe;
  * self-hosted proxy, to give it the base URL its matcher cannot guess.
  */
 const meter_stream_1 = require("../../../shared/meter-stream");
+const base_url_1 = require("../../../shared/base-url");
 const openai_recipe_1 = require("../../providers/openai/openai-recipe");
 const token_usage_1 = require("../../../shared/token-usage");
 /** The cost LiteLLM charged for this call, in USD. Non-streaming responses only. */
@@ -130,30 +131,16 @@ function litellmRecipe(options = {}) {
  * via `wrap(client, run, { recipe })`.
  */
 function isLiteLLM(client, baseUrl) {
-    const clientBase = client?.baseURL;
-    if (typeof clientBase !== 'string')
+    const clientBase = (0, base_url_1.baseUrlOf)(client);
+    if (clientBase === undefined)
         return false;
     // A prefix match on the raw string lets `.../v1` claim `.../v10`, which is a different
-    // deployment with a different price list. Compare the endpoint, one path segment at a time.
+    // deployment with a different price list. `withinBaseUrl` compares the endpoint, one path
+    // segment at a time.
     if (baseUrl)
-        return within(baseUrl, clientBase);
+        return (0, base_url_1.withinBaseUrl)(baseUrl, clientBase);
     return clientBase.toLowerCase().includes('litellm');
 }
-/** Whether `candidate` is the configured endpoint, or something under it. */
-function within(configured, candidate) {
-    try {
-        const want = new URL(configured);
-        const got = new URL(candidate);
-        if (want.origin !== got.origin)
-            return false;
-        const base = want.pathname.replace(/\/+$/, '');
-        const path = got.pathname.replace(/\/+$/, '');
-        return path === base || path.startsWith(`${base}/`);
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * The denomination, refused when it cannot divide a price.
  *

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

@@ -24,6 +24,7 @@ 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 registry_1 = require("../../core/registry");
+const base_url_1 = require("../../../shared/base-url");
 const sdk_usage_1 = require("./sdk-usage");
 /** Float noise: 0.00108 * 1e6 is 1080.0000000000002, and ceil would bill the extra unit. */
 const toUnits = (cost, unitsPerCredit) => Math.max(1, Math.ceil(Number((cost * unitsPerCredit).toPrecision(12))));
@@ -189,13 +190,10 @@ function openrouterRecipe(options = {}) {
  * endpoint on another host takes the recipe explicitly, via `wrap(client, run, { recipe })`.
  */
 function isOpenRouter(client) {
-    const baseUrl = client?.baseURL;
-    if (typeof baseUrl !== 'string')
-        return false;
+    const baseUrl = (0, base_url_1.baseUrlOf)(client);
     // The host, not a substring of the URL: `openrouter.ai.example.com` is somebody else's domain,
     // and claiming it would meter an unrelated client as a gateway.
-    const host = hostOf(baseUrl);
-    return host === 'openrouter.ai' || host.endsWith('.openrouter.ai');
+    return baseUrl !== undefined && (0, base_url_1.matchesHost)(baseUrl, 'openrouter.ai');
 }
 /**
  * Whether this is OpenRouter's own SDK client, which carries no base URL to recognise it by.
@@ -218,15 +216,6 @@ function isOpenRouterSdk(client) {
         return false;
     return 'credits' in client && 'generations' in client;
 }
-/** The hostname, lowercased, or '' when the URL is not one this can reason about. */
-function hostOf(url) {
-    try {
-        return new URL(url).hostname.toLowerCase();
-    }
-    catch {
-        return '';
-    }
-}
 /**
  * The denomination, refused when it cannot divide a price.
  *

package/dist/bindings/client/providers/groq/groq-recipe.js

@@ -51,23 +51,9 @@ exports.groqRecipe = void 0;
  */
 const token_usage_1 = require("../../../shared/token-usage");
 const openai_recipe_1 = require("../openai/openai-recipe");
+const base_url_1 = require("../../../shared/base-url");
 /** The one surface Groq serves, as the OpenAI recipe addresses it. */
 const CHAT_PATH = ['chat', 'completions', 'create'];
-/**
- * The hostname, lowercased, or '' when the URL is not one this can reason about.
- *
- * Duplicated from the gateway recipes rather than shared, as they duplicate it from each other -
- * three lines, and hoisting it would put a URL helper in the shared vocabulary file, which is
- * about counters.
- */
-function hostOf(url) {
-    try {
-        return new URL(url).hostname.toLowerCase();
-    }
-    catch {
-        return '';
-    }
-}
 /**
  * `baseURL` is a public field on both clients that reach Groq, and the only thing that says which
  * vendor is on the other end.
@@ -80,11 +66,8 @@ function hostOf(url) {
  * `wrap(client, { recipe: groqRecipe })` to attribute such a client to Groq explicitly.
  */
 function isGroq(client) {
-    const baseUrl = client?.baseURL;
-    if (typeof baseUrl !== 'string')
-        return false;
-    const host = hostOf(baseUrl);
-    return host === 'api.groq.com' || host.endsWith('.api.groq.com');
+    const baseUrl = (0, base_url_1.baseUrlOf)(client);
+    return baseUrl !== undefined && (0, base_url_1.matchesHost)(baseUrl, 'api.groq.com');
 }
 exports.groqRecipe = {
     vendor: 'groq',

package/dist/bindings/shared/base-url.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Reading a client's `baseURL`, which is the only thing that says which vendor is on the far end.
+ *
+ * Shape cannot answer that question: every OpenAI-compatible endpoint has the same methods, so
+ * `matches` falls back to the URL, and a wrong answer there does not throw - it silently meters
+ * one vendor's traffic under another vendor's name and bills the wrong party. That is what makes
+ * these few lines the most consequential ones in a binding, and why they live in one place rather
+ * than being written out per recipe.
+ *
+ * The subdomain rule below is the part worth getting exactly right, and the part a hand-written
+ * copy tends to get wrong. Five recipes match on a host - Groq, OpenRouter, LiteLLM, Databricks
+ * and Cloudflare - and two of them need a *set* of host suffixes rather than one, with Databricks
+ * needing the path as well, because its host families cover every Databricks API and most of them
+ * are not inference.
+ *
+ * This is deliberately not in `token-usage.ts`. That file is the vocabulary of what a response
+ * counts, and a hostname is not a counter.
+ */
+/** The hostname, lowercased, or '' when the URL is not one this can reason about. */
+export declare function hostOf(url: string): string;
+/** The path, lowercased and without trailing slashes, or '' when the URL will not parse. */
+export declare function pathOf(url: string): string;
+/**
+ * Whether a URL is served by `expected` or a subdomain of it.
+ *
+ * The dot is the whole point. A substring test lets `api.vendor.com.attacker.net` through, and an
+ * `endsWith` without it lets `notvendor.com` match `vendor.com` - both are somebody else's domain,
+ * and claiming either attributes their traffic to this vendor.
+ */
+export declare function matchesHost(url: string, expected: string): boolean;
+/**
+ * The same test against several hosts, for a platform that serves one product from more than one
+ * domain - Databricks has a hostname per cloud, and none of them is more canonical than the rest.
+ */
+export declare function matchesAnyHost(url: string, expected: readonly string[]): boolean;
+/**
+ * Whether `candidate` is the configured endpoint, or something underneath it.
+ *
+ * A prefix match on the raw string lets `.../v1` claim `.../v10`, which is a different deployment
+ * with a different price list. Compare the origin, then the path one whole segment at a time.
+ */
+export declare function withinBaseUrl(configured: string, candidate: string): boolean;
+/** A client's configured base URL, when it has one this can read. */
+export declare function baseUrlOf(client: unknown): string | undefined;

package/dist/bindings/shared/base-url.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Reading a client's `baseURL`, which is the only thing that says which vendor is on the far end.
+ *
+ * Shape cannot answer that question: every OpenAI-compatible endpoint has the same methods, so
+ * `matches` falls back to the URL, and a wrong answer there does not throw - it silently meters
+ * one vendor's traffic under another vendor's name and bills the wrong party. That is what makes
+ * these few lines the most consequential ones in a binding, and why they live in one place rather
+ * than being written out per recipe.
+ *
+ * The subdomain rule below is the part worth getting exactly right, and the part a hand-written
+ * copy tends to get wrong. Five recipes match on a host - Groq, OpenRouter, LiteLLM, Databricks
+ * and Cloudflare - and two of them need a *set* of host suffixes rather than one, with Databricks
+ * needing the path as well, because its host families cover every Databricks API and most of them
+ * are not inference.
+ *
+ * This is deliberately not in `token-usage.ts`. That file is the vocabulary of what a response
+ * counts, and a hostname is not a counter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hostOf = hostOf;
+exports.pathOf = pathOf;
+exports.matchesHost = matchesHost;
+exports.matchesAnyHost = matchesAnyHost;
+exports.withinBaseUrl = withinBaseUrl;
+exports.baseUrlOf = baseUrlOf;
+/** The hostname, lowercased, or '' when the URL is not one this can reason about. */
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
+/** The path, lowercased and without trailing slashes, or '' when the URL will not parse. */
+function pathOf(url) {
+    try {
+        return new URL(url).pathname.toLowerCase().replace(/\/+$/, '');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Whether a URL is served by `expected` or a subdomain of it.
+ *
+ * The dot is the whole point. A substring test lets `api.vendor.com.attacker.net` through, and an
+ * `endsWith` without it lets `notvendor.com` match `vendor.com` - both are somebody else's domain,
+ * and claiming either attributes their traffic to this vendor.
+ */
+function matchesHost(url, expected) {
+    const host = hostOf(url);
+    const want = expected.toLowerCase();
+    if (!host || !want)
+        return false;
+    return host === want || host.endsWith(`.${want}`);
+}
+/**
+ * The same test against several hosts, for a platform that serves one product from more than one
+ * domain - Databricks has a hostname per cloud, and none of them is more canonical than the rest.
+ */
+function matchesAnyHost(url, expected) {
+    return expected.some((host) => matchesHost(url, host));
+}
+/**
+ * Whether `candidate` is the configured endpoint, or something underneath it.
+ *
+ * A prefix match on the raw string lets `.../v1` claim `.../v10`, which is a different deployment
+ * with a different price list. Compare the origin, then the path one whole segment at a time.
+ */
+function withinBaseUrl(configured, candidate) {
+    try {
+        const want = new URL(configured);
+        const got = new URL(candidate);
+        if (want.origin !== got.origin)
+            return false;
+        const base = want.pathname.replace(/\/+$/, '');
+        const path = got.pathname.replace(/\/+$/, '');
+        return path === base || path.startsWith(`${base}/`);
+    }
+    catch {
+        return false;
+    }
+}
+/** A client's configured base URL, when it has one this can read. */
+function baseUrlOf(client) {
+    const configured = client?.baseURL;
+    return typeof configured === 'string' ? configured : undefined;
+}