@agentguard-run/spend 0.2.2 → 0.4.0

package/src/cli/models.ts

@@ -0,0 +1,236 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { AGENTGUARD_SPEND_VERSION } from '../index';
+import { fetchCatalog, getCachedCatalog, syncPricingIntoCostTable, type OpenRouterModel } from '../openrouter-catalog';
+import { getModelCost, knownModelCosts } from '../cost-table';
+import { TASK_TEMPLATES, getTaskTemplate } from '../templates';
+import { agentguardHome, banner, cyanBold, dim, green, statusBar, yellow } from './colors';
+
+export interface ModelRow {
+  id: string;
+  name: string;
+  inputCentsPerMtok: number | null;
+  outputCentsPerMtok: number | null;
+  capability: string;
+}
+
+export function rowsFromCatalog(models: OpenRouterModel[]): ModelRow[] {
+  return models.map((model) => {
+    const input = Number(model.pricing?.prompt);
+    const output = Number(model.pricing?.completion);
+    return {
+      id: model.id,
+      name: model.name ?? model.id,
+      inputCentsPerMtok: Number.isFinite(input) ? input * 100 * 1_000_000 : null,
+      outputCentsPerMtok: Number.isFinite(output) ? output * 100 * 1_000_000 : null,
+      capability: capabilityForModel(model.id),
+    };
+  });
+}
+
+export function rowsFromCostTable(): ModelRow[] {
+  return Object.entries(knownModelCosts()).map(([id, cost]) => ({
+    id,
+    name: id,
+    inputCentsPerMtok: cost.inputCentsPerKtok * 1000,
+    outputCentsPerMtok: cost.outputCentsPerKtok * 1000,
+    capability: capabilityForModel(id),
+  }));
+}
+
+export function filterRows(rows: ModelRow[], opts: { search?: string; capability?: string; task?: string }): ModelRow[] {
+  let out = rows;
+  if (opts.task) {
+    const template = getTaskTemplate(opts.task);
+    if (template) {
+      const allowed = new Set(template.allowedModels);
+      out = out.filter((row) => allowed.has(row.id) || row.capability === template.requiredCapability);
+    }
+  }
+  if (opts.capability) out = out.filter((row) => row.capability === opts.capability);
+  if (opts.search) {
+    const needle = opts.search.toLowerCase();
+    out = out.filter((row) => row.id.toLowerCase().includes(needle) || row.name.toLowerCase().includes(needle));
+  }
+  return out.sort((a, b) => displayCost(a) - displayCost(b) || a.id.localeCompare(b.id));
+}
+
+export function suggestedAssignments(task: string): Record<string, string[]> {
+  const template = getTaskTemplate(task);
+  if (!template) return {};
+  return {
+    primary: [template.primaryModel],
+    fallback: [template.fallbackModel],
+    allowed: template.allowedModels,
+  };
+}
+
+export async function runModels(argv: string[]): Promise<number> {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('agentguard models [--sync-pricing] [--search <term>] [--capability <tier>] [--task <template>] [--json]');
+    return 0;
+  }
+
+  const sync = argv.includes('--sync-pricing');
+  const json = argv.includes('--json');
+  const search = argValue(argv, '--search');
+  const capability = argValue(argv, '--capability');
+  const task = argValue(argv, '--task');
+
+  if (sync) {
+    const result = await syncPricingIntoCostTable({ force: true });
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log('');
+      console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+      console.log('');
+      console.log(`  ${green('applied')} ${result.count} OpenRouter pricing overrides`);
+      console.log(`  ${dim('saved')} ${agentguardHome()}/cost-overrides.json`);
+      console.log('');
+    }
+    return 0;
+  }
+
+  const rows = await loadRows();
+  const filtered = filterRows(rows, { search, capability, task });
+  if (json) {
+    console.log(JSON.stringify({ models: filtered, assignments: task ? suggestedAssignments(task) : undefined }, null, 2));
+    return 0;
+  }
+
+  if (process.stdin.isTTY && !search && !capability && !task) {
+    const selected = await interactivePick(filtered);
+    if (selected.length > 0) writeSelectedModels(selected);
+    return 0;
+  }
+
+  printRows(filtered, task);
+  return 0;
+}
+
+async function loadRows(): Promise<ModelRow[]> {
+  const cached = getCachedCatalog();
+  if (cached) return rowsFromCatalog(cached.data);
+  try {
+    const catalog = await fetchCatalog();
+    return rowsFromCatalog(catalog.data);
+  } catch {
+    return rowsFromCostTable();
+  }
+}
+
+function printRows(rows: ModelRow[], task?: string): void {
+  console.log('');
+  console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+  console.log('');
+  if (task && TASK_TEMPLATES[task]) {
+    const assignment = suggestedAssignments(task);
+    console.log('  ' + cyanBold(`task: ${task}`));
+    console.log(`  primary: ${assignment.primary?.join(', ') ?? 'n/a'}`);
+    console.log(`  fallback: ${assignment.fallback?.join(', ') ?? 'n/a'}`);
+    console.log('');
+  }
+  for (const row of rows.slice(0, 80)) {
+    console.log(`  ${green(row.id.padEnd(38))} ${formatCost(row).padEnd(22)} ${dim(row.capability)}`);
+  }
+  if (rows.length > 80) console.log(`  ${yellow(String(rows.length - 80) + ' more')}  refine with agentguard models --search <term>`);
+  console.log('');
+  console.log('  ' + statusBar());
+  console.log('');
+}
+
+async function interactivePick(rows: ModelRow[]): Promise<string[]> {
+  const selected = new Set<string>();
+  let cursor = 0;
+  let filtered = rows.slice(0, 80);
+  let query = '';
+  readline.emitKeypressEvents(process.stdin);
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+
+  const render = () => {
+    process.stdout.write('\x1b[2J\x1b[H');
+    console.log(banner(AGENTGUARD_SPEND_VERSION));
+    console.log('');
+    console.log(`Search: ${query || dim('press / to filter')}   Selected: ${selected.size}`);
+    console.log('');
+    filtered.slice(0, 18).forEach((row, index) => {
+      const marker = selected.has(row.id) ? '[x]' : '[ ]';
+      const pointer = index === cursor ? '>' : ' ';
+      console.log(`${pointer} ${marker} ${row.id.padEnd(40)} ${formatCost(row).padEnd(20)} ${row.capability}`);
+    });
+    console.log('');
+    console.log(dim('[/] search  [space] select  [enter] confirm  [q] quit'));
+  };
+
+  render();
+  return new Promise((resolve) => {
+    const onKey = (_chunk: string, key: readline.Key) => {
+      if (key.name === 'q' || (key.ctrl && key.name === 'c')) finish([]);
+      else if (key.name === 'return') finish([...selected]);
+      else if (key.name === 'down') { cursor = Math.min(cursor + 1, Math.max(0, filtered.length - 1)); render(); }
+      else if (key.name === 'up') { cursor = Math.max(cursor - 1, 0); render(); }
+      else if (key.name === 'space') {
+        const row = filtered[cursor];
+        if (row) selected.has(row.id) ? selected.delete(row.id) : selected.add(row.id);
+        render();
+      } else if (key.name === 'backspace') {
+        query = query.slice(0, -1);
+        filtered = filterRows(rows, { search: query });
+        cursor = 0;
+        render();
+      } else if (key.sequence && key.sequence.length === 1 && key.sequence !== '/') {
+        query += key.sequence;
+        filtered = filterRows(rows, { search: query });
+        cursor = 0;
+        render();
+      }
+    };
+    const finish = (value: string[]) => {
+      process.stdin.off('keypress', onKey);
+      if (process.stdin.isTTY) process.stdin.setRawMode(false);
+      process.stdout.write('\n');
+      resolve(value);
+    };
+    process.stdin.on('keypress', onKey);
+  });
+}
+
+function writeSelectedModels(models: string[]): void {
+  const filePath = path.join(agentguardHome(), 'policy.yaml');
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  let existing = '';
+  try { existing = fs.readFileSync(filePath, 'utf8'); } catch { existing = defaultPolicy(); }
+  const block = ['allowedModels:', ...models.map((model) => `  - ${model}`)].join('\n') + '\n';
+  const next = existing.match(/^allowedModels:/m)
+    ? existing.replace(/^allowedModels:\n(?:  - .*\n)*/m, block)
+    : existing.trimEnd() + '\n' + block;
+  fs.writeFileSync(filePath, next);
+  console.log(`${green('saved')} ${filePath}`);
+}
+
+function defaultPolicy(): string {
+  return 'id: local-policy-v1\nname: Local AgentGuard policy\nversion: 1\neffectiveFrom: "' + new Date().toISOString() + '"\nmode: enforce\nscope:\n  tenantId: local\ncaps:\n  - amountCents: 100\n    window: per_call\n    action: allow\n';
+}
+
+function formatCost(row: ModelRow): string {
+  if (row.inputCentsPerMtok === null || row.outputCentsPerMtok === null) return '$n/a per 1M';
+  return `$${(row.inputCentsPerMtok / 100).toFixed(2)}/$${(row.outputCentsPerMtok / 100).toFixed(2)} per 1M`;
+}
+
+function displayCost(row: ModelRow): number {
+  return row.inputCentsPerMtok ?? Number.MAX_SAFE_INTEGER;
+}
+
+function capabilityForModel(model: string): string {
+  if (model.includes('gpt-5') || model.includes('opus') || model.includes('sonnet')) return 'payment_initiate';
+  if (model.includes('mini') || model.includes('haiku') || model.includes('flash')) return 'read_only';
+  if (getModelCost(model)) return 'data_write';
+  return 'read_only';
+}
+
+function argValue(argv: string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : undefined;
+}

