@hivemind-os/collective-core 0.2.0

package/src/routing/selector.ts

@@ -0,0 +1,225 @@
+import { type AgentCard, type ProviderScore, ProviderSelectionStrategy, type ReputationScore } from '@hivemind-os/collective-types';
+
+import { ReputationScoreCalculator } from '../reputation/score-calculator.js';
+
+import type { CircuitBreaker } from './circuit-breaker.js';
+import type { PerformanceTracker } from './performance.js';
+
+export interface ProviderSelectionWeights {
+  reputation: number;
+  price: number;
+  speed: number;
+}
+
+export interface ProviderSelectorOptions {
+  circuitBreaker?: Pick<CircuitBreaker, 'isOpen'>;
+  performanceTracker?: Pick<PerformanceTracker, 'getEstimatedLatency'>;
+  reputationCalculator?: ReputationScoreCalculator;
+}
+
+const DEFAULT_WEIGHTS: ProviderSelectionWeights = {
+  reputation: 0.45,
+  price: 0.35,
+  speed: 0.2,
+};
+
+export class ProviderSelector {
+  private readonly circuitBreaker?: Pick<CircuitBreaker, 'isOpen'>;
+  private readonly performanceTracker?: Pick<PerformanceTracker, 'getEstimatedLatency'>;
+  private readonly reputationCalculator: ReputationScoreCalculator;
+  private roundRobinOffset = 0;
+
+  constructor(options: ProviderSelectorOptions = {}) {
+    this.circuitBreaker = options.circuitBreaker;
+    this.performanceTracker = options.performanceTracker;
+    this.reputationCalculator = options.reputationCalculator ?? new ReputationScoreCalculator();
+  }
+
+  rankProviders(agents: AgentCard[], capability: string, weights: Partial<ProviderSelectionWeights> = {}): ProviderScore[] {
+    const normalizedCapability = capability.trim();
+    if (!normalizedCapability) {
+      return [];
+    }
+
+    const candidates = agents
+      .map((agent) => this.toProviderScore(agent, normalizedCapability))
+      .filter((entry): entry is ProviderScore => entry !== null);
+
+    return this.applyCompositeScores(candidates, weights).sort((left, right) => right.compositeScore - left.compositeScore);
+  }
+
+  selectProviders(
+    agents: AgentCard[],
+    capability: string,
+    strategy: ProviderSelectionStrategy,
+    count: number,
+    weights: Partial<ProviderSelectionWeights> = {},
+  ): ProviderScore[] {
+    const ranked = this.rankProviders(agents, capability, weights);
+    const available = ranked.filter((entry) => !entry.circuitBreakerOpen);
+    const selectedCount = Math.max(1, Math.floor(count));
+
+    switch (strategy) {
+      case ProviderSelectionStrategy.CHEAPEST:
+        return this.selectCheapest(available, selectedCount);
+      case ProviderSelectionStrategy.FASTEST:
+        return this.selectFastest(available, selectedCount);
+      case ProviderSelectionStrategy.HIGHEST_REPUTATION:
+        return this.selectHighestReputation(available, selectedCount);
+      case ProviderSelectionStrategy.ROUND_ROBIN:
+        return this.selectRoundRobin(available, selectedCount);
+      case ProviderSelectionStrategy.WEIGHTED:
+      default:
+        return this.selectWeighted(available, selectedCount, weights);
+    }
+  }
+
+  selectCheapest(providers: ProviderScore[], count: number): ProviderScore[] {
+    return [...providers]
+      .sort((left, right) => compareBigInt(left.price, right.price) || compareNumber(right.reputation, left.reputation))
+      .slice(0, count);
+  }
+
+  selectFastest(providers: ProviderScore[], count: number): ProviderScore[] {
+    return [...providers]
+      .sort(
+        (left, right) => compareNumber(left.estimatedLatency ?? Number.POSITIVE_INFINITY, right.estimatedLatency ?? Number.POSITIVE_INFINITY)
+          || compareNumber(right.reputation, left.reputation),
+      )
+      .slice(0, count);
+  }
+
+  selectHighestReputation(providers: ProviderScore[], count: number): ProviderScore[] {
+    return [...providers]
+      .sort((left, right) => compareNumber(right.reputation, left.reputation) || compareBigInt(left.price, right.price))
+      .slice(0, count);
+  }
+
+  selectRoundRobin(providers: ProviderScore[], count: number): ProviderScore[] {
+    if (providers.length === 0) {
+      return [];
+    }
+
+    const start = this.roundRobinOffset % providers.length;
+    const rotated = providers.slice(start).concat(providers.slice(0, start));
+    this.roundRobinOffset = (this.roundRobinOffset + count) % providers.length;
+    return rotated.slice(0, Math.min(count, providers.length));
+  }
+
+  selectWeighted(
+    providers: ProviderScore[],
+    count: number,
+    weights: Partial<ProviderSelectionWeights> = {},
+  ): ProviderScore[] {
+    return this.applyCompositeScores(providers, weights)
+      .sort((left, right) => compareNumber(right.compositeScore, left.compositeScore) || compareBigInt(left.price, right.price))
+      .slice(0, count);
+  }
+
+  private toProviderScore(agent: AgentCard, capability: string): ProviderScore | null {
+    const matchedCapability = agent.capabilities.find((entry) => capabilityNameEquals(entry.name, capability));
+    if (!matchedCapability) {
+      return null;
+    }
+
+    const reputationScore = this.reputationCalculator.computeScore(agent, []);
+    const scopedScore = getScopedReputation(reputationScore, capability);
+    const reputation = scopedScore.successRate * 100 + Math.min(scopedScore.taskCount, 100) * 0.25 - reputationScore.totalDisputes;
+    const estimatedLatency = this.performanceTracker?.getEstimatedLatency(agent.did, matchedCapability.name)
+      ?? scopedScore.averageLatencyMs
+      ?? heuristicLatency(reputation);
+
+    return {
+      did: agent.did,
+      price: matchedCapability.pricing.amount,
+      reputation,
+      estimatedLatency,
+      circuitBreakerOpen: this.circuitBreaker?.isOpen(agent.did) ?? false,
+      compositeScore: 0,
+    };
+  }
+
+  private applyCompositeScores(
+    providers: ProviderScore[],
+    weights: Partial<ProviderSelectionWeights>,
+  ): ProviderScore[] {
+    const normalizedWeights = { ...DEFAULT_WEIGHTS, ...weights };
+    const reputations = providers.map((entry) => entry.reputation);
+    const prices = providers.map((entry) => entry.price);
+    const latencies = providers.map((entry) => entry.estimatedLatency ?? heuristicLatency(entry.reputation));
+
+    return providers.map((provider) => {
+      const normalizedReputation = normalizeNumber(provider.reputation, reputations);
+      const normalizedPrice = normalizeBigInt(provider.price, prices);
+      const normalizedSpeed = 1 - normalizeNumber(provider.estimatedLatency ?? heuristicLatency(provider.reputation), latencies);
+      return {
+        ...provider,
+        compositeScore:
+          normalizedWeights.reputation * normalizedReputation
+          - normalizedWeights.price * normalizedPrice
+          + normalizedWeights.speed * normalizedSpeed,
+      };
+    });
+  }
+}
+
+function getScopedReputation(score: ReputationScore, capability: string): { successRate: number; taskCount: number; averageLatencyMs?: number } {
+  const scoped = score.capabilityScores[capability]
+    ?? Object.entries(score.capabilityScores).find(([entry]) => capabilityNameEquals(entry, capability))?.[1];
+  if (scoped) {
+    return {
+      successRate: scoped.successRate,
+      taskCount: scoped.taskCount,
+      averageLatencyMs: scoped.averageLatencyMs || undefined,
+    };
+  }
+
+  return {
+    successRate: score.successRate,
+    taskCount: score.totalTasks,
+    averageLatencyMs: score.averageLatencyMs || undefined,
+  };
+}
+
+function heuristicLatency(reputation: number): number {
+  return Math.max(100, Math.round(1_500 - Math.max(0, reputation) * 10));
+}
+
+function capabilityNameEquals(left: string, right: string): boolean {
+  return left.toLowerCase() === right.toLowerCase();
+}
+
+function compareBigInt(left: bigint, right: bigint): number {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+}
+
+function compareNumber(left: number, right: number): number {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+}
+
+function normalizeNumber(value: number, values: number[]): number {
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max === min) {
+    return 0.5;
+  }
+
+  return (value - min) / (max - min);
+}
+
+function normalizeBigInt(value: bigint, values: bigint[]): number {
+  const min = values.reduce((current, entry) => (entry < current ? entry : current), values[0] ?? 0n);
+  const max = values.reduce((current, entry) => (entry > current ? entry : current), values[0] ?? 0n);
+  if (max === min) {
+    return 0.5;
+  }
+
+  const scale = 1_000_000n;
+  return Number(((value - min) * scale) / (max - min)) / Number(scale);
+}

