@holoscript/framework 6.0.3

package/src/economy/UsageMeter.ts

@@ -0,0 +1,440 @@
+/**
+ * UsageMeter — Per-tool-call cost tracking and aggregation
+ *
+ * Tracks usage across agents, tools, and time periods.
+ * Supports free-tier allowances and paid overage tracking.
+ *
+ * Part of HoloScript v5.8 "Live Economy".
+ *
+ * @version 1.0.0
+ */
+
+import type { TelemetryCollector } from './_core-stubs';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Aggregation period for usage data.
+ */
+export type UsagePeriod = 'hourly' | 'daily' | 'monthly';
+
+/**
+ * A single usage event.
+ */
+export interface UsageEvent {
+  /** Unique event ID */
+  id: string;
+  /** Agent that made the call */
+  agentId: string;
+  /** Tool that was called */
+  toolId: string;
+  /** Cost in USDC base units (6 decimals) */
+  cost: number;
+  /** Timestamp (ms since epoch) */
+  timestamp: number;
+  /** Whether this falls under free tier */
+  freeTier: boolean;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Aggregated usage for a specific dimension.
+ */
+export interface UsageAggregate {
+  /** Total number of calls */
+  totalCalls: number;
+  /** Total cost in USDC base units */
+  totalCost: number;
+  /** Free-tier calls */
+  freeTierCalls: number;
+  /** Free-tier cost (not charged) */
+  freeTierCost: number;
+  /** Paid calls */
+  paidCalls: number;
+  /** Paid cost (actually charged) */
+  paidCost: number;
+  /** Period start (ISO 8601) */
+  periodStart: string;
+  /** Period end (ISO 8601) */
+  periodEnd: string;
+}
+
+/**
+ * Usage summary for an agent.
+ */
+export interface AgentUsageSummary {
+  /** Agent ID */
+  agentId: string;
+  /** Per-tool usage breakdown */
+  byTool: Map<string, UsageAggregate>;
+  /** Total across all tools */
+  total: UsageAggregate;
+  /** Free-tier remaining allowance */
+  freeTierRemaining: number;
+}
+
+/**
+ * Free-tier configuration.
+ */
+export interface FreeTierConfig {
+  /** Monthly free-tier allowance in USDC base units */
+  monthlyAllowance: number;
+  /** Per-tool overrides */
+  toolOverrides?: Record<string, number>;
+}
+
+/**
+ * UsageMeter configuration.
+ */
+export interface UsageMeterConfig {
+  /** Free-tier configuration */
+  freeTier?: FreeTierConfig;
+  /** Default cost per tool call (USDC base units) */
+  defaultToolCost?: number;
+  /** Per-tool cost overrides */
+  toolCosts?: Record<string, number>;
+  /** Maximum events to retain per agent */
+  maxEventsPerAgent?: number;
+  /** Telemetry collector */
+  telemetry?: TelemetryCollector;
+}
+
+// =============================================================================
+// USAGE METER
+// =============================================================================
+
+export class UsageMeter {
+  private config: Required<Omit<UsageMeterConfig, 'telemetry' | 'freeTier' | 'toolCosts'>> & {
+    telemetry?: TelemetryCollector;
+    freeTier: FreeTierConfig;
+    toolCosts: Record<string, number>;
+  };
+
+  /** All usage events keyed by agentId */
+  private events: Map<string, UsageEvent[]> = new Map();
+
+  /** Free-tier consumption per agent (monthly, USDC base units) */
+  private freeTierUsed: Map<string, number> = new Map();
+
+  /** Current month key for free-tier reset */
+  private currentMonthKey: string;
+
+  private eventCounter = 0;
+
+  constructor(config?: UsageMeterConfig) {
+    this.config = {
+      freeTier: config?.freeTier ?? { monthlyAllowance: 500_000 }, // $0.50 free
+      defaultToolCost: config?.defaultToolCost ?? 100, // $0.0001
+      toolCosts: config?.toolCosts ?? {},
+      maxEventsPerAgent: config?.maxEventsPerAgent ?? 10000,
+      telemetry: config?.telemetry,
+    };
+    this.currentMonthKey = this.getMonthKey(Date.now());
+  }
+
+  // ===========================================================================
+  // RECORDING
+  // ===========================================================================
+
+  /**
+   * Record a tool call usage event.
+   */
+  recordUsage(agentId: string, toolId: string, metadata?: Record<string, unknown>): UsageEvent {
+    // Reset free-tier if month changed
+    this.checkMonthReset();
+
+    const cost = this.getToolCost(toolId);
+    const freeTierUsed = this.freeTierUsed.get(agentId) ?? 0;
+    const freeTierRemaining = Math.max(0, this.config.freeTier.monthlyAllowance - freeTierUsed);
+    const isFreeTier = cost <= freeTierRemaining;
+
+    if (isFreeTier) {
+      this.freeTierUsed.set(agentId, freeTierUsed + cost);
+    }
+
+    const event: UsageEvent = {
+      id: `usage-${++this.eventCounter}`,
+      agentId,
+      toolId,
+      cost,
+      timestamp: Date.now(),
+      freeTier: isFreeTier,
+      metadata,
+    };
+
+    // Store event
+    const agentEvents = this.events.get(agentId) ?? [];
+    agentEvents.push(event);
+
+    // Trim if too many
+    if (agentEvents.length > this.config.maxEventsPerAgent) {
+      agentEvents.splice(0, agentEvents.length - this.config.maxEventsPerAgent);
+    }
+
+    this.events.set(agentId, agentEvents);
+
+    this.emitTelemetry('usage_recorded', {
+      agentId,
+      toolId,
+      cost,
+      freeTier: isFreeTier,
+    });
+
+    return event;
+  }
+
+  // ===========================================================================
+  // COST LOOKUP
+  // ===========================================================================
+
+  /**
+   * Get the cost for a specific tool.
+   */
+  getToolCost(toolId: string): number {
+    // Check tool-specific override first
+    if (this.config.toolCosts[toolId] !== undefined) {
+      return this.config.toolCosts[toolId];
+    }
+    // Check free-tier tool overrides
+    if (this.config.freeTier.toolOverrides?.[toolId] !== undefined) {
+      return this.config.freeTier.toolOverrides[toolId];
+    }
+    return this.config.defaultToolCost;
+  }
+
+  /**
+   * Set cost for a specific tool.
+   */
+  setToolCost(toolId: string, cost: number): void {
+    this.config.toolCosts[toolId] = cost;
+  }
+
+  // ===========================================================================
+  // AGGREGATION
+  // ===========================================================================
+
+  /**
+   * Get usage summary for an agent within a time period.
+   */
+  getAgentUsage(agentId: string, period: UsagePeriod = 'monthly'): AgentUsageSummary {
+    const events = this.events.get(agentId) ?? [];
+    const { start, end } = this.getPeriodBounds(period);
+    const filtered = events.filter((e) => e.timestamp >= start && e.timestamp < end);
+
+    const byTool = new Map<string, UsageAggregate>();
+
+    const totalAgg: UsageAggregate = {
+      totalCalls: 0,
+      totalCost: 0,
+      freeTierCalls: 0,
+      freeTierCost: 0,
+      paidCalls: 0,
+      paidCost: 0,
+      periodStart: new Date(start).toISOString(),
+      periodEnd: new Date(end).toISOString(),
+    };
+
+    for (const event of filtered) {
+      // Per-tool aggregate
+      let toolAgg = byTool.get(event.toolId);
+      if (!toolAgg) {
+        toolAgg = {
+          totalCalls: 0,
+          totalCost: 0,
+          freeTierCalls: 0,
+          freeTierCost: 0,
+          paidCalls: 0,
+          paidCost: 0,
+          periodStart: new Date(start).toISOString(),
+          periodEnd: new Date(end).toISOString(),
+        };
+        byTool.set(event.toolId, toolAgg);
+      }
+
+      toolAgg.totalCalls++;
+      toolAgg.totalCost += event.cost;
+      totalAgg.totalCalls++;
+      totalAgg.totalCost += event.cost;
+
+      if (event.freeTier) {
+        toolAgg.freeTierCalls++;
+        toolAgg.freeTierCost += event.cost;
+        totalAgg.freeTierCalls++;
+        totalAgg.freeTierCost += event.cost;
+      } else {
+        toolAgg.paidCalls++;
+        toolAgg.paidCost += event.cost;
+        totalAgg.paidCalls++;
+        totalAgg.paidCost += event.cost;
+      }
+    }
+
+    const freeTierUsed = this.freeTierUsed.get(agentId) ?? 0;
+    const freeTierRemaining = Math.max(0, this.config.freeTier.monthlyAllowance - freeTierUsed);
+
+    return {
+      agentId,
+      byTool,
+      total: totalAgg,
+      freeTierRemaining,
+    };
+  }
+
+  /**
+   * Get aggregated usage across all agents for a period.
+   */
+  getGlobalUsage(period: UsagePeriod = 'monthly'): UsageAggregate {
+    const { start, end } = this.getPeriodBounds(period);
+    const agg: UsageAggregate = {
+      totalCalls: 0,
+      totalCost: 0,
+      freeTierCalls: 0,
+      freeTierCost: 0,
+      paidCalls: 0,
+      paidCost: 0,
+      periodStart: new Date(start).toISOString(),
+      periodEnd: new Date(end).toISOString(),
+    };
+
+    for (const events of this.events.values()) {
+      for (const event of events) {
+        if (event.timestamp >= start && event.timestamp < end) {
+          agg.totalCalls++;
+          agg.totalCost += event.cost;
+          if (event.freeTier) {
+            agg.freeTierCalls++;
+            agg.freeTierCost += event.cost;
+          } else {
+            agg.paidCalls++;
+            agg.paidCost += event.cost;
+          }
+        }
+      }
+    }
+
+    return agg;
+  }
+
+  /**
+   * Get top tools by usage cost.
+   */
+  getTopTools(
+    period: UsagePeriod = 'monthly',
+    limit = 10
+  ): Array<{ toolId: string; calls: number; cost: number }> {
+    const { start, end } = this.getPeriodBounds(period);
+    const toolMap = new Map<string, { calls: number; cost: number }>();
+
+    for (const events of this.events.values()) {
+      for (const event of events) {
+        if (event.timestamp >= start && event.timestamp < end) {
+          const existing = toolMap.get(event.toolId) ?? { calls: 0, cost: 0 };
+          existing.calls++;
+          existing.cost += event.cost;
+          toolMap.set(event.toolId, existing);
+        }
+      }
+    }
+
+    return [...toolMap.entries()]
+      .map(([toolId, data]) => ({ toolId, ...data }))
+      .sort((a, b) => b.cost - a.cost)
+      .slice(0, limit);
+  }
+
+  // ===========================================================================
+  // FREE TIER
+  // ===========================================================================
+
+  /**
+   * Get free-tier remaining for an agent.
+   */
+  getFreeTierRemaining(agentId: string): number {
+    this.checkMonthReset();
+    const used = this.freeTierUsed.get(agentId) ?? 0;
+    return Math.max(0, this.config.freeTier.monthlyAllowance - used);
+  }
+
+  /**
+   * Check if an agent has exceeded their free tier.
+   */
+  isOverFreeTier(agentId: string): boolean {
+    return this.getFreeTierRemaining(agentId) === 0;
+  }
+
+  // ===========================================================================
+  // QUERIES
+  // ===========================================================================
+
+  /**
+   * Get all tracked agent IDs.
+   */
+  getTrackedAgents(): string[] {
+    return [...this.events.keys()];
+  }
+
+  /**
+   * Get raw events for an agent.
+   */
+  getEvents(agentId: string): UsageEvent[] {
+    return [...(this.events.get(agentId) ?? [])];
+  }
+
+  /**
+   * Get total number of recorded events.
+   */
+  getTotalEventCount(): number {
+    let total = 0;
+    for (const events of this.events.values()) {
+      total += events.length;
+    }
+    return total;
+  }
+
+  // ===========================================================================
+  // INTERNALS
+  // ===========================================================================
+
+  private getMonthKey(timestamp: number): string {
+    const d = new Date(timestamp);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+  }
+
+  private checkMonthReset(): void {
+    const currentKey = this.getMonthKey(Date.now());
+    if (currentKey !== this.currentMonthKey) {
+      this.freeTierUsed.clear();
+      this.currentMonthKey = currentKey;
+    }
+  }
+
+  private getPeriodBounds(period: UsagePeriod): { start: number; end: number } {
+    const now = new Date();
+    let start: Date;
+
+    switch (period) {
+      case 'hourly':
+        start = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours());
+        return { start: start.getTime(), end: start.getTime() + 3600_000 };
+      case 'daily':
+        start = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+        return { start: start.getTime(), end: start.getTime() + 86400_000 };
+      case 'monthly':
+        start = new Date(now.getFullYear(), now.getMonth(), 1);
+        const nextMonth = new Date(now.getFullYear(), now.getMonth() + 1, 1);
+        return { start: start.getTime(), end: nextMonth.getTime() };
+    }
+  }
+
+  private emitTelemetry(type: string, data?: Record<string, unknown>): void {
+    this.config.telemetry?.record({
+      type,
+      severity: 'info',
+      agentId: 'usage-meter',
+      data,
+    });
+  }
+}

