@stigg/agent-sdk-js 0.5.0 → 0.5.1

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

@@ -40,7 +40,7 @@ export type AgentMiddleware = {
     /** 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>;
+    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. */
     abandon(runId: string): void;
 };
@@ -75,6 +75,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

@@ -23,6 +23,7 @@ exports.createAgentMiddleware = createAgentMiddleware;
  */
 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 = '*';
@@ -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,6 +118,10 @@ 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
@@ -117,9 +129,14 @@ function createAgentMiddleware(session, config) {
      */
     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;
     };
@@ -141,10 +158,18 @@ function createAgentMiddleware(session, config) {
     /** 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`));
-        }
+        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)
@@ -156,8 +181,8 @@ function createAgentMiddleware(session, config) {
         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) => {
+    /** 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 +199,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);
@@ -205,26 +264,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

@@ -4,16 +4,22 @@
  *   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.
+ * Everything here is LangChain's protocol - which hook a step starts on, where the customer and
+ * the usage are, which agent a step belongs to. Whether a step may run and what it is worth is the
+ * middleware's. LangChain hands a callback to every run beneath the `invoke`, sub-agents and
+ * LangGraph nodes included, so one handler governs the whole graph.
+ *
+ * A step belongs to the nearest run above it named for a configured agent: a `createAgent` or
+ * `createReactAgent` by its `name`, a hand-built graph's node by its own. That is LangChain's run
+ * tree, not metadata - `lc_agent_name` in metadata is inherited by an unnamed sub-agent, carried
+ * into a sub-agent by a tool that passes its own config, and settable by whoever sends the run's
+ * metadata, so it would bill the wrong agent or let a client pick whose budget pays.
  *
  * It blocks by default. LangChain swallows a handler's error unless `raiseError` is set, and runs
  * an async handler in the background unless `awaitHandlers` is set too, so both are set - through
  * the constructor, because `awaitHandlers` is derived inside `super()`. And LangChain copies a
  * handler (`new this.constructor(this)`) on its way into a nested run, so a copy shares the
- * original's middleware 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.
@@ -30,6 +36,12 @@ 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 +51,22 @@ 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 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.
+     */
+    private attributionOf;
 }

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

@@ -7,21 +7,28 @@ exports.StiggLangChainCallbackHandler = exports.CUSTOMER_METADATA_KEY = void 0;
  *   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.
+ * Everything here is LangChain's protocol - which hook a step starts on, where the customer and
+ * the usage are, which agent a step belongs to. Whether a step may run and what it is worth is the
+ * middleware's. LangChain hands a callback to every run beneath the `invoke`, sub-agents and
+ * LangGraph nodes included, so one handler governs the whole graph.
+ *
+ * A step belongs to the nearest run above it named for a configured agent: a `createAgent` or
+ * `createReactAgent` by its `name`, a hand-built graph's node by its own. That is LangChain's run
+ * tree, not metadata - `lc_agent_name` in metadata is inherited by an unnamed sub-agent, carried
+ * into a sub-agent by a tool that passes its own config, and settable by whoever sends the run's
+ * metadata, so it would bill the wrong agent or let a client pick whose budget pays.
  *
  * It blocks by default. LangChain swallows a handler's error unless `raiseError` is set, and runs
  * an async handler in the background unless `awaitHandlers` is set too, so both are set - through
  * the constructor, because `awaitHandlers` is derived inside `super()`. And LangChain copies a
  * handler (`new this.constructor(this)`) on its way into a nested run, so a copy shares the
- * original's middleware 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
@@ -29,15 +36,76 @@ const token_usage_1 = require("../../shared/token-usage");
  * `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. */
+/**
+ * What `createAgent({ name })` and LangGraph stamp in metadata. Never what a step is billed as -
+ * see the top of this file - only the label an unlisted agent is reported under.
+ */
 const AGENT_METADATA_KEY = 'lc_agent_name';
-/** 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 } })\`, ` +
     'or give the handler a default in its `stiggContext: { customerId }`.';
