agentgate 0.1.9 → 0.3.0

package/README.md

@@ -135,9 +135,29 @@ agentgate can notify your agent when queue items are completed, failed, or rejec
 
 Compatible with OpenClaw's `/hooks/wake` endpoint. See [OpenClaw webhook docs](https://docs.openclaw.ai/automation/webhook).
 
-## API Key Management
+## Inter-Agent Messaging
 
-Create and manage API keys for your agents in the admin UI at `/ui/keys`.
+Agents can communicate with each other through agentgate, with optional human oversight.
+
+📖 **[See full documentation](docs/inter-agent-messaging.md)**
+
+**Quick overview:**
+- Three modes: **Off**, **Supervised** (human approval), **Open** (immediate delivery)
+- Configure agent webhooks in Admin UI under **API Keys > Configure**
+- Endpoints: `/api/agents/messageable`, `/api/agents/message`, `/api/agents/messages`, `/api/agents/status`
+
+## Agent Registry
+
+Manage your agents in the admin UI at `/ui/keys`. Each agent has:
+
+- **Name** - Unique identifier (case-insensitive)
+- **API Key** - Bearer token for agent → agentgate authentication (shown once at creation)
+- **Webhook URL** (optional) - Endpoint for agentgate → agent notifications
+- **Webhook Token** (optional) - Bearer token for webhook authentication
+
+When an agent's webhook is configured, agentgate will POST notifications for:
+- Queue item status changes (approved/rejected/completed/failed)
+- Inter-agent message delivery or rejection
 
 
 ## Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgate",
-  "version": "0.1.9",
+  "version": "0.3.0",
   "type": "module",
   "description": "API gateway for AI agents with human-in-the-loop write approval",
   "main": "src/index.js",

package/src/index.js

@@ -2,7 +2,7 @@ import express from 'express';
 import cookieParser from 'cookie-parser';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { validateApiKey, getAccountsByService, getCookieSecret, getSetting } from './lib/db.js';
+import { validateApiKey, getAccountsByService, getCookieSecret, getSetting, getMessagingMode } from './lib/db.js';
 import { connectHsync } from './lib/hsyncManager.js';
 import githubRoutes, { serviceInfo as githubInfo } from './routes/github.js';
 import blueskyRoutes, { serviceInfo as blueskyInfo } from './routes/bluesky.js';
@@ -14,6 +14,7 @@ import youtubeRoutes, { serviceInfo as youtubeInfo } from './routes/youtube.js';
 import jiraRoutes, { serviceInfo as jiraInfo } from './routes/jira.js';
 import fitbitRoutes, { serviceInfo as fitbitInfo } from './routes/fitbit.js';
 import queueRoutes from './routes/queue.js';
+import agentsRoutes from './routes/agents.js';
 import uiRoutes from './routes/ui.js';
 
 // Aggregate service metadata from all routes
@@ -80,6 +81,13 @@ app.use('/api/fitbit', apiKeyAuth, readOnlyEnforce, fitbitRoutes);
 // Pattern: /api/queue/{service}/{accountName}/submit
 app.use('/api/queue', apiKeyAuth, queueRoutes);
 
+// Agent messaging routes - require auth, allow POST for sending messages
+// Includes apiKeyName in req for sender identification
+app.use('/api/agents', apiKeyAuth, (req, res, next) => {
+  req.apiKeyName = req.apiKeyInfo.name;
+  next();
+}, agentsRoutes);
+
 // UI routes - no API key needed (local admin access)
 app.use('/ui', uiRoutes);
 
