@stigg/agent-sdk-js 0.4.0 → 0.5.0

package/dist/core/session.js

@@ -29,6 +29,7 @@ const errors_1 = require("../errors");
 const headers_1 = require("../headers");
 const dimensions_1 = require("./dimensions");
 const hooks_1 = require("./hooks");
+const telemetry_1 = require("./telemetry");
 const context_1 = require("./context");
 const types_1 = require("../types");
 /** What a context looks like to a hook: the attribution, and nothing a hook could change. */
@@ -37,6 +38,8 @@ const hookContext = (context) => ({
     dimensions: context.dimensions,
     correlationId: context.correlationId,
     entitlementId: context.checkedId,
+    ...(context.agent !== undefined ? { agent: context.agent } : {}),
+    ...(context.tool !== undefined ? { tool: context.tool } : {}),
 });
 /** A metric nobody can bill: refused where the mapper that invented it can still be found. */
 const emptyMetricNameError = () => new errors_1.EngineError('measure', 'a metric needs a name - an empty one reports to no feature at all.');
@@ -111,13 +114,14 @@ class GovernanceSession {
      * application routes on, not an exception it recovers from.
      */
     async check(context, requestedUsage = 1) {
+        const startedAt = Date.now();
         this.checks += 1;
         const { entitlement } = context;
         // Asked and answered, with nobody to ask: this context named no entitlement, so there is no
         // budget to consult and no refusal that could come back. Still counted and recorded, because
         // the caller did ask and `lastDecision` is where they read what they got.
         if (!entitlement)
-            return this.record((0, decision_1.unenforcedDecision)(), context);
+            return this.record((0, decision_1.unenforcedDecision)(), context, startedAt);
         try {
             const engine = await this.deps.engine();
             // Before the check, not after: a customer Stigg has never seen holds no entitlement, so their
@@ -134,16 +138,16 @@ class GovernanceSession {
             // refused - an unknown plan, an archived customer - is refused here too, rather than
             // waved through by an `allow` that exists for outages, not for configuration mistakes.
             if (!reached && result.accessDeniedReason === CUSTOMER_NOT_FOUND) {
-                return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context);
+                return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context, startedAt);
             }
-            return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId, entitlement: context.entitlement }), context);
+            return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId, entitlement: context.entitlement }), context, startedAt);
         }
         catch (err) {
             const error = asEngineError('check', err);
             this.reportError(error, 'check', context);
             // Governance is fail-closed server-side; `'deny'` mirrors that, and `'allow'` - the default -
             // is the soft limit that keeps the application up while Stigg is unreachable.
-            return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context);
+            return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context, startedAt);
         }
     }
     /** Applies the context's mapper to a token measurement. The path every binding uses. */
@@ -216,6 +220,7 @@ class GovernanceSession {
     send(context, metrics, sendOptions) {
         const { dimensions, idempotencyKey, raw, event } = sendOptions;
         const mode = context.ingestMode;
+        const startedAt = Date.now();
         // A broken value is one broken metric, not a broken call: the others measured fine and the
         // spend they describe already happened. Dropping only the bad one reports what is knowable.
         //
@@ -260,10 +265,10 @@ class GovernanceSession {
         // distinguishable from one that never tried, and reported to `onIngest` like every result.
         if (!Object.keys(sendable).length) {
             if (rejected)
-                return Promise.resolve(this.failedIngest(context, idempotencyKey, rejected));
+                return Promise.resolve(this.failedIngest(context, idempotencyKey, rejected, startedAt));
             this.ingested += 1;
             const noop = { ok: true, reported: {}, idempotencyKey, mode, replayed: false };
-            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(noop, hookContext(context)));
+            this.emitIngest(context, noop, startedAt);
             return Promise.resolve(noop);
         }
         const promise = this.deps
@@ -311,10 +316,10 @@ class GovernanceSession {
                 this.ingestFailures += 1;
                 this.reportError(rejected, rejected.operation, context, idempotencyKey);
             }
-            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(landed, hookContext(context)));
+            this.emitIngest(context, landed, startedAt);
             return landed;
         })
