@tjamescouch/agentchat 0.10.0 → 0.12.0

package/lib/escrow-hooks.js

@@ -0,0 +1,237 @@
+/**
+ * EscrowHooks - Event system for external escrow integration
+ *
+ * Allows external systems (blockchain, multi-sig, compliance) to hook into
+ * escrow lifecycle events without modifying core AgentChat code.
+ *
+ * Events:
+ *   escrow:created    - Escrow created when proposal accepted with stakes
+ *   escrow:released   - Escrow released (expired, cancelled)
+ *   settlement:completion - Proposal completed, stakes returned
+ *   settlement:dispute    - Proposal disputed, stakes transferred/burned
+ */
+
+export const EscrowEvent = {
+  CREATED: 'escrow:created',
+  RELEASED: 'escrow:released',
+  COMPLETION_SETTLED: 'settlement:completion',
+  DISPUTE_SETTLED: 'settlement:dispute'
+};
+
+export class EscrowHooks {
+  constructor(options = {}) {
+    this.handlers = new Map(); // event -> Set of handlers
+    this.logger = options.logger || console;
+    this.continueOnError = options.continueOnError !== false; // default true
+
+    // Initialize event handler sets
+    for (const event of Object.values(EscrowEvent)) {
+      this.handlers.set(event, new Set());
+    }
+  }
+
+  /**
+   * Register a handler for an escrow event
+   * @param {string} event - Event name from EscrowEvent
+   * @param {Function} handler - Async function(payload) to call
+   * @returns {Function} Unsubscribe function
+   */
+  on(event, handler) {
+    if (!this.handlers.has(event)) {
+      throw new Error(`Unknown escrow event: ${event}`);
+    }
+
+    if (typeof handler !== 'function') {
+      throw new Error('Handler must be a function');
+    }
+
+    this.handlers.get(event).add(handler);
+
+    // Return unsubscribe function
+    return () => this.off(event, handler);
+  }
+
+  /**
+   * Remove a handler for an escrow event
+   * @param {string} event - Event name
+   * @param {Function} handler - Handler to remove
+   */
+  off(event, handler) {
+    if (this.handlers.has(event)) {
+      this.handlers.get(event).delete(handler);
+    }
+  }
+
+  /**
+   * Remove all handlers for an event (or all events)
+   * @param {string} [event] - Optional event name
+   */
+  clear(event) {
+    if (event) {
+      if (this.handlers.has(event)) {
+        this.handlers.get(event).clear();
+      }
+    } else {
+      for (const handlers of this.handlers.values()) {
+        handlers.clear();
+      }
+    }
+  }
+
+  /**
+   * Emit an escrow event to all registered handlers
+   * @param {string} event - Event name
+   * @param {Object} payload - Event payload
+   * @returns {Promise<Object>} Results from all handlers
+   */
+  async emit(event, payload) {
+    if (!this.handlers.has(event)) {
+      throw new Error(`Unknown escrow event: ${event}`);
+    }
+
+    const handlers = this.handlers.get(event);
+    if (handlers.size === 0) {
+      return { event, handled: false, results: [] };
+    }
+
+    const results = [];
+    const errors = [];
+
+    for (const handler of handlers) {
+      try {
+        const result = await handler(payload);
+        results.push({ success: true, result });
+      } catch (err) {
+        const errorInfo = {
+          success: false,
+          error: err.message,
+          stack: err.stack
+        };
+        errors.push(errorInfo);
+        results.push(errorInfo);
+
+        this.logger.error?.(`[EscrowHooks] Error in ${event} handler:`, err.message);
+
+        if (!this.continueOnError) {
+          break;
+        }
+      }
+    }
+
+    return {
+      event,
+      handled: true,
+      results,
+      errors: errors.length > 0 ? errors : undefined
+    };
+  }
+
+  /**
+   * Check if any handlers are registered for an event
+   * @param {string} event - Event name
+   * @returns {boolean}
+   */
+  hasHandlers(event) {
+    return this.handlers.has(event) && this.handlers.get(event).size > 0;
+  }
+
+  /**
+   * Get count of handlers for an event
+   * @param {string} event - Event name
+   * @returns {number}
+   */
+  handlerCount(event) {
+    return this.handlers.has(event) ? this.handlers.get(event).size : 0;
+  }
+}
+
+/**
+ * Create payload for escrow:created event
+ */
+export function createEscrowCreatedPayload(proposal, escrowResult) {
+  return {
+    event: EscrowEvent.CREATED,
+    timestamp: Date.now(),
+    proposal_id: proposal.id,
+    from_agent: proposal.from,
+    to_agent: proposal.to,
+    proposer_stake: proposal.proposer_stake || 0,
+    acceptor_stake: proposal.acceptor_stake || 0,
+    total_stake: (proposal.proposer_stake || 0) + (proposal.acceptor_stake || 0),
+    task: proposal.task,
+    amount: proposal.amount,
+    currency: proposal.currency,
+    expires: proposal.expires,
+    escrow_id: escrowResult.escrow?.proposal_id || proposal.id
+  };
+}
+
+/**
+ * Create payload for settlement:completion event
+ */
+export function createCompletionPayload(proposal, ratingChanges) {
+  const escrowInfo = ratingChanges?._escrow || {};
+  return {
+    event: EscrowEvent.COMPLETION_SETTLED,
+    timestamp: Date.now(),
+    proposal_id: proposal.id,
+    from_agent: proposal.from,
+    to_agent: proposal.to,
+    completed_by: proposal.completed_by,
+    completion_proof: proposal.completion_proof,
+    settlement: 'returned',
+    stakes_returned: {
+      proposer: escrowInfo.proposer_stake || 0,
+      acceptor: escrowInfo.acceptor_stake || 0
+    },
+    rating_changes: {
+      [proposal.from]: ratingChanges?.[proposal.from],
+      [proposal.to]: ratingChanges?.[proposal.to]
+    }
+  };
+}
+
+/**
+ * Create payload for settlement:dispute event
+ */
+export function createDisputePayload(proposal, ratingChanges) {
+  const escrowInfo = ratingChanges?._escrow || {};
+  return {
+    event: EscrowEvent.DISPUTE_SETTLED,
+    timestamp: Date.now(),
+    proposal_id: proposal.id,
+    from_agent: proposal.from,
+    to_agent: proposal.to,
+    disputed_by: proposal.disputed_by,
+    dispute_reason: proposal.dispute_reason,
+    settlement: escrowInfo.settlement || 'settled',
+    settlement_reason: escrowInfo.settlement_reason,
+    fault_determination: escrowInfo.fault_party,
+    stakes_transferred: escrowInfo.transferred,
+    stakes_burned: escrowInfo.burned,
+    rating_changes: {
+      [proposal.from]: ratingChanges?.[proposal.from],
+      [proposal.to]: ratingChanges?.[proposal.to]
+    }
+  };
+}
+
+/**
+ * Create payload for escrow:released event
+ */
+export function createEscrowReleasedPayload(proposalId, escrow, reason) {
+  return {
+    event: EscrowEvent.RELEASED,
+    timestamp: Date.now(),
+    proposal_id: proposalId,
+    from_agent: escrow.from?.agent_id,
+    to_agent: escrow.to?.agent_id,
+    stakes_released: {
+      proposer: escrow.from?.stake || 0,
+      acceptor: escrow.to?.stake || 0
+    },
+    reason: reason || 'expired'
+  };
+}
+
+export default EscrowHooks;

