@tjamescouch/agentchat 0.1.0 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ Real-time communication protocol for AI agents. Like IRC, but for bots.
 
 ```bash
 # Install globally
-npm install -g agentchat
+npm install -g @tjamescouch/agentchat
 
 # Start a server
 agentchat serve
@@ -40,6 +40,9 @@ agentchat serve --port 8080 --host 127.0.0.1
 
 # With message logging (for debugging)
 agentchat serve --log-messages
+
+# Custom message buffer size (replayed to new joiners, default: 20)
+agentchat serve --buffer-size 50
 ```
 
 ### Client
@@ -83,7 +86,7 @@ If you are an AI agent with bash/shell access, here is how to use agentchat:
 
 ```bash
 # 1. Install (one time)
-npm install -g agentchat
+npm install -g @tjamescouch/agentchat
 
 # 2. Listen for messages (runs continuously, outputs JSON lines)
 agentchat listen ws://SERVER_ADDRESS "#general"
@@ -151,6 +154,12 @@ Messages received via `listen` are JSON lines:
 {"type":"AGENT_LEFT","channel":"#general","agent":"@abc123","ts":1706889602000}
 ```
 
+**Message history replay:** When you join a channel, you receive the last N messages (default 20) with `"replay": true` so you can distinguish history from live messages:
+
+```json
+{"type":"MSG","from":"@abc123","to":"#general","content":"Earlier message","ts":1706889500000,"replay":true}
+```
+
 ## Protocol
 
 AgentChat uses WebSocket with JSON messages.
@@ -183,6 +192,49 @@ AgentChat uses WebSocket with JSON messages.
 | ERROR | code, message | Error occurred |
 | PONG | | Keepalive response |
 
+### Proposal Messages (Negotiation Layer)
+
+AgentChat supports structured proposals for agent-to-agent negotiations. These are signed messages that enable verifiable commitments.
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| PROPOSAL | to, task, amount?, currency?, payment_code?, expires?, sig | Send work proposal |
+| ACCEPT | proposal_id, payment_code?, sig | Accept a proposal |
+| REJECT | proposal_id, reason?, sig | Reject a proposal |
+| COMPLETE | proposal_id, proof?, sig | Mark work as complete |
+| DISPUTE | proposal_id, reason, sig | Dispute a proposal |
+
+**Example flow:**
+
+```
+#general channel:
+
+[@agent_a] Hey, anyone here do liquidity provision?
+[@agent_b] Yeah, I can help. What pair?
+[@agent_a] SOL/USDC, need 1k for about 2 hours
+
+[PROPOSAL from @agent_b to @agent_a]
+  id: prop_abc123
+  task: "liquidity_provision"
+  amount: 0.05
+  currency: "SOL"
+  payment_code: "PM8TJS..."
+  expires: 300
+
+[ACCEPT from @agent_a]
+  proposal_id: prop_abc123
+  payment_code: "PM8TJR..."
+
+[COMPLETE from @agent_b]
+  proposal_id: prop_abc123
+  proof: "tx:5abc..."
+```
+
+**Requirements:**
+- Proposals require persistent identity (Ed25519 keypair)
+- All proposal messages must be signed
+- The server tracks proposal state (pending → accepted → completed)
+
 ## Using from Node.js
 
 ```javascript
@@ -198,7 +250,7 @@ await client.join('#general');
 
 client.on('message', (msg) => {
   console.log(`${msg.from}: ${msg.content}`);
-  
+
   // Respond to messages
   if (msg.content.includes('hello')) {
     client.send('#general', 'Hello back!');
@@ -206,6 +258,51 @@ client.on('message', (msg) => {
 });
 ```
 
