@agentguard-run/spend 0.2.2 → 0.4.0

package/src/coach/output.ts

@@ -0,0 +1,172 @@
+/**
+ * AgentGuard(TM) Spend: Coach output writers.
+ *
+ * Files are written locally under ~/.agentguard by default. Conversation logs
+ * stay in ~/.agentguard/coach-sessions and are never uploaded by this SDK.
+ *
+ * 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 os from 'os';
+import * as path from 'path';
+import type { SpendPolicy } from '../types';
+import {
+  buildPolicyFromProfile,
+  formatCents,
+  projectedSavings,
+  type CoachBusinessProfile,
+  type ProjectedSavings,
+} from './conversation';
+
+export interface CoachOutputOptions {
+  home?: string;
+  now?: Date;
+  language?: 'ts' | 'py';
+  overwrite?: boolean;
+}
+
+export interface CoachOutputs {
+  policy: SpendPolicy;
+  policyPath: string;
+  quickstartPath: string;
+  sessionDir: string;
+  savings: ProjectedSavings;
+  policyYaml: string;
+  quickstartCode: string;
+  savingsTable: string;
+}
+
+export interface CoachSessionLogger {
+  path: string;
+  append: (event: string, payload?: Record<string, unknown>) => void;
+}
+
+export function agentguardHome(): string {
+  return process.env.AGENTGUARD_HOME || path.join(os.homedir(), '.agentguard');
+}
+
+export function coachSessionDir(home = agentguardHome()): string {
+  return path.join(home, 'coach-sessions');
+}
+
+export function createCoachSessionLogger(home = agentguardHome(), now = new Date()): CoachSessionLogger {
+  const dir = coachSessionDir(home);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stamp = now.toISOString().replace(/[:.]/g, '-');
+  const file = path.join(dir, `${stamp}.jsonl`);
+  fs.closeSync(fs.openSync(file, 'a', 0o600));
+  return {
+    path: file,
+    append(event: string, payload: Record<string, unknown> = {}) {
+      const line = JSON.stringify({ ts: new Date().toISOString(), event, ...payload }) + '\n';
+      fs.appendFileSync(file, line, { encoding: 'utf8', mode: 0o600 });
+    },
+  };
+}
+
+export function writeCoachOutputs(profile: CoachBusinessProfile, options: CoachOutputOptions = {}): CoachOutputs {
+  const home = options.home ?? agentguardHome();
+  const language = options.language ?? profile.language;
+  const sessionDir = coachSessionDir(home);
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+
+  const policy = buildPolicyFromProfile(profile);
+  const policyPath = path.join(home, 'policy.yaml');
+  const quickstartPath = path.join(home, language === 'py' ? 'quickstart.py' : 'quickstart.ts');
+  const savings = projectedSavings(profile);
+  const policyYaml = renderPolicyYaml(policy, profile, options.now ?? new Date());
+  const quickstartCode = language === 'py' ? renderQuickstartPy(policy, profile) : renderQuickstartTs(policy, profile);
+  const savingsTable = renderSavingsTable(savings);
+
+  if (!options.overwrite) {
+    assertWritableTarget(policyPath);
+    assertWritableTarget(quickstartPath);
+  }
+  atomicWrite(policyPath, policyYaml, 0o600);
+  atomicWrite(quickstartPath, quickstartCode, 0o600);
+
+  return { policy, policyPath, quickstartPath, sessionDir, savings, policyYaml, quickstartCode, savingsTable };
+}
+
+export function renderPolicyYaml(policy: SpendPolicy, profile: CoachBusinessProfile, now = new Date()): string {
+  const caps = policy.caps.map((cap) => {
+    const lines = [
+      `  # WHY: ${whyForWindow(cap.window)}`,
+      `  - amountCents: ${cap.amountCents}`,
+      `    window: ${cap.window}`,
+      `    action: ${cap.action}`,
+    ];
+    if (cap.downgradeTo) lines.push(`    downgradeTo: ${cap.downgradeTo}`);
+    if (cap.reason) lines.push(`    reason: ${quoteYaml(cap.reason)}`);
+    return lines.join('\n');
+  }).join('\n');
+  const tasks = profile.tasks.map((task) => `  - ${quoteYaml(task)}`).join('\n');
+  return `# AgentGuard Spend policy generated by agentguard coach\n# Generated at: ${now.toISOString()}\n# Scope key: ${profile.scopeLabel}\nid: ${policy.id}\nname: ${quoteYaml(policy.name)}\nversion: ${policy.version}\neffectiveFrom: ${quoteYaml(policy.effectiveFrom)}\nmode: ${policy.mode}\nrequiredCapability: ${policy.requiredCapability ?? 'read_only'}\nscope:\n  tenantId: ${quoteYaml(policy.scope.tenantId)}\nmodels:\n  primary: ${profile.primaryModel}\n  fallback: ${profile.fallbackModel}\ntasks:\n${tasks}\ncaps:\n${caps}\nsystemInstructions: |\n${indent(systemInstructions(profile), 2)}\n`;
+}
+
+export function renderQuickstartTs(policy: SpendPolicy, profile: CoachBusinessProfile): string {
+  return `import OpenAI from 'openai';\nimport { withSpendGuard, type SpendPolicy } from '@agentguard-run/spend';\n\nconst policy: SpendPolicy = ${JSON.stringify(policy, null, 2)};\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: '${escapeTs(profile.tenantId)}', agentId: '${escapeTs(profile.vertical)}' },\n  capabilityClaim: '${policy.requiredCapability ?? 'read_only'}',\n});\n\nexport async function runGuardedTask(prompt: string) {\n  return guardedClient.chat.completions.create({\n    model: '${escapeTs(profile.primaryModel)}',\n    messages: [{ role: 'user', content: prompt }],\n  });\n}\n`;
+}
+
+export function renderQuickstartPy(policy: SpendPolicy, profile: CoachBusinessProfile): string {
+  const caps = policy.caps.map((cap) => {
+    const args = [`amountCents=${cap.amountCents}`, `window='${cap.window}'`, `action='${cap.action}'`];
+    if (cap.downgradeTo) args.push(`downgradeTo='${escapePy(cap.downgradeTo)}'`);
+    return `        SpendCap(${args.join(', ')}),`;
+  }).join('\n');
+  return `from openai import OpenAI\nfrom agentguard_spend import with_spend_guard\nfrom agentguard_spend.types import SpendPolicy, SpendCap\n\npolicy = SpendPolicy(\n    id='${escapePy(policy.id)}',\n    name='${escapePy(policy.name)}',\n    scope={'tenantId': '${escapePy(profile.tenantId)}'},\n    caps=[\n${caps}\n    ],\n    mode='${policy.mode}',\n    requiredCapability='${policy.requiredCapability ?? 'read_only'}',\n    version=${policy.version},\n    effectiveFrom='${escapePy(policy.effectiveFrom)}',\n)\n\nopenrouter = OpenAI(base_url='https://openrouter.ai/api/v1')\nguarded_client = with_spend_guard(\n    openrouter,\n    policy=policy,\n    scope={'tenantId': '${escapePy(profile.tenantId)}', 'agentId': '${escapePy(profile.vertical)}'},\n    capability_claim='${policy.requiredCapability ?? 'read_only'}',\n)\n`;
+}
+
+export function renderSavingsTable(savings: ProjectedSavings): string {
+  const rows = [
+    'Projected monthly savings',
+    `Before AgentGuard: ${formatCents(savings.monthlyBeforeCents)}`,
+    `After AgentGuard:  ${formatCents(savings.monthlyAfterCents)}`,
+    `Savings:           ${formatCents(savings.monthlySavingsCents)} (${savings.savingsPercent}%)`,
+  ];
+  return rows.join('\n');
+}
+
+function atomicWrite(file: string, content: string, mode: number): void {
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, content, { encoding: 'utf8', mode });
+  fs.renameSync(temp, file);
+  fs.chmodSync(file, mode);
+}
+
+function assertWritableTarget(file: string): void {
+  if (!fs.existsSync(file)) return;
+  fs.accessSync(file, fs.constants.W_OK);
+}
+
+function whyForWindow(window: string): string {
+  if (window === 'per_call') return 'Bounds one agent action and routes overflow to the fallback model.';
+  if (window === 'per_day') return 'Catches runaway loops and unexpected daily volume.';
+  if (window === 'per_month') return 'Keeps the finance view predictable for the billing cycle.';
+  return 'Limits spend inside the selected time window.';
+}
+
+function systemInstructions(profile: CoachBusinessProfile): string {
+  return `Run ${profile.vertical} tasks with ${profile.requiredCapability} capability. Prefer ${profile.primaryModel} for high-value work and ${profile.fallbackModel} for routine work. Keep evidence pointers in outputs and escalate anything outside the configured capability tier.`;
+}
+
+function quoteYaml(value: string): string {
+  return JSON.stringify(value);
+}
+
+function indent(value: string, spaces: number): string {
+  const prefix = ' '.repeat(spaces);
+  return value.split('\n').map((line) => prefix + line).join('\n');
+}
+
+function escapeTs(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+function escapePy(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}

package/src/coach/system-prompt.ts

@@ -0,0 +1,181 @@
+/**
+ * AgentGuard(TM) Spend: Coach system prompt.
+ *
+ * AgentGuard Coach runs locally in the customer terminal. It may call the
+ * customer's chosen OpenAI-compatible provider, but it never calls AgentGuard
+ * infrastructure for prompts, completions, provider keys, signing keys, or
+ * policy details.
+ *
+ * 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).
+ */
+
+export interface CoachPromptSection {
+  id: string;
+  title: string;
+  content: string;
+}
+
+export const COACH_SYSTEM_PROMPT_SECTIONS: CoachPromptSection[] = [
+  {
+    id: 'role',
+    title: 'Role',
+    content: `You are AgentGuard Coach, helping a business owner configure AgentGuard Spend for their specific company. You produce a complete policy.yaml plus quickstart code customized to their vertical. You never make up cap values without explaining the math. You ask one question at a time, keep the tone direct, and optimize for a working local setup in under 90 seconds.`,
+  },
+  {
+    id: 'sdk-knowledge',
+    title: 'SDK Knowledge',
+    content: `AgentGuard Spend is a zero-data-plane SDK. Policy evaluation runs inside the customer process. Prompts, completions, provider API keys, signing keys, policies, and cost overrides never go to AgentGuard infrastructure.
+
+Enforcement actions:
+- allow: call proceeds unchanged.
+- downgrade: model is rewritten to the cap's downgradeTo model, then the call proceeds.
+- shadow: decision is signed and logged, but traffic is not changed.
+- block: provider call is stopped before bytes leave the customer process.
+
+Spend windows:
+- per_call: one call only.
+- per_minute: burst protection.
+- per_hour: short campaign or batch guard.
+- per_day: normal operating budget.
+- per_month: finance-facing budget ceiling.
+
+Capability tiers in ascending order:
+- read_only: read records and produce summaries or recommendations.
+- data_write: write database fields, tickets, messages, notes, or drafts.
+- payment_initiate: create or recommend payment, refund, dispute, or charge flows.
+- payment_execute: execute money movement only with a verified attestation.
+
+Policy schema:
+SpendPolicy has id, name, scope, caps, mode, version, effectiveFrom, and optional requiredCapability. SpendScope has tenantId plus optional userId, teamId, agentId, taskId, provider. SpendCap has amountCents, window, action, optional downgradeTo, optional reason.
+
+Provider wrappers:
+- withSpendGuard wraps OpenAI-compatible chat.completions.create clients, including OpenRouter.
+- withSpendGuardAnthropic wraps Anthropic messages.create and messages.stream.
+- withSpendGuardBedrock wraps BedrockRuntimeClient send for InvokeModelCommand and InvokeModelWithResponseStreamCommand.
+
+Streaming true-up:
+The SDK reserves against projected tokens before a stream starts. On stream completion or cancellation, it signs a settlement entry with actual usage when the provider supplies usage, and falls back to the local token estimator when needed.`,
+  },
+  {
+    id: 'vertical-encyclopedia-core',
+    title: 'Vertical Encyclopedia: Installed Skills',
+    content: `Use these condensed vertical patterns as RAG context, not training data.
+
+Law firm:
+Tasks: contract redline, novel contract review, legal research, brief drafting, deposition prep, discovery review. Models: anthropic/claude-haiku-4-5 for boilerplate and discovery, anthropic/claude-sonnet-4-6 for research and novel terms, anthropic/claude-opus-4-7 for brief drafting and deposition analysis. Caps: $0.25 discovery tagging, $1 contract redline, $3 novel review, $4 legal research, $8 brief drafting. Scope key: matter or client matter code in agentId, attorney in userId. Compliance: privilege workflows need zero proxy, per-matter accounting, jurisdiction-aware model allowlists, and signed decision receipts for audit packets.
+
+Healthcare:
+Tasks: patient triage, chart review, clinical documentation drafting, prior authorization narrative, medical literature search, patient education, insurance verification, appointment scheduling. Models: BAA-covered Bedrock Anthropic for PHI, OpenRouter openai/gpt-5-mini or anthropic/claude-haiku-4-5 for non-PHI. Caps: $0.10 education, $0.25 insurance verification, $0.50 triage, $2 chart review, $3 documentation, $5 prior authorization. Scope key: encounter or patient encounter in agentId, clinician in userId. Compliance: PHI workflows require data_write minimum plus provider BAA controls. Non-PHI can use OpenRouter.
+
+E-commerce:
+Tasks: support triage, order status, returns, refund authorization, chargeback evidence, fraud screen, product recommendations, abandoned cart. Models: anthropic/claude-haiku-4-5 and openai/gpt-5-mini for bulk support, anthropic/claude-sonnet-4-6 for escalated fraud and high-value refund review, anthropic/claude-opus-4-7 for chargeback evidence. Caps: $0.05 order status, $0.10 support triage, $0.25 returns or small refund, $1 high-value refund review, $5 chargeback evidence. Scope key: order or dispute id in agentId. Compliance: payment-touching workflows require payment_initiate, and money movement requires payment_execute with attestation.
+
+Accounting:
+Tasks: receipt OCR, GL categorization, bank reconciliation, anomaly flagging, month-end accrual drafting, audit prep narrative, tax research, tax memo drafting, financial statement footnotes. Models: openai/gpt-5-mini for OCR and anomaly flagging, anthropic/claude-haiku-4-5 for GL categorization, anthropic/claude-sonnet-4-6 for accruals and audit prep, anthropic/claude-opus-4-7 for tax research and tax memos. Caps: $0.05 OCR, $0.10 GL and bank rec, $1.50 accruals, $2 audit prep, $5 tax research, $7 tax memo. Scope key: client engagement in agentId. Compliance: SOX and audit workflows require data_write for ledger changes, with retained signed receipts.
+
+Real estate:
+Tasks: listing description, luxury listing copy, comparable research, buyer-match scoring, contract analysis, mortgage doc review, tenant communication, lease drafting, ticket triage, title issue research. Models: openai/gpt-5-mini for listings and ticket triage, anthropic/claude-haiku-4-5 for comps and tenant comms, anthropic/claude-sonnet-4-6 for mortgage docs and lease drafting, anthropic/claude-opus-4-7 for title and purchase agreement analysis. Caps: $0.05 listing and tickets, $0.10 buyer match or tenant comm, $0.25 comps, $0.50 luxury copy, $2 mortgage docs, $3 lease drafting, $5 contract analysis, $6 title research. Scope key: listing, loan, or transaction id in agentId. Compliance: fair-housing review, state disclosure review, and per-transaction receipts.`,
+  },
+  {
+    id: 'vertical-encyclopedia-extra',
+    title: 'Vertical Encyclopedia: Additional Profiles',
+    content: `Insurance: claims intake on openai/gpt-5-mini at $0.10, claim summary on anthropic/claude-haiku-4-5 at $0.25, coverage review on anthropic/claude-sonnet-4-6 at $2, litigation packet on anthropic/claude-opus-4-7 at $6. Scope: claim id. Capability: data_write for claim notes.
+Marketing agency: brief intake on gpt-5-mini at $0.05, content variants on claude-haiku at $0.10, brand strategy on claude-sonnet at $1, campaign audit on gpt-5-mini at $0.25. Scope: client project.
+Software dev team: PR summary on gpt-5-mini at $0.10, code scan on gemini-3-flash-preview at $0.10, architecture review on claude-sonnet at $2, release risk review on claude-opus at $5. Scope: repo or PR.
+Education: lesson outline on gpt-5-mini at $0.05, tutoring response on claude-haiku at $0.10, assessment rubric on claude-sonnet at $1, academic integrity review on claude-sonnet at $2. Scope: class or student session. Student records require data_write for gradebook updates.
+Tutoring: diagnostic quiz on gpt-5-mini at $0.05, explanation on claude-haiku at $0.10, learning plan on claude-sonnet at $1. Scope: learner session.
+Local services: intake summary on gpt-5-mini at $0.05, quote draft on claude-haiku at $0.10, dispute response on claude-sonnet at $1. Scope: job id.
+Restaurant: menu copy on gpt-5-mini at $0.05, review response on claude-haiku at $0.10, supplier negotiation prep on claude-sonnet at $1. Scope: location or vendor.
+Fitness and gym: class copy on gpt-5-mini at $0.05, member support on claude-haiku at $0.10, retention plan on claude-sonnet at $1. Scope: member segment. Health notes require data_write.
+Dental practice: appointment support on gpt-5-mini at $0.05, patient education on claude-haiku at $0.10, insurance narrative on claude-sonnet at $2. Scope: encounter. PHI requires data_write and BAA-covered provider.
+Salon and spa: booking support on gpt-5-mini at $0.05, client message on claude-haiku at $0.10, inventory planning on gpt-5-mini at $0.10. Scope: location or appointment.
+Construction: bid takeoff summary on gpt-5-mini at $0.25, RFI draft on claude-haiku at $0.25, contract risk on claude-sonnet at $2, claim narrative on claude-opus at $5. Scope: project.
+Landscaping: estimate draft on gpt-5-mini at $0.05, route support on claude-haiku at $0.10, seasonal campaign on gpt-5-mini at $0.10. Scope: route or job.
+Pet care: appointment notes on gpt-5-mini at $0.05, customer support on claude-haiku at $0.10, incident summary on claude-sonnet at $1. Scope: booking or pet profile.
+Photography: inquiry response on gpt-5-mini at $0.05, proposal on claude-haiku at $0.10, contract review on claude-sonnet at $1. Scope: client shoot.
+Freelance design: brief summary on gpt-5-mini at $0.05, concept copy on claude-haiku at $0.10, proposal on claude-sonnet at $1. Scope: client project.
+Podcast: show notes on gpt-5-mini at $0.05, clip ideas on claude-haiku at $0.10, sponsor proposal on claude-sonnet at $1. Scope: episode.
+Manufacturing: work-order summary on gpt-5-mini at $0.10, supplier risk on claude-sonnet at $2, QA incident report on claude-sonnet at $1. Scope: work order.
+Logistics: shipment exception triage on gpt-5-mini at $0.05, carrier dispute on claude-sonnet at $1, route planning narrative on claude-haiku at $0.25. Scope: shipment.
+Nonprofit: donor email on gpt-5-mini at $0.05, grant outline on claude-sonnet at $1, impact report on claude-sonnet at $2. Scope: campaign or grant.
+HR and recruiting: resume screen on gpt-5-mini at $0.05, interview packet on claude-haiku at $0.10, policy review on claude-sonnet at $1. Scope: requisition. Employment decisions need human review.
+Travel agency: itinerary draft on gpt-5-mini at $0.10, disruption support on claude-haiku at $0.25, VIP trip plan on claude-sonnet at $2. Scope: trip.
+Banking and fintech: support triage on gpt-5-mini at $0.05, KYC summary on claude-sonnet at $1, dispute packet on claude-sonnet at $2, payment workflow requires payment_initiate.
+Government contractor: RFP summary on claude-haiku at $0.25, compliance matrix on claude-sonnet at $2, proposal draft on claude-opus at $6. Scope: opportunity. Data residency may constrain providers.
+Energy and utilities: ticket triage on gpt-5-mini at $0.05, outage summary on claude-haiku at $0.25, regulatory response on claude-sonnet at $2. Scope: incident.
+Agriculture: grant draft on claude-sonnet at $1, field note summary on gpt-5-mini at $0.05, compliance report on claude-sonnet at $2. Scope: farm or field.
+Property management: tenant ticket on gpt-5-mini at $0.05, lease question on claude-haiku at $0.25, legal escalation on claude-sonnet at $2. Scope: property or unit.
+Automotive dealer: lead response on gpt-5-mini at $0.05, finance packet review on claude-sonnet at $1, service estimate support on claude-haiku at $0.10. Scope: lead or repair order.
+Creator business: content repurpose on gpt-5-mini at $0.05, sponsor pitch on claude-sonnet at $1, audience analysis on claude-haiku at $0.25. Scope: campaign.
+Security operations: alert summary on gpt-5-mini at $0.05, incident report on claude-sonnet at $2, postmortem on claude-opus at $5. Scope: incident.`,
+  },
+  {
+    id: 'cost-table-summary',
+    title: 'Cost Table Summary',
+    content: `Use only known model names. Prices are approximate dollars per 1M tokens and must be presented as estimates.
+openai/gpt-5: input $5.00, output $15.00.
+openai/gpt-5-mini: input $0.50, output $2.00.
+openai/gpt-4o: input $2.50, output $10.00.
+openai/gpt-4o-mini: input $0.15, output $0.60.
+anthropic/claude-opus-4-7: input $20.00, output $100.00.
+anthropic/claude-opus-4-6: input $15.00, output $75.00.
+anthropic/claude-sonnet-4-6: input $3.00, output $15.00.
+anthropic/claude-sonnet-4-5: input $3.00, output $15.00.
+anthropic/claude-haiku-4-5: input $1.00, output $5.00.
+google/gemini-3.1-pro-preview: input $2.00, output $10.00.
+google/gemini-3-flash-preview: input $0.20, output $1.00.
+anthropic.claude-opus-4-v1:0: input $15.00, output $75.00.
+anthropic.claude-sonnet-4-v1:0: input $3.00, output $15.00.
+amazon.nova-pro-v1:0: input $0.80, output $3.20.
+amazon.nova-lite-v1:0: input $0.06, output $0.24.
+For unknown live OpenRouter models, ask the customer to run agentguard models --sync-pricing before using them in a policy.`,
+  },
+  {
+    id: 'policy-reference',
+    title: 'Policy YAML Reference',
+    content: `Annotated policy template:
+id: business-task-v1
+name: Human readable policy name
+version: 1
+effectiveFrom: "2026-05-28T00:00:00.000Z"
+mode: enforce
+requiredCapability: read_only
+scope:
+  tenantId: customer-business-id
+  teamId: optional-team
+  agentId: optional-project-or-transaction
+caps:
+  # WHY: Per-call cap bounds one agent action.
+  - amountCents: 50
+    window: per_call
+    action: downgrade
+    downgradeTo: openai/gpt-4o-mini
+    reason: "Per-call budget reached, route to fallback"
+  # WHY: Daily cap catches loops and unexpected traffic.
+  - amountCents: 2500
+    window: per_day
+    action: block
+    reason: "Daily budget reached"
+  # WHY: Monthly cap gives finance a clear ceiling.
+  - amountCents: 50000
+    window: per_month
+    action: block
+    reason: "Monthly budget reached"`,
+  },
+  {
+    id: 'conversation-flow',
+    title: 'Conversation Flow Instructions',
+    content: `Ask one question at a time. The required flow is: Q1 what are you building, Q2 team size and monthly volume, Q3 top three AI tasks, Q4 monthly budget or per-task budget, Q5 confirm and offer refinements. After Q5, show projected savings math before finalizing. Always explain cap values with arithmetic. Always offer to write the local file. If the vertical is unknown, ask for customer type, task list, and whether any task touches payments, health data, financial records, legal privilege, student records, or regulated employment decisions. Suggest agentguard demo at the end.`,
+  },
+  {
+    id: 'hard-rules',
+    title: 'Hard Rules',
+    content: `Never propose a proxy architecture. Never suggest managed-key services. Never invent model names or prices outside the cost table. For HIPAA, SOX, privilege, student records, financial records, or employment workflows, require capability gating with data_write minimum when data can be written. For payment-touching workflows, require payment_initiate. For money movement, require payment_execute plus verified attestation. Keep conversation logs local in ~/.agentguard/coach-sessions.`,
+  },
+];
+
+export const MASTER_SYSTEM_PROMPT = COACH_SYSTEM_PROMPT_SECTIONS
+  .map((section) => `## ${section.title}\n${section.content}`)
+  .join('\n\n');

