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

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

@@ -0,0 +1,170 @@
+/**
+ * The vendor response shapes these converters read.
+ *
+ * Typed structurally rather than against each vendor's SDK, so the same handful of functions cover
+ * a direct client, a gateway response and an orchestrator callback - and adding a provider whose
+ * response happens to match costs nothing.
+ */
+/**
+ * A flat `usage` object whose cache counters sit BESIDE the input count rather than inside it.
+ *
+ * Named for the shape, not for a vendor, because more than one reports it: Anthropic's Messages
+ * API and TypeSafe's System One, which carries only the first two. The distinction from the two
+ * shapes below is the whole reason this is a separate reader - they spell the same two counters
+ * the same way but count their cached tokens *within* the input total, so reading one as the
+ * other double-counts in one direction or overstates in the other.
+ */
+export type FlatTokenUsage = {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+};
+/** OpenAI-compatible `usage` - also what OpenRouter and most gateways return. */
+export type OpenAILikeUsage = {
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    /** The vendor's own total. `prompt_tokens + completion_tokens`; cached tokens are inside the first. */
+    total_tokens?: number | null;
+    prompt_tokens_details?: {
+        cached_tokens?: number | null;
+        cache_write_tokens?: number | null;
+    } | null;
+};
+/**
+ * Databricks model serving `usage` - OpenAI's three counters, with Anthropic's spelling for cache.
+ *
+ * The mixed vocabulary is Databricks' own and is reported verbatim rather than normalised to one
+ * side or the other. The first three come back from every serving endpoint; the last three are
+ * Foundation Model API extensions and are absent on the external-model route, where the body is
+ * whatever the upstream provider's counters normalise to.
+ */
+export type DatabricksLikeUsage = {
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    /** Databricks states its own total, so it is read rather than reassembled from the parts. */
+    total_tokens?: number | null;
+    /** Reasoning models only. */
+    reasoning_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+};
+/**
+ * The same block as above, as `@databricks/sdk-modelservingquery` hands it over.
+ *
+ * Databricks' own `ExternalModelUsageElement`. The **wire** is the snake_case one above - the
+ * generated client's zod schema parses `prompt_tokens` and transforms it to `promptTokens` on the
+ * way in, exactly as Mistral's generated client does to `UsageInfo`. So this is a second spelling
+ * of one vendor's counters rather than a second set of counters, and it is read through
+ * `DATABRICKS_QUERY_METRIC_NAME_MAP` so both spellings report under the wire's names.
+ *
+ * Three, not six: the cache pair and `reasoning_tokens` have no field on this type at all, so a
+ * call made through the first-party client reports the three it can and nothing more. Absent, not
+ * zero - and the reason the native surface's metric list is a subset of the recipe's.
+ *
+ * Written out rather than aliased to {@link MistralLikeUsage}, which it currently matches
+ * field-for-field: these are two unrelated vendor contracts that happen to agree today, and
+ * collapsing them would make a change on either side look like a change to both.
+ */
+export type DatabricksQueryLikeUsage = {
+    promptTokens?: number | null;
+    completionTokens?: number | null;
+    /** Databricks states its own total here too, so it is read rather than reassembled. */
+    totalTokens?: number | null;
+};
+/** OpenAI's Responses API `usage` - the same counts as above under different names. */
+export type ResponsesLikeUsage = {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    /** The vendor's own total, under the same name the Chat Completions shape uses. */
+    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;
+    output_tokens?: number | null;
+    input_token_details?: {
+        cache_read?: number | null;
+        cache_creation?: number | null;
+    } | null;
+};
+/**
+ * Gemini's `usageMetadata`, which counts in its own names and overlaps in two directions at once.
+ *
+ * Both overlaps are quoted from the vendor's own field docs, because each one is a doubled or
+ * halved bill if read the other way round:
+ *
+ * - `promptTokenCount` - "when `cached_content` is set, this **also includes** the number of
+ *   tokens in the cached content", so `cachedContentTokenCount` is counted *inside* it, the way
+ *   OpenAI nests `cached_tokens` inside `prompt_tokens`.
+ * - `totalTokenCount` - "the sum of `prompt_token_count`, `candidates_token_count`,
+ *   `tool_use_prompt_token_count`, and `thoughts_token_count`", so the last two sit *beside* the
+ *   first two rather than within them. Thinking tokens in particular are billed as output and
+ *   are **not** inside `candidatesTokenCount`: a reader that ignores them undercounts the output
+ *   of every reasoning model this vendor sells.
+ */
+export type GeminiLikeUsage = {
+    /**
+     * The vendor's own total: `promptTokenCount + candidatesTokenCount + toolUsePromptTokenCount +
+     * thoughtsTokenCount`, with the cached count already inside the first. Read, never recomputed.
+     */
+    totalTokenCount?: number | null;
+    promptTokenCount?: number | null;
+    candidatesTokenCount?: number | null;
+    cachedContentTokenCount?: number | null;
+    thoughtsTokenCount?: number | null;
+    toolUsePromptTokenCount?: number | null;
+};
+/**
+ * Mistral's `UsageInfo`, which counts the OpenAI three under camelCase names.
+ *
+ * The *wire* is snake_case - `prompt_tokens` and the rest - and the generated SDK renames it on
+ * the way in, so what a recipe reads here and what it reports are deliberately different strings.
+ * See `MISTRAL_METRIC_NAME_MAP` in `token-usage.ts` for the mapping and why it runs in that direction.
+ *
+ * Every counter is optional because the SDK declares them so: the inbound schema defaults each to
+ * zero, which means an absent counter and a genuine zero arrive looking identical. Read them as
+ * possibly-missing rather than trusting the declared `number`.
+ */
+export type MistralLikeUsage = {
+    promptTokens?: number | null;
+    completionTokens?: number | null;
+    /** The vendor's own total. Stated, so it is read rather than recomputed from the two above. */
+    totalTokens?: number | null;
+};
+/**
+ * Ollama's counters, which sit **flat on the response root** rather than inside a `usage` object.
+ *
+ * Every field is optional here even though `ollama`'s own `ChatResponse` declares
+ * `prompt_eval_count: number` and `eval_count: number` as required. The server marks the whole
+ * `Metrics` struct `omitempty`, so an intermediate stream chunk carries none of them at all and
+ * the declared type is simply wrong about it. Trusting it substitutes zeroes for counters that
+ * were never sent, which bills a real call at nothing.
+ *
+ * `prompt_eval_cached_count` exists on the wire and is deliberately **not** read: the SDK does not
+ * declare it, and whether it sits inside `prompt_eval_count` or beside it is undocumented. A
+ * counter whose overlap direction is unknown cannot be reported without risking a double count.
+ */
+export type OllamaLikeUsage = {
+    prompt_eval_count?: number | null;
+    eval_count?: number | null;
+};