package/src/economy/_core-stubs.ts

@@ -0,0 +1,219 @@
+/**
+ * Type stubs for @holoscript/core types used by economy module.
+ * Copied from core to avoid cross-package DTS resolution failures.
+ * The real types come from @holoscript/core at runtime.
+ *
+ * Source: packages/core/src/compiler/safety/ResourceBudgetAnalyzer.ts
+ * Source: packages/core/src/debug/TelemetryCollector.ts
+ */
+
+// =============================================================================
+// TelemetryCollector (from core/debug/TelemetryCollector.ts)
+// =============================================================================
+
+export interface TelemetryCollector {
+  record(event: Record<string, unknown>): unknown;
+  recordEvent(
+    type: string,
+    agentId: string,
+    data?: Record<string, unknown>,
+    severity?: string,
+  ): unknown;
+  recordError(agentId: string, error: Error, context?: Record<string, unknown>): unknown;
+  startSpan(name: string, options?: Record<string, unknown>): unknown;
+  endSpan(spanId: string, status?: string, statusMessage?: string): unknown;
+  flush(): Promise<void>;
+  getStats(): Record<string, unknown>;
+  setEnabled(enabled: boolean): void;
+  configure(config: Record<string, unknown>): void;
+  clear(): void;
+  destroy(): void;
+}
+
+// =============================================================================
+// ResourceBudgetAnalyzer types (from core/compiler/safety/ResourceBudgetAnalyzer.ts)
+// =============================================================================
+
+export interface ResourceBudgetConfig {
+  maxTokens?: number;
+  maxConcurrency?: number;
+  maxCostUSD?: number;
+  warningThresholdPercent?: number;
+}
+
+export interface BudgetStatus {
+  tokensUsed: number;
+  tokensRemaining: number;
+  costUSD: number;
+  utilizationPercent: number;
+  isOverBudget: boolean;
+}
+
+export interface ResourceBudgetAnalyzer {
+  checkBudget(config: ResourceBudgetConfig): BudgetStatus;
+}
+
+/** Resource categories tracked by the budget analyzer */
+export type ResourceCategory =
+  | 'particles'
+  | 'physicsBodies'
+  | 'audioSources'
+  | 'meshInstances'
+  | 'gaussians'
+  | 'shaderPasses'
+  | 'networkMsgs'
+  | 'agentCount'
+  | 'memoryMB'
+  | 'gpuDrawCalls';
+
+/** Pre-defined platform budgets (exact shape from core) */
+export const PLATFORM_BUDGETS: Record<string, Partial<Record<ResourceCategory, number>>> = {
+  quest3: {
+    particles: 5000,
+    physicsBodies: 200,
+    audioSources: 16,
+    meshInstances: 500,
+    gaussians: 180_000,
+    shaderPasses: 4,
+    networkMsgs: 60,
+    agentCount: 10,
+    memoryMB: 512,
+    gpuDrawCalls: 200,
+  },
+  'desktop-vr': {
+    particles: 50000,
+    physicsBodies: 2000,
+    audioSources: 64,
+    meshInstances: 5000,
+    gaussians: 2_000_000,
+    shaderPasses: 16,
+    networkMsgs: 200,
+    agentCount: 50,
+    memoryMB: 4096,
+    gpuDrawCalls: 2000,
+  },
+  webgpu: {
+    particles: 20000,
+    physicsBodies: 500,
+    audioSources: 32,
+    meshInstances: 2000,
+    gaussians: 500_000,
+    shaderPasses: 8,
+    networkMsgs: 100,
+    agentCount: 20,
+    memoryMB: 1024,
+    gpuDrawCalls: 500,
+  },
+  'mobile-ar': {
+    particles: 2000,
+    physicsBodies: 50,
+    audioSources: 8,
+    meshInstances: 200,
+    gaussians: 100_000,
+    shaderPasses: 2,
+    networkMsgs: 30,
+    agentCount: 5,
+    memoryMB: 256,
+    gpuDrawCalls: 100,
+  },
+};
+
+/** Cost of each trait in resource units (exact shape from core) */
+export const TRAIT_RESOURCE_COSTS: Record<string, Partial<Record<ResourceCategory, number>>> = {
+  '@mesh': { meshInstances: 1, gpuDrawCalls: 1 },
+  '@material': { shaderPasses: 1, gpuDrawCalls: 1, memoryMB: 0.5 },
+  '@shader': { shaderPasses: 1, gpuDrawCalls: 1 },
+  '@advanced_pbr': { shaderPasses: 2, gpuDrawCalls: 1, memoryMB: 1 },
+  '@advanced_lighting': { gpuDrawCalls: 2, shaderPasses: 1 },
+  '@advanced_texturing': { memoryMB: 2, gpuDrawCalls: 1 },
+  '@light': { gpuDrawCalls: 1, shaderPasses: 1 },
+  '@lighting': { gpuDrawCalls: 2, shaderPasses: 1 },
+  '@global_illumination': { gpuDrawCalls: 4, shaderPasses: 3, memoryMB: 8 },
+  '@ray_tracing': { gpuDrawCalls: 8, shaderPasses: 4, memoryMB: 16 },
+  '@screen_space_effects': { shaderPasses: 2, gpuDrawCalls: 2 },
+  '@subsurface_scattering': { shaderPasses: 2, gpuDrawCalls: 1 },
+  '@rendering': { meshInstances: 1, gpuDrawCalls: 1, memoryMB: 1 },
+  '@render_network': { gpuDrawCalls: 2, networkMsgs: 5, memoryMB: 4 },
+  '@particle': { particles: 100, gpuDrawCalls: 1, memoryMB: 2 },
+  '@vfx': { particles: 200, shaderPasses: 1, gpuDrawCalls: 2 },
+  '@volumetric': { gpuDrawCalls: 3, shaderPasses: 2, memoryMB: 4 },
+  '@volumetric_window': { gpuDrawCalls: 2, memoryMB: 2 },
+  '@gaussian': { gaussians: 100_000, memoryMB: 10 },
+  '@gaussian_splat': { gaussians: 100_000, memoryMB: 10 },
+  '@multiview_gaussian_renderer': { gaussians: 200_000, memoryMB: 20, gpuDrawCalls: 4 },
+  '@nerf': { gpuDrawCalls: 4, memoryMB: 16, shaderPasses: 2 },
+  '@physics': { physicsBodies: 1 },
+  '@rigidbody': { physicsBodies: 1 },
+  '@collider': { physicsBodies: 1 },
+  '@joint': { physicsBodies: 2 },
+  '@trigger': { physicsBodies: 1 },
+  '@fluid_simulation': { particles: 500, physicsBodies: 10, memoryMB: 8 },
+  '@advanced_cloth': { particles: 200, physicsBodies: 5, memoryMB: 4 },
+  '@granular_material': { particles: 300, physicsBodies: 8, memoryMB: 6 },
+  '@voronoi_fracture': { physicsBodies: 20, meshInstances: 20, memoryMB: 4 },
+  '@audio': { audioSources: 1 },
+  '@spatial_audio': { audioSources: 1 },
+  '@environmental_audio': { audioSources: 4, memoryMB: 2 },
+  '@voice_mesh': { audioSources: 1, networkMsgs: 10 },
+  '@voice_input': { audioSources: 1, memoryMB: 1 },
+  '@voice_output': { audioSources: 1, memoryMB: 1 },
+  '@lip_sync': { memoryMB: 2, gpuDrawCalls: 1 },
+  '@ambisonics': { audioSources: 4, memoryMB: 4 },
+  '@networked': { networkMsgs: 1 },
+  '@networked_avatar': { networkMsgs: 10, meshInstances: 1, memoryMB: 2 },
+  '@lobby': { networkMsgs: 5, memoryMB: 2 },
+  '@mqtt_sink': { networkMsgs: 5 },
+  '@mqtt_source': { networkMsgs: 5 },
+  '@sync_tier': { networkMsgs: 2 },
+  '@crdt_room': { networkMsgs: 10, memoryMB: 4 },
+  '@shareplay': { networkMsgs: 5, memoryMB: 2 },
+  '@agent': { agentCount: 1, memoryMB: 5 },
+  '@npc': { agentCount: 1, memoryMB: 3, physicsBodies: 1 },
+  '@npc_ai': { agentCount: 1, memoryMB: 8 },
+  '@ai_npc_brain': { agentCount: 1, memoryMB: 10 },
+  '@multi_agent': { agentCount: 3, memoryMB: 15 },
+  '@agent_discovery': { agentCount: 1, memoryMB: 2 },
+  '@neural_animation': { memoryMB: 8, gpuDrawCalls: 2 },
+  '@neural_forge': { memoryMB: 16, agentCount: 1 },
+  '@local_llm': { memoryMB: 32, agentCount: 1 },
+  '@rag_knowledge': { memoryMB: 8 },
+  '@embedding_search': { memoryMB: 4 },
+  '@vector_db': { memoryMB: 8 },
+  '@stable_diffusion': { memoryMB: 32, gpuDrawCalls: 1 },
+  '@diffusion_realtime': { memoryMB: 16, gpuDrawCalls: 2 },
+  '@vision': { memoryMB: 4 },
+  '@pose_estimation': { memoryMB: 4, agentCount: 1 },
+  '@object_tracking': { memoryMB: 4 },
+  '@hand_mesh_ai': { memoryMB: 4, gpuDrawCalls: 1 },
+  '@animation': { gpuDrawCalls: 1, memoryMB: 2 },
+  '@skeleton': { gpuDrawCalls: 1, memoryMB: 1 },
+  '@ik': { memoryMB: 1 },
+  '@morph': { gpuDrawCalls: 1, memoryMB: 1 },
+  '@character': { physicsBodies: 1, meshInstances: 1, gpuDrawCalls: 2, memoryMB: 4 },
+  '@emotion_directive': { memoryMB: 1 },
+  '@dialog': { memoryMB: 2 },
+  '@scene_reconstruction': { meshInstances: 10, memoryMB: 8, gpuDrawCalls: 5 },
+  '@realitykit_mesh': { meshInstances: 5, memoryMB: 4, gpuDrawCalls: 3 },
+  '@openxr_hal': { memoryMB: 2 },
+  '@spatial_navigation': { memoryMB: 2 },
+  '@spatial_persona': { meshInstances: 1, memoryMB: 2, networkMsgs: 5 },
+  '@spatial_awareness': { memoryMB: 2 },
+  '@orbital': { physicsBodies: 1, memoryMB: 1 },
+  '@grabbable': { physicsBodies: 1 },
+  '@pressable': { physicsBodies: 1 },
+  '@slidable': { physicsBodies: 1 },
+  '@wot_thing': { networkMsgs: 2, memoryMB: 1 },
+  '@urdf_robot': { physicsBodies: 10, meshInstances: 10, memoryMB: 4 },
+  '@computer_use': { memoryMB: 4 },
+  '@pid_controller': { memoryMB: 0.5 },
+  '@biofeedback': { memoryMB: 1 },
+};
+
+/** A resource usage entry from the AST (exact shape from core) */
+export interface ResourceUsageNode {
+  name: string;
+  traits: string[];
+  calls: string[];
+  count: number;
+  traitConfigs?: Record<string, Record<string, number>>;
+}