@@ -233,7 +241,61 @@ app.get('/api/readme', apiKeyAuth, (req, res) => {
       queryParams: {
         base_url: 'Override the base URL in the generated skill (optional)'
       }
-    }
+    },
+    agentMessaging: (() => {
+      const mode = getMessagingMode();
+      return {
+        enabled: mode !== 'off',
+        mode,
+        description: mode === 'off'
+          ? 'Agent-to-agent messaging is disabled. Admin can enable it in the agentgate UI.'
+          : mode === 'supervised'
+            ? 'Agents can message each other. Messages require human approval before delivery.'
+            : 'Agents can message each other freely without approval.',
+        endpoints: {
+          sendMessage: {
+            method: 'POST',
+            path: '/api/agents/message',
+            body: { to: 'recipient_agent_name', message: 'Your message content' },
+            response: mode === 'supervised'
+              ? '{ id, status: "pending", message: "Message queued for human approval" }'
+              : '{ id, status: "delivered", message: "Message delivered" }'
+          },
+          getMessages: {
+            method: 'GET',
+            path: '/api/agents/messages',
+            queryParams: { unread: 'true (optional) - only return unread messages' },
+            response: '{ mode, messages: [{ id, from, message, created_at, read }, ...] }'
+          },
+          markRead: {
+            method: 'POST',
+            path: '/api/agents/messages/:id/read',
+            response: '{ success: true }'
+          },
+          status: {
+            method: 'GET',
+            path: '/api/agents/status',
+            response: '{ mode, enabled, unread_count }'
+          },
+          discoverAgents: {
+            method: 'GET',
+            path: '/api/agents/messageable',
+            description: 'Discover which agents you can message',
+            response: '{ mode, agents: [{ name }, ...] }'
+          }
+        },
+        modes: {
+          off: 'Messaging disabled - agents cannot communicate',
+          supervised: 'Messages require human approval before delivery',
+          open: 'Messages delivered immediately without approval'
+        },
+        notes: [
+          'Agent names are case-insensitive (e.g., "WorkBot" and "workbot" are the same)',
+          'Agents cannot message themselves',
+          'Maximum message length is 10KB'
+        ]
+      };
+    })()
   });
 });
 

package/src/lib/agentNotifier.js