package/src/cli/tips.ts

@@ -0,0 +1,161 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTGUARD_SPEND_VERSION } from '../index';
+import { agentguardHome, banner, dim, green, statusBar } from './colors';
+
+export interface AgentGuardTip {
+  id: string;
+  surface: string;
+  severity: 'info' | 'warning';
+  text: string;
+  learn_more_url: string;
+  dismissible: boolean;
+}
+
+interface TipsState {
+  seen?: string[];
+}
+
+export const TIPS: AgentGuardTip[] = [
+  {
+    id: 'cheap-read-only',
+    surface: 'models',
+    severity: 'info',
+    text: "Use 'openai/gpt-4o-mini' for read-only tasks. It is far cheaper than gpt-5 with the same audit guarantees.",
+    learn_more_url: 'https://agentguard.run/docs/models',
+    dismissible: true,
+  },
+  {
+    id: 'openrouter-cfo',
+    surface: 'auth',
+    severity: 'info',
+    text: 'One OpenRouter key gives access to hundreds of models across many providers. Your CFO sees one invoice while AgentGuard enforces who uses what.',
+    learn_more_url: 'https://agentguard.run/docs/openrouter',
+    dismissible: true,
+  },
+  {
+    id: 'public-verify',
+    surface: 'verify',
+    severity: 'info',
+    text: 'Share https://agentguard.run/verify with your auditor. Paste any receipt and get browser-based cryptographic verification with no install.',
+    learn_more_url: 'https://agentguard.run/verify',
+    dismissible: true,
+  },
+  {
+    id: 'weekly-pricing',
+    surface: 'models',
+    severity: 'info',
+    text: "Run 'agentguard models --sync-pricing' weekly to keep cost math current with OpenRouter live prices.",
+    learn_more_url: 'https://agentguard.run/docs/pricing',
+    dismissible: true,
+  },
+  {
+    id: 'payment-attestation',
+    surface: 'wizard',
+    severity: 'warning',
+    text: "Capability tier 'payment_execute' should require a verified attestation. Do not accept caller-supplied claims for real money movement.",
+    learn_more_url: 'https://agentguard.run/docs/capabilities',
+    dismissible: true,
+  },
+  {
+    id: 'shadow-rollout',
+    surface: 'policy',
+    severity: 'info',
+    text: "Use mode 'shadow' for the first day of a rollout. You get signed decisions before enforcement changes traffic.",
+    learn_more_url: 'https://agentguard.run/docs/policies',
+    dismissible: true,
+  },
+  {
+    id: 'verify-chain',
+    surface: 'verify',
+    severity: 'info',
+    text: "Run 'agentguard verify <log.jsonl> <pubkey>' before sharing an audit packet. Whole-chain verification catches missing entries.",
+    learn_more_url: 'https://agentguard.run/docs/verify',
+    dismissible: true,
+  },
+  {
+    id: 'local-overrides',
+    surface: 'models',
+    severity: 'info',
+    text: 'Negotiated rates belong in ~/.agentguard/cost-overrides.json. Keep pricing math local with the rest of the policy state.',
+    learn_more_url: 'https://agentguard.run/docs/pricing',
+    dismissible: true,
+  },
+  {
+    id: 'bedrock-routing',
+    surface: 'bindings',
+    severity: 'info',
+    text: 'Use the native Bedrock binding when AWS procurement requires direct provider calls. AgentGuard still signs every local decision.',
+    learn_more_url: 'https://agentguard.run/docs/bedrock',
+    dismissible: true,
+  },
+];
+
+export function tipsStatePath(): string {
+  return path.join(agentguardHome(), 'tips-seen.json');
+}
+
+export function readTipsState(filePath: string = tipsStatePath()): TipsState {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as TipsState;
+    return Array.isArray(parsed.seen) ? parsed : { seen: [] };
+  } catch {
+    return { seen: [] };
+  }
+}
+
+export function writeTipsState(state: TipsState, filePath: string = tipsStatePath()): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify({ seen: [...new Set(state.seen ?? [])] }, null, 2) + '\n', { mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch { return; }
+}
+
+export function unseenTips(state: TipsState = readTipsState()): AgentGuardTip[] {
+  const seen = new Set(state.seen ?? []);
+  return TIPS.filter((tip) => !seen.has(tip.id));
+}
+
+export function markTipsSeen(ids: string[], filePath: string = tipsStatePath()): void {
+  const state = readTipsState(filePath);
+  writeTipsState({ seen: [...new Set([...(state.seen ?? []), ...ids])] }, filePath);
+}
+
+export function maybeShowStartupTips(force = false): void {
+  const state = readTipsState();
+  const startupIds = ['startup-wizard', 'startup-verify'];
+  const seen = new Set(state.seen ?? []);
+  if (!force && startupIds.every((id) => seen.has(id))) return;
+  console.log('');
+  console.log('  ' + green("Tip: try 'agentguard wizard' to set up in 90 seconds."));
+  console.log('  ' + green('Tip: share https://agentguard.run/verify with your auditor.'));
+  markTipsSeen(startupIds);
+}
+
+export async function runTips(argv: string[]): Promise<number> {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('agentguard tips [--reset] [--json]');
+    return 0;
+  }
+  if (argv.includes('--reset')) {
+    writeTipsState({ seen: [] });
+    console.log('AgentGuard tips reset.');
+    return 0;
+  }
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify(TIPS, null, 2));
+    return 0;
+  }
+  console.log('');
+  console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+  console.log('');
+  for (const tip of TIPS) {
+    const label = tip.severity === 'warning' ? 'warning' : 'tip';
+    console.log(`  ${green(label)}  ${tip.text}`);
+    console.log(`       ${dim(tip.learn_more_url)}`);
+  }
+  console.log('');
+  console.log('  ' + statusBar());
+  console.log('');
+  markTipsSeen(TIPS.filter((tip) => tip.dismissible).map((tip) => tip.id));
+  return 0;
+}

