@stigg/agent-sdk-js 0.4.0 → 0.5.1

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/errors.d.ts

@@ -50,7 +50,14 @@ export declare class EngineError extends Error {
 export declare class GovernanceNotEnabledError extends Error {
     constructor(detail?: string);
 }
-/** Returns the decision when `err` is a governance denial - the one-liner for a binding catch. */
+/**
+ * Returns the decision when `err` is a governance denial - the one-liner for a binding catch.
+ *
+ * Frameworks rarely let an error through untouched. Vendor SDKs wrap callback errors, LangChain
+ * wraps a model call's error once per middleware, and LangGraph reports two branches that failed
+ * in one step as an `AggregateError` - so the denial is looked for down the whole `cause` chain and
+ * inside every aggregated error, not only at the top.
+ */
 export declare function isAccessDenied(err: unknown): AccessDecision | undefined;
 export declare const isEngineError: (err: unknown) => err is EngineError;
 export declare const isGovernanceNotEnabled: (err: unknown) => err is GovernanceNotEnabledError;

package/dist/errors.js

@@ -78,15 +78,37 @@ class GovernanceNotEnabledError extends Error {
     }
 }
 exports.GovernanceNotEnabledError = GovernanceNotEnabledError;
-/** Returns the decision when `err` is a governance denial - the one-liner for a binding catch. */
+/**
+ * How far down a wrapped error is searched. Each LangChain middleware that wraps a model call adds
+ * one `MiddlewareError` around a denial, and a sub-agent's run nests its own inside its parent's,
+ * so a handful of levels is ordinary. The bound is only there so a cyclic `cause` cannot spin.
+ */
+const MAX_CAUSE_DEPTH = 16;
+/**
+ * Returns the decision when `err` is a governance denial - the one-liner for a binding catch.
+ *
+ * Frameworks rarely let an error through untouched. Vendor SDKs wrap callback errors, LangChain
+ * wraps a model call's error once per middleware, and LangGraph reports two branches that failed
+ * in one step as an `AggregateError` - so the denial is looked for down the whole `cause` chain and
+ * inside every aggregated error, not only at the top.
+ */
 function isAccessDenied(err) {
+    return findDenial(err, 0);
+}
+function findDenial(err, depth) {
     if (isKind(err, 'denied'))
         return err.decision;
-    // Vendor SDKs wrap callback errors, so the denial can arrive one level down.
-    const cause = err?.cause;
-    if (cause && isKind(cause, 'denied'))
-        return cause.decision;
-    return undefined;
+    if (typeof err !== 'object' || err === null || depth >= MAX_CAUSE_DEPTH)
+        return undefined;
+    const { cause, errors } = err;
+    if (Array.isArray(errors)) {
+        for (const inner of errors) {
+            const decision = findDenial(inner, depth + 1);
+            if (decision)
+                return decision;
+        }
+    }
+    return cause === undefined ? undefined : findDenial(cause, depth + 1);
 }
 const isEngineError = (err) => isKind(err, 'engine');
 exports.isEngineError = isEngineError;

package/dist/index.d.ts

@@ -19,11 +19,12 @@ export { describeDecision, remedyMessage } from './decision-text';
 export { GOVERNANCE_HEADERS, parseGovernanceHeaders } from './headers';
 export type { GovernanceHeaders, ParsedGovernanceHeaders } from './headers';
 export { consoleLogger, noopLogger } from './logger';
+export { TRACER_NAME as STIGG_TRACER_NAME } from './core/telemetry';
 export type { Logger } from './logger';
 export { EngineError, AccessDeniedError, GovernanceNotEnabledError, isEngineError, isAccessDenied, isGovernanceNotEnabled, looksLikeGovernanceNotEnabled, } from './errors';
 export type { EngineCapabilities, EngineChainNode, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, EngineResolution, EntityInput, EventIngest, EntityPlacement, GovernanceEngine, } from './engine/engine';
 export { unitsPerTokens, vendorMetrics, emptyTokenUsage, entitlementId, entitlementKind, entitlementRef, toMeasurement, } from './types';
