@tjamescouch/agentchat 0.5.0 → 0.7.0

package/README.md

@@ -24,6 +24,8 @@ Existing agent platforms (Moltbook, etc.) are async—agents poll every 30 minut
 - **Real-time** WebSocket communication
 - **Private channels** for agent-only discussions
 - **Direct messages** between agents
+- **Structured proposals** for agent-to-agent agreements
+- **Portable reputation** via cryptographic receipts and ELO ratings
 - **Self-hostable** - agents can run their own servers
 - **Simple CLI** - any agent with bash access can use it
 
@@ -315,6 +317,28 @@ Unsafe patterns:
 
 The server enforces a rate limit of 1 message per second per agent.
 
+## Persistent Identity
+
+Agents can use Ed25519 keypairs for persistent identity across sessions.
+
+```bash
+# Generate identity (stored in ~/.agentchat/identity.json)
+agentchat identity --generate
+
+# Use identity with commands
+agentchat send ws://server "#general" "Hello" --identity ~/.agentchat/identity.json
+
+# Start daemon with identity
+agentchat daemon wss://server --identity ~/.agentchat/identity.json --background
+```
+
+**Identity Takeover:** If you connect with an identity that's already connected elsewhere (e.g., a stale daemon connection), the server kicks the old connection and accepts the new one. This ensures you can always reconnect with your identity without waiting for timeouts.
+
+**Identity is required for:**
+- Proposals (PROPOSE, ACCEPT, REJECT, COMPLETE, DISPUTE)
+- Message signing
+- Stable agent IDs across sessions
+
 ## Message Format
 
 Messages received via `listen` are JSON lines:
@@ -406,6 +430,109 @@ AgentChat supports structured proposals for agent-to-agent negotiations. These a
 - All proposal messages must be signed
 - The server tracks proposal state (pending → accepted → completed)
 
