@agentguard-run/spend 0.3.0 → 0.4.0

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

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

package/src/coach/conversation.ts

@@ -0,0 +1,248 @@
+/**
+ * AgentGuard(TM) Spend: Coach conversation state.
+ *
+ * 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 type { CapabilityTier, SpendCap, SpendPolicy } from '../types';
+
+export type CoachQuestionId = 'building' | 'scale' | 'tasks' | 'budget' | 'confirm';
+
+export interface CoachQuestion {
+  id: CoachQuestionId;
+  prompt: string;
+}
+
+export interface CoachAnswers {
+  building?: string;
+  scale?: string;
+  tasks?: string;
+  budget?: string;
+  confirm?: string;
+  language?: 'ts' | 'py';
+}
+
+export interface CoachBusinessProfile {
+  vertical: string;
+  tenantId: string;
+  teamSize: number;
+  monthlyVolume: number;
+  tasks: string[];
+  monthlyBudgetCents: number;
+  requiredCapability: CapabilityTier;
+  primaryModel: string;
+  fallbackModel: string;
+  perCallCapCents: number;
+  perDayCapCents: number;
+  perMonthCapCents: number;
+  scopeLabel: string;
+  language: 'ts' | 'py';
+}
+
+export interface ProjectedSavingsRow {
+  label: string;
+  beforeCents: number;
+  afterCents: number;
+  savingsCents: number;
+}
+
+export interface ProjectedSavings {
+  rows: ProjectedSavingsRow[];
+  monthlyBeforeCents: number;
+  monthlyAfterCents: number;
+  monthlySavingsCents: number;
+  savingsPercent: number;
+}
+
+export const COACH_QUESTIONS: CoachQuestion[] = [
+  { id: 'building', prompt: 'What are you building or running? Include your business type and the agent workflow.' },
+  { id: 'scale', prompt: 'How big is the team and roughly how many AI calls, tickets, orders, encounters, matters, or jobs happen per month?' },
+  { id: 'tasks', prompt: 'What are the top 3 AI tasks this agent will perform?' },
+  { id: 'budget', prompt: 'What monthly AI budget or per-task ceiling should this stay under?' },
+  { id: 'confirm', prompt: 'Confirm the setup or list any refinements before I write policy.yaml and quickstart code.' },
+];
+
+const VERTICAL_HINTS: Array<{ vertical: string; needles: string[]; scopeLabel: string; capability: CapabilityTier; primary: string; fallback: string; perCall: number }> = [
+  { vertical: 'law-firm', needles: ['law', 'legal', 'attorney', 'paralegal', 'contract', 'matter', 'discovery'], scopeLabel: 'matter', capability: 'data_write', primary: 'anthropic/claude-sonnet-4-6', fallback: 'anthropic/claude-haiku-4-5', perCall: 300 },
+  { vertical: 'healthcare', needles: ['health', 'medical', 'dental', 'clinic', 'patient', 'chart', 'hipaa', 'encounter'], scopeLabel: 'encounter', capability: 'data_write', primary: 'anthropic.claude-sonnet-4-v1:0', fallback: 'amazon.nova-lite-v1:0', perCall: 300 },
+  { vertical: 'ecommerce', needles: ['shopify', 'commerce', 'store', 'order', 'refund', 'chargeback', 'fraud', 'returns'], scopeLabel: 'order', capability: 'payment_initiate', primary: 'openai/gpt-5-mini', fallback: 'openai/gpt-4o-mini', perCall: 25 },
+  { vertical: 'accounting', needles: ['accounting', 'bookkeeping', 'tax', 'ledger', 'receipt', 'close', 'audit', 'sox'], scopeLabel: 'engagement', capability: 'data_write', primary: 'anthropic/claude-sonnet-4-6', fallback: 'anthropic/claude-haiku-4-5', perCall: 150 },
+  { vertical: 'software', needles: ['software', 'code', 'developer', 'github', 'repo', 'pull request', 'pr'], scopeLabel: 'repo', capability: 'read_only', primary: 'google/gemini-3-flash-preview', fallback: 'openai/gpt-4o-mini', perCall: 10 },
+  { vertical: 'real-estate', needles: ['real estate', 'broker', 'listing', 'mortgage', 'tenant', 'lease', 'property'], scopeLabel: 'transaction', capability: 'data_write', primary: 'openai/gpt-5-mini', fallback: 'openai/gpt-4o-mini', perCall: 50 },
+  { vertical: 'marketing', needles: ['marketing', 'agency', 'content', 'campaign', 'brand'], scopeLabel: 'campaign', capability: 'data_write', primary: 'openai/gpt-5-mini', fallback: 'openai/gpt-4o-mini', perCall: 25 },
+  { vertical: 'local-services', needles: ['salon', 'gym', 'restaurant', 'landscaping', 'construction', 'photography', 'fitness', 'pet'], scopeLabel: 'job', capability: 'data_write', primary: 'openai/gpt-5-mini', fallback: 'openai/gpt-4o-mini', perCall: 25 },
+];
+
+export class CoachConversation {
+  private answers: CoachAnswers = {};
+  private index = 0;
+
+  constructor(initial?: CoachAnswers) {
+    if (initial) this.answers = { ...initial };
+    this.index = firstMissingIndex(this.answers);
+  }
+
+  currentQuestion(): CoachQuestion | null {
+    return COACH_QUESTIONS[this.index] ?? null;
+  }
+
+  answer(value: string): void {
+    const question = this.currentQuestion();
+    if (!question) return;
+    this.answers[question.id] = value.trim();
+  }
+
+  next(): CoachQuestion | null {
+    this.index = Math.min(this.index + 1, COACH_QUESTIONS.length);
+    return this.currentQuestion();
+  }
+
+  back(): CoachQuestion | null {
+    this.index = Math.max(0, this.index - 1);
+    return this.currentQuestion();
+  }
+
+  isComplete(): boolean {
+    return COACH_QUESTIONS.every((question) => Boolean(this.answers[question.id]?.trim()));
+  }
+
+  snapshot(): CoachAnswers {
+    return { ...this.answers };
+  }
+
+  profile(cwd = process.cwd()): CoachBusinessProfile {
+    return buildBusinessProfile(this.answers, cwd);
+  }
+}
+
+export function buildBusinessProfile(answers: CoachAnswers, cwd = process.cwd()): CoachBusinessProfile {
+  const joined = `${answers.building ?? ''} ${answers.scale ?? ''} ${answers.tasks ?? ''}`.toLowerCase();
+  const hint = VERTICAL_HINTS.find((candidate) => candidate.needles.some((needle) => joined.includes(needle))) ?? VERTICAL_HINTS[0]!;
+  const scale = parseScale(answers.scale ?? '');
+  const budgetCents = parseBudgetCents(answers.budget ?? '', Math.max(4900, Math.ceil(scale.monthlyVolume * hint.perCall * 0.35)));
+  const tasks = parseTasks(answers.tasks ?? answers.building ?? hint.vertical);
+  const perMonthCapCents = Math.max(1000, budgetCents);
+  const perDayCapCents = Math.max(hint.perCall * 10, Math.ceil(perMonthCapCents / 20));
+  return {
+    vertical: hint.vertical,
+    tenantId: tenantIdFromBusiness(answers.building ?? hint.vertical),
+    teamSize: scale.teamSize,
+    monthlyVolume: scale.monthlyVolume,
+    tasks,
+    monthlyBudgetCents: perMonthCapCents,
+    requiredCapability: capabilityFor(joined, hint.capability),
+    primaryModel: hint.primary,
+    fallbackModel: hint.fallback,
+    perCallCapCents: hint.perCall,
+    perDayCapCents,
+    perMonthCapCents,
+    scopeLabel: hint.scopeLabel,
+    language: answers.language ?? detectProjectLanguage(cwd),
+  };
+}
+
+export function buildPolicyFromProfile(profile: CoachBusinessProfile): SpendPolicy {
+  const caps: SpendCap[] = [
+    {
+      amountCents: profile.perCallCapCents,
+      window: 'per_call',
+      action: 'downgrade',
+      downgradeTo: profile.fallbackModel,
+      reason: 'Per-call budget reached, route to fallback model',
+    },
+    {
+      amountCents: profile.perDayCapCents,
+      window: 'per_day',
+      action: 'block',
+      reason: 'Daily budget reached',
+    },
+    {
+      amountCents: profile.perMonthCapCents,
+      window: 'per_month',
+      action: 'block',
+      reason: 'Monthly budget reached',
+    },
+  ];
+  return {
+    id: `coach-${profile.vertical}-v1`,
+    name: `Coach generated ${profile.vertical} policy`,
+    scope: { tenantId: profile.tenantId },
+    caps,
+    mode: 'enforce',
+    requiredCapability: profile.requiredCapability,
+    version: 1,
+    effectiveFrom: new Date().toISOString(),
+  };
+}
+
+export function projectedSavings(profile: CoachBusinessProfile): ProjectedSavings {
+  const heavyPerCall = Math.max(profile.perCallCapCents * 4, 100);
+  const routedPerCall = Math.max(1, Math.ceil(profile.perCallCapCents * 0.45));
+  const monthlyBeforeCents = profile.monthlyVolume * heavyPerCall;
+  const monthlyAfterCents = Math.min(profile.perMonthCapCents, profile.monthlyVolume * routedPerCall);
+  const monthlySavingsCents = Math.max(0, monthlyBeforeCents - monthlyAfterCents);
+  return {
+    rows: [
+      { label: 'All traffic on premium model', beforeCents: monthlyBeforeCents, afterCents: 0, savingsCents: 0 },
+      { label: 'Task routed with AgentGuard caps', beforeCents: 0, afterCents: monthlyAfterCents, savingsCents: monthlySavingsCents },
+    ],
+    monthlyBeforeCents,
+    monthlyAfterCents,
+    monthlySavingsCents,
+    savingsPercent: monthlyBeforeCents > 0 ? Math.round((monthlySavingsCents / monthlyBeforeCents) * 100) : 0,
+  };
+}
+
+export function formatCents(cents: number): string {
+  return `$${(cents / 100).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+export function detectProjectLanguage(cwd: string): 'ts' | 'py' {
+  try {
+    if (fs.existsSync(path.join(cwd, 'pyproject.toml')) || fs.existsSync(path.join(cwd, 'requirements.txt'))) return 'py';
+    if (fs.existsSync(path.join(cwd, 'package.json'))) return 'ts';
+  } catch {
+    return 'ts';
+  }
+  return 'ts';
+}
+
+function firstMissingIndex(answers: CoachAnswers): number {
+  const index = COACH_QUESTIONS.findIndex((question) => !answers[question.id]?.trim());
+  return index === -1 ? COACH_QUESTIONS.length : index;
+}
+
+function parseScale(value: string): { teamSize: number; monthlyVolume: number } {
+  const numbers = (value.match(/\d[\d,]*/g) ?? []).map((part) => Number(part.replace(/,/g, ''))).filter(Number.isFinite);
+  const teamSize = Math.max(1, numbers[0] ?? 3);
+  const monthlyVolume = Math.max(25, numbers[1] ?? numbers[0] ?? 500);
+  return { teamSize, monthlyVolume };
+}
+
+function parseBudgetCents(value: string, fallback: number): number {
+  const money = value.match(/\$?\s*(\d[\d,]*(?:\.\d{1,2})?)/);
+  if (!money) return fallback;
+  const amount = Number(money[1]!.replace(/,/g, ''));
+  if (!Number.isFinite(amount) || amount <= 0) return fallback;
+  return Math.round(amount * 100);
+}
+
+function parseTasks(value: string): string[] {
+  const parts = value.split(/,|\n|;| and /i).map((part) => part.trim()).filter(Boolean);
+  return parts.length > 0 ? parts.slice(0, 3) : ['review requests', 'route models', 'write audit receipts'];
+}
+
+function tenantIdFromBusiness(value: string): string {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+  return cleaned || 'local-business';
+}
+
+function capabilityFor(text: string, fallback: CapabilityTier): CapabilityTier {
+  if (/refund|payment|charge|dispute|money|invoice/.test(text)) return 'payment_initiate';
+  if (/write|update|ledger|chart|patient|health|phi|sox|legal|contract|tax|student|employment/.test(text)) return 'data_write';
+  return fallback;
+}