-export type { AgentBudget, AgentOptions, AgentScope, ClientGovernance, CheckErrorAction, ClientOptions, DecisionSource, DeregisterInput, Entitlement, AccessDecision, Remedy, WrappedClient, IngestContext, IngestMode, IngestResult, Measurement, RegisterInput, GatedSurface, ChatOf, CallContext, TokenUsage, Metrics, MetricsMapper, } from './types';
+export type { AgentBudget, MiddlewareOptions, MiddlewareAgentOptions, MiddlewareTools, ToolGovernance, ToolUsageMapper, ToolCallMeasurement, GovernedAgentMiddleware, AgentOptions, AgentScope, ClientGovernance, CheckErrorAction, ClientOptions, DecisionSource, DeregisterInput, Entitlement, AccessDecision, Remedy, WrappedClient, IngestContext, IngestMode, IngestResult, Measurement, RegisterInput, GatedSurface, ChatOf, CallContext, TokenUsage, Metrics, MetricsMapper, } from './types';
 export { wrapClient } from './bindings/client/core/wrap-client';
 export { createClientRegistry, hasMethod } from './bindings/client/core/registry';
 export type { ClientRecipe, ClientRegistry, MethodRecipe, MetricsFor, MetricsOf, MeteredResponse, } from './bindings/client/core/types';
@@ -60,4 +61,5 @@ export type { TypeSafeMetric, TypeSafeMetrics } from './bindings/client/provider
 export { weightedMetrics } from './bindings/shared/weighted-metrics';
 export type { WeightedMetricsOptions } from './bindings/shared/weighted-metrics';
 export type { ProxyIngestInput } from './bindings/proxy';
+export type { AgentMiddleware, IssuedToolCall, StepAttribution, ToolStep, } from './bindings/orchestrator/core/agent-middleware';
 export { normalizedMetrics, normalizeUsage } from './bindings/shared/token-usage';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeUsage = exports.normalizedMetrics = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.cloudflareRecipe = exports.bedrockRecipe = exports.databricksExternalRecipe = exports.databricksRecipe = exports.ollamaRecipe = exports.mistralRecipe = exports.groqRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.unitsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
+exports.normalizeUsage = exports.normalizedMetrics = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.cloudflareRecipe = exports.bedrockRecipe = exports.databricksExternalRecipe = exports.databricksRecipe = exports.ollamaRecipe = exports.mistralRecipe = exports.groqRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.unitsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.STIGG_TRACER_NAME = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
 /**
  * Public surface.
  *
@@ -28,6 +28,10 @@ Object.defineProperty(exports, "parseGovernanceHeaders", { enumerable: true, get
 var logger_1 = require("./logger");
 Object.defineProperty(exports, "consoleLogger", { enumerable: true, get: function () { return logger_1.consoleLogger; } });
 Object.defineProperty(exports, "noopLogger", { enumerable: true, get: function () { return logger_1.noopLogger; } });
+// The OpenTelemetry instrumentation scope of every `stigg.check` / `stigg.ingest` span, for a span
+// filter to match on - Langfuse's `shouldExportSpan`, for one, exports only scopes it knows.
+var telemetry_1 = require("./core/telemetry");
+Object.defineProperty(exports, "STIGG_TRACER_NAME", { enumerable: true, get: function () { return telemetry_1.TRACER_NAME; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "EngineError", { enumerable: true, get: function () { return errors_1.EngineError; } });
 Object.defineProperty(exports, "AccessDeniedError", { enumerable: true, get: function () { return errors_1.AccessDeniedError; } });

package/dist/integrations/langchain.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@stigg/agent-sdk-js/langchain` - Stigg governance for LangChain and LangGraph.
+ *
+ * Its own entry point because it imports `@langchain/core`, which the package's main entry never
+ * does: an application that does not run LangChain never loads it. `@langchain/core` is an optional
+ * peer dependency, so this uses the copy the application already has - the one whose callback
+ * manager will be calling the handler.
+ *
+ *   import { StiggAgentSDK } from "@stigg/agent-sdk-js";
+ *   import { StiggLangChainCallbackHandler, AccessDeniedError } from "@stigg/agent-sdk-js/langchain";
+ */
+export { StiggLangChainCallbackHandler, CUSTOMER_METADATA_KEY, } from '../bindings/orchestrator/langchain/callback-handler';
+export type { StiggLangChainCallbackOptions } from '../bindings/orchestrator/langchain/callback-handler';
+export { AccessDeniedError, isAccessDenied } from '../errors';