package/src/spending/index.ts

@@ -0,0 +1 @@
+export * from './policy.js';

package/src/spending/policy.ts

@@ -0,0 +1,271 @@
+import Database from 'better-sqlite3';
+
+import type { PaymentRail, SpendingPolicy } from '@hivemind-os/collective-types';
+
+export interface SpendingPolicyDecision {
+  approved: boolean;
+  reason?: string;
+}
+
+export interface SpendingPolicyConfig extends SpendingPolicy {
+  perApp?: Record<string, { limits: SpendingPolicy['limits'] }>;
+}
+
+interface SpendingLogRow {
+  total: bigint | number | null;
+}
+
+interface SpendingLogColumn {
+  name: string;
+}
+
+interface SpendingAmount {
+  amount?: bigint;
+  amountMist?: bigint;
+  currency?: string;
+}
+
+export interface SpendingLogEntry {
+  id: number;
+  amountBaseUnits: bigint;
+  rail: PaymentRail;
+  currency?: string;
+  taskId?: string;
+  appId?: string;
+  timestamp: number;
+}
+
+export class SpendingPolicyEngine {
+  private readonly db: Database.Database;
+  private policy: SpendingPolicyConfig;
+
+  constructor(params: { policy: SpendingPolicyConfig; dbPath: string }) {
+    this.policy = params.policy;
+    this.db = new Database(params.dbPath);
+    this.db.defaultSafeIntegers(true);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS spending_log (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        amount_base_units INTEGER NOT NULL,
+        rail TEXT NOT NULL,
+        currency TEXT,
+        task_id TEXT,
+        app_id TEXT,
+        timestamp INTEGER NOT NULL
+      );
+    `);
+    this.migrateSpendingLogSchema();
+  }
+
+  evaluate(request: SpendingAmount & { rail: PaymentRail; appId?: string; originAppName?: string }): SpendingPolicyDecision {
+    const amount = resolveAmount(request);
+    const normalizedCurrency = normalizeCurrency(request.currency);
+    const originAppName = request.originAppName;
+    const normalizedRequest = {
+      amount,
+      currency: normalizedCurrency,
+      rail: request.rail,
+      appId: request.appId,
+    };
+    const perAppPolicy = originAppName ? this.policy.perApp?.[originAppName] : undefined;
+    if (perAppPolicy) {
+      const perAppDecision = this.evaluateLimits(perAppPolicy.limits, normalizedRequest, originAppName);
+      if (!perAppDecision.approved) {
+        return perAppDecision;
+      }
+    }
+
+    if (this.policy.denylist?.includes(request.appId ?? '')) {
+      return { approved: false, reason: 'App is denylisted.' };
+    }
+
+    if (this.policy.allowlist && !this.policy.allowlist.includes(request.appId ?? '')) {
+      return { approved: false, reason: 'App is not allowlisted.' };
+    }
+
+    if (this.policy.requireConfirmationAbove !== undefined && amount > this.policy.requireConfirmationAbove) {
+      return { approved: false, reason: 'Amount requires confirmation.' };
+    }
+
+    return this.evaluateLimits(this.policy.limits, normalizedRequest);
+  }
+
+  record(entry: SpendingAmount & { rail: PaymentRail; taskId: string; appId?: string; originAppName?: string }): void {
+    const amount = resolveAmount(entry);
+    this.db
+      .prepare(
+        `INSERT INTO spending_log (amount_base_units, rail, currency, task_id, app_id, timestamp)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        amount,
+        entry.rail,
+        normalizeCurrency(entry.currency) ?? null,
+        entry.taskId,
+        entry.originAppName ?? entry.appId ?? null,
+        Date.now(),
+      );
+  }
+
+  getSpent(interval: 'hour' | 'day' | 'month', rail?: PaymentRail, appId?: string, currency?: string): bigint {
+    return this.getSpentForLimit(interval, rail, appId, normalizeCurrency(currency));
+  }
+
+  /** Return the most recent spending log entries, newest first. */
+  getRecentEntries(limit = 50): SpendingLogEntry[] {
+    const rows = this.db
+      .prepare(
+        `SELECT id, amount_base_units, rail, currency, task_id, app_id, timestamp
+         FROM spending_log ORDER BY timestamp DESC LIMIT ?`,
+      )
+      .all(limit) as Array<{
+      id: number;
+      amount_base_units: bigint;
+      rail: string;
+      currency: string | null;
+      task_id: string | null;
+      app_id: string | null;
+      timestamp: bigint;
+    }>;
+    return rows.map((row) => ({
+      id: row.id,
+      amountBaseUnits: row.amount_base_units,
+      rail: row.rail as PaymentRail,
+      currency: row.currency ?? undefined,
+      taskId: row.task_id ?? undefined,
+      appId: row.app_id ?? undefined,
+      timestamp: Number(row.timestamp),
+    }));
+  }
+
+  updatePolicy(policy: SpendingPolicyConfig): void {
+    this.policy = policy;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  private evaluateLimits(
+    limits: SpendingPolicy['limits'],
+    request: {
+      amount: bigint;
+      currency?: string;
+      rail: PaymentRail;
+      appId?: string;
+    },
+    appScope?: string,
+  ): SpendingPolicyDecision {
+    for (const limit of limits) {
+      if (limit.rail && limit.rail !== request.rail) {
+        continue;
+      }
+
+      const limitCurrency = normalizeCurrency(limit.currency);
+      if (limitCurrency && limitCurrency !== request.currency) {
+        continue;
+      }
+
+      const scope = appScope ?? limit.scope;
+      if (!appScope && limit.scope && limit.scope !== request.appId) {
+        continue;
+      }
+
+      if (limit.interval === 'transaction' && request.amount > limit.amount) {
+        return { approved: false, reason: `Transaction limit exceeded for ${limit.interval}.` };
+      }
+
+      if (limit.interval === 'transaction') {
+        continue;
+      }
+
+      const spent = this.getSpentForLimit(limit.interval, limit.rail ?? request.rail, scope, limitCurrency ?? request.currency);
+      if (spent + request.amount > limit.amount) {
+        return { approved: false, reason: `Spending limit exceeded for ${limit.interval}.` };
+      }
+    }
+
+    return { approved: true };
+  }
+
+  private getSpentForLimit(
+    interval: 'hour' | 'day' | 'month' | 'lifetime',
+    rail?: PaymentRail,
+    scope?: string,
+    currency?: string,
+  ): bigint {
+    const startTime = interval === 'lifetime' ? 0 : getIntervalStart(interval);
+    let query = 'SELECT COALESCE(SUM(amount_base_units), 0) AS total FROM spending_log WHERE timestamp >= ?';
+    const params: Array<bigint | number | string> = [startTime];
+
+    if (rail) {
+      query += ' AND rail = ?';
+      params.push(rail);
+    }
+
+    if (scope) {
+      query += ' AND app_id = ?';
+      params.push(scope);
+    }
+
+    if (currency) {
+      query += ' AND currency = ?';
+      params.push(currency);
+    }
+
+    const row = this.db.prepare(query).get(...params) as SpendingLogRow | undefined;
+    const total = row?.total ?? 0n;
+    return typeof total === 'bigint' ? total : BigInt(total);
+  }
+
+  private migrateSpendingLogSchema(): void {
+    const columns = this.db.prepare('PRAGMA table_info(spending_log)').all() as SpendingLogColumn[];
+    const columnNames = new Set(columns.map((column) => column.name));
+
+    if (columnNames.has('amount_mist') && !columnNames.has('amount_base_units')) {
+      this.db.exec('ALTER TABLE spending_log RENAME COLUMN amount_mist TO amount_base_units');
+    }
+
+    if (!columnNames.has('currency')) {
+      this.db.exec('ALTER TABLE spending_log ADD COLUMN currency TEXT');
+    }
+  }
+}
+
+function getIntervalStart(interval: 'hour' | 'day' | 'month'): number {
+  const now = new Date(Date.now());
+
+  if (interval === 'hour') {
+    now.setMinutes(0, 0, 0);
+    return now.getTime();
+  }
+
+  if (interval === 'day') {
+    now.setHours(0, 0, 0, 0);
+    return now.getTime();
+  }
+
+  now.setDate(1);
+  now.setHours(0, 0, 0, 0);
+  return now.getTime();
+}
+
+function resolveAmount(value: SpendingAmount): bigint {
+  if (value.amount !== undefined && value.amountMist !== undefined && value.amount !== value.amountMist) {
+    throw new Error('amount and amountMist must match when both are provided.');
+  }
+
+  if (value.amount !== undefined) {
+    return value.amount;
+  }
+
+  if (value.amountMist !== undefined) {
+    return value.amountMist;
+  }
+
+  throw new Error('A spending amount is required.');
+}
+
+function normalizeCurrency(value: string | undefined): string | undefined {
+  return value?.trim() ? value.trim().toUpperCase() : undefined;
+}