package/src/coach/forecast.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentGuard(TM) Spend: local Coach forecast 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 type { CoachSpendPoint } from './anomaly';
+
+export interface CoachForecast {
+  daysObserved: number;
+  monthEndCents: number;
+  capCents: number | null;
+  overCap: boolean;
+  message: string;
+}
+
+export function forecastMonthEnd(points: CoachSpendPoint[], capCents: number | null = null, now = new Date()): CoachForecast {
+  const daily = lastThirtyDaily(points, now);
+  if (daily.length === 0) {
+    return { daysObserved: 0, monthEndCents: 0, capCents, overCap: false, message: 'No local spend history found.' };
+  }
+  const slope = linearSlope(daily.map((row, index) => ({ x: index + 1, y: row.cents })));
+  const monthDays = new Date(now.getFullYear(), now.getMonth() + 1, 0).getDate();
+  const elapsed = now.getDate();
+  const observedTotal = daily.reduce((sum, row) => sum + row.cents, 0);
+  const avg = observedTotal / Math.max(1, daily.length);
+  const projectedRemaining = Math.max(0, monthDays - elapsed) * Math.max(0, avg + slope);
+  const monthEndCents = Math.round(observedTotal + projectedRemaining);
+  const overCap = capCents !== null && monthEndCents > capCents;
+  return {
+    daysObserved: daily.length,
+    monthEndCents,
+    capCents,
+    overCap,
+    message: overCap ? 'Projected spend is above cap. Consider a lower fallback model or a tighter per_day cap.' : 'Projected spend is within the current cap.',
+  };
+}
+
+function lastThirtyDaily(points: CoachSpendPoint[], now: Date): Array<{ day: string; cents: number }> {
+  const cutoff = now.getTime() - 30 * 24 * 60 * 60 * 1000;
+  const buckets = new Map<string, number>();
+  for (const point of points) {
+    const t = Date.parse(point.ts);
+    if (!Number.isFinite(t) || t < cutoff) continue;
+    const day = new Date(t).toISOString().slice(0, 10);
+    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 linearSlope(points: Array<{ x: number; y: number }>): number {
+  if (points.length < 2) return 0;
+  const n = points.length;
+  const sx = points.reduce((sum, point) => sum + point.x, 0);
+  const sy = points.reduce((sum, point) => sum + point.y, 0);
+  const sxx = points.reduce((sum, point) => sum + point.x * point.x, 0);
+  const sxy = points.reduce((sum, point) => sum + point.x * point.y, 0);
+  const denom = n * sxx - sx * sx;
+  return denom === 0 ? 0 : (n * sxy - sx * sy) / denom;
+}