-            .catch((err) => this.failedIngest(context, idempotencyKey, asEngineError('ingest', err)))
+            .catch((err) => this.failedIngest(context, idempotencyKey, asEngineError('ingest', err), startedAt))
             .finally(() => {
             this.pending.delete(promise);
         });
@@ -403,11 +408,22 @@ class GovernanceSession {
         this.deps.logger.warn(`[stigg] reported ${names} but the response carried no credit balance - ${names.includes(',') ? 'these features are' : 'this feature is'} not mapped to ${checked}, so the budget this call checks ` +
             'against will never drain. Map it in Stigg, or report to the currency directly.');
     }
-    record(decision, context) {
+    record(decision, context, startedAt) {
         this.decision = decision;
+        // Telemetry is instrumentation exactly as a hook is: it never reaches the caller.
+        if (this.deps.tracing) {
+            (0, hooks_1.safely)(() => (0, telemetry_1.traceCheck)(context, decision, startedAt), (err) => this.deps.logger.debug(`[stigg] check span failed: ${String(err)}`));
+        }
         this.hook('onDecision', context, () => this.deps.hooks.onDecision?.(decision, hookContext(context)));
         return decision;
     }
+    /** Every ingest result, however it ended: to its span, then to the application's hook. */
+    emitIngest(context, result, startedAt) {
+        if (this.deps.tracing) {
+            (0, hooks_1.safely)(() => (0, telemetry_1.traceIngest)(context, result, startedAt), (err) => this.deps.logger.debug(`[stigg] ingest span failed: ${String(err)}`));
+        }
+        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(result, hookContext(context)));
+    }
     /**
      * Hooks are instrumentation, so a throwing one must not reach the caller: it cannot turn an
      * allow into a denial, flip a delivered ingest to `ok: false`, or reject a promise the contract
@@ -446,7 +462,7 @@ class GovernanceSession {
             customerId: context?.customerId,
         }), (err) => this.deps.logger.warn(`[stigg] onError threw while reporting ${error.message}: ${String(err)}`));
     }
-    failedIngest(context, idempotencyKey, error) {
+    failedIngest(context, idempotencyKey, error, startedAt = Date.now()) {
         this.ingestFailures += 1;
         // The error knows what failed - reading a vendor's usage is not the same event as the report
         // that would have followed it, and a context that says otherwise makes the two
@@ -472,7 +488,7 @@ class GovernanceSession {
             replayed: error.replayed ?? false,
             error,
         };
-        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(failure, hookContext(context)));
+        this.emitIngest(context, failure, startedAt);
         return failure;
     }
 }

package/dist/core/telemetry.d.ts

@@ -0,0 +1,8 @@
+import type { AccessDecision, IngestResult } from '../types';
+import type { ResolvedContext } from './context';
+/** The instrumentation scope every Stigg span is reported under - what a span filter matches on. */
+export declare const TRACER_NAME = "@stigg/agent-sdk-js";
+/** One check, from when it was asked to when it was answered. */
+export declare function traceCheck(context: ResolvedContext, decision: AccessDecision, startedAt: number): void;
+/** One report, whether it landed, failed, or had nothing to send. */
+export declare function traceIngest(context: ResolvedContext, result: IngestResult, startedAt: number): void;

