feat(automations): multi-channel message trigger OR-list (#3974) (#3982)

The `trigger.message` block only exposed two single-value channel filters
(`On channel (name)` and `On channel #`), so matching "channel A OR channel C"
required a separate automation per channel.

Add an `On channels` multi-select (`channelMulti`) to the message trigger — an
OR-list that fires when the message's resolved channel name matches ANY selected
entry. It mirrors the existing `action.sendMessage` `channels` field (name-based,
unified across sources) and works for both Meshtastic and MeshCore messages.

- catalog: add `channels` (channelMulti) to `trigger.message`, alongside the
  legacy scalar `channelName`/`channel` fields (kept for backward compat).
- builder: no change needed — the trigger already receives the shared `channels`
  prop, so the existing channelMulti renderer wires up automatically.
- triggerContext: all four matchers (messageMatchesFilter,
  meshCoreMessageMatchesFilter, describeMessageFilterMiss,
  describeMeshCoreFilterMiss) treat a populated `channels` array as an OR-list,
  taking precedence over the legacy scalar checks; empty/absent falls back to
  legacy behavior. New helpers messageFilterChannelNames /
  messageFilterUsesChannelName.
- engine: onMessage/onMeshCoreMessage resolve the per-source slot→name when a
  channels array is present (not just the scalar channelName).

No DB migration — saved automations keep working unchanged.


Claude-Session: https://claude.ai/code/session_015AFBA76hsjqhsXe1BdnYub

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: Yeraze

docs/features/automation-engine.md

@@ -56,7 +56,7 @@ Every automation has exactly one trigger (the **WHEN**). Each trigger exposes a
 
 | Trigger | Fires when… | Notable options |
 | --- | --- | --- |
-| **A message is received** | A text/packet message arrives | `Text contains` (case-insensitive substring), `Text matches regex`, channel match, `From node #` |
+| **A message is received** | A text/packet message arrives | `Text contains` (case-insensitive substring), `Text matches regex`, multi-channel match (`On channels` OR-list), legacy `On channel (name)`/`On channel #`, `From node #` |
 | **A new node is discovered** | A node is seen for the first time | — |
 | **A node is updated** | A node record changes (name, role, position, …) | — |
 | **Telemetry is received** | A telemetry reading arrives | `Metric` filter (battery, voltage, temperature, channel utilization, air util TX, …) |
@@ -67,9 +67,23 @@ Every automation has exactly one trigger (the **WHEN**). Each trigger exposes a
 ### Message trigger & channel-name matching
 
 The message trigger can filter on text (substring or regex) and on the **channel**. Prefer matching
-by **channel name** (`On channel (name)`) rather than raw slot index: the same logical channel can
-sit in a different slot on different sources, so a name match is portable across your whole mesh.
-The raw `On channel #` index is still available for single-source cases.
+by **channel name** rather than raw slot index: the same logical channel can sit in a different slot
+on different sources, so a name match is portable across your whole mesh.
+
+- **On channels** *(multi-select)* — pick one or more channels (unified by name across your
+  sources). The trigger fires when a message arrives on **any** of the selected channels — an
+  OR-list — so a single automation can cover "channel A **or** channel C" without a separate copy
+  per channel. Leave none selected to match any channel. When set, this **overrides** the two
+  single-channel fields below. Matching is by channel name and works for both Meshtastic and
+  MeshCore messages.
+- **On channel (name)** — legacy single-channel name match (case-insensitive). Kept for
+  backward compatibility with existing automations; the multi-select `On channels` above is
+  preferred. Ignored when `On channels` is set.
+- **On channel #** — the raw slot index, still available for single-source cases. Ignored when
+  `On channels` is set.
+
+Saved automations that used the old single-channel fields keep working unchanged — no migration
+is needed.
 
 ### Schedule trigger (live cron)
 

src/components/automations/catalog.ts

@@ -47,8 +47,9 @@ export const TRIGGERS: BlockDef[] = [
     fields: [
       { name: 'textContains', label: 'Text contains', kind: 'text', placeholder: 'e.g. ping', help: 'Case-insensitive substring match. Leave blank to match any text.' },
       { name: 'regex', label: 'Text matches regex', kind: 'text', placeholder: 'e.g. ^(test|ping)', advanced: true, help: 'A regular expression matched against the message text.' },
-      { name: 'channelName', label: 'On channel (name)', kind: 'text', placeholder: 'any', advanced: true, help: 'Match by channel name (case-insensitive) — portable across sources where the same channel sits in a different slot. Preferred over the channel # below.' },
-      { name: 'channel', label: 'On channel #', kind: 'number', placeholder: 'any', advanced: true, help: 'Match by raw channel index. Note: the same channel can be a different index on different sources — use the name above for cross-source automations.' },
+      { name: 'channels', label: 'On channels', kind: 'channelMulti', advanced: true, help: 'Match messages that arrive on ANY of these channels (unified by name across your sources). An OR-list — leave none to match any channel. When set, this overrides the single-channel fields below.' },
+      { name: 'channelName', label: 'On channel (name)', kind: 'text', placeholder: 'any', advanced: true, help: 'Match by channel name (case-insensitive) — portable across sources where the same channel sits in a different slot. Preferred over the channel # below. Ignored when "On channels" above is set.' },
+      { name: 'channel', label: 'On channel #', kind: 'number', placeholder: 'any', advanced: true, help: 'Match by raw channel index. Note: the same channel can be a different index on different sources — use the name above for cross-source automations. Ignored when "On channels" above is set.' },
       { name: 'from', label: 'From node #', kind: 'number', placeholder: 'any', advanced: true, help: 'Only fire for messages from this node number.' },
       COOLDOWN,
     ],

src/components/automations/compile.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { compile, decompile, type WorkflowForm } from './compile.js';
 import { validateAutomationGraph } from '../../types/automation.js';
+import { TRIGGERS } from './catalog.js';
 
 const trig = { type: 'trigger.message', params: { textContains: 'ping' } };
 const cond = (value: number) => ({ type: 'condition.numeric', params: { field: 'hops', op: '==', value } });
@@ -163,3 +164,30 @@ describe('decompile — fall-back to null', () => {
     expect(back!.rules[0].actions[0].type).toBe('action.tapback');
   });
 });
