@agentguard-run/spend 0.15.11 → 0.15.12

package/README.md

@@ -223,6 +223,42 @@ Only `InvokeModel` / `InvokeModelWithResponseStream` commands are gated; other B
 
 Python includes OpenAI, Anthropic, Bedrock, LangChain, CrewAI, and LlamaIndex integration helpers.
 
+## Framework integrations
+
+Drop-in adapters translate each framework's own hook/middleware surface into the
+same shared enforcement core (`guard.decide()` + the Ed25519-signed receipt
+chain). They never proxy prompts, completions, or provider keys — only redacted
+request shape reaches a receipt. One line each:
+
+```ts
+// Vercel AI SDK — wrapLanguageModel middleware (runs guard.decide before generate/stream)
+import { wrapLanguageModel } from 'ai';
+import { agentguardAiSdkMiddleware } from '@agentguard-run/spend/frameworks/vercel-ai';
+const governed = wrapLanguageModel({ model, middleware: agentguardAiSdkMiddleware({ policy, scope }) });
+
+// OpenAI SDK / OpenAI Agents SDK — wrap the client's chat.completions.create
+import OpenAI from 'openai';
+import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+const client = withSpendGuardOpenAI(new OpenAI(), { policy, scope });
+
+// LangChain (JS) — BaseCallbackHandler (handleChatModelStart preflights, handleLLMEnd settles)
+import { ChatOpenAI } from '@langchain/openai';
+import { createLangChainHandler } from '@agentguard-run/spend/frameworks/langchain';
+const llm = new ChatOpenAI({ callbacks: [createLangChainHandler({ policy, scope })] });
+
+// OpenRouter — wrap an OpenAI-compatible client pointed at openrouter.ai
+import { withSpendGuardOpenRouter } from '@agentguard-run/spend/frameworks/openrouter';
+const or = withSpendGuardOpenRouter(new OpenAI({ baseURL: 'https://openrouter.ai/api/v1' }), { policy, scope });
+
+// Claude Code — PreToolUse/PostToolUse hooks
+import { createClaudeCodeHooks } from '@agentguard-run/spend/frameworks/claude-code';
+const hooks = createClaudeCodeHooks({ policy, scope });
+
+// Hermes — pre-tool-call / approval / post-tool-call plugin hooks
+import { createHermesPlugin } from '@agentguard-run/spend/frameworks/hermes';
+export default createHermesPlugin({ policy, scope });
+```
+
 ## Spend-aware model router (removes vendor risk)
 
 `createRouter(...)` composes the bindings, the enforcement engine, and the signed receipt chain into one call: it picks a candidate model across providers by policy, enforces the spend cap with the **same** enforcement path (block / downgrade / allow), executes it, and **fails over to the next provider** on a provider error/timeout or a cap breach on the chosen model. Every route is recorded in a signed, hash-chained routing receipt (candidates considered, winner, reason, resolved cost, fallbacks) that verifies with the existing `verifyChain`. No prompt/completion content or keys ever enter the receipt.

package/dist/frameworks/index.d.ts

@@ -4,4 +4,6 @@ export * from './vercel-ai';
 export * from './claude-code';
 export * from './hermes';
 export * from './hermes-kanban';
+export * from './langchain';
+export * from './openai';
 //# sourceMappingURL=index.d.ts.map

package/dist/frameworks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/frameworks/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/frameworks/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}

package/dist/frameworks/index.js

@@ -20,4 +20,6 @@ __exportStar(require("./vercel-ai"), exports);
 __exportStar(require("./claude-code"), exports);
 __exportStar(require("./hermes"), exports);
 __exportStar(require("./hermes-kanban"), exports);
+__exportStar(require("./langchain"), exports);
+__exportStar(require("./openai"), exports);
 //# sourceMappingURL=index.js.map

package/dist/frameworks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/frameworks/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,+CAA6B;AAC7B,8CAA4B;AAC5B,gDAA8B;AAC9B,2CAAyB;AACzB,kDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/frameworks/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,+CAA6B;AAC7B,8CAA4B;AAC5B,gDAA8B;AAC9B,2CAAyB;AACzB,kDAAgC;AAChC,8CAA4B;AAC5B,2CAAyB"}

package/dist/frameworks/langchain.d.ts