package/src/cli/wizard.ts

@@ -0,0 +1,160 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { AGENTGUARD_SPEND_VERSION } from '../index';
+import { TASK_TEMPLATES, getTaskTemplate, listTaskTemplates, type TaskTemplate } from '../templates';
+import { agentguardHome, banner, cyanBold, green, statusBar } from './colors';
+
+const BUILD_TYPES = ['chatbot', 'agent', 'batch job', 'API endpoint'];
+const CAPABILITY_TIERS = [
+  ['read_only', 'Read records and produce findings'],
+  ['data_write', 'Write allowed fields after policy checks'],
+  ['payment_initiate', 'Create or recommend payment intents'],
+  ['payment_execute', 'Execute money movement only with verified attestation'],
+] as const;
+
+export interface WizardAnswers {
+  building: string;
+  template: string;
+  capability: string;
+  allowedModels: string[];
+  fallbackModel: string;
+  perCallCents: number;
+  perDayCents: number;
+  perMonthCents: number;
+  systemInstructions: string;
+}
+
+export class WizardStateMachine {
+  step = 0;
+  readonly totalSteps = 7;
+
+  next(answer: string): boolean {
+    if (!this.validate(this.step, answer)) return false;
+    this.step = Math.min(this.step + 1, this.totalSteps - 1);
+    return true;
+  }
+
+  back(): void {
+    this.step = Math.max(0, this.step - 1);
+  }
+
+  validate(step: number, answer: string): boolean {
+    if (step === 0) return BUILD_TYPES.includes(answer);
+    if (step === 1) return Boolean(TASK_TEMPLATES[answer]);
+    if (step === 2) return CAPABILITY_TIERS.some(([tier]) => tier === answer);
+    if (step === 3) return answer.split(',').map((item) => item.trim()).filter(Boolean).length > 0;
+    if (step === 4) return answer.trim().length > 0;
+    if (step === 5) return answer.split(',').every((item) => Number.isSafeInteger(Number(item.trim())) && Number(item.trim()) >= 0);
+    return true;
+  }
+}
+
+export async function runWizard(argv: string[]): Promise<number> {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('agentguard wizard [--defaults] [--template <name>]');
+    return 0;
+  }
+  const templateSlug = valueAfter(argv, '--template') ?? 'risk-review';
+  const useDefaults = argv.includes('--defaults') || !process.stdin.isTTY;
+  const answers = useDefaults ? defaultAnswers(templateSlug) : await promptAnswers(templateSlug);
+  const outputs = writeWizardOutputs(answers);
+  console.log('');
+  console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+  console.log('');
+  console.log(`  ${green('created')} ${outputs.policyPath}`);
+  console.log(`  ${green('created')} ${outputs.quickstartTsPath}`);
+  console.log(`  ${green('created')} ${outputs.quickstartPyPath}`);
+  console.log('');
+  console.log(cyanBold('Quickstart snippet'));
+  console.log('');
+  console.log(outputs.snippet);
+  console.log('');
+  console.log('  ' + statusBar());
+  console.log('');
+  return 0;
+}
+
+export function defaultAnswers(templateSlug = 'risk-review'): WizardAnswers {
+  const template = getTaskTemplate(templateSlug) ?? getTaskTemplate('risk-review') as TaskTemplate;
+  const perCall = template.caps.find((cap) => cap.window === 'per_call')?.amountCents ?? 100;
+  const perDay = template.caps.find((cap) => cap.window === 'per_day')?.amountCents ?? 2500;
+  return {
+    building: 'agent',
+    template: template.slug,
+    capability: template.requiredCapability,
+    allowedModels: [...template.allowedModels],
+    fallbackModel: template.fallbackModel,
+    perCallCents: perCall,
+    perDayCents: perDay,
+    perMonthCents: perDay * 20,
+    systemInstructions: template.systemInstructions,
+  };
+}
+
+export function writeWizardOutputs(answers: WizardAnswers, home = agentguardHome()): { policyPath: string; quickstartTsPath: string; quickstartPyPath: string; snippet: string } {
+  fs.mkdirSync(home, { recursive: true });
+  const policyPath = path.join(home, 'policy.yaml');
+  const quickstartTsPath = path.join(home, 'quickstart.ts');
+  const quickstartPyPath = path.join(home, 'quickstart.py');
+  const policy = policyYaml(answers);
+  const ts = quickstartTs(answers);
+  const py = quickstartPy(answers);
+  fs.writeFileSync(policyPath, policy);
+  fs.writeFileSync(quickstartTsPath, ts);
+  fs.writeFileSync(quickstartPyPath, py);
+  return { policyPath, quickstartTsPath, quickstartPyPath, snippet: tsSnippet(answers) };
+}
+
+async function promptAnswers(templateSlug: string): Promise<WizardAnswers> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (question: string, fallback: string) => new Promise<string>((resolve) => {
+    rl.question(`${question} (${fallback}): `, (answer) => resolve(answer.trim() || fallback));
+  });
+  try {
+    const seed = defaultAnswers(templateSlug);
+    console.log('');
+    console.log('  ' + banner(AGENTGUARD_SPEND_VERSION));
+    console.log('');
+    const building = await ask(`What are you building? ${BUILD_TYPES.join(', ')}`, seed.building);
+    const template = await ask(`Pick a task template: ${listTaskTemplates().map((item) => item.slug).join(', ')}`, seed.template);
+    const capability = await ask(`Capability tier: ${CAPABILITY_TIERS.map(([tier, label]) => tier + ' (' + label + ')').join(', ')}`, seed.capability);
+    const templateDef = getTaskTemplate(template) ?? getTaskTemplate(seed.template) as TaskTemplate;
+    const allowedModels = (await ask('Allowed models, comma separated', templateDef.allowedModels.join(','))).split(',').map((item) => item.trim()).filter(Boolean);
+    const fallbackModel = await ask('Fallback on downgrade', templateDef.fallbackModel);
+    const caps = await ask('Caps in cents: per-call, per-day, per-month', `${seed.perCallCents},${seed.perDayCents},${seed.perMonthCents}`);
+    const [perCallCents, perDayCents, perMonthCents] = caps.split(',').map((item) => Number(item.trim()));
+    const systemInstructions = await ask('System instructions', templateDef.systemInstructions);
+    return { building, template, capability, allowedModels, fallbackModel, perCallCents, perDayCents, perMonthCents, systemInstructions };
+  } finally {
+    rl.close();
+  }
+}
+
+function policyYaml(answers: WizardAnswers): string {
+  const id = `agentguard-${answers.template}-v1`;
+  const allowed = answers.allowedModels.map((model) => `  - ${model}`).join('\n');
+  return `# AgentGuard Spend policy generated by agentguard wizard\nid: ${id}\nname: ${answers.template} policy\nversion: 1\neffectiveFrom: "${new Date().toISOString()}"\nmode: enforce\nrequiredCapability: ${answers.capability}\nscope:\n  tenantId: my-tenant\nmodels:\n  allowed:\n${allowed}\n  fallback: ${answers.fallbackModel}\ncaps:\n  # WHY: Per-call cap bounds one agent action.\n  - amountCents: ${answers.perCallCents}\n    window: per_call\n    action: downgrade\n    downgradeTo: ${answers.fallbackModel}\n    reason: "Per-call budget reached, routing to fallback model"\n  # WHY: Daily cap catches runaway loops and unexpected volume.\n  - amountCents: ${answers.perDayCents}\n    window: per_day\n    action: block\n    reason: "Daily budget reached"\n  # WHY: Monthly cap keeps the finance view predictable.\n  - amountCents: ${answers.perMonthCents}\n    window: per_month\n    action: block\n    reason: "Monthly budget reached"\nsystemInstructions: |\n${indent(answers.systemInstructions, 2)}\n`;
+}
+
+function quickstartTs(answers: WizardAnswers): string {
+  return `import OpenAI from 'openai';\nimport { withSpendGuard, type SpendPolicy } from '@agentguard-run/spend';\n\nconst policy: SpendPolicy = {\n  id: 'agentguard-${answers.template}-v1',\n  name: '${answers.template} policy',\n  scope: { tenantId: 'my-tenant' },\n  caps: [\n    { amountCents: ${answers.perCallCents}, window: 'per_call', action: 'downgrade', downgradeTo: '${answers.fallbackModel}' },\n    { amountCents: ${answers.perDayCents}, window: 'per_day', action: 'block' },\n    { amountCents: ${answers.perMonthCents}, window: 'per_month', action: 'block' },\n  ],\n  mode: 'enforce',\n  requiredCapability: '${answers.capability}',\n  version: 1,\n  effectiveFrom: new Date().toISOString(),\n};\n\nconst openrouter = new OpenAI({\n  baseURL: 'https://openrouter.ai/api/v1',\n  apiKey: process.env.OPENROUTER_API_KEY,\n});\n\nexport const guardedClient = withSpendGuard(openrouter, {\n  policy,\n  scope: { tenantId: 'my-tenant', agentId: '${answers.template}' },\n  capabilityClaim: '${answers.capability}',\n});\n`;
+}
+
+function quickstartPy(answers: WizardAnswers): string {
+  return `from openai import OpenAI\nfrom agentguard_spend import with_spend_guard\nfrom agentguard_spend.types import SpendPolicy, SpendCap\n\npolicy = SpendPolicy(\n    id='agentguard-${answers.template}-v1', name='${answers.template} policy',\n    scope={'tenantId': 'my-tenant'},\n    caps=[\n        SpendCap(amountCents=${answers.perCallCents}, window='per_call', action='downgrade', downgradeTo='${answers.fallbackModel}'),\n        SpendCap(amountCents=${answers.perDayCents}, window='per_day', action='block'),\n        SpendCap(amountCents=${answers.perMonthCents}, window='per_month', action='block'),\n    ],\n    mode='enforce', requiredCapability='${answers.capability}',\n    version=1, effectiveFrom='2026-05-27T00:00:00Z',\n)\n\nopenrouter = OpenAI(base_url='https://openrouter.ai/api/v1')\nguarded_client = with_spend_guard(openrouter, policy=policy, scope={'tenantId': 'my-tenant', 'agentId': '${answers.template}'}, capability_claim='${answers.capability}')\n`;
+}
+
+function tsSnippet(answers: WizardAnswers): string {
+  return `const response = await guardedClient.chat.completions.create({\n  model: '${answers.allowedModels[0] ?? 'openai/gpt-4o-mini'}',\n  messages: [{ role: 'user', content: 'Run the governed task.' }],\n});`;
+}
+
+function indent(value: string, spaces: number): string {
+  const prefix = ' '.repeat(spaces);
+  return value.split('\n').map((line) => prefix + line).join('\n');
+}
+
+function valueAfter(argv: string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : undefined;
+}

