@stigg/agent-sdk-js 1.1.0 → 2.0.0

package/dist/core/session.js

@@ -31,6 +31,13 @@ const dimensions_1 = require("./dimensions");
 const hooks_1 = require("./hooks");
 const context_1 = require("./context");
 const types_1 = require("../types");
+/** What a context looks like to a hook: the attribution, and nothing a hook could change. */
+const hookContext = (context) => ({
+    customerId: context.customerId,
+    dimensions: context.dimensions,
+    correlationId: context.correlationId,
+    entitlementId: context.checkedId,
+});
 /** A metric nobody can bill: refused where the mapper that invented it can still be found. */
 const emptyMetricNameError = () => new errors_1.EngineError('measure', 'a metric needs a name - an empty one reports to no feature at all.');
 /**
@@ -53,6 +60,8 @@ class GovernanceSession {
     decision;
     /** The unmapped-feature warning is said once per client, not once per call. */
     warnedUnmapped = false;
+    /** Said once per client: the reason is the same every call, and so is the fix. */
+    warnedRounded = false;
     constructor(deps) {
         this.deps = deps;
     }
@@ -65,6 +74,10 @@ class GovernanceSession {
             [headers_1.GOVERNANCE_HEADERS.customer]: context.customerId,
             [headers_1.GOVERNANCE_HEADERS.dimensions]: JSON.stringify(context.dimensions),
             [headers_1.GOVERNANCE_HEADERS.run]: context.correlationId,
+            // Which of those dimensions is the agent. Only this side knows: the receiver sees a flat
+            // map and cannot tell attribution from metadata. Empty when the run names no agent, which
+            // is a receiver that should round nothing.
+            [headers_1.GOVERNANCE_HEADERS.attributionKey]: context.attributionKey ?? '',
         };
     }
     /**
@@ -100,7 +113,7 @@ class GovernanceSession {
         // budget to consult and no refusal that could come back. Still counted and recorded, because
         // the caller did ask and `lastDecision` is where they read what they got.
         if (!entitlement)
-            return this.record((0, decision_1.unenforcedDecision)());
+            return this.record((0, decision_1.unenforcedDecision)(), context);
         try {
             const engine = await this.deps.engine();
             const result = await engine.check(context.customerId, {
@@ -108,14 +121,14 @@ class GovernanceSession {
                 requestedUsage,
                 dimensions: context.dimensions,
             });
-            return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId }));
+            return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId, entitlement: context.entitlement }), context);
         }
         catch (err) {
             const error = asEngineError('check', err);
             this.reportError(error, 'check', context);
             // Governance is fail-closed server-side; `'deny'` mirrors that, and `'allow'` - the default -
             // is the soft limit that keeps the application up while Stigg is unreachable.
-            return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'));
+            return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context);
         }
     }
     /** Applies the context's mapper to a token measurement. The path every binding uses. */