package/dist/core/telemetry.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACER_NAME = void 0;
+exports.traceCheck = traceCheck;
+exports.traceIngest = traceIngest;
+const sdk_identity_1 = require("../sdk-identity");
+/** The instrumentation scope every Stigg span is reported under - what a span filter matches on. */
+exports.TRACER_NAME = '@stigg/agent-sdk-js';
+let api;
+/** The application's copy of the API, loaded once - or `null` when it has none installed. */
+function openTelemetry() {
+    if (api === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            api = require('@opentelemetry/api');
+        }
+        catch {
+            api = null;
+        }
+    }
+    return api;
+}
+/** Asked for per span, so a provider registered after this package was loaded is still found. */
+const tracer = (otel) => otel.trace.getTracer(exports.TRACER_NAME, sdk_identity_1.AGENT_SDK_VERSION);
+/** Who the call was for: the attribution, as the check and the report both carry it. */
+function attribution(context) {
+    const attributes = {
+        'stigg.customer.id': context.customerId,
+        'stigg.correlation_id': context.correlationId,
+    };
+    if (context.agent !== undefined)
+        attributes['gen_ai.agent.name'] = context.agent;
+    if (context.tool !== undefined)
+        attributes['gen_ai.tool.name'] = context.tool;
+    if (context.attributionKey && context.dimensions[context.attributionKey] !== undefined) {
+        attributes['stigg.agent.id'] = context.dimensions[context.attributionKey];
+    }
+    for (const [key, value] of Object.entries(context.dimensions))
+        attributes[`stigg.dimension.${key}`] = value;
+    if (context.eventName)
+        attributes['stigg.event.name'] = context.eventName.name;
+    return attributes;
+}
+/** One check, from when it was asked to when it was answered. */
+function traceCheck(context, decision, startedAt) {
+    const otel = openTelemetry();
+    if (!otel)
+        return;
+    const attributes = {
+        ...attribution(context),
+        'stigg.decision.has_access': decision.hasAccess,
+        'stigg.decision.source': decision.source,
+    };
+    if (context.checkedId)
+        attributes['stigg.entitlement.id'] = context.checkedId;
+    if (decision.reason)
+        attributes['stigg.decision.reason'] = decision.reason;
+    if (decision.deniedBy)
+        attributes['stigg.decision.denied_by'] = decision.deniedBy;
+    if (decision.remaining !== undefined)
+        attributes['stigg.decision.remaining'] = decision.remaining;
+    if (decision.remedy)
+        attributes['stigg.decision.remedy'] = decision.remedy;
+    if (decision.isFallback)
+        attributes['stigg.decision.is_fallback'] = true;
+    const span = tracer(otel).startSpan('stigg.check', { startTime: startedAt, attributes });
+    if (!decision.hasAccess) {
+        span.recordException({ name: 'AccessDeniedError', message: decision.message });
+        span.setStatus({ code: otel.SpanStatusCode.ERROR, message: decision.summary });
+    }
+    span.end();
+}
+/** One report, whether it landed, failed, or had nothing to send. */
+function traceIngest(context, result, startedAt) {
+    const otel = openTelemetry();
+    if (!otel)
+        return;
+    const attributes = {
+        ...attribution(context),
+        'stigg.ingest.ok': result.ok,
+        'stigg.ingest.mode': result.mode,
+        'stigg.ingest.idempotency_key': result.idempotencyKey,
+    };
+    for (const [metric, value] of Object.entries(result.reported))
+        attributes[`stigg.metric.${metric}`] = value;
+    if (result.creditsConsumed !== undefined)
+        attributes['stigg.ingest.credits_consumed'] = result.creditsConsumed;
+    if (result.replayed !== undefined)
+        attributes['stigg.ingest.replayed'] = result.replayed;
+    const span = tracer(otel).startSpan('stigg.ingest', { startTime: startedAt, attributes });
+    if (!result.ok) {
+        const message = result.error instanceof Error ? result.error.message : String(result.error ?? 'ingest failed');
+        span.recordException({ name: 'EngineError', message });
+        span.setStatus({ code: otel.SpanStatusCode.ERROR, message });
+    }
+    span.end();
+}

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;
     })[];
@@ -242,6 +242,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
@@ -398,6 +399,43 @@ 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.'),
+            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 +495,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,

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.
  *