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

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

@@ -0,0 +1,12 @@
+/**
+ * Which recipe fits a given client.
+ *
+ * Recipes are matched by the shape of the client rather than by a name the caller has to supply,
+ * so `wrap()` takes one argument and adding a provider is a registry entry - core never learns
+ * about a vendor. An unmatched client fails loudly and names what is supported, because a silent
+ * no-op here would mean a client that quietly meters nothing.
+ */
+import type { ClientRecipe, ClientRegistry } from './types';
+export declare function createClientRegistry(recipes?: ClientRecipe[]): ClientRegistry;
+/** True when every segment of the path exists on the client and the last one is callable. */
+export declare function hasMethod(client: unknown, path: readonly string[]): boolean;

package/dist/bindings/client/core/registry.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClientRegistry = createClientRegistry;
+exports.hasMethod = hasMethod;
+function createClientRegistry(recipes = []) {
+    const entries = [...recipes];
+    return {
+        register: (recipe) => {
+            entries.push(recipe);
+        },
+        find: (client) => entries.find((recipe) => recipe.matches?.(client) ?? false),
+        vendors: () => entries.map((recipe) => recipe.vendor),
+    };
+}
+/** True when every segment of the path exists on the client and the last one is callable. */
+// `readonly`, because the paths a caller has to hand are a recipe's own - and `MethodRecipe.path`
+// is readonly so a literal tuple survives assignment. Taking a mutable array made the exported
+// guard unusable with the exported type.
+function hasMethod(client, path) {
+    const target = path.reduce((node, key) => (node == null ? node : node[key]), client);
+    return typeof target === 'function';
+}

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

