@stigg/agent-sdk-js 1.0.1 → 2.0.0

package/dist/bindings/shared/token-usage.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizedMetrics = exports.addMetrics = exports.METRIC_PATHS = exports.metricNamesMatchPaths = exports.COMPUTED_TOTALS = exports.metricName = exports.GATEWAY_METRICS = exports.OPENAI_METRICS = exports.TYPESAFE_METRICS = exports.TYPESAFE_COMPONENT_METRICS = exports.OPENAI_RESPONSES_METRICS = exports.OPENAI_CHAT_METRICS = exports.GEMINI_COMPONENT_METRICS = exports.GEMINI_METRICS = exports.ANTHROPIC_METRICS = exports.ANTHROPIC_COMPONENT_METRICS = exports.TOTAL_TOKENS = exports.addTokenUsage = void 0;
+exports.normalizedMetrics = exports.addMetrics = exports.METRIC_PATHS = exports.metricNamesMatchPaths = exports.COMPUTED_TOTALS = exports.metricName = exports.BEDROCK_METRICS = exports.BEDROCK_PATHS = exports.GATEWAY_METRICS = exports.OPENAI_METRICS = exports.TYPESAFE_METRICS = exports.TYPESAFE_COMPONENT_METRICS = exports.OPENAI_RESPONSES_METRICS = exports.OPENAI_CHAT_METRICS = exports.GEMINI_COMPONENT_METRICS = exports.GEMINI_METRICS = exports.ANTHROPIC_METRICS = exports.ANTHROPIC_COMPONENT_METRICS = exports.TOTAL_TOKENS = exports.addTokenUsage = void 0;
 exports.fromFlatTokenUsage = fromFlatTokenUsage;
 exports.fromOpenAIUsage = fromOpenAIUsage;
 exports.fromResponsesUsage = fromResponsesUsage;
+exports.fromBedrockUsage = fromBedrockUsage;
 exports.fromLangChainUsage = fromLangChainUsage;
 exports.fromGeminiUsage = fromGeminiUsage;
 exports.normalizeUsage = normalizeUsage;