+
+describe('trigger.message catalog — multi-channel field (#3974)', () => {
+  const trigMsg = TRIGGERS.find((t) => t.type === 'trigger.message')!;
+
+  it('exposes a channelMulti "channels" field', () => {
+    const f = trigMsg.fields.find((x) => x.name === 'channels');
+    expect(f).toBeDefined();
+    expect(f!.kind).toBe('channelMulti');
+  });
+
+  it('keeps the legacy scalar channelName/channel fields for backward compat', () => {
+    expect(trigMsg.fields.some((x) => x.name === 'channelName' && x.kind === 'text')).toBe(true);
+    expect(trigMsg.fields.some((x) => x.name === 'channel' && x.kind === 'number')).toBe(true);
+  });
+
+  it('round-trips a channels array through compile/decompile', () => {
+    const channels = [{ name: 'gauntlet', protocol: 'meshtastic' }, { name: 'ops', protocol: 'meshtastic' }];
+    const form: WorkflowForm = {
+      trigger: { type: 'trigger.message', params: { channels } },
+      rules: [{ conditions: [], actions: [{ type: 'action.tapback', params: { emoji: '👍' } }] }],
+      combine: null,
+    };
+    const back = decompile(compile(form));
+    expect(back).not.toBeNull();
+    expect(back!.trigger.params).toEqual({ channels });
+  });
+});

src/server/services/automation/automationEngineService.test.ts

@@ -145,6 +145,31 @@ describe('AutomationEngineService', () => {
     expect(calls.map((c) => c.fn)).toEqual(['sendTapback']);
   });
 
