@stigg/agent-sdk-js 0.5.0 → 0.6.0

package/README.md

@@ -73,6 +73,54 @@ try {
 the shortest path from nothing to working metering is a currency and a `customerId` — no catalog
 modelling first.
 
+## 🕸️ Governing an agent graph
+
+A wrapper governs one client. A LangChain or LangGraph graph runs many agents and tools, so it
+gets one handler instead, passed on `invoke` — LangChain hands it to every model and tool call
+beneath, sub-agents included. Each agent is checked and reports its usage as itself. It imports
+`@langchain/core`, an optional peer, so it uses the copy your application already has.
+
+```ts
+import { StiggAgentSDK } from '@stigg/agent-sdk-js';
+import { StiggLangChainCallbackHandler } from '@stigg/agent-sdk-js/langchain';
+
+const stigg = new StiggAgentSDK();
+const credits = { currencyId: 'credits' };
+
+// Once per customer: each agent an entity with its own budget - what `agentId` below names.
+for (const agentId of ['agent-researcher', 'agent-writer']) {
+  await stigg.register({ customerId: 'customer-acme', agentId, entityTypeId: 'agent', budget: { entitlement: credits, limit: 100 } });
+}
+
+const stiggHandler = new StiggLangChainCallbackHandler({
+  stigg,
+  stiggContext: { attributionKey: 'agentId', entitlement: credits }, // the whole graph
+  agents: {
+    // by the name LangChain knows the agent or node by
+    researcher: { stiggContext: { agentId: 'agent-researcher' }, tools: { web_search: credits } },
+    writer: { stiggContext: { agentId: 'agent-writer' } },
+  },
+});
+
+await graph.invoke(input, {
+  callbacks: [stiggHandler],
+  metadata: { stiggContext: { customerId: 'customer-acme' } }, // per run
+});
+```
+
+Both take the same `stiggContext`, merged the same way — only where it attaches differs:
+
+| | Wrapper | Agent graph |
+| --- | --- | --- |
+| Attaches to | one vendor client | the graph's `invoke` |
+| The whole thing | `wrap(client, { stiggContext })` | `new StiggLangChainCallbackHandler({ stiggContext })` |
+| Per agent | a wrapped client per agent | `agents[name].stiggContext` |
+| Per request | `create({ ..., stiggContext })` | `invoke(input, { metadata: { stiggContext } })` |
+| Tools | not seen | `tools`, checked and metered per call |
+| A refusal | the call throws | the step throws, and the graph decides — a refused sub-agent reads to its lead as a failed tool call |
+
+The [LangChain and LangGraph guide](docs/langchain.md) has every configuration.
+
 ## 🧭 How it works
 
 Three things happen around a call you already make:

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

@@ -1,12 +1,16 @@
-import { type ResolvedContext } from '../../../core/context';
+import { type ResolvedContext, type StiggContext } from '../../../core/context';
 import type { GovernanceSession } from '../../../core/session';
 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 = {
     /** The agent that took the step, by the framework's own name for it. */
     agent?: string;
-    /** The customer the run is for, when the run named one. */
-    customerId?: string;
+    /**
+     * The `stiggContext`s the run stated on the way down to this step, outermost first - the run's,
+     * then any a node set for its own calls. Each is applied over the agent's context the way `wrap`
+     * applies a call's: the customer, dimensions, and anything else a call can override.
+     */
+    stiggContexts?: readonly StiggContext[];
 };
 /** 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 = {
@@ -34,14 +38,14 @@ export type AgentMiddleware = {
     /**
      * After a model call: its measurement is ingested, or the missing one reported. Never throws.
      * `issued` is the tool calls the reply asked for, so a tool step that arrives with only its call
-     * id is named, and billed to the agent that called it.
+     * id is named, and reported for the agent that called it.
      */
     endModel(runId: string, measurement: Measurement | undefined, issued?: readonly IssuedToolCall[]): Promise<void>;
     /** Before a tool runs: checked when the tool is a paid one, raising when refused. */
     startTool(runId: string, tool: ToolStep, attribution: StepAttribution): Promise<void>;
     /** After a tool succeeded: what its `usage` makes of the call, or one unit. Never throws. */
-    endTool(runId: string, output?: unknown): Promise<void>;
-    /** A step that failed: forgotten, and billed nothing - it did not deliver what it charges for. */
+    endTool(runId: string, output?: unknown, name?: string): Promise<void>;
+    /** A step that failed: forgotten, and reports nothing - it did not deliver what it charges for. */
     abandon(runId: string): void;
 };
 /** How one tool is governed, its shorthand expanded. */
@@ -75,6 +79,13 @@ export type AgentMiddlewareConfig = {
     agents: ReadonlyMap<string, ResolvedAgent>;
     /** Told once per agent that was not listed, so the caller can say so. */
     onUnlisted(agent: string): void;
+    /** Told once per tool whose usage was reported but not checked, because its name came only with its result. */
+    onUncheckedTool(tool: string): void;
+    /**
+     * Told once per kind of tool that ran with no name at all - called directly, so nothing named it
+     * and it could not be priced. Possibly a free tool, so a warning rather than a metering failure.
+     */
+    onUnnamedTool(kind: string | undefined): void;
     /** Where the caller puts the customer - quoted when a step has none. */
     missingCustomer: string;
 };

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

@@ -11,7 +11,7 @@ exports.createAgentMiddleware = createAgentMiddleware;
  * knows one vendor; here the middleware governs a graph's steps and a framework binding (the
  * LangChain callback handler, or a harness of your own) knows how its framework announces them.
  *
- * Every step is checked and billed as the agent that took it, so one agent running dry refuses
+ * Every step is checked and reported as the agent that took it, so one agent running dry refuses
  * that agent's steps and nothing else. A refusal is the SDK's own `AccessDeniedError`, thrown from
  * inside the step - the frameworks worth binding to offer hooks that observe a step, not ones that
  * replace its result - and what it means for the run is the graph's to decide. Nothing else throws
@@ -19,10 +19,11 @@ exports.createAgentMiddleware = createAgentMiddleware;
  * `checkErrorAction`.
  *
  * Steps are keyed by the run id the framework gives each one, because the end of a step usually
- * carries nothing else: what the start resolved is what the end bills.
+ * carries nothing else: what the start resolved is what the end reports.
  */
 const errors_1 = require("../../../errors");
 const context_1 = require("../../../core/context");