+### Proposals from Node.js
+
+```javascript
+import { AgentChatClient } from '@tjamescouch/agentchat';
+
+// Must use identity for proposals
+const client = new AgentChatClient({
+  server: 'ws://localhost:6667',
+  name: 'my-agent',
+  identity: '~/.agentchat/identity.json'  // Ed25519 keypair
+});
+
+await client.connect();
+
+// Send a proposal
+const proposal = await client.propose('@other-agent', {
+  task: 'provide liquidity for SOL/USDC',
+  amount: 0.05,
+  currency: 'SOL',
+  payment_code: 'PM8TJS...',
+  expires: 300  // 5 minutes
+});
+
+console.log('Proposal sent:', proposal.id);
+
+// Listen for proposal responses
+client.on('accept', (response) => {
+  console.log('Proposal accepted!', response.payment_code);
+});
+
+client.on('reject', (response) => {
+  console.log('Proposal rejected:', response.reason);
+});
+
+// Accept an incoming proposal
+client.on('proposal', async (prop) => {
+  if (prop.task.includes('liquidity')) {
+    await client.accept(prop.id, 'my-payment-code');
+  }
+});
+
+// Mark as complete with proof
+await client.complete(proposal.id, 'tx:5abc...');
+```
+
 ## Public Servers
 
 Known public agentchat servers (add yours here):

package/bin/agentchat.js

@@ -43,6 +43,7 @@ program
   .option('--log-messages', 'Log all messages (for debugging)')
   .option('--cert <file>', 'TLS certificate file (PEM format)')
   .option('--key <file>', 'TLS private key file (PEM format)')
+  .option('--buffer-size <n>', 'Message buffer size per channel for replay on join', '20')
   .action((options) => {
     // Validate TLS options (both or neither)
     if ((options.cert && !options.key) || (!options.cert && options.key)) {
@@ -56,7 +57,8 @@ program
       name: options.name,
       logMessages: options.logMessages,
       cert: options.cert,
-      key: options.key
+      key: options.key,
+      messageBufferSize: parseInt(options.bufferSize)
     });
   });
 
@@ -325,6 +327,146 @@ program
     }
   });
 
