@stigg/agent-sdk-js 0.4.0 → 0.5.0

package/README.md

@@ -121,6 +121,8 @@ rather than handing back a client that quietly meters nothing.
 | Give an agent its own budget | `stigg.register({ customerId, agentId, budget })` |
 | Start new customers on a plan | `stiggContext: { defaultPlanId }`, beside `customerId` |
 | Meter a gateway you operate | `client.stigg.headers()` out, `stigg.ingestFromHeaders(...)` back |
+| Govern a LangChain / LangGraph agent graph ([guide](docs/langchain.md)) | `new StiggLangChainCallbackHandler({ stigg, agents, tools })` from `@stigg/agent-sdk-js/langchain` |
+| Govern a graph from your own harness | `stigg.middleware({ stiggContext, agents })` |
 
 One wrapped client serves every customer and every agent: the context is an argument, given once at
 `wrap` as a default and overridable inside any single call.

package/dist/bindings/client/providers/mistral/mistral-recipe.d.ts

@@ -7,11 +7,11 @@ export declare const mistralRecipe: {
     totalTokensMetric: "total_tokens";
     matches: (client: unknown) => boolean;
     methods: ({
-        path: ("stream" | "chat" | "complete" | "parse" | "parseStream" | "fim" | "agents")[];
+        path: ("agents" | "stream" | "chat" | "complete" | "parse" | "parseStream" | "fim")[];
         attachStream: (stream: unknown, ingest: (measurement: Measurement) => void) => void;
         extractUsage?: undefined;
     } | {
-        path: ("stream" | "chat" | "complete" | "parse" | "parseStream" | "fim" | "agents")[];
+        path: ("agents" | "stream" | "chat" | "complete" | "parse" | "parseStream" | "fim")[];
         extractUsage: (result: MistralCompletionResponse | undefined) => Measurement | undefined;
         attachStream?: undefined;
     })[];

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

@@ -0,0 +1,81 @@
+import { type ResolvedContext } 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;
+};
+/** 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 = {
+    id: string;
+    name: string;
+};
+/** A tool about to run, as the framework announced it. */
+export type ToolStep = {
+    /** The tool's name, when the framework passes one - some do not, for some tools. */
+    name?: string;
+    /** The id of the model's tool call this step runs, when the framework passes it. */
+    callId?: string;
+    /**
+     * What the tool is when it has no name and no model called it - its class, for a packaged tool
+     * a node invokes directly. Only `'*'` can match it, so the catch-all still covers the call.
+     */
+    kind?: string;
+    /** What the tool was called with, for a `usage` mapper. */
+    input?: unknown;
+};
+/** What a framework binding drives: the start and end of every step a graph takes. */
+export type AgentMiddleware = {
+    /** Before a model call: checked, and raises `AccessDeniedError` when refused. */
+    startModel(runId: string, attribution: StepAttribution, eventName: string): Promise<void>;
+    /**
+     * 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.
+     */
+    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. */
+    abandon(runId: string): void;
+};
+/** How one tool is governed, its shorthand expanded. */
+export type ResolvedTool = {
+    entitlement?: Entitlement;
+    usage?: ToolUsageMapper;
+};
+/** A graph's tools by name, `'*'` for the rest - `false` for one left ungoverned. */
+export type ResolvedTools = Readonly<Record<string, ResolvedTool | false>>;
+/** One agent's part of the graph, already resolved over the shared context. */
+export type ResolvedAgent = {
+    context: ResolvedContext;
+    tools: ResolvedTools;
+};
+/** The key that stands for every tool a configuration does not name. */
+export declare const ALL_TOOLS = "*";
+/** A configuration's tools, each validated and expanded once, when the graph is configured. */
+export declare function resolveTools(tools: MiddlewareTools | undefined, where: string): ResolvedTools;
+/**
+ * The graph's agents, each resolved once over the shared context and tools, so a step does no
+ * more than look its agent up. An agent's tools are laid over the shared ones, name by name.
+ */
+export declare function resolveAgents(shared: ResolvedContext, { tools, agents }: Pick<MiddlewareOptions, 'tools' | 'agents'>): {
+    shared: ResolvedAgent;
+    agents: Map<string, ResolvedAgent>;
+};
+export type AgentMiddlewareConfig = {
+    /** The shared context and tools - what a step from an agent not listed resolves to. */
+    shared: ResolvedAgent;
+    /** Each listed agent's own, by name. */
+    agents: ReadonlyMap<string, ResolvedAgent>;
+    /** Told once per agent that was not listed, so the caller can say so. */
+    onUnlisted(agent: string): void;
+    /** Where the caller puts the customer - quoted when a step has none. */
+    missingCustomer: string;
+};
+export declare function createAgentMiddleware(session: GovernanceSession, config: AgentMiddlewareConfig): AgentMiddleware;

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

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_TOOLS = void 0;
+exports.resolveTools = resolveTools;
+exports.resolveAgents = resolveAgents;
+exports.createAgentMiddleware = createAgentMiddleware;
+/**
+ * The orchestration binding's core: an agent graph's middleware, with no framework in it.
+ *
+ * It splits the way the client binding does: `wrapClient` gates and meters a call and a recipe
+ * 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
+ * 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
+ * into the run: ingest never does, and a check that could not be made resolves through
+ * `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.
+ */
+const errors_1 = require("../../../errors");
+const context_1 = require("../../../core/context");
+const types_1 = require("../../../types");
+/** The key that stands for every tool a configuration does not name. */
+exports.ALL_TOOLS = '*';
+/** One tool's entry, validated and expanded. A mistake here is said at startup, not on the first call. */
+function resolveTool(name, tool, where) {
+    if (tool === false)
+        return false;
+    const at = `${where}.${name === exports.ALL_TOOLS ? `'${exports.ALL_TOOLS}'` : name}`;
+    if (!tool || typeof tool !== 'object') {
+        throw new Error(`${at} must be an entitlement, { entitlement, usage }, or false.`);
+    }
+    const shorthand = 'currencyId' in tool || 'featureId' in tool;
+    if (shorthand && ('usage' in tool || 'entitlement' in tool)) {
+        throw new Error(`${at} mixes an entitlement's own fields with \`usage\` or \`entitlement\`, so one of them would be ` +
+            'ignored. Write it as { entitlement: { currencyId }, usage }.');
+    }
+    const resolved = (shorthand ? { entitlement: tool } : tool);
+    if (resolved.usage !== undefined && typeof resolved.usage !== 'function') {
+        throw new Error(`${at}.usage must be a function from the tool call to the metrics it reports.`);
+    }
+    if (resolved.entitlement === undefined && !resolved.usage) {
+        throw new Error(`${at} names neither an entitlement to check nor a usage to report, so it would do nothing. ` +
+            'Give it one of them, or false to leave the tool ungoverned.');
+    }
+    const invalid = resolved.entitlement && (0, types_1.entitlementError)(resolved.entitlement);
+    if (invalid)
+        throw invalid;
+    return resolved;
+}
+/** A configuration's tools, each validated and expanded once, when the graph is configured. */
+function resolveTools(tools, where) {
+    return Object.fromEntries(Object.entries(tools ?? {}).map(([name, tool]) => [name, resolveTool(name, tool, where)]));
+}
+/**
+ * The graph's agents, each resolved once over the shared context and tools, so a step does no
+ * more than look its agent up. An agent's tools are laid over the shared ones, name by name.
+ */
+function resolveAgents(shared, { tools, agents }) {
+    const sharedTools = resolveTools(tools, 'stigg.middleware tools');
+    const resolved = new Map();
+    for (const [name, agent] of Object.entries(agents ?? {})) {
+        // An agent's context is a default for every step it takes, so one key would dedupe them all
+        // 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.');
+        }
+        resolved.set(name, {
+            context: agent.stiggContext ? (0, context_1.overrideContext)(shared, agent.stiggContext) : shared,
+            tools: { ...sharedTools, ...resolveTools(agent.tools, `stigg.middleware agents.${name}.tools`) },
+        });
+    }
+    return { shared: { context: shared, tools: sharedTools }, agents: resolved };
+}
+/**
+ * The tool's own entry, else the catch-all - only the catch-all for a tool with no name, so a
+ * class name never matches an entry written for a tool's name. An exempted tool, or one not
+ * covered, is ungoverned. Own keys only: a tool named `toString` must not find `Object.prototype`'s.
+ */
+function toolFor(tools, name) {
+    if (name !== undefined && Object.hasOwn(tools, name))
+        return tools[name] || undefined;
+    if (Object.hasOwn(tools, exports.ALL_TOOLS))
+        return tools[exports.ALL_TOOLS] || undefined;
+    return undefined;
+}
+/**
+ * How many issued calls are remembered, and how many steps can be in flight. An issued call is
+ * kept so a re-run finds its owner, and a step whose end never comes would otherwise stay for the
+ * life of the process, so past these the oldest go first.
+ */
+const ISSUED_CALLS_LIMIT = 1_000;
+const STEPS_LIMIT = 10_000;
+/** 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);
+    if (map.size <= limit)
+        return undefined;
+    const [oldest, dropped] = map.entries().next().value;
+    map.delete(oldest);
+    return dropped;
+}
+function createAgentMiddleware(session, config) {
+    /** Steps that started and have not ended, by run id. */
+    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();
+    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.
+     */
+    const agentFor = (agent) => {
+        const own = agent === undefined ? undefined : config.agents.get(agent);
+        if (!own && agent !== undefined && config.agents.size > 0 && !warnedUnlisted.has(agent)) {
+            warnedUnlisted.add(agent);
+            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;
+        if (!context.customerId)
+            throw (0, context_1.noCustomer)(config.missingCustomer);
+        return agent === undefined ? context : { ...context, agent };
+    };
+    /** The gate, raising rather than returning - the hooks it runs in have no return path. */
+    const check = async (context) => {
+        if (!(0, context_1.isEnforced)(context))
+            return;
+        const decision = await session.check(context);
+        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. */
+    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`));
+        }
+    };
+    /** 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. */
+    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 };
+    };
+    /** 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) => {
+        const options = { idempotencyKey };
+        if (!tool?.usage) {
+            await session.ingest(context, 1, options);
+            return;
+        }
+        try {
+            const metrics = tool.usage({ name: tool.name, input: tool.input, output });
+            if (!metrics || typeof metrics !== 'object' || Array.isArray(metrics)) {
+                throw new Error(`the usage of tool ${tool.name} returned ${String(metrics)}, not metrics by feature id`);
+            }
+            await session.ingestMetrics(context, metrics, options);
+        }
+        catch (err) {
+            session.failedToMeasure(context, err);
+        }
+    };
+    return {
+        async startModel(runId, attribution, eventName) {
+            const resolved = contextFor(agentFor(attribution.agent).context, attribution);
+            const context = resolved.eventName ? resolved : { ...resolved, eventName: { name: eventName } };
+            await check(context);
+            rememberStep(runId, { context });
+        },
+        // Awaited by the binding, so the agent's next check sees this spend. Safe to wait on: ingest
+        // never throws.
+        async endModel(runId, measurement, issued = []) {
+            const step = steps.get(runId);
+            rememberIssuedCalls(issued, step?.context.agent);
+            if (!step)
+                return;
+            steps.delete(runId);
+            if (!measurement) {
+                session.failedToMeasure(step.context, new Error('the model call ended without usage, so nothing was metered'));
+                return;
+            }
+            await session.ingestMeasurement(step.context, measurement);
+        },
+        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.
+            const issued = callId === undefined ? undefined : issuedCalls.get(callId);
+            const named = name ?? issued?.name;
+            const toolName = named ?? kind;
+            // Billed to the agent whose model asked for the call: a tool can run in a node of its own.
+            const owner = { ...attribution, agent: issued?.agent ?? attribution.agent };
+            const agent = agentFor(owner.agent);
+            const tool = toolName ? toolFor(agent.tools, named) : undefined;
+            if (!toolName || !tool)
+                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,
+            });
+        },
+        async endTool(runId, output) {
+            const step = steps.get(runId);
+            if (!step)
+                return;
+            steps.delete(runId);
+            await billTool(step, output);
+        },
+        abandon(runId) {
+            steps.delete(runId);
+        },
+    };
+}

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

@@ -0,0 +1,50 @@
+/**
+ * The LangChain and LangGraph binding: a callback handler over an agent graph's middleware.
+ *
+ *   const stiggHandler = new StiggLangChainCallbackHandler({ stigg, stiggContext, agents });
+ *   await agent.invoke(input, { callbacks: [stiggHandler], metadata: { stiggCustomerId } });
+ *
+ * Everything here is LangChain's protocol - which hook a step starts on, where the 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.
+ *
+ * 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.
+ *
+ * The one file in `src/` that imports LangChain, reached only through the
+ * `@stigg/agent-sdk-js/langchain` entry.
+ */
+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.
+ */
+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;
+};
+export declare class StiggLangChainCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    /**
+     * The graph's middleware, which every hook below drives. Protected, for a subclass that traces:
+     * the handler itself exposes nothing more, because what it did is flushed through the SDK it was
+     * given (`stigg.flush()`), and reported through the `hooks` it was configured with.
+     */
+    protected readonly middleware: GovernedAgentMiddleware;
+    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>;
+    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>;
+    handleToolEnd(output: unknown, runId: string): Promise<void>;
+    handleToolError(_err: unknown, runId: string): void;
+}

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

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StiggLangChainCallbackHandler = exports.CUSTOMER_METADATA_KEY = void 0;
+/**
+ * The LangChain and LangGraph binding: a callback handler over an agent graph's middleware.
+ *
+ *   const stiggHandler = new StiggLangChainCallbackHandler({ stigg, stiggContext, agents });
+ *   await agent.invoke(input, { callbacks: [stiggHandler], metadata: { stiggCustomerId } });
+ *
+ * Everything here is LangChain's protocol - which hook a step starts on, where the 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.
+ *
+ * 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.
+ *
+ * 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 token_usage_1 = require("../../shared/token-usage");
+/**
+ * The metadata key a caller names the customer under, on `invoke(input, { metadata })`. It wins
+ * over the handler's default, so set it server-side - on LangGraph Platform the client sends
+ * `metadata`, so set it in your auth handler, never from the request.
+ */
+exports.CUSTOMER_METADATA_KEY = 'stiggCustomerId';
+/** What `createAgent({ name })` stamps on every run of that agent. */
+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';
+/** The counters LangChain's `usage_metadata` states at the top level, reported under its own names. */
+const LANGCHAIN_METRICS = ['input_tokens', 'output_tokens', 'total_tokens'];
+/** Where a caller puts the customer, for the refusal a step with none raises. */
+const MISSING_CUSTOMER = `Name it on every run as \`invoke(input, { metadata: { ${exports.CUSTOMER_METADATA_KEY}: customerId } })\`, ` +
+    'or give the handler a default in its `stiggContext: { customerId }`.';
+class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
+    name = 'StiggLangChainCallbackHandler';
+    /**
+     * The graph's middleware, which every hook below drives. Protected, for a subclass that traces:
+     * the handler itself exposes nothing more, because what it did is flushed through the SDK it was
+     * given (`stigg.flush()`), and reported through the `hooks` it was configured with.
+     */
+    middleware;
+    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.
+            this.middleware = options.middleware;
+            return;
+        }
+        const { stigg, ...middlewareOptions } = options;
+        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 });
+    }
+    handleChatModelStart(_llm, _messages, runId, _parentRunId, _extraParams, _tags, metadata) {
+        return this.middleware.startModel(runId, attributionOf(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');
+    }
+    handleLLMEnd(output, runId) {
+        const message = output?.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);
+    }
+    handleLLMError(_err, runId) {
+        this.middleware.abandon(runId);
+    }
+    handleToolStart(tool, input, runId, _parentRunId, _tags, metadata, runName, toolCallId) {
+        // `runName` is set only for a tool built with `tool()`; a class-based one - `TavilySearch`,
+        // most packaged integrations - starts with none, and a serialized form that names only its
+        // class. The middleware names it from the model's own tool call, or by that class when no
+        // model called it.
+        const serialized = tool;
+        return this.middleware.startTool(runId, { name: runName ?? serialized?.name, callId: toolCallId, kind: serialized?.id?.at(-1), input: decoded(input) }, attributionOf(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));
+    }
+    handleToolError(_err, runId) {
+        this.middleware.abandon(runId);
+    }
+}
+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' &&
+        value !== null &&
+        value.type === 'tool' &&
+        'tool_call_id' in value &&
+        'content' in value);
+}
+/**
+ * A tool's input or output as its own author wrote it: LangChain hands both on serialized to JSON,
+ * so they are parsed back - and passed as they came when they are not JSON.
+ */
+function decoded(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** One generation's usage as a measurement, in LangChain's own vocabulary and the normalized one. */
+function measurementOf(message) {
+    const usage = message?.usage_metadata;
+    if (!usage)
+        return undefined;
+    return {
+        metrics: pickNumbers(usage, LANGCHAIN_METRICS),
+        usage: (0, token_usage_1.normalizeUsage)(usage),
+        raw: usage,
+        // The provider's own id - `msg_…` for Anthropic - so a retried graph step that replays the same
+        // message is the same report.
+        ...(message.id ? { idempotencyKey: message.id } : {}),
+    };
+}
+/** The named counters that are numbers, as they were stated. */
+function pickNumbers(source, names) {
+    const metrics = {};
+    for (const name of names) {
+        const value = source[name];
+        if (typeof value === 'number' && Number.isFinite(value))
+            metrics[name] = value;
+    }
+    return metrics;
+}

package/dist/core/context.d.ts

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

package/dist/core/context.js

@@ -72,15 +72,17 @@ function planId(value) {
     }
     return named;
 }