@@ -64,8 +65,41 @@ function fromResponsesUsage(usage) {
         input: Math.max(0, n(usage.input_tokens) - cacheRead),
         output: n(usage.output_tokens),
         cacheRead,
-        // The surface reports no cache writes of its own.
-        cacheCreate: 0,
+        // OpenAI's own Responses API reports no cache writes, so this is 0 for it either way. A
+        // gateway mirroring the surface may report them - OpenRouter does - and reading the field
+        // costs nothing where it is absent, where the alternative was dropping a counter the customer
+        // was charged for.
+        cacheCreate: n(usage.input_tokens_details?.cache_write_tokens),
+    };
+}
+/**
+ * Bedrock's Converse usage, whose four counters are disjoint.
+ *
+ * Nothing is subtracted, unlike the OpenAI and Gemini readers: AWS states that `inputTokens`
+ * already excludes whatever was read from or written to the cache, so taking the cache back out
+ * would charge the call for less than it used.
+ *
+ * The total is read, not recomputed, like every other vendor that publishes one - but it is worth
+ * knowing what it covers. AWS documents `totalTokens` as the input and output of the call, and
+ * documents `inputTokens` as cache-exclusive, so on a cached call the stated total can be smaller
+ * than the four counters add up to. Both are reported: price the breakdown if the cache matters to
+ * you, the total if it does not, and see the README's overlap table before pricing both.
+ */
+function fromBedrockUsage(usage) {
+    if (!usage)
+        return (0, types_1.emptyTokenUsage)();
+    const counted = {
+        input: n(usage.inputTokens),
+        output: n(usage.outputTokens),
+        cacheRead: n(usage.cacheReadInputTokens),
+        cacheCreate: n(usage.cacheWriteInputTokens),
+    };
+    const stated = n(usage.totalTokens);
+    return {
+        ...counted,
+        // The vendor's figure when it gave one; otherwise the sum, which is sound precisely because
+        // these four do not overlap.
+        ...withTotal(stated || counted.input + counted.output + counted.cacheRead + counted.cacheCreate),
     };
 }
 function fromLangChainUsage(usage) {
@@ -287,6 +321,26 @@ exports.OPENAI_METRICS = [
 ];
 /** A gateway speaks the OpenAI shape and adds the price it charged, under its own field name. */
 exports.GATEWAY_METRICS = [...exports.OPENAI_METRICS, 'cost'];
+/**
+ * Bedrock's five, under its own names and with no price among them.
+ *
+ * Reported verbatim rather than translated into the OpenAI spelling, which is the rule everywhere
+ * except where one service is reachable through two different clients - see `sdk-usage.ts` for
+ * that exception. Bedrock is reached one way, so its own names are the honest ones, and a reader
+ * comparing a Stigg meter against an AWS bill is comparing like with like.
+ *
+ * No `cost`: Bedrock states no price on the response, which is the thing that most separates it
+ * from the other two gateways here. See the recipe for what that costs a run.
+ */
+exports.BEDROCK_PATHS = [
+    'inputTokens',
+    'outputTokens',
+    'cacheReadInputTokens',
+    'cacheWriteInputTokens',
+    'totalTokens',
+];
+/** Those five. Flat, so the paths are the names. */
+exports.BEDROCK_METRICS = exports.BEDROCK_PATHS;
 /** The leaf a dotted path reports under - `prompt_tokens_details.cached_tokens` -> `cached_tokens`. */
 const metricName = (path) => path.split('.').pop();
 exports.metricName = metricName;
@@ -331,6 +385,7 @@ exports.METRIC_PATHS = {
     openaiResponses: OPENAI_RESPONSES_PATHS,
     typesafe: TYPESAFE_PATHS,
     gemini: GEMINI_PATHS,
+    bedrock: exports.BEDROCK_PATHS,
 };
 /**
  * Reads the named keys off a vendor's usage object, dotted paths included.

package/dist/bindings/shared/types.d.ts

@@ -39,8 +39,24 @@ export type ResponsesLikeUsage = {
     total_tokens?: number | null;
     input_tokens_details?: {
         cached_tokens?: number | null;
+        cache_write_tokens?: number | null;
     } | null;
 };
+/**
+ * Bedrock's Converse `usage`. Flat, camelCased, and **disjoint**.
+ *
+ * AWS is explicit that `inputTokens` counts only the tokens that were neither read from nor
+ * written to the cache - "total input tokens = inputTokens + cacheReadInputTokens +
+ * cacheWriteInputTokens" - so this shape behaves like Anthropic's and not like OpenAI's, where the
+ * cached count nests inside the prompt count. Subtracting here would undercount the call.
+ */
+export type BedrockLikeUsage = {
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    totalTokens?: number | null;
+    cacheReadInputTokens?: number | null;
+    cacheWriteInputTokens?: number | null;
+};
 /** LangChain's `usage_metadata`, as carried on an AIMessage. */
 export type LangChainLikeUsage = {
     input_tokens?: number | null;

package/dist/bindings/shared/weighted-metrics.js

@@ -38,7 +38,10 @@ function weightedMetrics(recipe, target, weights, options = {}) {
         // counts as the no-op ingest it is rather than as a report of zero.
         if (weighted <= 0)
             return {};
-        // Stigg takes whole units, and rounding down would bill nothing for a turn that did happen.
-        return { [target]: Math.ceil(weighted / per) };
+        // Reported as it came out of the weights. A credit currency takes fractions, so a turn worth
+        // a fifth of a unit costs a fifth - rounding here would be this SDK's arithmetic on someone
+        // else's price. A feature is the exception, since `POST /api/v1/usage` takes integers: choose
+        // `per` so the weights divide, or round in a mapper of your own.
+        return { [target]: weighted / per };
     };
 }

package/dist/config.d.ts

@@ -15,19 +15,6 @@ import { type Logger } from './logger';
 import type { CacheOptions, NodeSdkClient } from './engine/node-sdk-engine';
 import type { CheckErrorAction, IngestMode } from './types';
 import type { EngineError } from './errors';
-/**
- * Where the SDK sends its traffic, and how it identifies itself there.
- *
- * Either a server key - which names an environment on the hosted API - or a base URL that needs
- * no key, which is a local stand-in, a self-hosted deployment, or the built-in mock. They are one
- * positional parameter rather than two options fields precisely so they cannot both be given:
- * "an API key or a URL" is the real rule, and a union says it without a runtime check to fail.
- *
- * A self-hosted deployment that *does* want a key passes the key here and the URL in options.
- */
-export type StiggTarget = string | {
-    baseUrl: string;
-};
 declare const dataSchema: z.ZodObject<{
     apiKey: z.ZodString;
     baseUrl: z.ZodOptional<z.ZodString>;
@@ -50,11 +37,33 @@ export type ErrorContext = {
     customerId?: string;
 };
 /**
- * The second constructor argument: policy and transport, all of it optional and all of it with a
- * working default. Nothing required lives here - the one thing the SDK cannot infer is the
- * target, and that is the first argument.
+ * Everything the SDK can be told, in one object.
+ *
+ * All of it optional and all of it with a working default, including where to send traffic: the
+ * key falls back to `STIGG_SERVER_API_KEY` and the URL to the hosted API, so the smallest working
+ * program is `new StiggAgentSDK()`.
+ *
+ * One object rather than positional arguments so that each answer has exactly one place to go -
+ * a URL given in two places needs a runtime check to refuse both, and an optional argument in
+ * front of a required one forces `undefined` placeholders at the call site.
  */
 export type StiggAgentSDKOptions = {
+    /**
+     * The server key, which names the environment. Falls back to `STIGG_SERVER_API_KEY`, the way
+     * every vendor SDK does - **including when `baseUrl` is set**, since a URL says where traffic
+     * goes and nothing about who is sending it.
+     *
+     * So a shell with that variable exported sends it to whatever `baseUrl` names, a local mock
+     * included. To run keyless on such a machine, unset the variable for the process rather than
+     * relying on `baseUrl` to suppress it: a deployment that genuinely needs no key is the case
+     * where nothing is configured anywhere, and that is the one the fallback below serves.
+     */
+    apiKey?: string;
+    /**
+     * Where to send traffic, when it is not the hosted API. Pass it alongside `apiKey` for a
+     * self-hosted deployment that still wants a key, or on its own for one that needs none.
+     */
+    baseUrl?: string;
     /**
      * How checks are cached. See {@link CacheOptions} - it is the Node server SDK's own cache
      * configuration, passed through, because that is where caching actually happens.
@@ -124,7 +133,7 @@ export type ResolvedConfig = Omit<Required<z.infer<typeof dataSchema>>, 'baseUrl
     logger: Logger;
     onError: (error: EngineError, context: ErrorContext) => void;
 };
-export declare function resolveConfig(target?: StiggTarget, baseUrl?: string, options?: StiggAgentSDKOptions): ResolvedConfig;
+export declare function resolveConfig(options?: StiggAgentSDKOptions): ResolvedConfig;
 /** The slice of config the engine factory needs. */
 export type EngineConfig = {
     apiKey: string;

package/dist/config.js

@@ -35,37 +35,39 @@ const resolveLogger = (logger) => {
     return logger;
 };
 /**
- * The target, split into the key and the URL the transport actually needs.
+ * The key to send, which is the environment's identity.
  *
- * An absent target falls back to the environment variable, the way every vendor SDK does, so the
- * smallest working program is `new StiggAgentSDK()`. The failure for a missing key is raised here
- * rather than left to zod, because "set STIGG_SERVER_API_KEY" is the actionable half and the
- * schema only knows the field was too short.
+ * The environment variable is tried before the keyless fallback, and that order is the whole of
+ * it. A `baseUrl` says *where* to send traffic and nothing about who is sending it, so the two
+ * are independent: a self-hosted deployment names its URL in options and keeps its key in
+ * `STIGG_SERVER_API_KEY`, and substituting a sentinel there would 401 with nothing in the config
+ * to say why.
+ *
+ * {@link KEYLESS} is the last resort, not the rule: it stands in for a deployment that needs no
+ * key at all - a local stand-in, or the built-in mock - and exists only because the schema below
+ * demands a non-empty string. Nothing authenticates with it.
+ *
+ * The failure for a missing key is raised here rather than left to zod, because "set
+ * STIGG_SERVER_API_KEY" is the actionable half and the schema only knows the field was too short.
  */
-function resolveTarget(target) {
-    if (typeof target === 'object')
-        return { apiKey: KEYLESS, baseUrl: target.baseUrl };
-    const apiKey = (target ?? process.env.STIGG_SERVER_API_KEY)?.trim();
-    if (!apiKey) {
-        throw new Error('No Stigg API key - pass a server key as the first argument, or set STIGG_SERVER_API_KEY. ' +
-            'To run without one, pass a target with a `baseUrl` instead: a local stand-in, a ' +
-            'self-hosted deployment, or the built-in mock.');
-    }
-    return { apiKey };
+function resolveApiKey({ apiKey, baseUrl }) {
+    const named = apiKey?.trim();
+    if (named)
+        return named;
+    const fromEnv = process.env.STIGG_SERVER_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    // No key anywhere. A URL to send to is the one case where that is a configuration rather than
+    // an omission.
+    if (baseUrl)
+        return KEYLESS;
+    throw new Error('No Stigg API key - pass `apiKey`, or set STIGG_SERVER_API_KEY. To run without one, pass ' +
+        '`baseUrl` instead: a local stand-in, a self-hosted deployment, or the built-in mock.');
 }
-function resolveConfig(target, baseUrl, options = {}) {
-    const resolved = resolveTarget(target);
-    // A keyless target *is* a base URL, so naming a second one is two answers to one question.
-    // Refused rather than silently preferred: whichever the SDK picked, the other would be a URL
-    // the caller believes it is talking to and is not.
-    if (resolved.baseUrl && baseUrl) {
-        throw new Error(`This SDK was given a target with its own baseUrl (${resolved.baseUrl}) and a second one ` +
-            `(${baseUrl}). Pass the URL once: as the target when it needs no key, or as the second ` +
-            'argument alongside a key.');
-    }
+function resolveConfig(options = {}) {
     const parsed = dataSchema.parse({
-        apiKey: resolved.apiKey,
-        baseUrl: resolved.baseUrl ?? baseUrl,
+        apiKey: resolveApiKey(options),
+        baseUrl: options.baseUrl,
         checkErrorAction: options.checkErrorAction,
         ingest: options.ingest,
         timeoutMs: options.timeoutMs,

package/dist/core/context.d.ts

@@ -1,12 +1,5 @@
 import type { CheckErrorAction, Entitlement, IngestMode, Metrics, MetricsMapper } from '../types';
 import type { EventIngest } from '../engine/engine';
-/** The entity type an agent is provisioned and attributed as. Both halves, because they must agree. */
-export type AgentType = {
-    /** The governance entity type, as it exists in the account. */
-    entityTypeId: string;
-    /** The attribution key that type declares, under which `agentId` is sent on every call. */
-    attributionKey: string;
-};
 /**
  * What a call is governed by. Every field is optional here because each one may have been given
  * at `wrap` instead - `customerId` is the only one that has to come from somewhere, and the
@@ -16,15 +9,22 @@ export type StiggContext = {
     /** The tenant. Every governance call is scoped to one customer. */
     customerId?: string;
     /**
-     * The agent this call spends as. Travels as a dimension under {@link AgentType.attributionKey},
-     * which is the entire mechanism by which an agent is attributed - so naming one without an
-     * `agentType` is refused rather than guessed at.
+     * The agent this call spends as. Travels as a dimension under
+     * {@link StiggContext.attributionKey}, which is the entire mechanism by which an agent is
+     * attributed - so naming one without a key is refused rather than guessed at.
      *
      * Omitted, the call resolves no entity and is checked against the customer's own budget.
      */
     agentId?: string;
-    /** The entity type `agentId` is identified as. Required whenever `agentId` is given. */
-    agentType?: AgentType;
+    /**
+     * The key the agent's entity type declares, under which `agentId` is sent on every call.
+     * Required whenever `agentId` is given, and not defaulted: a guessed key resolves no entity, so
+     * the spend lands on the customer looking exactly like a call that was never governed.
+     *
+     * `register` takes an `entityTypeId` as well, because that call creates the entity. Attributing
+     * a call does not need to know what type it was created as - only what key to send it under.
+     */
+    attributionKey?: string;
     /**
      * Extra attribution, sent verbatim on the check and the report. Every key must be an attribution
      * key on one of the entity types involved, or it matches nothing and the usage rolls up to the
@@ -101,6 +101,15 @@ export type ResolvedContext = {
     correlationId: string;
     /** The entitlement's own id, resolved once - undefined when this context gates on nothing. */
     checkedId?: string;
+    /**
+     * Kept so a per-call `agentId` can inherit it.
+     *
+     * The key belongs to the entity type, which is a property of the client, while the agent varies
+     * per call - so naming it once at `wrap` and then only the agent per call is the shape a
+     * multi-agent server wants. The folded dimension alone would not do: an override needs the key
+     * itself to build its own.
+     */
+    attributionKey?: string;
 };
 /**
  * What nobody told the SDK, and it will not guess.

package/dist/core/context.js

@@ -50,13 +50,13 @@ function agentDimension(context) {
     if (!context.agentId.trim()) {
         throw new Error('stiggContext.agentId is empty - an agent nobody can name is also one nothing can bill.');
     }
-    if (!context.agentType) {
-        throw new Error(`stiggContext.agentId is '${context.agentId}' but no agentType says which key to send it under. ` +
-            'Pass `agentType: { entityTypeId, attributionKey }` - the pair the entity type was created ' +
-            'with. Without it the agent resolves no entity and the spend lands on the customer, which ' +
-            'looks exactly like a call that was never governed.');
+    if (!context.attributionKey?.trim()) {
+        throw new Error(`stiggContext.agentId is '${context.agentId}' but no attributionKey says which key to send ` +
+            "it under. Pass the key the agent's entity type declares. Without it the agent resolves " +
+            'no entity and the spend lands on the customer, which looks exactly like a call that was ' +
+            'never governed.');
     }
-    return { [context.agentType.attributionKey]: context.agentId };
+    return { [context.attributionKey]: context.agentId };
 }
 /**
  * Validates and derives, once. Everything expensive about a context happens here rather than on
@@ -71,6 +71,10 @@ function resolveContext(context, correlationId,
 // `wrap` passes false: a client whose calls each name their own customer is legal, and its
 // types already say which calls still owe one. Every path that reaches the engine resolves it.
 { requireCustomer = true, defaults } = {}) {
+    // Checked here as well as in `overrideContext`, and this is the half that matters more: `wrap`
+    // names an agent and its entitlement once for every call through the client, so a typo here
+    // governs *everything* by the fallback rather than one call.
+    assertKnownContext(context, requireCustomer ? 'stiggContext' : "wrap's stiggContext");
     const customerId = context.customerId?.trim() ?? '';
     if (!customerId && requireCustomer)
         throw (0, exports.noCustomer)();
@@ -95,8 +99,58 @@ function resolveContext(context, correlationId,
         idempotencyKey: context.idempotencyKey,
         correlationId: context.correlationId?.trim() || correlationId,
         checkedId: context.entitlement ? (0, types_1.entitlementId)(context.entitlement) : undefined,
+        attributionKey: context.attributionKey,
     };
 }
+/**
+ * Every field a `stiggContext` may carry.
+ *
+ * Typed as a total record of `keyof StiggContext` rather than written as a list, so a field added
+ * to the context without being added here is a compile error instead of a key this rejects.
+ */
+const CONTEXT_KEYS = {
+    customerId: true,
+    agentId: true,
+    attributionKey: true,
+    dimensions: true,
+    entitlement: true,
+    checkErrorAction: true,
+    usageMapper: true,
+    ingestMode: true,
+    eventName: true,
+    idempotencyKey: true,
+    correlationId: true,
+};
+/**
+ * Refuses a context carrying a field this SDK does not read.
+ *
+ * Almost always a typo, and a silent one without this: the context is read key by key, so an
+ * unknown key simply never arrives. A call meaning to spend as one agent spends as whatever
+ * `wrap` was given instead, and the only trace is a bill against the wrong entity.
+ *
+ * The types catch it everywhere but `messages.stream`, which Anthropic declares generic -
+ * `stream<Params extends MessageStreamParams>(body: Params, ...)` - and a generic parameter
+ * infers from its argument rather than checking it for excess properties. `WrappedClient`
+ * intersects the overlay with the vendor's own type to stay assignable to it, and an intersection
+ * of call signatures is an overload set resolved in order, so a context the overlay rejects falls
+ * through to that signature and is taken. Hence the runtime guarantee, which covers every surface
+ * as well as JS callers and hand-typed call sites.
+ *
+ * Thrown rather than warned, like the other guards in this file: the call it would have governed
+ * is in front of money, and a warning is read after the bill.
+ *
+ * `Object.hasOwn` rather than `in`, which walks the prototype chain and so answers true for
+ * `toString`, `constructor` and `hasOwnProperty` - the names likeliest to arrive from a JS caller
+ * building a context out of an object it did not create.
+ */
+function assertKnownContext(context, where) {
+    for (const key of Object.keys(context)) {
+        if (Object.hasOwn(CONTEXT_KEYS, key))
+            continue;
+        throw new Error(`${where} has no field \`${key}\` - this SDK would ignore it, and the call would be ` +
+            `governed by whatever remained instead. Valid fields: ${Object.keys(CONTEXT_KEYS).join(', ')}.`);
+    }
+}
 /**
  * One call's override, applied over what `wrap` already resolved.
  *
@@ -106,6 +160,7 @@ function resolveContext(context, correlationId,
  * fields last, because nothing before the response depends on them.
  */
 function overrideContext(base, override) {
+    assertKnownContext(override, 'stiggContext');
     // The cheap test first: these are the only fields that can change which budget is consulted,
     // so a call overriding only, say, `idempotencyKey` re-derives nothing.
     const rebased = override.customerId !== undefined ||
@@ -125,10 +180,21 @@ function overrideContext(base, override) {
             entitlement = override.entitlement;
             checkedId = (0, types_1.entitlementId)(override.entitlement);
         }
+        // The key falls back to the client's own, so a call naming a different agent of the same type
+        // need only name the agent - which is the multi-agent case, and the common one.
+        const attributionKey = override.attributionKey ?? base.attributionKey;
+        const agent = agentDimension({ ...override, attributionKey });
         // Merged per key, not replaced: a per-call tenant must not drop the client's own attribution.
-        const agent = agentDimension({ ...override, agentType: override.agentType });
-        dimensions =
-            override.dimensions || agent ? { ...base.dimensions, ...override.dimensions, ...agent } : base.dimensions;
+        //
+        // With one exception. An override naming a *different* entity type writes its agent under a
+        // different key, and the client's own key would otherwise ride along beside it - two agent
+        // dimensions on one call, which governance resolves as two entities and bills accordingly.
+        // That one is dropped by name: it describes an agent this call is not acting as. Every other
+        // dimension the client set is kept, because none of them is claiming to be the agent.
+        const inherited = agent && base.attributionKey && attributionKey !== base.attributionKey
+            ? Object.fromEntries(Object.entries(base.dimensions).filter(([key]) => key !== base.attributionKey))
+            : base.dimensions;
+        dimensions = override.dimensions || agent ? { ...inherited, ...override.dimensions, ...agent } : base.dimensions;
     }
     return {
         customerId,
@@ -141,6 +207,7 @@ function overrideContext(base, override) {
         usageMapper: override.usageMapper ?? base.usageMapper,
         idempotencyKey: override.idempotencyKey ?? base.idempotencyKey,
         correlationId: override.correlationId?.trim() || base.correlationId,
+        attributionKey: override.attributionKey ?? base.attributionKey,
     };
 }
 /** Whether a context gates at all. The enforcement switch, read on every call. */

package/dist/core/session.d.ts

@@ -4,13 +4,35 @@ import { type ResolvedContext } from './context';
 import type { GovernanceEngine } from '../engine/engine';
 import type { ErrorContext } from '../config';
 import type { Logger } from '../logger';
-import { type GovernanceDecision, type IngestResult, type Measurement, type Metrics, type TokenUsage } from '../types';
+import { type AccessDecision, type IngestResult, type Measurement, type Metrics, type TokenUsage } from '../types';
 /** Everything the session reports back while it works. Set once, at `wrap`. */
+/**
+ * Who the observation was for, which the observation itself cannot say.
+ *
+ * Neither an {@link AccessDecision} nor an {@link IngestResult} names the caller: `deniedBy`
+ * appears only on a refusal and names the entity that blocked, not the agent that asked. So one
+ * client serving several agents produced a stream of events nothing could attribute, and the only
+ * way to tell them apart was a separate wrapped client per agent - each with its own session
+ * state, which is a real cost rather than an inconvenience.
+ *
+ * `correlationId` is the one to reach for when reconciling: it ties a decision to the ingest that
+ * followed it, which is what anyone chasing a billing discrepancy actually needs.
+ */
+export type HookContext = {
+    /** The tenant this call was scoped to. */
+    customerId: string;
+    /** What it was attributed by - the agent under its entity type's own key, plus any extra. */
+    dimensions: Record<string, string>;
+    /** Shared by every observation of one call, and sent on the wire as `x-stigg-run-id`. */
+    correlationId: string;
+    /** What the call gated on, when it gated on anything. Undefined on a metering-only run. */
+    entitlementId?: string;
+};
 export type SessionHooks = {
     /** Every check this client makes. The whole decision, already formatted as `.summary`. */
-    onDecision?: (decision: GovernanceDecision) => void;
+    onDecision?: (decision: AccessDecision, context: HookContext) => void;
     /** Every ingest this client makes - including the ones that failed. */
-    onIngest?: (result: IngestResult) => void;
+    onIngest?: (result: IngestResult, context: HookContext) => void;
 };
 export type SessionDeps = {
     /**
@@ -28,7 +50,7 @@ export type SessionDeps = {
     hooks: SessionHooks;
 };
 /** What a client did, for whoever wants to print it. Spans every context it served. */
-export type GovernanceSummary = {
+export type SessionSummary = {
     checks: number;
     ingested: number;
     /**
@@ -40,7 +62,7 @@ export type GovernanceSummary = {
      */
     reported: Metrics;
     ingestFailures: number;
-    lastDecision?: GovernanceDecision;
+    lastDecision?: AccessDecision;
 };
 export type IngestOptions = {
     /** Overrides the context's own name for this one report - the vendor method that was gated. */
@@ -66,8 +88,10 @@ export declare class GovernanceSession {
     private decision?;
     /** The unmapped-feature warning is said once per client, not once per call. */
     private warnedUnmapped;
+    /** Said once per client: the reason is the same every call, and so is the fix. */
+    private warnedRounded;
     constructor(deps: SessionDeps);
-    get lastDecision(): GovernanceDecision | undefined;
+    get lastDecision(): AccessDecision | undefined;
     /** The attribution to send downstream when part of the work happens in another process. */
     headers(context: ResolvedContext): GovernanceHeaders;
     /**
@@ -87,7 +111,7 @@ export declare class GovernanceSession {
      * The enforcement path. Returns a decision, never throws - a refusal is a commercial event the
      * application routes on, not an exception it recovers from.
      */
-    check(context: ResolvedContext, requestedUsage?: number): Promise<GovernanceDecision>;
+    check(context: ResolvedContext, requestedUsage?: number): Promise<AccessDecision>;
     /** Applies the context's mapper to a token measurement. The path every binding uses. */
     ingestTokens(context: ResolvedContext, usage: TokenUsage, options?: IngestOptions): Promise<IngestResult>;
     /**
@@ -127,8 +151,8 @@ export declare class GovernanceSession {
      */
     failedToMeasure(context: ResolvedContext, err: unknown): void;
     /** Waits for in-flight ingests, so a caller knows what was actually delivered. */
-    drain(): Promise<GovernanceSummary>;
-    summary(): GovernanceSummary;
+    drain(): Promise<SessionSummary>;
+    summary(): SessionSummary;
     /** `correlationId:n` - distinct per call, for a vendor that offered no id of its own. */
     private nextKey;
     /**
@@ -144,6 +168,11 @@ export declare class GovernanceSession {
      * so the most that can be said is that nothing reported names what this call checks, and whether
      * a meter closes that gap is configuration this process cannot see.
      */
+    /**
+     * Says that an attributed run rounded, because an overcharge the caller did not ask for must
+     * not be silent - that silence is the thing this SDK was told off for in the first place.
+     */
+    private warnRounded;
     private warnIfNothingDrains;
     private record;
     /**