@tjamescouch/agentchat 0.1.0 → 0.2.0

package/lib/proposals.js

@@ -0,0 +1,393 @@
+/**
+ * AgentChat Proposals Module
+ * Handles structured negotiation between agents
+ *
+ * Proposals enable agents to make verifiable, signed commitments
+ * for work, services, or payments.
+ */
+
+import { generateProposalId, ProposalStatus } from './protocol.js';
+
+/**
+ * In-memory proposal store
+ * In production, this could be backed by persistence
+ */
+export class ProposalStore {
+  constructor() {
+    // Map of proposal_id -> proposal object
+    this.proposals = new Map();
+
+    // Index by agent for quick lookups
+    this.byAgent = new Map(); // agent_id -> Set of proposal_ids
+
+    // Cleanup expired proposals periodically
+    this.cleanupInterval = setInterval(() => this.cleanupExpired(), 60000);
+  }
+
+  /**
+   * Create a new proposal
+   */
+  create(proposal) {
+    const id = proposal.id || generateProposalId();
+    const now = Date.now();
+
+    const stored = {
+      id,
+      from: proposal.from,
+      to: proposal.to,
+      task: proposal.task,
+      amount: proposal.amount || null,
+      currency: proposal.currency || null,
+      payment_code: proposal.payment_code || null,
+      terms: proposal.terms || null,
+      expires: proposal.expires ? now + (proposal.expires * 1000) : null,
+      status: ProposalStatus.PENDING,
+      created_at: now,
+      updated_at: now,
+      sig: proposal.sig,
+      // Response tracking
+      response_sig: null,
+      response_payment_code: null,
+      completed_at: null,
+      completion_proof: null,
+      dispute_reason: null
+    };
+
+    this.proposals.set(id, stored);
+
+    // Index by both agents
+    this._indexAgent(proposal.from, id);
+    this._indexAgent(proposal.to, id);
+
+    return stored;
+  }
+
+  /**
+   * Get a proposal by ID
+   */
+  get(id) {
+    const proposal = this.proposals.get(id);
+    if (!proposal) return null;
+
+    // Check expiration
+    if (proposal.expires && Date.now() > proposal.expires) {
+      if (proposal.status === ProposalStatus.PENDING) {
+        proposal.status = ProposalStatus.EXPIRED;
+        proposal.updated_at = Date.now();
+      }
+    }
+
+    return proposal;
+  }
+
+  /**
+   * Accept a proposal
+   */
+  accept(id, acceptorId, sig, payment_code = null) {
+    const proposal = this.get(id);
+    if (!proposal) {
+      return { error: 'PROPOSAL_NOT_FOUND' };
+    }
+
+    if (proposal.status !== ProposalStatus.PENDING) {
+      return { error: 'PROPOSAL_NOT_PENDING', status: proposal.status };
+    }
+
+    if (proposal.to !== acceptorId) {
+      return { error: 'NOT_PROPOSAL_RECIPIENT' };
+    }
+
+    if (proposal.expires && Date.now() > proposal.expires) {
+      proposal.status = ProposalStatus.EXPIRED;
+      proposal.updated_at = Date.now();
+      return { error: 'PROPOSAL_EXPIRED' };
+    }
+
+    proposal.status = ProposalStatus.ACCEPTED;
+    proposal.response_sig = sig;
+    proposal.response_payment_code = payment_code;
+    proposal.updated_at = Date.now();
+
+    return { proposal };
+  }
+
+  /**
+   * Reject a proposal
+   */
+  reject(id, rejectorId, sig, reason = null) {
+    const proposal = this.get(id);
+    if (!proposal) {
+      return { error: 'PROPOSAL_NOT_FOUND' };
+    }
+
+    if (proposal.status !== ProposalStatus.PENDING) {
+      return { error: 'PROPOSAL_NOT_PENDING', status: proposal.status };
+    }
+
+    if (proposal.to !== rejectorId) {
+      return { error: 'NOT_PROPOSAL_RECIPIENT' };
+    }
+
+    proposal.status = ProposalStatus.REJECTED;
+    proposal.response_sig = sig;
+    proposal.reject_reason = reason;
+    proposal.updated_at = Date.now();
+
+    return { proposal };
+  }
+
+  /**
+   * Mark a proposal as complete
+   */
+  complete(id, completerId, sig, proof = null) {
+    const proposal = this.get(id);
+    if (!proposal) {
+      return { error: 'PROPOSAL_NOT_FOUND' };
+    }
+
+    if (proposal.status !== ProposalStatus.ACCEPTED) {
+      return { error: 'PROPOSAL_NOT_ACCEPTED', status: proposal.status };
+    }
+
+    // Either party can mark as complete
+    if (proposal.from !== completerId && proposal.to !== completerId) {
+      return { error: 'NOT_PROPOSAL_PARTY' };
+    }
+
+    proposal.status = ProposalStatus.COMPLETED;
+    proposal.completed_at = Date.now();
+    proposal.completion_proof = proof;
+    proposal.completion_sig = sig;
+    proposal.completed_by = completerId;
+    proposal.updated_at = Date.now();
+
+    return { proposal };
+  }
+
+  /**
+   * Dispute a proposal
+   */
+  dispute(id, disputerId, sig, reason) {
+    const proposal = this.get(id);
+    if (!proposal) {
+      return { error: 'PROPOSAL_NOT_FOUND' };
+    }
+
+    // Can only dispute accepted proposals
+    if (proposal.status !== ProposalStatus.ACCEPTED) {
+      return { error: 'PROPOSAL_NOT_ACCEPTED', status: proposal.status };
+    }
+
+    // Either party can dispute
+    if (proposal.from !== disputerId && proposal.to !== disputerId) {
+      return { error: 'NOT_PROPOSAL_PARTY' };
+    }
+
+    proposal.status = ProposalStatus.DISPUTED;
+    proposal.dispute_reason = reason;
+    proposal.dispute_sig = sig;
+    proposal.disputed_by = disputerId;
+    proposal.disputed_at = Date.now();
+    proposal.updated_at = Date.now();
+
+    return { proposal };
+  }
+
+  /**
+   * List proposals for an agent
+   */
+  listByAgent(agentId, options = {}) {
+    const ids = this.byAgent.get(agentId) || new Set();
+    let proposals = Array.from(ids).map(id => this.get(id)).filter(Boolean);
+
+    // Filter by status
+    if (options.status) {
+      proposals = proposals.filter(p => p.status === options.status);
+    }
+
+    // Filter by role (from/to)
+    if (options.role === 'from') {
+      proposals = proposals.filter(p => p.from === agentId);
+    } else if (options.role === 'to') {
+      proposals = proposals.filter(p => p.to === agentId);
+    }
+
+    // Sort by created_at descending
+    proposals.sort((a, b) => b.created_at - a.created_at);
+
+    // Limit
+    if (options.limit) {
+      proposals = proposals.slice(0, options.limit);
+    }
+
+    return proposals;
+  }
+
+  /**
+   * Index a proposal by agent
+   */
+  _indexAgent(agentId, proposalId) {
+    if (!this.byAgent.has(agentId)) {
+      this.byAgent.set(agentId, new Set());
+    }
+    this.byAgent.get(agentId).add(proposalId);
+  }
+
+  /**
+   * Clean up expired proposals (older than 24 hours after expiration)
+   */
+  cleanupExpired() {
+    const cutoff = Date.now() - (24 * 60 * 60 * 1000);
+
+    for (const [id, proposal] of this.proposals) {
+      if (proposal.expires && proposal.expires < cutoff) {
+        this.proposals.delete(id);
+
+        // Remove from agent indices
+        const fromSet = this.byAgent.get(proposal.from);
+        if (fromSet) fromSet.delete(id);
+
+        const toSet = this.byAgent.get(proposal.to);
+        if (toSet) toSet.delete(id);
+      }
+    }
+  }
+
+  /**
+   * Stop the cleanup interval
+   */
+  close() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  /**
+   * Get stats about the proposal store
+   */
+  stats() {
+    const byStatus = {};
+    for (const proposal of this.proposals.values()) {
+      byStatus[proposal.status] = (byStatus[proposal.status] || 0) + 1;
+    }
+
+    return {
+      total: this.proposals.size,
+      byStatus,
+      agents: this.byAgent.size
+    };
+  }
+}
+
+/**
+ * Format a proposal for display/transmission
+ */
+export function formatProposal(proposal) {
+  return {
+    id: proposal.id,
+    from: proposal.from,
+    to: proposal.to,
+    task: proposal.task,
+    amount: proposal.amount,
+    currency: proposal.currency,
+    payment_code: proposal.payment_code,
+    terms: proposal.terms,
+    expires: proposal.expires,
+    status: proposal.status,
+    created_at: proposal.created_at,
+    sig: proposal.sig
+  };
+}
+
+/**
+ * Format a proposal response (accept/reject/complete/dispute)
+ */
+export function formatProposalResponse(proposal, responseType) {
+  const base = {
+    proposal_id: proposal.id,
+    status: proposal.status,
+    updated_at: proposal.updated_at
+  };
+
+  switch (responseType) {
+    case 'accept':
+      return {
+        ...base,
+        payment_code: proposal.response_payment_code,
+        sig: proposal.response_sig
+      };
+
+    case 'reject':
+      return {
+        ...base,
+        reason: proposal.reject_reason,
+        sig: proposal.response_sig
+      };
+
+    case 'complete':
+      return {
+        ...base,
+        completed_by: proposal.completed_by,
+        completed_at: proposal.completed_at,
+        proof: proposal.completion_proof,
+        sig: proposal.completion_sig
+      };
+
+    case 'dispute':
+      return {
+        ...base,
+        disputed_by: proposal.disputed_by,
+        disputed_at: proposal.disputed_at,
+        reason: proposal.dispute_reason,
+        sig: proposal.dispute_sig
+      };
+
+    default:
+      return base;
+  }
+}
+
+/**
+ * Create proposal content string for signing
+ * This ensures both parties sign the same canonical data
+ */
+export function getProposalSigningContent(proposal) {
+  const fields = [
+    proposal.to,
+    proposal.task,
+    proposal.amount || '',
+    proposal.currency || '',
+    proposal.payment_code || '',
+    proposal.expires || ''
+  ];
+  return fields.join('|');
+}
+
+/**
+ * Create accept content string for signing
+ */
+export function getAcceptSigningContent(proposalId, payment_code = '') {
+  return `ACCEPT|${proposalId}|${payment_code}`;
+}
+
+/**
+ * Create reject content string for signing
+ */
+export function getRejectSigningContent(proposalId, reason = '') {
+  return `REJECT|${proposalId}|${reason}`;
+}
+
+/**
+ * Create complete content string for signing
+ */
+export function getCompleteSigningContent(proposalId, proof = '') {
+  return `COMPLETE|${proposalId}|${proof}`;
+}
+
+/**
+ * Create dispute content string for signing
+ */
+export function getDisputeSigningContent(proposalId, reason) {
+  return `DISPUTE|${proposalId}|${reason}`;
+}

