@stigg/agent-sdk-js 0.4.0 → 0.5.1

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

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StiggLangChainCallbackHandler = exports.CUSTOMER_METADATA_KEY = void 0;
+/**
+ * The LangChain and LangGraph binding: a callback handler over an agent graph's middleware.
+ *
+ *   const stiggHandler = new StiggLangChainCallbackHandler({ stigg, stiggContext, agents });
+ *   await agent.invoke(input, { callbacks: [stiggHandler], metadata: { stiggCustomerId } });
+ *
+ * Everything here is LangChain's protocol - which hook a step starts on, where the customer and
+ * the usage are, which agent a step belongs to. Whether a step may run and what it is worth is the
+ * middleware's. LangChain hands a callback to every run beneath the `invoke`, sub-agents and
+ * LangGraph nodes included, so one handler governs the whole graph.
+ *
+ * A step belongs to the nearest run above it named for a configured agent: a `createAgent` or
+ * `createReactAgent` by its `name`, a hand-built graph's node by its own. That is LangChain's run
+ * tree, not metadata - `lc_agent_name` in metadata is inherited by an unnamed sub-agent, carried
+ * into a sub-agent by a tool that passes its own config, and settable by whoever sends the run's
+ * metadata, so it would bill the wrong agent or let a client pick whose budget pays.
+ *
+ * It blocks by default. LangChain swallows a handler's error unless `raiseError` is set, and runs
+ * an async handler in the background unless `awaitHandlers` is set too, so both are set - through
+ * the constructor, because `awaitHandlers` is derived inside `super()`. And LangChain copies a
+ * handler (`new this.constructor(this)`) on its way into a nested run, so a copy shares the
+ * original's middleware and run tree rather than billing a sub-agent to a fresh session.
+ *
+ * The one file in `src/` that imports LangChain, reached only through the
+ * `@stigg/agent-sdk-js/langchain` entry.
+ */
+const base_1 = require("@langchain/core/callbacks/base");
+const hooks_1 = require("../../../core/hooks");
+const token_usage_1 = require("../../shared/token-usage");
+/**
+ * The metadata key a caller names the customer under, on `invoke(input, { metadata })`. It wins
+ * over the handler's default, so set it server-side - on LangGraph Platform the client sends
+ * `metadata`, so set it in your auth handler, never from the request.
+ */
+exports.CUSTOMER_METADATA_KEY = 'stiggCustomerId';
+/**
+ * What `createAgent({ name })` and LangGraph stamp in metadata. Never what a step is billed as -
+ * see the top of this file - only the label an unlisted agent is reported under.
+ */
+const AGENT_METADATA_KEY = 'lc_agent_name';
+const NODE_METADATA_KEY = 'langgraph_node';
+/** How many runs can be open at once before the oldest is forgotten - a run whose end never came. */
+const OPEN_RUNS_LIMIT = 10_000;
+/** The counters LangChain's `usage_metadata` states at the top level, reported under its own names. */
+const LANGCHAIN_METRICS = ['input_tokens', 'output_tokens', 'total_tokens'];
+/** Where a caller puts the customer, for the refusal a step with none raises. */
+const MISSING_CUSTOMER = `Name it on every run as \`invoke(input, { metadata: { ${exports.CUSTOMER_METADATA_KEY}: customerId } })\`, ` +
+    'or give the handler a default in its `stiggContext: { customerId }`.';
+/**
+ * The runs LangChain has open, each with its name and parent, so a step can be traced up to the
+ * agent it belongs to. Shared by a handler and every copy LangChain makes of it.
+ */
+class RunTree {
+    agents;
+    rootAgent;
+    warn;
+    open = new Map();
+    warnedFull = false;
+    warned = new Set();
+    /**
+     * `rootAgent`, when set, is what a top-level run is, whatever it was named: the caller names that
+     * run (`invoke(input, { runName })`), so its name alone would let them pick whose budget pays.
+     * `warn` is the SDK's logger, for what is said once.
+     */
+    constructor(agents, rootAgent, warn) {
+        this.agents = agents;
+        this.rootAgent = rootAgent;
+        this.warn = warn;
+    }
+    start(runId, parent, name) {
+        this.open.set(runId, { name: parent === undefined && this.rootAgent ? this.rootAgent : name, parent });
+        if (this.open.size <= OPEN_RUNS_LIMIT)
+            return;
+        // A forgotten run breaks the walk for the steps beneath it: they fall back to the shared
+        // context - still checked and reported, but not as their agent - so that is said.
+        this.open.delete(this.open.keys().next().value);
+        if (!this.warnedFull) {
+            this.warnedFull = true;
+            this.warnOnce(`[stigg] more than ${OPEN_RUNS_LIMIT} LangChain runs are open at once, so the oldest are being ` +
+                'forgotten: a step beneath one is governed by the shared context rather than as its agent.');
+        }
+    }
+    /** Says a thing once per process - and never fails a step for the logger's sake. */
+    warnOnce(message) {
+        if (this.warned.has(message) || this.warned.size >= 100)
+            return;
+        this.warned.add(message);
+        (0, hooks_1.safely)(() => this.warn(message), () => undefined);
+    }
+    end(runId) {
+        this.open.delete(runId);
+    }
+    /** The agent a run belongs to: itself when it is one, otherwise whatever its parent belongs to. */
+    agentAt(runId) {
+        const run = runId === undefined ? undefined : this.open.get(runId);
+        if (!run)
+            return undefined; // the top of the tree, or a run this handler never saw start
+        if (run.name !== undefined && this.isAgent(run.name))
+            return run.name;
+        return this.agentAt(run.parent);
+    }
+    isAgent(name) {
+        return this.agents.has(name);
+    }
+}
+class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
+    name = 'StiggLangChainCallbackHandler';
+    /**
+     * The graph's middleware, which every hook below drives. Protected, for a subclass that traces:
+     * the handler itself exposes nothing more, because what it did is flushed through the SDK it was
+     * given (`stigg.flush()`), and reported through the `hooks` it was configured with.
+     */
+    middleware;
+    runs;
+    constructor(options) {
+        super({ raiseError: true, _awaitHandler: true });
+        if (options instanceof StiggLangChainCallbackHandler) {
+            // LangChain's own copy, on its way into a nested run: the same graph, so the same state.
+            this.middleware = options.middleware;
+            this.runs = options.runs;
+            return;
+        }
+        const { stigg, rootAgent, ...middlewareOptions } = options;
+        if (rootAgent !== undefined && !options.agents?.[rootAgent]) {
+            throw new Error(`\`rootAgent\` names "${rootAgent}", which \`agents\` does not list - it must be one of them.`);
+        }
+        if (!stigg || typeof stigg.middleware !== 'function') {
+            throw new Error('`StiggLangChainCallbackHandler` needs `stigg`: the `StiggAgentSDK` it governs through.');
+        }
+        this.middleware = stigg.middleware({ ...middlewareOptions, missingCustomer: MISSING_CUSTOMER });
+        this.runs = new RunTree(new Set(Object.keys(options.agents ?? {})), rootAgent, (message) => stigg.config.logger.warn(message));
+    }
+    // The declared signature puts `runType` fourth and `parentRunId` last, but the callback manager
+    // calls this with `parentRunId` fourth and `runName` eighth - so it is read by what is passed.
+    // True of `@langchain/core` 1.2; the attribution tests run against the real manager, so a release
+    // that changes either side fails them.
+    handleChainStart(...args) {
+        const [, , runId, parentRunId, , , , runName] = args;
+        this.runs.start(runId, parentRunId, runName);
+    }
+    handleChainEnd(_outputs, runId) {
+        this.runs.end(runId);
+    }
+    handleChainError(_err, runId) {
+        this.runs.end(runId);
+    }
+    handleChatModelStart(_llm, _messages, runId, parentRunId, _extraParams, _tags, metadata) {
+        return this.middleware.startModel(runId, this.attributionOf(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');
+    }
+    handleLLMEnd(output, runId) {
+        const result = output;
+        const message = result?.generations?.[0]?.[0]?.message;
+        const issued = (message?.tool_calls ?? []).flatMap((call) => call.id && call.name ? [{ id: call.id, name: call.name }] : []);
+        return this.middleware.endModel(runId, measurementOf(message) ?? completionMeasurement(result, runId), issued);
+    }
+    handleLLMError(_err, runId) {
+        this.middleware.abandon(runId);
+    }
+    handleToolStart(tool, input, runId, parentRunId, _tags, metadata, runName, toolCallId) {
+        // `runName` is set only for a tool built with `tool()`; a class-based one - `TavilySearch`,
+        // most packaged integrations - starts with none, and a serialized form that names only its
+        // class. The middleware names it from the model's own tool call, or by that class when no
+        // model called it.
+        const serialized = tool;
+        const name = runName ?? serialized?.name;
+        // A tool is a run too: a sub-agent it starts belongs below it in the tree.
+        this.runs.start(runId, parentRunId, name);
+        return this.middleware.startTool(runId, { name, callId: toolCallId, kind: serialized?.id?.at(-1), input: decoded(input) }, this.attributionOf(parentRunId, metadata));
+    }
+    handleToolEnd(output, runId) {
+        this.runs.end(runId);
+        // A tool the model called returns a `ToolMessage`, its result serialized into `content` - and
+        // its name, for a tool that started without one.
+        const message = isToolMessage(output) ? output : undefined;
+        return this.middleware.endTool(runId, decoded(message ? message.content : output), message?.name);
+    }
+    handleToolError(_err, runId) {
+        this.runs.end(runId);
+        this.middleware.abandon(runId);
+    }
+    /**
+     * Who a step is for: the configured agent above it in the run tree, and the run's customer. With
+     * none above it, a name from metadata is passed on only as a label for the "not listed" warning -
+     * never a configured agent's name, which the tree alone can confer.
+     */
+    attributionOf(parentRunId, metadata) {
+        const label = metadata?.[AGENT_METADATA_KEY] ?? metadata?.[NODE_METADATA_KEY];
+        const unlisted = typeof label === 'string' && !this.runs.isAgent(label) ? label : undefined;
+        const customerId = metadata?.[exports.CUSTOMER_METADATA_KEY];
+        const agent = this.runs.agentAt(parentRunId);
+        // Metadata naming a configured agent the tree does not find is a misconfiguration - a subgraph
+        // node named apart from its agent, a top-level agent with no `rootAgent` - or a caller's attempt.
+        if (agent === undefined && typeof label === 'string' && this.runs.isAgent(label)) {
+            this.runs.warnOnce(`[stigg] a step's metadata names agent "${label}", but no run above it is named "${label}" - it is ` +
+                'governed by the shared context. Name the node or the agent after it, or set `rootAgent` if it is ' +
+                'the top-level agent.');
+        }
+        return {
+            agent: agent ?? unlisted,
+            customerId: typeof customerId === 'string' && customerId ? customerId : undefined,
+        };
+    }
+}
+exports.StiggLangChainCallbackHandler = StiggLangChainCallbackHandler;
+/** LangChain's `ToolMessage`, told by shape - the class is the application's copy, not ours. */
+function isToolMessage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.type === 'tool' &&
+        'tool_call_id' in value &&
+        'content' in value);
+}
+/**
+ * A tool's input or output as its own author wrote it: LangChain hands both on serialized to JSON,
+ * so they are parsed back - and passed as they came when they are not JSON.
+ */
+function decoded(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** One generation's usage as a measurement, in LangChain's own vocabulary and the normalized one. */
+function measurementOf(message) {
+    const usage = message?.usage_metadata;
+    if (!usage)
+        return undefined;
+    return {
+        metrics: pickNumbers(usage, LANGCHAIN_METRICS),
+        usage: (0, token_usage_1.normalizeUsage)(usage),
+        raw: usage,
+        // The provider's own id - `msg_…` for Anthropic - so a retried graph step that replays the same
+        // message is the same report.
+        ...(message.id ? { idempotencyKey: message.id } : {}),
+    };
+}
+/**
+ * A completion model's usage, which LangChain reports on `llmOutput.tokenUsage` rather than on a
+ * message - in camelCase, so it is mapped onto the same names a chat model reports under.
+ */
+function completionMeasurement(result, runId) {
+    const usage = result?.llmOutput?.tokenUsage;
+    if (!usage)
+        return undefined;
+    const raw = {
+        input_tokens: usage.promptTokens,
+        output_tokens: usage.completionTokens,
+        total_tokens: usage.totalTokens,
+    };
+    // An empty `tokenUsage` - a streamed completion's - says nothing, and is no measurement: reported
+    // as zero it would look like a call that cost nothing, rather than one nobody measured.
+    if (!Object.values(raw).some((value) => typeof value === 'number'))
+        return undefined;
+    // No provider message id to key on, so the run's own: the same run reported twice is one report.
+    return { metrics: pickNumbers(raw, LANGCHAIN_METRICS), usage: (0, token_usage_1.normalizeUsage)(raw), raw, idempotencyKey: runId };
+}
+/** The named counters that are numbers, as they were stated. */
+function pickNumbers(source, names) {
+    const metrics = {};
+    for (const name of names) {
+        const value = source[name];
+        if (typeof value === 'number' && Number.isFinite(value))
+            metrics[name] = value;
+    }
+    return metrics;
+}

package/dist/core/context.d.ts

@@ -122,6 +122,14 @@ export type ResolvedContext = {
      * itself to build its own.
      */
     attributionKey?: string;
+    /**
+     * The orchestrator's own name for the agent that took this step, when a middleware governs it -
+     * `lead`, `researcher`. A label for hooks and logs, never sent: what Stigg attributes by is
+     * `agentId`, which a customer-level run does not have.
+     */
+    agent?: string;
+    /** The paid tool this step ran, when a middleware checked one - a label, like `agent`. */
+    tool?: string;
 };
 /**
  * What nobody told the SDK, and it will not guess.
@@ -137,11 +145,10 @@ export declare const CONTEXT_DEFAULTS: {
     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, refused the same way from every binding. Only where
+ * to put the customer differs, so the remedy is the caller's to word.
  */
-/** The one field a call cannot proceed without, said the same way wherever it is missing. */
-export declare const noCustomer: () => Error;
+export declare const noCustomer: (remedy?: string) => Error;
 /**
  * The client-wide policy a context falls back to before the SDK's own defaults.
  *
@@ -153,6 +160,10 @@ export type ContextDefaults = {
     checkErrorAction?: CheckErrorAction;
     ingestMode?: IngestMode;
 };
+/**
+ * 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.
+ */
 export declare function resolveContext(context: StiggContext, correlationId: string, { requireCustomer, defaults }?: {
     requireCustomer?: boolean;
     defaults?: ContextDefaults;

package/dist/core/context.js

@@ -72,15 +72,17 @@ function planId(value) {
     }
     return named;
 }
+/**
+ * The one field a call cannot proceed without, refused the same way from every binding. Only where
+ * to put the customer differs, so the remedy is the caller's to word.
+ */
+const noCustomer = (remedy = 'Give `wrap(client, { stiggContext: { customerId } })` a default for every call through ' +
+    'this client, or name one per call in `stiggContext`.') => new Error(`No customerId - every governance call is scoped to a tenant. ${remedy}`);
+exports.noCustomer = noCustomer;
 /**
  * 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. */
-const noCustomer = () => new Error('No customerId - every governance call is scoped to a tenant. Give `wrap(client, ' +
-    '{ stiggContext: { customerId } })` a default for every call through this client, or name ' +
-    'one per call in `stiggContext`.');
-exports.noCustomer = noCustomer;
 function resolveContext(context, correlationId, 
 // `wrap` passes false: a client whose calls each name their own customer is legal, and its
 // types already say which calls still owe one. Every path that reaches the engine resolves it.

package/dist/core/session.d.ts

@@ -27,6 +27,13 @@ export type HookContext = {
     correlationId: string;
     /** What the call gated on, when it gated on anything. Undefined on a metering-only run. */
     entitlementId?: string;
+    /**
+     * The agent that took the step, by the orchestrator's own name for it, when a middleware
+     * governs the run. Present at the customer level too, where nothing is attributed to an agent.
+     */
+    agent?: string;
+    /** The tool a step ran, when it was a paid tool a middleware checked. */
+    tool?: string;
 };
 export type SessionHooks = {
     /** Every check this client makes. The whole decision, already formatted as `.summary`. */
@@ -54,6 +61,11 @@ export type SessionDeps = {
     logger: Logger;
     onError: (error: EngineError, context: ErrorContext) => void;
     hooks: SessionHooks;
+    /**
+     * Whether each check and report is an OpenTelemetry span. On for an orchestrator's middleware,
+     * where an observability tool's trace is already open around the graph; off for `wrap`.
+     */
+    tracing?: boolean;
 };
 /** What a client did, for whoever wants to print it. Spans every context it served. */
 export type SessionSummary = {
@@ -181,6 +193,8 @@ export declare class GovernanceSession {
     private warnRounded;
     private warnIfNothingDrains;
     private record;
+    /** Every ingest result, however it ended: to its span, then to the application's hook. */
+    private emitIngest;
     /**
      * Hooks are instrumentation, so a throwing one must not reach the caller: it cannot turn an
      * allow into a denial, flip a delivered ingest to `ok: false`, or reject a promise the contract
@@ -189,9 +203,9 @@ export declare class GovernanceSession {
     private hook;
     /**
      * Makes sure a customer with a default plan exists. Never throws, and answers whether Stigg was
-     * reached - false only for an outage, which is reported here and retried by the next call. A
-     * refusal is an answer: the SDK reports it once, and the call goes on to meet whatever the check
-     * says about a customer that does not exist.
+     * reached - false for a passing failure (unreachable, rate limited, timed out), which is reported
+     * here and retried after a short wait. A refusal is an answer: the SDK reports it once, and the
+     * call goes on to meet whatever the check says about a customer that does not exist.
      */
     private provisionCustomer;
     /**

package/dist/core/session.js

@@ -29,6 +29,7 @@ const errors_1 = require("../errors");
 const headers_1 = require("../headers");
 const dimensions_1 = require("./dimensions");
 const hooks_1 = require("./hooks");
+const telemetry_1 = require("./telemetry");
 const context_1 = require("./context");
 const types_1 = require("../types");
 /** What a context looks like to a hook: the attribution, and nothing a hook could change. */
@@ -37,6 +38,8 @@ const hookContext = (context) => ({
     dimensions: context.dimensions,
     correlationId: context.correlationId,
     entitlementId: context.checkedId,
+    ...(context.agent !== undefined ? { agent: context.agent } : {}),
+    ...(context.tool !== undefined ? { tool: context.tool } : {}),
 });
 /** A metric nobody can bill: refused where the mapper that invented it can still be found. */
 const emptyMetricNameError = () => new errors_1.EngineError('measure', 'a metric needs a name - an empty one reports to no feature at all.');
@@ -111,13 +114,14 @@ class GovernanceSession {
      * application routes on, not an exception it recovers from.
      */
     async check(context, requestedUsage = 1) {
+        const startedAt = Date.now();
         this.checks += 1;
         const { entitlement } = context;
         // Asked and answered, with nobody to ask: this context named no entitlement, so there is no
         // budget to consult and no refusal that could come back. Still counted and recorded, because
         // the caller did ask and `lastDecision` is where they read what they got.
         if (!entitlement)
-            return this.record((0, decision_1.unenforcedDecision)(), context);
+            return this.record((0, decision_1.unenforcedDecision)(), context, startedAt);
         try {
             const engine = await this.deps.engine();
             // Before the check, not after: a customer Stigg has never seen holds no entitlement, so their
@@ -134,16 +138,16 @@ class GovernanceSession {
             // refused - an unknown plan, an archived customer - is refused here too, rather than
             // waved through by an `allow` that exists for outages, not for configuration mistakes.
             if (!reached && result.accessDeniedReason === CUSTOMER_NOT_FOUND) {
-                return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context);
+                return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context, startedAt);
             }
-            return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId, entitlement: context.entitlement }), context);
+            return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId, entitlement: context.entitlement }), context, startedAt);
         }
         catch (err) {
             const error = asEngineError('check', err);
             this.reportError(error, 'check', context);
             // Governance is fail-closed server-side; `'deny'` mirrors that, and `'allow'` - the default -
             // is the soft limit that keeps the application up while Stigg is unreachable.
-            return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context);
+            return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context, startedAt);
         }
     }
     /** Applies the context's mapper to a token measurement. The path every binding uses. */