package/dist/bindings/shared/types.js

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

package/dist/bindings/shared/weighted-metrics.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A price per metric, as the mapper a run reports through.
+ *
+ * Writing one by hand is a reduce over a record and three details that are easy to miss: Stigg
+ * rejects fractions, a turn that measured nothing must report nothing rather than a zero, and a
+ * counter the response omitted is absent rather than zero. This gets all three right once.
+ */
+import type { MetricsMapper } from '../../types';
+import type { ClientRecipe } from '../client/core/types';
+export type WeightedMetricsOptions = {
+    /**
+     * How many weighted units make one of `target`. Defaults to 1, so a weight reads as the price
+     * of one unit of that metric: `output_tokens: 0.5` is half a credit per output token.
+     *
+     * Set it when the weights are easier to write per thousand than per one - `per: 1000` with
+     * `output_tokens: 5` prices five credits per thousand output tokens.
+     */
+    per?: number;
+};
+/**
+ * Prices what a vendor reported into one metric of your own.
+ *
+ * The weights are keyed to the recipe's own metric names, so a typo does not compile. Naming one
+ * is optional: a metric with no weight is free, and a table that prices nothing meters nothing.
+ *
+ * ```ts
+ * // Half a credit per output token, a whole one per input token, cache reads free.
+ * metrics: weightedMetrics(anthropicRecipe, 'data_credit', {
+ *   input_tokens: 1,
+ *   output_tokens: 0.5,
+ * })
+ * ```
+ *
+ * Prices what the vendor actually said, under its own names. For one vocabulary across several
+ * vendors, `normalizedMetrics` reports the four neutral counters instead.
+ */
+export declare function weightedMetrics<M extends string>(recipe: ClientRecipe<M>, target: string, weights: Partial<Record<M, number>>, options?: WeightedMetricsOptions): MetricsMapper;

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.weightedMetrics = weightedMetrics;
+/**
+ * Prices what a vendor reported into one metric of your own.
+ *
+ * The weights are keyed to the recipe's own metric names, so a typo does not compile. Naming one
+ * is optional: a metric with no weight is free, and a table that prices nothing meters nothing.
+ *
+ * ```ts
+ * // Half a credit per output token, a whole one per input token, cache reads free.
+ * metrics: weightedMetrics(anthropicRecipe, 'data_credit', {
+ *   input_tokens: 1,
+ *   output_tokens: 0.5,
+ * })
+ * ```
+ *
+ * Prices what the vendor actually said, under its own names. For one vocabulary across several
+ * vendors, `normalizedMetrics` reports the four neutral counters instead.
+ */
+function weightedMetrics(recipe, target, weights, options = {}) {
+    const per = options.per && options.per > 0 ? options.per : 1;
+    // The one thing this cannot report its way out of: an empty target is a feature id of `''`,
+    // which nothing downstream rejects - the value is validated, the key is not - so the turn
+    // reports to a feature that does not exist and the budget never moves.
+    if (!target.trim()) {
+        throw new Error('weightedMetrics needs a target to price into - an empty one reports to no feature.');
+    }
+    // Deduplicated, because the reducer walks the declaration: a recipe listing a name twice would
+    // charge for it twice, which is the one direction a meter must not be wrong in.
+    const priced = [...new Set(recipe.metrics)];
+    return ({ metrics }) => {
+        if (!metrics)
+            return {};
+        // An unpriced metric is free rather than an error, so a table names only what it charges for.
+        const weighted = priced.reduce((sum, name) => sum + (metrics[name] ?? 0) * (weights[name] ?? 0), 0);
+        // Nothing measured is not the same as nothing owed: report no metric at all, which the run
+        // counts as the no-op ingest it is rather than as a report of zero.
+        if (weighted <= 0)
+            return {};
+        // 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

@@ -0,0 +1,145 @@
+/**
+ * Client configuration - everything that is true of one Stigg *environment*, and nothing else.
+ *
+ * A Stigg API key is environment-bound, so the key identifies the environment: one instance per
+ * environment, like the Node server SDK. That draws the line for what belongs here. Anything that
+ * varies within an environment - which customer, which agent, what it bills against, who wants to
+ * watch it happen - is context for the call that needs it, not configuration for the process.
+ *
+ * The data half (ids, urls, numbers, enums) goes through zod so a typo fails at construction with
+ * a readable message instead of as a 404 three calls later. The collaborator half (logger,
+ * onError) is injected as-is - those are substitution seams, not data to validate.
+ */
+import { z } from 'zod';
+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';
+declare const dataSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    checkErrorAction: z.ZodDefault<z.ZodEnum<{
+        deny: "deny";
+        allow: "allow";
+    }>>;
+    ingest: z.ZodDefault<z.ZodEnum<{
+        sync: "sync";
+        async: "async";
+    }>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type { CacheOptions, NodeSdkClient };
+/** Reported to `onError` alongside the failure, so a swallowed ingest is still diagnosable. */
+export type ErrorContext = {
+    operation: string;
+    runId?: string;
+    idempotencyKey?: string;
+    customerId?: string;
+};
+/**
+ * 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.
+     */
+    cache?: CacheOptions;
+    /**
+     * A Node server SDK client you already have, used instead of building one.
+     *
+     * Pass it when the application uses `@stigg/node-server-sdk` directly. It is the only way to
+     * settle ownership: `Stigg.initialize` keeps one global instance per process and hands it back
+     * when the API key matches, so without this the SDK may be handed your client, believe it built
+     * it, and close it out from under you on `stigg.close()` - taking its cache and socket along.
+     * A client passed here is borrowed and never closed.
+     *
+     * It replaces only the cached half. The governance REST client is still built from the API key,
+     * because the Node SDK has no governance surface. Mutually exclusive with
+     * {@link StiggAgentSDKOptions.cache}, which configures a client this SDK is no longer building.
+     */
+    client?: NodeSdkClient;
+    /**
+     * @deprecated Ignored. There is no local decision cache to put a TTL on any more - the Node
+     * server SDK's entitlement cache serves these checks and keeps itself fresh, so there is no
+     * window to size. Configure caching with {@link StiggAgentSDKOptions.cache}; for a hard limit
+     * with no cached state at all, there is nothing to turn off on the attributed governance path.
+     */
+    cacheTtlMs?: number;
+    /**
+     * What happens to a call when the check itself fails - Stigg unreachable, a timeout, a 5xx.
+     *
+     * Defaults to `'allow'`: a soft limit, so an outage does not take the application down with it.
+     * Pass `'deny'` to mirror governance's own fail-closed behaviour. Overridable per call through
+     * `stiggContext`, and by `wrap`'s own context for every call through one client.
+     */
+    checkErrorAction?: CheckErrorAction;
+    /**
+     * Which of Stigg's ingest APIs a run reports through. Defaults to `'async'`: the event API, which
+     * costs a fraction of the latency and takes a far higher rate. Overridable per run, and see
+     * {@link IngestMode} for what the two trade against each other.
+     */
+    ingest?: IngestMode;
+    timeoutMs?: number;
+    /**
+     * Where the SDK narrates what it did. Defaults to `'console'`, because the things it says are
+     * the ones you need before anything is configured - which transport resolved, that a run is
+     * gating nothing, that what was reported names no entitlement the budget converts.
+     *
+     * Pass `'none'` to silence it, or your own logger to route it.
+     */
+    logger?: Logger | 'console' | 'none';
+    /**
+     * Every instrumentation failure, as structure rather than as a sentence.
+     *
+     * The one observability hook that is environment-scoped, because it is the only one that fires
+     * with no run to belong to: engine resolution, a bare `register()`, `close()`. Watching a
+     * decision or an ingest is per-run and lives on `run.start(..., { hooks })`.
+     *
+     * It is also the only place metering failures surface at all - they are swallowed so they
+     * cannot break a run - so it defaults to a warning through `logger` rather than to silence.
+     * Replace it to route an `EngineError` and its {@link ErrorContext} into your own telemetry.
+     */
+    onError?: (error: EngineError, context: ErrorContext) => void;
+};
+export type ResolvedConfig = Omit<Required<z.infer<typeof dataSchema>>, 'baseUrl'> & {
+    baseUrl?: string;
+    cache?: CacheOptions;
+    client?: NodeSdkClient;
+    logger: Logger;
+    onError: (error: EngineError, context: ErrorContext) => void;
+};
+export declare function resolveConfig(options?: StiggAgentSDKOptions): ResolvedConfig;
+/** The slice of config the engine factory needs. */
+export type EngineConfig = {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs: number;
+    cache?: CacheOptions;
+    client?: NodeSdkClient;
+    logger: Logger;
+};

package/dist/config.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
+/**
+ * Client configuration - everything that is true of one Stigg *environment*, and nothing else.
+ *
+ * A Stigg API key is environment-bound, so the key identifies the environment: one instance per
+ * environment, like the Node server SDK. That draws the line for what belongs here. Anything that
+ * varies within an environment - which customer, which agent, what it bills against, who wants to
+ * watch it happen - is context for the call that needs it, not configuration for the process.
+ *
+ * The data half (ids, urls, numbers, enums) goes through zod so a typo fails at construction with
+ * a readable message instead of as a 404 three calls later. The collaborator half (logger,
+ * onError) is injected as-is - those are substitution seams, not data to validate.
+ */
+const zod_1 = require("zod");
+const context_1 = require("./core/context");
+const logger_1 = require("./logger");
+/** The key sent when the target is a URL that needs none. Never reaches a real environment. */
+const KEYLESS = 'offline-mock';
+const dataSchema = zod_1.z.object({
+    apiKey: zod_1.z.string().min(1),
+    baseUrl: zod_1.z.string().url().optional(),
+    // Both default through the context's own table rather than restating it: the two used to
+    // disagree, and the one written here was the one nothing read.
+    checkErrorAction: zod_1.z.enum(['deny', 'allow']).default(context_1.CONTEXT_DEFAULTS.checkErrorAction),
+    ingest: zod_1.z.enum(['sync', 'async']).default(context_1.CONTEXT_DEFAULTS.ingestMode),
+    timeoutMs: zod_1.z.number().int().positive().default(3_000),
+});
+const resolveLogger = (logger) => {
+    if (logger === 'console' || logger === undefined)
+        return logger_1.consoleLogger;
+    if (logger === 'none')
+        return logger_1.noopLogger;
+    return logger;
+};
+/**
+ * The key to send, which is the environment's identity.
+ *
+ * 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 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(options = {}) {
+    const parsed = dataSchema.parse({
+        apiKey: resolveApiKey(options),
+        baseUrl: options.baseUrl,
+        checkErrorAction: options.checkErrorAction,
+        ingest: options.ingest,
+        timeoutMs: options.timeoutMs,
+    });
+    // Refused rather than silently preferred, like the two-URL case above: `cache` configures a
+    // client, and a client that was handed in is already configured. Whichever the SDK picked, the
+    // other would be settings the caller believes are in force and are not.
+    if (options.client && options.cache) {
+        throw new Error('This SDK was given both a `client` and `cache` options. The cache options configure a ' +
+            'client at construction, and the one you passed is already built - so they would be ' +
+            'ignored. Pass one: `client` for a client you own, or `cache` to have the SDK build one.');
+    }
+    const logger = resolveLogger(options.logger);
+    // Said rather than ignored in silence: someone who set this was sizing an overshoot window, and
+    // the answer to that question is now different rather than smaller.
+    if (options.cacheTtlMs !== undefined) {
+        logger.warn('[stigg] cacheTtlMs is ignored - this SDK no longer caches decisions. Checks are served by ' +
+            "the Node server SDK's entitlement cache, which invalidates on updates and writes reported " +
+            'usage back, so there is no TTL to size. Configure it with `cache` instead.');
+    }
+    return {
+        ...parsed,
+        cache: options.cache,
+        client: options.client,
+        logger,
+        // Never silent, never fatal. Replace it to route into your own telemetry.
+        onError: options.onError ?? ((error, context) => logger.warn(`[stigg] ${context.operation} failed: ${error.message}`)),
+    };
+}

package/dist/core/context.d.ts

@@ -0,0 +1,160 @@
+import type { CheckErrorAction, Entitlement, IngestMode, Metrics, MetricsMapper } from '../types';
+import type { EventIngest } from '../engine/engine';
+/**
+ * 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
+ * wrapped client's types say which calls still owe it.
+ */
+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 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 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
+     * customer instead.
+     *
+     * Overriding this **merges** per key over the wrap's own, so a per-call `{ tenantId }` does not
+     * silently drop a client-wide `{ region }`.
+     */
+    dimensions?: Record<string, string>;
+    /**
+     * What this call **gates on** - a credit currency or a metered feature, never both. **Omit it
+     * and the call gates nothing**: no check leaves the process, nothing can be refused, and
+     * metering is unchanged. The presence of this field is the enforcement switch, because a call
+     * with nothing to check against cannot be enforced, and a separate flag would only be a second
+     * place for the two to disagree.
+     */
+    entitlement?: Entitlement;
+    /**
+     * What a check resolves to when the engine could not answer it. Defaults to `'allow'` - a soft
+     * limit, so an outage does not take the application down with it.
+     *
+     * Worth knowing what that trades: reporting fails in the same outage and is swallowed, so the
+     * spend allowed through is neither capped nor recorded afterwards. `'deny'` mirrors governance,
+     * which is fail-closed server-side.
+     */
+    checkErrorAction?: CheckErrorAction;
+    /**
+     * What to report for each completed call. Defaults to the vendor's own metric names and values
+     * exactly as they came back, so what lands in Stigg reconciles against that vendor's invoice.
+     *
+     * The name on the left is a Stigg feature or credit id, and metering the one the call checks -
+     * {@link StiggContext.entitlement} - is what makes the budget move.
+     */
+    usageMapper?: MetricsMapper;
+    /** Which of Stigg's ingest APIs this call reports through. Defaults to `'async'`. */
+    ingestMode?: IngestMode;
+    /**
+     * The event name to report under in `'async'` mode. Defaults to the vendor call that produced
+     * the usage - `anthropic.messages.create` - which is what a Stigg meter filters on.
+     */
+    eventName?: EventIngest;
+    /**
+     * The key that deduplicates this report. Defaults to the vendor's own request id when it has
+     * one - stable across the vendor's retries, which a local counter cannot be - and to a
+     * generated key otherwise.
+     */
+    idempotencyKey?: string;
+    /**
+     * Correlates work that continues in another process, as `x-stigg-run-id`. Defaults to the id
+     * the wrap generated, so a gateway sees one value per client unless a call says otherwise.
+     */
+    correlationId?: string;
+};
+/**
+ * A context with everything decided and everything derivable already derived.
+ *
+ * Nothing here is optional that the call path would otherwise have to default, and nothing is
+ * computed that a call could be asked to compute twice.
+ */
+export type ResolvedContext = {
+    /**
+     * Empty only for a client wrapped without one, whose calls each name their own. Every path that
+     * reaches the engine resolves it first, so nothing downstream has to re-check it.
+     */
+    customerId: string;
+    entitlement?: Entitlement;
+    /** The agent folded in, so the check and the report send one object and neither re-derives it. */
+    dimensions: Record<string, string>;
+    checkErrorAction: CheckErrorAction;
+    ingestMode: IngestMode;
+    eventName?: EventIngest;
+    usageMapper: MetricsMapper;
+    idempotencyKey?: string;
+    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.
+ *
+ * Exported because the constructor's own schema defaults to these: two copies of "what happens
+ * when nothing says" is how a configured `deny` came to be parsed, stored and then ignored in
+ * favour of an `allow` written somewhere else.
+ *
+ * `allow` is the soft limit - an unreachable Stigg does not take the application down with it.
+ */
+export declare const CONTEXT_DEFAULTS: {
+    readonly checkErrorAction: "allow";
+    readonly ingestMode: "async";
+};
+/**
+ * Validates and derives, once. Everything expensive about a context happens here rather than on
+ * the call path - see the note at the top of this file for why that split exists.
+ */
+/** The one field a call cannot proceed without, said the same way wherever it is missing. */
+export declare const noCustomer: () => Error;
+/**
+ * The client-wide policy a context falls back to before the SDK's own defaults.
+ *
+ * The chain is per-call, then `wrap`, then the constructor, then {@link CONTEXT_DEFAULTS}. The
+ * constructor link is this parameter: without it a configured policy is inert, because every
+ * context would land on the defaults instead.
+ */
+export type ContextDefaults = {
+    checkErrorAction?: CheckErrorAction;
+    ingestMode?: IngestMode;
+};
+export declare function resolveContext(context: StiggContext, correlationId: string, { requireCustomer, defaults }?: {
+    requireCustomer?: boolean;
+    defaults?: ContextDefaults;
+}): ResolvedContext;
+/**
+ * One call's override, applied over what `wrap` already resolved.
+ *
+ * Only reached when a call actually carried a `stiggContext`; a call that did not reuses the
+ * resolved object as-is. The ordering below is the one the caller asked for: the base identity
+ * first, because a changed customer or agent changes which budget is consulted, and the metering
+ * fields last, because nothing before the response depends on them.
+ */
+export declare function overrideContext(base: ResolvedContext, override: StiggContext): ResolvedContext;
+/** Whether a context gates at all. The enforcement switch, read on every call. */
+export declare const isEnforced: (context: ResolvedContext) => boolean;
+/** Reported metrics, accumulated across a client's calls. */
+export declare const addMetrics: (into: Metrics, add: Metrics) => void;