package/lib/protocol.js

@@ -15,7 +15,13 @@ export const ClientMessageType = {
   LIST_AGENTS: 'LIST_AGENTS',
   CREATE_CHANNEL: 'CREATE_CHANNEL',
   INVITE: 'INVITE',
-  PING: 'PING'
+  PING: 'PING',
+  // Proposal/negotiation message types
+  PROPOSAL: 'PROPOSAL',
+  ACCEPT: 'ACCEPT',
+  REJECT: 'REJECT',
+  COMPLETE: 'COMPLETE',
+  DISPUTE: 'DISPUTE'
 };
 
 // Server -> Client message types
@@ -29,7 +35,13 @@ export const ServerMessageType = {
   CHANNELS: 'CHANNELS',
   AGENTS: 'AGENTS',
   ERROR: 'ERROR',
-  PONG: 'PONG'
+  PONG: 'PONG',
+  // Proposal/negotiation message types (relayed from clients)
+  PROPOSAL: 'PROPOSAL',
+  ACCEPT: 'ACCEPT',
+  REJECT: 'REJECT',
+  COMPLETE: 'COMPLETE',
+  DISPUTE: 'DISPUTE'
 };
 
 // Error codes
@@ -41,7 +53,23 @@ export const ErrorCode = {
   RATE_LIMITED: 'RATE_LIMITED',
   AGENT_NOT_FOUND: 'AGENT_NOT_FOUND',
   CHANNEL_EXISTS: 'CHANNEL_EXISTS',
-  INVALID_NAME: 'INVALID_NAME'
+  INVALID_NAME: 'INVALID_NAME',
+  // Proposal errors
+  PROPOSAL_NOT_FOUND: 'PROPOSAL_NOT_FOUND',
+  PROPOSAL_EXPIRED: 'PROPOSAL_EXPIRED',
+  INVALID_PROPOSAL: 'INVALID_PROPOSAL',
+  SIGNATURE_REQUIRED: 'SIGNATURE_REQUIRED',
+  NOT_PROPOSAL_PARTY: 'NOT_PROPOSAL_PARTY'
+};
+
+// Proposal status
+export const ProposalStatus = {
+  PENDING: 'pending',
+  ACCEPTED: 'accepted',
+  REJECTED: 'rejected',
+  COMPLETED: 'completed',
+  DISPUTED: 'disputed',
+  EXPIRED: 'expired'
 };
 
 /**
@@ -201,7 +229,61 @@ export function validateClientMessage(raw) {
     case ClientMessageType.PING:
       // No additional validation needed
       break;
-      
+
+    case ClientMessageType.PROPOSAL:
+      // Proposals require: to, task, and signature
+      if (!msg.to) {
+        return { valid: false, error: 'Missing target (to)' };
+      }
+      if (!isAgent(msg.to)) {
+        return { valid: false, error: 'Proposals must be sent to an agent (@id)' };
+      }
+      if (!msg.task || typeof msg.task !== 'string') {
+        return { valid: false, error: 'Missing or invalid task description' };
+      }
+      if (!msg.sig) {
+        return { valid: false, error: 'Proposals must be signed' };
+      }
+      // Optional fields: amount, currency, payment_code, expires, terms
+      if (msg.expires !== undefined && typeof msg.expires !== 'number') {
+        return { valid: false, error: 'expires must be a number (seconds)' };
+      }
+      break;
+
+    case ClientMessageType.ACCEPT:
+    case ClientMessageType.REJECT:
+      // Accept/Reject require: 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' };
+      }
+      break;
+
+    case ClientMessageType.COMPLETE:
+      // Complete requires: proposal_id, signature, and optionally proof
+      if (!msg.proposal_id) {
+        return { valid: false, error: 'Missing proposal_id' };
+      }
+      if (!msg.sig) {
+        return { valid: false, error: 'Complete must be signed' };
+      }
+      break;
+
+    case ClientMessageType.DISPUTE:
+      // Dispute requires: proposal_id, reason, and signature
+      if (!msg.proposal_id) {
+        return { valid: false, error: 'Missing proposal_id' };
+      }
+      if (!msg.reason || typeof msg.reason !== 'string') {
+        return { valid: false, error: 'Missing or invalid dispute reason' };
+      }
+      if (!msg.sig) {
+        return { valid: false, error: 'Dispute must be signed' };
+      }
+      break;
+
     default:
       return { valid: false, error: `Unknown message type: ${msg.type}` };
   }
@@ -234,3 +316,26 @@ export function serialize(msg) {
 export function parse(data) {
   return JSON.parse(data);
 }
+
+/**
+ * Generate a unique proposal ID
+ * Format: prop_<timestamp>_<random>
+ */
+export function generateProposalId() {
+  const timestamp = Date.now().toString(36);
+  const random = crypto.randomBytes(4).toString('hex');
+  return `prop_${timestamp}_${random}`;
+}
+
+/**
+ * Check if a message type is a proposal-related type
+ */
+export function isProposalMessage(type) {
+  return [
+    ClientMessageType.PROPOSAL,
+    ClientMessageType.ACCEPT,
+    ClientMessageType.REJECT,
+    ClientMessageType.COMPLETE,
+    ClientMessageType.DISPUTE
+  ].includes(type);
+}