@stigg/agent-sdk-js 1.1.0 → 2.0.0

package/README.md

@@ -33,6 +33,11 @@ is a `stiggContext`, given once at `wrap` as the default for that client and aga
 single call's own parameters to override it. One wrapped client therefore serves every customer
 and every agent, which is what a multi-tenant server actually needs.
 
+**No subscription required.** A customer's credit balance can be checked and drawn with no
+subscription in place at all, so the shortest path from nothing to a working integration is a
+credit currency and a `customerId` — no plan, no entitlement wiring, no catalog modelling first.
+Model the pricing once the metering is real.
+
 `check` happens when the context names an `entitlement`. Omit it and the call meters only: the
 request still goes out, and it is still billed.
 
@@ -59,11 +64,11 @@ request (a budget, a parent) is the only thing that fails without it.
 ```ts
 import { StiggAgentSDK } from '@stigg/agent-sdk-js';
 
-// One per environment. The key can be left out entirely to read STIGG_SERVER_API_KEY, or
-// replaced by a `{ baseUrl }` target that needs none - a local stand-in, or a self-hosted Stigg.
-// A key for somewhere other than the hosted API names that URL second:
-//   new StiggAgentSDK(apiKey, 'https://stigg.internal')
-// Everything after that is tuning, and every bit of it has a working default.
+// One per environment, and everything it takes is one object with a working default. The key can
+// be left out entirely to read STIGG_SERVER_API_KEY, or replaced by a `baseUrl` that needs none -
+// a local stand-in, or a self-hosted Stigg:
+//   new StiggAgentSDK({ apiKey, baseUrl: 'https://stigg.internal', ingest: 'sync' })
+// A bare key is the shorthand for the common case.
 const stigg = new StiggAgentSDK(apiKey);
 
 // Provisioning the agent: a write, so it is its own call. A *bare* registration is remembered per
@@ -72,11 +77,18 @@ const stigg = new StiggAgentSDK(apiKey);
 await stigg.register({
   customerId: 'customer-acme',
   agentId: 'agent-support-bot',
+  // The entity: what the agent IS. `register` is the one call that creates it, so it is the one
+  // call that needs the type.
   entityTypeId: 'agent',
-  entitlement: { currencyId: 'credits' },
-  parentId: 'team-eng',
-  usageLimitOnCreate: 5,
-  cadence: 'P1M',
+  // The assignment: what it may SPEND, and where it sits. One object, because it is one write -
+  // over (entity x entitlement), which is why the entitlement is required inside it.
+  budget: {
+    entitlement: { currencyId: 'credits' },
+    parentId: 'team-eng',
+    limit: 5,
+    apply: 'on-create',
+    cadence: 'P1M',
+  },
 });
 
 // Governs the client and hands back a COPY whose calls are checked and metered. The client you
@@ -90,11 +102,11 @@ const govClient = stigg.wrap(new Anthropic(), {
     // Naming an entitlement is the enforcement switch. Omit it and the calls meter without
     // gating - every call still goes out, and nothing is ever refused.
     entitlement: { currencyId: 'credits' },
-    // What the calls are attributed to. The type is required with it - a guessed attribution key
+    // What the calls are attributed to. The attribution key is required with it - a guessed one
     // resolves no entity, and the spend would land on the customer looking exactly like a call
     // that was never governed. The parent needs no key: governance walks the chain up from here.
     agentId: 'agent-support-bot',
-    agentType: { entityTypeId: 'agent', attributionKey: 'agentId' },
+    attributionKey: 'agentId',
     // Optional extra attribution, sent verbatim on every check and ingest.
     // dimensions: { tenantId: 'acme-eu' },
   },
@@ -238,7 +250,9 @@ that vendor's API would have guessed — so these are what your meters filter on
 | OpenAI (chat)             | `openai.chat.completions.create`                                    | `prompt_tokens`, `completion_tokens`, `cached_tokens`, `total_tokens`                     |
 | OpenAI (responses)        | `openai.responses.create`                                           | `input_tokens`, `output_tokens`, `cached_tokens`, `total_tokens`                          |
 | OpenRouter                | `openrouter.chat.completions.create`, `openrouter.responses.create` | the OpenAI set, plus `cost`                                                               |
+| OpenRouter — its own SDK  | `openrouter.chat.send`, `openrouter.responses.send`                 | the same set — `@openrouter/sdk` camelCases its counters and the recipe reads them back under the wire's names, so one meter covers either client |
 | LiteLLM                   | `litellm.chat.completions.create`, `litellm.responses.create`       | the OpenAI set, plus `cost`                                                               |
+| Bedrock                   | `bedrock.send`                                                      | `inputTokens`, `outputTokens`, `cacheReadInputTokens`, `cacheWriteInputTokens`, `totalTokens` — and no `cost`, because Bedrock states none |
 | TypeSafe                  | `typesafe.systemOne`                                                | `input_tokens`, `output_tokens`, `total_tokens`                                           |
 | Gemini                    | `gemini.models.generateContent`, `gemini.models.generateContentStream` | `promptTokenCount`, `candidatesTokenCount`, `cachedContentTokenCount`, `thoughtsTokenCount`, `toolUsePromptTokenCount`, `totalTokenCount` |
 | Gemini — a chat           | `gemini.chats.sendMessage`, `gemini.chats.sendMessageStream`        | the same five                                                                             |
@@ -266,6 +280,11 @@ A meter to put behind one of them, in Stigg's own terms:
 > event API answers with an acknowledgement, not a balance, so nothing downstream can notice on its
 > own — configure the meter first, or run with `ingest: 'sync'`, which does answer.
 
+> **None of this applies to a metric named after a credit currency.** That draws the wallet
+> directly and needs no event name and no meter — see [the three ingest paths](#the-engine-sdk-first-rest-to-complete)
+> below. If you are using `unitsPerTokens(currencyId, …)`, that is the path you are on, and the
+> table above is about the other one.
+
 #### Pricing them yourself
 
 `weightedMetrics` turns a price-per-metric table into the mapper:
@@ -292,10 +311,25 @@ optional — an unpriced one is free, and a table that prices nothing meters not
 A weight is the price of **one unit** of that metric, so the example above is half a credit per
 output token. Pass `{ per: 1000 }` when the numbers read better per thousand.
 
-It also handles the three things a hand-written mapper has to get right: Stigg takes whole units
-so the total rounds up, a turn that measured nothing reports nothing rather than a zero, and a
-counter the response omitted is absent rather than zero. For one number without weights,
-`creditsPerTokens(featureId, n)` is the short form.
+It also handles the two things a hand-written mapper has to get right: a turn that measured
+nothing reports nothing rather than a zero, and a counter the response omitted is absent rather
+than zero. For one number without weights, `unitsPerTokens(id, n)` is the short form.
+
+Neither rounds. A credit currency takes a fractional amount, so a turn worth a fifth of a unit
+costs a fifth of one — rounding it up would be this SDK's arithmetic on your price. **A feature is
+the exception**: `POST /api/v1/usage` answers `400 Expected integer, received float`, so when the
+target is a feature rather than a currency, pick a unit size that divides or round in your own
+mapper.
+
+> **An attributed run is the other exception, and the SDK rounds it up for you.** Per-entity usage
+> is counted in whole units — governance validates its ingest as an integer and increments a Redis
+> counter with `HINCRBY` — so a fractional amount is rejected there *while the wallet still moves*.
+> The agent's budget would stop advancing with nothing in the response to say so.
+>
+> So a run naming an `agentId` rounds its wallet draw up, and logs that it did. A run with no
+> entity attribution reports the fraction as measured. Denominate the currency finely enough that
+> one unit is small, and the overcharge is noise; this goes away when governance counts fractions.
+
 
 #### Writing the mapper yourself
 
@@ -502,23 +536,75 @@ Two clients, composed per operation, and the SDK tells you which one it picked:
 | `ingest`            | `@stigg/node-server-sdk`              | it has the in-memory cache, and usage reporting is the hot path          |
 | provision / archive | `@stigg/typescript` (REST, `v1-beta`) | entities and assignments exist only on the governance surface            |
 
-**Ingest has two APIs, and the context picks one.** They are not variants of one call:
+**Ingest has three paths, not two.** `ingest` picks between the first two — but **the name of the
+metric decides first**, and that is the rule to read before the table:
+
+> **If a metric is named after the credit currency the context checks, it draws the wallet
+> directly, in both modes.** No event, no usage report, and no meter involved — `ingest` then only
+> decides whether the call waits for the balance to come back.
+
+That is the path `unitsPerTokens(currencyId, …)` puts you on, and it is why switching `async` and
+`sync` can look like it changes nothing: both deduct credits, neither needs a metered feature, and
+the only visible difference is whether `IngestResult.creditsConsumed` is filled in. Metrics named
+after a **feature** take one of the other two columns.
 
-|                        | `ingest: 'async'` — the default     | `ingest: 'sync'`                                     |
-| ---------------------- | ----------------------------------- | ---------------------------------------------------- |
-| Call                   | `events.report` / `reportEvent`     | `usage.report` / `reportUsageBulk`                   |
-| Latency and rate limit | low latency, much higher limit      | higher latency, lower limit                          |
-| The next check         | lags while Stigg aggregates         | already includes the spend                           |
-| What you send          | the call, as one event              | a `featureId` and a whole-number `value`, per metric |
-| Meter type             | **Raw events**, configured in Stigg | calculated / incremental                             |
-| What comes back        | an acknowledgement                  | a credit balance                                     |
+|                        | A metric named after the currency       | `ingest: 'async'` — the default     | `ingest: 'sync'`                                     |
+| ---------------------- | --------------------------------------- | ----------------------------------- | ---------------------------------------------------- |
+| Call                   | `consumeCredits` / `consumeCreditsAsync` | `events.report` / `reportEvent`     | `usage.report` / `reportUsageBulk`                   |
+| Latency and rate limit | follows the mode                        | low latency, much higher limit      | higher latency, lower limit                          |
+| The next check         | includes it under `'sync'`; lags under `'async'` | lags while Stigg aggregates         | already includes the spend                           |
+| What you send          | a currency id and an amount             | the call, as one event              | a `featureId` and a whole-number `value`, per metric |
+| Meter type             | **none — the wallet is drawn directly** | **Raw events**, configured in Stigg | calculated / incremental                             |
+| What comes back        | a balance under `'sync'`, nothing under `'async'` | an acknowledgement        | a credit balance                                     |
 
 Async sends **one event for the whole turn**, every metric on its own dimension, because one event
 feeds any number of meters — fanning out per metric buys nothing and costs a request each. Sync
 sends one report per metric, batched into a single bulk call.
 
-A metric named after the currency the context checks is neither: it draws the wallet directly, since
-no raw event can reach a currency. It follows the mode only in whether it waits for the balance.
+There is no event path from a raw event to a currency, which is why the first column exists at all:
+a usage report takes only a `featureId`, so a currency has to be drawn rather than metered.
+
+> **`'async'` does not settle the wallet before the next check.** `consumeCreditsAsync` is
+> reconciled into the balance on Stigg's side, and nothing invalidates the entitlement cache in the
+> meantime — so a check made immediately after a draw can still see the balance from before it, and
+> approve a call the wallet could not afford. `'sync'` is what closes that window.
+
+**The match is exact.** A metric draws the wallet only when its name *equals* the currency the
+context checks. `unitsPerTokens('data_credit', …)` against `entitlement: { currencyId: 'credits' }`
+is a feature report named `data_credit`, not a draw on `credits` — so it needs a meter like any
+other feature, and silently meters nothing until one exists.
+
+**A check asks for one unit by default, so the last call can overshoot.** The budget is allowed
+below zero, and `'async'` adds a reconciliation window on top — calls made while Stigg is still
+turning events into usage all see the same balance. Worst case is therefore one call's cost, plus
+whatever lands in that window.
+
+Narrow it per call with the recipe's own estimator, which asks for what the call could cost
+instead of for one unit:
+
+```ts
+import { anthropicRecipe, estimateFromMaxTokens } from '@stigg/agent-sdk-js';
+
+stigg.wrap(new Anthropic(), {
+  stiggContext: { customerId, entitlement: { currencyId: 'credits' } },
+  // `estimate` reads the call's own parameters - here `max_tokens` - and asks for that many
+  // units instead of one. The ingest that follows still corrects the balance.
+  recipe: {
+    ...anthropicRecipe,
+    methods: anthropicRecipe.methods.map((method) => ({ ...method, estimate: estimateFromMaxTokens(1_000) })),
+  },
+});
+```
+
+It is opt-in on purpose: an estimate that overshoots denies calls the budget could have afforded,
+and the ingest that follows corrects the balance anyway. For a hard cap, pair it with
+`ingest: 'sync'` — `'async'` trades exactness for throughput, so it is not what a hard cap is for.
+
+**Which to reach for.** Credits when the unit is money-like, shared across features, pre-purchased
+or topped up — one balance, many consumers. A metered feature when the limit is per-capability,
+belongs to a plan entitlement, or resets on a billing cadence. Both when a plan grants a feature
+allowance and a credit pool covers the overage; name the feature in `usageMapper` and let Stigg's
+consumption mapping convert it, rather than pricing it in code.
 
 **Governance is optional.** Not every account has it. When it is missing the factory falls back
 to customer-level enforcement on the Node SDK alone — every example still runs, denials just name
@@ -764,34 +850,37 @@ team-research (team) usage=0/30
 the parent team, a funded pool). That is the more realistic split: an admin sets up the account, an
 application provisions its own agents at runtime. `register()` carries it:
 
-One caveat about the cap, because the two halves can overlap. `usageLimitOnCreate` is exactly that
+One caveat about the cap, because the two halves can overlap. `apply: 'on-create'` is exactly that
 — on create — so if the seed has already written an assignment for that agent, the application's
 cap is **not** applied and the seeded one stands. That is the point of the option (an admin who
 raises a budget out of band should not have it stamped back on every process start), but it does
-mean `--agent-limit` on the seed wins over the number below. Use `usageLimit` instead if the
-application is meant to own it.
+mean `--agent-limit` on the seed wins over the number below. Leave `apply` at its default
+(`'always'`) if the application is meant to own it.
 
 ```ts
 await stigg.register({
   customerId: 'customer-acme',
   agentId: 'agent-support-bot-anthropic',
   entityTypeId: 'agent',
-  // A budget is written over (entity x entitlement), so a call carrying one names it. `register`
-  // refuses a placement without it rather than provisioning an agent whose cap lands nowhere.
-  entitlement: { currencyId: 'credits' },
-  parentId: 'team-research',
-  usageLimit: 5,
-  cadence: 'P1M',
+  budget: {
+    // A budget is written over (entity x entitlement), so the entitlement is required here: a
+    // cap has nowhere to land without one.
+    entitlement: { currencyId: 'credits' },
+    parentId: 'team-research',
+    limit: 5,
+    cadence: 'P1M',
+  },
 });
 ```
 
 A cap is **not** a field on the entity. An entity is just a node — id, type, display name,
 metadata — and a limit is an _assignment_ over `(entity × capability)`. So that one call is two
 idempotent upserts underneath: `PUT …/entities` then `PUT …/assignments`. It is also why
-`parentId` rides the assignment rather than the entity: the hierarchy is per-capability, so one
-agent can sit under different parents for different currencies.
+`parentId` rides the assignment rather than the entity — and sits inside `budget` for the same
+reason: the hierarchy is per-capability, so one agent can sit under different parents for
+different currencies.
 
-`usageLimit` is tri-state — a number caps it, `null` tracks without blocking (the observe-only
+`budget.limit` is tri-state — a number caps it, `null` tracks without blocking (the observe-only
 rollout), and omitting it leaves whatever is already assigned untouched. Governance requires both
 it and `cadence` when it creates a budget, which is why both are passed above.
 
@@ -834,6 +923,8 @@ there (or exporting it in your shell) overrides the fixture without editing `dem
 | `AGENT_SDK_GEMINI_MODEL`               | `gemini-3.8-flash`                       | Model for the Gemini client example                                                                                                  |
 | `AGENT_SDK_OPENROUTER_MODEL`           | `anthropic/claude-opus-5`                | Primary model requested from the gateway                                                                                             |
 | `AGENT_SDK_OPENROUTER_FALLBACK_MODELS` | `anthropic/claude-sonnet-5,openai/gpt-5` | Comma-separated fallbacks tried in order                                                                                             |