@@ -0,0 +1,126 @@
+/**
+ * What a client binding needs to know about one vendor - and nothing more.
+ *
+ * Everything vendor-specific lives in a recipe: which methods to gate, how to read usage off a
+ * response, how a streamed response reports it later. The wrapper itself stays generic, so a new
+ * provider is a recipe file rather than a second copy of the gate.
+ */
+import type { Measurement, TokenUsage } from '../../../types';
+/**
+ * Just enough of a fetch `Response` for a recipe that has to read a header off it.
+ *
+ * Structural on purpose: core must not depend on a vendor's response class, nor on the DOM lib.
+ * Most vendors put everything a meter needs in the body, but not all - LiteLLM computes the cost
+ * and reports it beside the body, in `x-litellm-response-cost`, so a body-only extractor cannot
+ * see the one number that matters.
+ */
+export type MeteredResponse = {
+    headers?: {
+        get: (name: string) => string | null;
+    };
+};
+/** A single method to gate, addressed by its property path from the client root. */
+export type MethodRecipe = {
+    /**
+     * e.g. `['messages', 'create']` - the owner object is everything but the last segment.
+     *
+     * The method must return the vendor's request promise - an `APIPromise`, in both SDKs' terms:
+     * a promise that also offers `asResponse()` and `withResponse()`. The gate cannot hand over the
+     * vendor's own object, because the check it runs first is asynchronous and the object does not
+     * exist until it has passed, so it returns a stand-in shaped like one. A method that returns
+     * anything else - a paginated list, a stream helper, a bare value - would lose whatever that
+     * 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.
+     */
+    passthrough?: (params: any, options: any) => boolean;
+    /** Units to ask for before the call. Defaults to 1 - "is there any budget left at all?". */
+    estimate?: (params: any) => number;
+    /**
+     * Read straight off a completed response. Undefined when the result is a stream.
+     *
+     * `response` is the transport response the body came in on, for the vendors that report spend
+     * in a header rather than in the body. It is absent when the client's promise exposes no
+     * `withResponse()`, so a recipe that needs it must say what it does without it.
+     */
+    extractUsage?: (result: any, response?: MeteredResponse) => TokenUsage | Measurement | undefined;
+    /**
+     * Hooks a result that reports usage later. Wrap the iterator in place and call `ingest` once
+     * the stream completes, so one completed response emits exactly one measurement.
+     */
+    attachStream?: (result: any, ingest: (measurement: TokenUsage | Measurement) => void, response?: MeteredResponse) => void;
+    /**
+     * The event name for this call, when async ingest should report it as something other than the
+     * derived `vendor.path` - a proxy standing in for another vendor's API, say.
+     */
+    event?: string;
+};
+export type ClientRecipe<M extends string = string> = {
+    vendor: string;
+    /**
+     * The *name* of whichever metric is this vendor's total - not the number, which rides the
+     * measurement as `TokenUsage.total`.
+     *
+     * Declared rather than inferred, because the name differs per vendor - `totalTokenCount` for
+     * Gemini, `total_tokens` for everyone else - and a caller pricing metrics otherwise has no way
+     * to tell the total apart from the counters underneath it except by knowing each vendor by
+     * heart. Which matters: billing this *and* a component double-charges those tokens.
+     *
+     * Absent for a vendor that publishes no total and whose counters overlap, where there is
+     * nothing honest to put here.
+     */
+    totalTokensMetric?: M;
+    /**
+     * Every metric name this recipe can report, across all of its surfaces.
+     *
+     * What a mapper of your own can price, and what `weightedMetrics` types its table against. The
+     * union rather than one list per surface: a client speaks whichever API it likes, and a table
+     * covering both prices either - a name the call did not report is simply absent.
+     */
+    metrics: readonly M[];
+    methods: MethodRecipe[];
+    /**
+     * Duck-typed guard: does this recipe fit that client? Lets `wrap(client)` take one argument
+     * instead of asking the caller to name a vendor it can see for itself.
+     */
+    matches?: (client: unknown) => boolean;
+};
+/** The metric names a recipe reports, for naming the union without repeating it. */
+export type MetricsOf<R> = R extends ClientRecipe<infer M> ? M : never;
+/**
+ * What a mapper reads for that recipe: its metric names, each possibly absent.
+ *
+ * Partial because a counter the response did not carry is missing rather than zero - a vendor
+ * reports cache reads only when there were some. Each client binding exports this ready-made for
+ * its own vendor, so a hand-written mapper names the shape instead of building it.
+ */
+export type MetricsFor<R> = Partial<Record<MetricsOf<R>, number>>;
+/** The set of recipes a client can be matched against. */
+export interface ClientRegistry {
+    register(recipe: ClientRecipe): void;
+    find(client: unknown): ClientRecipe | undefined;
+    vendors(): string[];
+}
+/**
+ * What one call is called, for the event an async ingest reports.
+ *
+ * The vendor's own words for its own call - `anthropic.messages.create` - because the name is not
+ * an internal label: a Stigg raw-events meter filters on it, so it has to be something whoever
+ * configures that meter would recognise and could have guessed. Derived from what the recipe
+ * already declares, so a new binding names its events by existing.
+ */
+export declare const eventNameFor: (recipe: {
+    vendor: string;
+}, method: MethodRecipe) => string;

package/dist/bindings/client/core/types.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventNameFor = void 0;
+/**
+ * What one call is called, for the event an async ingest reports.
+ *
+ * The vendor's own words for its own call - `anthropic.messages.create` - because the name is not
+ * an internal label: a Stigg raw-events meter filters on it, so it has to be something whoever
+ * configures that meter would recognise and could have guessed. Derived from what the recipe
+ * already declares, so a new binding names its events by existing.
+ */
+const eventNameFor = (recipe, method) => method.event ?? `${recipe.vendor}.${method.path.join('.')}`;
+exports.eventNameFor = eventNameFor;

package/dist/bindings/client/core/wrap-client.d.ts