package/src/coach/anomaly.ts

@@ -0,0 +1,98 @@
+/**
+ * AgentGuard(TM) Spend: local Coach anomaly review skeleton.
+ *
+ * Reads local decision logs only. No network calls are made.
+ *
+ * Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * 64/071,781; 64/071,789).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { agentguardHome } from './output';
+
+export interface CoachSpendPoint {
+  ts: string;
+  scope: string;
+  agentId: string;
+  cents: number;
+}
+
+export interface CoachAnomaly {
+  scope: string;
+  agentId: string;
+  last24hCents: number;
+  baselineCents: number;
+  sigmaCents: number;
+  suggestion: string;
+}
+
+export function readDecisionSpend(scope = 'default', home = agentguardHome()): CoachSpendPoint[] {
+  const file = path.join(home, scope, 'decisions.ndjson');
+  if (!fs.existsSync(file)) return [];
+  const points: CoachSpendPoint[] = [];
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      const decision = parsed.decision ?? parsed;
+      const cents = Number(decision.actualCents ?? decision.projectedCents ?? 0);
+      const ts = String(decision.timestamp ?? parsed.timestamp ?? new Date(0).toISOString());
+      const scopeObj = decision.scope ?? {};
+      points.push({
+        ts,
+        scope: String(scopeObj.tenantId ?? decision.triggeredScopeKey ?? scope),
+        agentId: String(scopeObj.agentId ?? decision.agentId ?? 'unknown'),
+        cents: Number.isFinite(cents) ? cents : 0,
+      });
+    } catch {
+      continue;
+    }
+  }
+  return points;
+}
+
+export function reviewAnomalies(points: CoachSpendPoint[], now = new Date()): CoachAnomaly[] {
+  const cutoff = now.getTime() - 24 * 60 * 60 * 1000;
+  const byAgent = new Map<string, CoachSpendPoint[]>();
+  for (const point of points) {
+    const key = `${point.scope}\t${point.agentId}`;
+    byAgent.set(key, [...(byAgent.get(key) ?? []), point]);
+  }
+  const anomalies: CoachAnomaly[] = [];
+  for (const [key, rows] of byAgent) {
+    const [scope, agentId] = key.split('\t');
+    const daily = bucketDaily(rows);
+    const historical = daily.filter((row) => row.day < dayKey(new Date(cutoff))).map((row) => row.cents);
+    const recent = rows.filter((row) => Date.parse(row.ts) >= cutoff).reduce((sum, row) => sum + row.cents, 0);
+    if (historical.length < 3 || recent <= 0) continue;
+    const mean = historical.reduce((sum, value) => sum + value, 0) / historical.length;
+    const variance = historical.reduce((sum, value) => sum + Math.pow(value - mean, 2), 0) / historical.length;
+    const sigma = Math.sqrt(variance);
+    if (recent > mean + 3 * sigma) {
+      anomalies.push({
+        scope: scope ?? 'unknown',
+        agentId: agentId ?? 'unknown',
+        last24hCents: recent,
+        baselineCents: Math.round(mean),
+        sigmaCents: Math.round(sigma),
+        suggestion: 'Lower the per_day cap or add a per_minute block cap for this agent.',
+      });
+    }
+  }
+  return anomalies.sort((a, b) => b.last24hCents - a.last24hCents);
+}
+
+function bucketDaily(points: CoachSpendPoint[]): Array<{ day: string; cents: number }> {
+  const buckets = new Map<string, number>();
+  for (const point of points) {
+    const day = dayKey(new Date(point.ts));
+    buckets.set(day, (buckets.get(day) ?? 0) + point.cents);
+  }
+  return [...buckets.entries()].map(([day, cents]) => ({ day, cents })).sort((a, b) => a.day.localeCompare(b.day));
+}
+
+function dayKey(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}