@@ -0,0 +1,150 @@
+// Agent notification delivery - sends webhooks to agent gateways
+import { getApiKeyByName, updateQueueNotification } from './db.js';
+
+// Send a notification to an agent's webhook
+export async function notifyAgent(agentName, payload) {
+  const agent = getApiKeyByName(agentName);
+
+  if (!agent) {
+    return { success: false, error: `Agent "${agentName}" not found` };
+  }
+
+  if (!agent.webhook_url) {
+    return { success: false, error: `Agent "${agentName}" has no webhook configured` };
+  }
+
+  try {
+    const headers = {
+      'Content-Type': 'application/json'
+    };
+
+    if (agent.webhook_token) {
+      headers['Authorization'] = `Bearer ${agent.webhook_token}`;
+    }
+
+    const response = await fetch(agent.webhook_url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload)
+    });
+
+    if (response.ok) {
+      return { success: true };
+    } else {
+      const text = await response.text().catch(() => '');
+      return { success: false, error: `HTTP ${response.status}: ${text.substring(0, 200)}` };
+    }
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
+// Notify agent about a queue item status change
+export async function notifyAgentQueueStatus(entry) {
+  const agentName = entry.submitted_by;
+  if (!agentName) {
+    return { success: false, error: 'No submitter on queue entry' };
+  }
+
+  const agent = getApiKeyByName(agentName);
+  if (!agent?.webhook_url) {
+    // Agent doesn't have webhook configured - that's ok, just skip
+    return { success: false, error: 'No webhook configured' };
+  }
+
+  const statusEmoji = {
+    completed: '✅',
+    failed: '❌',
+    rejected: '🚫'
+  };
+
+  const payload = {
+    type: 'queue_status',
+    entry: {
+      id: entry.id,
+      service: entry.service,
+      account_name: entry.account_name,
+      status: entry.status,
+      comment: entry.comment,
+      rejection_reason: entry.rejection_reason,
+      results: entry.results
+    },
+    // Also include a human-readable message for Clawdbot-style gateways
+    text: `${statusEmoji[entry.status] || '📋'} [agentgate] Queue #${entry.id.substring(0, 8)} ${entry.status}\n→ ${entry.service}/${entry.account_name}${entry.rejection_reason ? `\nReason: ${entry.rejection_reason}` : ''}${entry.comment ? `\nOriginal: "${entry.comment.substring(0, 100)}"` : ''}`,
+    mode: 'now'
+  };
+
+  const result = await notifyAgent(agentName, payload);
+
+  // Update notification status in db
+  if (result.success) {
+    updateQueueNotification(entry.id, true);
+  } else {
+    updateQueueNotification(entry.id, false, result.error);
+  }
+
+  return result;
+}
+
+// Notify agent about a new message (delivered to recipient)
+export async function notifyAgentMessage(message) {
+  const agentName = message.to_agent;
+
+  const agent = getApiKeyByName(agentName);
+  if (!agent?.webhook_url) {
+    return { success: false, error: 'No webhook configured' };
+  }
+
+  const payload = {
+    type: 'agent_message',
+    message: {
+      id: message.id,
+      from: message.from_agent,
+      message: message.message,
+      created_at: message.created_at,
+      delivered_at: message.delivered_at
+    },
+    // Human-readable for Clawdbot-style gateways
+    text: `💬 [agentgate] Message from ${message.from_agent}:\n${message.message.substring(0, 500)}`,
+    mode: 'now'
+  };
+
+  return notifyAgent(agentName, payload);
+}
+
+// Notify sender that their message was rejected
+export async function notifyMessageRejected(message) {
+  const agentName = message.from_agent;
+
+  const agent = getApiKeyByName(agentName);
+  if (!agent?.webhook_url) {
+    return { success: false, error: 'No webhook configured' };
+  }
+
+  const payload = {
+    type: 'message_rejected',
+    message: {
+      id: message.id,
+      to: message.to_agent,
+      message: message.message,
+      rejection_reason: message.rejection_reason,
+      created_at: message.created_at,
+      rejected_at: message.reviewed_at
+    },
+    // Human-readable for Clawdbot-style gateways
+    text: `🚫 [agentgate] Message to ${message.to_agent} was rejected${message.rejection_reason ? `\nReason: ${message.rejection_reason}` : ''}\nOriginal: "${message.message.substring(0, 200)}"`,
+    mode: 'now'
+  };
+
+  return notifyAgent(agentName, payload);
+}
+
+// Batch notify multiple agents about their messages
+export async function notifyAgentMessagesBatch(messages) {
+  const results = [];
+  for (const msg of messages) {
+    const result = await notifyAgentMessage(msg);
+    results.push({ messageId: msg.id, ...result });
+  }
+  return results;
+}

package/src/lib/db.js

@@ -47,6 +47,22 @@ db.exec(`
     notified_at TEXT,
     notify_error TEXT
   );
+
+  CREATE TABLE IF NOT EXISTS agent_messages (
+    id TEXT PRIMARY KEY,
+    from_agent TEXT NOT NULL,
+    to_agent TEXT NOT NULL,
+    message TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    rejection_reason TEXT,
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    reviewed_at TEXT,
+    delivered_at TEXT,
+    read_at TEXT
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_agent_messages_recipient
+  ON agent_messages(to_agent, status);
 `);
 
 // Migrate write_queue table to add notification columns
@@ -71,19 +87,23 @@ try {
 }
 
 // Initialize api_keys table with migration support for old schema
