agentxchain 2.155.23 → 2.155.24

package/README.md

@@ -205,7 +205,7 @@ Partial coordinator artifacts are first-class here too: `audit` and `report` kee
 | `multi init\|status\|step\|resume\|approve-gate\|resync` | Run the multi-repo coordinator lifecycle, including blocked-state recovery via `multi resume` |
 | `intake record\|triage\|approve\|plan\|start\|scan\|resolve` | Continuous-delivery intake: turn delivery signals into governed work items |
 | `intake handoff` | Bridge a planned intake intent to a coordinator workstream for multi-repo execution |
-| `watch --event-file\|--event-dir\|--results\|--result` | Normalize external events into governed intake, poll event-file directories, and inspect durable watch result records |
+| `watch --event-file\|--event-dir\|--listen\|--results\|--result` | Normalize external events into governed intake, poll event-file directories, receive signed HTTP webhooks, and inspect durable watch result records |
 | `schedule list\|run-due\|daemon\|status` | Run repo-local lights-out scheduling: inspect schedules, execute due runs, poll in a local daemon loop, continue explicitly unblocked schedule-owned runs, or check daemon heartbeat |
 | `plugin install\|list\|remove` | Install, inspect, or remove governed hook plugins under `.agentxchain/plugins/` |
 | `plugin list-available` | List bundled built-in plugins installable by short name |

package/bin/agentxchain.js

@@ -254,6 +254,10 @@ program
   .option('--event-dir <path>', 'Poll a directory for external event JSON files')
   .option('--poll-seconds <seconds>', 'With --event-dir, polling interval in seconds', '5')
   .option('--dry-run', 'With --event-file, print the normalized intake payload without writing')
+  .option('--listen <port>', 'Start an HTTP webhook listener on the given port')
+  .option('--listen-host <host>', 'With --listen, bind to a specific host (default: 127.0.0.1)')
+  .option('--webhook-secret <secret>', 'With --listen, HMAC-SHA256 secret for signature verification')
+  .option('--allow-unsigned', 'With --listen, accept unsigned payloads (local dev only)')
   .option('--results', 'List all watch result records')
   .option('--result <id>', 'Show a single watch result by ID or filename')
   .option('--limit <n>', 'With --results, limit the number of results shown')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.155.23",
+  "version": "2.155.24",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/watch.js

@@ -11,6 +11,7 @@ import { notifyHuman as sendNotification } from '../lib/notify.js';
 import { validateProject } from '../lib/validation.js';
 import { resolveNextAgent, resolveExpectedClaimer } from '../lib/next-owner.js';
 import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
+import { startWebhookListener } from '../lib/watch-listener.js';
 
 const PID_FILE = '.agentxchain-watch.pid';
 
@@ -20,6 +21,11 @@ export async function watchCommand(opts) {
     return;
   }
 
