@agentguard-run/spend 0.15.10 → 0.15.12

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';

package/src/router.ts

@@ -11,6 +11,22 @@
 
 import { getCachedCatalog, type OpenRouterCatalog } from './openrouter-catalog';
 
+// Spend-and-policy-aware model router (removes vendor risk). Re-exported here so
+// the `./router` subpath exposes both the config recommender and the executor.
+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 interface RouterCatalogModel {
   id: string;
   in_per_mtok: number;