+/**
+ * The runs LangChain has open, each with its name and parent, so a step can be traced up to the
+ * agent it belongs to. Shared by a handler and every copy LangChain makes of it.
+ */
+class RunTree {
+    agents;
+    rootAgent;
+    warn;
+    open = new Map();
+    warnedFull = false;
+    warned = new Set();
+    /**
+     * `rootAgent`, when set, is what a top-level run is, whatever it was named: the caller names that
+     * run (`invoke(input, { runName })`), so its name alone would let them pick whose budget pays.
+     * `warn` is the SDK's logger, for what is said once.
+     */
+    constructor(agents, rootAgent, warn) {
+        this.agents = agents;
+        this.rootAgent = rootAgent;
+        this.warn = warn;
+    }
+    start(runId, parent, name) {
+        this.open.set(runId, { name: parent === undefined && this.rootAgent ? this.rootAgent : name, parent });
+        if (this.open.size <= OPEN_RUNS_LIMIT)
+            return;
+        // A forgotten run breaks the walk for the steps beneath it: they fall back to the shared
+        // context - still checked and reported, but not as their agent - so that is said.
+        this.open.delete(this.open.keys().next().value);
+        if (!this.warnedFull) {
+            this.warnedFull = true;
+            this.warnOnce(`[stigg] more than ${OPEN_RUNS_LIMIT} LangChain runs are open at once, so the oldest are being ` +
+                'forgotten: a step beneath one is governed by the shared context rather than as its agent.');
+        }
+    }
+    /** Says a thing once per process - and never fails a step for the logger's sake. */
+    warnOnce(message) {
+        if (this.warned.has(message) || this.warned.size >= 100)
+            return;
+        this.warned.add(message);
+        (0, hooks_1.safely)(() => this.warn(message), () => undefined);
+    }
+    end(runId) {
+        this.open.delete(runId);
+    }
+    /** The agent a run belongs to: itself when it is one, otherwise whatever its parent belongs to. */
+    agentAt(runId) {
+        const run = runId === undefined ? undefined : this.open.get(runId);
+        if (!run)
+            return undefined; // the top of the tree, or a run this handler never saw start
+        if (run.name !== undefined && this.isAgent(run.name))
+            return run.name;
+        return this.agentAt(run.parent);
+    }
+    isAgent(name) {
+        return this.agents.has(name);
+    }
+}
 class StiggLangChainCallbackHandler extends base_1.BaseCallbackHandler {
     name = 'StiggLangChainCallbackHandler';
     /**
@@ -46,63 +114,101 @@ 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, , , , runName] = args;
+        this.runs.start(runId, parentRunId, runName);
+    }
+    handleChainEnd(_outputs, runId) {
+        this.runs.end(runId);
+    }
+    handleChainError(_err, runId) {
+        this.runs.end(runId);
+    }
+    handleChatModelStart(_llm, _messages, runId, parentRunId, _extraParams, _tags, metadata) {
+        return this.middleware.startModel(runId, this.attributionOf(parentRunId, metadata), 'langchain.chat_model');
     }
     // The completion-model path, for an LLM that is not a chat model. Same gate, same meter.
-    handleLLMStart(_llm, _prompts, runId, _parentRunId, _extraParams, _tags, metadata) {
-        return this.middleware.startModel(runId, 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);
+        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 run's customer. With
+     * none above it, a name from metadata is passed on only as a label for the "not listed" warning -
+     * never a configured agent's name, which the tree alone can confer.
+     */
+    attributionOf(parentRunId, metadata) {
+        const label = metadata?.[AGENT_METADATA_KEY] ?? metadata?.[NODE_METADATA_KEY];
+        const unlisted = typeof label === 'string' && !this.runs.isAgent(label) ? label : undefined;
+        const customerId = metadata?.[exports.CUSTOMER_METADATA_KEY];
+        const agent = this.runs.agentAt(parentRunId);
+        // Metadata naming a configured agent the tree does not find is a misconfiguration - a subgraph
+        // node named apart from its agent, a top-level agent with no `rootAgent` - or a caller's attempt.
+        if (agent === undefined && typeof label === 'string' && this.runs.isAgent(label)) {
+            this.runs.warnOnce(`[stigg] a step's metadata names agent "${label}", but no run above it is named "${label}" - it is ` +
+                'governed by the shared context. Name the node or the agent after it, or set `rootAgent` if it is ' +
+                'the top-level agent.');
+        }
+        return {
+            agent: agent ?? unlisted,
+            customerId: typeof customerId === 'string' && customerId ? customerId : undefined,
+        };
+    }
 }
 exports.StiggLangChainCallbackHandler = StiggLangChainCallbackHandler;
-/** 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 +245,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/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/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/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 };
@@ -196,12 +198,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
@@ -428,6 +436,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 +526,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 +546,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",