@holoscript/framework 6.0.3

package/dist/economy/index.d.ts

@@ -0,0 +1,747 @@
+import { T as TelemetryCollector, R as ResourceCategory, a as ResourceUsageNode } from '../InvisibleWallet-rtRrBOA8.js';
+export { B as Bounty, b as BountyCurrency, c as BountyManager, d as BountyManagerConfig, e as BountyReward, f as BountyStatus, C as CHAIN_IDS, g as CHAIN_ID_TO_NETWORK, h as ClaimResult, i as CompletionProof, j as CreatorEarnings, k as CreatorRevenueAggregator, l as CreditTraitConfig, I as InvisibleWalletStub, K as KnowledgeListing, m as KnowledgeMarketplace, L as LedgerEntry, n as ListingResult, o as ListingStatus, M as MICRO_PAYMENT_THRESHOLD, p as MicroPaymentLedger, P as PaymentGateway, q as PaymentScheme, r as PaymentWebhookService, s as PayoutRecord, t as PayoutResult, u as PluginRevenue, v as PricingFactors, w as PurchaseResult, x as RefundRequest, y as RefundResult, z as RevenueAggregatorConfig, A as RevenueEvent, D as RevenuePeriod, E as RevenueSplitter, S as SettlementChain, F as SettlementEvent, G as SettlementEventListener, H as SettlementEventType, J as SettlementMode, N as SplitBreakdownEntry, O as SplitRecipient, Q as SplitResult, U as USDC_CONTRACTS, V as WalletConfig, W as WalletHexAddress, X as WalletInfo, Y as WebhookEventType, Z as WebhookHandler, _ as WebhookPayload, $ as WebhookProcessingResult, a0 as WebhookProvider, a1 as WebhookServiceConfig, a2 as WebhookVerificationResult, a3 as X402Facilitator, a4 as X402FacilitatorConfig, a5 as X402PaymentOption, a6 as X402PaymentPayload, a7 as X402PaymentRequired, a8 as X402SettlementResult, a9 as X402VerificationResult, aa as X402_VERSION, ab as creditTraitHandler } from '../InvisibleWallet-rtRrBOA8.js';
+import '../implementations-D9T3un9D.js';
+import '@holoscript/core';
+
+/**
+ * SubscriptionManager — Recurring subscription lifecycle management
+ *
+ * Manages subscription states: create → renew → cancel → suspend → reactivate.
+ * Supports trial periods, grace periods on failed renewal, and links to
+ * X402PaymentGateway for recurring authorization.
+ *
+ * Part of HoloScript v5.8 "Live Economy".
+ *
+ * @version 1.0.0
+ */
+
+/**
+ * Subscription lifecycle state.
+ */
+type SubscriptionState = 'trial' | 'active' | 'past_due' | 'suspended' | 'cancelled' | 'expired';
+/**
+ * Billing interval.
+ */
+type BillingInterval = 'daily' | 'weekly' | 'monthly' | 'yearly';
+/**
+ * A subscription record.
+ */
+interface Subscription {
+    /** Unique subscription ID */
+    id: string;
+    /** Subscriber (agent or user) ID */
+    subscriberId: string;
+    /** Plan ID */
+    planId: string;
+    /** Current state */
+    state: SubscriptionState;
+    /** Billing amount per period (USDC base units, 6 decimals) */
+    amount: number;
+    /** Billing interval */
+    interval: BillingInterval;
+    /** When the subscription was created (ISO 8601) */
+    createdAt: string;
+    /** Current period start (ISO 8601) */
+    currentPeriodStart: string;
+    /** Current period end (ISO 8601) */
+    currentPeriodEnd: string;
+    /** Trial end date (ISO 8601, null if no trial) */
+    trialEnd: string | null;
+    /** Whether currently in trial */
+    inTrial: boolean;
+    /** Number of failed renewal attempts */
+    failedRenewals: number;
+    /** Grace period end (ISO 8601, null if not in grace period) */
+    gracePeriodEnd: string | null;
+    /** When cancelled (ISO 8601, null if not cancelled) */
+    cancelledAt: string | null;
+    /** Cancel at period end (vs immediate) */
+    cancelAtPeriodEnd: boolean;
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Subscription plan definition.
+ */
+interface SubscriptionPlan {
+    /** Plan ID */
+    id: string;
+    /** Plan name */
+    name: string;
+    /** Plan description */
+    description: string;
+    /** Billing amount per period (USDC base units) */
+    amount: number;
+    /** Billing interval */
+    interval: BillingInterval;
+    /** Trial duration in days (0 = no trial) */
+    trialDays: number;
+    /** Features included */
+    features: string[];
+}
+/**
+ * SubscriptionManager configuration.
+ */
+interface SubscriptionManagerConfig {
+    /** Grace period duration in days (default: 3) */
+    gracePeriodDays?: number;
+    /** Maximum failed renewals before suspension (default: 3) */
+    maxFailedRenewals?: number;
+    /** Telemetry collector */
+    telemetry?: TelemetryCollector;
+}
+/**
+ * Renewal result.
+ */
+interface RenewalResult {
+    /** Whether renewal succeeded */
+    success: boolean;
+    /** Updated subscription */
+    subscription: Subscription;
+    /** Error message if failed */
+    error?: string;
+    /** Whether grace period was entered */
+    enteredGracePeriod?: boolean;
+}
+declare class SubscriptionManager {
+    private config;
+    private subscriptions;
+    private plans;
+    private renewalCallback?;
+    private subCounter;
+    constructor(config?: SubscriptionManagerConfig);
+    /**
+     * Register a subscription plan.
+     */
+    registerPlan(plan: SubscriptionPlan): void;
+    /**
+     * Get a plan by ID.
+     */
+    getPlan(planId: string): SubscriptionPlan | undefined;
+    /**
+     * List all plans.
+     */
+    listPlans(): SubscriptionPlan[];
+    /**
+     * Create a new subscription.
+     */
+    create(subscriberId: string, planId: string, metadata?: Record<string, unknown>): Subscription;
+    /**
+     * Attempt to renew a subscription.
+     */
+    renew(subscriptionId: string): Promise<RenewalResult>;
+    /**
+     * Cancel a subscription.
+     * @param immediate If true, cancel immediately; otherwise cancel at period end.
+     */
+    cancel(subscriptionId: string, immediate?: boolean): Subscription;
+    /**
+     * Suspend a subscription (e.g., after payment failures).
+     */
+    suspend(subscriptionId: string): Subscription;
+    /**
+     * Reactivate a suspended or cancelled subscription.
+     */
+    reactivate(subscriptionId: string): Subscription;
+    /**
+     * Set callback for renewal payment processing.
+     * Should return true if payment succeeded.
+     */
+    onRenewal(callback: (subscriptionId: string, amount: number) => Promise<boolean>): void;
+    /**
+     * Get a subscription by ID.
+     */
+    getSubscription(id: string): Subscription | undefined;
+    /**
+     * Get all subscriptions for a subscriber.
+     */
+    getSubscriberSubscriptions(subscriberId: string): Subscription[];
+    /**
+     * Get subscriptions by state.
+     */
+    getByState(state: SubscriptionState): Subscription[];
+    /**
+     * Get subscriptions due for renewal.
+     */
+    getDueForRenewal(): Subscription[];
+    /**
+     * Get subscriptions in grace period.
+     */
+    getInGracePeriod(): Subscription[];
+    /**
+     * Check if grace period has expired for past_due subscriptions.
+     */
+    processExpiredGracePeriods(): Subscription[];
+    /**
+     * Get stats.
+     */
+    getStats(): {
+        total: number;
+        byState: Record<string, number>;
+        totalMRR: number;
+        planCount: number;
+    };
+    /**
+     * Total subscription count.
+     */
+    getSubscriptionCount(): number;
+    private requireSubscription;
+    private computePeriodEnd;
+    private normalizeToMonthly;
+    private emitTelemetry;
+}
+
+/**
+ * AgentBudgetEnforcer — Per-agent budget caps with enforcement
+ *
+ * Tracks spending per agent with configurable enforcement modes
+ * (warn, soft, hard) and budget periods. Includes circuit breaker
+ * for consecutive failures or overspend.
+ *
+ * Part of HoloScript v5.8 "Live Economy".
+ *
+ * @version 1.0.0
+ */
+
+/**
+ * Enforcement mode for budget limits.
+ */
+type EnforcementMode = 'warn' | 'soft' | 'hard';
+/**
+ * Budget period type.
+ */
+type BudgetPeriod = 'per-request' | 'per-session' | 'daily' | 'monthly';
+/**
+ * Budget configuration for an agent.
+ */
+interface AgentBudget {
+    /** Agent ID */
+    agentId: string;
+    /** Maximum spend per period (USDC base units, 6 decimals) */
+    maxSpend: number;
+    /** Budget period */
+    period: BudgetPeriod;
+    /** Enforcement mode */
+    mode: EnforcementMode;
+    /** Warning threshold (fraction 0-1, e.g. 0.8 = warn at 80%) */
+    warnThreshold?: number;
+    /** Circuit breaker: max consecutive failures before tripping */
+    circuitBreakerThreshold?: number;
+}
+/**
+ * Current budget state for an agent.
+ */
+interface BudgetState {
+    /** Agent ID */
+    agentId: string;
+    /** Amount spent in current period (USDC base units) */
+    spent: number;
+    /** Budget limit (USDC base units) */
+    limit: number;
+    /** Budget remaining (USDC base units) */
+    remaining: number;
+    /** Whether budget is exhausted */
+    exhausted: boolean;
+    /** Whether warning threshold is reached */
+    warning: boolean;
+    /** Current enforcement mode */
+    mode: EnforcementMode;
+    /** Current period */
+    period: BudgetPeriod;
+    /** Period start (ISO 8601) */
+    periodStart: string;
+    /** Number of requests in this period */
+    requestCount: number;
+    /** Circuit breaker state */
+    circuitBreaker: CircuitBreakerState;
+}
+/**
+ * Circuit breaker state.
+ */
+interface CircuitBreakerState {
+    /** Whether the circuit breaker is open (tripped) */
+    isOpen: boolean;
+    /** Consecutive failure count */
+    consecutiveFailures: number;
+    /** Maximum consecutive failures */
+    threshold: number;
+    /** When the circuit breaker was tripped (ISO 8601, null if not tripped) */
+    trippedAt: string | null;
+    /** When the circuit breaker will reset (ISO 8601, null if not tripped) */
+    resetAt: string | null;
+}
+/**
+ * Result of a spend authorization check.
+ */
+interface SpendAuthorizationResult {
+    /** Whether the spend is authorized */
+    authorized: boolean;
+    /** Reason for denial */
+    reason?: string;
+    /** Current budget state */
+    state: BudgetState;
+    /** Whether this is a warning (authorized but near limit) */
+    warning?: boolean;
+    /** Warning message */
+    warningMessage?: string;
+}
+/**
+ * AgentBudgetEnforcer configuration.
+ */
+interface BudgetEnforcerConfig {
+    /** Default budget for agents without explicit config */
+    defaultBudget?: Partial<AgentBudget>;
+    /** Circuit breaker reset timeout (ms, default: 60s) */
+    circuitBreakerResetMs?: number;
+    /** Telemetry collector */
+    telemetry?: TelemetryCollector;
+}
+declare class AgentBudgetEnforcer {
+    private trackers;
+    private config;
+    private sessionCounter;
+    constructor(config?: BudgetEnforcerConfig);
+    /**
+     * Set budget for an agent.
+     */
+    setBudget(budget: AgentBudget): void;
+    /**
+     * Get budget configuration for an agent.
+     */
+    getBudget(agentId: string): AgentBudget | undefined;
+    /**
+     * Remove budget for an agent.
+     */
+    removeBudget(agentId: string): boolean;
+    /**
+     * Check if an agent is authorized to spend a given amount.
+     */
+    authorize(agentId: string, amount: number): SpendAuthorizationResult;
+    /**
+     * Record a spend. Call after a successful tool execution.
+     */
+    recordSpend(agentId: string, amount: number): void;
+    /**
+     * Record a failure. Increments circuit breaker counter.
+     */
+    recordFailure(agentId: string): void;
+    /**
+     * Get current budget state for an agent.
+     */
+    getState(agentId: string): BudgetState | undefined;
+    /**
+     * Get all agent budget states.
+     */
+    getAllStates(): BudgetState[];
+    /**
+     * Get agents that are over budget.
+     */
+    getOverBudgetAgents(): BudgetState[];
+    /**
+     * Reset an agent's period spending.
+     */
+    resetSpending(agentId: string): void;
+    /**
+     * Reset circuit breaker for an agent.
+     */
+    resetCircuitBreaker(agentId: string): void;
+    private getOrCreateTracker;
+    private checkPeriodReset;
+    private buildState;
+    private emitTelemetry;
+}
+
+/**
+ * UnifiedBudgetOptimizer — Bridges Economy and Rendering Budgets
+ *
+ * Oracle Cycle 6 identified that AgentBudgetEnforcer (1D USDC, hard stop)
+ * and ResourceBudgetAnalyzer (10D resources, graceful LOD degradation)
+ * solve the same optimization problem with zero shared abstractions.
+ *
+ * This module provides:
+ * 1. Trait Utility Function — value per resource cost (enables optimization)
+ * 2. Equimarginal LOD Allocation — drop by lowest value/cost ratio, not greedy
+ * 3. Resource Cost Floor Pricing — prevents economic denial-of-rendering
+ * 4. Unified budget query — single view of both economy + rendering pressure
+ *
+ * @version 1.0.0
+ */
+
+/**
+ * Trait utility entry — encodes how much value a trait provides per unit cost.
+ * Higher utility = keep this trait when budgets are tight.
+ */
+interface TraitUtility {
+    /** Trait name (e.g., '@particle', '@gaussian') */
+    trait: string;
+    /** Base utility score (0-100, higher = more valuable to the experience) */
+    baseUtility: number;
+    /** Category for grouping (visual, physics, audio, network, ai) */
+    category: TraitCategory;
+    /** Whether this trait is required (cannot be dropped by LOD) */
+    required: boolean;
+    /** LOD level at which this trait can start being dropped (0 = never) */
+    minLODLevel: number;
+}
+type TraitCategory = 'visual' | 'physics' | 'audio' | 'network' | 'ai' | 'interaction';
+/**
+ * Allocation decision for a single trait.
+ */
+interface TraitAllocation {
+    /** Trait name */
+    trait: string;
+    /** Whether to include this trait at current budget level */
+    included: boolean;
+    /** LOD level applied (0 = full detail) */
+    lodLevel: number;
+    /** Resource cost at current LOD */
+    resourceCost: Partial<Record<ResourceCategory, number>>;
+    /** Economic cost (USDC base units, 0 if no marketplace price) */
+    economicCost: number;
+    /** Computed utility score */
+    utility: number;
+    /** Value/cost ratio used for allocation decisions */
+    valueCostRatio: number;
+    /** Reason for exclusion if not included */
+    excludeReason?: string;
+}
+/**
+ * Resource cost floor for marketplace pricing.
+ * Prevents a 1-credit trait from consuming 10K gaussians.
+ */
+interface ResourceCostFloor {
+    /** Minimum price per unit of resource consumed */
+    perGaussian: number;
+    /** Minimum price per draw call */
+    perDrawCall: number;
+    /** Minimum price per MB memory */
+    perMemoryMB: number;
+    /** Minimum price per particle */
+    perParticle: number;
+    /** Minimum price per physics body */
+    perPhysicsBody: number;
+    /** Base platform fee (USDC base units) */
+    baseFee: number;
+}
+/**
+ * Unified budget state — single view across economy + rendering.
+ */
+interface UnifiedBudgetState {
+    /** Agent ID */
+    agentId: string;
+    /** Economic pressure (0-1, where 1 = budget exhausted) */
+    economicPressure: number;
+    /** Resource pressure per category (0-1) */
+    resourcePressure: Partial<Record<ResourceCategory, number>>;
+    /** Overall pressure (max of economic and worst resource) */
+    overallPressure: number;
+    /** Suggested LOD level based on combined pressure */
+    suggestedLOD: number;
+    /** Whether any hard limit is breached */
+    hardLimitBreached: boolean;
+    /** Traits that should be shed to relieve pressure */
+    shedCandidates: TraitAllocation[];
+}
+/**
+ * Configuration for the unified optimizer.
+ */
+interface UnifiedOptimizerConfig {
+    /** Target platform for resource limits */
+    platform: string;
+    /** Resource cost floor for marketplace pricing */
+    costFloor: ResourceCostFloor;
+    /** Custom trait utilities (override defaults) */
+    traitUtilities?: Map<string, TraitUtility>;
+    /** LOD scaling factors — how much resource cost reduces per LOD level */
+    lodScaling?: number[];
+    /** Economic budget limit (USDC base units, 0 = no limit) */
+    economicBudget?: number;
+    /** Economic spend so far (USDC base units) */
+    economicSpent?: number;
+}
+/**
+ * Default utility scores for common traits.
+ * These encode "how much does this trait contribute to the experience?"
+ *
+ * Scoring guide:
+ * - 90-100: Core experience (mesh, material, physics) — never drop
+ * - 70-89:  Important visual/audio quality (lighting, particles)
+ * - 50-69:  Enhancement (volumetric, VFX, spatial audio)
+ * - 30-49:  Nice-to-have (reflections, subsurface, ambisonics)
+ * - 10-29:  Luxury (ray tracing, global illumination, neural rendering)
+ */
+declare const DEFAULT_TRAIT_UTILITIES: Record<string, Omit<TraitUtility, 'trait'>>;
+/**
+ * Default resource cost floor pricing.
+ * Prevents marketplace traits from being priced below their GPU cost.
+ * Prices in USDC base units (6 decimals, so 1_000_000 = $1.00).
+ */
+/**
+ * Platform-specific LOD scaling curves.
+ *
+ * C6 Layer 2 finding: platform exchange rates are wildly non-uniform (25x
+ * price difference for a single @particle between Mobile AR and Desktop VR).
+ * A uniform LOD curve means constrained platforms over-degrade while powerful
+ * platforms under-utilize. Each platform gets its own perceptual curve.
+ *
+ * Constrained platforms (mobile_ar, quest3) degrade faster at LOD 1-2.
+ * Powerful platforms (desktop-vr) degrade slowly, preserving quality.
+ */
+declare const PLATFORM_LOD_SCALING: Record<string, number[]>;
+/**
+ * Default resource cost floor pricing.
+ * Prevents marketplace traits from being priced below their GPU cost.
+ * Prices in USDC base units (6 decimals, so 1_000_000 = $1.00).
+ */
+declare const DEFAULT_COST_FLOOR: ResourceCostFloor;
+/**
+ * Default LOD scaling: how much resource usage decreases per LOD level.
+ *
+ * Previous geometric scaling [1.0, 0.5, 0.25, 0.1, 0.05] over-degrades
+ * the visible mid-range (LOD 1-2). Human perception follows Weber-Fechner
+ * (logarithmic), meaning a 50% reduction at LOD 1 is far more noticeable
+ * than a 50% reduction at LOD 3.
+ *
+ * Perceptual curve: each step reduces quality by an amount proportional
+ * to the *perceived* difference, not the geometric ratio.
+ * LOD 0 = 1.0 (full), LOD 1 = 0.7, LOD 2 = 0.4, LOD 3 = 0.18, LOD 4 = 0.06
+ *
+ * This preserves more detail in the visually sensitive mid-range while
+ * still achieving aggressive reduction at far distances.
+ */
+declare const DEFAULT_LOD_SCALING: number[];
+declare class UnifiedBudgetOptimizer {
+    private platform;
+    private costFloor;
+    private traitUtilities;
+    private lodScaling;
+    private economicBudget;
+    private economicSpent;
+    constructor(config: UnifiedOptimizerConfig);
+    /**
+     * Allocate traits across a resource budget using the equimarginal principle.
+     * Instead of greedily dropping the deepest LOD first, this sorts by value/cost
+     * ratio and drops traits with the lowest marginal utility first.
+     *
+     * @param nodes - Resource usage nodes (traits + counts)
+     * @param maxLOD - Maximum LOD level to consider (default: 4)
+     * @returns Allocation decisions for each trait
+     */
+    allocate(nodes: ResourceUsageNode[], maxLOD?: number): TraitAllocation[];
+    /**
+     * Calculate the minimum marketplace price for a trait based on its resource cost.
+     * Prevents economic denial-of-rendering attacks where a cheap marketplace trait
+     * consumes massive GPU resources.
+     *
+     * @param traitName - The trait to price
+     * @param instanceCount - How many instances (default: 1)
+     * @returns Minimum price in USDC base units (6 decimals)
+     */
+    calculateCostFloor(traitName: string, instanceCount?: number): number;
+    /**
+     * Validate that a marketplace listing price meets the resource cost floor.
+     *
+     * @param traitName - The trait being listed
+     * @param listPrice - Proposed listing price (USDC base units)
+     * @param instanceCount - Expected instance count
+     * @returns Validation result
+     */
+    validateMarketplacePrice(traitName: string, listPrice: number, instanceCount?: number): {
+        valid: boolean;
+        floor: number;
+        deficit: number;
+        message: string;
+    };
+    /**
+     * Get a unified view of budget pressure across economy + rendering.
+     *
+     * @param agentId - Agent identifier
+     * @param nodes - Current resource usage nodes
+     * @param economicSpent - Current economic spend (USDC base units)
+     * @param economicLimit - Economic budget limit (USDC base units)
+     * @returns Unified budget state
+     */
+    getUnifiedState(agentId: string, nodes: ResourceUsageNode[], economicSpent?: number, economicLimit?: number): UnifiedBudgetState;
+    /**
+     * Get the utility score for a trait.
+     */
+    getUtility(traitName: string): TraitUtility | undefined;
+    /**
+     * Set custom utility for a trait.
+     */
+    setUtility(utility: TraitUtility): void;
+    /**
+     * Get the total weighted resource cost of a trait at a given LOD level.
+     * Collapses multi-dimensional resource cost into a single scalar
+     * using platform limits as normalization weights.
+     */
+    getWeightedCost(traitName: string, lodLevel?: number, instanceCount?: number): number;
+    /**
+     * Compute value/cost ratio for a trait at a given LOD level.
+     * Higher = more efficient use of resources.
+     */
+    getValueCostRatio(traitName: string, lodLevel?: number, instanceCount?: number): number;
+    private flattenToAllocations;
+    private buildAllocation;
+    private isRequired;
+    private canDropAtLOD;
+    private computeResourcePressure;
+}
+
+/**
+ * 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
+ */
+
+/**
+ * Aggregation period for usage data.
+ */
+type UsagePeriod = 'hourly' | 'daily' | 'monthly';
+/**
+ * A single usage event.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+interface FreeTierConfig {
+    /** Monthly free-tier allowance in USDC base units */
+    monthlyAllowance: number;
+    /** Per-tool overrides */
+    toolOverrides?: Record<string, number>;
+}
+/**
+ * UsageMeter configuration.
+ */
+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;
+}
+declare class UsageMeter {
+    private config;
+    /** All usage events keyed by agentId */
+    private events;
+    /** Free-tier consumption per agent (monthly, USDC base units) */
+    private freeTierUsed;
+    /** Current month key for free-tier reset */
+    private currentMonthKey;
+    private eventCounter;
+    constructor(config?: UsageMeterConfig);
+    /**
+     * Record a tool call usage event.
+     */
+    recordUsage(agentId: string, toolId: string, metadata?: Record<string, unknown>): UsageEvent;
+    /**
+     * Get the cost for a specific tool.
+     */
+    getToolCost(toolId: string): number;
+    /**
+     * Set cost for a specific tool.
+     */
+    setToolCost(toolId: string, cost: number): void;
+    /**
+     * Get usage summary for an agent within a time period.
+     */
+    getAgentUsage(agentId: string, period?: UsagePeriod): AgentUsageSummary;
+    /**
+     * Get aggregated usage across all agents for a period.
+     */
+    getGlobalUsage(period?: UsagePeriod): UsageAggregate;
+    /**
+     * Get top tools by usage cost.
+     */
+    getTopTools(period?: UsagePeriod, limit?: number): Array<{
+        toolId: string;
+        calls: number;
+        cost: number;
+    }>;
+    /**
+     * Get free-tier remaining for an agent.
+     */
+    getFreeTierRemaining(agentId: string): number;
+    /**
+     * Check if an agent has exceeded their free tier.
+     */
+    isOverFreeTier(agentId: string): boolean;
+    /**
+     * Get all tracked agent IDs.
+     */
+    getTrackedAgents(): string[];
+    /**
+     * Get raw events for an agent.
+     */
+    getEvents(agentId: string): UsageEvent[];
+    /**
+     * Get total number of recorded events.
+     */
+    getTotalEventCount(): number;
+    private getMonthKey;
+    private checkMonthReset;
+    private getPeriodBounds;
+    private emitTelemetry;
+}
+
+export { type AgentBudget, AgentBudgetEnforcer, type AgentUsageSummary, type BillingInterval, type BudgetEnforcerConfig, type BudgetPeriod, type BudgetState, type CircuitBreakerState, DEFAULT_COST_FLOOR, DEFAULT_LOD_SCALING, DEFAULT_TRAIT_UTILITIES, type EnforcementMode, type FreeTierConfig, PLATFORM_LOD_SCALING, type RenewalResult, type ResourceCostFloor, type SpendAuthorizationResult, type Subscription, SubscriptionManager, type SubscriptionManagerConfig, type SubscriptionPlan, type SubscriptionState, type TraitAllocation, type TraitCategory, type TraitUtility, UnifiedBudgetOptimizer, type UnifiedBudgetState, type UnifiedOptimizerConfig, type UsageAggregate, type UsageEvent, UsageMeter, type UsageMeterConfig, type UsagePeriod };