@stigg/agent-sdk-js 0.3.2 → 0.5.0

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;
     })[];
@@ -159,6 +159,18 @@ export declare class StiggAgentSDK {
      * rather than once each. Only the memoized path is shared - see `register`.
      */
     private readonly registering;
+    /**
+     * Customers this process has provisioned, by id - settled or still in flight. Shared by every
+     * client, so a customer seen by ten wrapped clients is provisioned once.
+     *
+     * 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.
+     *
+     * 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;
     private started?;
     /**
      * When the attempt currently in `started` rejected, or undefined while it is pending or has
@@ -230,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.
@@ -254,6 +280,18 @@ export declare class StiggAgentSDK {
      */
     private get contextDefaults();
     private newSession;
+    /**
+     * Creates the customer on `planId` the first time this process sees them, if Stigg does not
+     * already know them. Keyed by customer alone: once one exists, which plan a later call names
+     * is irrelevant - an existing customer is never moved.
+     */
+    private provisionCustomer;
+    /**
+     * The server picks the first subscription, and the plan asked for is only a request: a
+     * predefined free or trial plan can win, or no subscription may be created at all. Logging
+     * success regardless would hide a customer who landed somewhere nobody chose.
+     */
+    private describeProvisioned;
     /** The session the no-client paths share, built on first use so an unused SDK builds none. */
     private standalone;
     /**

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
@@ -120,6 +121,11 @@ const DEFAULT_WALLET = { currencyId: 'credits' };
  * for why remembering it at all is the point.
  */
 const RETRY_START_AFTER_MS = 2_000;
+/**
+ * How many customers one process remembers having provisioned. A server serving an open-ended set
+ * of tenants would otherwise grow this for as long as it runs.
+ */
+const KNOWN_CUSTOMERS_CAP = 10_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 };
@@ -184,6 +190,18 @@ class StiggAgentSDK {
      * rather than once each. Only the memoized path is shared - see `register`.
      */
     registering = new Map();
+    /**
+     * Customers this process has provisioned, by id - settled or still in flight. Shared by every
+     * client, so a customer seen by ten wrapped clients is provisioned once.
+     *
+     * 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.
+     *
+     * 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();
     started;
     /**
      * When the attempt currently in `started` rejected, or undefined while it is pending or has
@@ -381,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.
@@ -440,9 +495,11 @@ 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,
             onError: this.config.onError,
             hooks: hooks ?? {},
@@ -450,6 +507,52 @@ class StiggAgentSDK {
         this.sessions.add(session);
         return session;
     }
+    /**
+     * Creates the customer on `planId` the first time this process sees them, if Stigg does not
+     * already know them. Keyed by customer alone: once one exists, which plan a later call names
+     * is irrelevant - an existing customer is never moved.
+     */
+    provisionCustomer(customerId, planId) {
+        const known = this.customers.get(customerId);
+        if (known)
+            return known;
+        const pending = this.ensureStarted().then(async ({ engine }) => {
+            const outcome = await engine.provisionCustomer?.(customerId, planId);
+            if (outcome?.status === 'created')
+                this.describeProvisioned(customerId, planId, outcome);
+            // Said once, here, rather than by every call that follows: the memo keeps the refusal, so
+            // later calls go straight to the check, which answers for a customer that does not exist.
+            if (outcome?.status === 'rejected') {
+                const error = new errors_1.EngineError('provisionCustomer', `Stigg refused to provision customer ${customerId} on plan ${planId}, and will not be ` +
+                    `asked again by this process: ${outcome.reason}`);
+                (0, hooks_1.safely)(() => this.config.onError(error, { operation: 'provisionCustomer', customerId }), (reportErr) => this.config.logger.warn(`[stigg] onError threw while reporting ${error.message}: ${String(reportErr)}`));
+            }
+        });
+        this.customers.set(customerId, pending);
+        if (this.customers.size > KNOWN_CUSTOMERS_CAP) {
+            this.customers.delete(this.customers.keys().next().value);
+        }
+        // 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.
+        pending.catch(() => {
+            if (this.customers.get(customerId) === pending)
+                this.customers.delete(customerId);
+        });
+        return pending;
+    }
+    /**
+     * The server picks the first subscription, and the plan asked for is only a request: a
+     * predefined free or trial plan can win, or no subscription may be created at all. Logging
+     * success regardless would hide a customer who landed somewhere nobody chose.
+     */
+    describeProvisioned(customerId, planId, outcome) {
+        if (outcome.decision === 'REQUESTED_PLAN' && outcome.planId === planId) {
+            this.config.logger.info(`[stigg] customer ${customerId} provisioned on plan ${planId}`);
+            return;
+        }
+        this.config.logger.warn(`[stigg] customer ${customerId} was created, but not on plan ${planId}: Stigg chose ` +
+            `${outcome.decision}, and the customer is on ${outcome.planId ?? 'no plan'}.`);
+    }
     /** The session the no-client paths share, built on first use so an unused SDK builds none. */
     standalone() {
         this.loose ??= this.newSession();

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.3.2",
+  "version": "0.5.0",
   "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"
   }
 }