TealMonitor v2

TealMonitor v2 provides governance-owned cost controls — cost limits that cannot be bypassed by application code, anomaly detection that identifies unusual spending patterns, reasoning-token budgets for chain-of-thought models, and per-agent cost attribution for multi-agent systems.

TealMonitor v2 addresses OWASP ASI-06 (Excessive Resource Consumption) — the risk that AI agents consume unbounded compute, token, or API resources through runaway loops, prompt injection, or misconfiguration.

Why This Matters

Risk	Without Governance-Owned Costs	With TealMonitor v2
Budget bypass	Application-level limits can be overridden by code changes	Governance-owned limits enforced below application layer
Cost anomalies	Unusual spending detected only in monthly bills	Real-time anomaly detection with immediate enforcement
Reasoning token explosion	o1/o3 models use unbounded reasoning tokens	Reasoning-token budgets cap hidden compute costs
Attribution gaps	No visibility into which agent drives costs	Per-agent attribution with real-time dashboards
Runaway loops	Agent stuck in loop burns through budget	Velocity detection catches rapid spending

Compliance alignment: NIST AI RMF (GOVERN 2.3 — resource allocation), ISO 42001 (A.6.2.6 — resource management), SOC 2 CC6.6 (system operations).

Class

class TealMonitor {
  constructor(options: MonitorOptions);

  /** Evaluate cost governance for a request */
  evaluate(request: CostRequest, ctx: MonitorContext): Promise<CostDecision>;

  /** Get current spend for an agent */
  getSpend(agentId: string, window?: string): Promise<SpendReport>;

  /** Get cost anomaly status */
  getAnomalyStatus(agentId: string): Promise<AnomalyStatus>;

  /** Record actual cost after completion */
  recordCost(correlationId: string, actualCost: CostRecord): Promise<void>;
}

MonitorOptions

interface MonitorOptions {
  /** Cost limit configuration */
  limits: {
    /** Per-request cost limit (USD) */
    perRequest: number;
    /** Per-session cost limit (USD) */
    perSession?: number;
    /** Daily cost limit per agent (USD) */
    dailyPerAgent: number;
    /** Global daily limit across all agents (USD) */
    dailyGlobal?: number;
    /** Monthly budget cap (USD) */
    monthly?: number;
  };

  /** Reasoning token budget (for o1, o3, etc.) */
  reasoningBudget?: {
    enabled: boolean;
    /** Max reasoning tokens per request */
    maxPerRequest: number;
    /** Max reasoning tokens per session */
    maxPerSession?: number;
    /** Daily reasoning token budget */
    dailyLimit?: number;
  };

  /** Anomaly detection */
  anomalyDetection: {
    enabled: boolean;
    /** Sensitivity (affects false positive rate) */
    sensitivity: 'low' | 'medium' | 'high';
    /** Baseline window for normal spending */
    baselineWindow: string;  // '7d', '30d'
    /** Action on anomaly detection */
    onAnomaly: 'deny' | 'approval_required' | 'monitor';
  };

  /** Per-agent attribution */
  attribution: {
    enabled: boolean;
    /** Group agents by team/department */
    groupBy?: string;  // 'team', 'department', 'environment'
  };

  /** Cost estimation model */
  costModel: {
    /** Provider pricing (tokens → USD) */
    pricing: Record<string, ModelPricing>;
    /** Include reasoning tokens in cost calculation */
    includeReasoningTokens: boolean;
  };
}

interface ModelPricing {
  /** Input token cost per 1M tokens */
  inputPer1M: number;
  /** Output token cost per 1M tokens */
  outputPer1M: number;
  /** Reasoning token cost per 1M tokens (if applicable) */
  reasoningPer1M?: number;
}

evaluate()

Evaluate cost governance before a request is sent to the model.

import { TealMonitor } from 'tealtiger/monitor';

const monitor = new TealMonitor({
  limits: {
    perRequest: 2.00,
    dailyPerAgent: 50.00,
    dailyGlobal: 500.00,
    monthly: 10000.00
  },
  reasoningBudget: {
    enabled: true,
    maxPerRequest: 10000,
    dailyLimit: 100000
  },
  anomalyDetection: {
    enabled: true,
    sensitivity: 'medium',
    baselineWindow: '7d',
    onAnomaly: 'approval_required'
  },
  attribution: { enabled: true, groupBy: 'team' },
  costModel: {
    pricing: {
      'gpt-4o': { inputPer1M: 2.50, outputPer1M: 10.00 },
      'o1': { inputPer1M: 15.00, outputPer1M: 60.00, reasoningPer1M: 60.00 },
      'claude-3.5-sonnet': { inputPer1M: 3.00, outputPer1M: 15.00 }
    },
    includeReasoningTokens: true
  }
});

const decision = await monitor.evaluate(
  {
    model: 'o1',
    estimatedInputTokens: 2000,
    estimatedOutputTokens: 500,
    estimatedReasoningTokens: 8000
  },
  {
    agentId: 'research-bot-001',
    correlation_id: 'req-001',
    sessionId: 'sess-abc'
  }
);

console.log(decision.allowed);              // true
console.log(decision.estimatedCost);        // $0.54
console.log(decision.budgetRemaining);      // { daily: $42.30, monthly: $8,450.00 }
console.log(decision.reasoningTokensUsed);  // 8000 / 10000 per-request budget
console.log(decision.anomalyScore);         // 0.2 (normal)

