@stigg/agent-sdk-js 1.1.0 → 2.0.0

package/dist/stigg-agent-sdk.js

@@ -25,6 +25,7 @@ const dimensions_1 = require("./core/dimensions");
 const anthropic_recipe_1 = require("./bindings/client/providers/anthropic/anthropic-recipe");
 const gemini_recipe_1 = require("./bindings/client/providers/gemini/gemini-recipe");
 const litellm_recipe_1 = require("./bindings/client/gateways/litellm/litellm-recipe");
+const bedrock_recipe_1 = require("./bindings/client/gateways/bedrock/bedrock-recipe");
 const openai_recipe_1 = require("./bindings/client/providers/openai/openai-recipe");
 const openrouter_recipe_1 = require("./bindings/client/gateways/openrouter/openrouter-recipe");
 const typesafe_recipe_1 = require("./bindings/client/providers/typesafe/typesafe-recipe");
@@ -54,6 +55,9 @@ exports.DEFAULT_RECIPES = [
     anthropic_recipe_1.anthropicRecipe,
     (0, openrouter_recipe_1.openrouterRecipe)(),
     (0, litellm_recipe_1.litellmRecipe)(),
+    // Matched on its own client's configuration, so it sits with the gateways rather than ahead of
+    // or behind them: an AWS command bus is nothing any other guard here can mistake for its own.
+    (0, bedrock_recipe_1.bedrockRecipe)(),
     openai_recipe_1.openAIRecipe,
     typesafe_recipe_1.typesafeRecipe,
     // Gemini's two surfaces are matched separately - a client and one of its chats are different
@@ -81,11 +85,46 @@ const DEFAULT_EVENT_NAME = 'agent.usage';
  */
 const DEFAULT_WALLET = { currencyId: 'credits' };
 /**
- * Whether this call means to write the agent's budget or its place in the tree. One predicate,
- * used by both the operation that acts on it and the memo that decides whether to run at all -
- * two lists that disagreed about what counts is how a budget went missing before.
+ * How long a failed engine probe is remembered before the next call builds a new one.
+ *
+ * Long enough that an outage is probed on a timer rather than once per request, short enough that
+ * a transient failure costs seconds instead of a restart. See {@link StiggAgentSDK.ensureStarted}
+ * for why remembering it at all is the point.
  */
-const hasPlacement = (input) => input.parentId !== undefined || input.usageLimit !== undefined || input.usageLimitOnCreate !== undefined;
+const RETRY_START_AFTER_MS = 2_000;
+/** The key shorthand and the options object, folded into the one object the config takes. */
+function toOptions(first, second) {
+    return typeof first === 'string' ? { ...second, apiKey: first } : { ...first, ...second };
+}
+/** The assignment `register` is being asked to write, if it is being asked to write one. */
+function toPlacement(input) {
+    if (!input.budget)
+        return undefined;
+    const { entitlement, cadence, parentId } = input.budget;
+    // A placement writes an assignment against the entitlement, so an empty one persists a budget
+    // attached to nothing rather than merely routing badly.
+    const invalid = (0, types_1.entitlementError)(entitlement);
+    if (invalid)
+        throw invalid;
+    // `'on-create'` seeds and leaves an admin's change alone; `'always'`, the default, writes every
+    // time. One field, so the two cannot both be given.
+    const onCreate = input.budget.apply === 'on-create';
+    // The type says a seed carries a number, and a JS caller is not bound by it. Seeding `undefined`
+    // sends a cadence and no cap, so the agent is created with the budget it asked for missing -
+    // enforcement then falls through to whatever ancestor has one, silently. Refused instead.
+    if (onCreate && typeof input.budget.limit !== 'number') {
+        throw new Error(`Agent ${input.agentId} asked to seed a budget with no limit to seed. ` +
+            "`budget.apply: 'on-create'` writes a cap the first time and never again, so there is " +
+            'nothing to write without `budget.limit`.');
+    }
+    return {
+        parentId,
+        entitlement,
+        cadence,
+        usageLimit: onCreate ? undefined : input.budget.limit,
+        usageLimitOnCreate: onCreate ? (input.budget.limit ?? undefined) : undefined,
+    };
+}
 class StiggAgentSDK {
     config;
     clients;
@@ -105,14 +144,14 @@ class StiggAgentSDK {
      */
     registering = new Map();
     started;
+    /**
+     * When the attempt currently in `started` rejected, or undefined while it is pending or has
+     * resolved. What makes a failed probe expire rather than persist - see `ensureStarted`.
+     */
+    startFailedAt;
     engineState;
-    constructor(target, 
-    // A URL is a string and the options are not, which is the whole of the discrimination - the
-    // same shape the target itself uses. It exists so a keyless target can still name a knob
-    // without an `undefined` standing in for the URL it already carries.
-    baseUrlOrOptions, options = {}) {
-        const baseUrl = typeof baseUrlOrOptions === 'string' ? baseUrlOrOptions : undefined;
-        this.config = (0, config_1.resolveConfig)(target, baseUrl, typeof baseUrlOrOptions === 'object' ? baseUrlOrOptions : options);
+    constructor(first, second) {
+        this.config = (0, config_1.resolveConfig)(toOptions(first, second));
         this.clients = (0, registry_1.createClientRegistry)(exports.DEFAULT_RECIPES);
     }
     /** Releases what this SDK's engine holds open. */
@@ -164,35 +203,7 @@ class StiggAgentSDK {
         if (typeof agentId !== 'string' || !agentId.trim()) {
             throw new Error('register needs an agentId - an empty one provisions an entity nobody can name.');
         }
-        if (input.usageLimit !== undefined && input.usageLimitOnCreate !== undefined) {
-            throw new Error(`Agent ${agentId} was given both usageLimit and usageLimitOnCreate. They are different ` +
-                'budget modes - one overwrites on every call, the other seeds once - so pass exactly one.');
-        }
-        // The placement, built once: `hasPlacement` is the predicate, and the object it produces is what
-        // proves the entitlement is there - a second `hasPlacement(...)` further down would be a second
-        // list of what counts, which is how a budget goes missing.
-        let placement;
-        if (hasPlacement(input)) {
-            const { entitlement } = input;
-            if (!entitlement) {
-                throw new Error(`Agent ${agentId} was given a budget or a parent, but no entitlement to write it against. ` +
-                    'An assignment is written over (entity x entitlement), so there is nowhere to put this ' +
-                    'one. Name `entitlement` on the run that starts the agent, or drop usageLimit, ' +
-                    'usageLimitOnCreate and parentId - a run that names no entitlement meters only.');
-            }
-            // `run()` guards this too. A placement writes an assignment against the entitlement, so an
-            // empty one here persists a budget attached to nothing rather than merely routing badly.
-            const invalid = (0, types_1.entitlementError)(entitlement);
-            if (invalid)
-                throw invalid;
-            placement = {
-                parentId: input.parentId,
-                entitlement,
-                usageLimit: input.usageLimit,
-                usageLimitOnCreate: input.usageLimitOnCreate,
-                cadence: input.cadence,
-            };
-        }
+        const placement = toPlacement(input);
         const key = `${customerId}:${agentId}`;
         // Memoized on the description, not just the pair: a second call describing the agent
         // differently is asking for that description to be written, and skipping it leaves the
@@ -461,11 +472,23 @@ class StiggAgentSDK {
             if (!attribution) {
                 throw new errors_1.EngineError('ingest', 'request carries no governance headers - nothing to attribute usage to');
             }
+            // The same split `reportMetrics` makes: a metric named after the currency this ingest
+            // draws on goes to the wallet, which takes fractions, and everything else to the usage
+            // report, which does not.
+            const entitlement = input.entitlement ?? DEFAULT_WALLET;
+            const creditCurrencyId = (0, types_1.entitlementKind)(entitlement) === 'credit' ? (0, types_1.entitlementId)(entitlement) : undefined;
+            // Whether this proxied call names an agent, read from the header the sending side sets
+            // rather than guessed from the dimensions. The map arrives flat, so `{ region: 'eu' }`
+            // looks exactly like an attribution key from here - and rounding on that would overcharge a
+            // wallet draw with no entity behind it. See `wholeUnitsForGovernance`.
+            const attributed = !!attribution.attributionKey;
             const sendable = {};
-            for (const [featureId, value] of Object.entries(metrics)) {
+            for (const [featureId, rawValue] of Object.entries(metrics)) {
+                const drawsWallet = featureId === creditCurrencyId;
+                const value = attributed && drawsWallet ? (0, types_1.wholeUnitsForGovernance)(rawValue) : rawValue;
                 // A gateway maps someone else's usage object with someone else's mapper, so it is the
                 // path most likely to produce a value that is not a measurement at all.
-                const invalid = (0, types_1.usageValueError)(value, mode);
+                const invalid = (0, types_1.usageValueError)(value, mode, drawsWallet);
                 if (invalid)
                     throw invalid;
                 if (value > 0 || mode === 'async')
@@ -480,7 +503,7 @@ class StiggAgentSDK {
             }
             const reported = await this.engine.report(attribution.customerId, {
                 metrics: sendable,
-                entitlement: input.entitlement ?? DEFAULT_WALLET,
+                entitlement,
                 mode,
                 // What the proxy observed, as the proxy received it. There is no recipe out here, so the
                 // block is whatever `observedMeasurement` could make of the usage object it was handed.
@@ -544,20 +567,44 @@ class StiggAgentSDK {
             await this.close();
         return summaries;
     }
-    /** Builds the engine once, on first need. Concurrent callers share the same attempt. */
+    /**
+     * Builds the engine once, on first need. Concurrent callers share the same attempt.
+     *
+     * A *failed* attempt is shared too, but only for {@link RETRY_START_AFTER_MS}. A rejected
+     * promise is still a promise, so memoizing one unconditionally outlives the failure that caused
+     * it: under the default `checkErrorAction: 'allow'` the process stops enforcing any budget at
+     * all, and under `'deny'` it refuses every call - neither saying anything a log would show.
+     *
+     * Holding the failure briefly rather than discarding it on sight is the other half: callers
+     * inside the window get the same rejection immediately and their own `checkErrorAction` decides
+     * the outcome, so an outage is re-probed on a timer instead of once per request.
+     */
     ensureStarted() {
-        this.started ??= (0, create_engine_1.createGovernanceEngine)({
-            apiKey: this.config.apiKey,
-            baseUrl: this.config.baseUrl,
-            timeoutMs: this.config.timeoutMs,
-            cache: this.config.cache,
-            client: this.config.client,
-            logger: this.config.logger,
-        }).then((state) => {
-            this.engineState = state;
-            this.config.logger.info(`[stigg] ${(0, engine_1.describeResolution)(state.resolution)}`);
-            return state;
-        });
+        if (this.startFailedAt !== undefined && Date.now() - this.startFailedAt >= RETRY_START_AFTER_MS) {
+            this.started = undefined;
+            this.startFailedAt = undefined;
+        }
+        if (!this.started) {
+            const attempt = (0, create_engine_1.createGovernanceEngine)({
+                apiKey: this.config.apiKey,
+                baseUrl: this.config.baseUrl,
+                timeoutMs: this.config.timeoutMs,
+                cache: this.config.cache,
+                client: this.config.client,
+                logger: this.config.logger,
+            }).then((state) => {
+                this.engineState = state;
+                this.config.logger.info(`[stigg] ${(0, engine_1.describeResolution)(state.resolution)}`);
+                return state;
+            });
+            this.started = attempt;
+            // Checked against the attempt that failed, not just set: a late rejection from an attempt
+            // already replaced would otherwise expire the newer one that succeeded.
+            attempt.catch(() => {
+                if (this.started === attempt)
+                    this.startFailedAt = Date.now();
+            });
+        }
         // `wrap` starts this and does not await it, so between a failing probe and the first call
         // there is a rejected promise nobody is holding - which Node treats as an unhandled rejection
         // and ends the process over. Marked handled here; it changes nothing for an awaiter, because

package/dist/types.d.ts

@@ -10,7 +10,7 @@
  */
 import { EngineError } from './errors';
 import type { StiggContext } from './core/context';
-import type { GovernanceSummary, SessionHooks } from './core/session';
+import type { SessionSummary, SessionHooks } from './core/session';
 import type { GovernanceHeaders } from './headers';
 import type { ClientRecipe } from './bindings/client/core/types';
 import type { ObservedVendor } from './bindings/shared/token-usage';
@@ -111,7 +111,7 @@ export type Metrics = Record<string, number>;
  * Turns what a binding observed into the metrics to report.
  *
  * Defaults to the vendor's own: whatever names and values came back on the response. Supply your
- * own to report something else - see `creditsPerTokens` for the one-number case, and each client
+ * own to report something else - see `unitsPerTokens` for the one-number case, and each client
  * recipe for what that vendor meters by default.
  */
 export type MetricsMapper = (measurement: Measurement) => Metrics;
@@ -141,6 +141,19 @@ export type Measurement = {
     raw?: Record<string, unknown>;
     /** Per-call attribution, merged over the run's own dimensions. e.g. the model that served. */
     dimensions?: Record<string, string>;
+    /**
+     * Set when a counter here is this SDK's estimate rather than something the vendor stated.
+     *
+     * Only one thing sets it today: a stream the consumer abandoned. Anthropic states the output
+     * count on the event that ends the stream, so a reply stopped halfway never states one - and
+     * reporting nothing for text the customer read, and the vendor billed, is a hole rather than a
+     * conservative answer.
+     *
+     * Carried on the measurement rather than folded into a dimension so it reaches the run's
+     * `usageMapper`, which is what makes it a decision rather than a surprise: a mapper that would
+     * rather bill nothing than bill an estimate can branch on this and return `{}`.
+     */
+    estimated?: true;
     /** The vendor's own request id, when it has one that is stable across its retries. */
     idempotencyKey?: string;
     /**
@@ -159,27 +172,76 @@ export type Measurement = {
 export declare const vendorMetrics: MetricsMapper;
 /** A binding may report either shape; `TokenUsage` is the common case and stays terse. */
 export declare const toMeasurement: (value: TokenUsage | Measurement) => Measurement;
+/**
+ * The amount to report when this run is attributed to a governance entity.
+ *
+ * Governance counts in whole units and cannot be made to count otherwise from here: its ingest
+ * schema is `z.number().int()`, and the counter behind it is a Redis `HINCRBY`, which takes an
+ * integer delta. A fractional amount is rejected at that boundary - the wallet still moves, the
+ * per-entity counter does not, and nothing in the response says so. An agent's budget silently
+ * stops advancing while its spend carries on.
+ *
+ * So an attributed run rounds up, and only an attributed run: a run that names no entity reports
+ * what its mapper produced, because the wallet takes fractions and nothing downstream of it
+ * counts in whole units.
+ *
+ * Rounding *up* rather than to nearest, because a call that happened must cost something: at any
+ * sane denomination most calls are worth less than one unit, and rounding to nearest would bill
+ * nothing for nearly all of them.
+ *
+ * TODO: delete this, and the call sites that use it, once governance counts fractional usage.
+ * The platform fix is to scale internally - store micro-units and accept fractions at the API
+ * boundary - which keeps `HINCRBY` working and is the only way an agent budget can be
+ * denominated finely enough to price a call worth a tenth of a cent. Until then this is a
+ * deliberate overcharge on small calls, which is why it is announced rather than silent.
+ */
+export declare const wholeUnitsForGovernance: (value: number) => number;
 /**
  * Why a measured value cannot be reported, if it cannot.
  *
  * Zero is not an error - a cached refusal or an empty stream is a normal turn - but a mapper
  * dividing by an unset config returns NaN or Infinity, and reading those as "nothing was used"
- * meters the run at zero while every call still reports success. Those are refused in both modes;
- * a fraction is refused only under `'sync'`, whose DTO takes whole units.
+ * meters the run at zero while every call still reports success. Those are refused everywhere.
+ *
+ * A fraction is refused on one path only, and the rule is the endpoint's rather than this SDK's:
+ *
+ * - **The wallet** takes them. `credits.consumption.consume` and its async twin accept a
+ *   fractional `amount`, and balances are fractional too - which they have to be, or a currency
+ *   could never be denominated finely enough to price a call worth a tenth of a cent.
+ * - **An event** takes them. The number rides as a dimension and a meter sums what it finds,
+ *   which is the only way a gateway's `cost` reports honestly.
+ * - **The usage report** does not: `POST /api/v1/usage` answers
+ *   `400 Expected integer, received float`. That is the one case refused here, where the caller
+ *   can still see which metric it was - metering failures are swallowed into `onError`, so a 400
+ *   three frames down is a silent gap rather than an error anyone reads.
  *
  * Shared, because every path that reports usage has to answer this the same way.
  */
-export declare function usageValueError(value: number, mode?: IngestMode): EngineError | undefined;
+export declare function usageValueError(value: number, mode?: IngestMode, drawsWallet?: boolean): EngineError | undefined;
 /**
  * One metric, summed from every token class and divided by the unit size.
  *
- * The mapper for an application that prices tokens itself rather than letting Stigg convert a
- * credit-backed feature. Weighting cache reads cheaper is a pricing decision and belongs in
- * Stigg's consumption mapping, not here; Stigg rejects fractions, so the result rounds up.
+ * The mapper for an application that prices tokens itself. Named for what it produces - units
+ * under an id - rather than for credits, because it does not deduct any: it reports a number, and
+ * that number draws the wallet only when the id happens to name a credit currency. Which it is
+ * decides the whole ingest path, so a mapper that claimed to know was the wrong place to look.
+ *
+ * **Prefer reporting the raw counters and converting in Stigg.** A consumption mapping on the plan
+ * does the same arithmetic where a pricing change does not need a deploy, and it is the only place
+ * that can weight cache reads cheaper. Reach for this when the application deliberately prices
+ * itself.
+ *
+ * The division is reported as it comes out. A credit currency takes fractions, so a call worth
+ * four fifths of a unit costs four fifths of one - rounding it up here would be this SDK's
+ * arithmetic on someone else's price. A **feature** is the exception: `POST /api/v1/usage` takes
+ * integers, so pick a `tokensPerUnit` that divides, or round in your own mapper.
+ *
+ * @param id The Stigg feature id or credit currency id to report under.
+ * @param tokensPerUnit How many tokens make one unit.
  */
-export declare const creditsPerTokens: (featureId: string, tokensPerUnit?: number) => MetricsMapper;
+export declare const unitsPerTokens: (id: string, tokensPerUnit?: number) => MetricsMapper;
 /** What the caller should do about a denial. A refusal is a commercial event, not an error. */
-export type GovernanceRemedy = 'top-up' | 'raise-budget' | 'subscribe' | 'retry';
+export type Remedy = 'top-up' | 'raise-budget' | 'subscribe' | 'retry';
 /**
  * Which client answered, or - for 'cache', 'policy' and 'unenforced' - that nothing was asked.
  *
@@ -191,7 +253,7 @@ export type DecisionSource = 'rest' | 'node-sdk' | 'cache' | 'policy' | 'unenfor
  * The structured refusal. Returned, never thrown, everywhere the caller has a return path:
  * the denial path is a revenue surface (top-up, upgrade), so it must be inspectable.
  */
-export type GovernanceDecision = {
+export type AccessDecision = {
     hasAccess: boolean;
     /** Which entity blocked - a governance node, or the customer when governance is not in play. */
     deniedBy?: string;
@@ -200,7 +262,7 @@ export type GovernanceDecision = {
      * the SDK reached the verdict itself. `InsufficientCredits` and `BudgetExceeded` differ.
      */
     reason?: string;
-    remedy?: GovernanceRemedy;
+    remedy?: Remedy;
     /** Tightest remaining budget across the pool and the chain. Undefined when nothing is bounded. */
     remaining?: number;
     usageLimit?: number | null;
@@ -296,30 +358,57 @@ export type AgentOptions = {
     entityTypeId: string;
     displayName?: string;
     metadata?: Record<string, string>;
-    /** Places the agent under a parent entity. Tri-state: omit to leave it, null to make it a root. */
-    parentId?: string | null;
-    /** Budget for this agent, written on every call. Omit to leave whatever is already assigned. */
-    usageLimit?: number | null;
     /**
-     * Budget applied only when this agent has no assignment yet. Use this rather than `usageLimit`
-     * when an admin may change the budget out of band: `usageLimit` would overwrite their change on
-     * every process start. Mutually exclusive with `usageLimit`.
+     * What this agent may spend, and where it sits in the tree. Omit it and `register` writes an
+     * identity and nothing else.
+     *
+     * Grouped rather than flat because these five are one write underneath - an assignment over
+     * `(entity x entitlement)` - while the fields above are the entity. See {@link AgentBudget}.
      */
-    usageLimitOnCreate?: number;
+    budget?: AgentBudget;
+};
+/**
+ * What an agent may spend, as the one write it actually is.
+ *
+ * Grouped because these are one write underneath - an assignment over `(entity x entitlement)` -
+ * while the fields beside them describe the entity. The grouping is what makes two illegal
+ * combinations unrepresentable: `apply` is one field, so there is no way to ask for both budget
+ * modes, and `entitlement` is required, so there is no way to write a limit against nothing.
+ *
+ * `parentId` lives here rather than on the entity because the hierarchy is **per-entitlement**:
+ * an agent can sit under one parent for one budget and elsewhere for another.
+ */
+export type AgentBudget = {
+    /**
+     * Which entitlement the budget is written against - a credit currency or a metered feature.
+     *
+     * Required, because an assignment is written over `(entity x entitlement)`: a limit with
+     * nothing to write it against has nowhere to land.
+     */
+    entitlement: Entitlement;
     /** ISO-8601 single-unit reset window, e.g. 'P1M'. Governance requires it when creating a budget. */
     cadence?: string;
-};
+    /** Places the agent under a parent entity. Tri-state: omit to leave it, null to make it a root. */
+    parentId?: string | null;
+} & ({
+    /** The limit, written on every call. `null` clears whatever is assigned. */
+    limit?: number | null;
+    /** Writes the limit every time. The default. */
+    apply?: 'always';
+} | {
+    /** The limit to seed with. Not nullable: there is nothing to clear on an agent being created. */
+    limit: number;
+    /**
+     * Writes the limit only when this agent has no assignment yet.
+     *
+     * Reach for it when an admin may change the budget out of band - `'always'` would overwrite
+     * their change on every process start.
+     */
+    apply: 'on-create';
+});
 export type AgentScope = {
     /** The tenant. Every governance call is scoped to one customer. */
     customerId: string;
-    /**
-     * Which entitlement the budget is written against. Optional only because a bare registration is
-     * an identity and nothing else, and a metering-only run has none to hand over. A call carrying
-     * `usageLimit`, `usageLimitOnCreate` or `parentId` still needs one and `register` refuses it
-     * without: an assignment is written over `(entity x entitlement)`, so a placement with nothing
-     * to write it against has nowhere to land.
-     */
-    entitlement?: Entitlement;
 };
 /** `register` - the standalone call, which has no run to take the scope from. */
 export type RegisterInput = AgentOptions & AgentScope;
@@ -440,7 +529,7 @@ type GatedMethod<F, Ctx> = F extends {
  * The client's own surface, with every gated method taught to accept a `stiggContext`.
  *
  * Rebuilt structurally, which on its own would lose the vendor's class identity - so
- * {@link GovernedClient} intersects it back with `T` rather than replacing it. The overlay comes
+ * {@link WrappedClient} intersects it back with `T` rather than replacing it. The overlay comes
  * first in that intersection on purpose: an intersection of two call signatures is an overload
  * set resolved in order, and the vendor's own signature would reject `stiggContext` as an excess
  * property if it were tried first.
@@ -481,24 +570,24 @@ export type CallContext<Wrapped> = Wrapped extends {
  * A vendor client bound to this environment. Every call its recipe covers is checked before it
  * leaves and metered after, against the context `wrap` was given and whatever the call overrides.
  */
-export type GovernedClient<T, Wrapped = StiggContext, Paths extends readonly string[] = GatedPath> = GatedSurface<T, CallContext<Wrapped>, Paths> & T & {
+export type WrappedClient<T, Wrapped = StiggContext, Paths extends readonly string[] = GatedPath> = GatedSurface<T, CallContext<Wrapped>, Paths> & T & {
     /** What this client did, and what is still in flight. */
     readonly stigg: ClientGovernance;
 };
 /** The governance handle hung off a wrapped client. */
 export type ClientGovernance = {
     /** Waits for in-flight ingests, then reports what this client did. */
-    flush(): Promise<GovernanceSummary>;
+    flush(): Promise<SessionSummary>;
     /** Drains, then releases what this client holds. */
     close(): Promise<void>;
     /** What this client has done so far, without waiting. */
-    summary(): GovernanceSummary;
+    summary(): SessionSummary;
     /** The last decision this client made, or undefined if it has made none. */
-    readonly lastDecision?: GovernanceDecision;
+    readonly lastDecision?: AccessDecision;
     /** The `x-stigg-*` attribution for work continuing in another process. */
     headers(override?: StiggContext): GovernanceHeaders;
     /** The gate, for a call this client does not wrap. */
-    check(override?: StiggContext, requestedUsage?: number): Promise<GovernanceDecision>;
+    check(override?: StiggContext, requestedUsage?: number): Promise<AccessDecision>;
     /** The meter, for usage this client did not observe. */
     report(metrics: Metrics, override?: StiggContext): Promise<IngestResult>;
 };

package/dist/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.creditsPerTokens = exports.toMeasurement = exports.vendorMetrics = exports.emptyTokenUsage = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = void 0;
+exports.unitsPerTokens = exports.wholeUnitsForGovernance = exports.toMeasurement = exports.vendorMetrics = exports.emptyTokenUsage = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = void 0;
 exports.entitlementError = entitlementError;
 exports.usageValueError = usageValueError;
 /**
@@ -63,35 +63,85 @@ exports.vendorMetrics = vendorMetrics;
 /** A binding may report either shape; `TokenUsage` is the common case and stays terse. */
 const toMeasurement = (value) => 'input' in value ? { usage: value } : value;
 exports.toMeasurement = toMeasurement;
+/**
+ * The amount to report when this run is attributed to a governance entity.
+ *
+ * Governance counts in whole units and cannot be made to count otherwise from here: its ingest
+ * schema is `z.number().int()`, and the counter behind it is a Redis `HINCRBY`, which takes an
+ * integer delta. A fractional amount is rejected at that boundary - the wallet still moves, the
+ * per-entity counter does not, and nothing in the response says so. An agent's budget silently
+ * stops advancing while its spend carries on.
+ *
+ * So an attributed run rounds up, and only an attributed run: a run that names no entity reports
+ * what its mapper produced, because the wallet takes fractions and nothing downstream of it
+ * counts in whole units.
+ *
+ * Rounding *up* rather than to nearest, because a call that happened must cost something: at any
+ * sane denomination most calls are worth less than one unit, and rounding to nearest would bill
+ * nothing for nearly all of them.
+ *
+ * TODO: delete this, and the call sites that use it, once governance counts fractional usage.
+ * The platform fix is to scale internally - store micro-units and accept fractions at the API
+ * boundary - which keeps `HINCRBY` working and is the only way an agent budget can be
+ * denominated finely enough to price a call worth a tenth of a cent. Until then this is a
+ * deliberate overcharge on small calls, which is why it is announced rather than silent.
+ */
+const wholeUnitsForGovernance = (value) => Math.ceil(value);
+exports.wholeUnitsForGovernance = wholeUnitsForGovernance;
 /**
  * Why a measured value cannot be reported, if it cannot.
  *
  * Zero is not an error - a cached refusal or an empty stream is a normal turn - but a mapper
  * dividing by an unset config returns NaN or Infinity, and reading those as "nothing was used"
- * meters the run at zero while every call still reports success. Those are refused in both modes;
- * a fraction is refused only under `'sync'`, whose DTO takes whole units.
+ * meters the run at zero while every call still reports success. Those are refused everywhere.
+ *
+ * A fraction is refused on one path only, and the rule is the endpoint's rather than this SDK's:
+ *
+ * - **The wallet** takes them. `credits.consumption.consume` and its async twin accept a
+ *   fractional `amount`, and balances are fractional too - which they have to be, or a currency
+ *   could never be denominated finely enough to price a call worth a tenth of a cent.
+ * - **An event** takes them. The number rides as a dimension and a meter sums what it finds,
+ *   which is the only way a gateway's `cost` reports honestly.
+ * - **The usage report** does not: `POST /api/v1/usage` answers
+ *   `400 Expected integer, received float`. That is the one case refused here, where the caller
+ *   can still see which metric it was - metering failures are swallowed into `onError`, so a 400
+ *   three frames down is a silent gap rather than an error anyone reads.
  *
  * Shared, because every path that reports usage has to answer this the same way.
  */
-function usageValueError(value, mode = 'sync') {
+function usageValueError(value, mode = 'sync', 
+// Whether this metric draws the credit wallet rather than reporting a feature. The wallet takes
+// fractions in both modes, so what the ingest mode decides does not apply to it.
+drawsWallet = false) {
     if (!Number.isFinite(value) || value < 0) {
         return new errors_1.EngineError('ingest', `usage value must be a finite non-negative number, got ${value}`);
     }
-    // An event carries the number as a dimension for a meter to aggregate, and a meter is free to
-    // sum fractions - which is the only way a gateway's `cost` reports honestly. The usage report
-    // takes a whole number or nothing.
-    if (mode === 'async' || Number.isInteger(value))
+    if (mode === 'async' || drawsWallet || Number.isInteger(value))
         return undefined;
-    return new errors_1.EngineError('ingest', `usage value must be a positive whole number, got ${value}`);
+    return new errors_1.EngineError('ingest', `usage value must be a whole number to report against a feature, got ${value}. The usage ` +
+        'report takes integers; a credit currency takes fractions, and so does an event under ' +
+        "`ingest: 'async'`.");
 }
 /**
  * One metric, summed from every token class and divided by the unit size.
  *
- * The mapper for an application that prices tokens itself rather than letting Stigg convert a
- * credit-backed feature. Weighting cache reads cheaper is a pricing decision and belongs in
- * Stigg's consumption mapping, not here; Stigg rejects fractions, so the result rounds up.
+ * The mapper for an application that prices tokens itself. Named for what it produces - units
+ * under an id - rather than for credits, because it does not deduct any: it reports a number, and
+ * that number draws the wallet only when the id happens to name a credit currency. Which it is
+ * decides the whole ingest path, so a mapper that claimed to know was the wrong place to look.
+ *
+ * **Prefer reporting the raw counters and converting in Stigg.** A consumption mapping on the plan
+ * does the same arithmetic where a pricing change does not need a deploy, and it is the only place
+ * that can weight cache reads cheaper. Reach for this when the application deliberately prices
+ * itself.
+ *
+ * The division is reported as it comes out. A credit currency takes fractions, so a call worth
+ * four fifths of a unit costs four fifths of one - rounding it up here would be this SDK's
+ * arithmetic on someone else's price. A **feature** is the exception: `POST /api/v1/usage` takes
+ * integers, so pick a `tokensPerUnit` that divides, or round in your own mapper.
+ *
+ * @param id The Stigg feature id or credit currency id to report under.
+ * @param tokensPerUnit How many tokens make one unit.
  */
-const creditsPerTokens = (featureId, tokensPerUnit = 1) => ({ usage }) => usage
-    ? { [featureId]: Math.ceil((usage.input + usage.output + usage.cacheRead + usage.cacheCreate) / tokensPerUnit) }
-    : {};
-exports.creditsPerTokens = creditsPerTokens;
+const unitsPerTokens = (id, tokensPerUnit = 1) => ({ usage }) => usage ? { [id]: (usage.input + usage.output + usage.cacheRead + usage.cacheCreate) / tokensPerUnit } : {};
+exports.unitsPerTokens = unitsPerTokens;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -41,7 +41,8 @@
     "example-two-agents": "tsx examples/client/two-agents.ts",
     "example-gateway": "tsx examples/gateway/openrouter.ts",
     "example-gateway-openrouter": "tsx examples/gateway/openrouter.ts",
-    "example-gateway-litellm": "tsx examples/gateway/litellm.ts"
+    "example-gateway-litellm": "tsx examples/gateway/litellm.ts",
+    "example-gateway-bedrock": "tsx examples/gateway/bedrock.ts"
   },
   "nx": {
     "includedScripts": [
@@ -63,7 +64,9 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.124.0",
+    "@aws-sdk/client-bedrock-runtime": "^3.1150.0",
     "@google/genai": "^2.28.0",
+    "@openrouter/sdk": "^1.4.25",
     "@typesafe-ai/sdk": "^0.6.0",
     "dotenv": "^17.4.2",
     "openai": "^7.13.0",