package/dist/integrations/langchain.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAccessDenied = exports.AccessDeniedError = exports.CUSTOMER_METADATA_KEY = exports.StiggLangChainCallbackHandler = void 0;
+/**
+ * `@stigg/agent-sdk-js/langchain` - Stigg governance for LangChain and LangGraph.
+ *
+ * Its own entry point because it imports `@langchain/core`, which the package's main entry never
+ * does: an application that does not run LangChain never loads it. `@langchain/core` is an optional
+ * peer dependency, so this uses the copy the application already has - the one whose callback
+ * manager will be calling the handler.
+ *
+ *   import { StiggAgentSDK } from "@stigg/agent-sdk-js";
+ *   import { StiggLangChainCallbackHandler, AccessDeniedError } from "@stigg/agent-sdk-js/langchain";
+ */
+var callback_handler_1 = require("../bindings/orchestrator/langchain/callback-handler");
+Object.defineProperty(exports, "StiggLangChainCallbackHandler", { enumerable: true, get: function () { return callback_handler_1.StiggLangChainCallbackHandler; } });
+Object.defineProperty(exports, "CUSTOMER_METADATA_KEY", { enumerable: true, get: function () { return callback_handler_1.CUSTOMER_METADATA_KEY; } });
+// What a refusal is, re-exported so a catch block needs one import: `e instanceof AccessDeniedError`.
+var errors_1 = require("../errors");
+Object.defineProperty(exports, "AccessDeniedError", { enumerable: true, get: function () { return errors_1.AccessDeniedError; } });
+Object.defineProperty(exports, "isAccessDenied", { enumerable: true, get: function () { return errors_1.isAccessDenied; } });

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

@@ -2,12 +2,12 @@ import { type ResolvedConfig, type StiggAgentSDKOptions } from './config';
 import { type EngineResolution, type GovernanceEngine } from './engine/engine';
 import type { StiggContext } from './core/context';
 import type { SessionSummary } from './core/session';
-import type { Metrics, ClientOptions, DeregisterInput, AccessDecision, WrappedClient, PathsOf, IngestContext, IngestResult, RegisterInput } from './types';
+import type { Metrics, GovernedAgentMiddleware, MiddlewareOptions, ClientOptions, DeregisterInput, AccessDecision, WrappedClient, PathsOf, IngestContext, IngestResult, RegisterInput } from './types';
 import type { GovernanceHeaders } from './headers';
 /**
  * Recipes are data - method paths and usage extractors - so wiring them here costs nothing at
- * runtime and pulls in no vendor package. An orchestration adapter is different: it needs its
- * framework loaded, so it stays an explicit subpath import.
+ * runtime and pulls in no vendor package. The LangChain handler, which does load its framework,
+ * is reached only through the `@stigg/agent-sdk-js/langchain` entry, never from here.
  */
 /**
  * Order matters: the gateways are matched before the plain OpenAI adapter, because every one of
@@ -97,11 +97,11 @@ export declare const DEFAULT_RECIPES: ({
     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: import("./types").Measurement) => void) => void;
         extractUsage?: undefined;
     } | {
-        path: ("stream" | "chat" | "complete" | "parse" | "parseStream" | "fim" | "agents")[];
+        path: ("agents" | "stream" | "chat" | "complete" | "parse" | "parseStream" | "fim")[];
         extractUsage: (result: import("./bindings/client/providers/mistral/types").MistralCompletionResponse | undefined) => import("./types").Measurement | undefined;
         attachStream?: undefined;
     })[];
@@ -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
@@ -242,6 +248,20 @@ export declare class StiggAgentSDK {
      * see {@link GovernanceSession.warmUp} for which cache that is and when there is one at all.
      */
     wrap<T extends object, O extends ClientOptions>(client: T, options?: O): WrappedClient<T, O['stiggContext'], PathsOf<O['recipe'], T>>;
