@holoscript/framework 6.0.3

package/src/economy/AgentBudgetEnforcer.ts

@@ -0,0 +1,464 @@
+/**
+ * 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
+ */
+
+import type { TelemetryCollector } from './_core-stubs';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Enforcement mode for budget limits.
+ */
+export type EnforcementMode = 'warn' | 'soft' | 'hard';
+
+/**
+ * Budget period type.
+ */
+export type BudgetPeriod = 'per-request' | 'per-session' | 'daily' | 'monthly';
+
+/**
+ * Budget configuration for an agent.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+}
+
+// =============================================================================
+// INTERNAL TRACKING
+// =============================================================================
+
+interface AgentTracker {
+  budget: AgentBudget;
+  spent: number;
+  requestCount: number;
+  periodStart: number;
+  consecutiveFailures: number;
+  circuitBreakerTrippedAt: number | null;
+  sessionId: string;
+}
+
+// =============================================================================
+// AGENT BUDGET ENFORCER
+// =============================================================================
+
+export class AgentBudgetEnforcer {
+  private trackers: Map<string, AgentTracker> = new Map();
+  private config: Required<Omit<BudgetEnforcerConfig, 'telemetry' | 'defaultBudget'>> & {
+    telemetry?: TelemetryCollector;
+    defaultBudget: AgentBudget;
+  };
+  private sessionCounter = 0;
+
+  constructor(config?: BudgetEnforcerConfig) {
+    this.config = {
+      defaultBudget: {
+        agentId: '',
+        maxSpend: 10_000_000, // $10.00 default
+        period: 'daily',
+        mode: 'soft',
+        warnThreshold: 0.8,
+        circuitBreakerThreshold: 5,
+        ...config?.defaultBudget,
+      } as AgentBudget,
+      circuitBreakerResetMs: config?.circuitBreakerResetMs ?? 60_000,
+      telemetry: config?.telemetry,
+    };
+  }
+
+  // ===========================================================================
+  // BUDGET MANAGEMENT
+  // ===========================================================================
+
+  /**
+   * Set budget for an agent.
+   */
+  setBudget(budget: AgentBudget): void {
+    const existing = this.trackers.get(budget.agentId);
+    if (existing) {
+      existing.budget = { ...budget };
+    } else {
+      this.trackers.set(budget.agentId, {
+        budget: { ...budget },
+        spent: 0,
+        requestCount: 0,
+        periodStart: Date.now(),
+        consecutiveFailures: 0,
+        circuitBreakerTrippedAt: null,
+        sessionId: `session-${++this.sessionCounter}`,
+      });
+    }
+  }
+
+  /**
+   * Get budget configuration for an agent.
+   */
+  getBudget(agentId: string): AgentBudget | undefined {
+    return this.trackers.get(agentId)?.budget;
+  }
+
+  /**
+   * Remove budget for an agent.
+   */
+  removeBudget(agentId: string): boolean {
+    return this.trackers.delete(agentId);
+  }
+
+  // ===========================================================================
+  // AUTHORIZATION
+  // ===========================================================================
+
+  /**
+   * Check if an agent is authorized to spend a given amount.
+   */
+  authorize(agentId: string, amount: number): SpendAuthorizationResult {
+    const tracker = this.getOrCreateTracker(agentId);
+    this.checkPeriodReset(tracker);
+
+    const state = this.buildState(tracker);
+
+    // Check circuit breaker first
+    if (state.circuitBreaker.isOpen) {
+      // Check if reset time has passed
+      if (tracker.circuitBreakerTrippedAt) {
+        const elapsed = Date.now() - tracker.circuitBreakerTrippedAt;
+        if (elapsed >= this.config.circuitBreakerResetMs) {
+          // Reset circuit breaker
+          tracker.consecutiveFailures = 0;
+          tracker.circuitBreakerTrippedAt = null;
+        } else {
+          this.emitTelemetry('budget_circuit_breaker_blocked', { agentId, amount });
+          return {
+            authorized: false,
+            reason: `Circuit breaker open: ${tracker.consecutiveFailures} consecutive failures. Resets in ${Math.ceil((this.config.circuitBreakerResetMs - elapsed) / 1000)}s`,
+            state: this.buildState(tracker),
+          };
+        }
+      }
+    }
+
+    // Check budget
+    const wouldExceed = tracker.spent + amount > tracker.budget.maxSpend;
+    const warnThreshold = tracker.budget.warnThreshold ?? 0.8;
+    const atWarningLevel = (tracker.spent + amount) / tracker.budget.maxSpend >= warnThreshold;
+
+    if (wouldExceed) {
+      switch (tracker.budget.mode) {
+        case 'hard':
+          this.emitTelemetry('budget_hard_denied', {
+            agentId,
+            amount,
+            spent: tracker.spent,
+            limit: tracker.budget.maxSpend,
+          });
+          return {
+            authorized: false,
+            reason: `Budget exhausted (hard limit): spent ${tracker.spent} + ${amount} > limit ${tracker.budget.maxSpend}`,
+            state: this.buildState(tracker),
+          };
+
+        case 'soft':
+          this.emitTelemetry('budget_soft_denied', { agentId, amount, spent: tracker.spent });
+          return {
+            authorized: false,
+            reason: `Budget exhausted (soft limit): spent ${tracker.spent} + ${amount} > limit ${tracker.budget.maxSpend}`,
+            state: this.buildState(tracker),
+          };
+
+        case 'warn':
+          // Allow but warn
+          this.emitTelemetry('budget_warn_overspend', { agentId, amount });
+          return {
+            authorized: true,
+            state: this.buildState(tracker),
+            warning: true,
+            warningMessage: `Budget exceeded: spent ${tracker.spent} + ${amount} > limit ${tracker.budget.maxSpend}`,
+          };
+      }
+    }
+
+    // Check warning level
+    if (atWarningLevel && !wouldExceed) {
+      return {
+        authorized: true,
+        state: this.buildState(tracker),
+        warning: true,
+        warningMessage: `Approaching budget limit: ${Math.round(((tracker.spent + amount) / tracker.budget.maxSpend) * 100)}% used`,
+      };
+    }
+
+    return {
+      authorized: true,
+      state: this.buildState(tracker),
+    };
+  }
+
+  /**
+   * Record a spend. Call after a successful tool execution.
+   */
+  recordSpend(agentId: string, amount: number): void {
+    const tracker = this.getOrCreateTracker(agentId);
+    this.checkPeriodReset(tracker);
+    tracker.spent += amount;
+    tracker.requestCount++;
+    tracker.consecutiveFailures = 0; // Reset on success
+
+    this.emitTelemetry('budget_spend_recorded', { agentId, amount, totalSpent: tracker.spent });
+  }
+
+  /**
+   * Record a failure. Increments circuit breaker counter.
+   */
+  recordFailure(agentId: string): void {
+    const tracker = this.getOrCreateTracker(agentId);
+    tracker.consecutiveFailures++;
+
+    const threshold = tracker.budget.circuitBreakerThreshold ?? 5;
+    if (tracker.consecutiveFailures >= threshold && !tracker.circuitBreakerTrippedAt) {
+      tracker.circuitBreakerTrippedAt = Date.now();
+      this.emitTelemetry('budget_circuit_breaker_tripped', {
+        agentId,
+        failures: tracker.consecutiveFailures,
+        threshold,
+      });
+    }
+  }
+
+  // ===========================================================================
+  // QUERIES
+  // ===========================================================================
+
+  /**
+   * Get current budget state for an agent.
+   */
+  getState(agentId: string): BudgetState | undefined {
+    const tracker = this.trackers.get(agentId);
+    if (!tracker) return undefined;
+    this.checkPeriodReset(tracker);
+    return this.buildState(tracker);
+  }
+
+  /**
+   * Get all agent budget states.
+   */
+  getAllStates(): BudgetState[] {
+    return [...this.trackers.keys()].map((id) => this.getState(id)!).filter(Boolean);
+  }
+
+  /**
+   * Get agents that are over budget.
+   */
+  getOverBudgetAgents(): BudgetState[] {
+    return this.getAllStates().filter((s) => s.exhausted || s.circuitBreaker.isOpen);
+  }
+
+  /**
+   * Reset an agent's period spending.
+   */
+  resetSpending(agentId: string): void {
+    const tracker = this.trackers.get(agentId);
+    if (tracker) {
+      tracker.spent = 0;
+      tracker.requestCount = 0;
+      tracker.periodStart = Date.now();
+      tracker.consecutiveFailures = 0;
+      tracker.circuitBreakerTrippedAt = null;
+      tracker.sessionId = `session-${++this.sessionCounter}`;
+    }
+  }
+
+  /**
+   * Reset circuit breaker for an agent.
+   */
+  resetCircuitBreaker(agentId: string): void {
+    const tracker = this.trackers.get(agentId);
+    if (tracker) {
+      tracker.consecutiveFailures = 0;
+      tracker.circuitBreakerTrippedAt = null;
+    }
+  }
+
+  // ===========================================================================
+  // INTERNALS
+  // ===========================================================================
+
+  private getOrCreateTracker(agentId: string): AgentTracker {
+    let tracker = this.trackers.get(agentId);
+    if (!tracker) {
+      tracker = {
+        budget: { ...this.config.defaultBudget, agentId },
+        spent: 0,
+        requestCount: 0,
+        periodStart: Date.now(),
+        consecutiveFailures: 0,
+        circuitBreakerTrippedAt: null,
+        sessionId: `session-${++this.sessionCounter}`,
+      };
+      this.trackers.set(agentId, tracker);
+    }
+    return tracker;
+  }
+
+  private checkPeriodReset(tracker: AgentTracker): void {
+    const now = Date.now();
+    const elapsed = now - tracker.periodStart;
+
+    let shouldReset = false;
+    switch (tracker.budget.period) {
+      case 'per-request':
+        shouldReset = tracker.requestCount > 0;
+        break;
+      case 'per-session':
+        // Sessions don't auto-reset — must call resetSpending()
+        break;
+      case 'daily':
+        shouldReset = elapsed >= 86400_000;
+        break;
+      case 'monthly':
+        shouldReset = elapsed >= 30 * 86400_000;
+        break;
+    }
+
+    if (shouldReset) {
+      tracker.spent = 0;
+      tracker.requestCount = 0;
+      tracker.periodStart = now;
+      tracker.sessionId = `session-${++this.sessionCounter}`;
+    }
+  }
+
+  private buildState(tracker: AgentTracker): BudgetState {
+    const remaining = Math.max(0, tracker.budget.maxSpend - tracker.spent);
+    const warnThreshold = tracker.budget.warnThreshold ?? 0.8;
+    const cbThreshold = tracker.budget.circuitBreakerThreshold ?? 5;
+
+    return {
+      agentId: tracker.budget.agentId,
+      spent: tracker.spent,
+      limit: tracker.budget.maxSpend,
+      remaining,
+      exhausted: remaining === 0,
+      warning: tracker.spent / tracker.budget.maxSpend >= warnThreshold,
+      mode: tracker.budget.mode,
+      period: tracker.budget.period,
+      periodStart: new Date(tracker.periodStart).toISOString(),
+      requestCount: tracker.requestCount,
+      circuitBreaker: {
+        isOpen:
+          tracker.circuitBreakerTrippedAt !== null &&
+          Date.now() - tracker.circuitBreakerTrippedAt < this.config.circuitBreakerResetMs,
+        consecutiveFailures: tracker.consecutiveFailures,
+        threshold: cbThreshold,
+        trippedAt: tracker.circuitBreakerTrippedAt
+          ? new Date(tracker.circuitBreakerTrippedAt).toISOString()
+          : null,
+        resetAt: tracker.circuitBreakerTrippedAt
+          ? new Date(
+              tracker.circuitBreakerTrippedAt + this.config.circuitBreakerResetMs
+            ).toISOString()
+          : null,
+      },
+    };
+  }
+
+  private emitTelemetry(type: string, data?: Record<string, unknown>): void {
+    this.config.telemetry?.record({
+      type,
+      severity: type.includes('denied') || type.includes('tripped') ? 'warning' : 'info',
+      agentId: (data?.agentId as string) || 'budget-enforcer',
+      data,
+    });
+  }
+}

