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

package/dist/types.d.ts

@@ -0,0 +1,531 @@
+/**
+ * The vocabulary shared by the core, the engines and every binding, and the argument list of
+ * every call on the public surface.
+ *
+ * Terms follow Stigg governance rather than the draft design notes: provision/archive (not
+ * register/de-register), ingest (not report), assignment (not budget), dimensions (not tags).
+ *
+ * The imports below are all `import type`, so they are erased at compile time: this file pulls in
+ * no module at runtime and stays the leaf everything else can depend on.
+ */
+import { EngineError } from './errors';
+import type { StiggContext } from './core/context';
+import type { GovernanceSummary, SessionHooks } from './core/session';
+import type { GovernanceHeaders } from './headers';
+import type { ClientRecipe } from './bindings/client/core/types';
+import type { ObservedVendor } from './bindings/shared/token-usage';
+import type { EventIngest } from './engine/engine';
+/**
+ * What a budget is measured against. Exactly one of the two - the same mutual exclusion the
+ * Stigg check endpoint enforces, expressed so the compiler catches it instead of the API.
+ */
+export type Entitlement = {
+    currencyId: string;
+    featureId?: never;
+} | {
+    featureId: string;
+    currencyId?: never;
+};
+/**
+ * Which of Stigg's two ingest APIs a run reports through.
+ *
+ * `'sync'` is `usage.report`/`reportUsageBulk`: a fixed DTO of `featureId` and a whole-number
+ * `value` per metric, aggregated the moment it lands, so the next check sees it. It costs more
+ * latency and has the lower rate limit.
+ *
+ * `'async'` is `events.report`/`reportEvent`: the call is reported as one event and Stigg's own
+ * meters turn it into usage, seconds later. Low latency, a far higher rate limit, and nothing
+ * meters at all until a **raw-events meter** is configured for the event name on Stigg's side.
+ */
+export type IngestMode = 'sync' | 'async';
+/** The id to send as `featureId`/`currencyId`, whichever kind the entitlement is. */
+export declare const entitlementId: (entitlement: Entitlement) => string;
+/** 'credit' targets read the customer's credit pool; 'feature' targets need an entitling subscription. */
+export declare const entitlementKind: (entitlement: Entitlement) => "credit" | "feature";
+/**
+ * The entitlement as every Stigg endpoint takes it: one of two mutually exclusive id fields,
+ * ready to spread.
+ *
+ * ```ts
+ * await client.v1Beta.customers.entitlements.check(customerId, { ...entitlementRef(entitlement), requestedUsage });
+ * ```
+ *
+ * Narrowing on the property rather than through {@link entitlementKind} is the point: a function
+ * call cannot narrow a union, so every hand-written version of this needed a `!` on each branch -
+ * an assertion that the union already guarantees and that would survive the union changing.
+ */
+export declare const entitlementRef: (entitlement: Entitlement) => {
+    currencyId: string;
+} | {
+    featureId: string;
+};
+/**
+ * Why an entitlement cannot be billed against, if one was named at all.
+ *
+ * Naming none is legal: it is how a caller asks for metering without enforcement, so undefined is
+ * not an error here. The one place an entitlement is genuinely required is an assignment, which is
+ * written over `(entity x entitlement)` - and `register` refuses that case itself, because only it
+ * knows the agent to name in the message.
+ *
+ * What stays refused is an entitlement that is named and names nothing. The union permits
+ * `{ currencyId: '' }`, and an empty currency is falsy - so it classifies as a feature and every
+ * branch downstream then asks for a `featureId` that is not there. An empty id is a typo rather
+ * than an intention, and letting it through meters a run against nothing while it still looks
+ * enforced.
+ */
+export declare function entitlementError(entitlement: Entitlement | undefined): Error | undefined;
+/**
+ * A provider-neutral token measurement. Every client/orchestrator binding normalizes into this
+ * before anything touches Stigg, so the mapper below is written once for all of them.
+ */
+export type TokenUsage = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheCreate: number;
+    /**
+     * What the vendor says the call cost in total, when it says anything.
+     *
+     * Apart from the four above, and deliberately so: those are disjoint and add up to the call,
+     * while this one *overlaps all of them*. It is here because a mapper that wants one number
+     * should be able to use the vendor's own rather than re-adding the parts and hoping the
+     * arithmetic matches - the two can differ, and when they do the vendor's is the one that gets
+     * invoiced.
+     *
+     * Read from the response where the vendor publishes a total, and summed from the four where it
+     * publishes none and they are disjoint. Undefined where neither is true, which is the honest
+     * answer rather than a guess: see `COMPUTED_TOTALS`.
+     */
+    total?: number;
+};
+export declare const emptyTokenUsage: () => TokenUsage;
+/**
+ * What one completed call reports: feature id -> whole-number value. One report each.
+ *
+ * A record rather than a list of `{featureId, value}` pairs, so the same feature cannot appear
+ * twice - two reports of one feature in one call would collide on idempotency keys and silently
+ * lose one of them.
+ */
+export type Metrics = Record<string, number>;
+/**
+ * Turns what a binding observed into the metrics to report.
+ *
+ * Defaults to the vendor's own: whatever names and values came back on the response. Supply your
+ * own to report something else - see `creditsPerTokens` for the one-number case, and each client
+ * recipe for what that vendor meters by default.
+ */
+export type MetricsMapper = (measurement: Measurement) => Metrics;
+/**
+ * What one completed call is worth, as the binding that observed it saw it.
+ *
+ * Two views of one call, and both are useful. `metrics` is what the vendor said, in the vendor's
+ * own words - reported as-is, so what lands in Stigg reconciles against what the vendor bills.
+ * `usage` is the same call flattened into four comparable counters, which is what a mapper writes
+ * against when it wants one number or one vocabulary across vendors.
+ */
+export type Measurement = {
+    /** The vendor's own field names and values, verbatim. What gets reported by default. */
+    metrics?: Metrics;
+    /** The same call, normalized and non-overlapping. Context for writing your own mapper. */
+    usage?: TokenUsage;
+    /**
+     * The vendor's usage object as it arrived, before any counter was picked out of it.
+     *
+     * Carried only so an event can state what the vendor said in full - it rides the event's
+     * dimensions under a `raw.` prefix, flattened to scalars, and a meter can then aggregate a
+     * counter this SDK does not know about yet. Never reported as a metric: a feature id has to be
+     * something the customer's catalog knows, and a vendor's changelog must not be able to invent
+     * one. The usage block only - never a response body, so no prompt or completion text leaves
+     * the process.
+     */
+    raw?: Record<string, unknown>;
+    /** Per-call attribution, merged over the run's own dimensions. e.g. the model that served. */
+    dimensions?: Record<string, string>;
+    /** The vendor's own request id, when it has one that is stable across its retries. */
+    idempotencyKey?: string;
+    /**
+     * Why this measurement does not cover everything the vendor billed, when it does not.
+     *
+     * For the case where usage exists that the response never carried - not a disagreement between
+     * two numbers the vendor gave, which is data the caller can judge for themselves, but work
+     * that was charged for and never reported. What is here is still ingested: a short measurement
+     * beats none. The reason is then raised through the same channel a failed read uses, so
+     * `onError` fires and `summary().ingestFailures` counts it, rather than the shortfall being
+     * something a reader of the docs was supposed to have known about.
+     */
+    incomplete?: string;
+};
+/** What a run reports when nobody says otherwise: exactly what the vendor stated. */
+export declare const vendorMetrics: MetricsMapper;
+/** A binding may report either shape; `TokenUsage` is the common case and stays terse. */
+export declare const toMeasurement: (value: TokenUsage | Measurement) => Measurement;
+/**
+ * Why a measured value cannot be reported, if it cannot.
+ *
+ * Zero is not an error - a cached refusal or an empty stream is a normal turn - but a mapper
+ * dividing by an unset config returns NaN or Infinity, and reading those as "nothing was used"
+ * meters the run at zero while every call still reports success. Those are refused in both modes;
+ * a fraction is refused only under `'sync'`, whose DTO takes whole units.
+ *
+ * Shared, because every path that reports usage has to answer this the same way.
+ */
+export declare function usageValueError(value: number, mode?: IngestMode): EngineError | undefined;
+/**
+ * One metric, summed from every token class and divided by the unit size.
+ *
+ * The mapper for an application that prices tokens itself rather than letting Stigg convert a
+ * credit-backed feature. Weighting cache reads cheaper is a pricing decision and belongs in
+ * Stigg's consumption mapping, not here; Stigg rejects fractions, so the result rounds up.
+ */
+export declare const creditsPerTokens: (featureId: string, tokensPerUnit?: number) => MetricsMapper;
+/** What the caller should do about a denial. A refusal is a commercial event, not an error. */
+export type GovernanceRemedy = 'top-up' | 'raise-budget' | 'subscribe' | 'retry';
+/**
+ * Which client answered, or - for 'cache', 'policy' and 'unenforced' - that nothing was asked.
+ *
+ * `'unenforced'` is the one that could not have been asked: the run named no entitlement, so there
+ * is no budget to consult and every decision it hands back is an allow.
+ */
+export type DecisionSource = 'rest' | 'node-sdk' | 'cache' | 'policy' | 'unenforced';
+/**
+ * The structured refusal. Returned, never thrown, everywhere the caller has a return path:
+ * the denial path is a revenue surface (top-up, upgrade), so it must be inspectable.
+ */
+export type GovernanceDecision = {
+    hasAccess: boolean;
+    /** Which entity blocked - a governance node, or the customer when governance is not in play. */
+    deniedBy?: string;
+    /**
+     * Why it was refused. Stigg's `accessDeniedReason` verbatim, except where `locallyDerived` says
+     * the SDK reached the verdict itself. `InsufficientCredits` and `BudgetExceeded` differ.
+     */
+    reason?: string;
+    remedy?: GovernanceRemedy;
+    /** Tightest remaining budget across the pool and the chain. Undefined when nothing is bounded. */
+    remaining?: number;
+    usageLimit?: number | null;
+    currentUsage?: number;
+    source: DecisionSource;
+    checkedAt: number;
+    /** True when the engine served this from its own fallback rather than live state. */
+    isFallback?: boolean;
+    /**
+     * True when the SDK decided this rather than Stigg. A credit check reads the balance and
+     * compares it against the requested amount here, because the credit read takes no requested
+     * usage to adjudicate - so the balance is Stigg's, and the refusal is the SDK's.
+     *
+     * Distinct from `isFallback`: that one says the state was stale, this one says the state was
+     * live and the arithmetic was ours. Both can be true, and `strictCheck: false` on the engine's
+     * capabilities is the same admission at the level above.
+     */
+    locallyDerived?: boolean;
+    /** One line for a log: every field that matters, already formatted. */
+    summary: string;
+    /** What to tell the user. A refusal is a commercial event, so it carries its own remedy. */
+    message: string;
+};
+/**
+ * The outcome of one ingest - which is now one report per metric, so the result is per metric too.
+ * Never a rejection: metering must not break the caller's run.
+ */
+export type IngestResult = {
+    /** True only when every metric landed. One failure among four is not a success. */
+    ok: boolean;
+    /** What was reported, by feature id. Empty when the call measured nothing at all. */
+    reported: Metrics;
+    /**
+     * The key the report deduped on. Under `'sync'` each metric is keyed
+     * `${idempotencyKey}:${featureId}`, so they dedupe independently; under `'async'` the whole
+     * turn is one event under this key alone.
+     */
+    idempotencyKey: string;
+    /** Which API this went through, because the two answer with different amounts of truth. */
+    mode: IngestMode;
+    /**
+     * Stigg reported nothing consumed for every metric: these keys were already ingested.
+     * **Undefined under `'async'`** - the event API answers with an empty body, so a replay is
+     * something Stigg does and the SDK cannot observe. Saying `false` would be a claim, not a fact.
+     */
+    replayed?: boolean;
+    /**
+     * Credits this report actually drew, when Stigg said so. Absent when the features reported are
+     * not credit-backed - which is also when the run's budget will never drain - and always absent
+     * under `'async'`, which returns no balance at all.
+     */
+    creditsConsumed?: number;
+    error?: unknown;
+};
+/**
+ * What a check resolves to when the engine could not answer it. A policy, not a notification:
+ * hooks are told what happened and cannot change it, while this decides the outcome. Ingest has
+ * no equivalent - a failed ingest never affects a run, it only reaches `hooks.onError`.
+ */
+export type CheckErrorAction = 'deny' | 'allow';
+/** What binding a vendor client needs: how to recognise it, what to watch, and what governs it. */
+export type ClientOptions = {
+    /**
+     * Use this adapter instead of matching the client by its shape and base URL. The built-in ones
+     * cover Anthropic, OpenAI, OpenRouter and LiteLLM; reach for this when a vendor none of them
+     * identifies needs one of its own.
+     */
+    recipe?: ClientRecipe;
+    /** Everything this client reports back while it works. See {@link SessionHooks}. */
+    hooks?: SessionHooks;
+    /** The default context for every call through this client. Any call may override it. */
+    stiggContext?: StiggContext;
+};
+/**
+ * `register` - giving an agent an identity, a budget, and a place in the tree.
+ *
+ * A write, which is why it is its own call rather than something a gated call carries: a limit is
+ * not a field on the entity, so this is two idempotent upserts underneath - the entity, then an
+ * assignment over `(entity x entitlement)`. That is also why `parentId` belongs here and not on
+ * the entity: the hierarchy is per-entitlement.
+ *
+ * Optional throughout. Skip it and the agent has no entity - calls still work, and checks and
+ * usage apply to the customer instead.
+ */
+export type AgentOptions = {
+    /** The durable agent. This is the entity budgets attach to. */
+    agentId: string;
+    /**
+     * The governance entity type to create the agent as. Required, and not defaulted: a guessed
+     * type pairs the agent with an attribution key nothing resolves, and the spend then lands on
+     * the customer looking exactly like a call that was never governed.
+     */
+    entityTypeId: string;
+    displayName?: string;
+    metadata?: Record<string, string>;
+    /** Places the agent under a parent entity. Tri-state: omit to leave it, null to make it a root. */
+    parentId?: string | null;
+    /** Budget for this agent, written on every call. Omit to leave whatever is already assigned. */
+    usageLimit?: number | null;
+    /**
+     * Budget applied only when this agent has no assignment yet. Use this rather than `usageLimit`
+     * when an admin may change the budget out of band: `usageLimit` would overwrite their change on
+     * every process start. Mutually exclusive with `usageLimit`.
+     */
+    usageLimitOnCreate?: number;
+    /** ISO-8601 single-unit reset window, e.g. 'P1M'. Governance requires it when creating a budget. */
+    cadence?: string;
+};
+export type AgentScope = {
+    /** The tenant. Every governance call is scoped to one customer. */
+    customerId: string;
+    /**
+     * Which entitlement the budget is written against. Optional only because a bare registration is
+     * an identity and nothing else, and a metering-only run has none to hand over. A call carrying
+     * `usageLimit`, `usageLimitOnCreate` or `parentId` still needs one and `register` refuses it
+     * without: an assignment is written over `(entity x entitlement)`, so a placement with nothing
+     * to write it against has nowhere to land.
+     */
+    entitlement?: Entitlement;
+};
+/** `register` - the standalone call, which has no run to take the scope from. */
+export type RegisterInput = AgentOptions & AgentScope;
+/** `deregister` - archiving the entity. No entitlement: an entity is not archived per-entitlement. */
+export type DeregisterInput = Pick<AgentScope, 'customerId'> & Pick<AgentOptions, 'agentId'>;
+/**
+ * Every property path the shipped recipes gate, written as the overlay walks it.
+ *
+ * Paths, not leaf names. The extra field has to appear in the vendor's own parameter type or an
+ * object literal carrying it is an excess-property error - but matching on the last segment alone
+ * also typed `stiggContext` onto every *other* method that happened to share the name. `create` is
+ * the common one: `openai.files.create` and `openai.batches.create` are not gated by any recipe,
+ * so a caller who passed a context there type-checked, was never checked, and handed the vendor an
+ * unknown field it would forward rather than strip - the exact harm the narrow list existed to
+ * prevent.
+ *
+ * `messages.stream` is here without being in any recipe's `methods`: it reaches the wire through
+ * the gated `messages.create`, so a context given to it does arrive.
+ */
+export type GatedPath = ['messages', 'create'] | ['messages', 'stream'] | ['chat', 'completions', 'create'] | ['responses', 'create'] | ['systemOne'] | ['models', 'generateContent'] | ['models', 'generateContentStream'];
+/**
+ * Gemini's conversational surface, which is wrapped as an object in its own right: a `Chat` holds
+ * the models module privately, so wrapping the client never reaches these. The paths are one
+ * segment long because the `Chat` *is* the client there.
+ *
+ * Kept OUT of {@link GatedPath} and reached only through {@link ChatOf}, because one segment is
+ * the whole path here and `sendMessage` is far too common a verb to claim globally. In the
+ * fallback list it typed `stiggContext` onto any client that happened to have one - a Slack
+ * client, a queue client - and on a client that some *other* recipe matched, that was the silent
+ * case the narrow list exists to prevent: `wrap` succeeded, the method was never gated, and the
+ * context object was forwarded to the vendor as an unknown field.
+ */
+export type ChatGatedPath = ['sendMessage'] | ['sendMessageStream'];
+/**
+ * The paths to overlay when no recipe was named, given what the client actually looks like.
+ *
+ * `getHistory` is the discriminator, and it is exactly what `geminiChatRecipe.matches` requires -
+ * so the types promise a context on precisely the methods the runtime will gate, rather than on
+ * every object with a method of that name.
+ */
+/**
+ * The shapes the registry matches *before* it ever reaches the chat recipe.
+ *
+ * `geminiChatRecipe` is last in the shipped list, so any of these wins - which means a client
+ * carrying one of them has its chat methods left unpatched however chat-shaped it also looks.
+ */
+type GatedVendorShape = {
+    messages: {
+        create: unknown;
+    };
+} | {
+    chat: {
+        completions: {
+            create: unknown;
+        };
+    };
+} | {
+    responses: {
+        create: unknown;
+    };
+} | {
+    models: {
+        generateContent: unknown;
+    };
+} | {
+    models: {
+        generateContentStream: unknown;
+    };
+} | {
+    systemOne: unknown;
+};
+/**
+ * Which paths to overlay when no recipe was named, given what the client looks like.
+ *
+ * `getHistory` is the discriminator, and it is what `geminiChatRecipe.matches` requires - so the
+ * types promise a context on the methods the runtime will gate rather than on every object with
+ * a method of that name.
+ *
+ * It is not enough on its own, though. A client carrying *both* a gated vendor's shape and a
+ * chat's is matched as that vendor, leaving `sendMessage` unpatched - and an overlay keyed on
+ * `getHistory` alone still invited a context onto it, which is never checked and is handed to
+ * the vendor as an unknown field. So anything the registry would claim first is excluded here,
+ * mirroring that precedence.
+ */
+export type ChatOf<T> = T extends GatedVendorShape ? GatedPath : T extends {
+    getHistory: (...args: any[]) => any;
+} ? GatedPath | ChatGatedPath : GatedPath;
+/**
+ * The paths still live after stepping through `K`, or `never` when that key leads nowhere gated.
+ *
+ * This is what bounds the walk: recursion follows the paths themselves, so there is no depth
+ * budget to keep in step with the deepest vendor surface, and no mapping of branches - a client's
+ * whole `files` or `batches` subtree - that could never hold a gated method.
+ */
+type Below<Paths extends readonly string[], K> = Paths extends readonly [infer Head, ...infer Rest] ? Head extends K ? Rest extends readonly string[] ? Rest : never : never : never;
+/** One signature, with the context threaded into whatever parameter object it already takes. */
+type GatedSignature<P, R extends unknown[], Ret, Ctx> = P extends object ? (params: P & {
+    stiggContext?: Ctx;
+}, ...rest: R) => Ret : (params: P, ...rest: R) => Ret;
+/**
+ * A gated method, overloads and all.
+ *
+ * The arms are tried widest first because a single `infer` arm would silently collapse an
+ * overloaded method to its **last** signature - and `chat.completions.create` is overloaded
+ * precisely on `stream`, so collapsing it would hand a streaming caller the non-streaming return
+ * type. Three arms covers every vendor method the recipes gate; a fourth overload would fall
+ * through to the last arm and keep working, minus the earlier signatures.
+ */
+type GatedMethod<F, Ctx> = F extends {
+    (params: infer P1, ...rest: infer R1): infer T1;
+    (params: infer P2, ...rest: infer R2): infer T2;
+    (params: infer P3, ...rest: infer R3): infer T3;
+} ? GatedSignature<P1, R1, T1, Ctx> & GatedSignature<P2, R2, T2, Ctx> & GatedSignature<P3, R3, T3, Ctx> : F extends {
+    (params: infer P1, ...rest: infer R1): infer T1;
+    (params: infer P2, ...rest: infer R2): infer T2;
+} ? GatedSignature<P1, R1, T1, Ctx> & GatedSignature<P2, R2, T2, Ctx> : F extends (params: infer P, ...rest: infer R) => infer Ret ? GatedSignature<P, R, Ret, Ctx> : F;
+/**
+ * The client's own surface, with every gated method taught to accept a `stiggContext`.
+ *
+ * Rebuilt structurally, which on its own would lose the vendor's class identity - so
+ * {@link GovernedClient} intersects it back with `T` rather than replacing it. The overlay comes
+ * first in that intersection on purpose: an intersection of two call signatures is an overload
+ * set resolved in order, and the vendor's own signature would reject `stiggContext` as an excess
+ * property if it were tried first.
+ */
+export type GatedSurface<T, Ctx, Paths extends readonly string[] = GatedPath> = {
+    [K in keyof T]: [Below<Paths, K>] extends [never] ? T[K] : [
+    ] extends Below<Paths, K> ? GatedMethod<T[K], Ctx> : GatedSurface<T[K], Ctx, Below<Paths, K>>;
+};
+/**
+ * Which paths a wrapped client accepts a context on: the recipe's own, or the shipped ones.
+ *
+ * `wrap` infers the options object it was handed, so a recipe passed inline keeps whatever types
+ * it was written with - and a recipe that declares its paths as literals (`path: [...] as const`)
+ * gets the overlay on exactly the methods it gates, rather than on the shipped vendors' paths.
+ *
+ * Anything else falls back to {@link GatedPath}: no recipe at all, which is the detection case, and
+ * a recipe whose paths widened to `string[]`, where there is nothing to narrow to and guessing
+ * would be worse than the default. So this only ever adds precision; it cannot take it away.
+ */
+export type PathsOf<R, T = unknown> = R extends {
+    methods: readonly {
+        path: infer P;
+    }[];
+} ? P extends readonly [string, ...string[]] ? P : ChatOf<T> : ChatOf<T>;
+/**
+ * What a call still owes, given what `wrap` was already told.
+ *
+ * `customerId` is the one field that has to come from somewhere, so a client wrapped without one
+ * types it as required on every call and a client wrapped with one types it as optional. The
+ * runtime checks it either way, for callers the types never reached.
+ */
+export type CallContext<Wrapped> = Wrapped extends {
+    customerId: string;
+} ? StiggContext : StiggContext & {
+    customerId: string;
+};
+/**
+ * A vendor client bound to this environment. Every call its recipe covers is checked before it
+ * leaves and metered after, against the context `wrap` was given and whatever the call overrides.
+ */
+export type GovernedClient<T, Wrapped = StiggContext, Paths extends readonly string[] = GatedPath> = GatedSurface<T, CallContext<Wrapped>, Paths> & T & {
+    /** What this client did, and what is still in flight. */
+    readonly stigg: ClientGovernance;
+};
+/** The governance handle hung off a wrapped client. */
+export type ClientGovernance = {
+    /** Waits for in-flight ingests, then reports what this client did. */
+    flush(): Promise<GovernanceSummary>;
+    /** Drains, then releases what this client holds. */
+    close(): Promise<void>;
+    /** What this client has done so far, without waiting. */
+    summary(): GovernanceSummary;
+    /** The last decision this client made, or undefined if it has made none. */
+    readonly lastDecision?: GovernanceDecision;
+    /** The `x-stigg-*` attribution for work continuing in another process. */
+    headers(override?: StiggContext): GovernanceHeaders;
+    /** The gate, for a call this client does not wrap. */
+    check(override?: StiggContext, requestedUsage?: number): Promise<GovernanceDecision>;
+    /** The meter, for usage this client did not observe. */
+    report(metrics: Metrics, override?: StiggContext): Promise<IngestResult>;
+};
+/** What an out-of-process ingest needs, since it has no run to carry it. */
+export type IngestContext = {
+    /** What the run this usage belongs to checks against. Defaults to the `credits` currency. */
+    entitlement?: Entitlement;
+    /**
+     * What to report. Defaults to the vendor's own names, read off the usage object the proxy
+     * observed - the same default a wrapped client gets.
+     */
+    metrics?: MetricsMapper;
+    /**
+     * Which shape the observed usage is. Named rather than sniffed: Anthropic and the Responses API
+     * both count `input_tokens`, and a wrong guess would report to another customer's meter.
+     * Omitted, only the normalized counters are available - so supply a `metrics` mapper too.
+     */
+    vendor?: ObservedVendor;
+    /** Which of Stigg's ingest APIs to report through. Defaults to the client's setting. */
+    ingest?: IngestMode;
+    /**
+     * What the event is called in `'async'` mode. There is no wrapped call out here to name it
+     * after, so a proxy either says, or is reported under the vendor it declared.
+     *
+     * Singular, and named to match `IngestOptions.event`: one report is one event, whatever the
+     * turn measured.
+     */
+    event?: EventIngest;
+};
+export {};