+  if (opts.listen) {
+    await listenWebhook(opts);
+    return;
+  }
+
   if (opts.eventFile) {
     await ingestWatchEvent(opts);
     return;
@@ -311,6 +317,99 @@ function parsePollMs(value) {
   return Math.max(100, Math.round(seconds * 1000));
 }
 
+async function listenWebhook(opts) {
+  // Mutual exclusion checks
+  const incompatible = [
+    opts.eventFile && '--event-file',
+    opts.eventDir && '--event-dir',
+    opts.daemon && '--daemon',
+    (opts.results || opts.result) && '--results/--result',
+  ].filter(Boolean);
+
+  if (incompatible.length > 0) {
+    const message = `--listen cannot be combined with ${incompatible.join(', ')}`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.log(chalk.red(`  ${message}`));
+    }
+    process.exit(1);
+  }
+
+  const root = requireIntakeWorkspaceOrExit(opts);
+  const port = parseInt(opts.listen, 10);
+  if (!Number.isFinite(port) || port < 1 || port > 65535) {
+    const message = `invalid port: ${opts.listen}`;
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.log(chalk.red(`  ${message}`));
+    }
+    process.exit(1);
+  }
+
+  // Resolve webhook secret: CLI flag > env var > config
+  let secret = opts.webhookSecret || null;
+  if (!secret && process.env.AGENTXCHAIN_WEBHOOK_SECRET) {
+    secret = process.env.AGENTXCHAIN_WEBHOOK_SECRET;
+  }
+  if (!secret) {
+    try {
+      const rawConfig = JSON.parse(readFileSync(join(root, 'agentxchain.json'), 'utf8'));
+      secret = rawConfig?.watch?.webhook_secret || null;
+    } catch {}
+  }
+
+  const allowUnsigned = opts.allowUnsigned === true;
+  const host = opts.listenHost || '127.0.0.1';
+
+  try {
+    const server = await startWebhookListener({
+      root,
+      port,
+      host,
+      secret,
+      allowUnsigned,
+      dryRun: opts.dryRun === true,
+      onReady: ({ port: boundPort, host: boundHost }) => {
+        writePidFile(root);
+        console.log('');
+        console.log(chalk.bold('  AgentXchain Webhook Listener'));
+        console.log(chalk.dim(`  Listening: http://${boundHost}:${boundPort}`));
+        console.log(chalk.dim(`  Webhook:   POST /webhook`));
+        console.log(chalk.dim(`  Health:    GET  /health`));
+        console.log(chalk.dim(`  Secret:    ${secret ? 'configured' : allowUnsigned ? 'none (unsigned allowed)' : 'REQUIRED but missing — POST /webhook will return 403'}`));
+        if (opts.dryRun) console.log(chalk.yellow('  Dry-run:   events will NOT be persisted'));
+        console.log('');
+        console.log(chalk.cyan('  Waiting for webhook deliveries... (Ctrl+C to stop)'));
+        console.log('');
+      },
+    });
+
+    const cleanup = () => {
+      server.close();
+      removePidFile(root);
+      console.log('');
+      log('stop', 'Webhook listener stopped.');
+      process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      const message = `port ${port} is already in use`;
+      if (opts.json) {
+        console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+      } else {
+        console.log(chalk.red(`  ${message}`));
+      }
+    } else {
+      console.log(chalk.red(`  failed to start listener: ${err.message}`));
+    }
+    process.exit(1);
+  }
+}
+
 async function ingestWatchEvent(opts) {
   if (opts.daemon) {
     const message = '--daemon cannot be combined with --event-file';

package/src/lib/watch-events.js

@@ -253,7 +253,7 @@ export function resolveWatchRoute(payload, routes) {
  * @param {object} payload - the normalized watch event payload
  * @returns {{ result_id: string, result_path: string }}
  */
-export function writeWatchResult(root, pipelineResult, payload) {
+export function writeWatchResult(root, pipelineResult, payload, metadata = {}) {
   const ts = Date.now();
   const suffix = Math.random().toString(16).slice(2, 10);
   const resultId = `wr_${ts}_${suffix}`;
@@ -271,6 +271,7 @@ export function writeWatchResult(root, pipelineResult, payload) {
     intent_id: pipelineResult.intent?.intent_id || null,
     intent_status: pipelineResult.intent?.status || null,
     deduplicated: pipelineResult.deduplicated === true,
+    delivery_id: metadata.delivery_id || null,
     payload: {
       source: payload.source,
       category: payload.category,

package/src/lib/watch-listener.js

@@ -0,0 +1,297 @@
+import { createServer } from 'http';
+import { createHmac, timingSafeEqual } from 'crypto';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { recordEvent, triageIntent, approveIntent, planIntent, startIntent } from './intake.js';
+import { normalizeWatchEvent, resolveWatchRoute, writeWatchResult } from './watch-events.js';
+
+const MAX_BODY_BYTES = 1_048_576; // 1 MB
+
+/**
+ * Start an HTTP webhook listener that feeds events through the governed intake pipeline.
+ *
+ * @param {object} opts
+ * @param {string} opts.root - project root
+ * @param {number} opts.port - port to bind
+ * @param {string} [opts.host='127.0.0.1'] - host to bind
+ * @param {string|null} [opts.secret=null] - HMAC-SHA256 webhook secret
+ * @param {boolean} [opts.allowUnsigned=false] - accept unsigned payloads
+ * @param {boolean} [opts.dryRun=false] - normalize only, do not persist
+ * @param {Function} [opts.onReady] - called with { port, host } when listening
+ * @returns {Promise<import('http').Server>}
+ */
+export function startWebhookListener(opts) {
+  const { root, port, host = '127.0.0.1', secret = null, allowUnsigned = false, dryRun = false, onReady } = opts;
+  const startedAt = Date.now();
+  let eventsProcessed = 0;
+
+  let version = 'unknown';
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'node_modules', 'agentxchain', 'package.json'), 'utf8'));
+    version = pkg.version;
+  } catch {
+    try {
+      // Fallback: try the CLI's own package.json
+      const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+      version = pkg.version;
+    } catch {}
+  }
+
+  const server = createServer(async (req, res) => {
+    try {
+      // Health endpoint
+      if (req.method === 'GET' && req.url === '/health') {
+        writeJson(res, 200, {
+          ok: true,
+          version,
+          uptime_ms: Date.now() - startedAt,
+          events_processed: eventsProcessed,
+        });
+        return;
+      }
+
+      // Webhook endpoint
+      if (req.method === 'POST' && req.url === '/webhook') {
+        const outcome = await handleWebhook(req, res, { root, secret, allowUnsigned, dryRun, startedAt });
+        if (outcome?.counted) eventsProcessed++;
+        return;
+      }
+
+      // Method not allowed on known paths
+      if (req.url === '/webhook' || req.url === '/health') {
+        writeJson(res, 405, { ok: false, error: 'method not allowed' });
+        return;
+      }
+
+      // Not found
+      writeJson(res, 404, { ok: false, error: 'not found' });
+    } catch (err) {
+      writeJson(res, 500, { ok: false, error: 'internal error' });
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, host, () => {
+      server.removeListener('error', reject);
+      if (onReady) onReady({ port, host });
+      resolve(server);
+    });
+  });
+}
+
+async function handleWebhook(req, res, ctx) {
+  const { root, secret, allowUnsigned, dryRun } = ctx;
+
+  // Content-Type check
+  const contentType = req.headers['content-type'] || '';
+  if (!contentType.includes('application/json')) {
+    writeJson(res, 415, { ok: false, error: 'content type must be application/json' });
+    return { counted: false };
+  }
+
+  // Read body with size limit
+  let rawBody;
+  try {
+    rawBody = await readBody(req, MAX_BODY_BYTES);
+  } catch (err) {
+    if (err.message === 'payload too large') {
+      writeJson(res, 413, { ok: false, error: 'payload too large' });
+      return { counted: false };
+    }
+    writeJson(res, 400, { ok: false, error: err.message });
+    return { counted: false };
+  }
+
+  // Signature verification
+  if (secret) {
+    const sigHeader = req.headers['x-hub-signature-256'];
+    if (!sigHeader) {
+      writeJson(res, 401, { ok: false, error: 'signature verification failed' });
+      return { counted: false };
+    }
+    const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+    if (!constantTimeEqual(expected, sigHeader)) {
+      writeJson(res, 401, { ok: false, error: 'signature verification failed' });
+      return { counted: false };
+    }
+  } else if (!allowUnsigned) {
+    writeJson(res, 403, { ok: false, error: 'webhook secret required' });
+    return { counted: false };
+  }
+
+  // Parse JSON
+  let parsed;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    writeJson(res, 400, { ok: false, error: 'invalid JSON' });
+    return { counted: false };
+  }
+
+  // Construct envelope using X-GitHub-Event header if present
+  const githubEvent = req.headers['x-github-event'];
+  const deliveryId = req.headers['x-github-delivery'] || null;
+  let envelope;
+  if (parsed.provider && parsed.event) {
+    // Already enveloped
+    envelope = parsed;
+  } else if (githubEvent) {
+    envelope = { provider: 'github', event: githubEvent, ...parsed };
+  } else {
+    envelope = parsed;
+  }
+
+  // Normalize
+  let payload;
+  try {
+    payload = normalizeWatchEvent(envelope);
+  } catch (err) {
+    writeJson(res, 422, { ok: false, error: err.message });
+    return { counted: false };
+  }
+
+  // Dry-run: return normalized payload without persisting
+  if (dryRun) {
+    writeJson(res, 200, { ok: true, dry_run: true, payload });
+    return { counted: true };
+  }
+
+  // Record event through the governed intake pipeline
+  const result = recordEvent(root, payload);
+  if (!result.ok) {
+    writeJson(res, 422, { ok: false, error: result.error || 'event recording failed' });
+    return { counted: false };
+  }
+
+  // Route-based auto-triage and auto-approve (same logic as ingestWatchEvent)
+  let routed = null;
+  if (!result.deduplicated && result.intent) {
+    let routes;
+    try {
+      const rawConfig = JSON.parse(readFileSync(join(root, 'agentxchain.json'), 'utf8'));
+      routes = rawConfig?.watch?.routes;
+    } catch {}
+
+    const resolved = resolveWatchRoute(payload, routes);
+    if (resolved) {
+      const triageFields = { ...resolved.triage };
+      if (resolved.preferred_role) triageFields.preferred_role = resolved.preferred_role;
+
+      const triageResult = triageIntent(root, result.intent.intent_id, triageFields);
+      if (triageResult.ok) {
+        result.intent = triageResult.intent;
+        routed = { triaged: true, approved: false, preferred_role: resolved.preferred_role };
+
+        if (resolved.auto_approve) {
+          const approveResult = approveIntent(root, result.intent.intent_id, {
+            approver: 'watch_route',
+            reason: `auto-approved by watch route matching ${payload.category}`,
+          });
+          if (approveResult.ok) {
+            result.intent = approveResult.intent;
+            routed.approved = true;
+
+            if (resolved.auto_start) {
+              const planResult = planIntent(root, result.intent.intent_id, {
+                force: resolved.overwrite_planning_artifacts === true,
+              });
+              if (planResult.ok) {
+                result.intent = planResult.intent;
+                routed.planned = true;
+                const startResult = startIntent(root, result.intent.intent_id, {});
+                if (startResult.ok) {
+                  result.intent = startResult.intent;
+                  routed.started = true;
+                  routed.run_id = startResult.run_id || null;
+                  routed.role = startResult.role || null;
+                } else {
+                  routed.started = false;
+                  routed.auto_start_error = startResult.error;
+                }
+              } else {
+                routed.planned = false;
+                routed.started = false;
+                routed.auto_start_error = planResult.error;
+              }
+            }
+          }
+        } else if (resolved.auto_start) {
+          routed.auto_start_skipped = 'requires auto_approve';
+        }
+      }
+    }
+  }
+
+  if (routed) result.routed = routed;
+
+  // Write durable watch result
+  const watchResult = writeWatchResult(root, result, payload, { delivery_id: deliveryId });
+
+  // Build response
+  const response = {
+    ok: true,
+    result_id: watchResult.result_id,
+    event_id: result.event?.event_id || null,
+    intent_id: result.intent?.intent_id || null,
+    intent_status: result.intent?.status || null,
+    deduplicated: result.deduplicated === true,
+    delivery_id: deliveryId,
+    route: routed
+      ? {
+          matched: true,
+          triaged: routed.triaged === true,
+          approved: routed.approved === true,
+          planned: routed.planned === true,
+          started: routed.started === true,
+          preferred_role: routed.preferred_role || null,
+          run_id: routed.run_id || null,
+          role: routed.role || null,
+        }
+      : { matched: false },
+  };
+
+  writeJson(res, 200, response);
+  return { counted: true };
+}
+
+function readBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let rejected = false;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > maxBytes && !rejected) {
+        rejected = true;
+        reject(new Error('payload too large'));
+        // Resume to drain remaining data so the response can be sent
+        req.resume();
+        return;
+      }
+      if (!rejected) chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (!rejected) resolve(Buffer.concat(chunks));
+    });
+    req.on('error', (err) => {
+      if (!rejected) reject(err);
+    });
+  });
+}
+
+function constantTimeEqual(a, b) {
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+
+function writeJson(res, statusCode, payload) {
+  if (res.writableEnded) return;
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-cache',
+  });
+  res.end(JSON.stringify(payload));
+}