+const hooks_1 = require("../../../core/hooks");
 const types_1 = require("../../../types");
 /** The key that stands for every tool a configuration does not name. */
 exports.ALL_TOOLS = '*';
@@ -68,7 +69,7 @@ function resolveAgents(shared, { tools, agents }) {
         // into the first. The shared context is refused the same way, in `resolveContext`.
         if (agent.stiggContext?.idempotencyKey !== undefined) {
             throw new Error(`stigg.middleware's agents.${name}.stiggContext cannot set \`idempotencyKey\` - one key shared ` +
-                'by every step that agent takes would bill the first and discard the rest. Each step is keyed by its own id.');
+                'by every step that agent takes would report the first and discard the rest. Each step is keyed by its own id.');
         }
         resolved.set(name, {
             context: agent.stiggContext ? (0, context_1.overrideContext)(shared, agent.stiggContext) : shared,
@@ -96,6 +97,13 @@ function toolFor(tools, name) {
  */
 const ISSUED_CALLS_LIMIT = 1_000;
 const STEPS_LIMIT = 10_000;
+/**
+ * What deduplicates a tool step's report: the call id the model issued, plus what it reports
+ * against - one tool call is one report, and two entitlements on one call must not collide.
+ */
+function toolKey(callId, context, name) {
+    return callId ? `${callId}:${context.checkedId ?? name}` : undefined;
+}
 /** Adds to a map that drops its oldest entry past `limit`, and hands back what it dropped. */
 function remember(map, key, value, limit) {
     map.set(key, value);
@@ -110,22 +118,43 @@ function createAgentMiddleware(session, config) {
     const steps = new Map();
     /** The tool calls models issued, by call id - kept for re-runs, until the cap drops them. */
     const issuedCalls = new Map();
+    /** Tools that started without a name, by run id - until they end. */
+    const unnamedTools = new Map();
+    const warnedUnchecked = new Set();
+    const warnedUnnamed = new Set();
     const warnedUnlisted = new Set();
     /**
      * The agent a step belongs to. One the configuration does not list - or a step attributed to no
-     * agent - resolves to the shared context, so nothing runs unbilled for having been left out.
+     * agent - resolves to the shared context, so nothing runs unmetered for having been left out.
      */
     const agentFor = (agent) => {
         const own = agent === undefined ? undefined : config.agents.get(agent);
-        if (!own && agent !== undefined && config.agents.size > 0 && !warnedUnlisted.has(agent)) {
+        // Capped: the names come from the caller's own runs, so an unbounded set is theirs to grow.
+        if (!own &&
+            agent !== undefined &&
+            config.agents.size > 0 &&
+            !warnedUnlisted.has(agent) &&
+            warnedUnlisted.size < 100) {
             warnedUnlisted.add(agent);
-            config.onUnlisted(agent);
+            warn(() => config.onUnlisted(agent));
         }
         return own ?? config.shared;
     };
-    /** The context for one step. The customer is required: an empty one would be billed to nobody. */
-    const contextFor = (base, { agent, customerId }) => {
-        const context = customerId ? (0, context_1.overrideContext)(base, { customerId }) : base;
+    /** The context for one step. The customer is required: an empty one would report usage for nobody. */
+    const contextFor = (base, attribution) => {
+        const { agent, stiggContexts = [] } = attribution;
+        // A harness from 0.5 still naming the customer here would otherwise be told it named none.
+        if ('customerId' in attribution) {
+            throw new Error('A step names its customer in `stiggContexts: [{ customerId }]` - `StepAttribution.customerId` was ' +
+                'removed in 0.6.');
+        }
+        // A run spans many steps, so a key of its own would dedupe them all into the first - refused
+        // as the shared and the agents' contexts refuse it. Each step is keyed by its own id.
+        if (stiggContexts.some((layer) => layer?.idempotencyKey !== undefined)) {
+            throw new Error("A run's stiggContext cannot set `idempotencyKey` - one key shared by every step beneath it would " +
+                'report the first and discard the rest. Each step is keyed by its own id.');
+        }
+        const context = stiggContexts.reduce((resolved, override) => (0, context_1.overrideContext)(resolved, override), base);
         if (!context.customerId)
             throw (0, context_1.noCustomer)(config.missingCustomer);
         return agent === undefined ? context : { ...context, agent };
@@ -138,26 +167,39 @@ function createAgentMiddleware(session, config) {
         if (!decision.hasAccess)
             throw new errors_1.AccessDeniedError(decision);
     };
-    /** A step in flight. One dropped to make room is never billed, so that is said, not silent. */
+    /** A step in flight. One dropped to make room is never reported, so that is said, not silent. */
     const rememberStep = (runId, step) => {
         const dropped = remember(steps, runId, step, STEPS_LIMIT);
-        if (dropped) {
-            session.failedToMeasure(dropped.context, new Error(`a step was still in flight after ${STEPS_LIMIT} newer ones started, so it was dropped unbilled`));
-        }
+        if (dropped)
+            reportDropped(dropped.context, 'a step');
+    };
+    /** An unnamed tool held until its result names it - and said, if it is dropped to make room. */
+    const rememberUnnamed = (runId, tool) => {
+        const dropped = remember(unnamedTools, runId, tool, STEPS_LIMIT);
+        if (dropped)
+            reportDropped(dropped.context, 'a tool with no name');
     };
+    const reportDropped = (context, what) => session.failedToMeasure(context, new Error(`${what} was still in flight after ${STEPS_LIMIT} newer ones started, so it was dropped unreported`));
+    /** The application's warnings are its own code: one that throws must not fail a step. */
+    const warn = (say) => (0, hooks_1.safely)(say, () => undefined);
     /** The tool calls a reply asked for, kept until each tool has run. */
     const rememberIssuedCalls = (issued, agent) => {
         for (const call of issued)
             remember(issuedCalls, call.id, { name: call.name, agent }, ISSUED_CALLS_LIMIT);
     };
-    /** A tool step's context: priced by the tool's own entitlement, when it has one, and labelled with the tool. */
+    /**
+     * A tool step's context: priced by the tool's own entitlement, when it has one, and labelled with
+     * the tool. The tool goes last - a run's `stiggContext` naming another entitlement re-prices its
+     * model calls, not the tools it set a price on.
+     */
     const toolContext = (agent, tool, name, attribution) => {
         const eventName = { name: `tool.${name}` };
-        const priced = (0, context_1.overrideContext)(agent.context, tool.entitlement ? { entitlement: tool.entitlement, eventName } : { eventName });
-        return { ...contextFor(priced, attribution), tool: name };
+        const step = contextFor(agent.context, attribution);
+        const priced = (0, context_1.overrideContext)(step, tool.entitlement ? { entitlement: tool.entitlement, eventName } : { eventName });
+        return { ...priced, agent: step.agent, tool: name };
     };
-    /** Bills a tool step that ended: its `usage`, or one unit. A bad `usage` is a metering failure. */
-    const billTool = async ({ context, idempotencyKey, tool }, output) => {
+    /** Reports what a tool step that ended used: its `usage`, or one unit. A bad `usage` is a metering failure. */
+    const ingestTool = async ({ context, idempotencyKey, tool }, output) => {
         const options = { idempotencyKey };
         if (!tool?.usage) {
             await session.ingest(context, 1, options);
@@ -174,6 +216,40 @@ function createAgentMiddleware(session, config) {
             session.failedToMeasure(context, err);
         }
     };
+    /**
+     * The step an unnamed tool would have started, now that its result names it - or nothing to
+     * report, when it has no name or the name is not governed. It ran unchecked, which is said once
+     * per tool: only `'*'` can gate a tool whose name is not known when it starts.
+     */
+    const stepFromResult = (runId, name) => {
+        const unnamed = unnamedTools.get(runId);
+        if (!unnamed)
+            return undefined;
+        if (name === undefined) {
+            // Called directly - no tool call, no ToolMessage - so nothing ever named it. It may well be a
+            // free tool, so this is said once per kind of tool rather than raised as a metering failure.
+            const kind = unnamed.kind ?? '(unknown)';
+            if (!warnedUnnamed.has(kind) && warnedUnnamed.size < 100) {
+                warnedUnnamed.add(kind);
+                warn(() => config.onUnnamedTool(unnamed.kind));
+            }
+            return undefined;
+        }
+        const agent = agentFor(unnamed.owner.agent);
+        const tool = toolFor(agent.tools, name);
+        if (!tool)
+            return undefined;
+        if (tool.entitlement && !warnedUnchecked.has(name)) {
+            warnedUnchecked.add(name);
+            warn(() => config.onUncheckedTool(name));
+        }
+        const context = toolContext(agent, tool, name, unnamed.owner);
+        return {
+            context,
+            tool: { name, input: unnamed.input, usage: tool.usage, callId: unnamed.callId },
+            idempotencyKey: toolKey(unnamed.callId, context, name),
+        };
+    };
     return {
         async startModel(runId, attribution, eventName) {
             const resolved = contextFor(agentFor(attribution.agent).context, attribution);
@@ -197,7 +273,7 @@ function createAgentMiddleware(session, config) {
         },
         async startTool(runId, { name, callId, kind, input }, attribution) {
             // Never taken, only looked up - the cap drops old ones: a tools node that runs again, before
-            // or after the call succeeded, is the same call, owned by the same agent, billed under one key.
+            // or after the call succeeded, is the same call, owned by the same agent, reported under one key.
             const issued = callId === undefined ? undefined : issuedCalls.get(callId);
             const named = name ?? issued?.name;
             const toolName = named ?? kind;
@@ -205,26 +281,35 @@ function createAgentMiddleware(session, config) {
             const owner = { ...attribution, agent: issued?.agent ?? attribution.agent };
             const agent = agentFor(owner.agent);
             const tool = toolName ? toolFor(agent.tools, named) : undefined;
-            if (!toolName || !tool)
+            if (!toolName || !tool) {
+                // Nothing to check it against yet - but its result will name it, and a priced tool must
+                // not run free because its name was not known when it started.
+                // Only when a name could match - and with its context resolved now, so a run with no
+                // customer is refused before the tool runs, as a named tool is.
+                if (named === undefined && Object.values(agent.tools).some(Boolean)) {
+                    rememberUnnamed(runId, { owner, context: contextFor(agent.context, owner), input, callId, kind });
+                }
                 return;
+            }
             const context = toolContext(agent, tool, toolName, owner);
             if (tool.entitlement)
                 await check(context);
             rememberStep(runId, {
                 context,
                 tool: { name: toolName, input, usage: tool.usage, callId },
-                // One tool call is one report, and two entitlements on one call must not collide.
-                idempotencyKey: callId ? `${callId}:${context.checkedId ?? toolName}` : undefined,
+                idempotencyKey: toolKey(callId, context, toolName),
             });
         },
-        async endTool(runId, output) {
-            const step = steps.get(runId);
-            if (!step)
-                return;
+        async endTool(runId, output, name) {
+            // Started governed, or started unnamed and governed by the name its result carries.
+            const step = steps.get(runId) ?? stepFromResult(runId, name);
             steps.delete(runId);
-            await billTool(step, output);
+            unnamedTools.delete(runId);
+            if (step)
+                await ingestTool(step, output);
         },
         abandon(runId) {
+            unnamedTools.delete(runId);
             steps.delete(runId);
         },
     };

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

@@ -2,18 +2,24 @@
  * 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 } });
+ *   await agent.invoke(input, { callbacks: [stiggHandler], metadata: { stiggContext: { customerId } } });
  *
- * Everything here is LangChain's protocol - which hook a step starts on, where the agent's name,
- * the customer and the usage are. Whether a step may run and what it is worth is the middleware's,
- * and the handler keeps no state of its own. LangChain hands a callback to every run beneath the
- * `invoke`, sub-agents and LangGraph nodes included, so one handler governs the whole graph.
+ * Everything here is LangChain's protocol - which hook a step starts on, where the run's
+ * `stiggContext` 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 charge 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 rather than billing a sub-agent to a fresh session.
+ * 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.
@@ -22,14 +28,24 @@ import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import type { StiggAgentSDK } from '../../../stigg-agent-sdk';
 import type { GovernedAgentMiddleware, MiddlewareOptions } from '../../../types';
 /**
- * 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.
+ * The metadata key a run states its `stiggContext` under, on `invoke(input, { metadata })` - the
+ * same override `wrap` takes per call, applied over the handler's and the agent's. On `invoke` it
+ * names only the customer and `correlationId` (`RUN_FIELDS`); a node's own config may state more.
+ * On LangGraph Platform the client sends `metadata`, so set the customer in your auth handler,
+ * never from the request.
  */
+export declare const CONTEXT_METADATA_KEY = "stiggContext";
+/** @deprecated The customer alone, from before a run took a whole `stiggContext`. Read as `stiggContext.customerId`. */
 export declare const CUSTOMER_METADATA_KEY = "stiggCustomerId";
 export type StiggLangChainCallbackOptions = MiddlewareOptions & {
     /** The SDK this handler governs through - one per environment, shared with everything else. */
     stigg: StiggAgentSDK;
+    /**
+     * The agent the top-level run is - one of `agents`. Set it when the graph's entry point is itself
+     * an agent: the caller names the top-level run (`invoke(input, { runName })`), so without this its
+     * name would let them pick whose budget pays, or step outside any agent's.
+     */
+    rootAgent?: string;
 };
 export declare class StiggLangChainCallbackHandler extends BaseCallbackHandler {
     name: string;
@@ -39,12 +55,30 @@ export declare class StiggLangChainCallbackHandler extends BaseCallbackHandler {
      * given (`stigg.flush()`), and reported through the `hooks` it was configured with.
      */
     protected readonly middleware: GovernedAgentMiddleware;
+    private readonly runs;
     constructor(options: StiggLangChainCallbackOptions | StiggLangChainCallbackHandler);
-    handleChatModelStart(_llm: unknown, _messages: unknown, runId: string, _parentRunId?: string, _extraParams?: unknown, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
-    handleLLMStart(_llm: unknown, _prompts: unknown, runId: string, _parentRunId?: string, _extraParams?: unknown, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleChainStart(...args: Parameters<NonNullable<BaseCallbackHandler['handleChainStart']>>): void;
+    handleChainEnd(_outputs: unknown, runId: string): void;
+    handleChainError(_err: unknown, runId: string): void;
+    handleChatModelStart(_llm: unknown, _messages: unknown, runId: string, parentRunId?: string, _extraParams?: unknown, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleLLMStart(_llm: unknown, _prompts: unknown, runId: string, parentRunId?: string, _extraParams?: unknown, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
     handleLLMEnd(output: unknown, runId: string): Promise<void>;
     handleLLMError(_err: unknown, runId: string): void;
-    handleToolStart(tool: unknown, input: string, runId: string, _parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string, toolCallId?: string): Promise<void>;
+    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;
+    /**
+     * 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
+     * label for the "not listed" warning - never a configured agent's name, which the tree alone can
+     * confer.
+     */
+    private attributionOf;
+    /**
+     * The `stiggContext` a run's metadata states, with the customer the deprecated key names. That key
+     * is what a server's auth handler was told to set, so it is the one trusted: a `stiggContext`
+     * naming another customer beside it is refused rather than charged to someone else. A run with no
+     * parent - `invoke`'s own metadata - states only `RUN_FIELDS`, with the deprecated key or without.
+     */
+    private stiggContextOf;
 }

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

@@ -1,43 +1,142 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StiggLangChainCallbackHandler = exports.CUSTOMER_METADATA_KEY = void 0;
+exports.StiggLangChainCallbackHandler = exports.CUSTOMER_METADATA_KEY = exports.CONTEXT_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 } });
+ *   await agent.invoke(input, { callbacks: [stiggHandler], metadata: { stiggContext: { customerId } } });
  *
- * Everything here is LangChain's protocol - which hook a step starts on, where the agent's name,
- * the customer and the usage are. Whether a step may run and what it is worth is the middleware's,
- * and the handler keeps no state of its own. LangChain hands a callback to every run beneath the
- * `invoke`, sub-agents and LangGraph nodes included, so one handler governs the whole graph.
+ * Everything here is LangChain's protocol - which hook a step starts on, where the run's
+ * `stiggContext` 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 charge 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 rather than billing a sub-agent to a fresh session.
+ * 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.
+ * The metadata key a run states its `stiggContext` under, on `invoke(input, { metadata })` - the
+ * same override `wrap` takes per call, applied over the handler's and the agent's. On `invoke` it
+ * names only the customer and `correlationId` (`RUN_FIELDS`); a node's own config may state more.
+ * On LangGraph Platform the client sends `metadata`, so set the customer in your auth handler,
+ * never from the request.
+ */
+exports.CONTEXT_METADATA_KEY = 'stiggContext';
+/**
+ * What the `stiggContext` of a run with no parent - `invoke`'s own metadata - may state. On LangGraph
+ * Platform the request's client writes that metadata, so it names who the run is for and nothing that
+ * prices it or says which agent it is. The rest belongs on the handler, under `agents`, or in a
+ * node's own config.
  */
+const RUN_FIELDS = new Set(['customerId', 'correlationId']);
+/** @deprecated The customer alone, from before a run took a whole `stiggContext`. Read as `stiggContext.customerId`. */
 exports.CUSTOMER_METADATA_KEY = 'stiggCustomerId';
-/** What `createAgent({ name })` stamps on every run of that agent. */
+/**
+ * What `createAgent({ name })` and LangGraph stamp in metadata. Never what a step is reported as -
+ * see the top of this file - only the label an unlisted agent is reported under.
+ */
 const AGENT_METADATA_KEY = 'lc_agent_name';
-/** What LangGraph stamps on every step: the graph node it runs in - the agent, in a hand-built graph. */
 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 } })\`, ` +
+const MISSING_CUSTOMER = `Name it on every run as \`invoke(input, { metadata: { ${exports.CONTEXT_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, stiggContext) {
+        this.open.set(runId, {
+            name: parent === undefined && this.rootAgent ? this.rootAgent : name,
+            parent,
+            stiggContext,
+        });
+        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);
+    }
+    isOpen(runId) {
+        return this.open.has(runId);
+    }
+    /**
+     * The `stiggContext`s stated from the top of the tree down to a run, outermost first. LangChain
+     * merges `metadata` one key deep, so a node that sets its own `stiggContext` replaces the run's
+     * rather than adding to it - walking the tree puts the run's back underneath. A context a run
+     * merely inherited is the same object as its parent's, and is applied once.
+     */
+    stiggContextsAt(runId) {
+        const run = runId === undefined ? undefined : this.open.get(runId);
+        if (!run)
+            return [];
+        const above = this.stiggContextsAt(run.parent);
+        return run.stiggContext && run.stiggContext !== above.at(-1) ? [...above, run.stiggContext] : above;
+    }
+}
 class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
     name = 'StiggLangChainCallbackHandler';
     /**
@@ -46,63 +145,139 @@ class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
      * 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 middleware.
+            // 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, ...middlewareOptions } = options;
+        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));
     }
-    handleChatModelStart(_llm, _messages, runId, _parentRunId, _extraParams, _tags, metadata) {
-        return this.middleware.startModel(runId, attributionOf(metadata), 'langchain.chat_model');
+    // 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, , metadata, , runName] = args;
+        this.runs.start(runId, parentRunId, runName, this.stiggContextOf(metadata, parentRunId));
+    }
+    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, attributionOf(metadata), 'langchain.llm');
+    handleLLMStart(_llm, _prompts, runId, parentRunId, _extraParams, _tags, metadata) {
+        return this.middleware.startModel(runId, this.attributionOf(parentRunId, metadata), 'langchain.llm');
     }
     handleLLMEnd(output, runId) {
-        const message = output?.generations?.[0]?.[0]?.message;
+        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), issued);
+        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) {
+    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;
-        return this.middleware.startTool(runId, { name: runName ?? serialized?.name, callId: toolCallId, kind: serialized?.id?.at(-1), input: decoded(input) }, attributionOf(metadata));
+        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, this.stiggContextOf(metadata, parentRunId));
+        return this.middleware.startTool(runId, { name, callId: toolCallId, kind: serialized?.id?.at(-1), input: decoded(input) }, this.attributionOf(parentRunId, metadata));
     }
     handleToolEnd(output, runId) {
-        // A tool the model called returns a `ToolMessage`, its result serialized into `content`.
-        const content = isToolMessage(output) ? output.content : output;
-        return this.middleware.endTool(runId, decoded(content));
+        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 `stiggContext`s the
+     * run stated on the way down. With no agent 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 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.');
+        }
+        const above = this.runs.stiggContextsAt(parentRunId);
+        const own = this.stiggContextOf(metadata, parentRunId);
+        // A step's own `stiggContext` replaced the run's in its metadata; only the tree puts the run's
+        // back. A parent this handler never saw start - the handler given to a model rather than to
+        // `invoke` - leaves the step with its own context alone, and the run's customer gone.
+        if (own && own.customerId === undefined && parentRunId !== undefined && !this.runs.isOpen(parentRunId)) {
+            this.runs.warnOnce("[stigg] a step's own stiggContext names no customer, and the run above it was never seen by this " +
+                "handler - so the run's stiggContext is lost. Pass the handler at `invoke` (`callbacks: [handler]`), " +
+                'not to a model or tool.');
+        }
+        return {
+            agent: agent ?? unlisted,
+            stiggContexts: own && own !== above.at(-1) ? [...above, own] : above,
+        };
+    }
+    /**
+     * The `stiggContext` a run's metadata states, with the customer the deprecated key names. That key
+     * is what a server's auth handler was told to set, so it is the one trusted: a `stiggContext`
+     * naming another customer beside it is refused rather than charged to someone else. A run with no
+     * parent - `invoke`'s own metadata - states only `RUN_FIELDS`, with the deprecated key or without.
+     */
+    stiggContextOf(metadata, parentRunId) {
+        const stated = metadata?.[exports.CONTEXT_METADATA_KEY];
+        const customerId = metadata?.[exports.CUSTOMER_METADATA_KEY];
+        if (stated !== undefined && (typeof stated !== 'object' || stated === null || Array.isArray(stated))) {
+            throw new Error(`metadata.${exports.CONTEXT_METADATA_KEY} must be a \`stiggContext\` object, not ${String(stated)}.`);
+        }
+        const unlisted = parentRunId === undefined && stated ? Object.keys(stated).filter((key) => !RUN_FIELDS.has(key)) : [];
+        if (unlisted.length) {
+            throw new Error(`metadata.${exports.CONTEXT_METADATA_KEY} on a run's \`invoke\` names only the customer and \`correlationId\`, not ` +
+                `${unlisted.join(', ')} - a client can write that metadata. Set the rest on the handler, under \`agents\`, ` +
+                "or in a node's own config.");
+        }
+        if (typeof customerId !== 'string' || !customerId)
+            return stated;
+        this.runs.warnOnce(`[stigg] metadata.${exports.CUSTOMER_METADATA_KEY} is deprecated - pass \`metadata: { ${exports.CONTEXT_METADATA_KEY}: { customerId } }\` instead.`);
+        const context = stated;
+        if (context?.customerId !== undefined && context.customerId !== customerId) {
+            throw new Error(`metadata.${exports.CONTEXT_METADATA_KEY}.customerId (${String(context.customerId)}) differs from metadata.${exports.CUSTOMER_METADATA_KEY} ` +
+                `(${customerId}) - name the customer once, in metadata.${exports.CONTEXT_METADATA_KEY}.`);
+        }
+        return { ...context, customerId };
+    }
 }
 exports.StiggLangChainCallbackHandler = StiggLangChainCallbackHandler;
-/** Who a LangChain step is for: the agent (its `createAgent` name, or its graph node), and the customer. */
-function attributionOf(metadata) {
-    // `createAgent`'s name first: inside one, the node is an internal one (`model_request`). In a
-    // hand-built `StateGraph` there is no agent name, and the node is the agent.
-    const agent = metadata?.[AGENT_METADATA_KEY] ?? metadata?.[NODE_METADATA_KEY];
-    const customerId = metadata?.[exports.CUSTOMER_METADATA_KEY];
-    return {
-        agent: typeof agent === 'string' ? agent : undefined,
-        customerId: typeof customerId === 'string' && customerId ? customerId : undefined,
-    };
-}
 /** LangChain's `ToolMessage`, told by shape - the class is the application's copy, not ours. */
 function isToolMessage(value) {
     return (typeof value === 'object' &&
@@ -139,6 +314,26 @@ function measurementOf(message) {
         ...(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 = {};

package/dist/core/context.d.ts

@@ -144,6 +144,11 @@ export declare const CONTEXT_DEFAULTS: {
     readonly checkErrorAction: "allow";
     readonly ingestMode: "async";
 };
+/**
+ * A plan id as given, trimmed - or a refusal when it was given blank. Absent stays absent: no
+ * plan is a legal choice, while an empty one is a typo that would provision nobody onto nothing.
+ */
+export declare function planId(value: unknown, field?: string): string | undefined;
 /**
  * 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.

package/dist/core/context.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addMetrics = exports.isEnforced = exports.noCustomer = exports.CONTEXT_DEFAULTS = void 0;
+exports.planId = planId;
 exports.resolveContext = resolveContext;
 exports.overrideContext = overrideContext;
 /**
@@ -62,12 +63,14 @@ function agentDimension(context) {
  * A plan id as given, trimmed - or a refusal when it was given blank. Absent stays absent: no
  * plan is a legal choice, while an empty one is a typo that would provision nobody onto nothing.
  */
-function planId(value) {
+function planId(value, field = 'stiggContext.defaultPlanId') {
     if (value === undefined)
         return undefined;
-    const named = typeof value === 'string' ? value.trim() : '';
+    if (typeof value !== 'string')
+        throw new Error(`${field} must be a plan id string, not ${typeof value}.`);
+    const named = value.trim();
     if (!named) {
-        throw new Error('stiggContext.defaultPlanId is empty - leave the field out to provision no plan, or name the ' +
+        throw new Error(`${field} is empty - leave the field out to provision no plan, or name the ` +
             'plan new customers should start on.');
     }
     return named;
@@ -178,7 +181,32 @@ function assertKnownContext(context, where) {
         throw new Error(`${where} has no field \`${key}\` - this SDK would ignore it, and the call would be ` +
             `governed by whatever remained instead. Valid fields: ${Object.keys(CONTEXT_KEYS).join(', ')}.`);
     }
+    // The shapes a JavaScript caller - or a run's metadata - can get wrong without a compiler to say
+    // so: each would otherwise surface later as a bare TypeError, or as a call that looks unmetered.
+    for (const key of STRING_FIELDS) {
+        const value = context[key];
+        if (value !== undefined && typeof value !== 'string') {
+            throw new Error(`${where}.${key} must be a string, not ${typeof value}.`);
+        }
+    }
+    if (context.usageMapper !== undefined && typeof context.usageMapper !== 'function') {
+        throw new Error(`${where}.usageMapper must be a function, not ${typeof context.usageMapper}.`);
+    }
+    const { dimensions } = context;
+    if (dimensions !== undefined &&
+        (typeof dimensions !== 'object' || dimensions === null || Array.isArray(dimensions))) {
+        throw new Error(`${where}.dimensions must be an object of dimension values.`);
+    }
+    // Values are matched against entity ids, which are strings: a number would match nothing, and
+    // the call would look attributed while governing nothing. An absent one is left to mean absent.
+    for (const [key, value] of Object.entries(dimensions ?? {})) {
+        if (value !== undefined && typeof value !== 'string') {
+            throw new Error(`${where}.dimensions.${key} must be a string, not ${typeof value}.`);
+        }
+    }
 }
+/** The fields that are strings or absent. The customer and the plan say so in messages of their own. */
+const STRING_FIELDS = ['agentId', 'attributionKey', 'idempotencyKey', 'correlationId'];
 /**
  * One call's override, applied over what `wrap` already resolved.
  *

package/dist/core/session.d.ts

@@ -203,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

@@ -434,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)

package/dist/engine/engine.d.ts

@@ -126,6 +126,8 @@ export type EntityPlacement = {
      */
     usageLimitOnCreate?: number;
     cadence?: string;
+    /** The entities the budget is scoped to - its own assignment beside the agent's whole one. */
+    scopeEntityIds?: string[];
 };
 export type EntityInput = {
     id: string;

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>;

package/dist/engine/node-sdk-engine.js

@@ -57,6 +57,20 @@ const report_1 = require("./report");
  * connection, a dropped socket - which is what tells a refusal apart from an outage.
  */
 const errorCode = (err) => err?.errorCode;
+/**
+ * The failures that say nothing about the customer - a rate limit, a timeout, an unexpected error -
+ * so asking again later may succeed. Every other code Stigg answers with is a final answer about
+ * this customer or this configuration - an unknown plan, a key that cannot write, an invalid id -
+ * and asking again gets the same one.
+ */
+const PASSING_FAILURES = new Set([
+    'RateLimitExceeded',
+    'OperationTimeout',
+    'UnexpectedError',
+    'RequestTimeout',
+    // A lock another request holds on the customer - creating one takes it.
+    'ObjectAlreadyBeingUsedByAnotherRequestError',
+]);
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 /**
  * Drops keys that were never set, so a spread cannot un-set a default.
@@ -148,9 +162,10 @@ class NodeSdkEngine {
      * 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.
      */
     async provisionCustomer(customerId, planId) {
         try {
@@ -165,7 +180,7 @@ class NodeSdkEngine {
             const code = errorCode(err);
             if (code === 'DuplicatedEntityNotAllowed')
                 return { status: 'existing' };
-            if (code && code !== 'RequestTimeout') {
+            if (code && !PASSING_FAILURES.has(code)) {
                 return { status: 'rejected', code, reason: err instanceof Error ? err.message : String(err) };
             }
             throw (0, errors_1.asEngineError)('provisionCustomer', err);

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

@@ -87,6 +87,8 @@ class RestGovernanceEngine {
                         ...capability,
                         // Tri-state: omitted leaves the parent alone, null makes it a root, an id re-homes it.
                         ...(placement.parentId === undefined ? {} : { parentId: placement.parentId }),
+                        // Part of the assignment's identity: a scoped budget is its own row beside the whole one.
+                        ...(placement.scopeEntityIds ? { scopeEntityIds: placement.scopeEntityIds } : {}),
                         ...budget,
                     },
                 ],
@@ -107,14 +109,18 @@ class RestGovernanceEngine {
             return { usageLimit: placement.usageLimit, ...cadence };
         if (placement.usageLimitOnCreate === undefined)
             return cadence;
-        const existing = await this.client.v1Beta.customers.assignments.list(customerId, {
-            entityId,
-            ...capability,
-            limit: 1,
-        });
-        // Already assigned: leave the limit and its window exactly as they are.
-        if (existing.data.length > 0)
-            return {};
+        // An assignment is the `(entity, capability, scope)` triple, so "exists" means one with this
+        // scope - the agent's whole budget existing says nothing about its per-model one.
+        // Encoded whole, not joined: an id may hold a comma, and ['a,b'] is not ['a', 'b'].
+        const scopeOf = (ids) => JSON.stringify([...(ids ?? [])].sort());
+        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.
+        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.
+            if (scopeOf(row.scopeEntityIds) === scope)
+                return {};
+        }
         return { usageLimit: placement.usageLimitOnCreate, ...cadence };
     }
     async check(customerId, { entitlement, requestedUsage, dimensions }) {

package/dist/integrations/langchain.d.ts

@@ -9,6 +9,6 @@
  *   import { StiggAgentSDK } from "@stigg/agent-sdk-js";
  *   import { StiggLangChainCallbackHandler, AccessDeniedError } from "@stigg/agent-sdk-js/langchain";
  */
-export { StiggLangChainCallbackHandler, CUSTOMER_METADATA_KEY, } from '../bindings/orchestrator/langchain/callback-handler';
+export { StiggLangChainCallbackHandler, CONTEXT_METADATA_KEY, CUSTOMER_METADATA_KEY, } from '../bindings/orchestrator/langchain/callback-handler';
 export type { StiggLangChainCallbackOptions } from '../bindings/orchestrator/langchain/callback-handler';
 export { AccessDeniedError, isAccessDenied } from '../errors';

package/dist/integrations/langchain.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isAccessDenied = exports.AccessDeniedError = exports.CUSTOMER_METADATA_KEY = exports.StiggLangChainCallbackHandler = void 0;
+exports.isAccessDenied = exports.AccessDeniedError = exports.CUSTOMER_METADATA_KEY = exports.CONTEXT_METADATA_KEY = exports.StiggLangChainCallbackHandler = void 0;
 /**
  * `@stigg/agent-sdk-js/langchain` - Stigg governance for LangChain and LangGraph.
  *
@@ -14,6 +14,7 @@ exports.isAccessDenied = exports.AccessDeniedError = exports.CUSTOMER_METADATA_K
  */
 var callback_handler_1 = require("../bindings/orchestrator/langchain/callback-handler");
 Object.defineProperty(exports, "StiggLangChainCallbackHandler", { enumerable: true, get: function () { return callback_handler_1.StiggLangChainCallbackHandler; } });
+Object.defineProperty(exports, "CONTEXT_METADATA_KEY", { enumerable: true, get: function () { return callback_handler_1.CONTEXT_METADATA_KEY; } });
 Object.defineProperty(exports, "CUSTOMER_METADATA_KEY", { enumerable: true, get: function () { return callback_handler_1.CUSTOMER_METADATA_KEY; } });
 // What a refusal is, re-exported so a catch block needs one import: `e instanceof AccessDeniedError`.
 var errors_1 = require("../errors");

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

@@ -165,12 +165,18 @@ export declare class StiggAgentSDK {
      *
      * A refusal is remembered like a success: an unknown plan or a key that cannot write will be
      * refused the same way next time, and retrying it would spend a rate-limited call on every call.
-     * Only an unreachable Stigg is forgotten, so the customer's next call tries again.
+     * A passing failure - unreachable, rate limited - is remembered for
+     * {@link PROVISION_RETRY_AFTER_MS}, then forgotten, so the customer is asked again: soon, but not
+     * on every call while Stigg is the one asking for less.
      *
      * Capped at {@link KNOWN_CUSTOMERS_CAP}, oldest first. Forgetting a customer costs one more
      * provisioning call, which Stigg answers as a duplicate - so the cap bounds memory, not safety.
      */
     private readonly customers;
+    /** When a customer whose provisioning failed in passing may be asked again. */
+    private readonly provisionRetryAt;
+    /** Not readonly, so a test can shorten the wait rather than sleep through it. */
+    private provisionRetryAfterMs;
     private started?;
     /**
      * When the attempt currently in `started` rejected, or undefined while it is pending or has

package/dist/stigg-agent-sdk.js

@@ -126,6 +126,8 @@ const RETRY_START_AFTER_MS = 2_000;
  * of tenants would otherwise grow this for as long as it runs.
  */
 const KNOWN_CUSTOMERS_CAP = 10_000;
+/** How long a customer whose provisioning failed in passing waits before it is asked again. */
+const PROVISION_RETRY_AFTER_MS = 30_000;
 /** The key shorthand and the options object, folded into the one object the config takes. */
 function toOptions(first, second) {
     return typeof first === 'string' ? { ...second, apiKey: first } : { ...first, ...second };
@@ -134,7 +136,7 @@ function toOptions(first, second) {
 function toPlacement(input) {
     if (!input.budget)
         return undefined;
-    const { entitlement, cadence, parentId } = input.budget;
+    const { entitlement, cadence, parentId, scope } = input.budget;
     // A placement writes an assignment against the entitlement, so an empty one persists a budget
     // attached to nothing rather than merely routing badly.
     const invalid = (0, types_1.entitlementError)(entitlement);
@@ -151,12 +153,19 @@ function toPlacement(input) {
             "`budget.apply: 'on-create'` writes a cap the first time and never again, so there is " +
             'nothing to write without `budget.limit`.');
     }
+    // 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.
+    if (scope !== undefined && (!Array.isArray(scope) || scope.some((id) => typeof id !== 'string' || !id.trim()))) {
+        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.');
+    }
     return {
         parentId,
         entitlement,
         cadence,
         usageLimit: onCreate ? undefined : input.budget.limit,
         usageLimitOnCreate: onCreate ? (input.budget.limit ?? undefined) : undefined,
+        scopeEntityIds: scope?.length ? scope : undefined,
     };
 }
 class StiggAgentSDK {
@@ -196,12 +205,18 @@ class StiggAgentSDK {
      *
      * A refusal is remembered like a success: an unknown plan or a key that cannot write will be
      * refused the same way next time, and retrying it would spend a rate-limited call on every call.
-     * Only an unreachable Stigg is forgotten, so the customer's next call tries again.
+     * A passing failure - unreachable, rate limited - is remembered for
+     * {@link PROVISION_RETRY_AFTER_MS}, then forgotten, so the customer is asked again: soon, but not
+     * on every call while Stigg is the one asking for less.
      *
      * Capped at {@link KNOWN_CUSTOMERS_CAP}, oldest first. Forgetting a customer costs one more
      * provisioning call, which Stigg answers as a duplicate - so the cap bounds memory, not safety.
      */
     customers = new Map();
+    /** When a customer whose provisioning failed in passing may be asked again. */
+    provisionRetryAt = new Map();
+    /** Not readonly, so a test can shorten the wait rather than sleep through it. */
+    provisionRetryAfterMs = PROVISION_RETRY_AFTER_MS;
     started;
     /**
      * When the attempt currently in `started` rejected, or undefined while it is pending or has
@@ -262,6 +277,8 @@ class StiggAgentSDK {
         if (typeof agentId !== 'string' || !agentId.trim()) {
             throw new Error('register needs an agentId - an empty one provisions an entity nobody can name.');
         }
+        // Validated by presence, not truthiness: a blank plan is a typo, not a request for none.
+        const defaultPlanId = (0, context_1.planId)(input.defaultPlanId, 'register defaultPlanId');
         const placement = toPlacement(input);
         const key = `${customerId}:${agentId}`;
         // Memoized on the description, not just the pair: a second call describing the agent
@@ -284,6 +301,10 @@ class StiggAgentSDK {
         // built: `run()` already validates in this order, and a malformed call that reports itself as
         // a probe timeout sends the reader looking at the network for a typo they can see.
         await this.ensureStarted();
+        // The customer before the agent: an entity is created under a customer, so one Stigg has never
+        // seen would be refused. The same once-per-customer provisioning every check does.
+        if (defaultPlanId)
+            await this.provisionCustomer(customerId, defaultPlanId);
         if (!this.engine.capabilities.provisioning) {
             // Only a call that asked for something governance-only is an error. A budget or a parent
             // cannot be honoured, and carrying on would leave an agent that looks governed with a
@@ -428,6 +449,10 @@ class StiggAgentSDK {
             onUnlisted: (agent) => this.config.logger.warn(`[stigg] agent "${agent}" is not listed in the middleware's \`agents\`, so its calls are ` +
                 'governed by the shared `stiggContext` alone - at the customer level unless that context ' +
                 'names an agent. List it to govern it as itself.'),
+            onUncheckedTool: (tool) => this.config.logger.warn(`[stigg] tool "${tool}" was metered but not checked: it started with no name, so nothing ` +
+                "could match it until its result named it. Add `'*'` to `tools` to check tools like it."),
+            onUnnamedTool: (kind) => this.config.logger.warn(`[stigg] a tool${kind ? ` (${kind})` : ''} ran with no name, outside a model's tool call, so it ` +
+                "could not be checked or priced. If it is a paid tool, add `'*'` to `tools` to govern tools like it."),
             missingCustomer: options.missingCustomer ??
                 'Name one per run, or give the middleware a default in `stiggContext: { customerId }`.',
         });
@@ -514,8 +539,12 @@ class StiggAgentSDK {
      */
     provisionCustomer(customerId, planId) {
         const known = this.customers.get(customerId);
-        if (known)
+        const retryAt = this.provisionRetryAt.get(customerId);
+        // A passing failure answers every call until its wait is over - asked again on each one, a
+        // rate-limited Stigg would only be asked harder.
+        if (known && (retryAt === undefined || Date.now() < retryAt))
             return known;
+        this.provisionRetryAt.delete(customerId);
         const pending = this.ensureStarted().then(async ({ engine }) => {
             const outcome = await engine.provisionCustomer?.(customerId, planId);
             if (outcome?.status === 'created')
@@ -530,13 +559,16 @@ class StiggAgentSDK {
         });
         this.customers.set(customerId, pending);
         if (this.customers.size > KNOWN_CUSTOMERS_CAP) {
-            this.customers.delete(this.customers.keys().next().value);
+            const oldest = this.customers.keys().next().value;
+            this.customers.delete(oldest);
+            this.provisionRetryAt.delete(oldest);
         }
         // Only its own entry: one evicted by the cap may have been replaced by a newer attempt for the
-        // same customer by the time it fails, and deleting that one would re-ask a settled customer.
+        // same customer by the time it fails, and timing that one out would re-ask a settled customer.
         pending.catch(() => {
-            if (this.customers.get(customerId) === pending)
-                this.customers.delete(customerId);
+            if (this.customers.get(customerId) === pending) {
+                this.provisionRetryAt.set(customerId, Date.now() + this.provisionRetryAfterMs);
+            }
         });
         return pending;
     }

package/dist/types.d.ts

@@ -359,8 +359,9 @@ export type ClientContext = Omit<StiggContext, 'idempotencyKey'> & {
  * agent and nothing else.
  *
  * The customer is the one thing usually left out, because that changes per request: it rides each
- * run instead, wherever the binding says (on LangChain, `metadata.stiggCustomerId`), and wins over a
- * default here. Set it server-side, from the authenticated user, never from the request.
+ * run instead, in the run's own `stiggContext` - the per-call override `wrap` takes - wherever the
+ * binding says (on LangChain, `metadata.stiggContext`), and wins over a default here. Set it
+ * server-side, from the authenticated user, never from the request.
  */
 export type MiddlewareOptions = {
     /**
@@ -498,6 +499,18 @@ export type AgentBudget = {
     cadence?: string;
     /** Places the agent under a parent entity. Tri-state: omit to leave it, null to make it a root. */
     parentId?: string | null;
+    /**
+     * Narrows the budget to requests whose resolved entities include every one of these - a budget
+     * per value of a dimension, such as one per model: register each model as an entity of a type
+     * whose attribution key is the dimension, then scope one budget to each. Each scope is its own
+     * budget on the agent, so register once per scope. Omitted or empty, the budget is the agent's
+     * whole one.
+     *
+     * 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.
+     */
+    scope?: string[];
 } & ({
     /** The limit, written on every call. `null` clears whatever is assigned. */
     limit?: number | null;
@@ -519,7 +532,14 @@ export type AgentScope = {
     customerId: string;
 };
 /** `register` - the standalone call, which has no run to take the scope from. */
-export type RegisterInput = AgentOptions & AgentScope;
+export type RegisterInput = AgentOptions & AgentScope & {
+    /**
+     * The plan to provision the customer onto first, when Stigg does not know them yet - the same
+     * provisioning a check with `stiggContext.defaultPlanId` does, once per customer per process.
+     * Without it, registering under a customer Stigg has never seen fails: an entity needs one.
+     */
+    defaultPlanId?: string;
+};
 /** `deregister` - archiving the entity. No entitlement: an entity is not archived per-entitlement. */
 export type DeregisterInput = Pick<AgentScope, 'customerId'> & Pick<AgentOptions, 'agentId'>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -49,7 +49,8 @@
     "example-client-typesafe": "tsx examples/client/typesafe.ts",
     "example-two-agents": "tsx examples/client/two-agents.ts",
     "example-orchestrator-langchain": "tsx examples/orchestrator/langchain.ts",
-    "example-orchestrator-langgraph": "tsx examples/orchestrator/langgraph.ts",
+    "example-orchestrator-langgraph-handoff": "tsx examples/orchestrator/langgraph-handoff.ts",
+    "example-orchestrator-langgraph-model-fallback": "tsx examples/orchestrator/langgraph-model-fallback.ts",
     "example-gateway": "tsx examples/gateway/openrouter.ts",
     "example-gateway-openrouter": "tsx examples/gateway/openrouter.ts",
     "example-gateway-litellm": "tsx examples/gateway/litellm.ts",