@@ -195,17 +208,36 @@ class GovernanceSession {
         // survives into an event and is dropped from a usage report: a meter may filter on a field
         // being present, and an event that omits it on a cache miss changes shape call to call, while
         // a usage report of zero is a request that moves nothing.
+        // Which metric draws the wallet, which is what decides whether a fraction is legal: the one
+        // named after the currency this context checks goes to `consumeCredits`, and everything else
+        // to the usage report or an event. The same split `reportMetrics` makes further down.
+        const creditCurrencyId = context.entitlement && (0, types_1.entitlementKind)(context.entitlement) === 'credit' ? context.checkedId : undefined;
+        // Whether this run is attributed to a governance entity, which is what decides whether a
+        // fraction can be counted. See `wholeUnitsForGovernance`.
+        const attributed = !!context.attributionKey && !!context.dimensions[context.attributionKey];
         const sendable = {};
         let rejected;
-        for (const [featureId, value] of Object.entries(metrics)) {
+        for (const [featureId, rawValue] of Object.entries(metrics)) {
+            const drawsWallet = featureId === creditCurrencyId;
+            // The mapper's own number is what gets validated, before any rounding of ours. Rounding
+            // first laundered a negative into a success: `Math.ceil(-0.5)` is `-0`, which is not `< 0`,
+            // so it passed the guard that exists to catch it, was then dropped for not being `> 0`, and
+            // reported as the no-op ingest that an empty turn is. A mapper returning a negative would
+            // have been told it succeeded.
+            //
             // The key is the feature id this spend lands on, and the mapper that produced it is the
             // application's own function. An empty one is validated by nothing downstream - the value is
             // checked, the key is not - so it would report to a feature that cannot exist, answer `ok`,
             // and move no budget: the failure that looks like success, from a typo.
-            const invalid = featureId.trim() ? (0, types_1.usageValueError)(value, mode) : emptyMetricNameError();
-            if (invalid)
+            const invalid = featureId.trim() ? (0, types_1.usageValueError)(rawValue, mode, drawsWallet) : emptyMetricNameError();
+            if (invalid) {
                 rejected ??= invalid;
-            else if (value > 0 || mode === 'async')
+                continue;
+            }
+            const value = attributed && drawsWallet ? (0, types_1.wholeUnitsForGovernance)(rawValue) : rawValue;
+            if (value !== rawValue)
+                this.warnRounded(featureId, rawValue, value);
+            if (value > 0 || mode === 'async')
                 sendable[featureId] = value;
         }
         // Zero-token calls are normal (a cached refusal, an empty stream); they are not an error. They
@@ -216,7 +248,7 @@ class GovernanceSession {
                 return Promise.resolve(this.failedIngest(context, idempotencyKey, rejected));
             this.ingested += 1;
             const noop = { ok: true, reported: {}, idempotencyKey, mode, replayed: false };
-            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(noop));
+            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(noop, hookContext(context)));
             return Promise.resolve(noop);
         }
         const promise = this.deps
@@ -260,7 +292,7 @@ class GovernanceSession {
                 this.ingestFailures += 1;
                 this.reportError(rejected, rejected.operation, context, idempotencyKey);
             }
-            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(landed));
+            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(landed, hookContext(context)));
             return landed;
         })
             .catch((err) => this.failedIngest(context, idempotencyKey, asEngineError('ingest', err)))