+/**
+ * The one field a call cannot proceed without, refused the same way from every binding. Only where
+ * to put the customer differs, so the remedy is the caller's to word.
+ */
+const noCustomer = (remedy = 'Give `wrap(client, { stiggContext: { customerId } })` a default for every call through ' +
+    'this client, or name one per call in `stiggContext`.') => new Error(`No customerId - every governance call is scoped to a tenant. ${remedy}`);
+exports.noCustomer = noCustomer;
 /**
  * Validates and derives, once. Everything expensive about a context happens here rather than on
  * the call path - see the note at the top of this file for why that split exists.
  */
-/** The one field a call cannot proceed without, said the same way wherever it is missing. */
-const noCustomer = () => new Error('No customerId - every governance call is scoped to a tenant. Give `wrap(client, ' +
-    '{ stiggContext: { customerId } })` a default for every call through this client, or name ' +
-    'one per call in `stiggContext`.');
-exports.noCustomer = noCustomer;
 function resolveContext(context, correlationId, 
 // `wrap` passes false: a client whose calls each name their own customer is legal, and its
 // types already say which calls still owe one. Every path that reaches the engine resolves it.

package/dist/core/session.d.ts

@@ -27,6 +27,13 @@ export type HookContext = {
     correlationId: string;
     /** What the call gated on, when it gated on anything. Undefined on a metering-only run. */
     entitlementId?: string;
+    /**
+     * The agent that took the step, by the orchestrator's own name for it, when a middleware
+     * governs the run. Present at the customer level too, where nothing is attributed to an agent.
+     */
+    agent?: string;
+    /** The tool a step ran, when it was a paid tool a middleware checked. */
+    tool?: string;
 };
 export type SessionHooks = {
     /** Every check this client makes. The whole decision, already formatted as `.summary`. */
@@ -54,6 +61,11 @@ export type SessionDeps = {
     logger: Logger;
     onError: (error: EngineError, context: ErrorContext) => void;
     hooks: SessionHooks;
+    /**
+     * Whether each check and report is an OpenTelemetry span. On for an orchestrator's middleware,
+     * where an observability tool's trace is already open around the graph; off for `wrap`.
+     */
+    tracing?: boolean;
 };
 /** What a client did, for whoever wants to print it. Spans every context it served. */
 export type SessionSummary = {
@@ -181,6 +193,8 @@ export declare class GovernanceSession {
     private warnRounded;
     private warnIfNothingDrains;
     private record;
+    /** Every ingest result, however it ended: to its span, then to the application's hook. */
+    private emitIngest;
     /**
      * Hooks are instrumentation, so a throwing one must not reach the caller: it cannot turn an
      * allow into a denial, flip a delivered ingest to `ok: false`, or reject a promise the contract