+| `AGENT_SDK_BEDROCK_REGION`             | `us-east-1` (falls back to `AWS_REGION`) | Region the Bedrock model is called in. There is no Bedrock key variable: AWS authenticates through its own credential chain, and the example asks that chain rather than looking for one |
+| `AGENT_SDK_BEDROCK_MODEL`              | `anthropic.claude-sonnet-4-5-20250929-v1:0` | Bedrock model id. Names one model exactly — Bedrock does not route, so there is no fallback list                                   |
 | `AGENT_SDK_LITELLM_API_KEY`            | — (falls back to `LITELLM_API_KEY`)      | Layer 2. Blank ⇒ the offline mock                                                                                                    |
 | `AGENT_SDK_LITELLM_BASE_URL`           | `http://localhost:4000`                  | Your own proxy — self-hosted, so there is no public default                                                                          |
 | `AGENT_SDK_LITELLM_MODEL`              | `gpt-5`                                  | A model **group** from the proxy's config, not a provider slug                                                                       |
@@ -847,7 +938,7 @@ change it to play with an example, it is a fixture.** A real application decides
 in code — what it bills against is part of its pricing, not of its deployment.
 
 The SDK's own settings are arguments rather than variables, which is why none of them appear here:
-`new StiggAgentSDK(apiKey, baseUrl, { cache, client, timeoutMs, logger, onError })` for the
+`new StiggAgentSDK({ apiKey, baseUrl, cache, client, timeoutMs, logger, onError })` for the
 environment, and `wrap(client, { stiggContext })` — overridable inside any call's own parameters —
 for what a call is governed by.
 