CostDecision

interface CostDecision {
  /** Whether the request is allowed */
  allowed: boolean;

  /** Estimated cost for this request (USD) */
  estimatedCost: number;

  /** Reason for denial */
  reason_codes?: string[];

  /** Remaining budgets */
  budgetRemaining: {
    perRequest: number;
    daily: number;
    monthly?: number;
    session?: number;
  };

  /** Reasoning token usage */
  reasoningTokensUsed?: number;
  reasoningTokensBudget?: number;

  /** Anomaly detection result */
  anomalyScore: number;
  anomalyFlagged: boolean;

  /** Warnings (approaching limits) */
  warnings?: CostWarning[];
}

interface CostWarning {
  type: 'approaching_daily_limit' | 'approaching_monthly_limit' | 'high_velocity' | 'reasoning_budget_high';
  message: string;
  threshold: number;
  current: number;
}

Cost Anomaly Detection

TealMonitor v2 builds a spending baseline and detects anomalies in real-time:

const anomaly = await monitor.getAnomalyStatus('research-bot-001');

console.log(anomaly.score);           // 0.75 (elevated)
console.log(anomaly.flagged);         // true
console.log(anomaly.baseline);        // { dailyAvg: 12.50, dailyStdDev: 3.20 }
console.log(anomaly.current);         // { todaySpend: 28.40 }
console.log(anomaly.deviations);
// [
//   { dimension: 'daily_spend', zScore: 4.97, explanation: 'Spending 2.3x above daily average' },
//   { dimension: 'request_frequency', zScore: 3.1, explanation: '3x more requests than usual' }
// ]

Anomaly Dimensions

Dimension	What It Tracks
`daily_spend`	Total USD spent today vs. baseline
`request_frequency`	Requests per hour vs. baseline
`cost_per_request`	Average cost per request vs. baseline
`reasoning_tokens`	Reasoning token usage vs. baseline
`model_tier`	Shift toward more expensive models

Reasoning-Token Budgets

For models with hidden reasoning tokens (o1, o3), TealMonitor v2 enforces budgets on the reasoning compute:

const decision = await monitor.evaluate(
  {
    model: 'o1',
    estimatedInputTokens: 1000,
    estimatedOutputTokens: 200,
    estimatedReasoningTokens: 15000  // Exceeds per-request budget of 10000
  },
  { agentId: 'agent-001', correlation_id: 'req-001' }
);

// decision.allowed === false
// decision.reason_codes === ['REASONING_TOKEN_BUDGET_EXCEEDED']
// decision.reasoningTokensUsed === 15000
// decision.reasoningTokensBudget === 10000

Per-Agent Attribution

Track costs per agent with team/department grouping:

// Get spend report for a specific agent
const report = await monitor.getSpend('research-bot-001', '7d');

console.log(report.agentId);          // 'research-bot-001'
console.log(report.period);           // '7d'
console.log(report.totalCost);        // $87.50
console.log(report.byModel);          // { 'gpt-4o': $45.00, 'o1': $42.50 }
console.log(report.byDay);            // [{ date: '2026-06-01', cost: $12.50 }, ...]
console.log(report.requestCount);     // 342
console.log(report.avgCostPerRequest); // $0.26
console.log(report.reasoningTokens);  // 45,000

// Team-level aggregation
const teamReport = await monitor.getSpend('team:ml-research', '30d');
console.log(teamReport.totalCost);    // $2,340.00
console.log(teamReport.agents);       // ['research-bot-001', 'research-bot-002', ...]

Recording Actual Costs

After a request completes, record the actual cost for accurate tracking:

// After model response is received
await monitor.recordCost('req-001', {
  model: 'o1',
  inputTokens: 1850,
  outputTokens: 420,
  reasoningTokens: 7200,
  actualCost: 0.48,
  duration_ms: 3200
});

Integration with TealEngine

import { TealEngine, TealMonitor } from 'tealtiger';

const engine = new TealEngine({
  policy: {
    monitor: {
      limits: { perRequest: 2.00, dailyPerAgent: 50.00 },
      reasoningBudget: { enabled: true, maxPerRequest: 10000 },
      anomalyDetection: { enabled: true, sensitivity: 'medium', onAnomaly: 'approval_required' }
    }
  },
  modules: [new TealMonitor({ /* full config */ })]
});

TealEngine v1.3 API — Engine integration
TealTemporal — Rate limiting complements cost limits
TealDrift — Cost velocity as drift signal
SOC/IR Pipeline — Cost anomaly alerts in SIEM
Automation Levels — approval_required for cost anomalies

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Why This Matters

Class

MonitorOptions

evaluate()

CostDecision

Cost Anomaly Detection

Anomaly Dimensions

Reasoning-Token Budgets

Per-Agent Attribution

Recording Actual Costs

Integration with TealEngine

​Why This Matters

​Class

​MonitorOptions

​evaluate()

​CostDecision

​Cost Anomaly Detection

​Anomaly Dimensions

​Reasoning-Token Budgets

​Per-Agent Attribution

​Recording Actual Costs

​Integration with TealEngine

​Related Documentation

Why This Matters

Class

MonitorOptions

evaluate()

CostDecision

Cost Anomaly Detection

Anomaly Dimensions

Reasoning-Token Budgets

Per-Agent Attribution

Recording Actual Costs

Integration with TealEngine

Related Documentation