package/src/openrouter-catalog.ts

@@ -0,0 +1,180 @@
+/**
+ * AgentGuard(TM) Spend: OpenRouter catalog sync.
+ *
+ * OpenRouter requests go directly from the customer runtime to openrouter.ai.
+ * AgentGuard infrastructure does not receive prompts, completions, keys,
+ * policy files, or pricing overrides.
+ *
+ * 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 https from 'https';
+import * as os from 'os';
+import * as path from 'path';
+import { DEFAULT_COST_OVERRIDES_PATH, persistCostOverrides, setCostOverride, type ModelCost } from './cost-table';
+
+export interface OpenRouterPricing {
+  prompt?: string;
+  completion?: string;
+  image?: string;
+  request?: string;
+}
+
+export interface OpenRouterModel {
+  id: string;
+  name?: string;
+  context_length?: number;
+  pricing?: OpenRouterPricing;
+  architecture?: { modality?: string; tokenizer?: string; instruct_type?: string | null };
+  top_provider?: { context_length?: number; max_completion_tokens?: number | null; is_moderated?: boolean };
+  per_request_limits?: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+
+export interface OpenRouterCatalog {
+  data: OpenRouterModel[];
+  fetchedAt?: string;
+}
+
+export interface FetchCatalogOptions {
+  ttlMs?: number;
+  force?: boolean;
+  endpoint?: string;
+  cachePath?: string;
+}
+
+export interface SyncPricingResult {
+  count: number;
+  applied: string[];
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const STATE_DIR = process.env.AGENTGUARD_HOME || path.join(os.homedir(), '.agentguard');
+const DEFAULT_CACHE_PATH = path.join(STATE_DIR, 'openrouter-catalog.json');
+const DEFAULT_ENDPOINT = 'https://openrouter.ai/api/v1/models';
+
+let memoryCatalog: OpenRouterCatalog | null = null;
+
+export async function fetchCatalog(opts: FetchCatalogOptions = {}): Promise<OpenRouterCatalog> {
+  const ttlMs = opts.ttlMs ?? DAY_MS;
+  const cachePath = opts.cachePath ?? DEFAULT_CACHE_PATH;
+  if (!opts.force) {
+    const cached = readCachedCatalog(cachePath, ttlMs);
+    if (cached) return cached;
+  }
+
+  const fixturePath = process.env.AGENTGUARD_OPENROUTER_CATALOG_FIXTURE;
+  if (fixturePath) {
+    const fixture = parseCatalog(fs.readFileSync(fixturePath, 'utf8'));
+    return saveCatalog(fixture, cachePath);
+  }
+
+  try {
+    const body = await getJson(opts.endpoint ?? DEFAULT_ENDPOINT);
+    const catalog = parseCatalog(body);
+    return saveCatalog(catalog, cachePath);
+  } catch (err) {
+    const cached = readCachedCatalog(cachePath, Number.MAX_SAFE_INTEGER);
+    if (cached) return cached;
+    throw err;
+  }
+}
+
+export function getCachedCatalog(cachePath: string = DEFAULT_CACHE_PATH): OpenRouterCatalog | null {
+  if (memoryCatalog) return memoryCatalog;
+  return readCachedCatalog(cachePath, Number.MAX_SAFE_INTEGER);
+}
+
+export async function syncPricingIntoCostTable(opts: FetchCatalogOptions = {}): Promise<SyncPricingResult> {
+  const catalog = await fetchCatalog(opts);
+  const applied: string[] = [];
+  for (const model of catalog.data) {
+    const cost = modelCostFromOpenRouter(model);
+    if (!cost) continue;
+    setCostOverride(model.id, cost);
+    applied.push(model.id);
+  }
+  persistCostOverrides(DEFAULT_COST_OVERRIDES_PATH);
+  return { count: applied.length, applied };
+}
+
+export function persistOverrides(filePath?: string): void {
+  persistCostOverrides(filePath);
+}
+
+export function modelCostFromOpenRouter(model: OpenRouterModel): ModelCost | null {
+  const prompt = Number(model.pricing?.prompt);
+  const completion = Number(model.pricing?.completion);
+  if (!Number.isFinite(prompt) || !Number.isFinite(completion) || prompt < 0 || completion < 0) {
+    return null;
+  }
+  return {
+    inputCentsPerKtok: prompt * 100 * 1000,
+    outputCentsPerKtok: completion * 100 * 1000,
+  };
+}
+
+function readCachedCatalog(filePath: string, ttlMs: number): OpenRouterCatalog | null {
+  try {
+    const stat = fs.statSync(filePath);
+    if (Date.now() - stat.mtimeMs > ttlMs) return null;
+    const catalog = parseCatalog(fs.readFileSync(filePath, 'utf8'));
+    memoryCatalog = catalog;
+    return catalog;
+  } catch {
+    return null;
+  }
+}
+
+function saveCatalog(catalog: OpenRouterCatalog, filePath: string): OpenRouterCatalog {
+  const stamped: OpenRouterCatalog = { ...catalog, fetchedAt: catalog.fetchedAt ?? new Date().toISOString() };
+  memoryCatalog = stamped;
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(stamped, null, 2) + '\n', { mode: 0o600 });
+    try { fs.chmodSync(filePath, 0o600); } catch { return stamped; }
+  } catch {
+    return stamped;
+  }
+  return stamped;
+}
+
+function parseCatalog(body: string): OpenRouterCatalog {
+  const parsed = JSON.parse(body) as OpenRouterCatalog;
+  if (!parsed || !Array.isArray(parsed.data)) throw new Error('OpenRouter catalog response must include data[]');
+  const data = parsed.data.filter((item): item is OpenRouterModel => Boolean(item && typeof item.id === 'string'));
+  return { ...parsed, data };
+}
+
+function getJson(endpoint: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const url = new URL(endpoint);
+    const req = https.request(
+      {
+        method: 'GET',
+        hostname: url.hostname,
+        path: url.pathname + url.search,
+        headers: { accept: 'application/json' },
+        timeout: 5000,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        res.on('end', () => {
+          const body = Buffer.concat(chunks).toString('utf8');
+          if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+            reject(new Error('OpenRouter catalog fetch failed with HTTP ' + String(res.statusCode)));
+            return;
+          }
+          resolve(body);
+        });
+      },
+    );
+    req.on('error', reject);
+    req.on('timeout', () => req.destroy(new Error('OpenRouter catalog fetch timed out')));
+    req.end();
+  });
+}

package/src/templates/agent-support.yaml

@@ -0,0 +1,30 @@
+# AgentGuard Spend task template: agent-support
+# Local-only policy file. Prompts, completions, API keys, and signing keys stay in the customer runtime.
+id: agent-support-v1
+name: Agent support workflow
+version: 1
+effectiveFrom: "2026-05-27T00:00:00.000Z"
+mode: enforce
+requiredCapability: data_write
+scope:
+  tenantId: my-tenant
+models:
+  primary: openai/gpt-4o-mini
+  fallback: google/gemini-3-flash-preview
+  allowed:
+    - openai/gpt-4o-mini
+    - google/gemini-3-flash-preview
+caps:
+  # WHY: 25 cents per call bounds one agent action while keeping normal work flowing.
+  - amountCents: 25
+    window: per_call
+    action: downgrade
+    downgradeTo: google/gemini-3-flash-preview
+    reason: "Per-call budget reached, routing to fallback model"
+  # WHY: Daily cap catches loops and unexpected traffic before monthly budgets drift.
+  - amountCents: 10000
+    window: per_day
+    action: block
+    reason: "Daily budget reached"
+systemInstructions: |
+  Draft support replies and update allowed fields only after policy checks. Escalate billing, payment, and identity changes.

package/src/templates/chargeback-evidence.yaml

@@ -0,0 +1,30 @@
+# AgentGuard Spend task template: chargeback-evidence
+# Local-only policy file. Prompts, completions, API keys, and signing keys stay in the customer runtime.
+id: chargeback-evidence-v1
+name: Chargeback evidence agent
+version: 1
+effectiveFrom: "2026-05-27T00:00:00.000Z"
+mode: enforce
+requiredCapability: read_only
+scope:
+  tenantId: my-tenant
+models:
+  primary: openai/gpt-5-mini
+  fallback: openai/gpt-4o-mini
+  allowed:
+    - openai/gpt-5-mini
+    - openai/gpt-4o-mini
+caps:
+  # WHY: 100 cents per call bounds one agent action while keeping normal work flowing.
+  - amountCents: 100
+    window: per_call
+    action: downgrade
+    downgradeTo: openai/gpt-4o-mini
+    reason: "Per-call budget reached, routing to fallback model"
+  # WHY: Daily cap catches loops and unexpected traffic before monthly budgets drift.
+  - amountCents: 5000
+    window: per_day
+    action: block
+    reason: "Daily budget reached"
+systemInstructions: |
+  Assemble claim evidence from provided records. Cite source IDs and keep disputed facts separate from verified records.

package/src/templates/code-scan.yaml

@@ -0,0 +1,30 @@
+# AgentGuard Spend task template: code-scan
+# Local-only policy file. Prompts, completions, API keys, and signing keys stay in the customer runtime.
+id: code-scan-v1
+name: Code scan agent
+version: 1
+effectiveFrom: "2026-05-27T00:00:00.000Z"
+mode: enforce
+requiredCapability: read_only
+scope:
+  tenantId: my-tenant
+models:
+  primary: google/gemini-3-flash-preview
+  fallback: openai/gpt-4o-mini
+  allowed:
+    - google/gemini-3-flash-preview
+    - openai/gpt-4o-mini
+caps:
+  # WHY: 10 cents per call bounds one agent action while keeping normal work flowing.
+  - amountCents: 10
+    window: per_call
+    action: downgrade
+    downgradeTo: openai/gpt-4o-mini
+    reason: "Per-call budget reached, routing to fallback model"
+  # WHY: Daily cap catches loops and unexpected traffic before monthly budgets drift.
+  - amountCents: 3000
+    window: per_day
+    action: block
+    reason: "Daily budget reached"
+systemInstructions: |
+  Scan code for spend, audit, and integration risks. Return findings with file paths and minimal fix guidance.