@@ -878,8 +969,8 @@ The defaults are mock-only on purpose: against an environment you can write to,
 | `AGENT_SDK_DEMO_CUSTOMER_ID`          | `customer-acme`       | **Error.** Every governance call is scoped to a tenant, and the examples will not invent one |
 | `AGENT_SDK_DEMO_TEAM_ID`              | `team-research`       | The agents are **roots** — no ancestor budget binds them. `two-agents` needs one and says so |
 | `AGENT_SDK_DEMO_AGENT_ID`             | `agent-support-bot`   | **No agent at all**: checks and usage land on the customer's own pool. Blank it to see that path against the mock. Each client example appends its vendor (`…-anthropic`) |
-| `AGENT_SDK_DEMO_ENTITY_TYPE_ID` | `agent` *(mock only)* | `stiggContext.agentType.entityTypeId` — the entity type agents are provisioned as |
-| `AGENT_SDK_DEMO_ATTRIBUTION_KEY` | `agentId` *(mock only)* | `stiggContext.agentType.attributionKey` — the key that type identifies its agents under. **Both or neither**: the SDK defaults neither half, because a guessed key resolves no entity and the spend lands on the customer looking exactly like an ungoverned call |
+| `AGENT_SDK_DEMO_ENTITY_TYPE_ID` | `agent` *(mock only)* | `register`'s own `entityTypeId` — the entity type agents are provisioned as |
+| `AGENT_SDK_DEMO_ATTRIBUTION_KEY` | `agentId` *(mock only)* | `stiggContext.attributionKey` — the key that type identifies its agents under. **Both or neither**: the SDK defaults neither half, because a guessed key resolves no entity and the spend lands on the customer looking exactly like an ungoverned call |
 | `AGENT_SDK_OFFLINE`                   | empty                 | Set to `1` to force the mocks even when keys are present              |
 | `AGENT_SDK_DEMO_MOCK_GOVERNANCE_FAIL` | empty                 | Mock only: make the runtime check return `503`                        |
 