@@ -0,0 +1,52 @@
+import type { SpendGuard } from '../spend-guard';
+import { type FrameworkAdapterOptions } from './common';
+/**
+ * LangChain.js callback handler that runs `guard.decide()` before every LLM /
+ * chat-model call and settles real token usage after it completes.
+ *
+ * Hook point: LangChain's `BaseCallbackHandler` lifecycle methods
+ * `handleChatModelStart` / `handleLLMStart` (preflight, may throw
+ * AgentGuardBlockedError) and `handleLLMEnd` (usage settlement). We do NOT
+ * extend the real BaseCallbackHandler (that would force a peer-dep import at
+ * module load); LangChain duck-types handlers by these method names, and we set
+ * `awaitHandlers = true` so a thrown block aborts the call.
+ *
+ * This adapter reuses the shared framework core (createFrameworkGuard +
+ * preflightFrameworkCall + settleFrameworkCall). It never proxies prompts,
+ * completions, or provider keys — only redacted request shape leaves for the
+ * signed receipt.
+ *
+ * @example
+ *   import { ChatOpenAI } from '@langchain/openai';
+ *   import { createLangChainHandler } from '@agentguard-run/spend/frameworks/langchain';
+ *
+ *   const handler = createLangChainHandler({ policy, scope });
+ *   const llm = new ChatOpenAI({ callbacks: [handler] });
+ *   await llm.invoke('hello'); // throws AgentGuardBlockedError if a cap blocks
+ */
+export interface LangChainAdapterOptions extends FrameworkAdapterOptions {
+    framework?: 'langchain';
+}
+interface LangChainSerialized {
+    id?: string[];
+    kwargs?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare class AgentGuardLangChainHandler {
+    readonly name = "agentguard_spend";
+    /** Ensures LangChain awaits the handler so a thrown block actually aborts. */
+    readonly awaitHandlers = true;
+    readonly guard: SpendGuard;
+    private readonly opts;
+    private readonly pending;
+    constructor(opts: LangChainAdapterOptions);
+    handleChatModelStart(llm: LangChainSerialized, messages: unknown[][], runId: string, _parentRunId?: string, extraParams?: Record<string, unknown>, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleLLMStart(llm: LangChainSerialized, prompts: unknown[], runId: string, _parentRunId?: string, extraParams?: Record<string, unknown>, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleLLMEnd(output: unknown, runId: string): Promise<void>;
+    handleLLMError(_error: unknown, runId: string): Promise<void>;
+    private start;
+}
+export declare function createLangChainHandler(opts: LangChainAdapterOptions): AgentGuardLangChainHandler;
+export declare const agentguardLangChainHandler: typeof createLangChainHandler;
+export {};
+//# sourceMappingURL=langchain.d.ts.map

package/dist/frameworks/langchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../../src/frameworks/langchain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAUL,KAAK,uBAAuB,EAE7B,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,uBAAwB,SAAQ,uBAAuB;IACtE,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED,UAAU,mBAAmB;IAC3B,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,0BAA0B;IACrC,QAAQ,CAAC,IAAI,sBAAsB;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,QAAQ;IAC9B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;gBAErD,IAAI,EAAE,uBAAuB;IAKnC,oBAAoB,CACxB,GAAG,EAAE,mBAAmB,EACxB,QAAQ,EAAE,OAAO,EAAE,EAAE,EACrB,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;IAIV,cAAc,CAClB,GAAG,EAAE,mBAAmB,EACxB,OAAO,EAAE,OAAO,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;IAIV,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY3D,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAIrD,KAAK;CA2BpB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,GAAG,0BAA0B,CAEhG;AAED,eAAO,MAAM,0BAA0B,+BAAyB,CAAC"}

package/dist/frameworks/langchain.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentguardLangChainHandler = exports.AgentGuardLangChainHandler = void 0;
+exports.createLangChainHandler = createLangChainHandler;
+const common_1 = require("./common");
+class AgentGuardLangChainHandler {
+    name = 'agentguard_spend';
+    /** Ensures LangChain awaits the handler so a thrown block actually aborts. */
+    awaitHandlers = true;
+    guard;
+    opts;
+    pending = new Map();
+    constructor(opts) {
+        this.opts = { ...opts, framework: 'langchain' };
+        this.guard = (0, common_1.createFrameworkGuard)(this.opts);
+    }
+    async handleChatModelStart(llm, messages, runId, _parentRunId, extraParams, _tags, metadata) {
+        await this.start(runId, llm, messages, extraParams, metadata);
+    }
+    async handleLLMStart(llm, prompts, runId, _parentRunId, extraParams, _tags, metadata) {
+        await this.start(runId, llm, prompts, extraParams, metadata);
+    }
+    async handleLLMEnd(output, runId) {
+        const preflight = this.pending.get(runId);
+        if (!preflight)
+            return;
+        this.pending.delete(runId);
+        await (0, common_1.settleFrameworkCall)(preflight, normalizeUsage(output));
+        await (0, common_1.recordFrameworkReceipt)(this.guard, 'langchain', {
+            event: 'llm_end',
+            decisionId: preflight.decision.decisionId,
+            model: preflight.decision.modelResolved,
+        });
+    }
+    async handleLLMError(_error, runId) {
+        this.pending.delete(runId);
+    }
+    async start(runId, llm, payload, extraParams, metadata) {
+        const invocation = (0, common_1.objectRecord)(extraParams?.invocation_params) ?? {};
+        const model = (0, common_1.modelFromUnknown)(invocation.model ?? invocation.model_name ?? lastId(llm) ?? (0, common_1.objectRecord)(llm?.kwargs)?.model, this.opts.defaultModel ?? 'unknown');
+        const preflight = await (0, common_1.preflightFrameworkCall)(this.guard, this.opts, {
+            framework: 'langchain',
+            model,
+            params: payload,
+            outputTokens: (0, common_1.outputTokensFromParams)(invocation, this.opts.defaultOutputTokens ?? 1024),
+            metadata: (0, common_1.redactDataPlane)(metadata ?? {}),
+            workflowId: (0, common_1.stringValue)(metadata?.workflowId) ?? (0, common_1.stringValue)(metadata?.thread_id),
+            requestShape: {
+                toolCount: Array.isArray(invocation.tools) ? invocation.tools.length : 0,
+                maxTokens: invocation.max_tokens ?? invocation.maxTokens,
+                stream: invocation.stream === true,
+            },
+        });
+        this.pending.set(runId, preflight);
+    }
+}
+exports.AgentGuardLangChainHandler = AgentGuardLangChainHandler;
+function createLangChainHandler(opts) {
+    return new AgentGuardLangChainHandler(opts);
+}
+exports.agentguardLangChainHandler = createLangChainHandler;
+function lastId(llm) {
+    const id = llm?.id;
+    return Array.isArray(id) && id.length ? id[id.length - 1] : undefined;
+}
+/**
+ * Map a LangChain LLMResult into the `{ usage: { inputTokens, outputTokens } }`
+ * shape that settleFrameworkCall expects. LangChain reports token usage on
+ * `llmOutput.tokenUsage` (OpenAI) or `llmOutput.usage`.
+ */
+function normalizeUsage(output) {
+    const record = (0, common_1.objectRecord)(output);
+    const llmOutput = (0, common_1.objectRecord)(record?.llmOutput);
+    const tokenUsage = (0, common_1.objectRecord)(llmOutput?.tokenUsage) ?? (0, common_1.objectRecord)(llmOutput?.usage);
+    if (!tokenUsage)
+        return null;
+    return {
+        usage: {
+            inputTokens: tokenUsage.promptTokens ?? tokenUsage.prompt_tokens ?? tokenUsage.input_tokens ?? tokenUsage.inputTokens,
+            outputTokens: tokenUsage.completionTokens ?? tokenUsage.completion_tokens ?? tokenUsage.output_tokens ?? tokenUsage.outputTokens,
+        },
+    };
+}
+//# sourceMappingURL=langchain.js.map

package/dist/frameworks/langchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.js","sourceRoot":"","sources":["../../src/frameworks/langchain.ts"],"names":[],"mappings":"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"}

package/dist/frameworks/openai.d.ts

@@ -0,0 +1,33 @@
+import { type OpenAIBindingOptions } from '../spend-guard';
+/**
+ * One-line spend governance for the OpenAI SDK and the OpenAI Agents SDK.
+ *
+ * Hook point: the OpenAI client's `chat.completions.create`. `withSpendGuard`
+ * (the shared core binding) wraps that method so `guard.decide()` runs before
+ * every dispatch and can block/downgrade. Because the OpenAI Agents SDK
+ * (`@openai/agents`) drives the same underlying `OpenAI` client, passing the
+ * guarded client to the agent runner governs every model call the agent makes.
+ *
+ * This is a thin, named re-export of `withSpendGuard` so the OpenAI integration
+ * is discoverable at `@agentguard-run/spend/frameworks/openai`. It reuses the
+ * existing enforcement verbatim — no second code path.
+ *
+ * @example OpenAI SDK
+ *   import OpenAI from 'openai';
+ *   import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+ *
+ *   const client = withSpendGuardOpenAI(new OpenAI(), { policy, scope });
+ *   await client.chat.completions.create({ model: 'gpt-5', messages });
+ *
+ * @example OpenAI Agents SDK
+ *   import OpenAI from 'openai';
+ *   import { Agent, run, setDefaultOpenAIClient } from '@openai/agents';
+ *   import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+ *
+ *   setDefaultOpenAIClient(withSpendGuardOpenAI(new OpenAI(), { policy, scope }));
+ *   await run(new Agent({ name: 'assistant' }), 'hello');
+ */
+export declare function withSpendGuardOpenAI<TClient>(client: TClient, opts: OpenAIBindingOptions): TClient;
+export declare const withOpenAISpendGuard: typeof withSpendGuardOpenAI;
+export type { OpenAIBindingOptions } from '../spend-guard';
+//# sourceMappingURL=openai.d.ts.map

package/dist/frameworks/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/frameworks/openai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAElG;AAED,eAAO,MAAM,oBAAoB,6BAAuB,CAAC;AACzD,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/frameworks/openai.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withOpenAISpendGuard = void 0;
+exports.withSpendGuardOpenAI = withSpendGuardOpenAI;
+const spend_guard_1 = require("../spend-guard");
+/**
+ * One-line spend governance for the OpenAI SDK and the OpenAI Agents SDK.
+ *
+ * Hook point: the OpenAI client's `chat.completions.create`. `withSpendGuard`
+ * (the shared core binding) wraps that method so `guard.decide()` runs before
+ * every dispatch and can block/downgrade. Because the OpenAI Agents SDK
+ * (`@openai/agents`) drives the same underlying `OpenAI` client, passing the
+ * guarded client to the agent runner governs every model call the agent makes.
+ *
+ * This is a thin, named re-export of `withSpendGuard` so the OpenAI integration
+ * is discoverable at `@agentguard-run/spend/frameworks/openai`. It reuses the
+ * existing enforcement verbatim — no second code path.
+ *
+ * @example OpenAI SDK
+ *   import OpenAI from 'openai';
+ *   import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+ *
+ *   const client = withSpendGuardOpenAI(new OpenAI(), { policy, scope });
+ *   await client.chat.completions.create({ model: 'gpt-5', messages });
+ *
+ * @example OpenAI Agents SDK
+ *   import OpenAI from 'openai';
+ *   import { Agent, run, setDefaultOpenAIClient } from '@openai/agents';
+ *   import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+ *
+ *   setDefaultOpenAIClient(withSpendGuardOpenAI(new OpenAI(), { policy, scope }));
+ *   await run(new Agent({ name: 'assistant' }), 'hello');
+ */
+function withSpendGuardOpenAI(client, opts) {
+    return (0, spend_guard_1.withSpendGuard)(client, opts);
+}
+exports.withOpenAISpendGuard = withSpendGuardOpenAI;
+//# sourceMappingURL=openai.js.map

package/dist/frameworks/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/frameworks/openai.ts"],"names":[],"mappings":";;;AA8BA,oDAEC;AAhCD,gDAA2E;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,oBAAoB,CAAU,MAAe,EAAE,IAA0B;IACvF,OAAO,IAAA,4BAAc,EAAC,MAAM,EAAE,IAAI,CAAY,CAAC;AACjD,CAAC;AAEY,QAAA,oBAAoB,GAAG,oBAAoB,CAAC"}

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export { withSpendGuardBedrock, type BedrockBindingOptions } from './bindings/be
 export { recommend, defaultKey, type ModelRouteRecommendation, type RecommendOptions } from './router';
 export { createRouter, RoutingExhaustedError, type ModelRouter, type CreateRouterConfig, type RouterCandidate, type RouterPolicy, type RouterProvider, type RouterRequest, type RouteResult, type RouteReason, type RouteFallback, } from './router-engine';
 export { DEFAULT_LOCALE, SUPPORTED_LOCALES, TRANSLATIONS, type SupportedLocale, resolveLocale, t, formatBlockedTrace, type BlockedTraceArgs, } from './i18n';
-export declare const AGENTGUARD_SPEND_VERSION = "0.15.11";
+export declare const AGENTGUARD_SPEND_VERSION = "0.15.12";
 export declare const agentguard: {
     workflow: typeof runWorkflow;
 };

package/dist/index.js

@@ -167,7 +167,7 @@ Object.defineProperty(exports, "TRANSLATIONS", { enumerable: true, get: function
 Object.defineProperty(exports, "resolveLocale", { enumerable: true, get: function () { return i18n_1.resolveLocale; } });
 Object.defineProperty(exports, "t", { enumerable: true, get: function () { return i18n_1.t; } });
 Object.defineProperty(exports, "formatBlockedTrace", { enumerable: true, get: function () { return i18n_1.formatBlockedTrace; } });
-exports.AGENTGUARD_SPEND_VERSION = '0.15.11';
+exports.AGENTGUARD_SPEND_VERSION = '0.15.12';
 exports.agentguard = {
     workflow: context_1.workflow,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentguard-run/spend",
-  "version": "0.15.11",
+  "version": "0.15.12",
   "description": "All terminology and labels used in AgentGuard materials are descriptive of software functionality only, not legal definitions or guarantees of compliance. Terms like receipt, audit log, evidence, audit trail, and attestation refer solely to cryptographically-signed records produced by the software. Full functional-use disclaimer in README.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -110,6 +110,16 @@
       "require": "./dist/frameworks/openrouter.js",
       "default": "./dist/frameworks/openrouter.js"
     },
+    "./frameworks/langchain": {
+      "types": "./dist/frameworks/langchain.d.ts",
+      "require": "./dist/frameworks/langchain.js",
+      "default": "./dist/frameworks/langchain.js"
+    },
+    "./frameworks/openai": {
+      "types": "./dist/frameworks/openai.d.ts",
+      "require": "./dist/frameworks/openai.js",
+      "default": "./dist/frameworks/openai.js"
+    },
     "./operating-pack": {
       "types": "./dist/operating-pack.d.ts",
       "require": "./dist/operating-pack.js",

package/src/frameworks/README.md

@@ -42,3 +42,38 @@ const client = withSpendGuardOpenRouter(new OpenAI({
   apiKey: process.env.OPENROUTER_API_KEY,
 }), { policy, scope });
 ```
+
+## OpenAI SDK / OpenAI Agents SDK
+
+Hook point: the OpenAI client's `chat.completions.create`. Wrap the client once
+and every call the agent runner makes is governed.
+
+```ts
+import OpenAI from 'openai';
+import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+
+const client = withSpendGuardOpenAI(new OpenAI(), { policy, scope });
+```
+
+```ts
+// OpenAI Agents SDK — govern every model call the agent makes
+import OpenAI from 'openai';
+import { run, Agent, setDefaultOpenAIClient } from '@openai/agents';
+import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+
+setDefaultOpenAIClient(withSpendGuardOpenAI(new OpenAI(), { policy, scope }));
+```
+
+## LangChain (JS)
+
+Hook point: LangChain's `BaseCallbackHandler` lifecycle
+(`handleChatModelStart` / `handleLLMStart` preflight `guard.decide()`,
+`handleLLMEnd` settles real token usage). A blocked call throws
+`AgentGuardBlockedError`.
+
+```ts
+import { ChatOpenAI } from '@langchain/openai';
+import { createLangChainHandler } from '@agentguard-run/spend/frameworks/langchain';
+
+const llm = new ChatOpenAI({ callbacks: [createLangChainHandler({ policy, scope })] });
+```

package/src/frameworks/index.ts

@@ -4,3 +4,5 @@ export * from './vercel-ai';
 export * from './claude-code';
 export * from './hermes';
 export * from './hermes-kanban';
+export * from './langchain';
+export * from './openai';

package/src/frameworks/langchain.ts

@@ -0,0 +1,159 @@
+import type { SpendGuard } from '../spend-guard';
+import {
+  createFrameworkGuard,
+  modelFromUnknown,
+  objectRecord,
+  outputTokensFromParams,
+  preflightFrameworkCall,
+  recordFrameworkReceipt,
+  redactDataPlane,
+  settleFrameworkCall,
+  stringValue,
+  type FrameworkAdapterOptions,
+  type FrameworkPreflight,
+} from './common';
+
+/**
+ * LangChain.js callback handler that runs `guard.decide()` before every LLM /
+ * chat-model call and settles real token usage after it completes.
+ *
+ * Hook point: LangChain's `BaseCallbackHandler` lifecycle methods
+ * `handleChatModelStart` / `handleLLMStart` (preflight, may throw
+ * AgentGuardBlockedError) and `handleLLMEnd` (usage settlement). We do NOT
+ * extend the real BaseCallbackHandler (that would force a peer-dep import at
+ * module load); LangChain duck-types handlers by these method names, and we set
+ * `awaitHandlers = true` so a thrown block aborts the call.
+ *
+ * This adapter reuses the shared framework core (createFrameworkGuard +
+ * preflightFrameworkCall + settleFrameworkCall). It never proxies prompts,
+ * completions, or provider keys — only redacted request shape leaves for the
+ * signed receipt.
+ *
+ * @example
+ *   import { ChatOpenAI } from '@langchain/openai';
+ *   import { createLangChainHandler } from '@agentguard-run/spend/frameworks/langchain';
+ *
+ *   const handler = createLangChainHandler({ policy, scope });
+ *   const llm = new ChatOpenAI({ callbacks: [handler] });
+ *   await llm.invoke('hello'); // throws AgentGuardBlockedError if a cap blocks
+ */
+export interface LangChainAdapterOptions extends FrameworkAdapterOptions {
+  framework?: 'langchain';
+}
+
+interface LangChainSerialized {
+  id?: string[];
+  kwargs?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export class AgentGuardLangChainHandler {
+  readonly name = 'agentguard_spend';
+  /** Ensures LangChain awaits the handler so a thrown block actually aborts. */
+  readonly awaitHandlers = true;
+  readonly guard: SpendGuard;
+  private readonly opts: LangChainAdapterOptions;
+  private readonly pending = new Map<string, FrameworkPreflight>();
+
+  constructor(opts: LangChainAdapterOptions) {
+    this.opts = { ...opts, framework: 'langchain' };
+    this.guard = createFrameworkGuard(this.opts);
+  }
+
+  async handleChatModelStart(
+    llm: LangChainSerialized,
+    messages: unknown[][],
+    runId: string,
+    _parentRunId?: string,
+    extraParams?: Record<string, unknown>,
+    _tags?: string[],
+    metadata?: Record<string, unknown>,
+  ): Promise<void> {
+    await this.start(runId, llm, messages, extraParams, metadata);
+  }
+
+  async handleLLMStart(
+    llm: LangChainSerialized,
+    prompts: unknown[],
+    runId: string,
+    _parentRunId?: string,
+    extraParams?: Record<string, unknown>,
+    _tags?: string[],
+    metadata?: Record<string, unknown>,
+  ): Promise<void> {
+    await this.start(runId, llm, prompts, extraParams, metadata);
+  }
+
+  async handleLLMEnd(output: unknown, runId: string): Promise<void> {
+    const preflight = this.pending.get(runId);
+    if (!preflight) return;
+    this.pending.delete(runId);
+    await settleFrameworkCall(preflight, normalizeUsage(output));
+    await recordFrameworkReceipt(this.guard, 'langchain', {
+      event: 'llm_end',
+      decisionId: preflight.decision.decisionId,
+      model: preflight.decision.modelResolved,
+    });
+  }
+
+  async handleLLMError(_error: unknown, runId: string): Promise<void> {
+    this.pending.delete(runId);
+  }
+
+  private async start(
+    runId: string,
+    llm: LangChainSerialized,
+    payload: unknown,
+    extraParams?: Record<string, unknown>,
+    metadata?: Record<string, unknown>,
+  ): Promise<void> {
+    const invocation = objectRecord(extraParams?.invocation_params) ?? {};
+    const model = modelFromUnknown(
+      invocation.model ?? invocation.model_name ?? lastId(llm) ?? objectRecord(llm?.kwargs)?.model,
+      this.opts.defaultModel ?? 'unknown',
+    );
+    const preflight = await preflightFrameworkCall(this.guard, this.opts, {
+      framework: 'langchain',
+      model,
+      params: payload,
+      outputTokens: outputTokensFromParams(invocation, this.opts.defaultOutputTokens ?? 1024),
+      metadata: redactDataPlane(metadata ?? {}) as Record<string, unknown>,
+      workflowId: stringValue(metadata?.workflowId) ?? stringValue(metadata?.thread_id),
+      requestShape: {
+        toolCount: Array.isArray(invocation.tools) ? invocation.tools.length : 0,
+        maxTokens: invocation.max_tokens ?? invocation.maxTokens,
+        stream: invocation.stream === true,
+      },
+    });
+    this.pending.set(runId, preflight);
+  }
+}
+
+export function createLangChainHandler(opts: LangChainAdapterOptions): AgentGuardLangChainHandler {
+  return new AgentGuardLangChainHandler(opts);
+}
+
+export const agentguardLangChainHandler = createLangChainHandler;
+
+function lastId(llm: LangChainSerialized | undefined): string | undefined {
+  const id = llm?.id;
+  return Array.isArray(id) && id.length ? id[id.length - 1] : undefined;
+}
+
+/**
+ * Map a LangChain LLMResult into the `{ usage: { inputTokens, outputTokens } }`
+ * shape that settleFrameworkCall expects. LangChain reports token usage on
+ * `llmOutput.tokenUsage` (OpenAI) or `llmOutput.usage`.
+ */
+function normalizeUsage(output: unknown): { usage: Record<string, unknown> } | null {
+  const record = objectRecord(output);
+  const llmOutput = objectRecord(record?.llmOutput);
+  const tokenUsage = objectRecord(llmOutput?.tokenUsage) ?? objectRecord(llmOutput?.usage);
+  if (!tokenUsage) return null;
+  return {
+    usage: {
+      inputTokens: tokenUsage.promptTokens ?? tokenUsage.prompt_tokens ?? tokenUsage.input_tokens ?? tokenUsage.inputTokens,
+      outputTokens: tokenUsage.completionTokens ?? tokenUsage.completion_tokens ?? tokenUsage.output_tokens ?? tokenUsage.outputTokens,
+    },
+  };
+}

package/src/frameworks/openai.ts

@@ -0,0 +1,36 @@
+import { withSpendGuard, type OpenAIBindingOptions } from '../spend-guard';
+
+/**
+ * One-line spend governance for the OpenAI SDK and the OpenAI Agents SDK.
+ *
+ * Hook point: the OpenAI client's `chat.completions.create`. `withSpendGuard`
+ * (the shared core binding) wraps that method so `guard.decide()` runs before
+ * every dispatch and can block/downgrade. Because the OpenAI Agents SDK
+ * (`@openai/agents`) drives the same underlying `OpenAI` client, passing the
+ * guarded client to the agent runner governs every model call the agent makes.
+ *
+ * This is a thin, named re-export of `withSpendGuard` so the OpenAI integration
+ * is discoverable at `@agentguard-run/spend/frameworks/openai`. It reuses the
+ * existing enforcement verbatim — no second code path.
+ *
+ * @example OpenAI SDK
+ *   import OpenAI from 'openai';
+ *   import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+ *
+ *   const client = withSpendGuardOpenAI(new OpenAI(), { policy, scope });
+ *   await client.chat.completions.create({ model: 'gpt-5', messages });
+ *
+ * @example OpenAI Agents SDK
+ *   import OpenAI from 'openai';
+ *   import { Agent, run, setDefaultOpenAIClient } from '@openai/agents';
+ *   import { withSpendGuardOpenAI } from '@agentguard-run/spend/frameworks/openai';
+ *
+ *   setDefaultOpenAIClient(withSpendGuardOpenAI(new OpenAI(), { policy, scope }));
+ *   await run(new Agent({ name: 'assistant' }), 'hello');
+ */
+export function withSpendGuardOpenAI<TClient>(client: TClient, opts: OpenAIBindingOptions): TClient {
+  return withSpendGuard(client, opts) as TClient;
+}
+
+export const withOpenAISpendGuard = withSpendGuardOpenAI;
+export type { OpenAIBindingOptions } from '../spend-guard';