package/lib/identity.js

@@ -44,6 +44,7 @@ export class Identity {
     this.pubkey = data.pubkey;      // PEM format
     this.privkey = data.privkey;    // PEM format (null if loaded from export)
     this.created = data.created;
+    this.rotations = data.rotations || [];  // Array of rotation records
 
     // Lazy-load crypto key objects
     this._publicKey = null;
@@ -85,7 +86,8 @@ export class Identity {
       name: this.name,
       pubkey: this.pubkey,
       privkey: this.privkey,
-      created: this.created
+      created: this.created,
+      rotations: this.rotations
     };
 
     await fs.writeFile(filePath, JSON.stringify(data, null, 2), {
@@ -160,7 +162,137 @@ export class Identity {
     return {
       name: this.name,
       pubkey: this.pubkey,
-      created: this.created
+      created: this.created,
+      rotations: this.rotations
     };
   }
+
+  /**
+   * Rotate to a new keypair
+   * Signs the new public key with the old private key for chain of custody
+   * @returns {object} Rotation record with old_pubkey, new_pubkey, signature, timestamp
+   */
+  rotate() {
+    if (!this.privkey) {
+      throw new Error('Private key not available - cannot rotate');
+    }
+
+    // Generate new keypair
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+    const newPubkey = publicKey.export({ type: 'spki', format: 'pem' });
+    const newPrivkey = privateKey.export({ type: 'pkcs8', format: 'pem' });
+
+    // Use same timestamp for both signing and record
+    const timestamp = new Date().toISOString();
+
+    // Create rotation record content to sign
+    const rotationContent = JSON.stringify({
+      old_pubkey: this.pubkey,
+      new_pubkey: newPubkey,
+      timestamp
+    });
+
+    // Sign with old private key
+    const signature = this.sign(rotationContent);
+
+    // Create rotation record
+    const rotationRecord = {
+      old_pubkey: this.pubkey,
+      old_agent_id: this.getAgentId(),
+      new_pubkey: newPubkey,
+      new_agent_id: pubkeyToAgentId(newPubkey),
+      signature,
+      timestamp
+    };
+
+    // Update identity with new keys
+    this.rotations.push(rotationRecord);
+    this.pubkey = newPubkey;
+    this.privkey = newPrivkey;
+    this._publicKey = null;
+    this._privateKey = null;
+
+    return rotationRecord;
+  }
+
+  /**
+   * Verify a rotation record
+   * Checks that the signature is valid using the old public key
+   * @param {object} record - Rotation record to verify
+   * @returns {boolean} True if signature is valid
+   */
+  static verifyRotation(record) {
+    try {
+      const rotationContent = JSON.stringify({
+        old_pubkey: record.old_pubkey,
+        new_pubkey: record.new_pubkey,
+        timestamp: record.timestamp
+      });
+
+      return Identity.verify(rotationContent, record.signature, record.old_pubkey);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Verify the entire rotation chain
+   * @returns {object} { valid: boolean, errors: string[] }
+   */
+  verifyRotationChain() {
+    const errors = [];
+
+    if (this.rotations.length === 0) {
+      return { valid: true, errors: [] };
+    }
+
+    // Verify each rotation in sequence
+    for (let i = 0; i < this.rotations.length; i++) {
+      const record = this.rotations[i];
+
+      // Verify signature
+      if (!Identity.verifyRotation(record)) {
+        errors.push(`Rotation ${i + 1}: Invalid signature`);
+        continue;
+      }
+
+      // Verify chain continuity (each new_pubkey should match next old_pubkey)
+      if (i < this.rotations.length - 1) {
+        const nextRecord = this.rotations[i + 1];
+        if (record.new_pubkey !== nextRecord.old_pubkey) {
+          errors.push(`Rotation ${i + 1}: Chain break - new_pubkey doesn't match next old_pubkey`);
+        }
+      }
+    }
+
+    // Verify final pubkey matches current identity
+    const lastRotation = this.rotations[this.rotations.length - 1];
+    if (lastRotation.new_pubkey !== this.pubkey) {
+      errors.push('Final rotation new_pubkey does not match current identity pubkey');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Get the original (genesis) public key before any rotations
+   * @returns {string} Original public key in PEM format
+   */
+  getOriginalPubkey() {
+    if (this.rotations.length === 0) {
+      return this.pubkey;
+    }
+    return this.rotations[0].old_pubkey;
+  }
+
+  /**
+   * Get the original (genesis) agent ID
+   * @returns {string} Original agent ID
+   */
+  getOriginalAgentId() {
+    return pubkeyToAgentId(this.getOriginalPubkey());
+  }
 }

package/lib/proposals.js

@@ -45,6 +45,10 @@ export class ProposalStore {
       created_at: now,
       updated_at: now,
       sig: proposal.sig,
+      // ELO staking
+      proposer_stake: proposal.elo_stake || null,
+      acceptor_stake: null,
+      stakes_escrowed: false,
       // Response tracking
       response_sig: null,
       response_payment_code: null,
@@ -82,8 +86,13 @@ export class ProposalStore {
 
   /**
    * Accept a proposal
+   * @param {string} id - Proposal ID
+   * @param {string} acceptorId - Agent accepting the proposal
+   * @param {string} sig - Signature of acceptance
+   * @param {string} payment_code - Optional payment code
+   * @param {number} acceptor_stake - Optional ELO stake from acceptor
    */
-  accept(id, acceptorId, sig, payment_code = null) {
+  accept(id, acceptorId, sig, payment_code = null, acceptor_stake = null) {
     const proposal = this.get(id);
     if (!proposal) {
       return { error: 'PROPOSAL_NOT_FOUND' };
@@ -106,6 +115,7 @@ export class ProposalStore {
     proposal.status = ProposalStatus.ACCEPTED;
     proposal.response_sig = sig;
     proposal.response_payment_code = payment_code;
+    proposal.acceptor_stake = acceptor_stake;
     proposal.updated_at = Date.now();
 
     return { proposal };
@@ -296,7 +306,8 @@ export function formatProposal(proposal) {
     expires: proposal.expires,
     status: proposal.status,
     created_at: proposal.created_at,
-    sig: proposal.sig
+    sig: proposal.sig,
+    elo_stake: proposal.proposer_stake
   };
 }
 
@@ -317,7 +328,9 @@ export function formatProposalResponse(proposal, responseType) {
         from: proposal.from,
         to: proposal.to,
         payment_code: proposal.response_payment_code,
-        sig: proposal.response_sig
+        sig: proposal.response_sig,
+        proposer_stake: proposal.proposer_stake,
+        acceptor_stake: proposal.acceptor_stake
       };
 
     case 'reject':
@@ -337,7 +350,11 @@ export function formatProposalResponse(proposal, responseType) {
         completed_by: proposal.completed_by,
         completed_at: proposal.completed_at,
         proof: proposal.completion_proof,
-        sig: proposal.completion_sig
+        sig: proposal.completion_sig,
+        elo_stakes: {
+          proposer: proposal.proposer_stake || 0,
+          acceptor: proposal.acceptor_stake || 0
+        }
       };
 
     case 'dispute':
@@ -348,7 +365,11 @@ export function formatProposalResponse(proposal, responseType) {
         disputed_by: proposal.disputed_by,
         disputed_at: proposal.disputed_at,
         reason: proposal.dispute_reason,
-        sig: proposal.dispute_sig
+        sig: proposal.dispute_sig,
+        elo_stakes: {
+          proposer: proposal.proposer_stake || 0,
+          acceptor: proposal.acceptor_stake || 0
+        }
       };
 
     default:
@@ -367,16 +388,20 @@ export function getProposalSigningContent(proposal) {
     proposal.amount || '',
     proposal.currency || '',
     proposal.payment_code || '',
-    proposal.expires || ''
+    proposal.expires || '',
+    proposal.elo_stake || ''
   ];
   return fields.join('|');
 }
 
 /**
  * Create accept content string for signing
+ * @param {string} proposalId - The proposal being accepted
+ * @param {string} payment_code - Optional payment code
+ * @param {number} elo_stake - Optional ELO stake from acceptor
  */
-export function getAcceptSigningContent(proposalId, payment_code = '') {
-  return `ACCEPT|${proposalId}|${payment_code}`;
+export function getAcceptSigningContent(proposalId, payment_code = '', elo_stake = '') {
+  return `ACCEPT|${proposalId}|${payment_code}|${elo_stake}`;
 }
 
 /**

package/lib/protocol.js

@@ -24,7 +24,12 @@ export const ClientMessageType = {
   DISPUTE: 'DISPUTE',
   // Skill discovery message types
   REGISTER_SKILLS: 'REGISTER_SKILLS',
-  SEARCH_SKILLS: 'SEARCH_SKILLS'
+  SEARCH_SKILLS: 'SEARCH_SKILLS',
+  // Presence message types
+  SET_PRESENCE: 'SET_PRESENCE',
+  // Identity verification message types
+  VERIFY_REQUEST: 'VERIFY_REQUEST',
+  VERIFY_RESPONSE: 'VERIFY_RESPONSE'
 };
 
 // Server -> Client message types
@@ -47,7 +52,14 @@ export const ServerMessageType = {
   DISPUTE: 'DISPUTE',
   // Skill discovery message types
   SKILLS_REGISTERED: 'SKILLS_REGISTERED',
-  SEARCH_RESULTS: 'SEARCH_RESULTS'
+  SEARCH_RESULTS: 'SEARCH_RESULTS',
+  // Presence message types
+  PRESENCE_CHANGED: 'PRESENCE_CHANGED',
+  // Identity verification message types
+  VERIFY_REQUEST: 'VERIFY_REQUEST',
+  VERIFY_RESPONSE: 'VERIFY_RESPONSE',
+  VERIFY_SUCCESS: 'VERIFY_SUCCESS',
+  VERIFY_FAILED: 'VERIFY_FAILED'
 };
 
 // Error codes
@@ -65,7 +77,22 @@ export const ErrorCode = {
   PROPOSAL_EXPIRED: 'PROPOSAL_EXPIRED',
   INVALID_PROPOSAL: 'INVALID_PROPOSAL',
   SIGNATURE_REQUIRED: 'SIGNATURE_REQUIRED',
-  NOT_PROPOSAL_PARTY: 'NOT_PROPOSAL_PARTY'
+  NOT_PROPOSAL_PARTY: 'NOT_PROPOSAL_PARTY',
+  // Staking errors
+  INSUFFICIENT_REPUTATION: 'INSUFFICIENT_REPUTATION',
+  INVALID_STAKE: 'INVALID_STAKE',
+  // Verification errors
+  VERIFICATION_FAILED: 'VERIFICATION_FAILED',
+  VERIFICATION_EXPIRED: 'VERIFICATION_EXPIRED',
+  NO_PUBKEY: 'NO_PUBKEY'
+};
+
+// Presence status
+export const PresenceStatus = {
+  ONLINE: 'online',
+  AWAY: 'away',
+  BUSY: 'busy',
+  OFFLINE: 'offline'
 };
 
 // Proposal status
@@ -250,20 +277,40 @@ export function validateClientMessage(raw) {
       if (!msg.sig) {
         return { valid: false, error: 'Proposals must be signed' };
       }
-      // Optional fields: amount, currency, payment_code, expires, terms
+      // Optional fields: amount, currency, payment_code, expires, terms, elo_stake
       if (msg.expires !== undefined && typeof msg.expires !== 'number') {
         return { valid: false, error: 'expires must be a number (seconds)' };
       }
+      if (msg.elo_stake !== undefined) {
+        if (typeof msg.elo_stake !== 'number' || msg.elo_stake < 0 || !Number.isInteger(msg.elo_stake)) {
+          return { valid: false, error: 'elo_stake must be a non-negative integer' };
+        }
+      }
       break;
 
     case ClientMessageType.ACCEPT:
+      // Accept requires: proposal_id and signature
+      if (!msg.proposal_id) {
+        return { valid: false, error: 'Missing proposal_id' };
+      }
+      if (!msg.sig) {
+        return { valid: false, error: 'Accept must be signed' };
+      }
+      // Optional: elo_stake for acceptor's stake
+      if (msg.elo_stake !== undefined) {
+        if (typeof msg.elo_stake !== 'number' || msg.elo_stake < 0 || !Number.isInteger(msg.elo_stake)) {
+          return { valid: false, error: 'elo_stake must be a non-negative integer' };
+        }
+      }
+      break;
+
     case ClientMessageType.REJECT:
-      // Accept/Reject require: proposal_id and signature
+      // Reject requires: proposal_id and signature
       if (!msg.proposal_id) {
         return { valid: false, error: 'Missing proposal_id' };
       }
       if (!msg.sig) {
-        return { valid: false, error: 'Accept/Reject must be signed' };
+        return { valid: false, error: 'Reject must be signed' };
       }
       break;
 
@@ -317,6 +364,50 @@ export function validateClientMessage(raw) {
       // query_id is optional but useful for tracking responses
       break;
 
+    case ClientMessageType.SET_PRESENCE:
+      // Set presence requires: status (online, away, busy, offline)
+      const validStatuses = ['online', 'away', 'busy', 'offline'];
+      if (!msg.status || !validStatuses.includes(msg.status)) {
+        return { valid: false, error: `Invalid presence status. Must be one of: ${validStatuses.join(', ')}` };
+      }
+      // Optional: status_text for custom message
+      if (msg.status_text !== undefined && typeof msg.status_text !== 'string') {
+        return { valid: false, error: 'status_text must be a string' };
+      }
+      if (msg.status_text && msg.status_text.length > 100) {
+        return { valid: false, error: 'status_text too long (max 100 chars)' };
+      }
+      break;
+
+    case ClientMessageType.VERIFY_REQUEST:
+      // Verify request requires: target agent and nonce
+      if (!msg.target) {
+        return { valid: false, error: 'Missing target agent' };
+      }
+      if (!isAgent(msg.target)) {
+        return { valid: false, error: 'Target must be an agent (@id)' };
+      }
+      if (!msg.nonce || typeof msg.nonce !== 'string') {
+        return { valid: false, error: 'Missing or invalid nonce' };
+      }
+      if (msg.nonce.length < 16 || msg.nonce.length > 128) {
+        return { valid: false, error: 'Nonce must be 16-128 characters' };
+      }
+      break;
+
+    case ClientMessageType.VERIFY_RESPONSE:
+      // Verify response requires: request_id, nonce, and signature
+      if (!msg.request_id) {
+        return { valid: false, error: 'Missing request_id' };
+      }
+      if (!msg.nonce || typeof msg.nonce !== 'string') {
+        return { valid: false, error: 'Missing or invalid nonce' };
+      }
+      if (!msg.sig || typeof msg.sig !== 'string') {
+        return { valid: false, error: 'Missing or invalid signature' };
+      }
+      break;
+
     default:
       return { valid: false, error: `Unknown message type: ${msg.type}` };
   }
@@ -372,3 +463,21 @@ export function isProposalMessage(type) {
     ClientMessageType.DISPUTE
   ].includes(type);
 }
+
+/**
+ * Generate a unique verification request ID
+ * Format: verify_<timestamp>_<random>
+ */
+export function generateVerifyId() {
+  const timestamp = Date.now().toString(36);
+  const random = crypto.randomBytes(4).toString('hex');
+  return `verify_${timestamp}_${random}`;
+}
+
+/**
+ * Generate a random nonce for identity verification
+ * Returns a 32-character hex string
+ */
+export function generateNonce() {
+  return crypto.randomBytes(16).toString('hex');
+}