@agentguard-run/spend 0.13.1 → 0.13.2

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) };
+}