@@ -907,6 +998,7 @@ Stigg account.
 | `example-two-agents`        | [`client/two-agents.ts`](./examples/client/two-agents.ts)             | Two agents, one team: a sibling denied by its own cap, then the survivor denied by the team above it        |
 | `example-gateway-openrouter`| [`gateway/openrouter.ts`](./examples/gateway/openrouter.ts)           | The two gateway topologies: calling one gates, operating one only ingests. `example-gateway` runs this one  |
 | `example-gateway-litellm`   | [`gateway/litellm.ts`](./examples/gateway/litellm.ts)                 | The same two topologies when the cost is in a header: real spend, then tokens, from one request             |
+| `example-gateway-bedrock`   | [`gateway/bedrock.ts`](./examples/gateway/bedrock.ts)                 | A gateway that states no price: tokens are all there is to meter, and nothing proxies it                    |
 | `example-setup`             | [`shared/setup-governance.ts`](./examples/shared/setup-governance.ts) | Seeds a customer, a pool and per-entity budgets. Idempotent                                                 |
 
 `example-client` is an alias for the Anthropic one. Prefix any of them with `AGENT_SDK_OFFLINE=1`
@@ -1059,7 +1151,7 @@ AGENT_SDK_OFFLINE=1 AGENT_SDK_DEMO_MOCK_GOVERNANCE_FAIL=1 \
 
 # The explicit opt-in - refuse the call when the check itself could not be made. An SDK option,
 # not an env var, and overridable per call through `stiggContext`:
-#   new StiggAgentSDK(apiKey, baseUrl, { checkErrorAction: 'deny' })
+#   new StiggAgentSDK({ apiKey, baseUrl, checkErrorAction: 'deny' })
 ```
 
 `allow` is the default: a soft limit, so an unreachable Stigg does not take the application down
@@ -1092,7 +1184,7 @@ them first.
 | `403 GovernanceNotEnabled`                  | The account has no governance. Checks and usage still work; `register()` throws, because there is nowhere to create the agent entity. Contact Stigg to enable it.                                                                                                                                                                                    |
 | `No STIGG_API_KEY`                          | Set it to a server key for the environment in `STIGG_BASE_URL`, or leave it blank to run on the built-in mock.                                                                                                                                                                                                                                       |
 | `503` and every turn denied                 | The governance cache is unavailable and `checkErrorAction` is `deny`. The default is `allow`, so this is a policy that was asked for; drop it to keep running through the outage, or relax a single call with `stiggContext: { checkErrorAction: 'allow' }`. |
-| `usage value must be a whole number`        | Stigg rejects fractional usage under `'sync'`. Raise the unit size in your `usageMapper` — `creditsPerTokens(id, n)` — or map to a coarser unit.                                                                                                                                                                                                                                                    |
+| `usage value must be a whole number to report against a feature` | `POST /api/v1/usage` takes integers. Report against a **credit currency** instead, which takes fractions, or raise the unit size in your `usageMapper` so the division comes out whole.                                                                                                                                                 |
 | `... is backed by a raw-events meter`       | A `sync` run reported to a feature only a meter can fill. Report that run with `ingest: 'async'` (the default), or point it at a feature whose value your application computes.                                                                                                                                                                      |
 | Ingest reports `ok=true` but usage stays 0  | Under `async` an acknowledgement is all the event API returns. Check a raw-events meter filters on the event name (see the event table above); against a **local** Stigg, also that the `ingest-usage-stream-processor` and `calculate-usage-stream-processor` lambdas are running. `ingest: 'sync'` answers with a balance and will say so instead. |
 | Still denied right after a top-up           | Budgets reset per cadence window, so a spent agent stays spent. Re-run `example-setup --agent-limit N` with a higher limit, or use a new `AGENT_SDK_DEMO_AGENT_ID`.                                                                                                                                                                                  |

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/openrouter/openrouter-recipe.d.ts

@@ -6,6 +6,11 @@ type GatewayMetric = (typeof GATEWAY_METRICS)[number];
 /**
  * One recipe covers every upstream. OpenRouter normalizes Anthropic, OpenAI and the rest to the
  * same wire shape, so the response never changes form - `model` is just a field saying who served.
+ *
+ * It also covers both ways of reaching OpenRouter from Node: the OpenAI SDK pointed at the
+ * gateway's base URL, and OpenRouter's own `@openrouter/sdk`. Those are different objects with
+ * different method names reporting the same call, and a recipe that governed only the first would
+ * meter nothing at all for an application that took OpenRouter's own documented advice.
  */
 export declare function openrouterRecipe(options?: OpenRouterRecipeOptions): ClientRecipe<GatewayMetric>;
 /** One of the metric names OpenRouter reports. */