@agentguard-run/spend 0.2.2 → 0.4.0

package/src/bindings/bedrock.ts

@@ -0,0 +1,200 @@
+/** Native AWS Bedrock binding for AgentGuard Spend. */
+
+import type { CapabilityTier, CallContext, Provider, SpendPolicy, SpendScope } from '../types';
+import {
+  AgentGuardBlockedError,
+  SpendGuard,
+  type SpendGuardConfig,
+  extractText,
+  usageCountsFromObject,
+  wrapUsageStream,
+  type UsageCounts,
+} from '../spend-guard';
+
+export interface BedrockBindingOptions {
+  policy: SpendPolicy;
+  scope: SpendScope;
+  capabilityClaim?: CapabilityTier;
+  config?: Omit<SpendGuardConfig, 'policy'>;
+}
+
+type BedrockCommand = {
+  input?: Record<string, unknown>;
+  constructor?: { name?: string };
+};
+
+export function withSpendGuardBedrock(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  client: any,
+  opts: BedrockBindingOptions,
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any {
+  const guard = new SpendGuard({ policy: opts.policy, ...(opts.config ?? {}) });
+  const originalSend = client?.send?.bind(client);
+  if (!originalSend) throw new Error('withSpendGuardBedrock: expected client.send');
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  client.send = async (command: BedrockCommand, ...args: any[]) => {
+    if (!isInvokeModelCommand(command)) return originalSend(command, ...args);
+
+    const call = buildBedrockCall(command, guard, opts);
+    const { decision } = await guard.decide(call);
+    if (decision.action === 'block') throw new AgentGuardBlockedError(decision, opts.scope, opts.config?.locale);
+
+    if (decision.action === 'downgrade' && decision.modelResolved !== decision.modelRequested && command.input) {
+      command.input = { ...command.input, modelId: decision.modelResolved };
+    }
+
+    const response = await originalSend(command, ...args);
+    if (isStreamingCommand(command) && response?.body) {
+      return {
+        ...response,
+        body: wrapBedrockStream(response.body, guard, decision.decisionId, call),
+      };
+    }
+
+    const usage = extractBedrockResponseUsage(response, call.model);
+    if (usage) await guard.settleStreamUsage(decision.decisionId, usage.inputTokens, usage.outputTokens);
+    return response;
+  };
+
+  client.__agentguard = guard;
+  return client;
+}
+
+function isInvokeModelCommand(command: BedrockCommand): boolean {
+  const name = command?.constructor?.name;
+  return name === 'InvokeModelCommand' || name === 'InvokeModelWithResponseStreamCommand';
+}
+
+function isStreamingCommand(command: BedrockCommand): boolean {
+  return command?.constructor?.name === 'InvokeModelWithResponseStreamCommand';
+}
+
+function buildBedrockCall(command: BedrockCommand, guard: SpendGuard, opts: BedrockBindingOptions): CallContext {
+  const input = command.input ?? {};
+  const modelId = String(input.modelId ?? 'unknown');
+  const body = parseJsonBody(input.body);
+  const inputText = extractText(body);
+  return {
+    provider: 'bedrock' as Provider,
+    model: modelId,
+    inputTokens: guard.estimateTokens(inputText),
+    outputTokens: outputTokensFromBody(body),
+    scope: opts.scope,
+    capabilityClaim: opts.capabilityClaim,
+  };
+}
+
+function wrapBedrockStream(
+  stream: AsyncIterable<unknown>,
+  guard: SpendGuard,
+  decisionId: string,
+  call: CallContext,
+): AsyncIterable<unknown> {
+  const tracker = new BedrockStreamUsageTracker(guard, call);
+  return wrapUsageStream(stream, {
+    onChunk: (event) => tracker.observe(event),
+    settle: (partial, reason) => {
+      const usage = tracker.usage();
+      return guard.settleStreamUsage(decisionId, usage.inputTokens, usage.outputTokens, { partial, reason });
+    },
+  });
+}
+
+class BedrockStreamUsageTracker {
+  private input: number | null = null;
+  private output: number | null = null;
+  private content = '';
+
+  constructor(private guard: SpendGuard, private call: CallContext) {}
+
+  observe(event: unknown): void {
+    const payload = bedrockEventPayload(event);
+    if (!payload) return;
+    const usage = usageFromBedrockPayload(payload);
+    if (usage) {
+      this.input = usage.inputTokens;
+      this.output = usage.outputTokens;
+    }
+    this.content += textFromBedrockPayload(payload);
+  }
+
+  usage(): UsageCounts {
+    return {
+      inputTokens: this.input ?? this.call.inputTokens,
+      outputTokens: this.output ?? this.guard.estimateTokens(this.content),
+    };
+  }
+}
+
+function extractBedrockResponseUsage(response: unknown, modelId: string): UsageCounts | null {
+  const body = (response as { body?: unknown } | null)?.body;
+  const parsed = parseJsonBody(body);
+  const usage = usageFromBedrockPayload(parsed);
+  if (usage) return usage;
+  if (modelId.startsWith('amazon.nova.')) return usageCountsFromObject((parsed as Record<string, unknown> | null)?.usage);
+  return null;
+}
+
+function usageFromBedrockPayload(payload: unknown): UsageCounts | null {
+  if (!payload || typeof payload !== 'object') return null;
+  const obj = payload as Record<string, unknown>;
+  const direct = usageCountsFromObject(obj.usage);
+  if (direct) return direct;
+
+  const bedrockMetrics = obj['amazon-bedrock-invocationMetrics'];
+  if (bedrockMetrics && typeof bedrockMetrics === 'object') {
+    const metrics = bedrockMetrics as Record<string, unknown>;
+    const input = metrics.inputTokenCount;
+    const output = metrics.outputTokenCount;
+    if (Number.isSafeInteger(input) && Number.isSafeInteger(output)) {
+      return { inputTokens: input as number, outputTokens: output as number };
+    }
+  }
+
+  const nested = usageCountsFromObject((obj.message as Record<string, unknown> | undefined)?.usage);
+  if (nested) return nested;
+  return null;
+}
+
+function textFromBedrockPayload(payload: unknown): string {
+  if (!payload || typeof payload !== 'object') return '';
+  const obj = payload as Record<string, unknown>;
+  const delta = obj.delta as Record<string, unknown> | undefined;
+  if (typeof delta?.text === 'string') return delta.text;
+  const contentBlockDelta = obj.contentBlockDelta as Record<string, unknown> | undefined;
+  const nestedDelta = contentBlockDelta?.delta as Record<string, unknown> | undefined;
+  if (typeof nestedDelta?.text === 'string') return nestedDelta.text;
+  const output = obj.output as Record<string, unknown> | undefined;
+  if (output) return extractText(output);
+  return '';
+}
+
+function outputTokensFromBody(body: unknown): number {
+  if (!body || typeof body !== 'object') return 512;
+  const obj = body as Record<string, unknown>;
+  const value = obj.max_tokens ?? obj.maxTokens ?? obj.max_new_tokens ??
+    (obj.inferenceConfig as Record<string, unknown> | undefined)?.maxTokens;
+  return Number.isSafeInteger(value) && (value as number) >= 0 ? value as number : 512;
+}
+
+function parseJsonBody(body: unknown): unknown {
+  if (!body) return {};
+  try {
+    if (typeof body === 'string') return JSON.parse(body);
+    if (body instanceof Uint8Array) return JSON.parse(new TextDecoder().decode(body));
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(body)) return JSON.parse(body.toString('utf8'));
+    if (typeof body === 'object') return body;
+  } catch {
+    return {};
+  }
+  return {};
+}
+
+function bedrockEventPayload(event: unknown): unknown {
+  const obj = event as Record<string, unknown> | null;
+  const chunk = obj?.chunk as Record<string, unknown> | undefined;
+  const bytes = chunk?.bytes ?? chunk?.payload ?? obj?.payload;
+  return parseJsonBody(bytes);
+}