package/dist/types.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.creditsPerTokens = exports.toMeasurement = exports.vendorMetrics = exports.emptyTokenUsage = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = void 0;
+exports.entitlementError = entitlementError;
+exports.usageValueError = usageValueError;
+/**
+ * The vocabulary shared by the core, the engines and every binding, and the argument list of
+ * every call on the public surface.
+ *
+ * Terms follow Stigg governance rather than the draft design notes: provision/archive (not
+ * register/de-register), ingest (not report), assignment (not budget), dimensions (not tags).
+ *
+ * The imports below are all `import type`, so they are erased at compile time: this file pulls in
+ * no module at runtime and stays the leaf everything else can depend on.
+ */
+const errors_1 = require("./errors");
+/** The id to send as `featureId`/`currencyId`, whichever kind the entitlement is. */
+const entitlementId = (entitlement) => entitlement.currencyId ?? entitlement.featureId;
+exports.entitlementId = entitlementId;
+/** 'credit' targets read the customer's credit pool; 'feature' targets need an entitling subscription. */
+const entitlementKind = (entitlement) => entitlement.currencyId ? 'credit' : 'feature';
+exports.entitlementKind = entitlementKind;
+/**
+ * The entitlement as every Stigg endpoint takes it: one of two mutually exclusive id fields,
+ * ready to spread.
+ *
+ * ```ts
+ * await client.v1Beta.customers.entitlements.check(customerId, { ...entitlementRef(entitlement), requestedUsage });
+ * ```
+ *
+ * Narrowing on the property rather than through {@link entitlementKind} is the point: a function
+ * call cannot narrow a union, so every hand-written version of this needed a `!` on each branch -
+ * an assertion that the union already guarantees and that would survive the union changing.
+ */
+const entitlementRef = (entitlement) => entitlement.currencyId !== undefined ? { currencyId: entitlement.currencyId } : { featureId: entitlement.featureId };
+exports.entitlementRef = entitlementRef;
+/**
+ * Why an entitlement cannot be billed against, if one was named at all.
+ *
+ * Naming none is legal: it is how a caller asks for metering without enforcement, so undefined is
+ * not an error here. The one place an entitlement is genuinely required is an assignment, which is
+ * written over `(entity x entitlement)` - and `register` refuses that case itself, because only it
+ * knows the agent to name in the message.
+ *
+ * What stays refused is an entitlement that is named and names nothing. The union permits
+ * `{ currencyId: '' }`, and an empty currency is falsy - so it classifies as a feature and every
+ * branch downstream then asks for a `featureId` that is not there. An empty id is a typo rather
+ * than an intention, and letting it through meters a run against nothing while it still looks
+ * enforced.
+ */
+function entitlementError(entitlement) {
+    if (!entitlement)
+        return undefined;
+    if ((0, exports.entitlementId)(entitlement)?.trim())
+        return undefined;
+    return new Error('a run needs a non-empty currencyId or featureId - an empty one bills against nothing.');
+}
+const emptyTokenUsage = () => ({ input: 0, output: 0, cacheRead: 0, cacheCreate: 0 });
+exports.emptyTokenUsage = emptyTokenUsage;
+/** What a run reports when nobody says otherwise: exactly what the vendor stated. */
+const vendorMetrics = (measurement) => measurement.metrics ?? {};
+exports.vendorMetrics = vendorMetrics;
+/** A binding may report either shape; `TokenUsage` is the common case and stays terse. */
+const toMeasurement = (value) => 'input' in value ? { usage: value } : value;
+exports.toMeasurement = toMeasurement;
+/**
+ * Why a measured value cannot be reported, if it cannot.
+ *
+ * Zero is not an error - a cached refusal or an empty stream is a normal turn - but a mapper
+ * dividing by an unset config returns NaN or Infinity, and reading those as "nothing was used"
+ * meters the run at zero while every call still reports success. Those are refused in both modes;
+ * a fraction is refused only under `'sync'`, whose DTO takes whole units.
+ *
+ * Shared, because every path that reports usage has to answer this the same way.
+ */
+function usageValueError(value, mode = 'sync') {
+    if (!Number.isFinite(value) || value < 0) {
+        return new errors_1.EngineError('ingest', `usage value must be a finite non-negative number, got ${value}`);
+    }
+    // An event carries the number as a dimension for a meter to aggregate, and a meter is free to
+    // sum fractions - which is the only way a gateway's `cost` reports honestly. The usage report
+    // takes a whole number or nothing.
+    if (mode === 'async' || Number.isInteger(value))
+        return undefined;
+    return new errors_1.EngineError('ingest', `usage value must be a positive whole number, got ${value}`);
+}
+/**
+ * One metric, summed from every token class and divided by the unit size.
+ *
+ * The mapper for an application that prices tokens itself rather than letting Stigg convert a
+ * credit-backed feature. Weighting cache reads cheaper is a pricing decision and belongs in
+ * Stigg's consumption mapping, not here; Stigg rejects fractions, so the result rounds up.
+ */
+const creditsPerTokens = (featureId, tokensPerUnit = 1) => ({ usage }) => usage
+    ? { [featureId]: Math.ceil((usage.input + usage.output + usage.cacheRead + usage.cacheCreate) / tokensPerUnit) }
+    : {};
+exports.creditsPerTokens = creditsPerTokens;