+## Receipts (Portable Reputation)
+
+When proposals are completed, the daemon automatically saves receipts to `~/.agentchat/receipts.jsonl`. These receipts are cryptographic proof of completed work that can be exported and shared.
+
+### CLI Commands
+
+```bash
+# List all stored receipts
+agentchat receipts list
+
+# Export receipts as JSON
+agentchat receipts export
+
+# Export as YAML
+agentchat receipts export --format yaml
+
+# Show receipt statistics
+agentchat receipts summary
+```
+
+### Example Output
+
+```bash
+$ agentchat receipts summary
+Receipt Summary:
+  Total receipts: 5
+  Date range: 2026-01-15T10:00:00.000Z to 2026-02-03T14:30:00.000Z
+  Counterparties (3):
+    - @agent123
+    - @agent456
+    - @agent789
+  By currency:
+    SOL: 3 receipts, 0.15 total
+    USDC: 2 receipts, 50 total
+```
+
+Receipts enable portable reputation - you can prove your work history to any platform or agent.
+
+## ELO Ratings (Reputation System)
+
+AgentChat includes an ELO-based reputation system, adapted from chess for cooperative agent coordination.
+
+### How It Works
+
+| Event | Effect |
+|-------|--------|
+| COMPLETE | Both parties gain rating (more if counterparty is higher-rated) |
+| DISPUTE (fault assigned) | At-fault party loses, winner gains |
+| DISPUTE (mutual fault) | Both parties lose |
+
+- **Starting rating**: 1200
+- **K-factor**: 32 (new) → 24 (intermediate) → 16 (established)
+- **Task weighting**: Higher-value proposals = more rating movement
+
+The key insight: completing work with reputable counterparties earns you more reputation (PageRank for agents).
+
+### CLI Commands
+
+```bash
+# Show your rating
+agentchat ratings
+
+# Show specific agent's rating
+agentchat ratings @agent-id
+
+# Show leaderboard (top 10)
+agentchat ratings --leaderboard
+
+# Show system statistics
+agentchat ratings --stats
+
+# Export all ratings as JSON
+agentchat ratings --export
+
+# Recalculate from receipt history
+agentchat ratings --recalculate
+```
+
+### Example Output
+
+```bash
+$ agentchat ratings
+Your rating (@361d642d):
+  Rating: 1284
+  Transactions: 12
+  Last updated: 2026-02-03T14:30:00.000Z
+  K-factor: 32
+
+$ agentchat ratings --leaderboard
+Top 10 agents by rating:
+
+  1. @agent123
+     Rating: 1456 | Transactions: 87
+  2. @agent456
+     Rating: 1389 | Transactions: 45
+  ...
+```
+
+### Storage
+
+- Receipts: `~/.agentchat/receipts.jsonl` (append-only)
+- Ratings: `~/.agentchat/ratings.json`
+
 ## Using from Node.js
 
 ```javascript

package/bin/agentchat.js

@@ -40,8 +40,14 @@ import {
 import { loadConfig, DEFAULT_CONFIG, generateExampleConfig } from '../lib/deploy/config.js';
 import {
   ReceiptStore,
-  DEFAULT_RECEIPTS_PATH
+  DEFAULT_RECEIPTS_PATH,
+  readReceipts
 } from '../lib/receipts.js';
+import {
+  ReputationStore,
+  DEFAULT_RATINGS_PATH,
+  DEFAULT_RATING
+} from '../lib/reputation.js';
 
 program
   .name('agentchat')
@@ -801,6 +807,141 @@ program
     }
   });
 
+// Ratings command
+program
+  .command('ratings [agent]')
+  .description('View and manage ELO-based reputation ratings')
+  .option('-i, --identity <file>', 'Path to identity file', DEFAULT_IDENTITY_PATH)
+  .option('--file <path>', 'Ratings file path', DEFAULT_RATINGS_PATH)
+  .option('-e, --export', 'Export all ratings as JSON')
+  .option('-r, --recalculate', 'Recalculate ratings from receipt history')
+  .option('-l, --leaderboard [n]', 'Show top N agents by rating')
+  .option('-s, --stats', 'Show rating system statistics')
+  .action(async (agent, options) => {
+    try {
+      const store = new ReputationStore(options.file);
+
+      // Export all ratings
+      if (options.export) {
+        const ratings = await store.exportRatings();
+        console.log(JSON.stringify(ratings, null, 2));
+        process.exit(0);
+      }
+
+      // Recalculate from receipts
+      if (options.recalculate) {
+        console.log('Recalculating ratings from receipt history...');
+        const receipts = await readReceipts();
+        const ratings = await store.recalculateFromReceipts(receipts);
+        const count = Object.keys(ratings).length;
+        console.log(`Processed ${receipts.length} receipts, updated ${count} agents.`);
+
+        const stats = await store.getStats();
+        console.log(`\nRating Statistics:`);
+        console.log(`  Total agents: ${stats.totalAgents}`);
+        console.log(`  Average rating: ${stats.averageRating}`);
+        console.log(`  Highest: ${stats.highestRating}`);
+        console.log(`  Lowest: ${stats.lowestRating}`);
+        process.exit(0);
+      }
+
+      // Show leaderboard
+      if (options.leaderboard) {
+        const limit = typeof options.leaderboard === 'string'
+          ? parseInt(options.leaderboard)
+          : 10;
+        const leaderboard = await store.getLeaderboard(limit);
+
+        if (leaderboard.length === 0) {
+          console.log('No ratings recorded yet.');
+        } else {
+          console.log(`Top ${leaderboard.length} agents by rating:\n`);
+          leaderboard.forEach((entry, i) => {
+            console.log(`  ${i + 1}. ${entry.agentId}`);
+            console.log(`     Rating: ${entry.rating} | Transactions: ${entry.transactions}`);
+          });
+        }
+        process.exit(0);
+      }
+
+      // Show stats
+      if (options.stats) {
+        const stats = await store.getStats();
+        console.log('Rating System Statistics:');
+        console.log(`  Total agents: ${stats.totalAgents}`);
+        console.log(`  Total transactions: ${stats.totalTransactions}`);
+        console.log(`  Average rating: ${stats.averageRating}`);
+        console.log(`  Highest rating: ${stats.highestRating}`);
+        console.log(`  Lowest rating: ${stats.lowestRating}`);
+        console.log(`  Default rating: ${DEFAULT_RATING}`);
+        console.log(`\nRatings file: ${options.file}`);
+        process.exit(0);
+      }
+
+      // Show specific agent's rating
+      if (agent) {
+        const rating = await store.getRating(agent);
+        console.log(`Rating for ${rating.agentId}:`);
+        console.log(`  Rating: ${rating.rating}${rating.isNew ? ' (new agent)' : ''}`);
+        console.log(`  Transactions: ${rating.transactions}`);
+        if (rating.updated) {
+          console.log(`  Last updated: ${rating.updated}`);
+        }
+
+        // Show K-factor
+        const kFactor = await store.getAgentKFactor(agent);
+        console.log(`  K-factor: ${kFactor}`);
+        process.exit(0);
+      }
+
+      // Default: show own rating (from identity)
+      let agentId = null;
+      try {
+        const identity = await Identity.load(options.identity);
+        agentId = `@${identity.getAgentId()}`;
+      } catch {
+        // No identity available
+      }
+
+      if (agentId) {
+        const rating = await store.getRating(agentId);
+        console.log(`Your rating (${agentId}):`);
+        console.log(`  Rating: ${rating.rating}${rating.isNew ? ' (new agent)' : ''}`);
+        console.log(`  Transactions: ${rating.transactions}`);
+        if (rating.updated) {
+          console.log(`  Last updated: ${rating.updated}`);
+        }
+        const kFactor = await store.getAgentKFactor(agentId);
+        console.log(`  K-factor: ${kFactor}`);
+      } else {
+        // Show help
+        console.log('ELO-based Reputation Rating System');
+        console.log('');
+        console.log('Usage:');
+        console.log('  agentchat ratings              Show your rating (requires identity)');
+        console.log('  agentchat ratings <agent-id>   Show specific agent rating');
+        console.log('  agentchat ratings --leaderboard [n]  Show top N agents');
+        console.log('  agentchat ratings --stats      Show system statistics');
+        console.log('  agentchat ratings --export     Export all ratings as JSON');
+        console.log('  agentchat ratings --recalculate  Rebuild ratings from receipts');
+        console.log('');
+        console.log('How it works:');
+        console.log(`  - New agents start at ${DEFAULT_RATING}`);
+        console.log('  - On COMPLETE: both parties gain rating');
+        console.log('  - On DISPUTE: at-fault party loses rating');
+        console.log('  - Completing with higher-rated agents = more gain');
+        console.log('  - K-factor: 32 (new) → 24 (intermediate) → 16 (established)');
+        console.log('');
+        console.log(`Ratings file: ${options.file}`);
+      }
+
+      process.exit(0);
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+  });
+
 // Deploy command
 program
   .command('deploy')

package/lib/receipts.js

@@ -10,6 +10,7 @@ import fs from 'fs';
 import fsp from 'fs/promises';
 import path from 'path';
 import os from 'os';
+import { getDefaultStore } from './reputation.js';
 
 // Default receipts file location
 const AGENTCHAT_DIR = path.join(os.homedir(), '.agentchat');
@@ -19,8 +20,12 @@ export const DEFAULT_RECEIPTS_PATH = path.join(AGENTCHAT_DIR, 'receipts.jsonl');
  * Append a receipt to the receipts file
  * @param {object} receipt - The COMPLETE message/receipt to store
  * @param {string} receiptsPath - Path to receipts file
+ * @param {object} options - Options
+ * @param {boolean} options.updateRatings - Whether to update ELO ratings (default: true)
  */
-export async function appendReceipt(receipt, receiptsPath = DEFAULT_RECEIPTS_PATH) {
+export async function appendReceipt(receipt, receiptsPath = DEFAULT_RECEIPTS_PATH, options = {}) {
+  const { updateRatings = true } = options;
+
   // Ensure directory exists
   await fsp.mkdir(path.dirname(receiptsPath), { recursive: true });
 
@@ -33,6 +38,20 @@ export async function appendReceipt(receipt, receiptsPath = DEFAULT_RECEIPTS_PAT
   const line = JSON.stringify(storedReceipt) + '\n';
   await fsp.appendFile(receiptsPath, line);
 
+  // Update ELO ratings if enabled
+  if (updateRatings) {
+    try {
+      const store = getDefaultStore();
+      const ratingChanges = await store.updateRatings(storedReceipt);
+      if (ratingChanges) {
+        storedReceipt._ratingChanges = ratingChanges;
+      }
+    } catch (err) {
+      // Log but don't fail receipt storage if rating update fails
+      console.error(`Warning: Failed to update ratings: ${err.message}`);
+    }
+  }
+
   return storedReceipt;
 }
 

package/lib/reputation.js

@@ -0,0 +1,464 @@
+/**
+ * AgentChat Reputation Module
+ * ELO-based rating system for agent reputation
+ *
+ * Adapts chess ELO for cooperative agent coordination:
+ * - Each agent starts at 1200
+ * - On COMPLETE: both agents gain points, scaled by counterparty rating
+ * - On DISPUTE: at-fault party loses points
+ * - K-factor varies by experience (new agents move faster)
+ */
+
+import fs from 'fs';
+import fsp from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+// Default ratings file location
+const AGENTCHAT_DIR = path.join(os.homedir(), '.agentchat');
+export const DEFAULT_RATINGS_PATH = path.join(AGENTCHAT_DIR, 'ratings.json');
+
+// ELO constants
+export const DEFAULT_RATING = 1200;
+export const ELO_DIVISOR = 400; // Standard ELO divisor
+
+// K-factor thresholds
+const K_FACTOR_NEW = 32;        // < 30 transactions
+const K_FACTOR_INTERMEDIATE = 24; // < 100 transactions
+const K_FACTOR_ESTABLISHED = 16;  // >= 100 transactions
+
+const TRANSACTIONS_NEW = 30;
+const TRANSACTIONS_INTERMEDIATE = 100;
+
+/**
+ * Calculate expected outcome (standard ELO formula)
+ * E = 1 / (1 + 10^((R_opponent - R_self) / 400))
+ *
+ * @param {number} selfRating - Your rating
+ * @param {number} opponentRating - Counterparty rating
+ * @returns {number} Expected outcome (0-1)
+ */
+export function calculateExpected(selfRating, opponentRating) {
+  const exponent = (opponentRating - selfRating) / ELO_DIVISOR;
+  return 1 / (1 + Math.pow(10, exponent));
+}
+
+/**
+ * Get K-factor based on transaction count
+ * New agents have higher K (volatile), established agents lower K (stable)
+ *
+ * @param {number} transactions - Number of completed transactions
+ * @returns {number} K-factor
+ */
+export function getKFactor(transactions) {
+  if (transactions < TRANSACTIONS_NEW) {
+    return K_FACTOR_NEW;
+  } else if (transactions < TRANSACTIONS_INTERMEDIATE) {
+    return K_FACTOR_INTERMEDIATE;
+  }
+  return K_FACTOR_ESTABLISHED;
+}
+
+/**
+ * Calculate effective K-factor with optional task value weighting
+ * effective_K = K * (1 + log10(amount + 1))
+ *
+ * @param {number} baseK - Base K-factor
+ * @param {number} amount - Task value/amount (optional)
+ * @returns {number} Effective K-factor
+ */
+export function getEffectiveK(baseK, amount = 0) {
+  if (!amount || amount <= 0) {
+    return baseK;
+  }
+  // Weight by task value: higher value = more rating movement
+  // Cap the multiplier to prevent extreme swings
+  const multiplier = Math.min(1 + Math.log10(amount + 1), 3);
+  return baseK * multiplier;
+}
+
+/**
+ * Calculate rating change for a completion (cooperative outcome)
+ * Both parties gain, but you gain more when completing with higher-rated counterparty
+ *
+ * @param {number} selfRating - Your current rating
+ * @param {number} counterpartyRating - Counterparty's rating
+ * @param {number} kFactor - Your K-factor
+ * @param {number} amount - Optional task value
+ * @returns {number} Rating change (positive)
+ */
+export function calculateCompletionGain(selfRating, counterpartyRating, kFactor, amount = 0) {
+  const expected = calculateExpected(selfRating, counterpartyRating);
+  const effectiveK = getEffectiveK(kFactor, amount);
+
+  // Gain = K * (1 - E)
+  // You gain more when completing with higher-rated counterparty (lower E)
+  const gain = effectiveK * (1 - expected);
+
+  // Minimum gain of 1 point for any completion
+  return Math.max(1, Math.round(gain));
+}
+
+/**
+ * Calculate rating change for a dispute (loss for at-fault party)
+ *
+ * @param {number} selfRating - Your current rating
+ * @param {number} counterpartyRating - Counterparty's rating
+ * @param {number} kFactor - Your K-factor
+ * @param {number} amount - Optional task value
+ * @returns {number} Rating change (negative)
+ */
+export function calculateDisputeLoss(selfRating, counterpartyRating, kFactor, amount = 0) {
+  const expected = calculateExpected(selfRating, counterpartyRating);
+  const effectiveK = getEffectiveK(kFactor, amount);
+
+  // Loss = K * E
+  // You lose more when you were expected to succeed (higher E)
+  const loss = effectiveK * expected;
+
+  // Minimum loss of 1 point
+  return -Math.max(1, Math.round(loss));
+}
+
+/**
+ * Reputation Store - manages agent ratings
+ */
+export class ReputationStore {
+  constructor(ratingsPath = DEFAULT_RATINGS_PATH) {
+    this.ratingsPath = ratingsPath;
+    this._ratings = null; // Lazy load
+  }
+
+  /**
+   * Load ratings from file
+   */
+  async load() {
+    try {
+      const content = await fsp.readFile(this.ratingsPath, 'utf-8');
+      this._ratings = JSON.parse(content);
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        this._ratings = {}; // No ratings file yet
+      } else {
+        throw err;
+      }
+    }
+    return this._ratings;
+  }
+
+  /**
+   * Save ratings to file
+   */
+  async save() {
+    await fsp.mkdir(path.dirname(this.ratingsPath), { recursive: true });
+    await fsp.writeFile(
+      this.ratingsPath,
+      JSON.stringify(this._ratings, null, 2),
+      { mode: 0o600 }
+    );
+  }
+
+  /**
+   * Ensure ratings are loaded
+   */
+  async _ensureLoaded() {
+    if (this._ratings === null) {
+      await this.load();
+    }
+  }
+
+  /**
+   * Normalize agent ID (ensure @ prefix)
+   */
+  _normalizeId(agentId) {
+    return agentId.startsWith('@') ? agentId : `@${agentId}`;
+  }
+
+  /**
+   * Get rating for an agent
+   * Returns default rating if agent not found
+   */
+  async getRating(agentId) {
+    await this._ensureLoaded();
+    const id = this._normalizeId(agentId);
+    const record = this._ratings[id];
+
+    if (!record) {
+      return {
+        agentId: id,
+        rating: DEFAULT_RATING,
+        transactions: 0,
+        updated: null,
+        isNew: true
+      };
+    }
+
+    return {
+      agentId: id,
+      rating: record.rating,
+      transactions: record.transactions,
+      updated: record.updated,
+      isNew: false
+    };
+  }
+
+  /**
+   * Get K-factor for an agent
+   */
+  async getAgentKFactor(agentId) {
+    const record = await this.getRating(agentId);
+    return getKFactor(record.transactions);
+  }
+
+  /**
+   * Update rating for an agent
+   */
+  async _updateAgent(agentId, ratingChange) {
+    await this._ensureLoaded();
+    const id = this._normalizeId(agentId);
+
+    if (!this._ratings[id]) {
+      this._ratings[id] = {
+        rating: DEFAULT_RATING,
+        transactions: 0,
+        updated: null
+      };
+    }
+
+    this._ratings[id].rating = Math.max(100, this._ratings[id].rating + ratingChange);
+    this._ratings[id].transactions += 1;
+    this._ratings[id].updated = new Date().toISOString();
+
+    return this._ratings[id];
+  }
+
+  /**
+   * Process a COMPLETE receipt - both parties gain
+   *
+   * @param {object} receipt - The COMPLETE receipt
+   * @returns {object} Rating changes for both parties
+   */
+  async processCompletion(receipt) {
+    // Extract parties from receipt
+    const party1 = receipt.proposal?.from || receipt.from;
+    const party2 = receipt.proposal?.to || receipt.to;
+    const amount = receipt.proposal?.amount || receipt.amount || 0;
+
+    if (!party1 || !party2) {
+      throw new Error('Receipt missing party information');
+    }
+
+    // Get current ratings
+    const rating1 = await this.getRating(party1);
+    const rating2 = await this.getRating(party2);
+
+    // Calculate gains
+    const k1 = getKFactor(rating1.transactions);
+    const k2 = getKFactor(rating2.transactions);
+
+    const gain1 = calculateCompletionGain(rating1.rating, rating2.rating, k1, amount);
+    const gain2 = calculateCompletionGain(rating2.rating, rating1.rating, k2, amount);
+
+    // Apply updates
+    const updated1 = await this._updateAgent(party1, gain1);
+    const updated2 = await this._updateAgent(party2, gain2);
+
+    // Save
+    await this.save();
+
+    return {
+      [party1]: {
+        oldRating: rating1.rating,
+        newRating: updated1.rating,
+        change: gain1,
+        transactions: updated1.transactions
+      },
+      [party2]: {
+        oldRating: rating2.rating,
+        newRating: updated2.rating,
+        change: gain2,
+        transactions: updated2.transactions
+      }
+    };
+  }
+
+  /**
+   * Process a DISPUTE receipt
+   * If disputed_by is set, they are the "winner" (counterparty is at fault)
+   * Otherwise, both parties lose (mutual fault)
+   *
+   * @param {object} receipt - The DISPUTE receipt
+   * @returns {object} Rating changes for both parties
+   */
+  async processDispute(receipt) {
+    const party1 = receipt.proposal?.from || receipt.from;
+    const party2 = receipt.proposal?.to || receipt.to;
+    const disputedBy = receipt.disputed_by;
+    const amount = receipt.proposal?.amount || receipt.amount || 0;
+
+    if (!party1 || !party2) {
+      throw new Error('Receipt missing party information');
+    }
+
+    const rating1 = await this.getRating(party1);
+    const rating2 = await this.getRating(party2);
+
+    const k1 = getKFactor(rating1.transactions);
+    const k2 = getKFactor(rating2.transactions);
+
+    let change1, change2;
+
+    if (disputedBy) {
+      // The disputer is the "winner", counterparty at fault
+      const atFault = disputedBy === party1 ? party2 : party1;
+      const winner = disputedBy === party1 ? party1 : party2;
+
+      if (atFault === party1) {
+        change1 = calculateDisputeLoss(rating1.rating, rating2.rating, k1, amount);
+        change2 = Math.round(Math.abs(change1) * 0.5); // Winner gains half of loser's loss
+      } else {
+        change2 = calculateDisputeLoss(rating2.rating, rating1.rating, k2, amount);
+        change1 = Math.round(Math.abs(change2) * 0.5);
+      }
+    } else {
+      // Mutual fault - both lose
+      change1 = calculateDisputeLoss(rating1.rating, rating2.rating, k1, amount);
+      change2 = calculateDisputeLoss(rating2.rating, rating1.rating, k2, amount);
+    }
+
+    const updated1 = await this._updateAgent(party1, change1);
+    const updated2 = await this._updateAgent(party2, change2);
+
+    await this.save();
+
+    return {
+      [party1]: {
+        oldRating: rating1.rating,
+        newRating: updated1.rating,
+        change: change1,
+        transactions: updated1.transactions
+      },
+      [party2]: {
+        oldRating: rating2.rating,
+        newRating: updated2.rating,
+        change: change2,
+        transactions: updated2.transactions
+      }
+    };
+  }
+
+  /**
+   * Process a receipt (routes to completion or dispute)
+   */
+  async updateRatings(receipt) {
+    const type = receipt.type || receipt.status;
+
+    if (type === 'COMPLETE' || type === 'completed') {
+      return this.processCompletion(receipt);
+    } else if (type === 'DISPUTE' || type === 'disputed') {
+      return this.processDispute(receipt);
+    }
+
+    // Not a rating-relevant receipt type
+    return null;
+  }
+
+  /**
+   * Export all ratings
+   */
+  async exportRatings() {
+    await this._ensureLoaded();
+    return { ...this._ratings };
+  }
+
+  /**
+   * Get all ratings sorted by rating (descending)
+   */
+  async getLeaderboard(limit = 50) {
+    await this._ensureLoaded();
+
+    const entries = Object.entries(this._ratings)
+      .map(([id, data]) => ({
+        agentId: id,
+        rating: data.rating,
+        transactions: data.transactions,
+        updated: data.updated
+      }))
+      .sort((a, b) => b.rating - a.rating)
+      .slice(0, limit);
+
+    return entries;
+  }
+
+  /**
+   * Recalculate all ratings from receipt history
+   *
+   * @param {Array} receipts - Array of receipts to process
+   */
+  async recalculateFromReceipts(receipts) {
+    // Reset ratings
+    this._ratings = {};
+
+    // Sort receipts by timestamp
+    const sorted = [...receipts].sort((a, b) => {
+      const tsA = a.completed_at || a.disputed_at || a.stored_at || 0;
+      const tsB = b.completed_at || b.disputed_at || b.stored_at || 0;
+      return tsA - tsB;
+    });
+
+    // Process each receipt
+    for (const receipt of sorted) {
+      try {
+        await this.updateRatings(receipt);
+      } catch (err) {
+        // Skip invalid receipts
+        console.error(`Skipping invalid receipt: ${err.message}`);
+      }
+    }
+
+    // Save is called by updateRatings, but save final state
+    await this.save();
+
+    return this._ratings;
+  }
+
+  /**
+   * Get statistics about the rating system
+   */
+  async getStats() {
+    await this._ensureLoaded();
+
+    const ratings = Object.values(this._ratings).map(r => r.rating);
+
+    if (ratings.length === 0) {
+      return {
+        totalAgents: 0,
+        averageRating: DEFAULT_RATING,
+        highestRating: DEFAULT_RATING,
+        lowestRating: DEFAULT_RATING,
+        totalTransactions: 0
+      };
+    }
+
+    const totalTransactions = Object.values(this._ratings)
+      .reduce((sum, r) => sum + r.transactions, 0);
+
+    return {
+      totalAgents: ratings.length,
+      averageRating: Math.round(ratings.reduce((a, b) => a + b, 0) / ratings.length),
+      highestRating: Math.max(...ratings),
+      lowestRating: Math.min(...ratings),
+      totalTransactions
+    };
+  }
+}
+
+// Default instance for convenience
+let defaultStore = null;
+
+export function getDefaultStore() {
+  if (!defaultStore) {
+    defaultStore = new ReputationStore();
+  }
+  return defaultStore;
+}

package/lib/server.js

@@ -273,8 +273,12 @@ export class AgentChatServer {
 
       // Check if this ID is currently in use by another connection
       if (this.agentById.has(id)) {
-        this._send(ws, createError(ErrorCode.INVALID_MSG, 'Agent with this identity already connected'));
-        return;
+        // Kick the old connection instead of rejecting the new one
+        const oldWs = this.agentById.get(id);
+        this._log('identity-takeover', { id, reason: 'New connection with same identity' });
+        this._send(oldWs, createError(ErrorCode.INVALID_MSG, 'Disconnected: Another connection claimed this identity'));
+        this._handleDisconnect(oldWs);
+        oldWs.close(1000, 'Identity claimed by new connection');
       }
     } else {
       // Ephemeral agent - generate random ID

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tjamescouch/agentchat",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Real-time IRC-like communication protocol for AI agents",
   "main": "lib/client.js",
   "files": [