-// Old schema had: id, name, key, created_at
-// New schema has: id, name, key_prefix, key_hash, created_at
+// Schema evolution:
+// v1: id, name, key, created_at
+// v2: id, name, key_prefix, key_hash, created_at
+// v3: + webhook_url, webhook_token (for agent configurations)
 try {
   const tableInfo = db.prepare('PRAGMA table_info(api_keys)').all();
 
   if (tableInfo.length === 0) {
-    // Table doesn't exist, create with new schema
+    // Table doesn't exist, create with latest schema
     db.exec(`
       CREATE TABLE api_keys (
         id TEXT PRIMARY KEY,
-        name TEXT NOT NULL,
+        name TEXT NOT NULL UNIQUE,
         key_prefix TEXT NOT NULL,
         key_hash TEXT NOT NULL,
+        webhook_url TEXT,
+        webhook_token TEXT,
         created_at TEXT DEFAULT CURRENT_TIMESTAMP
       );
     `);
@@ -99,22 +119,46 @@ try {
         DROP TABLE api_keys;
         CREATE TABLE api_keys (
           id TEXT PRIMARY KEY,
-          name TEXT NOT NULL,
+          name TEXT NOT NULL UNIQUE,
           key_prefix TEXT NOT NULL,
           key_hash TEXT NOT NULL,
+          webhook_url TEXT,
+          webhook_token TEXT,
           created_at TEXT DEFAULT CURRENT_TIMESTAMP
         );
       `);
       console.log('Migration complete.');
+    } else {
+      // Check if we need to add webhook columns (v2 -> v3 migration)
+      const hasWebhookUrl = tableInfo.some(col => col.name === 'webhook_url');
+      if (!hasWebhookUrl) {
+        console.log('Adding webhook columns to api_keys table...');
+        db.exec(`
+          ALTER TABLE api_keys ADD COLUMN webhook_url TEXT;
+          ALTER TABLE api_keys ADD COLUMN webhook_token TEXT;
+        `);
+        console.log('Webhook columns added.');
+      }
     }
-    // else: table exists with new schema, nothing to do
   }
 } catch (err) {
   console.error('Error initializing api_keys table:', err.message);
 }
 
 // API Keys
+
+// Check if an agent name already exists (case-insensitive)
+export function agentNameExists(name) {
+  const result = db.prepare('SELECT id FROM api_keys WHERE LOWER(name) = LOWER(?)').get(name);
+  return !!result;
+}
+
 export async function createApiKey(name) {
+  // Check for duplicate names (case-insensitive)
+  if (agentNameExists(name)) {
+    throw new Error(`An agent with name "${name}" already exists (names are case-insensitive)`);
+  }
+
   const id = nanoid();
   const key = `rms_${nanoid(32)}`;
   const keyPrefix = key.substring(0, 8) + '...' + key.substring(key.length - 4);
@@ -124,20 +168,33 @@ export async function createApiKey(name) {
 }
 
 export function listApiKeys() {
-  return db.prepare('SELECT id, name, key_prefix, created_at FROM api_keys').all();
+  return db.prepare('SELECT id, name, key_prefix, webhook_url, webhook_token, created_at FROM api_keys').all();
+}
+
+export function getApiKeyByName(name) {
+  // Case-insensitive lookup
+  return db.prepare('SELECT id, name, key_prefix, webhook_url, webhook_token, created_at FROM api_keys WHERE LOWER(name) = LOWER(?)').get(name);
+}
+
+export function getApiKeyById(id) {
+  return db.prepare('SELECT id, name, key_prefix, webhook_url, webhook_token, created_at FROM api_keys WHERE id = ?').get(id);
 }
 
 export function deleteApiKey(id) {
   return db.prepare('DELETE FROM api_keys WHERE id = ?').run(id);
 }
 
+export function updateAgentWebhook(id, webhookUrl, webhookToken) {
+  return db.prepare('UPDATE api_keys SET webhook_url = ?, webhook_token = ? WHERE id = ?').run(webhookUrl || null, webhookToken || null, id);
+}
+
 export async function validateApiKey(key) {
   // Must check all keys since we can't look up by hash directly
   const allKeys = db.prepare('SELECT * FROM api_keys').all();
   for (const row of allKeys) {
     const match = await bcrypt.compare(key, row.key_hash);
     if (match) {
-      return { id: row.id, name: row.name };
+      return { id: row.id, name: row.name, webhookUrl: row.webhook_url, webhookToken: row.webhook_token };
     }
   }
   return null;
@@ -382,4 +439,124 @@ export function listQueueEntriesBySubmitter(submittedBy, service = null, account
   return db.prepare(sql).all(params);
 }
 
+// Agent Messaging
+
+// Get messaging mode: 'off', 'supervised', 'open'
+export function getMessagingMode() {
+  const setting = getSetting('agent_messaging');
+  return setting?.mode || 'off';
+}
+
+export function setMessagingMode(mode) {
+  if (!['off', 'supervised', 'open'].includes(mode)) {
+    throw new Error('Invalid messaging mode');
+  }
+  setSetting('agent_messaging', { mode });
+}
+
+export function createAgentMessage(fromAgent, toAgent, message) {
+  const id = nanoid();
+  const mode = getMessagingMode();
+
+  if (mode === 'off') {
+    throw new Error('Agent messaging is disabled');
+  }
+
+  // In open mode, messages are delivered immediately
+  const status = mode === 'open' ? 'delivered' : 'pending';
+  const deliveredAt = mode === 'open' ? new Date().toISOString() : null;
+
+  db.prepare(`
+    INSERT INTO agent_messages (id, from_agent, to_agent, message, status, delivered_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(id, fromAgent, toAgent, message, status, deliveredAt);
+
+  return { id, status };
+}
+
+export function getAgentMessage(id) {
+  return db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+}
+
+// Get messages for a specific agent (recipient)
+export function getMessagesForAgent(agentName, unreadOnly = false) {
+  let sql = `
+    SELECT * FROM agent_messages
+    WHERE to_agent = ? AND status = 'delivered'
+  `;
+  if (unreadOnly) {
+    sql += ' AND read_at IS NULL';
+  }
+  sql += ' ORDER BY created_at DESC';
+  return db.prepare(sql).all(agentName);
+}
+
+// Mark message as read
+export function markMessageRead(id, agentName) {
+  return db.prepare(`
+    UPDATE agent_messages
+    SET read_at = CURRENT_TIMESTAMP
+    WHERE id = ? AND to_agent = ? AND read_at IS NULL
+  `).run(id, agentName);
+}
+
+// Admin: list pending messages (for supervised mode)
+export function listPendingMessages() {
+  return db.prepare(`
+    SELECT * FROM agent_messages
+    WHERE status = 'pending'
+    ORDER BY created_at DESC
+  `).all();
+}
+
+// Admin: approve message
+export function approveAgentMessage(id) {
+  return db.prepare(`
+    UPDATE agent_messages
+    SET status = 'delivered', reviewed_at = CURRENT_TIMESTAMP, delivered_at = CURRENT_TIMESTAMP
+    WHERE id = ? AND status = 'pending'
+  `).run(id);
+}
+
+// Admin: reject message
+export function rejectAgentMessage(id, reason) {
+  return db.prepare(`
+    UPDATE agent_messages
+    SET status = 'rejected', reviewed_at = CURRENT_TIMESTAMP, rejection_reason = ?
+    WHERE id = ? AND status = 'pending'
+  `).run(reason || 'No reason provided', id);
+}
+
+// Admin: list all messages (for UI)
+export function listAgentMessages(status = null) {
+  if (status) {
+    return db.prepare('SELECT * FROM agent_messages WHERE status = ? ORDER BY created_at DESC').all(status);
+  }
+  return db.prepare('SELECT * FROM agent_messages ORDER BY created_at DESC').all();
+}
+
+// Admin: delete message
+export function deleteAgentMessage(id) {
+  return db.prepare('DELETE FROM agent_messages WHERE id = ?').run(id);
+}
+
+// Admin: clear messages by status
+export function clearAgentMessagesByStatus(status) {
+  if (status === 'all') {
+    return db.prepare("DELETE FROM agent_messages WHERE status IN ('delivered', 'rejected')").run();
+  }
+  return db.prepare('DELETE FROM agent_messages WHERE status = ?').run(status);
+}
+
+// Get counts for message queue
+export function getMessageCounts() {
+  const rows = db.prepare('SELECT status, COUNT(*) as count FROM agent_messages GROUP BY status').all();
+  const counts = { all: 0, pending: 0, delivered: 0, rejected: 0 };
+  for (const row of rows) {
+    counts[row.status] = row.count;
+    counts.all += row.count;
+  }
+  return counts;
+}
+
 export default db;

package/src/lib/notifier.js

@@ -7,6 +7,30 @@ import { getSetting, updateQueueNotification } from './db.js';
 const DEFAULT_RETRY_ATTEMPTS = 3;
 const DEFAULT_RETRY_DELAY_MS = 5000;
 
+/**
+ * Find the most relevant result to display (usually last one with a URL, or first failure)
+ */
+function findRelevantResult(results, forError = false) {
+  if (!results?.length) return null;
+  
+  if (forError) {
+    // For errors, find the first non-ok result
+    return results.find(r => !r.ok) || results[results.length - 1];
+  }
+  
+  // For success, find the last result with a useful URL (PR, issue, etc.)
+  // Search backwards to get the most relevant one (e.g., PR URL, not branch ref)
+  for (let i = results.length - 1; i >= 0; i--) {
+    const r = results[i];
+    if (r.body?.html_url || r.body?.url) {
+      return r;
+    }
+  }
+  
+  // Fallback to last result
+  return results[results.length - 1];
+}
+
 /**
  * Format the notification text for a queue entry
  */
@@ -18,29 +42,29 @@ function formatNotification(entry) {
   text += `\n→ ${entry.service}/${entry.account_name}`;
 
   // Include key result info (e.g., PR URL, issue URL)
-  if (entry.results?.length) {
-    const firstResult = entry.results[0];
-    if (firstResult.body) {
+  if (entry.status === 'completed' && entry.results?.length) {
+    const relevantResult = findRelevantResult(entry.results, false);
+    if (relevantResult?.body) {
       // GitHub PR/Issue
-      if (firstResult.body.html_url) {
-        text += `\n→ ${firstResult.body.html_url}`;
+      if (relevantResult.body.html_url) {
+        text += `\n→ ${relevantResult.body.html_url}`;
       }
       // Other useful fields
-      else if (firstResult.body.url) {
-        text += `\n→ ${firstResult.body.url}`;
+      else if (relevantResult.body.url) {
+        text += `\n→ ${relevantResult.body.url}`;
       }
     }
   }
 
   // Include error info for failures
   if (entry.status === 'failed' && entry.results?.length) {
-    const firstResult = entry.results[0];
-    if (firstResult.error) {
-      text += `\n→ Error: ${firstResult.error}`;
-    } else if (firstResult.body?.message) {
-      text += `\n→ Error: ${firstResult.body.message}`;
-    } else if (firstResult.status) {
-      text += `\n→ Error: HTTP ${firstResult.status}`;
+    const failingResult = findRelevantResult(entry.results, true);
+    if (failingResult.error) {
+      text += `\n→ Error: ${failingResult.error}`;
+    } else if (failingResult.body?.message) {
+      text += `\n→ Error: ${failingResult.body.message}`;
+    } else if (!failingResult.ok && failingResult.status) {
+      text += `\n→ Error: HTTP ${failingResult.status}`;
     }
   }
 
@@ -166,10 +190,14 @@ function formatBatchLine(entry) {
   let line = `${emoji} #${entry.id.substring(0, 8)} - ${entry.service}/${entry.account_name}`;
 
   // Add brief result info
-  if (entry.status === 'completed' && entry.results?.[0]?.body?.html_url) {
-    line += ` - ${entry.results[0].body.html_url}`;
+  if (entry.status === 'completed') {
+    const relevantResult = findRelevantResult(entry.results, false);
+    if (relevantResult?.body?.html_url) {
+      line += ` - ${relevantResult.body.html_url}`;
+    }
   } else if (entry.status === 'failed') {
-    const err = entry.results?.[0]?.error || entry.results?.[0]?.body?.message || `HTTP ${entry.results?.[0]?.status || '?'}`;
+    const failingResult = findRelevantResult(entry.results, true);
+    const err = failingResult?.error || failingResult?.body?.message || (failingResult && !failingResult.ok ? `HTTP ${failingResult.status || '?'}` : 'Unknown error');
     line += ` - ${err.substring(0, 50)}`;
   } else if (entry.status === 'rejected') {
     line += ` - ${(entry.rejection_reason || 'rejected').substring(0, 50)}`;