agentgate 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgate",
-  "version": "0.3.2",
+  "version": "0.4.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,8 +2,9 @@ import express from 'express';
 import cookieParser from 'cookie-parser';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { validateApiKey, getAccountsByService, getCookieSecret, getSetting, getMessagingMode } from './lib/db.js';
+import { validateApiKey, getAccountsByService, getCookieSecret, getMessagingMode } from './lib/db.js';
 import { connectHsync } from './lib/hsyncManager.js';
+import { initSocket } from './lib/socketManager.js';
 import githubRoutes, { serviceInfo as githubInfo } from './routes/github.js';
 import blueskyRoutes, { serviceInfo as blueskyInfo } from './routes/bluesky.js';
 import redditRoutes, { serviceInfo as redditInfo } from './routes/reddit.js';
@@ -186,7 +187,19 @@ app.get('/api/readme', apiKeyAuth, (req, res) => {
           { method: 'GET', path: '/api/queue/list', description: 'List all your submissions across all services' },
           { method: 'GET', path: '/api/queue/{service}/{accountName}/list', description: 'List your submissions for a specific service/account' }
         ],
-        response: '{ count: number, entries: [{ id, service, account_name, comment, status, rejection_reason?, submitted_at, reviewed_at?, completed_at? }, ...] }'
+        response: '{ count: number, shared_visibility: boolean, entries: [{ id, service, account_name, comment, status, submitted_by, rejection_reason?, submitted_at, reviewed_at?, completed_at? }, ...] }',
+        sharedVisibility: 'When shared_queue_visibility is enabled by admin, agents can see ALL queue items (not just their own). Response includes shared_visibility: true when active.'
+      },
+      withdraw: {
+        description: 'Withdraw your own pending submission (requires agent_withdraw_enabled setting)',
+        method: 'DELETE',
+        path: '/api/queue/{service}/{accountName}/status/{id}',
+        constraints: [
+          'Only the submitting agent can withdraw their own items',
+          'Only works for "pending" status - cannot withdraw approved/completed/etc',
+          'Requires admin to enable agent_withdraw_enabled setting'
+        ],
+        response: '{ success: true, message: "Queue entry withdrawn", id }'
       },
       statuses: {
         pending: 'Waiting for human approval',
@@ -194,7 +207,8 @@ app.get('/api/readme', apiKeyAuth, (req, res) => {
         executing: 'Currently running the requests',
         completed: 'All requests succeeded',
         failed: 'One or more requests failed (check results)',
-        rejected: 'Human rejected the request (check rejection_reason)'
+        rejected: 'Human rejected the request (check rejection_reason)',
+        withdrawn: 'Agent withdrew their own pending request'
       },
       example: {
         submit: {
@@ -213,27 +227,50 @@ app.get('/api/readme', apiKeyAuth, (req, res) => {
         }
       }
     },
-    notifications: (() => {
-      const config = getSetting('notifications');
-      const enabled = config?.clawdbot?.enabled || false;
-      return {
-        enabled,
-        description: enabled
-          ? 'Webhook notifications are ENABLED. You will receive automatic notifications when queue items complete, fail, or are rejected. No need to poll.'
-          : 'Webhook notifications are NOT configured. You must poll the status endpoint to check request status.',
-        setup: 'Configure in Admin UI under Advanced → Clawdbot Notifications',
-        webhookFormat: {
-          description: 'POST to your webhook URL with JSON body',
-          payload: {
-            text: 'Notification message with status, service, result URL, and original comment',
-            mode: 'now'
-          },
-          example: '✅ [agentgate] Queue #abc123 completed\\n→ github/monteslu\\n→ https://github.com/...\\nOriginal: "Create PR"'
+    notifications: {
+      description: 'Agents receive webhook notifications for queue status updates (completed/failed/rejected) and agent messages. Each agent configures their own webhook.',
+      setup: {
+        agentgateConfig: {
+          description: 'Configure YOUR webhook in agentgate Admin UI',
+          steps: [
+            '1. Go to Admin UI → API Keys',
+            '2. Click "Configure" next to your API key',
+            '3. Enter Webhook URL (e.g., https://your-gateway.com/hooks/wake)',
+            '4. Enter Authorization Token (bearer token for your gateway)'
+          ]
         },
-        events: enabled ? (config.clawdbot.events || ['completed', 'failed']) : ['completed', 'failed', 'rejected'],
-        compatible: 'OpenClaw/Clawdbot /hooks/wake endpoint'
-      };
-    })(),
+        gatewayConfig: {
+          description: 'Your gateway must ALSO have webhooks enabled to receive POSTs',
+          openclaw: 'Add to config: { "hooks": { "enabled": true, "token": "your-token" } }',
+          note: 'Without this, your gateway returns 405 and notifications fail silently'
+        }
+      },
+      webhookFormat: {
+        description: 'POST to your webhook URL with JSON body',
+        payload: {
+          text: 'Notification message with status, service, result URL, and original comment',
+          mode: 'now'
+        },
+        example: '✅ [agentgate] Queue #abc123 completed\\n→ github/monteslu\\n→ https://github.com/...\\nOriginal: "Create PR"'
+      },
+      events: ['completed', 'failed', 'rejected', 'agent_message', 'broadcast', 'message_rejected'],
+      troubleshooting: [
+        'Check webhook URL/token in API Keys → Configure',
+        'Ensure hooks.enabled=true in your gateway config',
+        'Test endpoint: curl -X POST <url> -H "Authorization: Bearer <token>" -d \'{"text":"test"}\''
+      ],
+      compatible: 'OpenClaw/Clawdbot /hooks/wake endpoint',
+      bestPractice: {
+        description: 'Treat notifications as action triggers, not just acknowledgments',
+        examples: [
+          'Queue completed (PR created) → Request code review from teammate',
+          'PR merged → Update docs, notify stakeholders, start next task',
+          'Queue rejected → Read reason, fix issue, resubmit',
+          'Queue failed → Check error, debug, resubmit',
+          'Message received → Respond if needed and act on implied tasks'
+        ]
+      }
+    },
     skill: {
       description: 'Generate a SKILL.md file for OpenClaw/AgentSkills compatible systems',
       endpoint: 'GET /api/skill',
@@ -282,6 +319,18 @@ app.get('/api/readme', apiKeyAuth, (req, res) => {
             path: '/api/agents/messageable',
             description: 'Discover which agents you can message',
             response: '{ mode, agents: [{ name }, ...] }'
+          },
+          broadcast: {
+            method: 'POST',
+            path: '/api/agents/broadcast',
+            description: 'Send a message to ALL agents with webhooks (excluding yourself)',
+            body: { message: 'Your broadcast message' },
+            response: '{ delivered: ["Agent1", "Agent2"], failed: [{ name: "Agent3", error: "HTTP 500" }], total: 3 }',
+            notes: [
+              'Broadcasts go directly to agent webhooks - not stored in messages table',
+              'Sender is automatically excluded from recipients',
+              'Requires messaging mode to be "supervised" or "open" (not "off")'
+            ]
           }
         },
         modes: {
@@ -435,6 +484,10 @@ const server = app.listen(PORT, async () => {
   console.log(`agentgate gateway running at http://localhost:${PORT}`);
   console.log(`Admin UI: http://localhost:${PORT}/ui`);
 
+  // Initialize socket.io for real-time updates
+  initSocket(server);
+  console.log('Socket.io initialized for real-time updates');
+
   // Start hsync if configured
   try {
     await connectHsync(PORT);

package/src/lib/db.js

@@ -406,7 +406,7 @@ export function getPendingQueueCount() {
 
 export function getQueueCounts() {
   const rows = db.prepare('SELECT status, COUNT(*) as count FROM write_queue GROUP BY status').all();
-  const counts = { all: 0, pending: 0, completed: 0, failed: 0, rejected: 0 };
+  const counts = { all: 0, pending: 0, completed: 0, failed: 0, rejected: 0, withdrawn: 0 };
   for (const row of rows) {
     counts[row.status] = row.count;
     counts.all += row.count;
@@ -560,3 +560,45 @@ export function getMessageCounts() {
 }
 
 export default db;
+
+// Shared Queue Visibility helpers
+export function getSharedQueueVisibility() {
+  return getSetting('shared_queue_visibility') === true;
+}
+
+export function setSharedQueueVisibility(enabled) {
+  setSetting('shared_queue_visibility', enabled);
+}
+
+// List all queue entries (for shared visibility mode)
+export function listAllQueueEntries(service = null, accountName = null) {
+  let sql = 'SELECT * FROM write_queue';
+  const params = [];
+  
+  if (service && accountName) {
+    sql += ' WHERE service = ? AND account_name = ?';
+    params.push(service, accountName);
+  } else if (service) {
+    sql += ' WHERE service = ?';
+    params.push(service);
+  }
+  
+  sql += ' ORDER BY submitted_at DESC';
+  
+  const rows = db.prepare(sql).all(...params);
+  return rows.map(row => ({
+    ...row,
+    requests: JSON.parse(row.requests),
+    results: row.results ? JSON.parse(row.results) : null,
+    notified: Boolean(row.notified)
+  }));
+}
+
+// Agent Withdraw helpers
+export function getAgentWithdrawEnabled() {
+  return getSetting('agent_withdraw_enabled') === true;
+}
+
+export function setAgentWithdrawEnabled(enabled) {
+  setSetting('agent_withdraw_enabled', enabled);
+}

package/src/lib/socketManager.js

@@ -0,0 +1,73 @@
+import { Server } from 'socket.io';
+import { getQueueCounts, getMessageCounts, getMessagingMode } from './db.js';
+
+let io = null;
+
+/**
+ * Initialize socket.io with the HTTP server
+ * @param {import('http').Server} server - The HTTP server instance
+ */
+export function initSocket(server) {
+  io = new Server(server, {
+    cors: {
+      origin: '*',
+      methods: ['GET', 'POST']
+    }
+  });
+
+  io.on('connection', (socket) => {
+    // Send current counts immediately on connect
+    socket.emit('counts', getCurrentCounts());
+
+    socket.on('disconnect', () => {
+      // Client disconnected
+    });
+  });
+
+  return io;
+}
+
+/**
+ * Get current counts for queue and messages
+ */
+function getCurrentCounts() {
+  const queueCounts = getQueueCounts();
+  const messageCounts = getMessageCounts();
+  const messagingMode = getMessagingMode();
+
+  return {
+    queue: {
+      pending: queueCounts.pending,
+      total: queueCounts.all
+    },
+    messages: {
+      pending: messageCounts.pending,
+      unread: messageCounts.delivered,
+      total: messageCounts.all
+    },
+    messagingEnabled: messagingMode !== 'off'
+  };
+}
+
+/**
+ * Emit count update to all connected clients
+ * Call this whenever queue or message counts change
+ */
+export function emitCountUpdate() {
+  if (io) {
+    io.emit('counts', getCurrentCounts());
+  }
+}
+
+/**
+ * Emit a specific event to all connected clients
+ * @param {string} event - Event name
+ * @param {any} data - Event data
+ */
+export function emitEvent(event, data) {
+  if (io) {
+    io.emit(event, data);
+  }
+}
+
+export { io };

package/src/routes/agents.js

@@ -9,6 +9,7 @@ import {
   getApiKeyByName
 } from '../lib/db.js';
 import { notifyAgentMessage } from '../lib/agentNotifier.js';
+import { emitCountUpdate } from '../lib/socketManager.js';
 
 const router = Router();
 
@@ -63,6 +64,9 @@ router.post('/message', async (req, res) => {
     // Use canonical recipient name from database
     const result = createAgentMessage(fromAgent, recipientName, message);
 
+    // Emit real-time update
+    emitCountUpdate();
+
     if (mode === 'supervised') {
       return res.json({
         id: result.id,
@@ -182,4 +186,73 @@ router.get('/messageable', async (req, res) => {
   });
 });
 
+
+// POST /api/agents/broadcast - Broadcast a message to all agents
+router.post('/broadcast', async (req, res) => {
+  const { message } = req.body;
+  const fromAgent = req.apiKeyName || 'system';
+
+  if (!message) {
+    return res.status(400).json({ error: 'Missing "message" field' });
+  }
+
+  if (message.length > MAX_MESSAGE_LENGTH) {
+    return res.status(400).json({
+      error: `Message too long. Maximum ${MAX_MESSAGE_LENGTH} bytes allowed.`
+    });
+  }
+
+  const mode = getMessagingMode();
+  if (mode === 'off') {
+    return res.status(403).json({ error: 'Agent messaging is disabled' });
+  }
+
+  // Get all agents with webhooks (excluding sender)
+  const apiKeys = listApiKeys();
+  const recipients = apiKeys.filter(k => 
+    k.webhook_url && k.name.toLowerCase() !== fromAgent.toLowerCase()
+  );
+
+  if (recipients.length === 0) {
+    return res.json({ delivered: [], failed: [], total: 0 });
+  }
+
+  const delivered = [];
+  const failed = [];
+
+  await Promise.all(recipients.map(async (agent) => {
+    const payload = {
+      type: 'broadcast',
+      from: fromAgent,
+      message: message,
+      timestamp: new Date().toISOString(),
+      text: `📢 [agentgate] Broadcast from ${fromAgent}:\n${message.substring(0, 500)}`,
+      mode: 'now'
+    };
+
+    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) {
+        delivered.push(agent.name);
+      } else {
+        failed.push({ name: agent.name, error: `HTTP ${response.status}` });
+      }
+    } catch (err) {
+      failed.push({ name: agent.name, error: err.message });
+    }
+  }));
+
+  return res.json({ delivered, failed, total: recipients.length });
+});
+
 export default router;

package/src/routes/queue.js

@@ -1,5 +1,6 @@
 import { Router } from 'express';
-import { createQueueEntry, getQueueEntry, getAccountCredentials, listQueueEntriesBySubmitter } from '../lib/db.js';
+import { createQueueEntry, getQueueEntry, getAccountCredentials, listQueueEntriesBySubmitter, updateQueueStatus, getSharedQueueVisibility, listAllQueueEntries, getAgentWithdrawEnabled } from '../lib/db.js';
+import { emitCountUpdate } from '../lib/socketManager.js';
 
 const router = Router();
 
@@ -69,6 +70,9 @@ router.post('/:service/:accountName/submit', (req, res) => {
     // Create the queue entry
     const entry = createQueueEntry(service, accountName, requests, comment, submittedBy);
 
+    // Emit real-time update
+    emitCountUpdate();
+
     res.status(201).json({
       id: entry.id,
       status: entry.status,
@@ -88,10 +92,14 @@ router.post('/:service/:accountName/submit', (req, res) => {
 router.get('/list', (req, res) => {
   try {
     const submittedBy = req.apiKeyInfo?.name || 'unknown';
-    const entries = listQueueEntriesBySubmitter(submittedBy);
+    const sharedVisibility = getSharedQueueVisibility();
+    const entries = sharedVisibility 
+      ? listAllQueueEntries() 
+      : listQueueEntriesBySubmitter(submittedBy);
 
     res.json({
       count: entries.length,
+      shared_visibility: sharedVisibility,
       entries: entries
     });
   } catch (error) {
@@ -115,10 +123,14 @@ router.get('/:service/:accountName/list', (req, res) => {
       });
     }
 
-    const entries = listQueueEntriesBySubmitter(submittedBy, service, accountName);
+    const sharedVisibility = getSharedQueueVisibility();
+    const entries = sharedVisibility 
+      ? listAllQueueEntries(service, accountName) 
+      : listQueueEntriesBySubmitter(submittedBy, service, accountName);
 
     res.json({
       count: entries.length,
+      shared_visibility: sharedVisibility,
       entries: entries
     });
   } catch (error) {
@@ -183,4 +195,67 @@ router.get('/:service/:accountName/status/:id', (req, res) => {
   }
 });
 
+
+// Withdraw a pending queue item (agent can only withdraw their own submissions)
+// DELETE /api/queue/:service/:accountName/status/:id
+router.delete('/:service/:accountName/status/:id', (req, res) => {
+  try {
+    // Check if withdraw is enabled
+    if (!getAgentWithdrawEnabled()) {
+      return res.status(403).json({
+        error: 'Disabled',
+        message: 'Agent withdraw is not enabled. Ask admin to enable agent_withdraw_enabled setting.'
+      });
+    }
+
+    const { id } = req.params;
+    const agentName = req.apiKeyInfo?.name || 'unknown'; // Set by auth middleware
+
+    const entry = getQueueEntry(id);
+
+    if (!entry) {
+      return res.status(404).json({
+        error: 'Not found',
+        message: 'Queue entry not found'
+      });
+    }
+
+    // Verify the requesting agent is the submitter
+    if (entry.submitted_by !== agentName) {
+      return res.status(403).json({
+        error: 'Forbidden',
+        message: 'You can only withdraw your own submissions'
+      });
+    }
+
+    // Only allow withdrawal of pending items
+    if (entry.status !== 'pending') {
+      return res.status(400).json({
+        error: 'Cannot withdraw',
+        message: `Cannot withdraw entry with status "${entry.status}". Only pending items can be withdrawn.`
+      });
+    }
+
+    // Update status to withdrawn
+    updateQueueStatus(id, 'withdrawn', { 
+      reviewed_at: new Date().toISOString().replace('T', ' ').replace('Z', '')
+    });
+
+    // Emit real-time update
+    emitCountUpdate();
+
+    res.json({
+      success: true,
+      message: 'Queue entry withdrawn',
+      id: id
+    });
+
+  } catch (error) {
+    res.status(500).json({
+      error: 'Failed to withdraw',
+      message: error.message
+    });
+  }
+});
+
 export default router;

package/src/routes/ui/auth.js

@@ -0,0 +1,149 @@
+// Auth routes - login, logout, password setup
+import { Router } from 'express';
+import { setAdminPassword, verifyAdminPassword, hasAdminPassword } from '../../lib/db.js';
+import { AUTH_COOKIE, COOKIE_MAX_AGE, htmlHead } from './shared.js';
+
+const router = Router();
+
+// Check if user is authenticated
+export function isAuthenticated(req) {
+  return req.signedCookies[AUTH_COOKIE] === 'authenticated';
+}
+
+// Auth middleware for protected routes
+export function requireAuth(req, res, next) {
+  if (req.path === '/login' || req.path === '/setup-password') {
+    return next();
+  }
+
+  if (!hasAdminPassword()) {
+    return res.redirect('/ui/setup-password');
+  }
+
+  if (!isAuthenticated(req)) {
+    return res.redirect('/ui/login');
+  }
+
+  next();
+}
+
+// Login page
+router.get('/login', (req, res) => {
+  if (!hasAdminPassword()) {
+    return res.redirect('/ui/setup-password');
+  }
+  if (isAuthenticated(req)) {
+    return res.redirect('/ui');
+  }
+  res.send(renderLoginPage());
+});
+
+// Handle login
+router.post('/login', async (req, res) => {
+  const { password } = req.body;
+  if (!password) {
+    return res.send(renderLoginPage('Password required'));
+  }
+
+  const valid = await verifyAdminPassword(password);
+  if (!valid) {
+    return res.send(renderLoginPage('Invalid password'));
+  }
+
+  res.cookie(AUTH_COOKIE, 'authenticated', {
+    signed: true,
+    httpOnly: true,
+    maxAge: COOKIE_MAX_AGE,
+    sameSite: 'lax'
+  });
+  res.redirect('/ui');
+});
+
+// Logout
+router.post('/logout', (req, res) => {
+  res.clearCookie(AUTH_COOKIE);
+  res.redirect('/ui/login');
+});
+
+// Password setup page (first time only)
+router.get('/setup-password', (req, res) => {
+  if (hasAdminPassword()) {
+    return res.redirect('/ui/login');
+  }
+  res.send(renderSetupPasswordPage());
+});
+
+// Handle password setup
+router.post('/setup-password', async (req, res) => {
+  if (hasAdminPassword()) {
+    return res.redirect('/ui/login');
+  }
+
+  const { password, confirmPassword } = req.body;
+  if (!password || password.length < 4) {
+    return res.send(renderSetupPasswordPage('Password must be at least 4 characters'));
+  }
+  if (password !== confirmPassword) {
+    return res.send(renderSetupPasswordPage('Passwords do not match'));
+  }
+
+  await setAdminPassword(password);
+
+  res.cookie(AUTH_COOKIE, 'authenticated', {
+    signed: true,
+    httpOnly: true,
+    maxAge: COOKIE_MAX_AGE,
+    sameSite: 'lax'
+  });
+  res.redirect('/ui');
+});
+
+// Render functions
+function renderLoginPage(error = '') {
+  return `${htmlHead('Login')}
+<body>
+  <div style="max-width: 400px; margin: 100px auto;">
+    <div style="display: flex; align-items: center; gap: 12px; margin-bottom: 24px;">
+      <img src="/public/favicon.svg" alt="agentgate" style="height: 48px;">
+      <h1 style="margin: 0;">agentgate</h1>
+    </div>
+    <div class="card">
+      <h2 style="margin-top: 0;">Login</h2>
+      ${error ? `<div class="error">${error}</div>` : ''}
+      <form method="POST" action="/ui/login">
+        <label>Password</label>
+        <input type="password" name="password" required autofocus>
+        <button type="submit" class="btn-primary" style="width: 100%;">Login</button>
+      </form>
+    </div>
+  </div>
+</body>
+</html>`;
+}
+
+function renderSetupPasswordPage(error = '') {
+  return `${htmlHead('Setup')}
+<body>
+  <div style="max-width: 400px; margin: 100px auto;">
+    <div style="display: flex; align-items: center; gap: 12px; margin-bottom: 24px;">
+      <img src="/public/favicon.svg" alt="agentgate" style="height: 48px;">
+      <h1 style="margin: 0;">agentgate</h1>
+    </div>
+    <div class="card">
+      <h2 style="margin-top: 0;">Set Admin Password</h2>
+      <p class="help">This is your first time running agentgate. Please set an admin password.</p>
+      ${error ? `<div class="error">${error}</div>` : ''}
+      <form method="POST" action="/ui/setup-password">
+        <label>Password</label>
+        <input type="password" name="password" required autofocus minlength="4">
+        <label>Confirm Password</label>
+        <input type="password" name="confirmPassword" required minlength="4">
+        <button type="submit" class="btn-primary" style="width: 100%;">Set Password</button>
+      </form>
+    </div>
+  </div>
+</body>
+</html>`;
+}
+
+export default router;