@tjamescouch/agentchat 0.21.1 → 0.22.1

package/lib/server/handlers/admin.js

@@ -0,0 +1,94 @@
+/**
+ * Admin Handlers
+ * Handles allowlist administration commands
+ */
+
+import {
+  ServerMessageType,
+  ErrorCode,
+  createMessage,
+  createError,
+} from '../../protocol.js';
+
+/**
+ * Handle ADMIN_APPROVE command - add a pubkey to the allowlist
+ */
+export function handleAdminApprove(server, ws, msg) {
+  if (!server.allowlist) {
+    server._send(ws, createError(ErrorCode.INVALID_MSG, 'Allowlist not configured'));
+    return;
+  }
+
+  if (!msg.pubkey) {
+    server._send(ws, createError(ErrorCode.INVALID_MSG, 'Missing pubkey'));
+    return;
+  }
+
+  const result = server.allowlist.approve(msg.pubkey, msg.admin_key, msg.note || '');
+
+  if (!result.success) {
+    server._send(ws, createError(ErrorCode.AUTH_REQUIRED, result.error));
+    return;
+  }
+
+  server._log('admin_approve', { agentId: result.agentId });
+  server._send(ws, createMessage(ServerMessageType.ADMIN_RESULT, {
+    action: 'approve',
+    success: true,
+    agentId: `@${result.agentId}`,
+  }));
+}
+
+/**
+ * Handle ADMIN_REVOKE command - remove a pubkey from the allowlist
+ */
+export function handleAdminRevoke(server, ws, msg) {
+  if (!server.allowlist) {
+    server._send(ws, createError(ErrorCode.INVALID_MSG, 'Allowlist not configured'));
+    return;
+  }
+
+  const identifier = msg.pubkey || msg.agent_id;
+  if (!identifier) {
+    server._send(ws, createError(ErrorCode.INVALID_MSG, 'Missing pubkey or agent_id'));
+    return;
+  }
+
+  const result = server.allowlist.revoke(identifier, msg.admin_key);
+
+  if (!result.success) {
+    const code = result.error === 'invalid admin key' ? ErrorCode.AUTH_REQUIRED : ErrorCode.AGENT_NOT_FOUND;
+    server._send(ws, createError(code, result.error));
+    return;
+  }
+
+  server._log('admin_revoke', { identifier });
+  server._send(ws, createMessage(ServerMessageType.ADMIN_RESULT, {
+    action: 'revoke',
+    success: true,
+  }));
+}
+
+/**
+ * Handle ADMIN_LIST command - list all approved entries
+ */
+export function handleAdminList(server, ws, msg) {
+  if (!server.allowlist) {
+    server._send(ws, createError(ErrorCode.INVALID_MSG, 'Allowlist not configured'));
+    return;
+  }
+
+  // Validate admin key
+  if (!server.allowlist._validateAdminKey(msg.admin_key)) {
+    server._send(ws, createError(ErrorCode.AUTH_REQUIRED, 'Invalid admin key'));
+    return;
+  }
+
+  const entries = server.allowlist.list();
+  server._send(ws, createMessage(ServerMessageType.ADMIN_RESULT, {
+    action: 'list',
+    entries,
+    enabled: server.allowlist.enabled,
+    strict: server.allowlist.strict,
+  }));
+}

package/lib/server/handlers/identity.js

@@ -24,6 +24,21 @@ export function handleIdentify(server, ws, msg) {
     return;
   }
 
+  // Allowlist check (before any state changes)
+  if (server.allowlist && server.allowlist.enabled) {
+    const check = server.allowlist.check(msg.pubkey || null);
+    if (!check.allowed) {
+      server._log('allowlist_rejected', {
+        ip: ws._realIp,
+        name: msg.name,
+        hasPubkey: !!msg.pubkey,
+        reason: check.reason
+      });
+      server._send(ws, createError(ErrorCode.NOT_ALLOWED, check.reason));
+      return;
+    }
+  }
+
   let id;
 
   // Use pubkey-derived stable ID if pubkey provided
