Add incoming region to kwargs

app/fanout/AGENTS_fanout.md

@@ -120,6 +120,7 @@ Wraps bot code execution via `app/fanout/bot_exec.py`. Config blob:
 - Executes in a thread pool with timeout and semaphore concurrency control
 - Rate-limits outgoing messages for repeater compatibility
 - Channel `message_text` passed to bot code is normalized for human readability by stripping a leading `"{sender_name}: "` prefix when it matches the payload sender.
+- The `bot(...)` function receives, in order: `sender_name`, `sender_key`, `message_text`, `is_dm`, `channel_key`, `channel_name`, `sender_timestamp`, `path`, then optionally `is_outgoing`, `path_bytes_per_hop`, `packet_hash`. `region` (resolved region name for region-scoped channel messages; `None` otherwise) is delivered **only** to bots that use `**kwargs` or explicitly name the `region` parameter — it is intentionally not added to the positional call styles so existing bot signatures keep binding unchanged. `_analyze_bot_signature` in `bot_exec.py` picks the call style from the bot's actual signature.
 
 ### webhook (webhook.py)
 HTTP webhook delivery. Config blob:

app/fanout/bot.py

@@ -137,6 +137,9 @@ class BotModule(FanoutModule):
             path_value = paths[0].get("path") if isinstance(paths[0], dict) else None
         path_bytes_per_hop = _derive_path_bytes_per_hop(paths, path_value)
         packet_hash = data.get("packet_hash")
+        # Resolved region name for region-scoped channel messages (None for DMs,
+        # unscoped flood, or when the transport code matched no known region).
+        region = data.get("region")
 
         # Wait for message to settle (allows retransmissions to be deduped)
         await asyncio.sleep(2)
@@ -163,6 +166,7 @@ class BotModule(FanoutModule):
                         is_outgoing,
                         path_bytes_per_hop,
                         packet_hash,
+                        region,
                     ),
                     timeout=BOT_EXECUTION_TIMEOUT,
                 )

app/fanout/bot_exec.py

@@ -72,14 +72,16 @@ def _analyze_bot_signature(bot_func_or_sig) -> BotCallPlan:
     has_varargs = any(p.kind == inspect.Parameter.VAR_POSITIONAL for p in param_values)
     has_kwargs = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in param_values)
     explicit_optional_names = tuple(
-        name for name in ("is_outgoing", "path_bytes_per_hop", "packet_hash") if name in params
+        name
+        for name in ("is_outgoing", "path_bytes_per_hop", "packet_hash", "region")
+        if name in params
     )
     unsupported_required_kwonly = [
         p.name
         for p in param_values
         if p.kind == inspect.Parameter.KEYWORD_ONLY
         and p.default is inspect.Parameter.empty
-        and p.name not in {"is_outgoing", "path_bytes_per_hop", "packet_hash"}
+        and p.name not in {"is_outgoing", "path_bytes_per_hop", "packet_hash", "region"}
     ]
     if unsupported_required_kwonly:
         raise ValueError(
@@ -107,6 +109,8 @@ def _analyze_bot_signature(bot_func_or_sig) -> BotCallPlan:
         keyword_args["path_bytes_per_hop"] = 1
     if has_kwargs or "packet_hash" in params:
         keyword_args["packet_hash"] = ""
+    if has_kwargs or "region" in params:
+        keyword_args["region"] = None
     candidate_specs.append(("keyword", [], keyword_args))
 
     if not has_kwargs and explicit_optional_names:
@@ -117,6 +121,8 @@ def _analyze_bot_signature(bot_func_or_sig) -> BotCallPlan:
             kwargs["path_bytes_per_hop"] = 1
         if has_kwargs or "packet_hash" in params:
             kwargs["packet_hash"] = ""
+        if has_kwargs or "region" in params:
+            kwargs["region"] = None
         candidate_specs.append(("mixed_keyword", base_args, kwargs))
 
     if has_varargs or positional_capacity >= 11:
@@ -142,7 +148,7 @@ def _analyze_bot_signature(bot_func_or_sig) -> BotCallPlan:
         "Supported trailing parameters are: path; path + is_outgoing; "
         "path + path_bytes_per_hop; path + is_outgoing + path_bytes_per_hop; "
         "path + is_outgoing + path_bytes_per_hop + packet_hash; "
-        "or use **kwargs for forward compatibility."
+        "or use **kwargs for forward compatibility (which also receives region)."
     )
 
 
@@ -159,6 +165,7 @@ def execute_bot_code(
     is_outgoing: bool = False,
     path_bytes_per_hop: int | None = None,
     packet_hash: str | None = None,
+    region: str | None = None,
 ) -> str | list[str] | None:
     """
     Execute user-provided bot code with message context.
@@ -166,6 +173,10 @@ def execute_bot_code(
     The code should define a function:
     `bot(sender_name, sender_key, message_text, is_dm, channel_key, channel_name, sender_timestamp, path, is_outgoing, path_bytes_per_hop, packet_hash)`
     or use named parameters / `**kwargs`.
+
+    `region` is only delivered to bots that opt in via `**kwargs` or by naming
+    the parameter (`region`); the positional call styles are unchanged for
+    backward compatibility.
     that returns either None (no response), a string (single response message),
     or a list of strings (multiple messages sent in order).
 
@@ -185,6 +196,8 @@ def execute_bot_code(
         is_outgoing: True if this is our own outgoing message
         path_bytes_per_hop: Number of bytes per routing hop (1, 2, or 3), if known
         packet_hash: MeshCore packet hash (first 16 hex chars of SHA256, uppercase), if known
+        region: Resolved region name for a region-scoped channel message, or None
+            for DMs, unscoped flood, or a transport code matching no known region
 
     Returns:
         Response string, list of strings, or None.
@@ -284,6 +297,8 @@ def execute_bot_code(
                 keyword_args["path_bytes_per_hop"] = path_bytes_per_hop
             if "packet_hash" in call_plan.keyword_args:
                 keyword_args["packet_hash"] = packet_hash
+            if "region" in call_plan.keyword_args:
+                keyword_args["region"] = region
             result = bot_func(**keyword_args)
         else:
             result = bot_func(