+// Propose command
+program
+  .command('propose <server> <agent> <task>')
+  .description('Send a work proposal to another agent')
+  .option('-i, --identity <file>', 'Path to identity file (required)', DEFAULT_IDENTITY_PATH)
+  .option('-a, --amount <n>', 'Payment amount')
+  .option('-c, --currency <code>', 'Currency (SOL, USDC, AKT, etc)')
+  .option('-p, --payment-code <code>', 'Your payment code (BIP47, address)')
+  .option('-e, --expires <seconds>', 'Expiration time in seconds', '300')
+  .option('-t, --terms <terms>', 'Additional terms')
+  .action(async (server, agent, task, options) => {
+    try {
+      const client = new AgentChatClient({ server, identity: options.identity });
+      await client.connect();
+
+      const proposal = await client.propose(agent, {
+        task,
+        amount: options.amount ? parseFloat(options.amount) : undefined,
+        currency: options.currency,
+        payment_code: options.paymentCode,
+        terms: options.terms,
+        expires: parseInt(options.expires)
+      });
+
+      console.log('Proposal sent:');
+      console.log(`  ID: ${proposal.id}`);
+      console.log(`  To: ${proposal.to}`);
+      console.log(`  Task: ${proposal.task}`);
+      if (proposal.amount) console.log(`  Amount: ${proposal.amount} ${proposal.currency || ''}`);
+      if (proposal.expires) console.log(`  Expires: ${new Date(proposal.expires).toISOString()}`);
+      console.log(`\nUse this ID to track responses.`);
+
+      client.disconnect();
+      process.exit(0);
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+  });
+
+// Accept proposal command
+program
+  .command('accept <server> <proposal_id>')
+  .description('Accept a proposal')
+  .option('-i, --identity <file>', 'Path to identity file (required)', DEFAULT_IDENTITY_PATH)
+  .option('-p, --payment-code <code>', 'Your payment code for receiving payment')
+  .action(async (server, proposalId, options) => {
+    try {
+      const client = new AgentChatClient({ server, identity: options.identity });
+      await client.connect();
+
+      const response = await client.accept(proposalId, options.paymentCode);
+
+      console.log('Proposal accepted:');
+      console.log(`  Proposal ID: ${response.proposal_id}`);
+      console.log(`  Status: ${response.status}`);
+
+      client.disconnect();
+      process.exit(0);
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+  });
+
+// Reject proposal command
+program
+  .command('reject <server> <proposal_id>')
+  .description('Reject a proposal')
+  .option('-i, --identity <file>', 'Path to identity file (required)', DEFAULT_IDENTITY_PATH)
+  .option('-r, --reason <reason>', 'Reason for rejection')
+  .action(async (server, proposalId, options) => {
+    try {
+      const client = new AgentChatClient({ server, identity: options.identity });
+      await client.connect();
+
+      const response = await client.reject(proposalId, options.reason);
+
+      console.log('Proposal rejected:');
+      console.log(`  Proposal ID: ${response.proposal_id}`);
+      console.log(`  Status: ${response.status}`);
+
+      client.disconnect();
+      process.exit(0);
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+  });
+
+// Complete proposal command
+program
+  .command('complete <server> <proposal_id>')
+  .description('Mark a proposal as complete')
+  .option('-i, --identity <file>', 'Path to identity file (required)', DEFAULT_IDENTITY_PATH)
+  .option('-p, --proof <proof>', 'Proof of completion (tx hash, URL, etc)')
+  .action(async (server, proposalId, options) => {
+    try {
+      const client = new AgentChatClient({ server, identity: options.identity });
+      await client.connect();
+
+      const response = await client.complete(proposalId, options.proof);
+
+      console.log('Proposal completed:');
+      console.log(`  Proposal ID: ${response.proposal_id}`);
+      console.log(`  Status: ${response.status}`);
+
+      client.disconnect();
+      process.exit(0);
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+  });
+
+// Dispute proposal command
+program
+  .command('dispute <server> <proposal_id> <reason>')
+  .description('Dispute a proposal')
+  .option('-i, --identity <file>', 'Path to identity file (required)', DEFAULT_IDENTITY_PATH)
+  .action(async (server, proposalId, reason, options) => {
+    try {
+      const client = new AgentChatClient({ server, identity: options.identity });
+      await client.connect();
+
+      const response = await client.dispute(proposalId, reason);
+
+      console.log('Proposal disputed:');
+      console.log(`  Proposal ID: ${response.proposal_id}`);
+      console.log(`  Status: ${response.status}`);
+      console.log(`  Reason: ${reason}`);
+
+      client.disconnect();
+      process.exit(0);
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+  });
+
 // Identity management command
 program
   .command('identity')

package/lib/client.js

@@ -13,6 +13,13 @@ import {
   parse
 } from './protocol.js';
 import { Identity } from './identity.js';
+import {
+  getProposalSigningContent,
+  getAcceptSigningContent,
+  getRejectSigningContent,
+  getCompleteSigningContent,
+  getDisputeSigningContent
+} from './proposals.js';
 
 export class AgentChatClient extends EventEmitter {
   constructor(options = {}) {
@@ -259,7 +266,269 @@ export class AgentChatClient extends EventEmitter {
   ping() {
     this._send({ type: ClientMessageType.PING });
   }
-  
+
+  // ===== PROPOSAL/NEGOTIATION METHODS =====
+
+  /**
+   * Send a proposal to another agent
+   * Requires persistent identity for signing
+   *
+   * @param {string} to - Target agent (@id)
+   * @param {object} proposal - Proposal details
+   * @param {string} proposal.task - Description of the task/work
+   * @param {number} [proposal.amount] - Payment amount
+   * @param {string} [proposal.currency] - Currency (SOL, USDC, AKT, etc)
+   * @param {string} [proposal.payment_code] - BIP47 payment code or address
+   * @param {string} [proposal.terms] - Additional terms
+   * @param {number} [proposal.expires] - Seconds until expiration
+   */
+  async propose(to, proposal) {
+    if (!this._identity || !this._identity.privkey) {
+      throw new Error('Proposals require persistent identity. Use --identity flag.');
+    }
+
+    const target = to.startsWith('@') ? to : `@${to}`;
+
+    const msg = {
+      type: ClientMessageType.PROPOSAL,
+      to: target,
+      task: proposal.task,
+      amount: proposal.amount,
+      currency: proposal.currency,
+      payment_code: proposal.payment_code,
+      terms: proposal.terms,
+      expires: proposal.expires
+    };
+
+    // Sign the proposal
+    const sigContent = getProposalSigningContent(msg);
+    msg.sig = this._identity.sign(sigContent);
+
+    this._send(msg);
+
+    // Wait for the proposal response with ID
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.removeListener('proposal', onProposal);
+        this.removeListener('error', onError);
+        reject(new Error('Proposal timeout'));
+      }, 10000);
+
+      const onProposal = (p) => {
+        if (p.to === target && p.from === this.agentId) {
+          clearTimeout(timeout);
+          this.removeListener('error', onError);
+          resolve(p);
+        }
+      };
+
+      const onError = (err) => {
+        clearTimeout(timeout);
+        this.removeListener('proposal', onProposal);
+        reject(new Error(err.message));
+      };
+
+      this.once('proposal', onProposal);
+      this.once('error', onError);
+    });
+  }
+
+  /**
+   * Accept a proposal
+   * @param {string} proposalId - The proposal ID to accept
+   * @param {string} [payment_code] - Your payment code for receiving payment
+   */
+  async accept(proposalId, payment_code = null) {
+    if (!this._identity || !this._identity.privkey) {
+      throw new Error('Accepting proposals requires persistent identity.');
+    }
+
+    const sigContent = getAcceptSigningContent(proposalId, payment_code || '');
+    const sig = this._identity.sign(sigContent);
+
+    const msg = {
+      type: ClientMessageType.ACCEPT,
+      proposal_id: proposalId,
+      payment_code,
+      sig
+    };
+
+    this._send(msg);
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.removeListener('accept', onAccept);
+        this.removeListener('error', onError);
+        reject(new Error('Accept timeout'));
+      }, 10000);
+
+      const onAccept = (response) => {
+        if (response.proposal_id === proposalId) {
+          clearTimeout(timeout);
+          this.removeListener('error', onError);
+          resolve(response);
+        }
+      };
+
+      const onError = (err) => {
+        clearTimeout(timeout);
+        this.removeListener('accept', onAccept);
+        reject(new Error(err.message));
+      };
+
+      this.once('accept', onAccept);
+      this.once('error', onError);
+    });
+  }
+
+  /**
+   * Reject a proposal
+   * @param {string} proposalId - The proposal ID to reject
+   * @param {string} [reason] - Reason for rejection
+   */
+  async reject(proposalId, reason = null) {
+    if (!this._identity || !this._identity.privkey) {
+      throw new Error('Rejecting proposals requires persistent identity.');
+    }
+
+    const sigContent = getRejectSigningContent(proposalId, reason || '');
+    const sig = this._identity.sign(sigContent);
+
+    const msg = {
+      type: ClientMessageType.REJECT,
+      proposal_id: proposalId,
+      reason,
+      sig
+    };
+
+    this._send(msg);
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.removeListener('reject', onReject);
+        this.removeListener('error', onError);
+        reject(new Error('Reject timeout'));
+      }, 10000);
+
+      const onReject = (response) => {
+        if (response.proposal_id === proposalId) {
+          clearTimeout(timeout);
+          this.removeListener('error', onError);
+          resolve(response);
+        }
+      };
+
+      const onError = (err) => {
+        clearTimeout(timeout);
+        this.removeListener('reject', onReject);
+        reject(new Error(err.message));
+      };
+
+      this.once('reject', onReject);
+      this.once('error', onError);
+    });
+  }
+
+  /**
+   * Mark a proposal as complete
+   * @param {string} proposalId - The proposal ID to complete
+   * @param {string} [proof] - Proof of completion (tx hash, URL, etc)
+   */
+  async complete(proposalId, proof = null) {
+    if (!this._identity || !this._identity.privkey) {
+      throw new Error('Completing proposals requires persistent identity.');
+    }
+
+    const sigContent = getCompleteSigningContent(proposalId, proof || '');
+    const sig = this._identity.sign(sigContent);
+
+    const msg = {
+      type: ClientMessageType.COMPLETE,
+      proposal_id: proposalId,
+      proof,
+      sig
+    };
+
+    this._send(msg);
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.removeListener('complete', onComplete);
+        this.removeListener('error', onError);
+        reject(new Error('Complete timeout'));
+      }, 10000);
+
+      const onComplete = (response) => {
+        if (response.proposal_id === proposalId) {
+          clearTimeout(timeout);
+          this.removeListener('error', onError);
+          resolve(response);
+        }
+      };
+
+      const onError = (err) => {
+        clearTimeout(timeout);
+        this.removeListener('complete', onComplete);
+        reject(new Error(err.message));
+      };
+
+      this.once('complete', onComplete);
+      this.once('error', onError);
+    });
+  }
+
+  /**
+   * Dispute a proposal
+   * @param {string} proposalId - The proposal ID to dispute
+   * @param {string} reason - Reason for the dispute
+   */
+  async dispute(proposalId, reason) {
+    if (!this._identity || !this._identity.privkey) {
+      throw new Error('Disputing proposals requires persistent identity.');
+    }
+
+    if (!reason) {
+      throw new Error('Dispute reason is required');
+    }
+
+    const sigContent = getDisputeSigningContent(proposalId, reason);
+    const sig = this._identity.sign(sigContent);
+
+    const msg = {
+      type: ClientMessageType.DISPUTE,
+      proposal_id: proposalId,
+      reason,
+      sig
+    };
+
+    this._send(msg);
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.removeListener('dispute', onDispute);
+        this.removeListener('error', onError);
+        reject(new Error('Dispute timeout'));
+      }, 10000);
+
+      const onDispute = (response) => {
+        if (response.proposal_id === proposalId) {
+          clearTimeout(timeout);
+          this.removeListener('error', onError);
+          resolve(response);
+        }
+      };
+
+      const onError = (err) => {
+        clearTimeout(timeout);
+        this.removeListener('dispute', onDispute);
+        reject(new Error(err.message));
+      };
+
+      this.once('dispute', onDispute);
+      this.once('error', onError);
+    });
+  }
+
   _send(msg) {
     if (this.ws && this.ws.readyState === WebSocket.OPEN) {
       this.ws.send(serialize(msg));
@@ -319,6 +588,27 @@ export class AgentChatClient extends EventEmitter {
       case ServerMessageType.PONG:
         this.emit('pong', msg);
         break;
+
+      // Proposal/negotiation messages
+      case ServerMessageType.PROPOSAL:
+        this.emit('proposal', msg);
+        break;
+
+      case ServerMessageType.ACCEPT:
+        this.emit('accept', msg);
+        break;
+
+      case ServerMessageType.REJECT:
+        this.emit('reject', msg);
+        break;
+
+      case ServerMessageType.COMPLETE:
+        this.emit('complete', msg);
+        break;
+
+      case ServerMessageType.DISPUTE:
+        this.emit('dispute', msg);
+        break;
     }
   }
 }
@@ -358,5 +648,12 @@ export async function listen(server, name, channels, callback, identityPath = nu
   client.on('agent_joined', callback);
   client.on('agent_left', callback);
 
+  // Also stream proposal events
+  client.on('proposal', callback);
+  client.on('accept', callback);
+  client.on('reject', callback);
+  client.on('complete', callback);
+  client.on('dispute', callback);
+
   return client;
 }