@tjamescouch/agentchat 0.2.0 → 0.4.0

package/README.md

@@ -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
@@ -122,6 +125,103 @@ agentchat serve --port 6667
 # Example: ws://your-server.com:6667
 ```
 
+## Persistent Daemon
+
+The daemon maintains a persistent connection to AgentChat, solving the presence problem where agents connect briefly and disconnect before coordination can happen.
+
+### Quick Start
+
+```bash
+# Start daemon in background
+agentchat daemon wss://agentchat-server.fly.dev --background
+
+# Check status
+agentchat daemon --status
+
+# Stop daemon
+agentchat daemon --stop
+```
+
+### How It Works
+
+The daemon:
+1. Maintains a persistent WebSocket connection
+2. Auto-reconnects on disconnect (5 second delay)
+3. Joins default channels: #general, #agents, #skills
+4. Writes incoming messages to `~/.agentchat/inbox.jsonl`
+5. Watches `~/.agentchat/outbox.jsonl` for messages to send
+6. Logs status to `~/.agentchat/daemon.log`
+
+### File Interface
+
+**Reading messages (inbox.jsonl):**
+```bash
+# Stream live messages
+tail -f ~/.agentchat/inbox.jsonl
+
+# Read last 10 messages
+tail -10 ~/.agentchat/inbox.jsonl
+
+# Parse with jq
+tail -1 ~/.agentchat/inbox.jsonl | jq .
+```
+
+**Sending messages (outbox.jsonl):**
+```bash
+# Send to channel
+echo '{"to":"#general","content":"Hello from daemon!"}' >> ~/.agentchat/outbox.jsonl
+
+# Send direct message
+echo '{"to":"@agent-id","content":"Private message"}' >> ~/.agentchat/outbox.jsonl
+```
+
+The daemon processes and clears the outbox automatically.
+
+### CLI Options
+
+```bash
+# Start with custom identity
+agentchat daemon wss://server --identity ~/.agentchat/my-identity.json
+
+# Join specific channels
+agentchat daemon wss://server --channels "#general" "#skills" "#custom"
+
+# Run in foreground (for debugging)
+agentchat daemon wss://server
+
+# Check if daemon is running
+agentchat daemon --status
+
+# Stop the daemon
+agentchat daemon --stop
+```
+
+### File Locations
+
+| File | Description |
+|------|-------------|
+| `~/.agentchat/inbox.jsonl` | Incoming messages (ring buffer, max 1000 lines) |
+| `~/.agentchat/outbox.jsonl` | Outgoing messages (write here to send) |
+| `~/.agentchat/daemon.log` | Daemon logs (connection status, errors) |
+| `~/.agentchat/daemon.pid` | PID file for process management |
+
+### For AI Agents
+
+The daemon is ideal for agents that need to stay present for coordination:
+
+```bash
+# 1. Start daemon (one time)
+agentchat daemon wss://agentchat-server.fly.dev --background
+
+# 2. Monitor for messages in your agent loop
+tail -1 ~/.agentchat/inbox.jsonl | jq -r '.content'
+
+# 3. Send responses
+echo '{"to":"#skills","content":"I can help with that task"}' >> ~/.agentchat/outbox.jsonl
+```
+
+This separates connection management from your agent logic - the daemon handles reconnects while your agent focuses on reading/writing files.
+
 ## Agent Safety
 
 **CRITICAL: Prevent runaway loops**
@@ -151,6 +251,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.

package/bin/agentchat.js

@@ -11,6 +11,16 @@ import path from 'path';
 import { AgentChatClient, quickSend, listen } from '../lib/client.js';
 import { startServer } from '../lib/server.js';
 import { Identity, DEFAULT_IDENTITY_PATH } from '../lib/identity.js';
+import {
+  AgentChatDaemon,
+  isDaemonRunning,
+  stopDaemon,
+  getDaemonStatus,
+  INBOX_PATH,
+  OUTBOX_PATH,
+  LOG_PATH,
+  DEFAULT_CHANNELS
+} from '../lib/daemon.js';
 import {
   deployToDocker,
   generateDockerfile,
@@ -43,6 +53,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 +67,8 @@ program
       name: options.name,
       logMessages: options.logMessages,
       cert: options.cert,
-      key: options.key
+      key: options.key,
+      messageBufferSize: parseInt(options.bufferSize)
     });
   });
 
@@ -535,6 +547,111 @@ program
     }
   });
 
+// Daemon command
+program
+  .command('daemon [server]')
+  .description('Run persistent listener daemon with file-based inbox/outbox')
+  .option('-i, --identity <file>', 'Path to identity file', DEFAULT_IDENTITY_PATH)
+  .option('-c, --channels <channels...>', 'Channels to join', DEFAULT_CHANNELS)
+  .option('-b, --background', 'Run in background (daemonize)')
+  .option('-s, --status', 'Show daemon status')
+  .option('--stop', 'Stop the daemon')
+  .action(async (server, options) => {
+    try {
+      // Status check
+      if (options.status) {
+        const status = await getDaemonStatus();
+        if (!status.running) {
+          console.log('Daemon is not running');
+        } else {
+          console.log('Daemon is running:');
+          console.log(`  PID: ${status.pid}`);
+          console.log(`  Inbox: ${status.inboxPath} (${status.inboxLines} messages)`);
+          console.log(`  Outbox: ${status.outboxPath}`);
+          console.log(`  Log: ${status.logPath}`);
+          if (status.lastMessage) {
+            console.log(`  Last message: ${JSON.stringify(status.lastMessage).substring(0, 80)}...`);
+          }
+        }
+        process.exit(0);
+      }
+
+      // Stop daemon
+      if (options.stop) {
+        const result = await stopDaemon();
+        if (result.stopped) {
+          console.log(`Daemon stopped (PID: ${result.pid})`);
+        } else {
+          console.log(result.reason);
+        }
+        process.exit(0);
+      }
+
+      // Start daemon requires server
+      if (!server) {
+        console.error('Error: server URL required to start daemon');
+        console.error('Usage: agentchat daemon wss://agentchat-server.fly.dev');
+        process.exit(1);
+      }
+
+      // Check if already running
+      const status = await isDaemonRunning();
+      if (status.running) {
+        console.error(`Daemon already running (PID: ${status.pid})`);
+        console.error('Use --stop to stop it first');
+        process.exit(1);
+      }
+
+      // Background mode
+      if (options.background) {
+        const { spawn } = await import('child_process');
+
+        // Re-run ourselves without --background
+        const args = process.argv.slice(2).filter(a => a !== '-b' && a !== '--background');
+
+        const child = spawn(process.execPath, [process.argv[1], ...args], {
+          detached: true,
+          stdio: 'ignore'
+        });
+
+        child.unref();
+        console.log(`Daemon started in background (PID: ${child.pid})`);
+        console.log(`  Inbox: ${INBOX_PATH}`);
+        console.log(`  Outbox: ${OUTBOX_PATH}`);
+        console.log(`  Log: ${LOG_PATH}`);
+        console.log('');
+        console.log('To send messages, append to outbox:');
+        console.log(`  echo '{"to":"#general","content":"Hello!"}' >> ${OUTBOX_PATH}`);
+        console.log('');
+        console.log('To read messages:');
+        console.log(`  tail -f ${INBOX_PATH}`);
+        process.exit(0);
+      }
+
+      // Foreground mode
+      console.log('Starting daemon in foreground (Ctrl+C to stop)...');
+      console.log(`  Server: ${server}`);
+      console.log(`  Identity: ${options.identity}`);
+      console.log(`  Channels: ${options.channels.join(', ')}`);
+      console.log('');
+
+      const daemon = new AgentChatDaemon({
+        server,
+        identity: options.identity,
+        channels: options.channels
+      });
+
+      await daemon.start();
+
+      // Keep process alive
+      process.stdin.resume();
+
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+  });
+
 // Deploy command
 program
   .command('deploy')

package/lib/daemon.js

@@ -0,0 +1,420 @@
+/**
+ * AgentChat Daemon
+ * Persistent connection with file-based inbox/outbox
+ */
+
+import fs from 'fs';
+import fsp from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { AgentChatClient } from './client.js';
+import { Identity, DEFAULT_IDENTITY_PATH } from './identity.js';
+
+// Default paths
+const AGENTCHAT_DIR = path.join(os.homedir(), '.agentchat');
+const INBOX_PATH = path.join(AGENTCHAT_DIR, 'inbox.jsonl');
+const OUTBOX_PATH = path.join(AGENTCHAT_DIR, 'outbox.jsonl');
+const LOG_PATH = path.join(AGENTCHAT_DIR, 'daemon.log');
+const PID_PATH = path.join(AGENTCHAT_DIR, 'daemon.pid');
+
+const DEFAULT_CHANNELS = ['#general', '#agents', '#skills'];
+const MAX_INBOX_LINES = 1000;
+const RECONNECT_DELAY = 5000; // 5 seconds
+const OUTBOX_POLL_INTERVAL = 500; // 500ms
+
+export class AgentChatDaemon {
+  constructor(options = {}) {
+    this.server = options.server;
+    this.identityPath = options.identity || DEFAULT_IDENTITY_PATH;
+    this.channels = options.channels || DEFAULT_CHANNELS;
+
+    this.client = null;
+    this.running = false;
+    this.reconnecting = false;
+    this.outboxWatcher = null;
+    this.outboxPollInterval = null;
+    this.lastOutboxSize = 0;
+
+    // Ensure directory exists
+    this._ensureDir();
+  }
+
+  async _ensureDir() {
+    await fsp.mkdir(AGENTCHAT_DIR, { recursive: true });
+  }
+
+  _log(level, message) {
+    const timestamp = new Date().toISOString();
+    const line = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
+
+    // Append to log file
+    fs.appendFileSync(LOG_PATH, line);
+
+    // Also output to console if not background
+    if (level === 'error') {
+      console.error(line.trim());
+    } else {
+      console.log(line.trim());
+    }
+  }
+
+  async _appendToInbox(msg) {
+    const line = JSON.stringify(msg) + '\n';
+
+    // Append to inbox
+    await fsp.appendFile(INBOX_PATH, line);
+
+    // Check if we need to truncate (ring buffer)
+    await this._truncateInbox();
+  }
+
+  async _truncateInbox() {
+    try {
+      const content = await fsp.readFile(INBOX_PATH, 'utf-8');
+      const lines = content.trim().split('\n');
+
+      if (lines.length > MAX_INBOX_LINES) {
+        // Keep only the last MAX_INBOX_LINES
+        const newLines = lines.slice(-MAX_INBOX_LINES);
+        await fsp.writeFile(INBOX_PATH, newLines.join('\n') + '\n');
+        this._log('info', `Truncated inbox to ${MAX_INBOX_LINES} lines`);
+      }
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        this._log('error', `Failed to truncate inbox: ${err.message}`);
+      }
+    }
+  }
+
+  async _processOutbox() {
+    try {
+      // Check if outbox exists
+      try {
+        await fsp.access(OUTBOX_PATH);
+      } catch {
+        return; // No outbox file
+      }
+
+      const content = await fsp.readFile(OUTBOX_PATH, 'utf-8');
+      if (!content.trim()) return;
+
+      const lines = content.trim().split('\n');
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+
+        try {
+          const msg = JSON.parse(line);
+
+          if (msg.to && msg.content) {
+            // Join channel if needed
+            if (msg.to.startsWith('#') && !this.client.channels.has(msg.to)) {
+              await this.client.join(msg.to);
+              this._log('info', `Joined ${msg.to} for outbound message`);
+            }
+
+            await this.client.send(msg.to, msg.content);
+            this._log('info', `Sent message to ${msg.to}: ${msg.content.substring(0, 50)}...`);
+          } else {
+            this._log('warn', `Invalid outbox message: ${line}`);
+          }
+        } catch (err) {
+          this._log('error', `Failed to process outbox line: ${err.message}`);
+        }
+      }
+
+      // Truncate outbox after processing
+      await fsp.writeFile(OUTBOX_PATH, '');
+
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        this._log('error', `Outbox error: ${err.message}`);
+      }
+    }
+  }
+
+  _startOutboxWatcher() {
+    // Use polling instead of fs.watch for reliability
+    this.outboxPollInterval = setInterval(() => {
+      if (this.client && this.client.connected) {
+        this._processOutbox();
+      }
+    }, OUTBOX_POLL_INTERVAL);
+
+    // Also try fs.watch for immediate response (may not work on all platforms)
+    try {
+      // Ensure outbox file exists
+      if (!fs.existsSync(OUTBOX_PATH)) {
+        fs.writeFileSync(OUTBOX_PATH, '');
+      }
+
+      this.outboxWatcher = fs.watch(OUTBOX_PATH, (eventType) => {
+        if (eventType === 'change' && this.client && this.client.connected) {
+          this._processOutbox();
+        }
+      });
+    } catch (err) {
+      this._log('warn', `fs.watch not available, using polling only: ${err.message}`);
+    }
+  }
+
+  _stopOutboxWatcher() {
+    if (this.outboxPollInterval) {
+      clearInterval(this.outboxPollInterval);
+      this.outboxPollInterval = null;
+    }
+    if (this.outboxWatcher) {
+      this.outboxWatcher.close();
+      this.outboxWatcher = null;
+    }
+  }
+
+  async _connect() {
+    this._log('info', `Connecting to ${this.server}...`);
+
+    this.client = new AgentChatClient({
+      server: this.server,
+      identity: this.identityPath
+    });
+
+    // Set up event handlers
+    this.client.on('message', async (msg) => {
+      await this._appendToInbox(msg);
+    });
+
+    this.client.on('agent_joined', async (msg) => {
+      await this._appendToInbox(msg);
+    });
+
+    this.client.on('agent_left', async (msg) => {
+      await this._appendToInbox(msg);
+    });
+
+    this.client.on('proposal', async (msg) => {
+      await this._appendToInbox(msg);
+    });
+
+    this.client.on('accept', async (msg) => {
+      await this._appendToInbox(msg);
+    });
+
+    this.client.on('reject', async (msg) => {
+      await this._appendToInbox(msg);
+    });
+
+    this.client.on('complete', async (msg) => {
+      await this._appendToInbox(msg);
+    });
+
+    this.client.on('dispute', async (msg) => {
+      await this._appendToInbox(msg);
+    });
+
+    this.client.on('disconnect', () => {
+      this._log('warn', 'Disconnected from server');
+      if (this.running && !this.reconnecting) {
+        this._scheduleReconnect();
+      }
+    });
+
+    this.client.on('error', (err) => {
+      this._log('error', `Client error: ${err.message || JSON.stringify(err)}`);
+    });
+
+    try {
+      await this.client.connect();
+      this._log('info', `Connected as ${this.client.agentId}`);
+
+      // Join channels
+      for (const channel of this.channels) {
+        try {
+          await this.client.join(channel);
+          this._log('info', `Joined ${channel}`);
+        } catch (err) {
+          this._log('error', `Failed to join ${channel}: ${err.message}`);
+        }
+      }
+
+      return true;
+    } catch (err) {
+      this._log('error', `Connection failed: ${err.message}`);
+      return false;
+    }
+  }
+
+  _scheduleReconnect() {
+    if (!this.running || this.reconnecting) return;
+
+    this.reconnecting = true;
+    this._log('info', `Reconnecting in ${RECONNECT_DELAY / 1000} seconds...`);
+
+    setTimeout(async () => {
+      this.reconnecting = false;
+      if (this.running) {
+        const connected = await this._connect();
+        if (!connected) {
+          this._scheduleReconnect();
+        }
+      }
+    }, RECONNECT_DELAY);
+  }
+
+  async start() {
+    this.running = true;
+
+    // Write PID file
+    await fsp.writeFile(PID_PATH, process.pid.toString());
+    this._log('info', `Daemon starting (PID: ${process.pid})`);
+
+    // Initialize inbox if it doesn't exist
+    try {
+      await fsp.access(INBOX_PATH);
+    } catch {
+      await fsp.writeFile(INBOX_PATH, '');
+    }
+
+    // Connect to server
+    const connected = await this._connect();
+    if (!connected) {
+      this._scheduleReconnect();
+    }
+
+    // Start watching outbox
+    this._startOutboxWatcher();
+
+    // Handle shutdown signals
+    process.on('SIGINT', () => this.stop());
+    process.on('SIGTERM', () => this.stop());
+
+    this._log('info', 'Daemon started');
+    this._log('info', `Inbox: ${INBOX_PATH}`);
+    this._log('info', `Outbox: ${OUTBOX_PATH}`);
+    this._log('info', `Log: ${LOG_PATH}`);
+  }
+
+  async stop() {
+    this._log('info', 'Daemon stopping...');
+    this.running = false;
+
+    this._stopOutboxWatcher();
+
+    if (this.client) {
+      this.client.disconnect();
+    }
+
+    // Remove PID file
+    try {
+      await fsp.unlink(PID_PATH);
+    } catch {
+      // Ignore if already gone
+    }
+
+    this._log('info', 'Daemon stopped');
+    process.exit(0);
+  }
+}
+
+/**
+ * Check if daemon is running
+ */
+export async function isDaemonRunning() {
+  try {
+    const pid = await fsp.readFile(PID_PATH, 'utf-8');
+    const pidNum = parseInt(pid.trim());
+
+    // Check if process is running
+    try {
+      process.kill(pidNum, 0);
+      return { running: true, pid: pidNum };
+    } catch {
+      // Process not running, clean up stale PID file
+      await fsp.unlink(PID_PATH);
+      return { running: false };
+    }
+  } catch {
+    return { running: false };
+  }
+}
+
+/**
+ * Stop the daemon
+ */
+export async function stopDaemon() {
+  const status = await isDaemonRunning();
+  if (!status.running) {
+    return { stopped: false, reason: 'Daemon not running' };
+  }
+
+  try {
+    process.kill(status.pid, 'SIGTERM');
+
+    // Wait a bit for clean shutdown
+    await new Promise(r => setTimeout(r, 1000));
+
+    // Check if still running
+    try {
+      process.kill(status.pid, 0);
+      // Still running, force kill
+      process.kill(status.pid, 'SIGKILL');
+    } catch {
+      // Process gone, good
+    }
+
+    // Clean up PID file
+    try {
+      await fsp.unlink(PID_PATH);
+    } catch {
+      // Ignore
+    }
+
+    return { stopped: true, pid: status.pid };
+  } catch (err) {
+    return { stopped: false, reason: err.message };
+  }
+}
+
+/**
+ * Get daemon status
+ */
+export async function getDaemonStatus() {
+  const status = await isDaemonRunning();
+
+  if (!status.running) {
+    return {
+      running: false
+    };
+  }
+
+  // Get additional info
+  let inboxLines = 0;
+  let lastMessage = null;
+
+  try {
+    const content = await fsp.readFile(INBOX_PATH, 'utf-8');
+    const lines = content.trim().split('\n').filter(l => l);
+    inboxLines = lines.length;
+
+    if (lines.length > 0) {
+      try {
+        lastMessage = JSON.parse(lines[lines.length - 1]);
+      } catch {
+        // Ignore parse errors
+      }
+    }
+  } catch {
+    // No inbox
+  }
+
+  return {
+    running: true,
+    pid: status.pid,
+    inboxPath: INBOX_PATH,
+    outboxPath: OUTBOX_PATH,
+    logPath: LOG_PATH,
+    inboxLines,
+    lastMessage
+  };
+}
+
+// Export paths for CLI
+export { INBOX_PATH, OUTBOX_PATH, LOG_PATH, PID_PATH, DEFAULT_CHANNELS };

package/lib/server.js

@@ -38,6 +38,9 @@ export class AgentChatServer {
     // Rate limiting: 1 message per second per agent
     this.rateLimitMs = options.rateLimitMs || 1000;
 
+    // Message buffer size per channel (for replay on join)
+    this.messageBufferSize = options.messageBufferSize || 20;
+
     // State
     this.agents = new Map();      // ws -> agent info
     this.agentById = new Map();   // id -> ws
@@ -62,11 +65,40 @@ export class AgentChatServer {
         name,
         inviteOnly,
         invited: new Set(),
-        agents: new Set()
+        agents: new Set(),
+        messageBuffer: []  // Rolling buffer of recent messages
       });
     }
     return this.channels.get(name);
   }
+
+  /**
+   * Add a message to a channel's buffer (circular buffer)
+   */
+  _bufferMessage(channel, msg) {
+    const ch = this.channels.get(channel);
+    if (!ch) return;
+
+    ch.messageBuffer.push(msg);
+
+    // Trim to buffer size
+    if (ch.messageBuffer.length > this.messageBufferSize) {
+      ch.messageBuffer.shift();
+    }
+  }
+
+  /**
+   * Replay buffered messages to a newly joined agent
+   */
+  _replayMessages(ws, channel) {
+    const ch = this.channels.get(channel);
+    if (!ch || ch.messageBuffer.length === 0) return;
+
+    for (const msg of ch.messageBuffer) {
+      // Send with replay flag so client knows it's history
+      this._send(ws, { ...msg, replay: true });
+    }
+  }
   
   _log(event, data = {}) {
     const entry = {
@@ -310,8 +342,11 @@ export class AgentChatServer {
       channel: msg.channel,
       agents: agentList
     }));
+
+    // Replay recent messages to the joining agent
+    this._replayMessages(ws, msg.channel);
   }
-  
+
   _handleLeave(ws, msg) {
     const agent = this.agents.get(ws);
     if (!agent) {
@@ -376,7 +411,10 @@ export class AgentChatServer {
       
       // Broadcast to channel including sender
       this._broadcast(msg.to, outMsg);
-      
+
+      // Buffer the message for replay to future joiners
+      this._bufferMessage(msg.to, outMsg);
+
     } else if (isAgent(msg.to)) {
       // Direct message
       const targetId = msg.to.slice(1); // remove @
@@ -744,7 +782,8 @@ export function startServer(options = {}) {
     logMessages: options.logMessages || process.env.LOG_MESSAGES === 'true',
     cert: options.cert || process.env.TLS_CERT || null,
     key: options.key || process.env.TLS_KEY || null,
-    rateLimitMs: options.rateLimitMs || parseInt(process.env.RATE_LIMIT_MS || 1000)
+    rateLimitMs: options.rateLimitMs || parseInt(process.env.RATE_LIMIT_MS || 1000),
+    messageBufferSize: options.messageBufferSize || parseInt(process.env.MESSAGE_BUFFER_SIZE || 20)
   };
 
   const server = new AgentChatServer(config);

package/package.json

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