package/src/cli/auth.ts

@@ -0,0 +1,145 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as http from 'http';
+import * as https from 'https';
+import * as path from 'path';
+import * as readline from 'readline';
+import { AGENTGUARD_SPEND_VERSION } from '../index';
+import { agentguardHome, banner, dim, green, statusBar, yellow } from './colors';
+
+const OPENROUTER_AUTH_URL = 'https://openrouter.ai/api/v1/auth/key';
+
+export function openRouterKeyPath(): string {
+  return path.join(agentguardHome(), 'openrouter-key');
+}
+
+export function keyFingerprint(key: string): string {
+  return crypto.createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+
+export async function validateOpenRouterKey(key: string, endpoint = process.env.AGENTGUARD_OPENROUTER_AUTH_URL || OPENROUTER_AUTH_URL): Promise<boolean> {
+  if (!key.trim()) return false;
+  if (endpoint.startsWith('mock://')) {
+    const expected = new URL(endpoint).searchParams.get('key');
+    return expected === key.trim();
+  }
+  try {
+    const status = await requestStatus(endpoint, key.trim());
+    return status >= 200 && status < 300;
+  } catch {
+    return false;
+  }
+}
+
+export function readOpenRouterKey(): string | null {
+  if (process.env.OPENROUTER_API_KEY) return process.env.OPENROUTER_API_KEY;
+  try {
+    const value = fs.readFileSync(openRouterKeyPath(), 'utf8').trim();
+    return value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeOpenRouterKey(key: string): void {
+  const filePath = openRouterKeyPath();
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, key.trim() + '\n', { mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch { return; }
+}
+
+export async function runAuth(argv: string[]): Promise<number> {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('agentguard auth openrouter | status | clear openrouter');
+    return 0;
+  }
+  const sub = argv[0] ?? 'status';
+  if (sub === 'status') return authStatus();
+  if (sub === 'clear' && argv[1] === 'openrouter') return clearOpenRouter();
+  if (sub === 'openrouter') return configureOpenRouter(argv);
+  console.error(`agentguard auth: unknown command '${argv.join(' ')}'`);
+  return 2;
+}
+
+async function configureOpenRouter(argv: string[]): Promise<number> {
+  const flagKey = valueAfter(argv, '--key');
+  const key = flagKey ?? await promptForKey();
+  if (!key) {
+    console.error('No key provided.');
+    return 2;
+  }
+  const ok = await validateOpenRouterKey(key);
+  if (!ok) {
+    console.error('OpenRouter key validation failed.');
+    return 1;
+  }
+  writeOpenRouterKey(key);
+  console.log('');
+  console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+  console.log('');
+  console.log(`  ${green('configured')} openrouter  fingerprint ${keyFingerprint(key)}`);
+  console.log(`  ${dim('saved')} ${openRouterKeyPath()}`);
+  console.log('');
+  return 0;
+}
+
+function authStatus(): number {
+  const key = readOpenRouterKey();
+  console.log('');
+  console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+  console.log('');
+  if (key) {
+    console.log(`  ${green('openrouter')} configured  fingerprint ${keyFingerprint(key)}`);
+  } else {
+    console.log(`  ${yellow('openrouter')} not configured`);
+  }
+  console.log('');
+  console.log('  ' + statusBar());
+  console.log('');
+  return 0;
+}
+
+function clearOpenRouter(): number {
+  try { fs.unlinkSync(openRouterKeyPath()); } catch { return 0; }
+  console.log('OpenRouter key removed.');
+  return 0;
+}
+
+async function promptForKey(): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question('OpenRouter API key: ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function requestStatus(endpoint: string, key: string): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const url = new URL(endpoint);
+    const client = url.protocol === 'http:' ? http : https;
+    const req = client.request(
+      {
+        method: 'GET',
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname + url.search,
+        headers: { authorization: `Bearer ${key}`, accept: 'application/json' },
+        timeout: 5000,
+      },
+      (res) => {
+        res.resume();
+        res.on('end', () => resolve(res.statusCode ?? 0));
+      },
+    );
+    req.on('error', reject);
+    req.on('timeout', () => req.destroy(new Error('OpenRouter auth validation timed out')));
+    req.end();
+  });
+}
+
+function valueAfter(argv: string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : undefined;
+}

package/src/cli/coach.ts

@@ -0,0 +1,249 @@
+/**
+ * `agentguard coach`: local LLM-driven policy setup.
+ */
+
+import * as readline from 'readline';
+import { AGENTGUARD_SPEND_VERSION } from '../index';
+import { CoachConversation, formatCents } from '../coach/conversation';
+import { forecastMonthEnd } from '../coach/forecast';
+import { createCoachClient, resolveCoachApiKey, type CoachChatMessage, type CoachProvider } from '../coach/llm-client';
+import { readDecisionSpend, reviewAnomalies } from '../coach/anomaly';
+import { MASTER_SYSTEM_PROMPT } from '../coach/system-prompt';
+import { createCoachSessionLogger, writeCoachOutputs } from '../coach/output';
+import { banner, cyanBold, dim, green, yellow } from './colors';
+
+interface CoachCliOptions {
+  provider: CoachProvider;
+  baseUrl?: string;
+  model?: string;
+  language?: 'ts' | 'py';
+  defaults: boolean;
+  yes: boolean;
+}
+
+const HELP = `agentguard coach: local LLM-driven policy setup
+
+usage:
+  agentguard coach [--provider openrouter|openai|anthropic|compatible] [--base-url <url>] [--model <model>]
+  agentguard coach review [--scope <name>]
+  agentguard coach forecast [--scope <name>] [--cap-cents <cents>]
+
+examples:
+  agentguard auth openrouter
+  agentguard coach
+  agentguard coach --base-url https://api.deepseek.com/v1 --model deepseek-chat
+  agentguard coach review
+`;
+
+export async function runCoach(argv: string[]): Promise<number> {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(HELP);
+    return 0;
+  }
+  if (argv[0] === 'review') return runCoachReview(argv.slice(1));
+  if (argv[0] === 'forecast') return runCoachForecast(argv.slice(1));
+
+  const options = parseOptions(argv);
+  const apiKey = resolveCoachApiKey(options.provider);
+  if (options.provider !== 'mock' && !apiKey) {
+    console.log('');
+    console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+    console.log('');
+    console.log(`  ${yellow('agentguard coach needs a local provider key')}`);
+    console.log('  Run agentguard auth openrouter, set OPENROUTER_API_KEY, or pass --base-url with AGENTGUARD_COACH_API_KEY.');
+    console.log('  Prompts and policy details stay in your terminal and go only to your chosen provider.');
+    console.log('');
+    return 0;
+  }
+
+  let cancelled = false;
+  const logger = createCoachSessionLogger();
+  const onSigint = () => {
+    cancelled = true;
+    logger.append('cancelled', { reason: 'sigint' });
+    process.stdout.write('\ncoach cancelled. No policy files were written.\n');
+  };
+  process.once('SIGINT', onSigint);
+
+  try {
+    const conversation = new CoachConversation(options.language ? { language: options.language } : undefined);
+    const history: CoachChatMessage[] = [{ role: 'system', content: MASTER_SYSTEM_PROMPT }];
+    const client = createCoachClient({ provider: options.provider, baseUrl: options.baseUrl, model: options.model, apiKey: apiKey ?? undefined });
+
+    console.log('');
+    console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+    console.log('');
+    console.log(cyanBold('AgentGuard Coach'));
+    console.log(dim('Local LLM setup. No AgentGuard service receives prompts, completions, keys, or policies.'));
+    console.log('');
+
+    if (options.defaults || !process.stdin.isTTY) {
+      fillDefaults(conversation);
+      logger.append('answers_defaulted', { answers: conversation.snapshot() });
+    } else {
+      await runInteractiveQuestions(conversation, logger, history, client, () => cancelled);
+    }
+
+    if (cancelled) return 130;
+    if (!conversation.isComplete()) {
+      console.log(yellow('coach did not collect enough answers to write policy files.'));
+      return 0;
+    }
+
+    const profile = conversation.profile(process.cwd());
+    if (options.language) profile.language = options.language;
+    logger.append('profile_built', { profile });
+
+    console.log('');
+    await streamCoachSummary(client, history, profileSummaryPrompt(profile), logger, () => cancelled);
+    if (cancelled) return 130;
+
+    const outputs = writeCoachOutputs(profile, { language: profile.language, overwrite: options.yes || options.defaults });
+    logger.append('files_written', { policyPath: outputs.policyPath, quickstartPath: outputs.quickstartPath, sessionLogPath: logger.path });
+
+    console.log('');
+    console.log(outputs.savingsTable);
+    console.log('');
+    console.log(`${green('created')} ${outputs.policyPath}`);
+    console.log(`${green('created')} ${outputs.quickstartPath}`);
+    console.log(`${green('session')} ${logger.path}`);
+    console.log('');
+    console.log('Next: agentguard demo --policy ~/.agentguard/policy.yaml');
+    console.log('Verify receipts: https://agentguard.run/verify');
+    console.log('');
+    return 0;
+  } finally {
+    process.removeListener('SIGINT', onSigint);
+  }
+}
+
+async function runCoachReview(argv: string[]): Promise<number> {
+  const scope = valueAfter(argv, '--scope') ?? 'default';
+  const anomalies = reviewAnomalies(readDecisionSpend(scope));
+  console.log('');
+  console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+  console.log('');
+  if (anomalies.length === 0) {
+    console.log('No local spend anomalies found for the last 24 hours.');
+    return 0;
+  }
+  for (const item of anomalies) {
+    console.log(`${item.scope}/${item.agentId}: ${formatCents(item.last24hCents)} in last 24h. Baseline ${formatCents(item.baselineCents)}, sigma ${formatCents(item.sigmaCents)}.`);
+    console.log(`Suggestion: ${item.suggestion}`);
+  }
+  return 0;
+}
+
+async function runCoachForecast(argv: string[]): Promise<number> {
+  const scope = valueAfter(argv, '--scope') ?? 'default';
+  const cap = valueAfter(argv, '--cap-cents');
+  const forecast = forecastMonthEnd(readDecisionSpend(scope), cap ? Number(cap) : null);
+  console.log('');
+  console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+  console.log('');
+  console.log(`Days observed: ${forecast.daysObserved}`);
+  console.log(`Projected month-end: ${formatCents(forecast.monthEndCents)}`);
+  if (forecast.capCents !== null) console.log(`Cap: ${formatCents(forecast.capCents)}`);
+  console.log(forecast.message);
+  return 0;
+}
+
+async function runInteractiveQuestions(
+  conversation: CoachConversation,
+  logger: ReturnType<typeof createCoachSessionLogger>,
+  history: CoachChatMessage[],
+  client: ReturnType<typeof createCoachClient>,
+  isCancelled: () => boolean,
+): Promise<void> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (prompt: string) => new Promise<string>((resolve) => rl.question(`${prompt}\n> `, resolve));
+  try {
+    while (!conversation.isComplete() && !isCancelled()) {
+      const question = conversation.currentQuestion();
+      if (!question) break;
+      const answer = (await ask(question.prompt)).trim();
+      if (answer.toLowerCase() === 'back') {
+        conversation.back();
+        logger.append('back', { to: conversation.currentQuestion()?.id });
+        continue;
+      }
+      if (!answer) continue;
+      conversation.answer(answer);
+      logger.append('answer', { question: question.id, answer });
+      history.push({ role: 'user', content: `${question.prompt}\n${answer}` });
+      await streamCoachSummary(client, history, coachQuestionPrompt(question.id), logger, isCancelled);
+      conversation.next();
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+async function streamCoachSummary(
+  client: ReturnType<typeof createCoachClient>,
+  history: CoachChatMessage[],
+  prompt: string,
+  logger: ReturnType<typeof createCoachSessionLogger>,
+  isCancelled: () => boolean,
+): Promise<void> {
+  history.push({ role: 'user', content: prompt });
+  let content = '';
+  process.stdout.write('\n');
+  try {
+    for await (const token of client.streamChat(history)) {
+      if (isCancelled()) break;
+      content += token;
+      process.stdout.write(token);
+    }
+    process.stdout.write('\n');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    content = `Coach provider unavailable: ${message}`;
+    console.log(content);
+  }
+  history.push({ role: 'assistant', content });
+  logger.append('assistant', { content });
+}
+
+function fillDefaults(conversation: CoachConversation): void {
+  const answers = [
+    'A customer support agent for an ecommerce business',
+    'Team of 5, around 2000 support tickets and orders per month',
+    'triage refunds, draft support replies, assemble chargeback evidence',
+    '$199 monthly budget with low per-call costs',
+    'Confirmed',
+  ];
+  for (const answer of answers) {
+    if (!conversation.currentQuestion()) break;
+    conversation.answer(answer);
+    conversation.next();
+  }
+}
+
+function coachQuestionPrompt(id: string): string {
+  return `Acknowledge the ${id} answer in 2 short sentences. Ask only the next unanswered setup question. Do not write files yet.`;
+}
+
+function profileSummaryPrompt(profile: ReturnType<CoachConversation['profile']>): string {
+  return `Prepare a concise final setup summary for this profile before files are written: ${JSON.stringify(profile)}. Include projected savings math in words. Do not invent model names or pricing.`;
+}
+
+function parseOptions(argv: string[]): CoachCliOptions {
+  const baseUrl = valueAfter(argv, '--base-url');
+  const providerFlag = valueAfter(argv, '--provider') as CoachProvider | undefined;
+  const provider = providerFlag ?? (baseUrl ? 'compatible' : 'openrouter');
+  const language = valueAfter(argv, '--language') as 'ts' | 'py' | undefined;
+  return {
+    provider,
+    baseUrl,
+    model: valueAfter(argv, '--model'),
+    language: language === 'py' ? 'py' : language === 'ts' ? 'ts' : undefined,
+    defaults: argv.includes('--defaults'),
+    yes: argv.includes('--yes') || argv.includes('-y'),
+  };
+}
+
+function valueAfter(argv: string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : undefined;
+}