amalgm 0.1.51 → 0.1.53

package/runtime/scripts/amalgm-mcp/browser/tools.js

@@ -1,6 +1,6 @@
 /**
- * Browser MCP tools. In desktop local mode they drive Amalgm's visible
- * Electron browser surface; elsewhere they fall back to Playwright.
+ * Browser MCP tools. In the desktop app they drive Amalgm's visible
+ * Electron browser surface; elsewhere they fall back to agent-browser.
  */
 
 const { textResult, errorResult } = require('../lib/tool-result');
@@ -39,6 +39,7 @@ const tabTargetProperties = {
 
 const locatorProperties = {
   ...tabTargetProperties,
+  ref: { type: 'string', description: 'Snapshot ref such as @e1' },
   selector: { type: 'string', description: 'CSS selector for the target element' },
   text: { type: 'string', description: 'Visible text to match' },
   role: { type: 'string', description: 'ARIA role, e.g. button, link, textbox' },
@@ -224,7 +225,7 @@ module.exports = [
       type: 'object',
       properties: {
         ...tabTargetProperties,
-        full_page: { type: 'boolean', description: 'Capture the full scrollable page (Playwright fallback only; Electron captures viewport)' },
+        full_page: { type: 'boolean', description: 'Capture the full scrollable page' },
       },
     },
     async handler(args, ctx) {
@@ -261,8 +262,8 @@ module.exports = [
     description: 'Click an element by selector, text, role/name, label, placeholder, or testId.',
     inputSchema: { type: 'object', properties: locatorProperties },
     async handler(args, ctx) {
-      if (!args.selector && !args.text && !args.role && !args.label && !args.placeholder && !args.testId && !args.name) {
-        return errorResult('A selector, text, role, label, placeholder, testId, or name is required');
+      if (!args.ref && !args.selector && !args.text && !args.role && !args.label && !args.placeholder && !args.testId && !args.name) {
+        return errorResult('A ref, selector, text, role, label, placeholder, testId, or name is required');
       }
       try {
         const result = await clickBrowser(args, ctx);
@@ -320,6 +321,7 @@ module.exports = [
       type: 'object',
       properties: {
         ...tabTargetProperties,
+        ref: { type: 'string', description: 'Snapshot ref such as @e1' },
         selector: { type: 'string', description: 'CSS selector to extract (omit for full page)' },
       },
     },
@@ -482,7 +484,7 @@ module.exports = [
   },
   {
     name: 'browser_cua_move',
-    description: 'Move the visible automation cursor to viewport coordinates.',
+    description: 'Move the browser mouse to viewport coordinates.',
     inputSchema: {
       type: 'object',
       properties: { ...tabTargetProperties, x: { type: 'number' }, y: { type: 'number' }, keys: { type: 'array', items: { type: 'string' } } },
@@ -625,7 +627,7 @@ module.exports = [
   },
   {
     name: 'browser_start_video',
-    description: 'Start recording the visible browser session to a local WebM video. Saved when browser_stop_video is called.',
+    description: 'Start recording the browser session to a local WebM video. Saved when browser_stop_video is called.',
     inputSchema: {
       type: 'object',
       properties: {

package/runtime/scripts/amalgm-mcp/config.js

@@ -8,15 +8,8 @@
 
 const path = require('path');
 const os = require('os');
-const fs = require('fs');
-const {
-  DEFAULT_PROXY_BASE_URL,
-  proxyBaseUrl,
-  readProxyToken,
-} = require('../proxy-token-store');
-const { runtimePort } = require('../../lib/runtime-manifest');
 
-const PORT = runtimePort('amalgm-mcp');
+const PORT = parseInt(process.env.AMALGM_MCP_PORT || '8083', 10);
 const MCP_PROTOCOL_VERSION = '2024-11-05';
 
 const AMALGM_DIR = process.env.AMALGM_DIR || path.join(os.homedir(), '.amalgm');
@@ -26,30 +19,20 @@ const STORAGE_DIR = AMALGM_DIR; // tasks.json etc. live directly under ~/.amalgm
 const LOCAL_DB_FILE = path.join(STORAGE_DIR, 'amalgm.db');
 const TASKS_FILE = path.join(STORAGE_DIR, 'tasks.json');
 const AGENTS_FILE = path.join(STORAGE_DIR, 'agents.json');
-const ARTIFACTS_DIR = path.join(STORAGE_DIR, 'artifacts');
-const ARTIFACTS_FILE = path.join(STORAGE_DIR, 'artifacts.json');
+const APPS_DIR = path.join(STORAGE_DIR, 'apps');
+const APPS_FILE = path.join(STORAGE_DIR, 'apps.json');
+const LEGACY_ARTIFACTS_DIR = path.join(STORAGE_DIR, 'artifacts');
+const LEGACY_ARTIFACTS_FILE = path.join(STORAGE_DIR, 'artifacts.json');
 const COMPUTER_RECORD_FILE = path.join(STORAGE_DIR, 'computer.json');
-const COMPUTER_AUTH_FILE = path.join(STORAGE_DIR, 'auth.json');
 const TASK_RUNS_DIR = path.join(STORAGE_DIR, 'task-runs');
 const EVENT_TRIGGERS_FILE = path.join(STORAGE_DIR, 'event-triggers.json');
+const WORKFLOWS_FILE = path.join(STORAGE_DIR, 'workflows.json');
 const AGENT_CONVOS_DIR = path.join(STORAGE_DIR, 'agent-convos');
 
-function readJson(file) {
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-function cleanString(value) {
-  return typeof value === 'string' && value.trim() ? value.trim() : '';
-}
-
 // Chat server (local Next.js/Electron) — same process tree; no cloud hop.
-const CHAT_SERVER_URL = `http://localhost:${runtimePort('chat-server')}`;
+const CHAT_SERVER_URL = `http://localhost:${process.env.CHAT_SERVER_PORT || 8084}`;
 
-const SCHEDULER_INTERVAL_MS = 60_000;
+const SCHEDULER_INTERVAL_MS = 30_000;
 
 // Default working directory for automated runs (was /workspace in the container).
 const DEFAULT_CWD = process.env.AMALGM_DEFAULT_CWD || os.homedir();
@@ -58,19 +41,13 @@ const DEFAULT_CWD = process.env.AMALGM_DEFAULT_CWD || os.homedir();
 // Sensitive provider keys live on the Fly.io api-proxy. When running locally
 // without signing in, none of this is configured and hasSupabase() returns false.
 
-const savedComputerRecord = readJson(COMPUTER_RECORD_FILE) || {};
-const savedComputerAuth = readJson(COMPUTER_AUTH_FILE) || {};
-const AMALGM_USER_ID = cleanString(process.env.AMALGM_USER_ID)
-  || cleanString(savedComputerRecord.user_id)
-  || cleanString(savedComputerAuth.user_id);
-const AMALGM_COMPUTER_ID = cleanString(process.env.AMALGM_COMPUTER_ID)
-  || cleanString(savedComputerRecord.computer_id)
-  || cleanString(savedComputerAuth.computer_id)
-  || cleanString(process.env.AMALGM_CONTAINER_ID);
+const AMALGM_USER_ID = process.env.AMALGM_USER_ID || '';
+const AMALGM_COMPUTER_ID = process.env.AMALGM_COMPUTER_ID || process.env.AMALGM_CONTAINER_ID || '';
 
-const PROXY_TOKEN = readProxyToken()
+const PROXY_TOKEN = process.env.AMALGM_PROXY_TOKEN
   || (process.env.AMALGM_RUNTIME_SOURCE === 'npm' ? '' : process.env.ANTHROPIC_API_KEY || '');
-const PROXY_BASE_URL = proxyBaseUrl() || (PROXY_TOKEN ? DEFAULT_PROXY_BASE_URL : '');
+const DEFAULT_PROXY_BASE_URL = 'https://amalgm-api-proxy-v2.fly.dev';
+const PROXY_BASE_URL = process.env.AMALGM_PROXY_URL || (PROXY_TOKEN ? DEFAULT_PROXY_BASE_URL : '');
 const SUPABASE_PROXY_URL = PROXY_BASE_URL ? `${PROXY_BASE_URL}/supabase` : '';
 
 const SUPABASE_URL_DIRECT =
@@ -89,9 +66,15 @@ const SUPABASE_AUTH_HEADERS = SUPABASE_PROXY_URL
 const EVENTS_PUBLIC_URL =
   process.env.AMALGM_EVENTS_PUBLIC_URL || `http://localhost:${PORT}/events`;
 
-const ARTIFACTS_DOMAIN = process.env.AMALGM_ARTIFACTS_DOMAIN || 'artifacts.amalgm.ai';
-const ARTIFACT_PORT_MIN = parseInt(process.env.AMALGM_ARTIFACT_PORT_MIN || '9100', 10);
-const ARTIFACT_PORT_MAX = parseInt(process.env.AMALGM_ARTIFACT_PORT_MAX || '9199', 10);
+const APPS_DOMAIN = (
+  process.env.AMALGM_APPS_DOMAIN
+  || process.env.NEXT_PUBLIC_APPS_DOMAIN
+  || process.env.AMALGM_ARTIFACTS_DOMAIN
+  || process.env.NEXT_PUBLIC_ARTIFACTS_DOMAIN
+  || 'apps.amalgm.ai'
+);
+const APP_PORT_MIN = parseInt(process.env.AMALGM_APP_PORT_MIN || process.env.AMALGM_ARTIFACT_PORT_MIN || '9100', 10);
+const APP_PORT_MAX = parseInt(process.env.AMALGM_APP_PORT_MAX || process.env.AMALGM_ARTIFACT_PORT_MAX || '9199', 10);
 const GATEWAY_BASE_URL = (
   process.env.AMALGM_GATEWAY_INTERNAL_URL
   || process.env.AMALGM_GATEWAY_URL
@@ -102,8 +85,8 @@ const GATEWAY_INTERNAL_SECRET =
   || process.env.PROXY_ADMIN_SECRET
   || process.env.ADMIN_SECRET
   || '';
-const ARTIFACT_ROUTE_SYNC_INTERVAL_MS = parseInt(
-  process.env.AMALGM_ARTIFACT_ROUTE_SYNC_INTERVAL_MS || '30000',
+const APP_ROUTE_SYNC_INTERVAL_MS = parseInt(
+  process.env.AMALGM_APP_ROUTE_SYNC_INTERVAL_MS || process.env.AMALGM_ARTIFACT_ROUTE_SYNC_INTERVAL_MS || '30000',
   10,
 );
 
@@ -115,12 +98,14 @@ module.exports = {
   LOCAL_DB_FILE,
   TASKS_FILE,
   AGENTS_FILE,
-  ARTIFACTS_DIR,
-  ARTIFACTS_FILE,
+  APPS_DIR,
+  APPS_FILE,
+  LEGACY_ARTIFACTS_DIR,
+  LEGACY_ARTIFACTS_FILE,
   COMPUTER_RECORD_FILE,
-  COMPUTER_AUTH_FILE,
   TASK_RUNS_DIR,
   EVENT_TRIGGERS_FILE,
+  WORKFLOWS_FILE,
   AGENT_CONVOS_DIR,
   CHAT_SERVER_URL,
   SCHEDULER_INTERVAL_MS,
@@ -132,10 +117,10 @@ module.exports = {
   SUPABASE_URL,
   SUPABASE_AUTH_HEADERS,
   EVENTS_PUBLIC_URL,
-  ARTIFACTS_DOMAIN,
-  ARTIFACT_PORT_MIN,
-  ARTIFACT_PORT_MAX,
+  APPS_DOMAIN,
+  APP_PORT_MIN,
+  APP_PORT_MAX,
   GATEWAY_BASE_URL,
   GATEWAY_INTERNAL_SECRET,
-  ARTIFACT_ROUTE_SYNC_INTERVAL_MS,
+  APP_ROUTE_SYNC_INTERVAL_MS,
 };

package/runtime/scripts/amalgm-mcp/deps.js

@@ -1,15 +1,3 @@
-/**
- * Deps — resolves optional native deps (cron-parser, playwright).
- *
- * The container-era code looked in /opt/amalgm-mcp-dep/ first and then the
- * global require path. Locally we only need the global require path — these
- * are npm deps of the main repo.
- *
- * Playwright is lazy: we don't require() it until a browser_* tool is called.
- * This keeps boot fast and lets the MCP server run on machines that haven't
- * run `npx playwright install chromium` yet.
- */
-
 function loadCronParser() {
   try {
     return require('cron-parser');
@@ -19,22 +7,4 @@ function loadCronParser() {
   }
 }
 
-let _playwrightMod = null;
-
-function loadPlaywright() {
-  if (_playwrightMod) return _playwrightMod;
-  for (const mod of ['playwright', 'playwright-core']) {
-    try {
-      _playwrightMod = require(mod);
-      console.log(`[AmalgmMCP] Loaded Playwright from: ${mod}`);
-      return _playwrightMod;
-    } catch {
-      // Try next candidate.
-    }
-  }
-  throw new Error(
-    'Playwright is not installed. Run: npm install playwright && npx playwright install chromium',
-  );
-}
-
-module.exports = { loadCronParser, loadPlaywright };
+module.exports = { loadCronParser };

package/runtime/scripts/amalgm-mcp/events/ingress.js

@@ -1,19 +1,20 @@
 /**
  * /events — webhook ingress.
  *
- * Accepts raw POST body, requires a verified signature, and on a hit fires an
- * agent run via events/executor.js and returns 200 with
+ * Accepts raw POST body, requires a verified signature, and on a hit fires a
+ * automation workflow run via automations/runner.js and returns 200 with
  * `{ ok, event, triggered }`.
  */
 
 const {
   extractSignature,
+  matchAllBySignature,
   matchBySignature,
   pickSourceLabel,
   collectPassthroughHeaders,
 } = require('./matcher');
-const { loadEventTriggers, saveEventTriggers } = require('./store');
-const { executeArtifactEvent } = require('./executor');
+const { listEventTriggersForIngress, markTriggerFired } = require('../automations/store');
+const { executeAutomationForTrigger } = require('../automations/runner');
 const ring = require('./ring-buffer');
 
 /**
@@ -44,20 +45,37 @@ async function handleEventsPost(req, sendJson) {
     return sendJson(401, { error: 'Webhook signature required' });
   }
 
-  const triggerData = loadEventTriggers();
-  const matchedTrigger = matchBySignature(triggerData.triggers, signature, rawBody);
-  if (!matchedTrigger) {
-    console.warn('[AmalgmMCP:Events] No trigger matched the webhook signature');
-    return sendJson(401, { error: 'Invalid webhook signature — no matching trigger' });
-  }
-
+  const triggers = listEventTriggersForIngress();
   const githubEvent = req.headers['x-github-event'];
+  const eventSource = pickSourceLabel(req.headers);
+  const eventName =
+    githubEvent ||
+    req.headers['x-linear-event'] ||
+    req.headers['x-gitlab-event'] ||
+    'webhook';
+
   // GitHub webhook handshake: acknowledge verified ping events immediately.
   if (githubEvent === 'ping') {
+    const pingTrigger = matchBySignature(triggers, signature, rawBody);
+    if (!pingTrigger) {
+      console.warn('[AmalgmMCP:Events] No trigger matched the GitHub ping signature');
+      return sendJson(401, { error: 'Invalid webhook signature — no matching trigger' });
+    }
     console.log('[AmalgmMCP:Events] GitHub ping — pong');
     return sendJson(200, { ok: true, message: 'pong' });
   }
 
+  const matchedTriggers = matchAllBySignature(
+    triggers,
+    signature,
+    rawBody,
+    { source: eventSource, event: eventName },
+  );
+  if (!matchedTriggers?.length) {
+    console.warn(`[AmalgmMCP:Events] No trigger matched ${eventSource}.${eventName}`);
+    return sendJson(401, { error: 'Invalid webhook signature or source/event — no matching trigger' });
+  }
+
   const eventHeaders = collectPassthroughHeaders(req.headers);
 
   let parsedBody;
@@ -67,47 +85,37 @@ async function handleEventsPost(req, sendJson) {
     parsedBody = rawBody;
   }
 
-  console.log(`[AmalgmMCP:Events] Matched trigger "${matchedTrigger.name}" (${matchedTrigger.id})`);
+  console.log(
+    `[AmalgmMCP:Events] Matched ${matchedTriggers.length} trigger(s) for ${eventSource}.${eventName}`,
+  );
 
   const eventObj = {
-    source: pickSourceLabel(req.headers),
-    event:
-      githubEvent ||
-      req.headers['x-linear-event'] ||
-      req.headers['x-gitlab-event'] ||
-      'webhook',
+    source: eventSource,
+    event: eventName,
     payload: parsedBody,
     headers: eventHeaders,
     timestamp: new Date().toISOString(),
   };
   ring.push(eventObj);
 
-  const eventDef = {
-    name: matchedTrigger.name,
-    description: matchedTrigger.name,
-    agent_prompt: matchedTrigger.agent_prompt,
-    harness: matchedTrigger.harness,
-    model: matchedTrigger.model,
-    authMethod: matchedTrigger.authMethod,
-    chatInput: matchedTrigger.chatInput,
-  };
-  const syntheticArtifact = { id: matchedTrigger.id, name: matchedTrigger.name };
-  const fullPayload = { body: parsedBody, headers: eventHeaders };
-
-  executeArtifactEvent(syntheticArtifact, eventDef, fullPayload, {
-    triggerId: matchedTrigger.id,
-    projectPath: matchedTrigger.projectPath,
-  }).catch((err) => {
-    console.error(
-      `[AmalgmMCP:Events] Trigger agent run failed for "${matchedTrigger.name}":`,
-      err.message,
-    );
-  });
+  for (const matchedTrigger of matchedTriggers) {
+    executeAutomationForTrigger(matchedTrigger.id, eventObj).catch((err) => {
+      console.error(
+        `[AmalgmMCP:Events] Automation workflow failed for trigger "${matchedTrigger.name}":`,
+        err.message,
+      );
+    });
 
-  matchedTrigger.lastFiredAt = new Date().toISOString();
-  saveEventTriggers(triggerData);
+    markTriggerFired(matchedTrigger.id, { source: 'events:ingress' });
+  }
 
-  return sendJson(200, { ok: true, event: eventObj, triggered: true });
+  return sendJson(200, {
+    ok: true,
+    event: eventObj,
+    triggered: true,
+    triggerCount: matchedTriggers.length,
+    triggerIds: matchedTriggers.map((trigger) => trigger.id),
+  });
 }
 
 module.exports = { handleEventsPost };

package/runtime/scripts/amalgm-mcp/events/internal-workflows.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function findEngineRepoPath() {
+  const explicit = process.env.AMALGM_ENGINE_REPO_PATH;
+  if (explicit && fs.existsSync(path.join(explicit, 'packages', 'amalgm', 'package.json'))) {
+    return explicit;
+  }
+
+  const candidate = path.resolve(__dirname, '../../../..');
+  if (fs.existsSync(path.join(candidate, 'packages', 'amalgm', 'package.json'))) {
+    return candidate;
+  }
+
+  return null;
+}
+
+function engineNpmPublishWorkflow(repoPath) {
+  const escapedRepoPath = JSON.stringify(repoPath);
+  const repoUrl = process.env.AMALGM_ENGINE_REPO_URL || 'https://github.com/amalgm-inc/amalgm-engine.git';
+  const cloneLine = JSON.stringify(`  git clone ${repoUrl} .`);
+  return `export default workflow({
+  trigger: event("github.push"),
+
+  allowlist: {
+    localCompute: true,
+    secrets: ["NODE_AUTH_TOKEN"],
+    actions: ["amalgm.notify_user"]
+  },
+
+  limits: {
+    maxConcurrentRuns: 1,
+    queueLimit: 5,
+    cellTimeoutMs: 600000
+  },
+
+  cells: [
+    code("filter_push", async ({ event, stop }) => {
+      const payload = event.payload
+      if (payload.ref !== "refs/heads/main") stop()
+
+      const commits = Array.isArray(payload.commits) ? payload.commits : []
+      const changed = Array.from(new Set([
+        ...(payload.head_commit?.added || []),
+        ...(payload.head_commit?.modified || []),
+        ...(payload.head_commit?.removed || []),
+        ...commits.flatMap((commit) => [
+          ...(commit.added || []),
+          ...(commit.modified || []),
+          ...(commit.removed || [])
+        ])
+      ]))
+
+      const relevant = changed.some((file) =>
+        file.startsWith("packages/amalgm/") ||
+        file.startsWith("runtime/") ||
+        file === "scripts/sync-npm-package-runtime.mjs"
+      )
+
+      if (!relevant) stop()
+
+      return {
+        sha: payload.after,
+        ref: payload.ref,
+        files: changed
+      }
+    }),
+
+    cli("update_repo", {
+      cwd: ${escapedRepoPath},
+      command: [
+        "if [ ! -d .git ]; then",
+        ${cloneLine},
+        "fi",
+        "git fetch origin main",
+        "git checkout main",
+        "git pull --ff-only origin main"
+      ].join("\\n")
+    }),
+
+    cli("sync_runtime", {
+      cwd: ${escapedRepoPath},
+      command: "node scripts/sync-npm-package-runtime.mjs"
+    }),
+
+    cli("stamp_version", {
+      cwd: ${escapedRepoPath} + "/packages/amalgm",
+      command: "npm version --allow-same-version --no-git-tag-version \\"0.1.$(date +%s)\\""
+    }),
+
+    cli("check_package", {
+      cwd: ${escapedRepoPath} + "/packages/amalgm",
+      command: "npm run check"
+    }),
+
+    cli("publish_package", {
+      cwd: ${escapedRepoPath} + "/packages/amalgm",
+      command: [
+        ": \\"${'$'}{NODE_AUTH_TOKEN:?Missing NODE_AUTH_TOKEN}\\"",
+        "printf '//registry.npmjs.org/:_authToken=${'$'}{NODE_AUTH_TOKEN}\\\\n' > .npmrc",
+        "trap 'rm -f .npmrc' EXIT",
+        "VERSION=\\"$(node -p \\"require('./package.json').version\\")\\"",
+        "if npm view \\"amalgm@${'$'}{VERSION}\\" version >/dev/null 2>&1; then",
+        "  echo \\"amalgm@${'$'}{VERSION} already exists; skipping publish\\"",
+        "else",
+        "  npm publish --access public --tag latest",
+        "fi",
+        "npm dist-tag add \\"amalgm@${'$'}{VERSION}\\" canary"
+      ].join("\\n"),
+      env: {
+        NODE_AUTH_TOKEN: ({ secrets }) => secrets.NODE_AUTH_TOKEN
+      },
+      timeoutMs: 600000
+    }),
+
+    tool("notify_user", "amalgm", "notify_user", {
+      subject: "amalgm npm publish complete",
+      level: "success",
+      message: ({ outputs }) => {
+        const publish = outputs.publish_package || {}
+        return [
+          "amalgm npm publish workflow completed.",
+          "",
+          "~~~",
+          String(publish.stdout || "").trim() || "No stdout captured.",
+          "~~~"
+        ].join("\\n")
+      }
+    })
+  ]
+})`;
+}
+
+function internalWorkflowSeeds() {
+  if (!findEngineRepoPath()) return [];
+  const repoPath = process.env.AMALGM_ENGINE_PUBLISH_REPO_PATH
+    || path.join(os.homedir(), '.amalgm', 'workflow-checkouts', 'amalgm-engine-publish');
+
+  return [
+    {
+      id: 'internal-amalgm-engine-npm-publish',
+      name: 'Publish amalgm npm package',
+      description: 'Internal workflow: publish the amalgm npm package when amalgm-engine is pushed to main.',
+      source: 'github',
+      event: 'push',
+      projectPath: repoPath,
+      enabled: true,
+      internal: true,
+      workflowText: engineNpmPublishWorkflow(repoPath),
+      allowlist: {
+        localCompute: true,
+        secrets: ['NODE_AUTH_TOKEN'],
+        actions: ['amalgm.notify_user'],
+      },
+      limits: {
+        maxConcurrentRuns: 1,
+        queueLimit: 5,
+        cellTimeoutMs: 600000,
+      },
+    },
+  ];
+}
+
+module.exports = {
+  internalWorkflowSeeds,
+};

package/runtime/scripts/amalgm-mcp/events/matcher.js

@@ -50,25 +50,54 @@ function computeSignature(secret, rawBody) {
 }
 
 /**
- * Return the trigger whose secret verifies the provided auth proof, or null.
+ * Check whether a trigger's source/event selector matches an inbound event.
+ * Empty or "*" means "any" for either side.
  */
-function matchBySignature(triggers, signature, rawBody) {
+function matchesEventRef(trigger, eventRef = {}) {
+  if (!trigger) return false;
+  const actualSource = String(eventRef.source || '').trim();
+  const actualEvent = String(eventRef.event || '').trim();
+  const wantedSource = String(trigger.source || '*').trim();
+  const wantedEvent = String(trigger.event || '*').trim();
+  return (
+    (!wantedSource || wantedSource === '*' || wantedSource === actualSource)
+    && (!wantedEvent || wantedEvent === '*' || wantedEvent === actualEvent)
+  );
+}
+
+function verifiesSignature(trigger, signature, rawBody) {
+  if (!trigger?.enabled || !trigger.secret) return false;
+  if (
+    signature.header === 'authorization'
+    || TOKEN_HEADERS.includes(signature.header)
+  ) {
+    return timingSafeEqual(signature.value, trigger.secret);
+  }
+
+  const expected = computeSignature(trigger.secret, rawBody);
+  return timingSafeEqual(signature.value, expected);
+}
+
+/**
+ * Return every trigger whose secret and optional source/event selector match.
+ */
+function matchAllBySignature(triggers, signature, rawBody, eventRef = null) {
   if (!signature || typeof signature.value !== 'string') return null;
 
+  const matches = [];
   for (const trigger of triggers) {
-    if (!trigger.enabled || !trigger.secret) continue;
-    if (
-      signature.header === 'authorization'
-      || TOKEN_HEADERS.includes(signature.header)
-    ) {
-      if (timingSafeEqual(signature.value, trigger.secret)) return trigger;
-      continue;
-    }
-
-    const expected = computeSignature(trigger.secret, rawBody);
-    if (timingSafeEqual(signature.value, expected)) return trigger;
+    if (!verifiesSignature(trigger, signature, rawBody)) continue;
+    if (eventRef && !matchesEventRef(trigger, eventRef)) continue;
+    matches.push(trigger);
   }
-  return null;
+  return matches;
+}
+
+/**
+ * Return the first trigger whose secret verifies the provided auth proof, or null.
+ */
+function matchBySignature(triggers, signature, rawBody, eventRef = null) {
+  return matchAllBySignature(triggers, signature, rawBody, eventRef)?.[0] || null;
 }
 
 /**
@@ -119,7 +148,9 @@ function collectPassthroughHeaders(reqHeaders) {
 module.exports = {
   extractSignature,
   computeSignature,
+  matchAllBySignature,
   matchBySignature,
+  matchesEventRef,
   pickSourceLabel,
   collectPassthroughHeaders,
 };