@stigg/agent-sdk-js 0.4.0 → 0.5.1

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,88 @@
+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, name?: string): 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;
+    /** 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;
+};
+export declare function createAgentMiddleware(session: GovernanceSession, config: AgentMiddlewareConfig): AgentMiddleware;

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

@@ -0,0 +1,299 @@
+"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 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 = '*';
+/** 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;
+/**
+ * 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);
+    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();
+    /** Tools that started without a name, by run id - until they end. */
+    const unnamedTools = new Map();
+    const warnedUnchecked = new Set();
+    const warnedUnnamed = new Set();
+    const warnedUnlisted = new Set();
+    /**
+     * The agent a step belongs to. One the configuration does not list - or a step attributed to no
+     * agent - resolves to the shared context, so nothing runs unbilled for having been left out.
+     */
+    const agentFor = (agent) => {
+        const own = agent === undefined ? undefined : config.agents.get(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);
+            warn(() => config.onUnlisted(agent));
+        }
+        return own ?? config.shared;
+    };
+    /** The context for one step. The customer is required: an empty one would be billed to nobody. */
+    const contextFor = (base, { agent, customerId }) => {
+        const context = customerId ? (0, context_1.overrideContext)(base, { customerId }) : base;
+        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)
+            reportDropped(dropped.context, 'a step');
+    };
+    /** An unnamed tool held until its result names it - and said, if it is dropped to make room. */
+    const rememberUnnamed = (runId, tool) => {
+        const dropped = remember(unnamedTools, runId, tool, STEPS_LIMIT);
+        if (dropped)
+            reportDropped(dropped.context, 'a tool with no name');
+    };
+    const reportDropped = (context, what) => session.failedToMeasure(context, new Error(`${what} was still in flight after ${STEPS_LIMIT} newer ones started, so it was dropped unreported`));
+    /** The application's warnings are its own code: one that throws must not fail a step. */
+    const warn = (say) => (0, hooks_1.safely)(say, () => undefined);
+    /** The tool calls a reply asked for, kept until each tool has run. */
+    const rememberIssuedCalls = (issued, agent) => {
+        for (const call of issued)
+            remember(issuedCalls, call.id, { name: call.name, agent }, ISSUED_CALLS_LIMIT);
+    };
+    /** A tool step's context: priced by the tool's own entitlement, when it has one, and labelled with the tool. */
+    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 };
+    };
+    /** 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);
+            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);
+        }
+    };
+    /**
+     * 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);
+            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) {
+                // 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 },
+                idempotencyKey: toolKey(callId, context, toolName),
+            });
+        },
+        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);
+            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

@@ -0,0 +1,72 @@
+/**
+ * The LangChain and LangGraph binding: a callback handler over an agent graph's middleware.
+ *
+ *   const stiggHandler = new StiggLangChainCallbackHandler({ stigg, stiggContext, agents });
+ *   await agent.invoke(input, { callbacks: [stiggHandler], metadata: { stiggCustomerId } });
+ *
+ * Everything here is LangChain's protocol - which hook a step starts on, where the customer and
+ * the usage are, which agent a step belongs to. Whether a step may run and what it is worth is the
+ * middleware's. LangChain hands a callback to every run beneath the `invoke`, sub-agents and
+ * LangGraph nodes included, so one handler governs the whole graph.
+ *
+ * A step belongs to the nearest run above it named for a configured agent: a `createAgent` or
+ * `createReactAgent` by its `name`, a hand-built graph's node by its own. That is LangChain's run
+ * tree, not metadata - `lc_agent_name` in metadata is inherited by an unnamed sub-agent, carried
+ * into a sub-agent by a tool that passes its own config, and settable by whoever sends the run's
+ * metadata, so it would bill the wrong agent or let a client pick whose budget pays.
+ *
+ * It blocks by default. LangChain swallows a handler's error unless `raiseError` is set, and runs
+ * an async handler in the background unless `awaitHandlers` is set too, so both are set - through
+ * the constructor, because `awaitHandlers` is derived inside `super()`. And LangChain copies a
+ * handler (`new this.constructor(this)`) on its way into a nested run, so a copy shares the
+ * original's middleware and run tree rather than billing a sub-agent to a fresh session.
+ *
+ * The one file in `src/` that imports LangChain, reached only through the
+ * `@stigg/agent-sdk-js/langchain` entry.
+ */
+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;
+    /**
+     * 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;
+    /**
+     * 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;
+    private readonly runs;
+    constructor(options: StiggLangChainCallbackOptions | StiggLangChainCallbackHandler);
+    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>;
+    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;
+}