@@ -216,6 +220,7 @@ class GovernanceSession {
     send(context, metrics, sendOptions) {
         const { dimensions, idempotencyKey, raw, event } = sendOptions;
         const mode = context.ingestMode;
+        const startedAt = Date.now();
         // A broken value is one broken metric, not a broken call: the others measured fine and the
         // spend they describe already happened. Dropping only the bad one reports what is knowable.
         //
@@ -260,10 +265,10 @@ class GovernanceSession {
         // distinguishable from one that never tried, and reported to `onIngest` like every result.
         if (!Object.keys(sendable).length) {
             if (rejected)
-                return Promise.resolve(this.failedIngest(context, idempotencyKey, rejected));
+                return Promise.resolve(this.failedIngest(context, idempotencyKey, rejected, startedAt));
             this.ingested += 1;
             const noop = { ok: true, reported: {}, idempotencyKey, mode, replayed: false };
-            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(noop, hookContext(context)));
+            this.emitIngest(context, noop, startedAt);
             return Promise.resolve(noop);
         }
         const promise = this.deps
@@ -311,10 +316,10 @@ class GovernanceSession {
                 this.ingestFailures += 1;
                 this.reportError(rejected, rejected.operation, context, idempotencyKey);
             }
-            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(landed, hookContext(context)));
+            this.emitIngest(context, landed, startedAt);
             return landed;
         })
