@agentguard-run/spend 0.13.1 → 0.13.3

package/src/frameworks/common.ts

@@ -0,0 +1,208 @@
+import type { CapabilityTier, CallContext, Provider, SignedDecisionLogEntry, SpendDecision, SpendPolicy, SpendScope } from '../types';
+import { inferProvider } from '../cost-table';
+import { sanitizeMetadata } from '../governance';
+import { AgentGuardBlockedError, SpendGuard, type SpendGuardConfig } from '../spend-guard';
+
+export interface FrameworkAdapterOptions {
+  policy: SpendPolicy;
+  scope: SpendScope;
+  capabilityClaim?: CapabilityTier;
+  config?: Omit<SpendGuardConfig, 'policy'>;
+  licenseKey?: string;
+  defaultModel?: string;
+  defaultOutputTokens?: number;
+  framework?: string;
+}
+
+export interface FrameworkPreflight {
+  guard: SpendGuard;
+  call: CallContext;
+  decision: SpendDecision;
+  signed: SignedDecisionLogEntry | null;
+}
+
+export interface FrameworkCallInput {
+  framework: string;
+  model?: string;
+  provider?: Provider;
+  params?: unknown;
+  requestShape?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  workflowId?: string;
+  subagentId?: string;
+  toolName?: string;
+  outputTokens?: number;
+}
+
+const DATA_PLANE_KEYS = /^(prompt|completion|content|messages|input|output|text|raw)$/i;
+
+export function createFrameworkGuard(opts: FrameworkAdapterOptions): SpendGuard {
+  return new SpendGuard({
+    policy: opts.policy,
+    ...(opts.config ?? {}),
+    licenseKey: opts.licenseKey ?? opts.config?.licenseKey,
+  });
+}
+
+export function safeRequestShape(value: unknown): Record<string, unknown> {
+  const redacted = redactDataPlane(value);
+  if (redacted && typeof redacted === 'object' && !Array.isArray(redacted)) {
+    return sanitizeMetadata(redacted as Record<string, unknown>);
+  }
+  return { valueType: typeof value };
+}
+
+export function redactDataPlane(value: unknown): unknown {
+  if (value == null) return value;
+  if (Array.isArray(value)) return value.map((child) => redactDataPlane(child));
+  if (typeof value !== 'object') return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if (DATA_PLANE_KEYS.test(key)) {
+      out[key + '_present'] = child != null;
+      out[key + '_type'] = Array.isArray(child) ? 'array' : typeof child;
+      if (Array.isArray(child)) out[key + '_items'] = child.length;
+      continue;
+    }
+    out[key] = redactDataPlane(child);
+  }
+  return out;
+}
+
+export function estimateInputTokens(guard: SpendGuard, value: unknown): number {
+  const serialized = typeof value === 'string' ? value : stableJson(value ?? {});
+  return Math.max(1, guard.estimateTokens(serialized));
+}
+
+export function outputTokensFromParams(params: unknown, fallback = 512): number {
+  const record = objectRecord(params);
+  const value =
+    record?.max_tokens ??
+    record?.maxTokens ??
+    record?.maxOutputTokens ??
+    record?.max_completion_tokens ??
+    record?.maxCompletionTokens;
+  return Number.isSafeInteger(value) && (value as number) >= 0 ? value as number : fallback;
+}
+
+export function modelFromUnknown(model: unknown, fallback = 'unknown'): string {
+  if (typeof model === 'string' && model.trim()) return model.trim();
+  const record = objectRecord(model);
+  for (const key of ['modelId', 'model_id', 'id', 'name']) {
+    const value = record?.[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return fallback;
+}
+
+export function providerFromModel(model: string, provider?: Provider): Provider {
+  return provider ?? inferProvider(model);
+}
+
+export function buildFrameworkCall(
+  guard: SpendGuard,
+  opts: FrameworkAdapterOptions,
+  input: FrameworkCallInput,
+): CallContext {
+  const model = modelFromUnknown(input.model, opts.defaultModel ?? 'unknown');
+  const metadata = sanitizeMetadata(redactDataPlane(input.metadata ?? {}) as Record<string, unknown>);
+  const requestShape = sanitizeMetadata({
+    framework: input.framework,
+    ...(input.requestShape ?? safeRequestShape(input.params)),
+  });
+  return {
+    provider: providerFromModel(model, input.provider),
+    model,
+    inputTokens: estimateInputTokens(guard, input.params),
+    outputTokens: input.outputTokens ?? outputTokensFromParams(input.params, opts.defaultOutputTokens ?? 512),
+    scope: opts.scope,
+    capabilityClaim: opts.capabilityClaim,
+    workflowId: input.workflowId ?? stringValue(metadata.workflowId) ?? stringValue(metadata.workflow_id),
+    subagentId: input.subagentId ?? stringValue(metadata.subagentId) ?? stringValue(metadata.subagent_id),
+    label: stringValue(metadata.label) ?? input.framework,
+    toolName: input.toolName,
+    requestShape,
+  };
+}
+
+export async function preflightFrameworkCall(
+  guard: SpendGuard,
+  opts: FrameworkAdapterOptions,
+  input: FrameworkCallInput,
+): Promise<FrameworkPreflight> {
+  const call = buildFrameworkCall(guard, opts, input);
+  const { decision, signed } = await guard.decide(call);
+  if (decision.action === 'block') {
+    throw new AgentGuardBlockedError(decision, opts.scope, opts.config?.locale);
+  }
+  return { guard, call, decision, signed };
+}
+
+export async function settleFrameworkCall(preflight: FrameworkPreflight, result: unknown, partial = false): Promise<void> {
+  const usage = usageFromResult(result);
+  if (!usage) return;
+  await preflight.guard.settleStreamUsage(
+    preflight.decision.decisionId,
+    usage.inputTokens,
+    usage.outputTokens,
+    { partial },
+  );
+}
+
+export async function recordFrameworkReceipt(
+  guard: SpendGuard,
+  framework: string,
+  receipt: Record<string, unknown>,
+): Promise<{ decision: SpendDecision; signed: SignedDecisionLogEntry | null }> {
+  return guard.recordOutcomeReceipt({
+    type: 'framework_adapter',
+    framework,
+    totalCostCents: safeInteger(receipt.totalCostCents),
+    ...sanitizeMetadata(redactDataPlane(receipt) as Record<string, unknown>),
+  });
+}
+
+export function usageFromResult(result: unknown): { inputTokens: number; outputTokens: number } | null {
+  const candidates = [
+    objectRecord(result)?.usage,
+    objectRecord(objectRecord(result)?.response)?.usage,
+    objectRecord(objectRecord(result)?.rawResponse)?.usage,
+  ];
+  for (const candidate of candidates) {
+    const usage = objectRecord(candidate);
+    if (!usage) continue;
+    const input = firstInteger(usage.inputTokens, usage.promptTokens, usage.prompt_tokens, usage.input_tokens);
+    const output = firstInteger(usage.outputTokens, usage.completionTokens, usage.completion_tokens, usage.output_tokens);
+    if (input !== null && output !== null) return { inputTokens: input, outputTokens: output };
+  }
+  return null;
+}
+
+export function objectRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+export function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function firstInteger(...values: unknown[]): number | null {
+  for (const value of values) {
+    if (Number.isSafeInteger(value) && (value as number) >= 0) return value as number;
+  }
+  return null;
+}
+
+function safeInteger(value: unknown): number {
+  return Number.isSafeInteger(value) && (value as number) >= 0 ? value as number : 0;
+}
+
+function stableJson(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/frameworks/hermes.ts

@@ -0,0 +1,83 @@
+import type { SpendGuard } from '../spend-guard';
+import { createFrameworkGuard, recordFrameworkReceipt, redactDataPlane, safeRequestShape, stringValue, type FrameworkAdapterOptions } from './common';
+
+export interface HermesToolEvent {
+  toolName?: string;
+  name?: string;
+  args?: Record<string, unknown>;
+  toolArgs?: Record<string, unknown>;
+  workflowId?: string;
+  sessionId?: string;
+  metadata?: Record<string, unknown>;
+  result?: Record<string, unknown>;
+}
+
+export interface HermesHookResult {
+  allow: boolean;
+  approved?: boolean;
+  reason?: string;
+  receiptId?: string;
+  editedArgs?: Record<string, unknown>;
+}
+
+export interface HermesPlugin {
+  name: 'agentguard-spend';
+  guard: SpendGuard;
+  hooks: {
+    'pre-tool-call': (event: HermesToolEvent) => Promise<HermesHookResult>;
+    approval: (event: HermesToolEvent) => Promise<HermesHookResult>;
+    'post-tool-call': (event: HermesToolEvent) => Promise<HermesHookResult>;
+  };
+  preToolCall(event: HermesToolEvent): Promise<HermesHookResult>;
+  approval(event: HermesToolEvent): Promise<HermesHookResult>;
+  postToolCall(event: HermesToolEvent): Promise<HermesHookResult>;
+}
+
+export function createHermesPlugin(opts: FrameworkAdapterOptions): HermesPlugin {
+  const guard = createFrameworkGuard({ ...opts, framework: 'hermes' });
+  const plugin: HermesPlugin = {
+    name: 'agentguard-spend',
+    guard,
+    hooks: {
+      'pre-tool-call': (event) => preToolCall(guard, opts, event),
+      approval: (event) => approval(guard, opts, event),
+      'post-tool-call': (event) => postToolCall(guard, event),
+    },
+    preToolCall: (event) => preToolCall(guard, opts, event),
+    approval: (event) => approval(guard, opts, event),
+    postToolCall: (event) => postToolCall(guard, event),
+  };
+  return plugin;
+}
+
+export const agentguardHermesPlugin = createHermesPlugin;
+
+async function preToolCall(guard: SpendGuard, opts: FrameworkAdapterOptions, event: HermesToolEvent): Promise<HermesHookResult> {
+  const gate = await guard.guardToolCall({
+    toolName: toolName(event),
+    toolArgs: safeRequestShape(redactDataPlane(event.toolArgs ?? event.args ?? {})),
+    workflowId: event.workflowId ?? event.sessionId,
+    scope: opts.scope,
+  });
+  if (!gate.approved) return { allow: false, approved: false, reason: gate.decision.reasons.join('; ') };
+  return { allow: true, approved: true, editedArgs: gate.editedArgs };
+}
+
+async function approval(guard: SpendGuard, opts: FrameworkAdapterOptions, event: HermesToolEvent): Promise<HermesHookResult> {
+  return preToolCall(guard, opts, event);
+}
+
+async function postToolCall(guard: SpendGuard, event: HermesToolEvent): Promise<HermesHookResult> {
+  const { decision } = await recordFrameworkReceipt(guard, 'hermes', {
+    event: 'post-tool-call',
+    toolName: toolName(event),
+    workflowId: event.workflowId ?? event.sessionId ?? null,
+    metadata: redactDataPlane(event.metadata ?? {}),
+    result: redactDataPlane(event.result ?? {}),
+  });
+  return { allow: true, approved: true, receiptId: decision.decisionId };
+}
+
+function toolName(event: HermesToolEvent): string {
+  return stringValue(event.toolName) ?? stringValue(event.name) ?? 'unknown_tool';
+}

package/src/frameworks/index.ts

@@ -0,0 +1,5 @@
+export * from './common';
+export * from './openrouter';
+export * from './vercel-ai';
+export * from './claude-code';
+export * from './hermes';

package/src/frameworks/openrouter.ts

@@ -0,0 +1,90 @@
+import { withSpendGuard, type OpenAIBindingOptions, type SpendGuardConfig } from '../spend-guard';
+import type { CapabilityTier, SpendPolicy, SpendScope } from '../types';
+import { createFrameworkGuard, preflightFrameworkCall, settleFrameworkCall, type FrameworkAdapterOptions } from './common';
+
+export interface OpenRouterBindingOptions {
+  policy: SpendPolicy;
+  scope: SpendScope;
+  capabilityClaim?: CapabilityTier;
+  config?: Omit<SpendGuardConfig, 'policy'>;
+  licenseKey?: string;
+  openRouterBaseUrl?: string;
+}
+
+export function withSpendGuardOpenRouter<TClient>(client: TClient, opts: OpenRouterBindingOptions): TClient {
+  const config = {
+    ...(opts.config ?? {}),
+    openRouterBaseUrl: opts.openRouterBaseUrl ?? opts.config?.openRouterBaseUrl ?? 'https://openrouter.ai/api/v1',
+    providerRoute: opts.config?.providerRoute ?? 'openrouter',
+  } as Omit<SpendGuardConfig, 'policy'>;
+  return withSpendGuard(client, {
+    policy: opts.policy,
+    scope: opts.scope,
+    capabilityClaim: opts.capabilityClaim,
+    licenseKey: opts.licenseKey,
+    config,
+  } satisfies OpenAIBindingOptions) as TClient;
+}
+
+export function withOpenRouterSpendGuard<TClient>(client: TClient, opts: OpenRouterBindingOptions): TClient {
+  return withSpendGuardOpenRouter(client, opts);
+}
+
+export interface OpenRouterFetchOptions extends FrameworkAdapterOptions {
+  fetchImpl?: (url: string, init?: Record<string, unknown>) => Promise<unknown>;
+  endpoint?: string;
+}
+
+export function createOpenRouterFetch(opts: OpenRouterFetchOptions): (url: string, init?: Record<string, unknown>) => Promise<unknown> {
+  const guard = createFrameworkGuard({ ...opts, defaultModel: opts.defaultModel ?? 'openrouter/auto', framework: 'openrouter' });
+  const fetchImpl = opts.fetchImpl ?? (globalThis as unknown as { fetch?: (url: string, init?: Record<string, unknown>) => Promise<unknown> }).fetch;
+  if (!fetchImpl) throw new Error('createOpenRouterFetch: fetch is not available');
+  const endpoint = opts.endpoint ?? 'https://openrouter.ai/api/v1/chat/completions';
+
+  return async (url: string, init: Record<string, unknown> = {}) => {
+    const target = String(url);
+    if (!target.startsWith(endpoint)) return fetchImpl(target, init);
+    const body = parseJsonBody(init.body);
+    const preflight = await preflightFrameworkCall(guard, opts, {
+      framework: 'openrouter',
+      model: typeof body.model === 'string' ? body.model : opts.defaultModel ?? 'openrouter/auto',
+      params: body,
+      metadata: metadataRecord(body.metadata),
+      requestShape: {
+        endpoint: '/api/v1/chat/completions',
+        stream: body.stream === true,
+        maxTokens: typeof body.max_tokens === 'number' ? body.max_tokens : undefined,
+        toolCount: Array.isArray(body.tools) ? body.tools.length : 0,
+      },
+    });
+    const nextBody = preflight.decision.action === 'downgrade' && preflight.decision.modelResolved !== preflight.decision.modelRequested
+      ? { ...body, model: preflight.decision.modelResolved }
+      : body;
+    const response = await fetchImpl(target, { ...init, body: JSON.stringify(nextBody) });
+    await settleFrameworkCall(preflight, await responseJson(response));
+    return response;
+  };
+}
+
+function parseJsonBody(body: unknown): Record<string, unknown> {
+  if (typeof body === 'string') {
+    try { return JSON.parse(body) as Record<string, unknown>; } catch { return {}; }
+  }
+  if (body && typeof body === 'object' && !Array.isArray(body)) return body as Record<string, unknown>;
+  return {};
+}
+
+function metadataRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+async function responseJson(response: unknown): Promise<unknown> {
+  const maybe = response as { clone?: () => { json?: () => Promise<unknown> }; json?: () => Promise<unknown> };
+  try {
+    if (typeof maybe.clone === 'function') return await maybe.clone().json?.();
+    if (typeof maybe.json === 'function') return await maybe.json();
+  } catch {
+    return null;
+  }
+  return null;
+}

package/src/frameworks/vercel-ai.ts

@@ -0,0 +1,118 @@
+import type { SpendGuard } from '../spend-guard';
+import { createFrameworkGuard, modelFromUnknown, objectRecord, preflightFrameworkCall, recordFrameworkReceipt, redactDataPlane, settleFrameworkCall, type FrameworkAdapterOptions, type FrameworkPreflight } from './common';
+
+export type AgentGuardAiSdkMiddleware = {
+  specificationVersion: 'v3';
+  transformParams?: (args: { type: 'generate' | 'stream'; params: unknown; model: unknown }) => Promise<unknown> | unknown;
+  wrapGenerate?: (args: { doGenerate: () => Promise<unknown>; doStream?: () => Promise<unknown>; params: unknown; model: unknown }) => Promise<unknown>;
+  wrapStream?: (args: { doGenerate?: () => Promise<unknown>; doStream: () => Promise<unknown>; params: unknown; model: unknown }) => Promise<unknown>;
+};
+
+export interface AgentGuardAiSdkOptions extends FrameworkAdapterOptions {
+  framework?: 'vercel-ai-sdk';
+}
+
+export function agentguardAiSdkMiddleware(opts: AgentGuardAiSdkOptions): AgentGuardAiSdkMiddleware {
+  const guard = createFrameworkGuard({ ...opts, framework: 'vercel-ai-sdk' });
+  return {
+    specificationVersion: 'v3',
+    transformParams: ({ params }) => params,
+    wrapGenerate: async ({ doGenerate, params, model }) => {
+      const preflight = await aiSdkPreflight(guard, opts, params, model, 'generate');
+      const result = await doGenerate();
+      await settleFrameworkCall(preflight, result);
+      await recordFrameworkReceipt(guard, 'vercel-ai-sdk', {
+        event: 'post_generate',
+        decisionId: preflight.decision.decisionId,
+        model: preflight.decision.modelResolved,
+        requestShape: requestShape(params, 'generate'),
+        hasUsage: Boolean(objectRecord(result)?.usage),
+      });
+      return result;
+    },
+    wrapStream: async ({ doStream, params, model }) => {
+      const preflight = await aiSdkPreflight(guard, opts, params, model, 'stream');
+      const result = await doStream();
+      return wrapAiSdkStreamResult(guard, preflight, result, params);
+    },
+  };
+}
+
+export const agentguard = agentguardAiSdkMiddleware;
+
+async function aiSdkPreflight(
+  guard: SpendGuard,
+  opts: AgentGuardAiSdkOptions,
+  params: unknown,
+  model: unknown,
+  type: 'generate' | 'stream',
+): Promise<FrameworkPreflight> {
+  return preflightFrameworkCall(guard, opts, {
+    framework: 'vercel-ai-sdk',
+    model: modelFromUnknown(model, opts.defaultModel ?? 'unknown'),
+    params,
+    metadata: agentguardMetadata(params),
+    requestShape: requestShape(params, type),
+  });
+}
+
+function requestShape(params: unknown, type: 'generate' | 'stream'): Record<string, unknown> {
+  const record = objectRecord(params) ?? {};
+  const tools = objectRecord(record.tools) ?? {};
+  return {
+    type,
+    maxOutputTokens: record.maxOutputTokens ?? record.maxTokens,
+    toolNames: Object.keys(tools).sort(),
+    providerOptionsPresent: Boolean(record.providerOptions),
+    redacted: redactDataPlane({ prompt: record.prompt, messages: record.messages }),
+  };
+}
+
+function agentguardMetadata(params: unknown): Record<string, unknown> {
+  const record = objectRecord(params) ?? {};
+  const providerOptions = objectRecord(record.providerOptions) ?? objectRecord(record.providerMetadata) ?? {};
+  const metadata = objectRecord(providerOptions.agentguard) ?? {};
+  return metadata;
+}
+
+async function wrapAiSdkStreamResult(
+  guard: SpendGuard,
+  preflight: FrameworkPreflight,
+  result: unknown,
+  params: unknown,
+): Promise<unknown> {
+  const record = objectRecord(result);
+  const stream = record?.stream;
+  if (!stream || typeof (stream as { pipeThrough?: unknown }).pipeThrough !== 'function') {
+    await settleFrameworkCall(preflight, result, true);
+    await recordFrameworkReceipt(guard, 'vercel-ai-sdk', {
+      event: 'post_stream',
+      decisionId: preflight.decision.decisionId,
+      model: preflight.decision.modelResolved,
+      requestShape: requestShape(params, 'stream'),
+      partial: true,
+    });
+    return result;
+  }
+  const TransformStreamCtor = (globalThis as unknown as { TransformStream?: new (handlers: Record<string, unknown>) => unknown }).TransformStream;
+  if (!TransformStreamCtor) return result;
+  let finalUsage: unknown = null;
+  const transform = new TransformStreamCtor({
+    transform(chunk: unknown, controller: { enqueue: (chunk: unknown) => void }) {
+      const usage = objectRecord(chunk)?.usage;
+      if (usage) finalUsage = { usage };
+      controller.enqueue(chunk);
+    },
+    async flush() {
+      await settleFrameworkCall(preflight, finalUsage ?? result);
+      await recordFrameworkReceipt(guard, 'vercel-ai-sdk', {
+        event: 'post_stream',
+        decisionId: preflight.decision.decisionId,
+        model: preflight.decision.modelResolved,
+        requestShape: requestShape(params, 'stream'),
+        partial: false,
+      });
+    },
+  });
+  return { ...record, stream: (stream as { pipeThrough: (transform: unknown) => unknown }).pipeThrough(transform) };
+}

package/src/receipts/dag.ts

@@ -192,6 +192,7 @@ export async function verifyReceiptDag(
           entryHash: node.entryHash,
           signature: node.signature,
           signerFingerprint: node.signerFingerprint,
+          builderCode: node.builderCode ?? undefined,
         },
         publicKey,
       );
@@ -348,6 +349,7 @@ function normalizeDagNode(input: ReceiptDagInput): NormalizedDagNode {
     entryHash: candidate.entryHash,
     signature: candidate.signature,
     signerFingerprint: candidate.signerFingerprint,
+    builderCode: candidate.builderCode ?? null,
     timestamp: stringOrNull(decision.timestamp) ?? new Date(0).toISOString(),
     previousHash,
     legacyPreviousHash: previousHash,