feat: expose auto responder tokens as environment variables (#2314) (#2356)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Yeraze

docs/developers/auto-responder-scripting.md

@@ -366,15 +366,30 @@ All scripts receive these environment variables:
 |----------|-------------|---------|
 | `MESSAGE` | Full message text received | `"weather miami"` |
 | `FROM_NODE` | Sender's node number | `"123456789"` |
-| `FROM_SHORT_NAME` | Sender's short name (if known) | `"JOHN"` |
-| `FROM_LONG_NAME` | Sender's long name (if known) | `"John Doe"` |
+| `NODE_ID` | Sender's node ID (hex format) | `"!a2e4ff4c"` |
+| `SHORT_NAME` | Sender's short name (if known) | `"JOHN"` |
+| `LONG_NAME` | Sender's long name (if known) | `"John Doe"` |
+| `FROM_SHORT_NAME` | Sender's short name (alias for `SHORT_NAME`) | `"JOHN"` |
+| `FROM_LONG_NAME` | Sender's long name (alias for `LONG_NAME`) | `"John Doe"` |
 | `FROM_LAT` | Sender's latitude (if known) | `"25.7617"` |
 | `FROM_LON` | Sender's longitude (if known) | `"-80.1918"` |
 | `MM_LAT` | MeshMonitor node's latitude (if known) | `"25.7617"` |
 | `MM_LON` | MeshMonitor node's longitude (if known) | `"-80.1918"` |
+| `HOPS` | Number of hops the message traveled | `"2"` |
+| `SNR` | Signal-to-noise ratio of received packet | `"6.25"` |
+| `RSSI` | Received signal strength indicator | `"-98"` |
+| `CHANNEL` | Channel number the message was received on | `"0"` |
+| `VERSION` | Sender's firmware version (if known) | `"2.5.6.a1b2c3d"` |
+| `NODECOUNT` | Number of active nodes on the mesh | `"42"` |
+| `VIA_MQTT` | Whether message arrived via MQTT bridge | `"true"` |
+| `IS_DIRECT` | Whether the message is a direct message | `"true"` |
 | `PACKET_ID` | Message packet ID | `"987654321"` |
+| `MESHTASTIC_IP` | IP address of the connected Meshtastic node | `"192.168.1.100"` |
+| `MESHTASTIC_PORT` | TCP port of the connected Meshtastic node | `"4403"` |
 | `TRIGGER` | Trigger pattern that matched | `"weather {location}"` |
+| `MATCHED_PATTERN` | The specific pattern that matched | `"weather {location}"` |
 | `PARAM_*` | Extracted parameters | `PARAM_location="miami"` |
+| `MSG_*` | All message fields as individual variables | `MSG_text="weather miami"` |
 | `TZ` | Server timezone (IANA timezone name) | `"America/New_York"` |
 
 ### Location Environment Variables

docs/features/automation.md

@@ -890,9 +890,22 @@ Scripts must:
 All scripts receive these environment variables:
 - `MESSAGE`: Full message text received
 - `FROM_NODE`: Sender's node number
+- `NODE_ID`: Sender's node ID (hex format, e.g., `!a2e4ff4c`)
+- `LONG_NAME` / `SHORT_NAME`: Sender's node names
+- `HOPS`: Number of hops the message traveled
+- `SNR` / `RSSI`: Signal quality of received packet
+- `CHANNEL`: Channel number the message was received on
+- `VERSION`: Sender's firmware version
+- `NODECOUNT`: Number of active nodes on the mesh
+- `VIA_MQTT`: Whether message arrived via MQTT bridge
+- `IS_DIRECT`: Whether the message is a direct message
+- `MESHTASTIC_IP` / `MESHTASTIC_PORT`: Connected node address
 - `PACKET_ID`: Message packet ID
 - `TRIGGER`: The trigger pattern that matched
 - `PARAM_*`: Extracted parameters (e.g., `PARAM_location`, `PARAM_name`)
+- `MSG_*`: All message fields as individual variables
+
+See the [Auto Responder Scripting Guide](/developers/auto-responder-scripting#environment-variables) for the complete list.
 
 **JSON Output Format**:
 

src/server/meshtasticManager.ts

@@ -7857,7 +7857,9 @@ class MeshtasticManager {
               const { promisify } = await import('util');
               const execFileAsync = promisify(execFile);
 
-              const scriptEnv = await this.createScriptEnvVariables(message, matchedPattern, extractedParams, trigger, packetId);
+              const scriptEnv = await this.createScriptEnvVariables(message, matchedPattern, extractedParams, trigger, packetId, {
+                nodeId, hopsTraveled, isDirectMessage
+              });
 
               // Expand tokens in script args if provided
               let scriptArgsList: string[] = [];
@@ -8050,7 +8052,14 @@ class MeshtasticManager {
    * - MSG_*: All message fields (e.g., MSG_rxSnr, MSG_rxRssi, MSG_hopStart, MSG_hopLimit, MSG_viaMqtt, etc.)
    * - PARAM_*: Extracted parameters from trigger pattern
    */
-  private async createScriptEnvVariables(message: TextMessage, matchedPattern: string, extractedParams: Record<string, string>, trigger: AutoResponderTrigger, packetId?: number) {
+  private async createScriptEnvVariables(
+    message: TextMessage,
+    matchedPattern: string,
+    extractedParams: Record<string, string>,
+    trigger: AutoResponderTrigger,
+    packetId?: number,
+    context?: { nodeId: string; hopsTraveled: number; isDirectMessage: boolean }
+  ) {
     const config = await this.getScriptConnectionConfig();
     const scriptEnv: Record<string, string> = {
       ...process.env as Record<string, string>,
@@ -8063,15 +8072,32 @@ class MeshtasticManager {
       MESHTASTIC_PORT: String(config.tcpPort),
     };
 
+    // Add token-matching environment variables (Issue #2314)
+    // These match the {TOKEN} names from the auto responder documentation
+    if (context) {
+      scriptEnv.NODE_ID = context.nodeId;
+      scriptEnv.HOPS = String(context.hopsTraveled);
+      scriptEnv.IS_DIRECT = String(context.isDirectMessage);
+    }
+    if (message.rxSnr !== undefined) scriptEnv.SNR = String(message.rxSnr);
+    if (message.rxRssi !== undefined) scriptEnv.RSSI = String(message.rxRssi);
+    scriptEnv.CHANNEL = String(message.channel);
+    scriptEnv.VIA_MQTT = String(message.viaMqtt);
+
     // Add sender node information environment variables
     const fromNode = await databaseService.nodes.getNode(message.fromNodeNum);
     if (fromNode) {
       // Add node names (Issue #1099)
       if (fromNode.shortName) {
         scriptEnv.FROM_SHORT_NAME = fromNode.shortName;
+        scriptEnv.SHORT_NAME = fromNode.shortName;
       }
       if (fromNode.longName) {
         scriptEnv.FROM_LONG_NAME = fromNode.longName;
+        scriptEnv.LONG_NAME = fromNode.longName;
+      }
+      if (fromNode.firmwareVersion) {
+        scriptEnv.VERSION = fromNode.firmwareVersion;
       }
       // Add location (FROM_LAT, FROM_LON)
       if (fromNode.latitude != null && fromNode.longitude != null) {
@@ -8080,6 +8106,12 @@ class MeshtasticManager {
       }
     }
 
+    // Add NODECOUNT - active nodes based on maxNodeAgeHours setting
+    const maxNodeAgeHours = parseInt(await databaseService.settings.getSetting('maxNodeAgeHours') || '24');
+    const maxNodeAgeDays = maxNodeAgeHours / 24;
+    const activeNodes = await databaseService.nodes.getActiveNodes(maxNodeAgeDays);
+    scriptEnv.NODECOUNT = String(activeNodes.length);
+
     // Add location environment variables for the MeshMonitor node (MM_LAT, MM_LON)
     const localNodeInfo = this.getLocalNodeInfo();
     if (localNodeInfo) {