-            .catch((err) => this.failedIngest(context, idempotencyKey, asEngineError('ingest', err)))
+            .catch((err) => this.failedIngest(context, idempotencyKey, asEngineError('ingest', err), startedAt))
             .finally(() => {
             this.pending.delete(promise);
         });
@@ -403,11 +408,22 @@ class GovernanceSession {
         this.deps.logger.warn(`[stigg] reported ${names} but the response carried no credit balance - ${names.includes(',') ? 'these features are' : 'this feature is'} not mapped to ${checked}, so the budget this call checks ` +
             'against will never drain. Map it in Stigg, or report to the currency directly.');
     }
-    record(decision, context) {
+    record(decision, context, startedAt) {
         this.decision = decision;
+        // Telemetry is instrumentation exactly as a hook is: it never reaches the caller.
+        if (this.deps.tracing) {
+            (0, hooks_1.safely)(() => (0, telemetry_1.traceCheck)(context, decision, startedAt), (err) => this.deps.logger.debug(`[stigg] check span failed: ${String(err)}`));
+        }
         this.hook('onDecision', context, () => this.deps.hooks.onDecision?.(decision, hookContext(context)));
         return decision;
     }
+    /** Every ingest result, however it ended: to its span, then to the application's hook. */
+    emitIngest(context, result, startedAt) {
+        if (this.deps.tracing) {
+            (0, hooks_1.safely)(() => (0, telemetry_1.traceIngest)(context, result, startedAt), (err) => this.deps.logger.debug(`[stigg] ingest span failed: ${String(err)}`));
+        }
+        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(result, hookContext(context)));
+    }
     /**
      * Hooks are instrumentation, so a throwing one must not reach the caller: it cannot turn an
      * allow into a denial, flip a delivered ingest to `ok: false`, or reject a promise the contract
@@ -418,9 +434,9 @@ class GovernanceSession {
     }
     /**
      * Makes sure a customer with a default plan exists. Never throws, and answers whether Stigg was
-     * reached - false only for an outage, which is reported here and retried by the next call. A
-     * refusal is an answer: the SDK reports it once, and the call goes on to meet whatever the check
-     * says about a customer that does not exist.
+     * reached - false for a passing failure (unreachable, rate limited, timed out), which is reported
+     * here and retried after a short wait. A refusal is an answer: the SDK reports it once, and the
+     * call goes on to meet whatever the check says about a customer that does not exist.
      */
     async provisionCustomer(context) {
         if (!context.defaultPlanId || !context.customerId || !this.deps.provisionCustomer)
@@ -446,7 +462,7 @@ class GovernanceSession {
             customerId: context?.customerId,
         }), (err) => this.deps.logger.warn(`[stigg] onError threw while reporting ${error.message}: ${String(err)}`));
     }