+  it('matches a message trigger by the multi-channel OR-list, resolving slot→name (#3974)', async () => {
+    const { calls, deps } = recorder();
+    await createEnabled('on-gauntlet-or-ops', {
+      version: 1,
+      nodes: [
+        { id: 't', type: 'trigger.message', params: { channels: [{ name: 'gauntlet', protocol: 'meshtastic' }, { name: 'ops', protocol: 'meshtastic' }] } },
+        { id: 'tap', type: 'action.tapback', params: { emoji: '👍' } },
+      ],
+      edges: [{ from: 't', to: 'tap' }],
+    });
+    // Slot 2 = "Gauntlet", slot 3 = "Ops", everything else "Primary".
+    const chData = {
+      getNode: async () => null,
+      getTelemetry: async () => null,
+      getChannelName: async (_sourceId: string | null, idx: number) => (idx === 2 ? 'Gauntlet' : idx === 3 ? 'Ops' : 'Primary'),
+    };
+    const engine = new AutomationEngineService({ automationsRepo: autos, varResolver: resolver, deps, data: chData, now: () => clock });
+    await engine.load();
+
+    expect(await engine.onMessage(message({ channel: 2 }), 'default')).toBe(1); // matches "gauntlet"
+    expect(await engine.onMessage(message({ channel: 3 }), 'default')).toBe(1); // matches "ops"
+    expect(await engine.onMessage(message({ channel: 0 }), 'default')).toBe(0); // "Primary" in neither
+    expect(calls.map((c) => c.fn)).toEqual(['sendTapback', 'sendTapback']);
+  });
+
   it('fires a message automation on a MeshCore message and replies on the trigger scope (#3833)', async () => {
     const { calls, deps } = recorder();
     await createEnabled('mc-ping', {

src/server/services/automation/automationEngineService.ts

@@ -33,6 +33,7 @@ import {
   meshCoreMessageMatchesFilter,
   describeMessageFilterMiss,
   describeMeshCoreFilterMiss,
+  messageFilterUsesChannelName,
   type TriggerContext,
   type SystemEvent,
 } from './triggerContext.js';
@@ -384,7 +385,7 @@ export class AutomationEngineService {
     let channelName: string | null | undefined;
     const usesChannelName = (this.index.get('trigger.message') ?? []).some((a) => {
       const p = a.triggerNode.params as Record<string, unknown> | undefined;
-      return typeof p?.channelName === 'string' && p.channelName.length > 0;
+      return messageFilterUsesChannelName(p ?? {});
     });
     if (usesChannelName && this.data.getChannelName) {
       channelName = await this.data.getChannelName(sourceId, Number(msg.channel));
@@ -408,7 +409,7 @@ export class AutomationEngineService {
     let channelName: string | null | undefined;
     const usesChannelName = (this.index.get('trigger.message') ?? []).some((a) => {
       const p = a.triggerNode.params as Record<string, unknown> | undefined;
-      return typeof p?.channelName === 'string' && p.channelName.length > 0;
+      return messageFilterUsesChannelName(p ?? {});
     });
     // A received channel message stores its slot index in `from` as `channel-<idx>`.
     const channelIdx = ctx.fields.channel;

src/server/services/automation/triggerContext.test.ts

@@ -11,6 +11,8 @@ import {
   meshCoreMessageMatchesFilter,
   describeMessageFilterMiss,
   describeMeshCoreFilterMiss,
+  messageFilterChannelNames,
+  messageFilterUsesChannelName,
   resolveTriggerPath,
   BROADCAST_ADDR,
 } from './triggerContext.js';
@@ -140,6 +142,103 @@ describe('messageMatchesFilter', () => {
   });
 });
 
+describe('multi-channel trigger filter (#3974)', () => {
+  const chans = (...names: string[]) => names.map((name) => ({ name, protocol: 'meshtastic' }));
+
+  describe('messageFilterChannelNames', () => {
+    it('extracts non-empty names from the channels array', () => {
+      expect(messageFilterChannelNames({ channels: chans('gauntlet', 'ops') })).toEqual(['gauntlet', 'ops']);
+    });
+    it('drops blank names and ignores non-object entries', () => {
+      expect(messageFilterChannelNames({ channels: [{ name: '' }, { name: 'ops' }, 'x', null, {}] })).toEqual(['ops']);
+    });
+    it('returns [] when channels is absent or not an array', () => {
+      expect(messageFilterChannelNames({})).toEqual([]);
+      expect(messageFilterChannelNames({ channels: 'nope' })).toEqual([]);
+    });
+  });
+
+  describe('messageFilterUsesChannelName', () => {
+    it('is true for a scalar channelName', () => {
+      expect(messageFilterUsesChannelName({ channelName: 'gauntlet' })).toBe(true);
+    });
+    it('is true for a populated channels array', () => {
+      expect(messageFilterUsesChannelName({ channels: chans('gauntlet') })).toBe(true);
+    });
+    it('is false when neither is set / all blank', () => {
+      expect(messageFilterUsesChannelName({})).toBe(false);
+      expect(messageFilterUsesChannelName({ channelName: '' })).toBe(false);
+      expect(messageFilterUsesChannelName({ channels: [{ name: '' }] })).toBe(false);
+    });
+  });
+
+  describe('messageMatchesFilter OR-list (Meshtastic)', () => {
+    it('fires when the resolved name matches ANY entry (case-insensitive)', () => {
+      expect(messageMatchesFilter(msg(), { channels: chans('gauntlet', 'ops') }, 'Gauntlet')).toBe(true);
+      expect(messageMatchesFilter(msg(), { channels: chans('gauntlet', 'ops') }, 'OPS')).toBe(true);
+    });
+    it('does not fire when the resolved name matches no entry', () => {
+      expect(messageMatchesFilter(msg(), { channels: chans('gauntlet', 'ops') }, 'Primary')).toBe(false);
+    });
+    it('never matches when the name could not be resolved', () => {
+      expect(messageMatchesFilter(msg(), { channels: chans('gauntlet') }, null)).toBe(false);
+      expect(messageMatchesFilter(msg(), { channels: chans('gauntlet') })).toBe(false);
+    });
+    it('an empty channels array is a legacy fallback (does not constrain)', () => {
+      expect(messageMatchesFilter(msg(), { channels: [] }, null)).toBe(true);
+      // empty array + legacy scalar channelName still honors the scalar
+      expect(messageMatchesFilter(msg(), { channels: [], channelName: 'ops' }, 'Ops')).toBe(true);
+      expect(messageMatchesFilter(msg(), { channels: [], channelName: 'ops' }, 'Primary')).toBe(false);
+    });
+    it('channels takes precedence over the legacy scalar channel/channelName', () => {
+      // channels wins: the mismatched legacy scalar channelName is ignored.
+      expect(messageMatchesFilter(msg(), { channels: chans('ops'), channelName: 'gauntlet' }, 'Ops')).toBe(true);
+      // channels wins: the legacy numeric channel is ignored (msg.channel = 0, would fail on channel:2).
+      expect(messageMatchesFilter(msg(), { channels: chans('ops'), channel: 2 }, 'Ops')).toBe(true);
+    });
+    it('still applies text/regex checks alongside the channel OR-list', () => {
+      expect(messageMatchesFilter(msg({ text: 'ping' }), { channels: chans('ops'), textContains: 'ping' }, 'Ops')).toBe(true);
+      expect(messageMatchesFilter(msg({ text: 'pong' }), { channels: chans('ops'), textContains: 'ping' }, 'Ops')).toBe(false);
+    });
+  });
+
+  describe('meshCoreMessageMatchesFilter OR-list (MeshCore)', () => {
+    it('fires when the resolved name matches ANY entry', () => {
+      expect(meshCoreMessageMatchesFilter(mcMsg({ fromPublicKey: 'channel-1' }), { channels: chans('gauntlet', 'ops') }, 'Ops')).toBe(true);
+      expect(meshCoreMessageMatchesFilter(mcMsg({ fromPublicKey: 'channel-1' }), { channels: chans('gauntlet', 'ops') }, 'Primary')).toBe(false);
+    });
+    it('never matches when the name could not be resolved', () => {
+      expect(meshCoreMessageMatchesFilter(mcMsg({ fromPublicKey: 'channel-1' }), { channels: chans('ops') }, null)).toBe(false);
+    });
+    it('empty channels array falls back to legacy scalar behavior', () => {
+      expect(meshCoreMessageMatchesFilter(mcMsg({ fromPublicKey: 'channel-1' }), { channels: [] }, null)).toBe(true);
+      expect(meshCoreMessageMatchesFilter(mcMsg({ fromPublicKey: 'channel-1' }), { channels: [], channelName: 'ops' }, 'Ops')).toBe(true);
+    });
+    it('channels precedence ignores the legacy numeric channel', () => {
+      expect(meshCoreMessageMatchesFilter(mcMsg({ fromPublicKey: 'channel-1' }), { channels: chans('ops'), channel: 5 }, 'Ops')).toBe(true);
+    });
+    it('Meshtastic-only filters (from/to/portnum) still force a non-match', () => {
+      expect(meshCoreMessageMatchesFilter(mcMsg({ fromPublicKey: 'channel-1' }), { channels: chans('ops'), from: 5 }, 'Ops')).toBe(false);
+    });
+  });
+
+  describe('describeMessageFilterMiss / describeMeshCoreFilterMiss OR-list reasons', () => {
+    it('explains a Meshtastic multi-channel miss', () => {
+      expect(describeMessageFilterMiss(msg(), { channels: chans('gauntlet', 'ops') }, 'Primary'))
+        .toBe('channel name "Primary" not in [gauntlet, ops]');
+      expect(describeMessageFilterMiss(msg(), { channels: chans('ops') }, null))
+        .toBe('channel name "(unresolved)" not in [ops]');
+    });
+    it('returns undefined for a Meshtastic multi-channel hit', () => {
+      expect(describeMessageFilterMiss(msg(), { channels: chans('gauntlet', 'ops') }, 'Ops')).toBeUndefined();
+    });
+    it('explains a MeshCore multi-channel miss', () => {
+      expect(describeMeshCoreFilterMiss(mcMsg({ fromPublicKey: 'channel-1' }), { channels: chans('ops') }, 'Primary'))
+        .toBe('channel name "Primary" not in [ops]');
+    });
+  });
+});
+
 describe('buildMeshCoreMessageContext (#3833)', () => {
   it('maps a channel message: synthetic from, channel index, broadcast, scope', () => {
     const ctx = buildMeshCoreMessageContext(