proffesor-for-testing__agentic-qe/docs/implementation/specs/SPEC-042-A-token-tracking-schema.md

SPEC-042-A: Token Tracking Schema

Field	Value
Specification ID	SPEC-042-A
Parent ADR	ADR-042
Version	1.0
Status	Implemented
Last Updated	2026-01-14
Author	Claude Code

---

Overview

Defines the data structures for token tracking across V3 QE agents, including per-task metrics, agent aggregations, domain breakdowns, and session summaries with optimization statistics.

---

Specification Details

Section 1: Core Token Interfaces

// v3/src/learning/token-tracker.ts

export interface TokenUsage {
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  estimatedCostUsd?: number;
}

export interface TaskTokenMetric {
  taskId: string;
  agentId: string;
  domain: DomainName;
  operation: string;
  timestamp: number;
  usage: TokenUsage;
  patternReused: boolean;      // Was a cached pattern used?
  tokensSaved?: number;        // Estimated tokens saved via caching
}

export interface AgentTokenMetrics {
  agentId: string;
  totalInputTokens: number;
  totalOutputTokens: number;
  totalTokens: number;
  totalCost: number;
  tasksExecuted: number;
  patternsReused: number;      // How many times we skipped LLM calls
  estimatedTokensSaved: number;
}

Section 2: Session Summary

export interface SessionTokenSummary {
  sessionId: string;
  startTime: number;
  endTime?: number;
  byAgent: Map<string, AgentTokenMetrics>;
  byDomain: Map<DomainName, TokenUsage>;
  totalUsage: TokenUsage;
  optimizationStats: {
    patternsReused: number;
    cacheHits: number;
    earlyExits: number;
    tokensSaved: number;
    savingsPercentage: number;
  };
}

Section 3: Extended QE Pattern

// Update v3/src/learning/qe-patterns.ts

export interface QEPattern {
  id: string;
  // ... existing fields ...

  // Token tracking fields (from agentic-flow)
  tokensUsed?: number;
  inputTokens?: number;
  outputTokens?: number;
  latencyMs?: number;

  // Optimization metadata
  reusable: boolean;           // Can this pattern be reused?
  reuseCount: number;          // How many times it's been reused
  averageTokenSavings: number; // Avg tokens saved when reused
}

Section 4: Pattern Store Configuration

export interface PatternStoreConfig {
  // Token optimization config
  tokenTracking: {
    enabled: boolean;
    trackInputOutput: boolean;    // Track input/output separately
    estimateCosts: boolean;       // Calculate cost estimates
    costPerInputToken: number;    // e.g., 0.003 / 1000
    costPerOutputToken: number;   // e.g., 0.015 / 1000
  };

  // Reuse optimization config
  reuseOptimization: {
    enabled: boolean;
    minSimilarityForReuse: number;  // e.g., 0.85
    minSuccessRateForReuse: number; // e.g., 0.90
    maxAgeForReuse: number;         // e.g., 7 days
  };
}

export interface PatternSearchResult {
  pattern: QEPattern;
  similarity: number;
  canReuse: boolean;
  estimatedTokenSavings: number;
  reuseConfidence: number;
}

Section 5: Metrics Collector Integration

// Update v3/src/mcp/metrics/metrics-collector.ts

export interface TaskMetric {
  taskId: string;
  agentId: string;
  startTime: [number, number];
  endTime?: [number, number];
  durationMs?: number;
  success: boolean;
  retries: number;

  // Token tracking
  tokenUsage?: TokenUsage;
  patternReused?: boolean;
  tokensSaved?: number;
}

class MetricsCollectorImpl {
  recordTokenUsage(taskId: string, usage: TokenUsage): void {
    const task = this.completedTasks.get(taskId);
    if (task) {
      task.tokenUsage = usage;
      this.updateAgentTokenMetrics(task.agentId, usage);
      this.updateDomainTokenMetrics(task.domain, usage);
    }
  }

  recordPatternReuse(taskId: string, tokensSaved: number): void {
    const task = this.completedTasks.get(taskId);
    if (task) {
      task.patternReused = true;
      task.tokensSaved = tokensSaved;
      this.totalTokensSaved += tokensSaved;
    }
  }

  getTokenEfficiency(): TokenEfficiencyReport {
    return {
      totalTokensUsed: this.totalTokens,
      totalTokensSaved: this.totalTokensSaved,
      savingsPercentage: (this.totalTokensSaved /
        (this.totalTokens + this.totalTokensSaved)) * 100,
      patternReuseRate: this.patternsReused / this.totalTasks,
      averageTokensPerTask: this.totalTokens / this.totalTasks
    };
  }
}

---

Validation Rules

Rule ID	Description	Severity
SPEC-042-A-001	TokenUsage.totalTokens must equal inputTokens + outputTokens	Error
SPEC-042-A-002	estimatedCostUsd must be non-negative when present	Error
SPEC-042-A-003	patternReused true requires tokensSaved > 0	Warning

---

Related Specifications

Spec ID	Title	Relationship
SPEC-042-B	Reduction Strategies	Uses these schemas
SPEC-042-C	MCP Tools and CLI	Exposes these metrics

---

Changelog

Version	Date	Author	Changes
1.0	2026-01-14	Claude Code	Initial specification

---

References

• Parent ADR
• agentic-flow Token Efficiency Docs