-    failedIngest(context, idempotencyKey, error) {
+    failedIngest(context, idempotencyKey, error, startedAt = Date.now()) {
         this.ingestFailures += 1;
         // The error knows what failed - reading a vendor's usage is not the same event as the report
         // that would have followed it, and a context that says otherwise makes the two
@@ -472,7 +488,7 @@ class GovernanceSession {
             replayed: error.replayed ?? false,
             error,
         };
-        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(failure, hookContext(context)));
+        this.emitIngest(context, failure, startedAt);
         return failure;
     }
 }

package/dist/core/telemetry.d.ts

@@ -0,0 +1,8 @@
+import type { AccessDecision, IngestResult } from '../types';
+import type { ResolvedContext } from './context';
+/** The instrumentation scope every Stigg span is reported under - what a span filter matches on. */
+export declare const TRACER_NAME = "@stigg/agent-sdk-js";
+/** One check, from when it was asked to when it was answered. */
+export declare function traceCheck(context: ResolvedContext, decision: AccessDecision, startedAt: number): void;
+/** One report, whether it landed, failed, or had nothing to send. */
+export declare function traceIngest(context: ResolvedContext, result: IngestResult, startedAt: number): void;

package/dist/core/telemetry.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACER_NAME = void 0;
+exports.traceCheck = traceCheck;
+exports.traceIngest = traceIngest;
+const sdk_identity_1 = require("../sdk-identity");
+/** The instrumentation scope every Stigg span is reported under - what a span filter matches on. */
+exports.TRACER_NAME = '@stigg/agent-sdk-js';
+let api;
+/** The application's copy of the API, loaded once - or `null` when it has none installed. */
+function openTelemetry() {
+    if (api === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            api = require('@opentelemetry/api');
+        }
+        catch {
+            api = null;
+        }
+    }
+    return api;
+}
+/** Asked for per span, so a provider registered after this package was loaded is still found. */
+const tracer = (otel) => otel.trace.getTracer(exports.TRACER_NAME, sdk_identity_1.AGENT_SDK_VERSION);
+/** Who the call was for: the attribution, as the check and the report both carry it. */
+function attribution(context) {
+    const attributes = {
+        'stigg.customer.id': context.customerId,
+        'stigg.correlation_id': context.correlationId,
+    };
+    if (context.agent !== undefined)
+        attributes['gen_ai.agent.name'] = context.agent;
+    if (context.tool !== undefined)
+        attributes['gen_ai.tool.name'] = context.tool;
+    if (context.attributionKey && context.dimensions[context.attributionKey] !== undefined) {
+        attributes['stigg.agent.id'] = context.dimensions[context.attributionKey];
+    }
+    for (const [key, value] of Object.entries(context.dimensions))
+        attributes[`stigg.dimension.${key}`] = value;
+    if (context.eventName)
+        attributes['stigg.event.name'] = context.eventName.name;
+    return attributes;
+}
+/** One check, from when it was asked to when it was answered. */
+function traceCheck(context, decision, startedAt) {
+    const otel = openTelemetry();
+    if (!otel)
+        return;
+    const attributes = {
+        ...attribution(context),
+        'stigg.decision.has_access': decision.hasAccess,
+        'stigg.decision.source': decision.source,
+    };
+    if (context.checkedId)
+        attributes['stigg.entitlement.id'] = context.checkedId;
+    if (decision.reason)
+        attributes['stigg.decision.reason'] = decision.reason;
+    if (decision.deniedBy)
+        attributes['stigg.decision.denied_by'] = decision.deniedBy;
+    if (decision.remaining !== undefined)
+        attributes['stigg.decision.remaining'] = decision.remaining;
+    if (decision.remedy)
+        attributes['stigg.decision.remedy'] = decision.remedy;
+    if (decision.isFallback)
+        attributes['stigg.decision.is_fallback'] = true;
+    const span = tracer(otel).startSpan('stigg.check', { startTime: startedAt, attributes });
+    if (!decision.hasAccess) {
+        span.recordException({ name: 'AccessDeniedError', message: decision.message });
+        span.setStatus({ code: otel.SpanStatusCode.ERROR, message: decision.summary });
+    }
+    span.end();
+}
+/** One report, whether it landed, failed, or had nothing to send. */
+function traceIngest(context, result, startedAt) {
+    const otel = openTelemetry();
+    if (!otel)
+        return;
+    const attributes = {
+        ...attribution(context),
+        'stigg.ingest.ok': result.ok,
+        'stigg.ingest.mode': result.mode,
+        'stigg.ingest.idempotency_key': result.idempotencyKey,
+    };
+    for (const [metric, value] of Object.entries(result.reported))
+        attributes[`stigg.metric.${metric}`] = value;
+    if (result.creditsConsumed !== undefined)
+        attributes['stigg.ingest.credits_consumed'] = result.creditsConsumed;
+    if (result.replayed !== undefined)
+        attributes['stigg.ingest.replayed'] = result.replayed;
+    const span = tracer(otel).startSpan('stigg.ingest', { startTime: startedAt, attributes });
+    if (!result.ok) {
+        const message = result.error instanceof Error ? result.error.message : String(result.error ?? 'ingest failed');
+        span.recordException({ name: 'EngineError', message });
+        span.setStatus({ code: otel.SpanStatusCode.ERROR, message });
+    }
+    span.end();
+}

package/dist/engine/node-sdk-engine.d.ts

@@ -94,9 +94,10 @@ export declare class NodeSdkEngine implements GovernanceEngine {
      * mutation, and writes the entitlements it answers with straight into the cache - so the check
      * that follows reads the new plan locally instead of fetching it.
      *
-     * Throws only when Stigg did not answer. Any answer - created, duplicate, or refused - resolves,
-     * because the caller treats them differently: a refusal will be the same next time, and an
-     * unreachable server may not.
+     * Resolves with a final answer - created, duplicate, or a refusal that will be the same next
+     * time. Throws for a passing failure - unreachable, rate limited, timed out - so the customer is
+     * asked again later: remembering one as a refusal would deny that customer until the process
+     * restarts.
      */
     provisionCustomer(customerId: string, planId: string): Promise<ProvisionOutcome>;
     upsertEntity(): Promise<void>;