package/src/economy/BountyManager.ts

@@ -0,0 +1,185 @@
+/**
+ * Bounty Manager — Task-based incentive system for agent teams.
+ *
+ * Creates, claims, and settles bounties tied to board tasks.
+ * Integrates with X402Facilitator for on-chain or in-memory payouts.
+ *
+ * FW-0.6
+ */
+
+import type { X402Facilitator, MicroPaymentLedger } from './x402-facilitator';
+
+// ── Types ──
+
+export type BountyCurrency = 'USDC' | 'credits';
+export type BountyStatus = 'open' | 'claimed' | 'completed' | 'expired' | 'disputed';
+
+export interface BountyReward {
+  amount: number;
+  currency: BountyCurrency;
+}
+
+export interface Bounty {
+  id: string;
+  taskId: string;
+  reward: BountyReward;
+  status: BountyStatus;
+  createdBy: string;
+  claimedBy?: string;
+  completedAt?: string;
+  deadline?: number;
+  createdAt: string;
+}
+
+export interface ClaimResult {
+  success: boolean;
+  bountyId: string;
+  error?: string;
+}
+
+export interface CompletionProof {
+  commitHash?: string;
+  summary: string;
+  /** Arbitrary evidence (test output, URLs, etc.) */
+  evidence?: string[];
+}
+
+export interface PayoutResult {
+  success: boolean;
+  bountyId: string;
+  amount: number;
+  currency: BountyCurrency;
+  /** Settlement method used (ledger for credits/micro, on-chain for larger USDC) */
+  settlement: 'ledger' | 'on_chain';
+  error?: string;
+}
+
+export interface BountyManagerConfig {
+  /** Optional X402Facilitator for USDC payouts. Without it, only credits work. */
+  facilitator?: X402Facilitator;
+  /** Optional MicroPaymentLedger for credit-based or micro USDC payouts. */
+  ledger?: MicroPaymentLedger;
+  /** Default deadline in ms from creation (default: 7 days). */
+  defaultDeadlineMs?: number;
+}
+
+// ── Manager ──
+
+export class BountyManager {
+  private bounties: Map<string, Bounty> = new Map();
+  private nextId = 1;
+  private config: BountyManagerConfig;
+
+  constructor(config: BountyManagerConfig = {}) {
+    this.config = config;
+  }
+
+  /** Create a bounty for a board task. */
+  createBounty(
+    taskId: string,
+    reward: BountyReward,
+    createdBy: string,
+    deadline?: number,
+  ): Bounty {
+    if (reward.amount <= 0) throw new Error('Bounty reward must be positive');
+
+    const id = `bounty_${String(this.nextId++).padStart(4, '0')}`;
+    const now = Date.now();
+
+    const bounty: Bounty = {
+      id,
+      taskId,
+      reward,
+      status: 'open',
+      createdBy,
+      createdAt: new Date().toISOString(),
+      deadline: deadline ?? (this.config.defaultDeadlineMs
+        ? now + this.config.defaultDeadlineMs
+        : undefined),
+    };
+
+    this.bounties.set(id, bounty);
+    return bounty;
+  }
+
+  /** Claim an open bounty. */
+  claimBounty(bountyId: string, agentId: string): ClaimResult {
+    const bounty = this.bounties.get(bountyId);
+    if (!bounty) return { success: false, bountyId, error: 'Bounty not found' };
+    if (bounty.status !== 'open') return { success: false, bountyId, error: `Bounty is ${bounty.status}, not open` };
+
+    // Check deadline
+    if (bounty.deadline && Date.now() > bounty.deadline) {
+      bounty.status = 'expired';
+      return { success: false, bountyId, error: 'Bounty has expired' };
+    }
+
+    bounty.status = 'claimed';
+    bounty.claimedBy = agentId;
+    return { success: true, bountyId };
+  }
+
+  /** Complete a bounty with proof of work and trigger payout. */
+  completeBounty(bountyId: string, proof: CompletionProof): PayoutResult {
+    const bounty = this.bounties.get(bountyId);
+    if (!bounty) return { success: false, bountyId, amount: 0, currency: 'credits', settlement: 'ledger', error: 'Bounty not found' };
+    if (bounty.status !== 'claimed') return { success: false, bountyId, amount: 0, currency: bounty.reward.currency, settlement: 'ledger', error: `Bounty is ${bounty.status}, not claimed` };
+
+    if (!proof.summary || proof.summary.trim().length === 0) {
+      return { success: false, bountyId, amount: 0, currency: bounty.reward.currency, settlement: 'ledger', error: 'Completion proof requires a summary' };
+    }
+
+    bounty.status = 'completed';
+    bounty.completedAt = new Date().toISOString();
+
+    // Determine settlement method
+    const settlement: 'ledger' | 'on_chain' =
+      bounty.reward.currency === 'credits' ? 'ledger' :
+      bounty.reward.amount < 0.10 ? 'ledger' : 'on_chain';
+
+    return {
+      success: true,
+      bountyId,
+      amount: bounty.reward.amount,
+      currency: bounty.reward.currency,
+      settlement,
+    };
+  }
+
+  /** Get a bounty by ID. */
+  getBounty(bountyId: string): Bounty | undefined {
+    return this.bounties.get(bountyId);
+  }
+
+  /** List bounties, optionally filtered by status. */
+  list(status?: BountyStatus): Bounty[] {
+    const all = Array.from(this.bounties.values());
+    if (!status) return all;
+    return all.filter(b => b.status === status);
+  }
+
+  /** List bounties for a specific task. */
+  byTask(taskId: string): Bounty[] {
+    return Array.from(this.bounties.values()).filter(b => b.taskId === taskId);
+  }
+
+  /** Expire bounties past their deadline. Returns count expired. */
+  expireStale(): number {
+    const now = Date.now();
+    let count = 0;
+    for (const bounty of this.bounties.values()) {
+      if (bounty.deadline && now > bounty.deadline && bounty.status === 'open') {
+        bounty.status = 'expired';
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /** Total open bounty value in a given currency. */
+  totalOpen(currency?: BountyCurrency): number {
+    return this.list('open')
+      .filter(b => !currency || b.reward.currency === currency)
+      .reduce((sum, b) => sum + b.reward.amount, 0);
+  }
+}