+    /**
+     * An agent graph's governance middleware - the orchestration counterpart to `wrap`.
+     *
+     * There is no single client to gate in a graph: it is several agents, each spending against its
+     * own entitlement. So the graph is configured once - the shared context, and each agent's own
+     * under `agents` - and every step it takes is checked and billed as the agent that took it. A
+     * refusal is thrown as `AccessDeniedError` from inside the refused agent; what that means for the
+     * run is the graph's to decide.
+     *
+     * What comes back is framework-neutral: the start and end of each model call and tool. A
+     * framework binding drives it - `new StiggLangChainCallbackHandler({ stigg, ...options })` from
+     * `@stigg/agent-sdk-js/langchain` builds one of these - and so can a harness of your own.
+     */
+    middleware(options?: MiddlewareOptions): GovernedAgentMiddleware;
     /**
      * Hangs the governance handle off the wrapped client. Refuses to overwrite a `stigg` the vendor
      * already has: silently replacing one of its own properties would be a worse surprise.

package/dist/stigg-agent-sdk.js

@@ -36,6 +36,7 @@ const openrouter_recipe_1 = require("./bindings/client/gateways/openrouter/openr
 const typesafe_recipe_1 = require("./bindings/client/providers/typesafe/typesafe-recipe");
 const registry_1 = require("./bindings/client/core/registry");
 const wrap_client_1 = require("./bindings/client/core/wrap-client");
+const agent_middleware_1 = require("./bindings/orchestrator/core/agent-middleware");
 const token_usage_1 = require("./bindings/shared/token-usage");
 const context_1 = require("./core/context");
 const session_1 = require("./core/session");
@@ -43,8 +44,8 @@ const hooks_1 = require("./core/hooks");
 const types_1 = require("./types");
 /**
  * Recipes are data - method paths and usage extractors - so wiring them here costs nothing at
- * runtime and pulls in no vendor package. An orchestration adapter is different: it needs its
- * framework loaded, so it stays an explicit subpath import.
+ * runtime and pulls in no vendor package. The LangChain handler, which does load its framework,
+ * is reached only through the `@stigg/agent-sdk-js/langchain` entry, never from here.
  */
 /**
  * Order matters: the gateways are matched before the plain OpenAI adapter, because every one of
@@ -125,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 };
@@ -195,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
@@ -398,6 +407,47 @@ class StiggAgentSDK {
             void session.warmUp(context);
         return governed;
     }
+    /**
+     * An agent graph's governance middleware - the orchestration counterpart to `wrap`.
+     *
+     * There is no single client to gate in a graph: it is several agents, each spending against its
+     * own entitlement. So the graph is configured once - the shared context, and each agent's own
+     * under `agents` - and every step it takes is checked and billed as the agent that took it. A
+     * refusal is thrown as `AccessDeniedError` from inside the refused agent; what that means for the
+     * run is the graph's to decide.
+     *
+     * What comes back is framework-neutral: the start and end of each model call and tool. A
+     * framework binding drives it - `new StiggLangChainCallbackHandler({ stigg, ...options })` from
+     * `@stigg/agent-sdk-js/langchain` builds one of these - and so can a harness of your own.
+     */
+    middleware(options = {}) {
+        // Started, not awaited, and caught - for the reasons `wrap` gives.
+        void this.ensureStarted().catch((err) => this.reportStartupFailure(err));
+        const shared = (0, context_1.resolveContext)(options.stiggContext ?? {}, (0, node_crypto_1.randomUUID)(), {
+            requireCustomer: false,
+            defaults: this.contextDefaults,
+        });
+        const { shared: sharedAgent, agents } = (0, agent_middleware_1.resolveAgents)(shared, options);
+        // Spans for the observability tool already tracing the graph - out of the box, for orchestrators only.
+        const session = this.newSession(options.hooks, { tracing: true });
+        const middleware = (0, agent_middleware_1.createAgentMiddleware)(session, {
+            shared: sharedAgent,
+            agents,
+            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 }`.',
+        });
+        this.attachGovernance(middleware, session, shared);
+        if (shared.customerId)
+            void session.warmUp(shared);
+        return middleware;
+    }
     /**
      * Hangs the governance handle off the wrapped client. Refuses to overwrite a `stigg` the vendor
      * already has: silently replacing one of its own properties would be a worse surprise.
@@ -457,8 +507,9 @@ class StiggAgentSDK {
     get contextDefaults() {
         return { checkErrorAction: this.config.checkErrorAction, ingestMode: this.config.ingest };
     }
-    newSession(hooks) {
+    newSession(hooks, { tracing = false } = {}) {
         const session = new session_1.GovernanceSession({
+            tracing,
             engine: () => this.ensureStarted().then((state) => state.engine),
             provisionCustomer: (customerId, planId) => this.provisionCustomer(customerId, planId),
             logger: this.config.logger,
@@ -475,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')
@@ -491,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/dist/types.d.ts

@@ -13,6 +13,7 @@ import type { StiggContext } from './core/context';
 import type { SessionSummary, SessionHooks } from './core/session';
 import type { GovernanceHeaders } from './headers';
 import type { ClientRecipe } from './bindings/client/core/types';
+import type { AgentMiddleware } from './bindings/orchestrator/core/agent-middleware';
 import type { ObservedVendor } from './bindings/shared/token-usage';
 import type { EventIngest } from './engine/engine';
 /**
@@ -347,6 +348,102 @@ export type ClientOptions = {
 export type ClientContext = Omit<StiggContext, 'idempotencyKey'> & {
     idempotencyKey?: never;
 };
+/**
+ * The governance of one agent graph: `stigg.middleware(options)`. Framework-neutral - a framework
+ * binding drives it (for LangChain and LangGraph, `StiggLangChainCallbackHandler`, which takes the
+ * same options), and so can a customer's own harness.
+ *
+ * A graph is configured here rather than wired call by call: the shared settings once, and each
+ * agent that should be governed as itself under `agents`, by the name its framework knows it by.
+ * Every step is checked and billed as the agent that took it, so one agent running dry stops that
+ * agent and nothing else.
+ *
+ * The customer is the one thing usually left out, because that changes per request: it rides each
+ * run instead, wherever the binding says (on LangChain, `metadata.stiggCustomerId`), and wins over a
+ * default here. Set it server-side, from the authenticated user, never from the request.
+ */
+export type MiddlewareOptions = {
+    /**
+     * The context every agent starts from - what is checked, how usage prices, how it is reported.
+     * An agent's own `stiggContext` is laid over it, so this is where the parts they share go once.
+     * No `idempotencyKey`, for the reason a client's default has none: every step would share it.
+     */
+    stiggContext?: ClientContext;
+    /**
+     * The tools every agent may call that are governed, by tool name - `'*'` for every tool not
+     * named. An agent's own `tools` are laid over these. A tool not covered runs ungoverned.
+     */
+    tools?: MiddlewareTools;
+    /**
+     * Everything the graph reports back while it works. Each call's `HookContext.agent` says which
+     * agent took the step, so one hook can tell them apart.
+     */
+    hooks?: SessionHooks;
+    /**
+     * The agents governed as themselves, by the name the framework stamps on their steps - on
+     * LangChain, the `name` given to `createAgent`, or the node's name in a hand-built LangGraph graph.
+     *
+     * An agent left out is not left ungoverned: its steps run under the shared `stiggContext` alone -
+     * at the customer level, unless that context names an agent - and the SDK says once that it was
+     * not listed. Leave `agents` out entirely and every step is governed that way, which is a
+     * one-agent graph or a customer-level one.
+     */
+    agents?: Record<string, MiddlewareAgentOptions>;
+    /**
+     * Where this framework's caller puts the customer, for the refusal a step with none raises. Set
+     * by a framework binding; a harness of your own can name its own convention here.
+     */
+    missingCustomer?: string;
+};
+/** One agent's part of a graph's middleware, laid over the shared settings. */
+export type MiddlewareAgentOptions = {
+    /** This agent's context over the shared one - typically its `agentId`, and what it gates on. */
+    stiggContext?: ClientContext;
+    /** This agent's tools over the shared ones - its own paid tools, or `false` to exempt one. */
+    tools?: MiddlewareTools;
+};
+/**
+ * The governed tools of a graph, by tool name, with `'*'` standing for every tool not named.
+ *
+ * `false` exempts a tool, `'*'` included. It is what a sub-agent held as a tool needs under `'*'`:
+ * that sub-agent's own model calls are already checked and billed, so billing the tool that runs it
+ * too would charge the same work twice.
+ */
+export type MiddlewareTools = Record<string, Entitlement | ToolGovernance | false>;
+/**
+ * How one tool is governed. An entitlement alone is shorthand for `{ entitlement }`.
+ *
+ * - `entitlement` - checked before the tool runs, and refused like a model call.
+ * - `usage` - what a call that succeeded reports, from the tool's own input and output, as a
+ *   client's `usageMapper` does for a model call. Left out, a call reports one unit against
+ *   `entitlement`. Given without `entitlement`, the tool is metered and never refused.
+ */
+export type ToolGovernance = {
+    entitlement: Entitlement;
+    usage?: ToolUsageMapper;
+} | {
+    entitlement?: undefined;
+    usage: ToolUsageMapper;
+};
+/**
+ * Turns one tool call into the metrics to report. Never throws into the run: a mapper that throws
+ * is a metering failure, reported through `onError` like any other.
+ */
+export type ToolUsageMapper = (call: ToolCallMeasurement) => Metrics;
+/** One tool call that succeeded, as a `ToolUsageMapper` sees it. */
+export type ToolCallMeasurement = {
+    /** The tool's name. */
+    name: string;
+    /** What the tool was called with - its arguments, parsed, when the framework passed them as JSON. */
+    input: unknown;
+    /** What the tool returned - parsed, when the framework passed it on as JSON. */
+    output: unknown;
+};
+/** A graph's middleware, carrying the same governance handle a wrapped client does. */
+export type GovernedAgentMiddleware = AgentMiddleware & {
+    /** What this graph did, and what is still in flight. */
+    readonly stigg: ClientGovernance;
+};
 /**
  * `register` - giving an agent an identity, a budget, and a place in the tree.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.4.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",
@@ -17,6 +17,10 @@
         "types": "./dist/internal.d.ts",
         "default": "./dist/internal.js"
       },
+      "./langchain": {
+        "types": "./dist/integrations/langchain.d.ts",
+        "default": "./dist/integrations/langchain.js"
+      },
       "./package.json": "./package.json"
     }
   },
@@ -44,6 +48,8 @@
     "example-client-databricks": "tsx examples/client/databricks.ts",
     "example-client-typesafe": "tsx examples/client/typesafe.ts",
     "example-two-agents": "tsx examples/client/two-agents.ts",
+    "example-orchestrator-langchain": "tsx examples/orchestrator/langchain.ts",
+    "example-orchestrator-langgraph": "tsx examples/orchestrator/langgraph.ts",
     "example-gateway": "tsx examples/gateway/openrouter.ts",
     "example-gateway-openrouter": "tsx examples/gateway/openrouter.ts",
     "example-gateway-litellm": "tsx examples/gateway/litellm.ts",
@@ -69,17 +75,43 @@
     "@stigg/typescript": "0.1.0-beta.55",
     "zod": "^4.6.1"
   },
+  "peerDependencies": {
+    "@langchain/core": ">=1.0.0 <2",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.124.0",
     "@aws-sdk/client-bedrock-runtime": "^3.1150.0",
     "@databricks/sdk-modelservingquery": "0.25.0",
     "@google/genai": "^2.28.0",
+    "@langchain/anthropic": "^1.5.12",
+    "@langchain/core": "^1.2.18",
+    "@langchain/langgraph": "^1.5.1",
+    "@langchain/tavily": "^1.2.0",
+    "@langfuse/langchain": "^6.0.0",
+    "@langfuse/otel": "^6.0.0",
+    "@langfuse/tracing": "^6.0.0",
     "@mistralai/mistralai": "^2.7.0",
     "@openrouter/sdk": "^1.4.25",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.12.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
+    "@opentelemetry/otlp-exporter-base": "^0.220.0",
+    "@opentelemetry/sdk-trace-base": "^2.12.0",
+    "@opentelemetry/sdk-trace-node": "^2.0.1",
     "@typesafe-ai/sdk": "^0.6.0",
     "cloudflare": "^7.3.0",
     "dotenv": "^17.4.2",
     "groq-sdk": "^1.6.0",
+    "langchain": "^1.5.18",
     "ollama": "^0.6.4",
     "openai": "^7.13.0",
     "tsx": "^4.23.13"
@@ -93,6 +125,10 @@
       "types": "./dist/internal.d.ts",
       "default": "./dist/internal.js"
     },
+    "./langchain": {
+      "types": "./dist/integrations/langchain.d.ts",
+      "default": "./dist/integrations/langchain.js"
+    },
     "./package.json": "./package.json"
   }
 }