@@ -0,0 +1,6 @@
+import { type ResolvedContext } from '../../../core/context';
+import type { GovernanceSession } from '../../../core/session';
+import type { ClientRecipe } from './types';
+export declare function wrapClient<T extends object>(client: T, recipe: ClientRecipe, session: GovernanceSession, context: ResolvedContext): T;
+/** Whether this client is one `wrap(...)` handed back. */
+export declare function isGoverned(client: object): boolean;

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

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapClient = wrapClient;
+exports.isGoverned = isGoverned;
+/**
+ * The client binding: a drop-in wrapper that gates before the call and meters after it.
+ *
+ * Two properties matter and pull in opposite directions. Metering must never break the caller's
+ * call, so ingest failures are swallowed into `onError`. Enforcement must never be swallowed, so
+ * a denial is raised. They are deliberately separate code paths here: a failed check becomes a
+ * policy decision, never an accidental "allowed".
+ *
+ * Methods are patched onto a copy rather than proxied or subclassed: a Proxy needs a nested proxy
+ * per namespace and has to keep `this` intact for helpers that re-enter the client, and
+ * subclassing breaks on the next SDK release. The copy is what leaves `wrap()`; the object the
+ * caller built is never mutated, so it keeps working ungoverned.
+ *
+ * ## The per-call context, and why it is read the way it is
+ *
+ * A gated call sits directly in front of a network request the application pays for, so the SDK's
+ * own work has to disappear next to it. The hot path below does exactly this much when a call
+ * carries no `stiggContext`: one property read and one truthiness test. Nothing is destructured,
+ * merged, validated or allocated - the context `wrap` resolved is used as it stands.
+ */
+const errors_1 = require("../../../errors");
+const context_1 = require("../../../core/context");
+const types_1 = require("../../../types");
+const types_2 = require("./types");
+const WRAPPED = Symbol.for('stigg.agent-sdk.wrapped');
+function wrapClient(client, recipe, session, context) {
+    const already = client[WRAPPED];
+    if (already) {
+        throw new Error(`This client is already governed (${already}). Wrap the client you built, not one that ` +
+            '`wrap(...)` handed back - the context travels with each call, so one wrapped client ' +
+            'already serves every customer and agent.');
+    }
+    const copy = Object.create(client);
+    let patched = 0;
+    for (const method of recipe.methods) {
+        if (patch(copy, client, session, context, method, (0, types_2.eventNameFor)(recipe, method)))
+            patched += 1;
+    }
+    // A recipe whose paths resolve to nothing produces a client that is stamped, looks governed,
+    // and gates nothing - the same outcome `wrap` already refuses when no recipe matches at all,
+    // reached by a different road. Partial is fine and expected: `openAIRecipe` declares both
+    // surfaces because one client can speak either, and a client built for one has no other.
+    if (!patched) {
+        throw new Error(`The ${recipe.vendor} recipe gates ${recipe.methods.map((m) => m.path.join('.')).join(', ')}, and this ` +
+            'client has none of them. Nothing would be checked or metered, so this is refused rather ' +
+            'than handed back looking governed. Check the recipe matches the client you passed.');
+    }
+    Object.defineProperty(copy, WRAPPED, { value: recipe.vendor, enumerable: false });
+    return copy;
+}
+/** Whether this client is one `wrap(...)` handed back. */
+function isGoverned(client) {
+    return client[WRAPPED] !== undefined;
+}
+/**
+ * Gives the copy its own objects along one gated path.
+ *
+ * `Object.create(client)` alone is not enough: the copy would *inherit* `messages`, so patching
+ * `copy.messages.create` would write straight into the namespace the original shares. Only the
+ * objects on a gated path are copied; everything else is inherited, so a namespace the vendor
+ * builds lazily still resolves.
+ */
+function ownPath(copy, source, path) {
+    let owner = copy;
+    let realOwner = source;
+    for (const key of path) {
+        const next = realOwner?.[key];
+        if (next === null || typeof next !== 'object')
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(owner, key)) {
+            Object.defineProperty(owner, key, {
+                value: Object.create(next),
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        owner = owner[key];
+        realOwner = next;
+    }
+    return { owner, realOwner };
+}
+function patch(copy, source, session, base, method, eventName) {
+    const resolved = ownPath(copy, source, method.path.slice(0, -1));
+    if (!resolved)
+        return false;
+    const { owner, realOwner } = resolved;
+    const key = method.path[method.path.length - 1];
+    const original = realOwner?.[key];
+    if (typeof original !== 'function')
+        return false;
+    // How much to ask permission for before the call - Stigg's `requestedUsage`. The recipe owns
+    // it: only the adapter can read a cost off that vendor's own parameters. Defaults to 1,
+    // "is there any budget left at all?" - the ingest afterwards is what makes the balance right.
+    const estimate = method.estimate ?? (() => 1);
+    // Folded in once per method rather than per call. The event name is the only part of a context
+    // that depends on which method was gated - it is what a Stigg meter filters on, and one client
+    // can reach two APIs a meter should be able to tell apart - so resolving it here is what lets
+    // the common call read a context with nothing left to decide.
+    const defaults = base.eventName ? base : { ...base, eventName: { name: 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.
+        // 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
+        // copy and the merge happen only for a call that actually carried one.
+        if (params?.stiggContext !== undefined) {
+            const { stiggContext, ...rest } = params;
+            params = rest;
+            args = args.map((arg, i) => (i === contextArg ? rest : arg));
+            context = (0, context_1.overrideContext)(defaults, stiggContext);
+        }
+        const callOptions = args[1];
+        // The vendor's own object is the receiver, never the copy: an SDK method reading a private
+        // field off `this` would throw on an object that only delegates to the real one.
+        const target = realOwner;
+        if (method.passthrough?.(params, callOptions)) {
+            return original.apply(target, args);
+        }
+        const settled = (async () => {
+            // The one field a call cannot proceed without, refused here rather than three frames down.
+            // `wrap` deliberately allows a client with no customer - its calls each name their own, and
+            // the types say which still owe one - but a type is not a guarantee at runtime, and a
+            // framework that owns the call site cannot satisfy one. Left to reach the engine, the empty
+            // id comes back as a verdict about a customer that is not there, worded as confidently as
+            // any other and attributed to nobody.
+            //
+            // Inside the async body on purpose: this method stands in for the vendor's, which returns a
+            // promise, so a caller's `.catch()` has to see this the way it sees a denial.
+            if (!context.customerId)
+                throw (0, context_1.noCustomer)();
+            // The context owns the check policy; this only decides how much to ask for. A context that
+            // names no entitlement has nothing to ask against, so the gate is skipped outright rather
+            // than asked and ignored: `estimate` is the recipe reading the caller's own parameters, and
+            // paying for one per call to throw the answer away is not what metering-only promises - nor
+            // would a client whose every call checked still report the `checks: 0` an operator reads.
+            if ((0, context_1.isEnforced)(context)) {
+                const decision = await session.check(context, requestedUnits(estimate, params));
+                // No return path here for a structured refusal - the vendor's signature owns the return
+                // type - so this is the one place the SDK raises instead of returning a decision.
+                if (!decision.hasAccess)
+                    throw new errors_1.AccessDeniedError(decision);
+            }
+            const result = await collect(original.apply(target, args), params);
+            // Whatever the recipe reports - tokens for most vendors, real spend plus the model that
+            // served it for one that knows better. The wrapper stays out of that judgement.
+            const ingest = (measured) => {
+                const measurement = (0, types_1.toMeasurement)(measured);
+                void session.ingestMeasurement(context, measurement);
+                // Reported what it could, and said what it could not. A measurement that does not cover
+                // everything the vendor charged for is a metering failure even though the ingest itself
+                // succeeded - so it goes out *and* is raised, rather than one or the other.
+                if (measurement.incomplete)
+                    session.failedToMeasure(context, new Error(measurement.incomplete));
+            };
+            try {
+                const measurement = method.extractUsage?.(result.data, result.response);
+                if (measurement)
+                    ingest(measurement);
+                else
+                    method.attachStream?.(result.data, ingest, result.response);
+            }
+            catch (err) {
+                // The vendor already answered. A recipe that cannot read its response is a metering
+                // failure, not the caller's - turning it into a rejection would fail a call that worked.
+                session.failedToMeasure(context, err);
+            }
+            return result;
+        })();
+        // Marks the inner promise handled; the stand-in below still surfaces the rejection to callers.
+        settled.catch(() => undefined);
+        return gatedPromise(settled);
+    };
+    return true;
+}
+/**
+ * How much to ask permission for, with the one answer a gate must never send.
+ *
+ * `estimate` is the application's own callback - a gateway recipe takes it as an option - and a
+ * negative one is worse than a wrong one: `remaining >= requestedUsage` is true at any balance,
+ * so an unaffordable call is granted by a budget that had nothing left. `NaN` and `Infinity` fail
+ * the same comparison in the other direction. Zero and fractions are left alone: a credit
+ * currency is spent in fractions, and asking for nothing is a legitimate "may I at all".
+ */
+function requestedUnits(estimate, params) {
+    const units = estimate(params);
+    return Number.isFinite(units) && units >= 0 ? units : 1;
+}
+/**
+ * Awaits the vendor's own promise, keeping the caller's response readable where it can.
+ *
+ * A body can be read once, and the recipes need it parsed to find usage in - so a gated call used
+ * to hand `asResponse()` a response nobody could read afterwards. `asResponse()` gives the
+ * response over before anything has touched it, which is early enough to take a copy: the SDK
+ * parses the original exactly as it always did, and the untouched clone is what the caller gets.
+ *
+ * Not for a stream, whose body *is* the stream - copying it would tee an open connection into
+ * memory. Nothing is lost there, because a stream is metered off its own events rather than off
+ * the response.
+ */
+async function collect(pending, params) {
+    if (typeof pending?.withResponse !== 'function')
+        return { data: await pending };
+    // Only a promise that hands over the unparsed response can be copied, and only a body that is
+    // not itself a stream is worth copying.
+    const spare = params?.stream ? undefined : await spareResponse(pending);
+    // `withResponse()` after the copy, so the vendor still supplies its own request id alongside
+    // the parse rather than this having to guess which header it came from.
+    return { ...(await pending.withResponse()), spare };
+}
+async function spareResponse(pending) {
+    if (typeof pending.asResponse !== 'function')
+        return undefined;
+    const response = await pending.asResponse();
+    // The request parameter says what was asked for; the response says what was sent, and only the
+    // second is worth trusting with an open connection. A stream is an event stream, and teeing one
+    // would buffer a live body to serve a copy nobody asked for.
+    if (String(response?.headers?.get?.('content-type') ?? '').includes('event-stream'))
+        return undefined;
+    return typeof response?.clone === 'function' && response.bodyUsed === false ? response.clone() : undefined;
+}
+/**
+ * A real promise, because the gate has to return one before the vendor's exists.
+ *
+ * The check is asynchronous and the vendor is not called until it passes, so at the moment the
+ * caller receives a value there is nothing yet to hand over. What stands in is a `Promise`
+ * subclass carrying the helpers the vendor's own promise declares - a plain object with a `then`
+ * is not a promise: `instanceof Promise` is false on it, and everything past `then`/`catch`
+ * silently does not exist despite the type saying otherwise.
+ */
+class GatedPromise extends Promise {
+    // `then` must hand back a plain promise. The default builds another of these through the
+    // constructor, which has no settled result to hang the helpers off.
+    static get [Symbol.species]() {
+        return Promise;
+    }
+}
+function gatedPromise(settled) {
+    const promise = new GatedPromise((resolve, reject) => {
+        settled.then((result) => resolve(result.data), reject);
+    });
+    // A caller that only wants the response asks `withResponse()` and never touches this one -
+    // Anthropic's stream helper does exactly that. Left alone, a refusal would reject a promise
+    // nobody is holding, which Node reports as unhandled and, by default, exits on. Marking it
+    // handled costs nothing: the rejection is still delivered to whoever does await it.
+    promise.catch(() => undefined);
+    // The copy is ours; the caller is handed it in place of the response the parse consumed.
+    promise.asResponse = () => settled.then((result) => result.spare ?? result.response);
+    promise.withResponse = () => settled.then(({ spare: _spare, ...rest }) => rest);
+    promise._thenUnwrap = (transform) => gatedPromise(settled.then((result) => ({ ...result, data: transform(result.data, result) })));
+    return promise;
+}

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

@@ -0,0 +1,17 @@
+import { BEDROCK_METRICS } from '../../../shared/token-usage';
+import type { BedrockRecipeOptions } from './types';
+import type { ClientRecipe, MetricsFor, MetricsOf } from '../../core/types';
+type BedrockMetric = (typeof BEDROCK_METRICS)[number];
+/**
+ * One recipe for every model Bedrock serves.
+ *
+ * Converse normalizes Anthropic, Nova, Llama and the rest to one request and one response, so the
+ * usage block never changes shape - which is the whole reason this can be a single recipe rather
+ * than one per upstream vendor.
+ */
+export declare function bedrockRecipe(options?: BedrockRecipeOptions): ClientRecipe<BedrockMetric>;
+/** One of the metric names Bedrock reports. */
+export type BedrockMetricName = MetricsOf<ReturnType<typeof bedrockRecipe>>;
+/** What a mapper reads off a Bedrock call: those names, each possibly absent. */
+export type BedrockMetrics = MetricsFor<ReturnType<typeof bedrockRecipe>>;
+export {};

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

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bedrockRecipe = bedrockRecipe;
+/**
+ * The Bedrock recipe - a gateway whose client is a command bus, and which never states a price.
+ *
+ * Bedrock is the third shape of "gateway" these bindings cover, and it differs from the other two
+ * in both halves:
+ *
+ *   - **The client is not a method tree.** `openai-node` and `@openrouter/sdk` hang a method off a
+ *     namespace - `chat.completions.create`, `chat.send` - and a recipe names that path. The AWS
+ *     SDK has exactly one method, `send`, and the operation is the *argument*: `send(new
+ *     ConverseCommand(...))`. So the gated path is `['send']` and the recipe has to look at what
+ *     it was handed, because the same method also lists async invocations and fetches guardrails,
+ *     and gating those would charge a budget for calls that spend nothing.
+ *
+ *   - **There is no cost on the response.** OpenRouter writes the credits it charged into the
+ *     body; LiteLLM prices every call and puts dollars in a header. Bedrock reports tokens and
+ *     stops - the price lives in the AWS bill, not in the response - so a run that wants to bill
+ *     real spend cannot do it here, and one that wants to meter tokens is served exactly as well
+ *     as anywhere else. `metrics` says so by having no `cost` in it, rather than by reporting a
+ *     zero that a mapper would happily multiply.
+ *
+ * There is no served-model dimension either, and that absence is also a fact about Bedrock rather
+ * than an omission: it does not route. You name a model id and that model answers, so there is no
+ * drift between what was asked for and what served, and nothing for a dimension to tell you.
+ */
+const meter_stream_1 = require("../../../shared/meter-stream");
+const token_usage_1 = require("../../../shared/token-usage");
+/** The service a command belongs to, as the AWS SDK's own schema spells it. */
+const BEDROCK_SERVICE = 'com.amazonaws.bedrockruntime';
+/**
+ * The two operations that run inference through the Converse API, and so the two worth gating.
+ *
+ * `InvokeModel` is inference too, and is deliberately not here: its request and response bodies
+ * are the *upstream vendor's* - Anthropic's shape for a Claude model, Amazon's for a Nova one - so
+ * one reader cannot meter them, and a recipe that gated the call while measuring nothing would
+ * report every one of them as a metering failure. An application on `InvokeModel` wants a recipe
+ * per upstream; an application on Converse gets one that works for every model Bedrock serves.
+ */
+const METERED_OPERATIONS = new Set(['Converse', 'ConverseStream']);
+/**
+ * Which AWS operation a command object is for.
+ *
+ * Read off the SDK's own serialization schema - `[version, service, operation, http]` - rather
+ * than from the class name, because a class name is the first thing a bundler rewrites and this
+ * decides whether a call is gated at all. The constructor name is the fallback for an SDK version
+ * that shapes the schema differently, where being approximately right beats refusing to gate.
+ */
+function operationOf(command) {
+    const schema = command?.schema;
+    if (Array.isArray(schema) && typeof schema[1] === 'string' && typeof schema[2] === 'string') {
+        return { service: schema[1], operation: schema[2] };
+    }
+    const name = command?.constructor?.name;
+    return typeof name === 'string' && name.endsWith('Command') ? { operation: name.slice(0, -'Command'.length) } : {};
+}
+/** True for a call this recipe must leave alone - anything that is not Converse inference. */
+function isNotMetered(command) {
+    const { service, operation } = operationOf(command);
+    if (service !== undefined && service !== BEDROCK_SERVICE)
+        return true;
+    return !operation || !METERED_OPERATIONS.has(operation);
+}
+/** Tokens from one Converse response, under Bedrock's own names. */
+function measure(usage, requestId) {
+    if (!usage)
+        return undefined;
+    return {
+        metrics: (0, token_usage_1.pickMetrics)(usage, token_usage_1.BEDROCK_PATHS),
+        usage: (0, token_usage_1.fromBedrockUsage)(usage),
+        raw: usage,
+        // AWS's own request id, which is stable across the SDK's retries - and the SDK retries by
+        // default, so a local counter would bill the same answer more than once.
+        idempotencyKey: requestId,
+    };
+}
+/**
+ * One recipe for every model Bedrock serves.
+ *
+ * Converse normalizes Anthropic, Nova, Llama and the rest to one request and one response, so the
+ * usage block never changes shape - which is the whole reason this can be a single recipe rather
+ * than one per upstream vendor.
+ */
+function bedrockRecipe(options = {}) {
+    const estimate = options.estimate ?? (() => 1);
+    return {
+        vendor: 'bedrock',
+        metrics: token_usage_1.BEDROCK_METRICS,
+        totalTokensMetric: 'totalTokens',
+        // The client's own configuration names the service, which is what separates this from every
+        // other AWS v3 client - they all have `send`, and none of the rest are inference. Data rather
+        // than a class name, for the same reason `operationOf` prefers the schema.
+        matches: (client) => {
+            const config = client?.config;
+            if (!config || typeof client?.send !== 'function')
+                return false;
+            return config.defaultSigningName === 'bedrock' && typeof config.serviceId === 'string';
+        },
+        methods: [
+            {
+                path: ['send'],
+                estimate,
+                // The operation rides in the argument, so this is where a non-inference call is let
+                // through ungated rather than charged for.
+                passthrough: (command) => isNotMetered(command),
+                // A streamed Converse resolves to `{ stream, $metadata }` - the usage is not on the
+                // response at all, so this returns nothing and `attachStream` takes it from there.
+                extractUsage: (result) => result?.stream ? undefined : measure(result?.usage, result?.$metadata?.requestId),
+                /**
+                 * ConverseStream puts its usage in a `metadata` event at the end, so the stream has to be
+                 * run to the end to know what the call cost - the same bargain every streaming binding
+                 * makes.
+                 *
+                 * The iterable is `result.stream`, not `result`: AWS hands back an envelope with the
+                 * stream hanging off it, where the other SDKs hand back the stream itself. Metering the
+                 * envelope would patch an object nobody iterates and report nothing, with no error.
+                 */
+                attachStream: (result, ingest) => {
+                    const requestId = result?.$metadata?.requestId;
+                    let usage;
+                    (0, meter_stream_1.meterStream)(result?.stream, (event) => {
+                        if (event?.metadata?.usage)
+                            usage = event.metadata.usage;
+                    }, () => {
+                        const measurement = measure(usage, requestId);
+                        if (measurement)
+                            ingest(measurement);
+                    });
+                },
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,13 @@
+export type BedrockRecipeOptions = {
+    /**
+     * How much to ask permission for before the call.
+     *
+     * The default asks for 1 - "is there any budget left at all?" - and lets the ingest afterwards
+     * settle the balance, which leaves a gap of about one call's worth of tokens. A run that wants
+     * that gap closed knows something this recipe cannot: `inferenceConfig.maxTokens` is the only
+     * ceiling Bedrock is given, and whether it is worth asking for depends on how a budget is
+     * denominated. Reading it is one line - `(command) => command?.input?.inferenceConfig?.maxTokens
+     * ?? 1` - and it is the caller's line to write.
+     */
+    estimate?: (command: any) => number;
+};

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

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

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