@@ -314,6 +346,19 @@ 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.
+     */
+    warnRounded(featureId, from, to) {
+        if (this.warnedRounded)
+            return;
+        this.warnedRounded = true;
+        this.deps.logger.warn(`[stigg] rounded ${featureId} up from ${from} to ${to}: this run is attributed to a governance ` +
+            'entity, and per-entity usage is counted in whole units. An unattributed run reports the ' +
+            'fraction as measured. Denominate the currency finely enough that one unit is small, or ' +
+            'drop the agent attribution to meter exactly.');
+    }
     warnIfNothingDrains(context, result, sent) {
         if (this.warnedUnmapped)
             return;
@@ -339,9 +384,9 @@ class GovernanceSession {
         this.deps.logger.warn(`[stigg] reported ${names} but the response carried no credit balance - ${names.includes(',') ? 'these features are' : 'this feature is'} not mapped to ${checked}, so the budget this call checks ` +
             'against will never drain. Map it in Stigg, or report to the currency directly.');
     }
-    record(decision) {
+    record(decision, context) {
         this.decision = decision;
-        this.hook('onDecision', undefined, () => this.deps.hooks.onDecision?.(decision));
+        this.hook('onDecision', context, () => this.deps.hooks.onDecision?.(decision, hookContext(context)));
         return decision;
     }
     /**
@@ -390,7 +435,7 @@ class GovernanceSession {
             replayed: error.replayed ?? false,
             error,
         };
-        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(failure));
+        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(failure, hookContext(context)));
         return failure;
     }
 }

package/dist/decision-text.d.ts

@@ -2,7 +2,7 @@
  * How a decision reads to a human. Kept next to the decision itself rather than in a binding,
  * because every binding needs the same words and none of them should invent their own.
  */
-import type { GovernanceDecision } from './types';
+import type { AccessDecision } from './types';
 /**
  * Denial -> what to tell the user.
  *
@@ -10,6 +10,6 @@ import type { GovernanceDecision } from './types';
  * admin-set cap is an escalation to that admin, and the two must not be collapsed into one
  * "you have been blocked" string.
  */
-export declare function remedyMessage(decision: GovernanceDecision | undefined): string;
+export declare function remedyMessage(decision: AccessDecision | undefined): string;
 /** One-line decision summary for logs. */
-export declare function describeDecision(decision: Omit<GovernanceDecision, 'summary' | 'message'>): string;
+export declare function describeDecision(decision: Omit<AccessDecision, 'summary' | 'message'>): string;

package/dist/engine/decision.d.ts

@@ -1,31 +1,36 @@
-import type { GovernanceDecision, GovernanceRemedy } from '../types';
+import type { AccessDecision, Entitlement, Remedy } from '../types';
 import type { EngineCheckResult } from './engine';
 /**
  * Denial reasons map to different products, so they must not be collapsed: an empty wallet is an
  * upsell, an admin-set cap is an escalation, and a missing subscription is neither.
  */
-export declare function remedyFor(reason: string | null | undefined): GovernanceRemedy | undefined;
+export declare function remedyFor(reason: string | null | undefined): Remedy | undefined;
 export type DecisionContext = {
     customerId: string;
+    /**
+     * What the run gates on, when it gates on anything. Only its *kind* is read - see
+     * {@link toDecision} for why a denial needs it.
+     */
+    entitlement?: Entitlement;
 };
 /**
  * `remaining` is the tightest bound across the pool and every chain node, because the binding
  * constraint is whichever runs out first. It stays undefined when nothing is bounded - the
  * observe-only rollout, where usage is counted but never blocks.
  */
-export declare function toDecision(result: EngineCheckResult, { customerId }: DecisionContext): GovernanceDecision;
+export declare function toDecision(result: EngineCheckResult, { customerId, entitlement }: DecisionContext): AccessDecision;
 /**
  * Attaches the human-readable halves, so every caller prints the same words. Exported because
  * anything that adjusts a decision after the fact has to refresh them too - a stale summary is
  * worse than none.
  */
-export declare function withDecisionText(decision: Omit<GovernanceDecision, 'summary' | 'message'>): GovernanceDecision;
+export declare function withDecisionText(decision: Omit<AccessDecision, 'summary' | 'message'>): AccessDecision;
 /**
  * The decision to return when the engine itself failed and policy resolved the outcome. No
  * `deniedBy`: nobody's budget refused this, so naming an entity would be a lie - the failure
  * detail goes to the `onError` hook instead.
  */
-export declare function policyDecision(hasAccess: boolean): GovernanceDecision;
+export declare function policyDecision(hasAccess: boolean): AccessDecision;
 /**
  * The decision a run that named no entitlement hands back.
  *
@@ -34,4 +39,4 @@ export declare function policyDecision(hasAccess: boolean): GovernanceDecision;
  * is no budget to ask about - so the only fields true of it are the allow and the source that says
  * why it is one. No `remaining`, because nothing is bounded; no `deniedBy`, because nothing refused.
  */
-export declare function unenforcedDecision(): GovernanceDecision;
+export declare function unenforcedDecision(): AccessDecision;

package/dist/engine/decision.js

@@ -12,6 +12,7 @@ exports.unenforcedDecision = unenforcedDecision;
  * much, so no new primitive is needed on top of it.
  */
 const decision_text_1 = require("../decision-text");
+const types_1 = require("../types");
 /**
  * Denial reasons map to different products, so they must not be collapsed: an empty wallet is an
  * upsell, an admin-set cap is an escalation, and a missing subscription is neither.
@@ -49,7 +50,7 @@ const tightest = (values) => {
  * constraint is whichever runs out first. It stays undefined when nothing is bounded - the
  * observe-only rollout, where usage is counted but never blocks.
  */
-function toDecision(result, { customerId }) {
+function toDecision(result, { customerId, entitlement }) {
     const nodes = (result.chains ?? []).flat();
     const denied = nodes.find((node) => !node.isGranted);
     const reason = result.accessDeniedReason ?? undefined;
@@ -70,7 +71,13 @@ function toDecision(result, { customerId }) {
         decision.locallyDerived = true;
     if (reason) {
         decision.reason = reason;
-        decision.remedy = remedyFor(reason);
+        // An exhausted credit pool comes back as a budget denial, so the reason alone cannot tell an
+        // empty wallet from an admin-set cap - and the two are different products. Nothing in the
+        // chain denied means nothing anyone administers refused this: the pool did. On a credit
+        // entitlement that is a top-up, and saying "ask whoever set this budget to raise it" instead
+        // sends a customer who would have paid to go and find an administrator.
+        const poolLevel = !denied && entitlement !== undefined && (0, types_1.entitlementKind)(entitlement) === 'credit';
+        decision.remedy = poolLevel && remedyFor(reason) === 'raise-budget' ? 'top-up' : remedyFor(reason);
     }
     if (!result.isGranted) {
         // With no chain (governance off, or a pool-level denial) the customer is what blocked.

package/dist/engine/report.js

@@ -75,7 +75,10 @@ function creditResult(currencyId, amount, currentUsage, mode, source) {
     return {
         reported: { [currencyId]: amount },
         currentUsage: currentUsage ?? undefined,
-        creditsConsumed: amount,
+        // What Stigg confirmed drawn, not what was sent - `reported` already says that. Under
+        // `'async'` the draw is reconciled later and the response carries no balance, so there is
+        // nothing confirmed to state and the field stays absent, exactly as its own type promises.
+        creditsConsumed: mode === 'async' ? undefined : amount,
         replayed: mode === 'async' ? undefined : false,
         mode,
         source,

package/dist/errors.d.ts

@@ -2,15 +2,15 @@
  * A flat error hierarchy with `isX()` guards, so callers can branch without `instanceof`
  * surviving across bundles or duplicated copies of this package.
  */
-import type { GovernanceDecision, Metrics } from './types';
+import type { AccessDecision, Metrics } from './types';
 /**
  * Thrown only where there is no return path for a decision - inside a wrapped client method,
  * which must hand back the vendor's own response type or nothing at all. Everywhere else a
- * denial is a returned `GovernanceDecision`.
+ * denial is a returned `AccessDecision`.
  */
 export declare class AccessDeniedError extends Error {
-    readonly decision: GovernanceDecision;
-    constructor(decision: GovernanceDecision);
+    readonly decision: AccessDecision;
+    constructor(decision: AccessDecision);
 }
 /** Anything the engine could not complete: transport, timeout, 4xx/5xx, bad input. */
 export declare class EngineError extends Error {
@@ -38,12 +38,20 @@ export declare class EngineError extends Error {
         replayed?: boolean;
     });
 }
-/** Governance is not enabled for this Stigg account. An account state, not a transient failure. */
+/**
+ * Per-agent budgets are not enabled for this Stigg environment. An account state, not a transient
+ * failure, and the class keeps the platform's own name because that is what has to be turned on.
+ *
+ * The message says what to do rather than what is missing. "Governance is not enabled" names an
+ * internal capability to someone who was trying to charge for agent usage and has no reason to
+ * know the two are the same thing - so the first line is the fix, and the feature name follows it
+ * for whoever has to go and find the setting.
+ */
 export declare class GovernanceNotEnabledError extends Error {
     constructor(detail?: string);
 }
 /** Returns the decision when `err` is a governance denial - the one-liner for a binding catch. */
-export declare function isAccessDenied(err: unknown): GovernanceDecision | undefined;
+export declare function isAccessDenied(err: unknown): AccessDecision | undefined;
 export declare const isEngineError: (err: unknown) => err is EngineError;
 export declare const isGovernanceNotEnabled: (err: unknown) => err is GovernanceNotEnabledError;
 /**

package/dist/errors.js

@@ -16,7 +16,7 @@ const isKind = (err, kind) => typeof err === 'object' && err !== null && err[MAR
 /**
  * Thrown only where there is no return path for a decision - inside a wrapped client method,
  * which must hand back the vendor's own response type or nothing at all. Everywhere else a
- * denial is a returned `GovernanceDecision`.
+ * denial is a returned `AccessDecision`.
  */
 class AccessDeniedError extends Error {
     decision;
@@ -59,9 +59,19 @@ class EngineError extends Error {
     }
 }
 exports.EngineError = EngineError;
-/** Governance is not enabled for this Stigg account. An account state, not a transient failure. */
+/**
+ * Per-agent budgets are not enabled for this Stigg environment. An account state, not a transient
+ * failure, and the class keeps the platform's own name because that is what has to be turned on.
+ *
+ * The message says what to do rather than what is missing. "Governance is not enabled" names an
+ * internal capability to someone who was trying to charge for agent usage and has no reason to
+ * know the two are the same thing - so the first line is the fix, and the feature name follows it
+ * for whoever has to go and find the setting.
+ */
 class GovernanceNotEnabledError extends Error {
-    constructor(detail = 'Governance is not enabled for this account. Contact Stigg to enable it.') {
+    constructor(detail = 'Per-agent budgets are not enabled for this Stigg environment, so an agent cannot be ' +
+        'given an identity or a budget. Enable Governance for the account to use them - or drop ' +
+        '`agentId` and the budget fields, and checks and usage apply to the customer instead.') {
         super(detail);
         this.name = 'GovernanceNotEnabledError';
         mark(this, 'not-enabled');

package/dist/headers.d.ts

@@ -9,6 +9,17 @@ export declare const GOVERNANCE_HEADERS: {
     readonly customer: "x-stigg-customer-id";
     readonly dimensions: "x-stigg-dimensions";
     readonly run: "x-stigg-run-id";
+    /**
+     * Which key in `dimensions` names the agent, when one does.
+     *
+     * Sent because the far end cannot work it out. Governance resolves an entity per attribution
+     * key, and which keys those are is declared on the entity types in the account - so a receiver
+     * holding only `{ agentId: 'a-1', region: 'eu' }` cannot tell the attribution from the
+     * metadata. Guessing either way is wrong in a direction that costs money: treat every
+     * dimension as attribution and an ordinary `region` rounds the draw up; treat none as
+     * attribution and a real agent's budget stops counting.
+     */
+    readonly attributionKey: "x-stigg-attribution-key";
 };
 /**
  * What `run.headers()` produces - all three, always.
@@ -22,6 +33,8 @@ export type ParsedGovernanceHeaders = {
     customerId: string;
     dimensions: Record<string, string>;
     runId?: string;
+    /** The key under which `dimensions` names the agent, when the sender named one. */
+    attributionKey?: string;
 };
 /** The receiving side. Returns undefined when the request carries no attribution to act on. */
 export declare function parseGovernanceHeaders(headers: Record<string, string | string[] | undefined>): ParsedGovernanceHeaders | undefined;

package/dist/headers.js

@@ -13,6 +13,17 @@ exports.GOVERNANCE_HEADERS = {
     customer: 'x-stigg-customer-id',
     dimensions: 'x-stigg-dimensions',
     run: 'x-stigg-run-id',
+    /**
+     * Which key in `dimensions` names the agent, when one does.
+     *
+     * Sent because the far end cannot work it out. Governance resolves an entity per attribution
+     * key, and which keys those are is declared on the entity types in the account - so a receiver
+     * holding only `{ agentId: 'a-1', region: 'eu' }` cannot tell the attribution from the
+     * metadata. Guessing either way is wrong in a direction that costs money: treat every
+     * dimension as attribution and an ordinary `region` rounds the draw up; treat none as
+     * attribution and a real agent's budget stops counting.
+     */
+    attributionKey: 'x-stigg-attribution-key',
 };
 /** The receiving side. Returns undefined when the request carries no attribution to act on. */
 function parseGovernanceHeaders(headers) {
@@ -55,7 +66,15 @@ function parseGovernanceHeaders(headers) {
             dimensions = {};
         }
     }
-    return { customerId, dimensions, runId: read(exports.GOVERNANCE_HEADERS.run) };
+    // Only honoured when it names a dimension that is actually there: a key with nothing under it
+    // attributes to no entity, and treating it as though it did would round a draw up for nothing.
+    const attributionKey = read(exports.GOVERNANCE_HEADERS.attributionKey);
+    return {
+        customerId,
+        dimensions,
+        runId: read(exports.GOVERNANCE_HEADERS.run),
+        ...(attributionKey && dimensions[attributionKey] ? { attributionKey } : {}),
+    };
 }
 const isDimensions = (value) => typeof value === 'object' &&
     value !== null &&

package/dist/index.d.ts

@@ -11,10 +11,10 @@
  * `@stigg/agent-sdk-js/internal`, under a weaker compatibility promise.
  */
 export { StiggAgentSDK } from './stigg-agent-sdk';
-export type { AgentType, StiggContext } from './core/context';
-export type { GovernanceSummary, IngestOptions, SessionHooks } from './core/session';
+export type { StiggContext } from './core/context';
+export type { SessionSummary, HookContext, IngestOptions, SessionHooks } from './core/session';
 export { RAW_PREFIX, flattenRaw } from './core/dimensions';
-export type { CacheOptions, ErrorContext, NodeSdkClient, StiggAgentSDKOptions, StiggTarget } from './config';
+export type { CacheOptions, ErrorContext, NodeSdkClient, StiggAgentSDKOptions } from './config';
 export { describeDecision, remedyMessage } from './decision-text';
 export { GOVERNANCE_HEADERS, parseGovernanceHeaders } from './headers';
 export type { GovernanceHeaders, ParsedGovernanceHeaders } from './headers';
@@ -22,8 +22,8 @@ export { consoleLogger, noopLogger } from './logger';
 export type { Logger } from './logger';
 export { EngineError, AccessDeniedError, GovernanceNotEnabledError, isEngineError, isAccessDenied, isGovernanceNotEnabled, looksLikeGovernanceNotEnabled, } from './errors';
 export type { EngineCapabilities, EngineChainNode, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, EngineResolution, EntityInput, EventIngest, EntityPlacement, GovernanceEngine, } from './engine/engine';
-export { creditsPerTokens, vendorMetrics, emptyTokenUsage, entitlementId, entitlementKind, entitlementRef, toMeasurement, } from './types';
-export type { AgentOptions, AgentScope, ClientGovernance, CheckErrorAction, ClientOptions, DecisionSource, DeregisterInput, Entitlement, GovernanceDecision, GovernanceRemedy, GovernedClient, IngestContext, IngestMode, IngestResult, Measurement, RegisterInput, GatedSurface, CallContext, TokenUsage, Metrics, MetricsMapper, } from './types';
+export { unitsPerTokens, vendorMetrics, emptyTokenUsage, entitlementId, entitlementKind, entitlementRef, toMeasurement, } from './types';
+export type { AgentBudget, AgentOptions, AgentScope, ClientGovernance, CheckErrorAction, ClientOptions, DecisionSource, DeregisterInput, Entitlement, AccessDecision, Remedy, WrappedClient, IngestContext, IngestMode, IngestResult, Measurement, RegisterInput, GatedSurface, CallContext, TokenUsage, Metrics, MetricsMapper, } from './types';
 export { wrapClient } from './bindings/client/core/wrap-client';
 export { createClientRegistry, hasMethod } from './bindings/client/core/registry';
 export type { ClientRecipe, ClientRegistry, MethodRecipe, MetricsFor, MetricsOf, MeteredResponse, } from './bindings/client/core/types';
@@ -40,6 +40,9 @@ export type { OpenRouterRecipeOptions } from './bindings/client/gateways/openrou
 export { litellmRecipe } from './bindings/client/gateways/litellm/litellm-recipe';
 export type { LiteLLMMetric, LiteLLMMetrics } from './bindings/client/gateways/litellm/litellm-recipe';
 export type { LiteLLMRecipeOptions } from './bindings/client/gateways/litellm/types';
+export { bedrockRecipe } from './bindings/client/gateways/bedrock/bedrock-recipe';
+export type { BedrockMetricName, BedrockMetrics } from './bindings/client/gateways/bedrock/bedrock-recipe';
+export type { BedrockRecipeOptions } from './bindings/client/gateways/bedrock/types';
 export { typesafeRecipe, estimateFromState } from './bindings/client/providers/typesafe/typesafe-recipe';
 export type { TypeSafeMetric, TypeSafeMetrics } from './bindings/client/providers/typesafe/typesafe-recipe';
 export { weightedMetrics } from './bindings/shared/weighted-metrics';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeUsage = exports.normalizedMetrics = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.creditsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
+exports.normalizeUsage = exports.normalizedMetrics = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.bedrockRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.unitsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
 /**
  * Public surface.
  *
@@ -37,7 +37,7 @@ Object.defineProperty(exports, "isAccessDenied", { enumerable: true, get: functi
 Object.defineProperty(exports, "isGovernanceNotEnabled", { enumerable: true, get: function () { return errors_1.isGovernanceNotEnabled; } });
 Object.defineProperty(exports, "looksLikeGovernanceNotEnabled", { enumerable: true, get: function () { return errors_1.looksLikeGovernanceNotEnabled; } });
 var types_1 = require("./types");
-Object.defineProperty(exports, "creditsPerTokens", { enumerable: true, get: function () { return types_1.creditsPerTokens; } });
+Object.defineProperty(exports, "unitsPerTokens", { enumerable: true, get: function () { return types_1.unitsPerTokens; } });
 Object.defineProperty(exports, "vendorMetrics", { enumerable: true, get: function () { return types_1.vendorMetrics; } });
 Object.defineProperty(exports, "emptyTokenUsage", { enumerable: true, get: function () { return types_1.emptyTokenUsage; } });
 Object.defineProperty(exports, "entitlementId", { enumerable: true, get: function () { return types_1.entitlementId; } });
@@ -73,6 +73,12 @@ Object.defineProperty(exports, "openrouterRecipe", { enumerable: true, get: func
 // nothing from a stream. Name it at `wrap(client, { recipe })` to give it your proxy's base URL.
 var litellm_recipe_1 = require("./bindings/client/gateways/litellm/litellm-recipe");
 Object.defineProperty(exports, "litellmRecipe", { enumerable: true, get: function () { return litellm_recipe_1.litellmRecipe; } });
+// A default too, and the gateway that states no price. Bedrock's client is a command bus rather
+// than a method tree, so the recipe gates `send` and reads the command to tell inference from the
+// rest of the API; it reports Bedrock's own token counters and no `cost`, because there is none on
+// the response to report. See the recipe for what that means for a run that wanted to bill spend.
+var bedrock_recipe_1 = require("./bindings/client/gateways/bedrock/bedrock-recipe");
+Object.defineProperty(exports, "bedrockRecipe", { enumerable: true, get: function () { return bedrock_recipe_1.bedrockRecipe; } });
 // Built in as well. One method, no stream, and two counters - see the recipe for why a
 // question-answering API has neither a cache counter nor a cost to report.
 var typesafe_recipe_1 = require("./bindings/client/providers/typesafe/typesafe-recipe");

package/dist/stigg-agent-sdk.d.ts

@@ -1,8 +1,8 @@
-import { type ResolvedConfig, type StiggAgentSDKOptions, type StiggTarget } from './config';
+import { type ResolvedConfig, type StiggAgentSDKOptions } from './config';
 import { type EngineResolution, type GovernanceEngine } from './engine/engine';
 import type { StiggContext } from './core/context';
-import type { GovernanceSummary } from './core/session';
-import type { Metrics, ClientOptions, DeregisterInput, GovernanceDecision, GovernedClient, PathsOf, IngestContext, IngestResult, RegisterInput } from './types';
+import type { SessionSummary } from './core/session';
+import type { Metrics, ClientOptions, DeregisterInput, AccessDecision, WrappedClient, PathsOf, IngestContext, IngestResult, RegisterInput } from './types';
 import type { GovernanceHeaders } from './headers';
 /**
  * Recipes are data - method paths and usage extractors - so wiring them here costs nothing at
@@ -77,7 +77,7 @@ export declare const DEFAULT_RECIPES: ({
         } | undefined;
         attachStream: (stream: any, ingest: (measurement: import("./types").Measurement) => void) => void;
     }[];
-} | import("./bindings/client/core/types").ClientRecipe<"cached_tokens" | "prompt_tokens" | "completion_tokens" | "input_tokens" | "output_tokens" | "total_tokens" | "cost"> | {
+} | import("./bindings/client/core/types").ClientRecipe<"cached_tokens" | "prompt_tokens" | "completion_tokens" | "input_tokens" | "output_tokens" | "total_tokens" | "cost"> | import("./bindings/client/core/types").ClientRecipe<"inputTokens" | "outputTokens" | "cacheReadInputTokens" | "cacheWriteInputTokens" | "totalTokens"> | {
     vendor: string;
     metrics: readonly ["input_tokens", "output_tokens", "total_tokens"];
     totalTokensMetric: "total_tokens";
@@ -110,6 +110,11 @@ export declare class StiggAgentSDK {
      */
     private readonly registering;
     private 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`.
+     */
+    private startFailedAt?;
     private engineState?;
     /**
      * Synchronous - nothing here touches the network. The engine is built on the first call that
@@ -117,16 +122,16 @@ export declare class StiggAgentSDK {
      *
      * Where this SDK sends its traffic comes first, because it is the only thing that cannot be
      * inferred: a server key, a `{ baseUrl }` target that needs none, or nothing at all to read
-     * `STIGG_SERVER_API_KEY`. See {@link StiggTarget}. A key that belongs to somewhere other than
+     * `STIGG_SERVER_API_KEY`. A key that belongs to somewhere other than
      * the hosted API names that URL second - the two together are one idea, so neither is buried
      * among the tuning knobs that follow.
      *
      * Construct one per environment and share it - the engine's cache and its connection pool are
      * per instance, so a second one for the same environment is wasted rather than wrong.
      */
-    constructor(target?: StiggTarget, baseUrl?: string, options?: StiggAgentSDKOptions);
-    /** The same, for a target that already carries its URL - or one on the hosted API. */
-    constructor(target?: StiggTarget, options?: StiggAgentSDKOptions);
+    constructor(options?: StiggAgentSDKOptions);
+    /** The shorthand, for a server key with nothing else to say about where it points. */
+    constructor(apiKey: string, options?: Omit<StiggAgentSDKOptions, 'apiKey'>);
     /** Releases what this SDK's engine holds open. */
     close(): Promise<void>;
     /**
@@ -174,7 +179,7 @@ export declare class StiggAgentSDK {
      * entitlement, so the calls that follow read local state. Nothing is cached in this package -
      * see {@link GovernanceSession.warmUp} for which cache that is and when there is one at all.
      */
-    wrap<T extends object, O extends ClientOptions>(client: T, options?: O): GovernedClient<T, O['stiggContext'], PathsOf<O['recipe'], T>>;
+    wrap<T extends object, O extends ClientOptions>(client: T, options?: O): WrappedClient<T, O['stiggContext'], PathsOf<O['recipe'], T>>;
     /**
      * Hangs the governance handle off the wrapped client. Refuses to overwrite a `stigg` the vendor
      * already has: silently replacing one of its own properties would be a worse surprise.
@@ -184,7 +189,7 @@ export declare class StiggAgentSDK {
      * The gate, with no client to wrap - what a framework binding reaches for, and what the gateway
      * example checks with before it proxies.
      */
-    check(context: StiggContext, requestedUsage?: number): Promise<GovernanceDecision>;
+    check(context: StiggContext, requestedUsage?: number): Promise<AccessDecision>;
     /** The meter, with no client to wrap. Metrics already in Stigg's own vocabulary. */
     report(context: StiggContext, metrics: Metrics): Promise<IngestResult>;
     /** The `x-stigg-*` attribution for work continuing in another process, with no client involved. */
@@ -205,7 +210,7 @@ export declare class StiggAgentSDK {
      * Returns the decision when `err` is a governance refusal, so a catch block is one line and the
      * caller needs no import to tell a denial from a real failure.
      */
-    denial(err: unknown): GovernanceDecision | undefined;
+    denial(err: unknown): AccessDecision | undefined;
     /**
      * The gateway side of the split lifecycle: ingest usage a proxy observed, attributed from the
      * headers the application sent with the request. Ingest only - a gateway sees requests, not
@@ -236,7 +241,18 @@ export declare class StiggAgentSDK {
      */
     flush(options?: {
         close?: boolean;
-    }): Promise<GovernanceSummary[]>;
-    /** Builds the engine once, on first need. Concurrent callers share the same attempt. */
+    }): Promise<SessionSummary[]>;
+    /**
+     * 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.
+     */
     private ensureStarted;
 }