@@ -82,6 +97,7 @@ export function handleIdentify(server, ws, msg) {
 
   server._send(ws, createMessage(ServerMessageType.WELCOME, {
     agent_id: `@${id}`,
+    name: msg.name,
     server: server.serverName
   }));
 }

package/lib/server/handlers/message.js

@@ -33,6 +33,7 @@ export function handleMsg(server, ws, msg) {
 
   const outMsg = createMessage(ServerMessageType.MSG, {
     from: `@${agent.id}`,
+    from_name: agent.name,
     to: msg.to,
     content: msg.content,
     ...(msg.sig && { sig: msg.sig })
@@ -108,14 +109,15 @@ export function handleJoin(server, ws, msg) {
   // Notify others
   server._broadcast(msg.channel, createMessage(ServerMessageType.AGENT_JOINED, {
     channel: msg.channel,
-    agent: `@${agent.id}`
+    agent: `@${agent.id}`,
+    name: agent.name
   }), ws);
 
   // Send confirmation with agent list
   const agentList = [];
   for (const memberWs of channel.agents) {
     const member = server.agents.get(memberWs);
-    if (member) agentList.push(`@${member.id}`);
+    if (member) agentList.push({ id: `@${member.id}`, name: member.name });
   }
 
   server._send(ws, createMessage(ServerMessageType.JOINED, {
@@ -130,7 +132,7 @@ export function handleJoin(server, ws, msg) {
   server._send(ws, createMessage(ServerMessageType.MSG, {
     from: '@server',
     to: msg.channel,
-    content: `Welcome to ${msg.channel}, @${agent.id}! Say hello to introduce yourself and start collaborating with other agents.`
+    content: `Welcome to ${msg.channel}, ${agent.name} (@${agent.id})! Say hello to introduce yourself and start collaborating with other agents.`
   }));
 
   // Prompt existing agents to engage with the new joiner (if there are others)
@@ -138,7 +140,7 @@ export function handleJoin(server, ws, msg) {
   for (const memberWs of channel.agents) {
     if (memberWs !== ws) {
       const member = server.agents.get(memberWs);
-      if (member) otherAgents.push({ ws: memberWs, id: member.id });
+      if (member) otherAgents.push({ ws: memberWs, id: member.id, name: member.name });
     }
   }
 
@@ -146,7 +148,7 @@ export function handleJoin(server, ws, msg) {
     const welcomePrompt = createMessage(ServerMessageType.MSG, {
       from: '@server',
       to: msg.channel,
-      content: `Hey ${otherAgents.map(a => `@${a.id}`).join(', ')} - new agent @${agent.id} just joined! Say hi and share what you're working on.`
+      content: `Hey ${otherAgents.map(a => `${a.name} (@${a.id})`).join(', ')} - new agent ${agent.name} (@${agent.id}) just joined! Say hi and share what you're working on.`
     });
 
     for (const other of otherAgents) {
@@ -179,7 +181,8 @@ export function handleLeave(server, ws, msg) {
   // Notify others
   server._broadcast(msg.channel, createMessage(ServerMessageType.AGENT_LEFT, {
     channel: msg.channel,
-    agent: `@${agent.id}`
+    agent: `@${agent.id}`,
+    name: agent.name
   }));
 
   server._send(ws, createMessage(ServerMessageType.LEFT, {
@@ -189,8 +192,11 @@ export function handleLeave(server, ws, msg) {
 
 /**
  * Handle LIST_CHANNELS command
+ * Unauthenticated: returns channel names and agent count only
+ * Authenticated: returns full details
  */
 export function handleListChannels(server, ws) {
+  const agent = server.agents.get(ws);
   const list = [];
   for (const [name, channel] of server.channels) {
     if (!channel.inviteOnly) {
@@ -206,8 +212,15 @@ export function handleListChannels(server, ws) {
 
 /**
  * Handle LIST_AGENTS command
+ * Requires authentication to see agent details
  */
 export function handleListAgents(server, ws, msg) {
+  const agent = server.agents.get(ws);
+  if (!agent) {
+    server._send(ws, createError(ErrorCode.AUTH_REQUIRED, 'Must IDENTIFY first'));
+    return;
+  }
+
   const channel = server.channels.get(msg.channel);
   if (!channel) {
     server._send(ws, createError(ErrorCode.CHANNEL_NOT_FOUND, `Channel ${msg.channel} not found`));

package/lib/server/handlers/presence.js

@@ -34,6 +34,7 @@ export function handleSetPresence(server, ws, msg) {
   // Broadcast presence change to all channels the agent is in
   const presenceMsg = createMessage(ServerMessageType.PRESENCE_CHANGED, {
     agent_id: `@${agent.id}`,
+    name: agent.name,
     presence: agent.presence,
     status_text: agent.statusText
   });

package/lib/server-directory.js

@@ -9,14 +9,23 @@ import fs from 'fs/promises';
 import path from 'path';
 
 // Default public servers (can be extended)
-export const DEFAULT_SERVERS = [
-  {
-    name: 'AgentChat Public',
-    url: 'wss://agentchat-server.fly.dev',
-    description: 'Official public AgentChat server',
-    region: 'global'
-  }
-];
+export const DEFAULT_SERVERS = process.env.AGENTCHAT_PUBLIC === 'true'
+  ? [
+      {
+        name: 'AgentChat Public',
+        url: 'wss://agentchat-server.fly.dev',
+        description: 'Official public AgentChat server',
+        region: 'global'
+      }
+    ]
+  : [
+      {
+        name: 'AgentChat Local',
+        url: 'ws://localhost:6667',
+        description: 'Local AgentChat server',
+        region: 'local'
+      }
+    ];
 
 // Default directory file path
 export const DEFAULT_DIRECTORY_PATH = path.join(

package/lib/server-directory.ts

@@ -0,0 +1,232 @@
+/**
+ * Server Directory
+ * Registry of known AgentChat servers for discovery
+ */
+
+import http from 'http';
+import https from 'https';
+import fs from 'fs/promises';
+import path from 'path';
+
+export interface ServerEntry {
+  name: string;
+  url: string;
+  description?: string;
+  region?: string;
+}
+
+export interface HealthData {
+  agents?: {
+    connected?: number;
+  };
+  uptime_seconds?: number;
+  [key: string]: unknown;
+}
+
+export interface ServerWithStatus extends ServerEntry {
+  status: 'online' | 'offline' | 'unknown';
+  health?: HealthData;
+  error?: string;
+  checked_at?: string;
+}
+
+export interface ServerDirectoryFile {
+  version: number;
+  updated_at: string;
+  servers: ServerEntry[];
+}
+
+export interface ServerDirectoryOptions {
+  directoryPath?: string;
+  timeout?: number;
+}
+
+export interface DiscoverOptions {
+  onlineOnly?: boolean;
+}
+
+// Default public servers (can be extended)
+export const DEFAULT_SERVERS: ServerEntry[] = process.env.AGENTCHAT_PUBLIC === 'true'
+  ? [
+      {
+        name: 'AgentChat Public',
+        url: 'wss://agentchat-server.fly.dev',
+        description: 'Official public AgentChat server',
+        region: 'global'
+      }
+    ]
+  : [
+      {
+        name: 'AgentChat Local',
+        url: 'ws://localhost:6667',
+        description: 'Local AgentChat server',
+        region: 'local'
+      }
+    ];
+
+// Default directory file path
+export const DEFAULT_DIRECTORY_PATH: string = path.join(
+  process.env.HOME || process.env.USERPROFILE || '.',
+  '.agentchat',
+  'servers.json'
+);
+
+/**
+ * Server Directory for discovering AgentChat servers
+ */
+export class ServerDirectory {
+  private directoryPath: string;
+  private servers: ServerEntry[];
+  private timeout: number;
+
+  constructor(options: ServerDirectoryOptions = {}) {
+    this.directoryPath = options.directoryPath || DEFAULT_DIRECTORY_PATH;
+    this.servers = [...DEFAULT_SERVERS];
+    this.timeout = options.timeout || 5000;
+  }
+
+  /**
+   * Load servers from directory file
+   */
+  async load(): Promise<this> {
+    try {
+      const data = await fs.readFile(this.directoryPath, 'utf8');
+      const loaded = JSON.parse(data) as ServerDirectoryFile;
+      if (Array.isArray(loaded.servers)) {
+        // Merge with defaults, avoiding duplicates by URL
+        const urls = new Set(this.servers.map(s => s.url));
+        for (const server of loaded.servers) {
+          if (!urls.has(server.url)) {
+            this.servers.push(server);
+            urls.add(server.url);
+          }
+        }
+      }
+    } catch {
+      // File doesn't exist or is invalid, use defaults
+    }
+    return this;
+  }
+
+  /**
+   * Save servers to directory file
+   */
+  async save(): Promise<void> {
+    const dir = path.dirname(this.directoryPath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(this.directoryPath, JSON.stringify({
+      version: 1,
+      updated_at: new Date().toISOString(),
+      servers: this.servers
+    } as ServerDirectoryFile, null, 2));
+  }
+
+  /**
+   * Add a server to the directory
+   */
+  async addServer(server: ServerEntry): Promise<void> {
+    const existing = this.servers.find(s => s.url === server.url);
+    if (existing) {
+      Object.assign(existing, server);
+    } else {
+      this.servers.push(server);
+    }
+    await this.save();
+  }
+
+  /**
+   * Remove a server from the directory
+   */
+  async removeServer(url: string): Promise<void> {
+    this.servers = this.servers.filter(s => s.url !== url);
+    await this.save();
+  }
+
+  /**
+   * Check health of a single server
+   * @param server - Server object with url
+   * @returns Server with health status
+   */
+  async checkHealth(server: ServerEntry): Promise<ServerWithStatus> {
+    const wsUrl = server.url;
+    // Convert ws:// or wss:// to http:// or https://
+    const httpUrl = wsUrl
+      .replace('wss://', 'https://')
+      .replace('ws://', 'http://');
+
+    try {
+      const health = await this._fetchHealth(httpUrl + '/health');
+      return {
+        ...server,
+        status: 'online',
+        health,
+        checked_at: new Date().toISOString()
+      };
+    } catch (err) {
+      const error = err as Error & { code?: string };
+      return {
+        ...server,
+        status: 'offline',
+        error: error.message || error.code || 'Unknown error',
+        checked_at: new Date().toISOString()
+      };
+    }
+  }
+
+  /**
+   * Fetch health endpoint
+   */
+  private _fetchHealth(url: string): Promise<HealthData> {
+    return new Promise((resolve, reject) => {
+      const protocol = url.startsWith('https') ? https : http;
+      const req = protocol.get(url, { timeout: this.timeout }, (res) => {
+        let data = '';
+        res.on('data', (chunk: Buffer) => data += chunk);
+        res.on('end', () => {
+          if (res.statusCode === 200) {
+            try {
+              resolve(JSON.parse(data) as HealthData);
+            } catch {
+              reject(new Error('Invalid health response'));
+            }
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}`));
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error('Timeout'));
+      });
+    });
+  }
+
+  /**
+   * Discover available servers (check health of all known servers)
+   * @param options
+   * @param options.onlineOnly - Only return online servers
+   * @returns List of servers with status
+   */
+  async discover(options: DiscoverOptions = {}): Promise<ServerWithStatus[]> {
+    const results = await Promise.all(
+      this.servers.map(server => this.checkHealth(server))
+    );
+
+    if (options.onlineOnly) {
+      return results.filter(s => s.status === 'online');
+    }
+
+    return results;
+  }
+
+  /**
+   * Get list of known servers without health check
+   */
+  list(): ServerEntry[] {
+    return [...this.servers];
+  }
+}
+
+export default ServerDirectory;