@stigg/agent-sdk-js 0.7.4 → 0.7.6

package/README.md

@@ -148,8 +148,6 @@ closed, and conflating them is how an outage takes an application down.
 | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/gemini.svg" width="18" alt=""> | Gemini | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/typesafe.png" width="18" alt=""> | TypeSafe |
 | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/groq.svg" width="18" alt=""> | Groq | | |
 
-**Frameworks** — [Vercel AI SDK](docs/vercel-ai.md): any model it runs, through `generateText`, `streamText` and agents. Model calls only, for now.
-
 **Gateways** — what was actually *charged*, and which model actually served after routing:
 
 | | Gateway | | Gateway |
@@ -163,7 +161,8 @@ closed, and conflating them is how an outage takes an application down.
 | | Orchestrator | | Orchestrator |
 | --- | --- | --- | --- |
 | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/langchain.svg" width="18" alt=""> | [LangChain](docs/langchain.md) | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/langgraph.svg" width="18" alt=""> | [LangGraph](docs/langchain.md#a-hand-built-langgraph) |
-| <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/google-adk.png" width="18" alt=""> | [Google ADK](docs/guide.md#google-adk-one-plugin-per-runner) | | Your own harness, through `stigg.middleware()` |
+| <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/google-adk.png" width="18" alt=""> | [Google ADK](docs/guide.md#google-adk-one-plugin-per-runner) | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/vercel.svg" width="18" alt=""> | [Vercel AI SDK](docs/vercel-ai.md) (model calls, for now) |
+| | Your own harness, through `stigg.middleware()` | | |
 
 Each binding is written against the *shape a vendor returns*, not against its SDK — so installing
 this package pulls in **no vendor packages at all**, and you install only the one you use.

package/dist/bindings/client/core/wrap-client.d.ts

@@ -4,3 +4,10 @@ import type { ClientRecipe } from './types';
 export declare function wrapClient<T extends object>(client: T, recipe: ClientRecipe, session: GovernanceSession, context: ResolvedContext): T;
 /** Whether this client is one `wrap(...)` handed back. */
 export declare function isGoverned(client: object): boolean;
+/**
+ * The model a call used, for its AUDR record: the response's word for it before the request's,
+ * since a router can serve another. Read by shape across vendors - `model` for most,
+ * `modelVersion` on a Gemini response, `input.modelId` on a Bedrock command, and a bare string
+ * for Cloudflare's `ai.run(model, inputs)`.
+ */
+export declare function modelOf(...sources: unknown[]): string | undefined;

package/dist/bindings/client/core/wrap-client.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapClient = wrapClient;
 exports.isGoverned = isGoverned;
+exports.modelOf = modelOf;
 /**
  * The client binding: a drop-in wrapper that gates before the call and meters after it.
  *
@@ -37,7 +38,7 @@ function wrapClient(client, recipe, session, context) {
     const copy = Object.create(client);
     let patched = 0;
     for (const method of recipe.methods) {
-        if (patch(copy, client, session, context, method, (0, types_2.eventNameFor)(recipe, method)))
+        if (patch(copy, client, session, context, method, (0, types_2.eventNameFor)(recipe, method), recipe.vendor))
             patched += 1;
     }
     // A recipe whose paths resolve to nothing produces a client that is stamped, looks governed,
@@ -84,7 +85,7 @@ function ownPath(copy, source, path) {
     }
     return { owner, realOwner };
 }
-function patch(copy, source, session, base, method, eventName) {
+function patch(copy, source, session, base, method, eventName, vendor) {
     const resolved = ownPath(copy, source, method.path.slice(0, -1));
     if (!resolved)
         return false;
@@ -150,12 +151,19 @@ function patch(copy, source, session, base, method, eventName) {
                 if (!decision.hasAccess)
                     throw new errors_1.AccessDeniedError(decision);
             }
+            const startedAt = Date.now();
             const result = await collect(original.apply(target, args), params);
             // Whatever the recipe reports - tokens for most vendors, real spend plus the model that
             // served it for one that knows better. The wrapper stays out of that judgement.
             const ingest = (measured) => {
                 const measurement = (0, types_1.toMeasurement)(measured);
-                void session.ingestMeasurement(context, measurement);
+                // What an AUDR record names and the measurement does not. Read when the usage arrives, so
+                // a stream's ingest finds the same answer a completed response does.
+                const traced = {
+                    ...context,
+                    audr: { provider: vendor, model: modelOf(result.data, params, args[0]), startedAt },
+                };
+                void session.ingestMeasurement(traced, measurement);
                 // Reported what it could, and said what it could not. A measurement that does not cover
                 // everything the vendor charged for is a metering failure even though the ingest itself
                 // succeeded - so it goes out *and* is raised, rather than one or the other.
@@ -182,6 +190,26 @@ function patch(copy, source, session, base, method, eventName) {
     };
     return true;
 }
+/**
+ * The model a call used, for its AUDR record: the response's word for it before the request's,
+ * since a router can serve another. Read by shape across vendors - `model` for most,
+ * `modelVersion` on a Gemini response, `input.modelId` on a Bedrock command, and a bare string
+ * for Cloudflare's `ai.run(model, inputs)`.
+ */
+function modelOf(...sources) {
+    for (const source of sources) {
+        if (typeof source === 'string' && source)
+            return source;
+        if (typeof source !== 'object' || source === null)
+            continue;
+        const fields = source;
+        for (const value of [fields.model, fields.modelVersion, fields.modelId, fields.input?.modelId]) {
+            if (typeof value === 'string' && value)
+                return value;
+        }
+    }
+    return undefined;
+}
 /**
  * How much to ask permission for, with the one answer a gate must never send.
  *

package/dist/bindings/orchestrator/adk/plugin.js

@@ -111,7 +111,12 @@ class StiggAdkPlugin extends adk_1.BasePlugin {
         const runId = `adk:${invocationId}:${++this.seq}`;
         const step = { agent: agentName, adkContext: callbackContext, model: llmRequest.model };
         try {
-            await this.middleware.startModel(runId, await this.attributionOf(step), 'adk.model');
+            // The invocation is the AUDR run: every model call of one `runAsync`, whichever agent made it.
+            const attribution = {
+                ...(await this.attributionOf(step)),
+                audr: { model: llmRequest.model, runId: invocationId },
+            };
+            await this.middleware.startModel(runId, attribution, 'adk.model');
         }
         catch (err) {
             const decision = (0, errors_1.isAccessDenied)(err);

package/dist/bindings/orchestrator/core/agent-middleware.d.ts

@@ -1,5 +1,6 @@
 import { type ResolvedContext, type StiggContext } from '../../../core/context';
 import type { GovernanceSession } from '../../../core/session';
+import type { AudrTrace } from '../../../core/audr';
 import { type Entitlement, type Measurement, type MiddlewareOptions, type MiddlewareTools, type ToolUsageMapper } from '../../../types';
 /** Who a step is for, as the framework stated it on that step. */
 export type StepAttribution = {
@@ -11,6 +12,12 @@ export type StepAttribution = {
      * applies a call's: the customer, dimensions, and anything else a call can override.
      */
     stiggContexts?: readonly StiggContext[];
+    /**
+     * What a model step called and where it sits in the framework's run tree, for its AUDR record.
+     * Optional: without it a record still goes out. Kept, not copied, until the step ends - so a
+     * binding can set `model` to the one the reply says served, which the start cannot know.
+     */
+    audr?: Pick<AudrTrace, 'provider' | 'model' | 'runId' | 'spanId' | 'parentSpanId'>;
 };
 /** A tool call the model issued in its reply: the id the tool step will refer back to, and what it named. */
 export type IssuedToolCall = {

package/dist/bindings/orchestrator/core/agent-middleware.js

@@ -253,8 +253,13 @@ function createAgentMiddleware(session, config) {
     return {
         async startModel(runId, attribution, eventName) {
             const resolved = contextFor(agentFor(attribution.agent).context, attribution);
-            const context = resolved.eventName ? resolved : { ...resolved, eventName: { name: eventName } };
+            const named = resolved.eventName ? resolved : { ...resolved, eventName: { name: eventName } };
+            // The framework's run id is this step's span, so a record lines up with the trace it is in.
+            const audr = Object.assign(attribution.audr ?? {}, { spanId: attribution.audr?.spanId ?? runId });
+            const context = { ...named, audr };
             await check(context);
+            // Started once the check is through, as `wrap` times a call: the record times the model, not Stigg.
+            audr.startedAt = Date.now();
             rememberStep(runId, { context });
         },
         // Awaited by the binding, so the agent's next check sees this spend. Safe to wait on: ingest

package/dist/bindings/orchestrator/langchain/callback-handler.d.ts

@@ -67,6 +67,12 @@ export declare class StiggLangChainCallbackHandler extends BaseCallbackHandler {
     handleToolStart(tool: unknown, input: string, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string, toolCallId?: string): Promise<void>;
     handleToolEnd(output: unknown, runId: string): Promise<void>;
     handleToolError(_err: unknown, runId: string): void;
+    /**
+     * A model step's attribution, plus what its AUDR record names: the provider and model LangChain
+     * states in its `ls_*` metadata, and the step's place in the run tree - the top-level run as the
+     * AUDR run, the run directly above as the parent span.
+     */
+    private modelAttributionOf;
     /**
      * Who a step is for: the configured agent above it in the run tree, and the `stiggContext`s the
      * run stated on the way down. With no agent above it, a name from metadata is passed on only as a

package/dist/bindings/orchestrator/langchain/callback-handler.js

@@ -117,6 +117,14 @@ class RunTree {
             return run.name;
         return this.agentAt(run.parent);
     }
+    /** The top of the tree above a run, as far as this handler saw it start. */
+    rootOf(runId) {
+        let current = runId;
+        for (let parent = this.open.get(current)?.parent; parent !== undefined; parent = this.open.get(current)?.parent) {
+            current = parent;
+        }
+        return current;
+    }
     isAgent(name) {
         return this.agents.has(name);
     }
@@ -179,11 +187,11 @@ class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
         this.runs.end(runId);
     }
     handleChatModelStart(_llm, _messages, runId, parentRunId, _extraParams, _tags, metadata) {
-        return this.middleware.startModel(runId, this.attributionOf(parentRunId, metadata), 'langchain.chat_model');
+        return this.middleware.startModel(runId, this.modelAttributionOf(runId, parentRunId, metadata), 'langchain.chat_model');
     }
     // The completion-model path, for an LLM that is not a chat model. Same gate, same meter.
     handleLLMStart(_llm, _prompts, runId, parentRunId, _extraParams, _tags, metadata) {
-        return this.middleware.startModel(runId, this.attributionOf(parentRunId, metadata), 'langchain.llm');
+        return this.middleware.startModel(runId, this.modelAttributionOf(runId, parentRunId, metadata), 'langchain.llm');
     }
     handleLLMEnd(output, runId) {
         const result = output;
@@ -216,6 +224,23 @@ class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
         this.runs.end(runId);
         this.middleware.abandon(runId);
     }
+    /**
+     * A model step's attribution, plus what its AUDR record names: the provider and model LangChain
+     * states in its `ls_*` metadata, and the step's place in the run tree - the top-level run as the
+     * AUDR run, the run directly above as the parent span.
+     */
+    modelAttributionOf(runId, parentRunId, metadata) {
+        const text = (value) => (typeof value === 'string' && value ? value : undefined);
+        return {
+            ...this.attributionOf(parentRunId, metadata),
+            audr: {
+                provider: text(metadata?.ls_provider),
+                model: text(metadata?.ls_model_name),
+                runId: parentRunId === undefined ? runId : this.runs.rootOf(parentRunId),
+                parentSpanId: parentRunId,
+            },
+        };
+    }
     /**
      * Who a step is for: the configured agent above it in the run tree, and the `stiggContext`s the
      * run stated on the way down. With no agent above it, a name from metadata is passed on only as a

package/dist/bindings/orchestrator/vercel-ai/middleware.d.ts

@@ -33,10 +33,12 @@ export type StiggVercelMiddleware = {
     wrapGenerate(options: {
         doGenerate: () => PromiseLike<any>;
         params: any;
+        model?: any;
     }): Promise<any>;
     wrapStream(options: {
         doStream: () => PromiseLike<any>;
         params: any;
+        model?: any;
     }): Promise<any>;
     /** What this middleware did, and what is still in flight. */
     readonly stigg: GovernedAgentMiddleware['stigg'];
@@ -47,4 +49,4 @@ export declare function stiggVercelMiddleware({ stigg, stiggContext, hooks, }: S
  * call's `abortSignal` - which is how the AI SDK stops a stream, without cancelling it.
  * ponytail: a reader that stops with no `abortSignal` is not reported; nothing tells this layer.
  */
-export declare function observeStream(result: any, signal: AbortSignal | undefined, done: (measurement: Measurement | undefined) => void): void;
+export declare function observeStream(result: any, signal: AbortSignal | undefined, done: (measurement: Measurement | undefined, modelId?: string) => void): void;

package/dist/bindings/orchestrator/vercel-ai/middleware.js

@@ -17,7 +17,9 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
     // `doGenerate()` takes no arguments: the model is called with what `transformParams` returned.
     // So the context comes out there, and is found again by that params object.
     const contexts = new WeakMap();
-    // A step's id only has to be unique among this middleware's own steps in flight.
+    // A step's id is also its AUDR span, so it is unique across middlewares, not only among this
+    // one's steps in flight: one id per middleware, and a counter under it.
+    const prefix = crypto.randomUUID();
     let steps = 0;
     // A stream reports when it ends, after `wrapStream` has returned - so the call's next step waits
     // for those reports here, and is checked against their spend. Keyed by the call: the AI SDK hands
@@ -27,13 +29,15 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
     const reporting = new Map();
     const callOf = (params) => contexts.get(params) ?? JSON.stringify([stiggContext?.customerId, stiggContext?.agentId]);
     /** Checks the step, as the agent and customer this call names. Refused: `AccessDeniedError`. */
-    const start = async (params, event) => {
+    const start = async (params, model, event) => {
         // Once: a call's steps run one after another, so nothing of its own lands while this waits.
         await Promise.all(reporting.get(callOf(params)) ?? []);
-        const runId = String(++steps);
+        const runId = `${prefix}:${++steps}`;
         const context = contexts.get(params);
-        await governance.startModel(runId, { stiggContexts: context ? [context] : [] }, event);
-        return runId;
+        // Kept by the middleware until the step ends, so the model the reply names can still land on it.
+        const trace = audrOf(model);
+        await governance.startModel(runId, { stiggContexts: context ? [context] : [], audr: trace }, event);
+        return { runId, trace };
     };
     return {
         specificationVersion: 'v3',
@@ -52,8 +56,8 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
                 contexts.set(stripped, context);
             return stripped;
         },
-        async wrapGenerate({ doGenerate, params }) {
-            const runId = await start(params, 'vercel-ai.generate');
+        async wrapGenerate({ doGenerate, params, model }) {
+            const { runId, trace } = await start(params, model, 'vercel-ai.generate');
             let result;
             try {
                 result = await doGenerate();
@@ -66,11 +70,12 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
             // usage stated: estimated from the reply, as a stream is, and counted as a metering failure.
             const responseId = result?.response?.id;
             const chars = (0, usage_1.contentChars)(result?.content);
+            served(trace, result?.response?.modelId);
             await governance.endModel(runId, (0, usage_1.measurementOf)(result?.usage, responseId) ?? (chars ? (0, usage_1.estimated)(chars, usage_1.NO_USAGE, responseId) : undefined));
             return result;
         },
-        async wrapStream({ doStream, params }) {
-            const runId = await start(params, 'vercel-ai.stream');
+        async wrapStream({ doStream, params, model }) {
+            const { runId, trace } = await start(params, model, 'vercel-ai.stream');
             let result;
             try {
                 result = await doStream();
@@ -79,9 +84,10 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
                 governance.abandon(runId);
                 throw err;
             }
-            observeStream(result, params?.abortSignal, (measurement) => {
+            observeStream(result, params?.abortSignal, (measurement, modelId) => {
                 if (!measurement)
                     return governance.abandon(runId);
+                served(trace, modelId);
                 const call = callOf(params);
                 const pending = reporting.get(call) ?? new Set();
                 reporting.set(call, pending);
@@ -97,6 +103,22 @@ function stiggVercelMiddleware({ stigg, stiggContext, hooks, }) {
         },
     };
 }
+/**
+ * What an AUDR record names for the model the AI SDK called. Its `provider` is the provider and the
+ * API it went through - `anthropic.messages`, `openai.chat` - and the vendor is the part before the dot.
+ */
+function audrOf(model) {
+    const text = (value) => (typeof value === 'string' && value ? value : undefined);
+    return {
+        provider: text(model?.provider)?.split('.')[0],
+        model: text(model?.modelId),
+    };
+}
+/** The model the reply says served, over the one the call asked for: a gateway or an alias can differ. */
+function served(trace, modelId) {
+    if (typeof modelId === 'string' && modelId)
+        trace.model = modelId;
+}
 /** What `incomplete` says for a stream that ended without its usage, by how it ended. */
 const STREAM_GAPS = {
     ended: usage_1.NO_USAGE,
@@ -119,14 +141,21 @@ function cancelEnd(reason) {
 function streamTally() {
     let usage;
     let responseId;
+    let modelId;
     let chars = 0;
     return {
+        /** The model the stream's metadata said served, if it said. */
+        modelId: () => modelId,
         /** Never throws: a malformed part is simply not counted. */
         record(part) {
             if (part?.type === 'finish')
                 usage = part.usage;
-            else if (part?.type === 'response-metadata' && typeof part.id === 'string')
-                responseId = part.id;
+            else if (part?.type === 'response-metadata') {
+                if (typeof part.id === 'string')
+                    responseId = part.id;
+                if (typeof part.modelId === 'string')
+                    modelId = part.modelId;
+            }
             else if (typeof part?.delta === 'string')
                 chars += part.delta.length;
         },
@@ -165,7 +194,7 @@ function observeStream(result, signal, done) {
         reported = true;
         // Every step of a loop shares the signal, which may live as long as the process.
         signal?.removeEventListener('abort', onAbort);
-        done(tally.measurement(end));
+        done(tally.measurement(end), tally.modelId());
     };
     const onAbort = () => report(isTimeout(signal?.reason) ? 'timedOut' : 'stopped');
     signal?.addEventListener('abort', onAbort, { once: true });

package/dist/config.d.ts

@@ -15,6 +15,7 @@ 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';
+import type { AudrOptions } from './core/audr';
 declare const dataSchema: z.ZodObject<{
     apiKey: z.ZodString;
     baseUrl: z.ZodOptional<z.ZodString>;
@@ -125,6 +126,14 @@ export type StiggAgentSDKOptions = {
      * Replace it to route an `EngineError` and its {@link ErrorContext} into your own telemetry.
      */
     onError?: (error: EngineError, context: ErrorContext) => void;
+    /**
+     * Also write an AUDR record (https://openaudr.dev) for every model call this SDK measures, to
+     * the application's own `@openaudr/audr` client. Off unless set.
+     *
+     * For systems other than Stigg - Chargebee, Lago, an OTel collector. Stigg already receives this
+     * usage directly, so do not point the client at a Stigg sink: every call would count twice.
+     */
+    audr?: AudrOptions;
 };
 export type ResolvedConfig = Omit<Required<z.infer<typeof dataSchema>>, 'baseUrl'> & {
     baseUrl?: string;
@@ -132,6 +141,7 @@ export type ResolvedConfig = Omit<Required<z.infer<typeof dataSchema>>, 'baseUrl
     client?: NodeSdkClient;
     logger: Logger;
     onError: (error: EngineError, context: ErrorContext) => void;
+    audr?: AudrOptions;
 };
 export declare function resolveConfig(options?: StiggAgentSDKOptions): ResolvedConfig;
 /** The slice of config the engine factory needs. */

package/dist/config.js

@@ -92,6 +92,7 @@ function resolveConfig(options = {}) {
         ...parsed,
         cache: options.cache,
         client: options.client,
+        audr: options.audr,
         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}`)),
@@ -112,6 +113,7 @@ function resolveConfig(options = {}) {
         ...config,
         apiKey: config.apiKey ? '[redacted]' : undefined,
         client: config.client ? '[client supplied by the caller]' : undefined,
+        audr: config.audr ? { environment: config.audr.environment, client: '[client supplied by the caller]' } : undefined,
     });
     for (const key of ['toJSON', Symbol.for('nodejs.util.inspect.custom')]) {
         Object.defineProperty(config, key, { value: redacted, enumerable: false, writable: false });

package/dist/core/audr.d.ts

@@ -0,0 +1,107 @@
+import type { Measurement } from '../types';
+import type { ResolvedContext } from './context';
+/** The spec version these records are written to. */
+export declare const AUDR_SPEC_VERSION = "1.1.0";
+/** How this SDK signs its records: the harness, under its own package name. */
+export declare const AUDR_EMITTER: {
+    readonly component: "harness";
+    readonly name: "@stigg/agent-sdk-js";
+    readonly version: string;
+};
+/** AUDR's environments. A sink ignores a record that names none, so one is required here. */
+export declare const AUDR_ENVIRONMENTS: readonly ["production", "staging", "development", "test", "evaluation"];
+export type AudrEnvironment = (typeof AUDR_ENVIRONMENTS)[number];
+/**
+ * One AUDR record, as this SDK writes it - a subset of the spec's, structurally compatible with
+ * `@openaudr/audr`'s `AudrRecord`, so the host's `Client` takes it as is.
+ */
+export type AudrRecord = {
+    spec_version: string;
+    record_id: string;
+    emitter: {
+        component: 'harness';
+        name: string;
+        version: string;
+    };
+    resource: {
+        type: 'model';
+        operation: 'generation';
+        modality: 'text';
+        provider: string;
+        name: string;
+    };
+    run: {
+        run_id: string;
+        span_id: string;
+        parent_span_id?: string;
+        name?: string;
+    };
+    attribution: {
+        environment: AudrEnvironment;
+        account_id: string;
+        feature_id?: string;
+        labels?: Record<string, string>;
+    };
+    usage: {
+        llm: {
+            input_tokens?: number;
+            output_tokens?: number;
+            cache_read_tokens?: number;
+            cache_write_tokens?: number;
+            requests: number;
+        };
+    };
+    timing: {
+        event_time: string;
+        duration_ms?: number;
+    };
+};
+/** What this SDK needs of an `@openaudr/audr` `Client`: somewhere to hand a record. */
+export type AudrClientLike = {
+    /** Validates and queues the record. The real one returns at once and never throws. */
+    record(record: AudrRecord): unknown;
+};
+export type AudrOptions = {
+    /**
+     * The host's own AUDR client - `new Client(sink)` from `@openaudr/audr`. Its sink decides where
+     * records go; this SDK never creates, flushes or shuts it down.
+     */
+    client: AudrClientLike;
+    /** Which environment the records are for. Every record carries the customer, as `account_id`. */
+    environment: AudrEnvironment;
+};
+/**
+ * What a binding knows about one call that the measurement does not: who served it, which model,
+ * where it sits in a run tree, and when it started. Never sent to Stigg.
+ */
+export type AudrTrace = {
+    /** The vendor that was called - the recipe's own name for it. */
+    provider?: string;
+    /** The model the vendor says served, falling back to the one the request named. */
+    model?: string;
+    /**
+     * The run this call belongs to, when a framework's run tree says. Otherwise the correlation id
+     * when the caller stated one, and the call alone when it did not.
+     */
+    runId?: string;
+    /** This call's own span. Generated when the binding has none. */
+    spanId?: string;
+    /** The span this call ran under, when a framework's run tree says. */
+    parentSpanId?: string;
+    /** `Date.now()` when the call started, for `timing.duration_ms`. */
+    startedAt?: number;
+};
+/** Emits one record per measured model call. Built once per SDK, shared by every session. */
+export type AudrEmitter = {
+    /** Returns what the client's `record()` did, so a client whose record() is async is still caught. */
+    emit(context: ResolvedContext, measurement: Measurement): unknown;
+};
+/**
+ * Refused at construction rather than at the first call: a client that cannot take a record, or an
+ * environment a sink will ignore, would otherwise drop every record without a word.
+ */
+export declare function createAudrEmitter(options: AudrOptions, warn: (message: string) => void): AudrEmitter;
+/** The record for one call, or nothing when there is no token usage to state. */
+export declare function toRecord(context: ResolvedContext, measurement: Measurement, environment: AudrEnvironment, now?: number): AudrRecord | undefined;
+/** A UUIDv7 (RFC 9562): 48 bits of Unix milliseconds, then random bits. AUDR's `record_id`. */
+export declare function uuidv7(now?: number): string;

package/dist/core/audr.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDR_ENVIRONMENTS = exports.AUDR_EMITTER = exports.AUDR_SPEC_VERSION = void 0;
+exports.createAudrEmitter = createAudrEmitter;
+exports.toRecord = toRecord;
+exports.uuidv7 = uuidv7;
+const sdk_identity_1 = require("../sdk-identity");
+/** The spec version these records are written to. */
+exports.AUDR_SPEC_VERSION = '1.1.0';
+/** How this SDK signs its records: the harness, under its own package name. */
+exports.AUDR_EMITTER = {
+    component: 'harness',
+    name: '@stigg/agent-sdk-js',
+    version: sdk_identity_1.AGENT_SDK_VERSION,
+};
+/** AUDR's environments. A sink ignores a record that names none, so one is required here. */
+exports.AUDR_ENVIRONMENTS = [
+    'production',
+    'staging',
+    'development',
+    'test',
+    'evaluation',
+];
+/**
+ * Refused at construction rather than at the first call: a client that cannot take a record, or an
+ * environment a sink will ignore, would otherwise drop every record without a word.
+ */
+function createAudrEmitter(options, warn) {
+    if (typeof options?.client?.record !== 'function') {
+        throw new Error("`audr.client` has no record() method. Pass the application's own AUDR client - " +
+            '`new Client(sink)` from `@openaudr/audr`.');
+    }
+    if (!exports.AUDR_ENVIRONMENTS.includes(options.environment)) {
+        throw new Error(`\`audr.environment\` is '${String(options.environment)}' - it must be one of ` +
+            `${exports.AUDR_ENVIRONMENTS.join(', ')}. A sink ignores a record that names none.`);
+    }
+    const { client, environment } = options;
+    let warnedShort = false;
+    return {
+        emit(context, measurement) {
+            // An estimate is this SDK's number, not the vendor's, and an incomplete measurement fills
+            // what the vendor left out with zeros - AUDR has no way to say either. A downstream system
+            // counts what a record states, so it must be only what the provider stated.
+            if (measurement.estimated || measurement.incomplete) {
+                if (!warnedShort) {
+                    warnedShort = true;
+                    warn('[stigg] an estimated or incomplete measurement was not emitted as an AUDR record: AUDR carries only ' +
+                        'stated usage.');
+                }
+                return undefined;
+            }
+            const record = toRecord(context, measurement, environment);
+            return record ? client.record(record) : undefined;
+        },
+    };
+}
+/** The record for one call, or nothing when there is no token usage to state. */
+function toRecord(context, measurement, environment, now = Date.now()) {
+    const llm = llmUsage(measurement.usage);
+    if (!llm)
+        return undefined;
+    const trace = context.audr ?? {};
+    const labels = labelsOf({ ...context.dimensions, ...measurement.dimensions });
+    const spanId = trace.spanId || crypto.randomUUID();
+    const record = {
+        spec_version: exports.AUDR_SPEC_VERSION,
+        record_id: uuidv7(now),
+        emitter: { ...exports.AUDR_EMITTER },
+        resource: {
+            type: 'model',
+            operation: 'generation',
+            // Required for a model. `text` is the adapters' own default: no recipe here reads a call's
+            // modality, and a vision or audio call is still metered by the tokens it states.
+            modality: 'text',
+            provider: providerSlug(trace.provider),
+            name: trace.model || 'unknown',
+        },
+        run: {
+            // A generated correlation id is the wrap's, not a run's: one client wrapped at module scope
+            // would make every call it ever makes, for every customer, a single run.
+            run_id: runIdOf(trace.runId ?? (context.correlationStated ? context.correlationId : spanId)),
+            span_id: spanId,
+            ...(trace.parentSpanId ? { parent_span_id: trace.parentSpanId } : {}),
+            ...(context.agent ? { name: context.agent } : {}),
+        },
+        attribution: {
+            environment,
+            account_id: context.customerId,
+            ...(context.checkedId ? { feature_id: context.checkedId } : {}),
+            ...(labels ? { labels } : {}),
+        },
+        usage: { llm },
+        timing: {
+            event_time: new Date(now).toISOString(),
+            ...(trace.startedAt !== undefined && now >= trace.startedAt ? { duration_ms: now - trace.startedAt } : {}),
+        },
+    };
+    return record;
+}
+/**
+ * The four counters, already in AUDR's terms: `TokenUsage` is disjoint, so `input` excludes cache
+ * reads and writes as AUDR's `input_tokens` does. Reasoning stays inside `output` - AUDR subtracts
+ * it only when it is reported apart, and this SDK does not report it apart.
+ */
+function llmUsage(usage) {
+    if (!usage)
+        return undefined;
+    const counters = {
+        input_tokens: count(usage.input),
+        output_tokens: count(usage.output),
+        cache_read_tokens: count(usage.cacheRead),
+        cache_write_tokens: count(usage.cacheCreate),
+    };
+    const stated = Object.fromEntries(Object.entries(counters).filter(([, value]) => value !== undefined));
+    return { ...stated, requests: 1 };
+}
+/** A counter AUDR can carry: a whole, non-negative number. Anything else is left unstated. */
+function count(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+/** AUDR's provider slug: lowercase, each run of other characters a `-`. */
+function providerSlug(name) {
+    const slug = (name ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || 'unknown';
+}
+/** AUDR bounds a run id to 8-64 characters; one outside that is padded or cut rather than lost. */
+function runIdOf(id) {
+    if (id.length > 64)
+        return id.slice(0, 64);
+    return id.length < 8 ? id.padEnd(8, '_') : id;
+}
+/**
+ * The call's dimensions, as labels: AUDR's metadata that is not usage, which is what they are to
+ * anyone but Stigg. Keys and values AUDR would reject are dropped, not the record.
+ */
+function labelsOf(dimensions) {
+    const labels = Object.entries(dimensions).filter(([key, value]) => /^[a-zA-Z0-9_.-]{1,64}$/.test(key) && typeof value === 'string' && value.length <= 256);
+    return labels.length ? Object.fromEntries(labels) : undefined;
+}
+/** A UUIDv7 (RFC 9562): 48 bits of Unix milliseconds, then random bits. AUDR's `record_id`. */
+function uuidv7(now = Date.now()) {
+    // The global Web Crypto, not `node:crypto`: that import belongs to one file (see
+    // test/module-boundaries.test.ts), and Node 22 has this one built in.
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    for (let i = 0; i < 6; i++)
+        bytes[i] = Math.floor(now / 2 ** (8 * (5 - i))) & 0xff;
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/core/context.d.ts

@@ -1,5 +1,6 @@
 import type { CheckErrorAction, Entitlement, IngestMode, Metrics, MetricsMapper } from '../types';
 import type { EventIngest } from '../engine/engine';
+import type { AudrTrace } from './audr';
 /**
  * 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
@@ -111,6 +112,12 @@ export type ResolvedContext = {
     usageMapper: MetricsMapper;
     idempotencyKey?: string;
     correlationId: string;
+    /**
+     * Whether a context stated `correlationId`, rather than taking the one its wrap generated. Only
+     * a stated id says which calls belong to one run; a generated one spans every call - and every
+     * customer - through the client.
+     */
+    correlationStated?: true;
     /** The entitlement's own id, resolved once - undefined when this context gates on nothing. */
     checkedId?: string;
     /**
@@ -130,6 +137,11 @@ export type ResolvedContext = {
     agent?: string;
     /** The paid tool this step ran, when a middleware checked one - a label, like `agent`. */
     tool?: string;
+    /**
+     * What the binding knows about the call for its AUDR record - provider, model, span. Set per
+     * call, read only when AUDR emission is on, and never sent to Stigg.
+     */
+    audr?: AudrTrace;
 };
 /**
  * What nobody told the SDK, and it will not guess.

package/dist/core/context.js

@@ -128,6 +128,7 @@ function resolveContext(context, correlationId,
         usageMapper: context.usageMapper ?? types_1.vendorMetrics,
         idempotencyKey: context.idempotencyKey,
         correlationId: context.correlationId?.trim() || correlationId,
+        ...(context.correlationId?.trim() ? { correlationStated: true } : {}),
         checkedId: context.entitlement ? (0, types_1.entitlementId)(context.entitlement) : undefined,
         attributionKey: context.attributionKey,
     };
@@ -281,6 +282,7 @@ function overrideContext(base, override) {
         usageMapper: override.usageMapper ?? base.usageMapper,
         idempotencyKey: override.idempotencyKey ?? base.idempotencyKey,
         correlationId: override.correlationId?.trim() || base.correlationId,
+        ...(override.correlationId?.trim() || base.correlationStated ? { correlationStated: true } : {}),
         attributionKey: override.attributionKey ?? base.attributionKey,
     };
 }

package/dist/core/session.d.ts

@@ -1,5 +1,6 @@
 import { EngineError } from '../errors';
 import { type GovernanceHeaders } from '../headers';
+import type { AudrEmitter } from './audr';
 import { type ResolvedContext } from './context';
 import type { GovernanceEngine } from '../engine/engine';
 import type { ErrorContext } from '../config';
@@ -66,6 +67,8 @@ export type SessionDeps = {
      * where an observability tool's trace is already open around the graph; off for `wrap`.
      */
     tracing?: boolean;
+    /** Writes an AUDR record for each measured call. Absent unless `audr` was passed at construction. */
+    audr?: AudrEmitter;
 };
 /** What a client did, for whoever wants to print it. Spans every context it served. */
 export type SessionSummary = {

package/dist/core/session.js

@@ -168,6 +168,13 @@ class GovernanceSession {
         // they both set, because it saw the call.
         const dimensions = measured.dimensions ? { ...context.dimensions, ...measured.dimensions } : context.dimensions;
         const idempotencyKey = measured.idempotencyKey ?? options.idempotencyKey ?? context.idempotencyKey ?? this.nextKey(context);
+        // Before the report, and whatever becomes of it: the call happened either way, and the record
+        // is a separate receipt for someone else. Here because this is the last point that still has
+        // the token counters - the mapper below turns them into Stigg's metrics.
+        const { audr } = this.deps;
+        if (audr) {
+            (0, hooks_1.safely)(() => audr.emit(context, measured), (err) => this.reportError(asEngineError('audr', err), 'audr', context, idempotencyKey));
+        }
         try {
             return this.send(context, context.usageMapper(measured), {
                 dimensions,

package/dist/engine/engine.d.ts

@@ -122,9 +122,14 @@ export type EntityPlacement = {
     /**
      * Set the budget only when the assignment does not exist yet. An existing one keeps its limit
      * and cadence, so a raise made in the dashboard survives the next run. Mutually exclusive with
-     * `usageLimit` - it costs one extra read, which is why it is not the default.
+     * `usageLimit` - it costs one extra read, which is why a number is never seeded unless asked for.
+     *
+     * `null` seeds an unlimited assignment - the metering-only one, which puts the agent in the tree
+     * and tracks its usage without its own assignment refusing it. It is what a budget with no limit
+     * sends, so that case pays the read on every call. Unlike a numeric seed it still applies the
+     * caller's `cadence` to an existing assignment, as a budget with no limit always has.
      */
-    usageLimitOnCreate?: number;
+    usageLimitOnCreate?: number | null;
     cadence?: string;
     /** The entities the budget is scoped to - its own assignment beside the agent's whole one. */
     scopeEntityIds?: string[];

package/dist/engine/rest-governance-engine.js

@@ -16,6 +16,8 @@ const errors_1 = require("../errors");
 const types_1 = require("../types");
 const sdk_identity_1 = require("../sdk-identity");
 const report_1 = require("./report");
+/** The window an unlimited assignment is created with when the caller named none. */
+const TRACKING_CADENCE = 'P1M';
 /** The governance check endpoint is `/api/v1-beta/` and flagged experimental. */
 class RestGovernanceEngine {
     /**
@@ -116,11 +118,16 @@ class RestGovernanceEngine {
         const scope = scopeOf(placement.scopeEntityIds);
         // Every page: the one with this scope can sit past the first, and missing it would overwrite
         // an admin's limit with the seed.
+        const tracking = placement.usageLimitOnCreate === null;
         for await (const row of this.client.v1Beta.customers.assignments.list(customerId, { entityId, ...capability })) {
-            // Already assigned: leave the limit and its window exactly as they are.
+            // Already assigned: leave the limit and its window exactly as they are - except that a
+            // metering-only call still moves the window it named, as a budget with no limit always did.
             if (scopeOf(row.scopeEntityIds) === scope)
-                return {};
+                return tracking ? cadence : {};
         }
+        // Governance requires a window on create, and a metering-only caller has no reason to pick one.
+        if (tracking)
+            return { usageLimit: null, cadence: placement.cadence ?? TRACKING_CADENCE };
         return { usageLimit: placement.usageLimitOnCreate, ...cadence };
     }
     async check(customerId, { entitlement, requestedUsage, dimensions }) {

package/dist/index.d.ts

@@ -15,6 +15,7 @@ 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 } from './config';
+export type { AudrClientLike, AudrEnvironment, AudrOptions, AudrRecord, AudrTrace } from './core/audr';
 export { describeDecision, remedyMessage } from './decision-text';
 export { GOVERNANCE_HEADERS, parseGovernanceHeaders } from './headers';
 export type { GovernanceHeaders, ParsedGovernanceHeaders } from './headers';

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

@@ -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<"prompt_tokens" | "completion_tokens" | "input_tokens" | "output_tokens" | "cache_read_input_tokens" | "cache_creation_input_tokens" | "total_tokens" | "reasoning_tokens"> | import("./bindings/client/core/types").ClientRecipe<"cached_tokens" | "prompt_tokens" | "completion_tokens" | "input_tokens" | "output_tokens" | "cache_read_input_tokens" | "cache_creation_input_tokens" | "total_tokens"> | {
+} | import("./bindings/client/core/types").ClientRecipe<"cost" | "input_tokens" | "output_tokens" | "cached_tokens" | "prompt_tokens" | "completion_tokens" | "total_tokens"> | import("./bindings/client/core/types").ClientRecipe<"input_tokens" | "output_tokens" | "prompt_tokens" | "completion_tokens" | "cache_read_input_tokens" | "cache_creation_input_tokens" | "total_tokens" | "reasoning_tokens"> | import("./bindings/client/core/types").ClientRecipe<"input_tokens" | "output_tokens" | "cached_tokens" | "prompt_tokens" | "completion_tokens" | "cache_read_input_tokens" | "cache_creation_input_tokens" | "total_tokens"> | {
     vendor: string;
     metrics: readonly ["prompt_tokens", "completion_tokens", "cached_tokens", "total_tokens"];
     totalTokensMetric: "total_tokens";
@@ -146,6 +146,8 @@ export declare class StiggAgentSDK {
     private readonly clients;
     /** Every session this SDK handed out, so `flush()` can drain all of them at once. */
     private readonly sessions;
+    /** One for the whole SDK, so every client and middleware writes to the same AUDR client. */
+    private readonly audr?;
     /** The session the no-client paths share. Built on first use. */
     private loose?;
     /**

package/dist/stigg-agent-sdk.js

@@ -41,6 +41,7 @@ const token_usage_1 = require("./bindings/shared/token-usage");
 const context_1 = require("./core/context");
 const session_1 = require("./core/session");
 const hooks_1 = require("./core/hooks");
+const audr_1 = require("./core/audr");
 const types_1 = require("./types");
 /**
  * Recipes are data - method paths and usage extractors - so wiring them here costs nothing at
@@ -151,7 +152,8 @@ function toPlacement(input) {
     if (onCreate && typeof input.budget.limit !== 'number') {
         throw new Error(`Agent ${input.agentId} asked to seed a budget with no limit to seed. ` +
             "`budget.apply: 'on-create'` writes a cap the first time and never again, so there is " +
-            'nothing to write without `budget.limit`.');
+            'nothing to write without `budget.limit`. To seed an unlimited, metering-only budget, ' +
+            'leave out both `limit` and `apply`.');
     }
     // Each entry names an entity, and a blank one names none: the budget would be scoped to an
     // entity no request resolves, and apply to nothing.
@@ -159,12 +161,15 @@ function toPlacement(input) {
         throw new Error(`Agent ${input.agentId} has a budget.scope that is not a list of entity ids: ${JSON.stringify(scope)}. ` +
             'Leave it out, or pass [], for the whole budget.');
     }
+    // No limit at all is metering only: an agent with no assignment is in nobody's tree and its usage
+    // is counted against nothing, so it gets an unlimited one - seeded, so a cap set later survives.
+    const tracking = !onCreate && input.budget.limit === undefined;
     return {
         parentId,
         entitlement,
         cadence,
         usageLimit: onCreate ? undefined : input.budget.limit,
-        usageLimitOnCreate: onCreate ? (input.budget.limit ?? undefined) : undefined,
+        usageLimitOnCreate: tracking ? null : onCreate ? (input.budget.limit ?? undefined) : undefined,
         scopeEntityIds: scope?.length ? scope : undefined,
     };
 }
@@ -186,6 +191,8 @@ class StiggAgentSDK {
     clients;
     /** Every session this SDK handed out, so `flush()` can drain all of them at once. */
     sessions = new Set();
+    /** One for the whole SDK, so every client and middleware writes to the same AUDR client. */
+    audr;
     /** The session the no-client paths share. Built on first use. */
     loose;
     /**
@@ -227,6 +234,8 @@ class StiggAgentSDK {
     constructor(first, second) {
         this.config = (0, config_1.resolveConfig)(toOptions(first, second));
         this.clients = (0, registry_1.createClientRegistry)(exports.DEFAULT_RECIPES);
+        if (this.config.audr)
+            this.audr = (0, audr_1.createAudrEmitter)(this.config.audr, (message) => this.config.logger.warn(message));
     }
     /** Releases what this SDK's engine holds open. */
     async close() {
@@ -529,6 +538,7 @@ class StiggAgentSDK {
             logger: this.config.logger,
             onError: this.config.onError,
             hooks: hooks ?? {},
+            audr: this.audr,
         });
         this.sessions.add(session);
         return session;

package/dist/types.d.ts

@@ -509,10 +509,21 @@ export type AgentBudget = {
      * A scoped budget governs only the requests it names: one naming no model, or a model with no
      * budget, is limited by the agent's whole budget and its ancestors' alone - with neither, by
      * nothing. Register the whole budget too.
+     *
+     * A scope with no `limit` meters that scope only: it is created unlimited, like a whole budget
+     * with no limit, so it shows that scope's usage and refuses nothing.
      */
     scope?: string[];
 } & ({
-    /** The limit, written on every call. `null` clears whatever is assigned. */
+    /**
+     * The limit, written on every call. `null` clears whatever is assigned.
+     *
+     * Omitted, the agent is metering only: the first call creates an unlimited assignment, so its
+     * usage is tracked in the governance tree and its own assignment never refuses it - its
+     * ancestors' budgets and the customer's entitlement still can. Later calls leave the limit
+     * assigned by then - a cap set in the dashboard included - untouched, though a `cadence` they
+     * pass is still applied. `cadence` defaults to `'P1M'` on that create.
+     */
     limit?: number | null;
     /** Writes the limit every time. The default. */
     apply?: 'always';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -86,6 +86,7 @@
   "peerDependencies": {
     "@google/adk": ">=2.3.0 <3",
     "@langchain/core": ">=1.0.0 <2",
+    "@openaudr/audr": ">=0.2.0 <0.3",
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependenciesMeta": {
@@ -95,6 +96,9 @@
     "@langchain/core": {
       "optional": true
     },
+    "@openaudr/audr": {
+      "optional": true
+    },
     "@opentelemetry/api": {
       "optional": true
     }
@@ -114,6 +118,7 @@
     "@langfuse/otel": "^6.0.0",
     "@langfuse/tracing": "^6.0.0",
     "@mistralai/mistralai": "^2.7.0",
+    "@openaudr/audr": "0.2.0",
     "@openrouter/sdk": "^1.4.25",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^2.12.0",