@stigg/agent-sdk-js 0.5.1 → 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, name?: string): Promise<void>;
-    /** A step that failed: forgotten, and billed nothing - it did not deliver what it charges for. */
+    /** 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. */

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,7 +19,7 @@ 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");
@@ -69,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,
@@ -125,7 +125,7 @@ function createAgentMiddleware(session, config) {
     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);
@@ -140,9 +140,21 @@ function createAgentMiddleware(session, config) {
         }
         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 };
@@ -155,7 +167,7 @@ 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)
@@ -175,11 +187,16 @@ function createAgentMiddleware(session, config) {
         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 };
     };
     /** 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) => {
@@ -256,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;

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

@@ -2,10 +2,10 @@
  * 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 customer and
- * the usage are, which agent a step belongs to. Whether a step may run and what it is worth is the
+ * 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.
  *
@@ -13,7 +13,7 @@
  * `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.
+ * 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
@@ -28,10 +28,14 @@ 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. */
@@ -64,9 +68,17 @@ export declare class StiggLangChainCallbackHandler extends BaseCallbackHandler {
     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 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.
+     * 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,14 +1,14 @@
 "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 customer and
- * the usage are, which agent a step belongs to. Whether a step may run and what it is worth is the
+ * 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.
  *
@@ -16,7 +16,7 @@ exports.StiggLangChainCallbackHandler = exports.CUSTOMER_METADATA_KEY = void 0;
  * `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.
+ * 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
@@ -31,13 +31,24 @@ 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 })` and LangGraph stamp in metadata. Never what a step is billed as -
+ * 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';
@@ -47,7 +58,7 @@ 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
@@ -70,8 +81,12 @@ class RunTree {
         this.rootAgent = rootAgent;
         this.warn = warn;
     }
-    start(runId, parent, name) {
-        this.open.set(runId, { name: parent === undefined && this.rootAgent ? this.rootAgent : name, parent });
+    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
@@ -105,6 +120,22 @@ class RunTree {
     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';
@@ -138,8 +169,8 @@ class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
     // 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);
+        const [, , runId, parentRunId, , metadata, , runName] = args;
+        this.runs.start(runId, parentRunId, runName, this.stiggContextOf(metadata, parentRunId));
     }
     handleChainEnd(_outputs, runId) {
         this.runs.end(runId);
@@ -171,7 +202,7 @@ class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
         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);
+        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) {
@@ -186,14 +217,14 @@ class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
         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.
+     * 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 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.
@@ -202,11 +233,49 @@ class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
                 '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,
-            customerId: typeof customerId === 'string' && customerId ? customerId : undefined,
+            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;
 /** LangChain's `ToolMessage`, told by shape - the class is the application's copy, not ours. */

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/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/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.js

@@ -136,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);
@@ -153,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 {
@@ -270,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
@@ -292,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

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.1",
+  "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",