fix: a gateway silence read as "not my conversation"

The gateway response carried only whether a reply came back, and the
forwarder used that to decide whether to suppress AstrBot's own model. But
this agent is quiet on purpose far more often than it speaks: a PASS, several
messages merged into one answer by the debounce, the rhythm gate. All of
those return handled=false.

So the forwarder read the persona's deliberate restraint as "not mine" and
handed the room to its built-in model, which then answered in it as someone
else. That is worse than not replying — the restraint is the behaviour being
overridden, and it is the most common outcome by design.

The response now carries `owned` beside `handled`, set once the turn clears
the admission gates, which is the moment the answer to "is this conversation
mine" is known. Everything after that point is about what to say, including
saying nothing. The plugin gates stop_event() on `owned` and falls back to
`handled` when the field is absent, so an older agent behaves exactly as it
does today — pinned by the existing unhandled-response test.

Mutation-checked: conflating the two again (the pre-change semantics) fails
the assertion that a PASS still claims the conversation, and claiming every
turn from the start fails the assertion that a refused one does not.

Also documents the second inbound path, which nothing did. docs/deploy.md
described a QQ-only deployment and never mentioned the gateway, AstrBot, or
how to configure a second platform — the interface was configurable and
undiscoverable. Includes the two AstrBot stages that run before plugin
handlers and would throttle or silently drop a busy QQ group.

Author: wangkant

CHANGELOG.md

@@ -21,6 +21,19 @@ before it was changed and is covered by a test that fails without the fix.
   that is not a directory, an empty `BOT_NAME`, and any key `.env.example`
   does not list. Reported, never fatal — a deployment that is 90% configured
   should start and say what the other 10% is.
+- **`GATEWAY_NATIVE_PLATFORMS` — one forwarder can carry QQ too.** The gateway
+  namespaces every id as `<platform>:<raw>` so a forwarded identity can never
+  collide with a real QQ number. Right for Telegram, exactly wrong for QQ
+  itself: routing QQ through the same door renamed every conversation, so
+  memory, history and every candidate scope pointed at rooms and people that
+  do not exist — and not repairably, because the ledgers content-address their
+  rows over `conv_id`, so the rename moves every id derived from it. Naming a
+  platform here makes its ids arrive bare, identical to NapCat's. Empty by
+  default. It is an operator setting rather than something the forwarder
+  asserts, because a bare id is the spelling `OWNER_QQ`, `QQ_GROUPS` and
+  `PRIVATE_ALLOWED_QQS` are written in — and for the same reason those
+  whitelists now gate on the id's shape rather than on the sink, so a native
+  forwarder cannot both claim QQ authority and skip the QQ gate.
 - **`.env.example` is checked against the code.** The typo check treats the
   template as the authority on what a key may be called, so a test scans every
   `os.getenv` / `os.environ.get` in the package and asserts the template
@@ -189,6 +202,15 @@ before it was changed and is covered by a test that fails without the fix.
 - `.env.example` documents `AGENT_HOME`, `LLM_TIMEOUT`, `LLM_MAX_RETRIES`,
   `MAX_INFLIGHT_GATEWAY` and the two ledger warn-byte settings.
 
+- **A gateway reply of silence no longer reads as "not my conversation".**
+  The response said only whether a reply came back, and the forwarder used
+  that to decide whether to suppress its own model. But this agent stays quiet
+  on purpose far more often than it speaks — a PASS, several messages merged
+  into one answer, the rhythm gate — so AstrBot's built-in model answered in
+  rooms the persona had deliberately sat out, as someone else. The response
+  now carries `owned` alongside `handled`, set once the turn clears admission;
+  the plugin gates on that and falls back to `handled` against an older agent.
+
 ### Performance
 
 Both items were measured before and after; the two that an audit also flagged

docs/deploy.md

@@ -88,6 +88,43 @@ If (1) fails, the agent can never send. If (1) works and (2) never logs
 anything, the bridge's webhook is not configured or is pointed elsewhere. Both
 failures look identical from the outside — a bot that is running and silent.
 
+## More than one platform
+
+Everything above is the QQ path. For Telegram, Discord, Slack and the rest,
+the agent does not connect to the platform at all — a forwarder does, and
+POSTs a platform-neutral event to `POST /webhook/gateway`. The one in this
+repo is an [AstrBot](https://github.com/AstrBotDevs/AstrBot) plugin at
+`integrations/astrbot/astrbot_plugin_llm_persona_gateway/`; copy it into
+AstrBot's `data/plugins/`, and configure the platforms in AstrBot's own UI.
+The persona, memory, learning and typing simulation stay here.
+
+Two settings and one decision:
+
+- `GATEWAY_TOKEN` — shared with the plugin. Required off-host, and the
+  request carries an HMAC-SHA256 envelope over `timestamp.nonce.body` with a
+  replay guard, so a token seen in a log is not enough on its own.
+- `GATEWAY_OWNER_IDS` — platform-prefixed ids (`telegram:12345`) that get the
+  owner branch in DMs. Gateway identities are namespaced `<platform>:<id>` so
+  they can never collide with a QQ number.
+- The decision: **does QQ go through the forwarder too?**
+
+Leave QQ on NapCat and you have two inbound paths but nothing to reconcile.
+Route it through the forwarder and there is one door and one place to
+configure platforms — but then set `GATEWAY_NATIVE_PLATFORMS` to the
+forwarder's QQ adapter name (`aiocqhttp` for AstrBot), or every QQ
+conversation arrives under a namespaced name it has never had before. Memory,
+history and every learned example are keyed the bare way, and the evidence and
+candidate ledgers content-address their rows over the conversation id — so the
+rename changes every id derived from it and cannot be undone by rewriting a
+field. `GATEWAY_NATIVE_PLATFORMS` keeps the ids identical to NapCat's.
+
+Naming a platform there grants its forwarder QQ authority, since bare ids are
+what `OWNER_QQ`, `QQ_GROUPS` and `PRIVATE_ALLOWED_QQS` are compared against.
+Which is why those whitelists then apply to it, unlike to a namespaced
+platform — the forwarder's own allowlist is not the only filter any more.
+
+Do not run both doors for QQ at once; the same message would arrive twice.
+
 ## Exposing the webhook
 
 Keep the default loopback binding when the bridge and the agent share a

integrations/astrbot/astrbot_plugin_llm_persona_gateway/README.md

@@ -53,14 +53,41 @@ loopback URL visible to AstrBot; never send the token over cleartext HTTP.
 | `group_whitelist` | list | `[]` | Group IDs to forward; empty = none. |
 | `private_enabled` | bool | `false` | Enable forwarding for explicitly allowlisted private senders. |
 | `private_whitelist` | list | `[]` | Allowed private senders; empty = none. |
-| `block_default` | bool | `true` | Call `event.stop_event()` only after the agent successfully accepts ownership (`handled: true`). Transport failures, invalid responses, and `handled: false` fall back to AstrBot's normal pipeline. |
-
-## Important: QQ / NapCat double-handling
-
-If NapCat already feeds the agent directly through `POST /webhook/qq`, keep
-`aiocqhttp` in `excluded_platforms` (it is there by default). Otherwise the
-same QQ message would reach the agent twice — once from NapCat and once from
-this plugin.
+| `block_default` | bool | `true` | Call `event.stop_event()` once the agent claims the conversation (`owned: true`). Transport failures, invalid responses and conversations the agent turned away fall back to AstrBot's normal pipeline. |
+
+`owned` is not `handled`. The agent stays quiet on purpose far more often
+than it speaks — a PASS, several messages merged into one answer, the rhythm
+gate — and all of those return `handled: false`. Gating on that would hand
+the room to AstrBot's built-in model, which would then answer as someone else
+in a conversation the persona had decided to sit out. An agent too old to
+send `owned` falls back to `handled`, which is what it did before.
+
+## QQ: two ways, and you must pick one
+
+**Default — NapCat feeds the agent directly.** `aiocqhttp` stays in
+`excluded_platforms`, QQ goes NapCat → `POST /webhook/qq`, and this plugin
+carries everything else. Nothing to configure.
+
+**Or route QQ through here too**, so AstrBot is the single place you configure
+every platform. Remove `aiocqhttp` from `excluded_platforms`, add the QQ group
+to `group_whitelist`, stop NapCat posting to `/webhook/qq`, and set
+`GATEWAY_NATIVE_PLATFORMS=aiocqhttp` on the agent.
+
+That last setting is not optional and not cosmetic. Without it the agent
+namespaces forwarded ids, so every QQ conversation arrives under a new name
+and the agent addresses rooms and people that do not exist — memory, history
+and every learned example are keyed the old way, and the ledgers
+content-address their rows over the conversation id, so it cannot be renamed
+back afterwards. With it, a QQ message relayed by AstrBot lands on exactly the
+keys NapCat would have produced.
+
+Do **not** do both at once: the same message would reach the agent twice.
+
+Two things to change on the AstrBot side before it can carry a busy QQ group,
+because both run before plugin handlers: raise or disable the rate-limit stage
+(30 messages / 60 s by default, and it stalls rather than drops), and review
+`content_safety.internal_keywords`, which is on by default and will silently
+drop messages the persona would have answered.
 
 ## Request authentication
 

integrations/astrbot/astrbot_plugin_llm_persona_gateway/_conf_schema.json

@@ -16,7 +16,7 @@
   },
   "excluded_platforms": {
     "type": "list",
-    "description": "Platform adapter names that must NOT be forwarded. Keep aiocqhttp here when NapCat already feeds the agent directly, otherwise QQ messages would be handled twice.",
+    "description": "Platform adapter names that must NOT be forwarded. Keep aiocqhttp here when NapCat already feeds the agent directly through /webhook/qq, otherwise QQ messages would be handled twice. To make AstrBot the single inbound path for QQ as well, remove it, stop NapCat posting to /webhook/qq, and set GATEWAY_NATIVE_PLATFORMS=aiocqhttp on the agent so QQ ids stay spelled the way every store on disk already spells them.",
     "default": ["aiocqhttp"]
   },
   "group_whitelist": {

integrations/astrbot/astrbot_plugin_llm_persona_gateway/main.py

@@ -162,7 +162,7 @@ async def forward_to_agent(self, event: AstrMessageEvent):
             "raw_text": raw_text,
         }
 
-        delivered, replies = await self._post_to_agent(neutral_event)
+        _replied, owned, replies = await self._post_to_agent(neutral_event)
 
         first = True
         for item in replies:
@@ -176,9 +176,12 @@ async def forward_to_agent(self, event: AstrMessageEvent):
             first = False
             yield event.chain_result(chain)
 
-        if delivered and self.config.get("block_default", True):
-            # The agent owns these conversations: keep AstrBot's built-in
-            # LLM pipeline from producing a second reply.
+        if owned and self.config.get("block_default", True):
+            # Gate on ownership, not on whether a reply came back. The agent
+            # stays quiet on purpose far more often than it speaks — PASS, a
+            # debounce merge, the rhythm gate — and reading that as "not mine"
+            # hands the conversation to AstrBot's built-in model, which then
+            # answers as someone else in a room this persona chose to sit out.
             event.stop_event()
 
     def _map_segments(self, event: AstrMessageEvent, self_id: str):
@@ -278,14 +281,23 @@ def _endpoint_is_allowed(url: str, token: str) -> tuple[bool, str]:
             return False, "off-host agent_url requires a non-empty gateway_token"
         return True, ""
 
-    async def _post_to_agent(self, neutral_event: dict) -> tuple[bool, list]:
+    async def _post_to_agent(
+            self, neutral_event: dict) -> tuple[bool, bool, list]:
+        """POST one event; return (replied, owned, reply items).
+
+        `owned` is the agent's answer to "is this conversation mine", which is
+        NOT the same as whether it replied: a PASS, a debounce merge and a
+        rhythm-gate skip are all deliberate silence in a conversation it owns.
+        Falling back to `handled` keeps an older agent — one that does not send
+        the field — behaving exactly as it does today.
+        """
         url = str(self.config.get("agent_url") or DEFAULT_AGENT_URL)
         timeout = float(self.config.get("timeout_s") or DEFAULT_TIMEOUT_S)
         token = str(self.config.get("gateway_token") or "")
         allowed, reason = self._endpoint_is_allowed(url, token)
         if not allowed:
             logger.warning(f"llm_persona_gateway: refusing unsafe agent_url: {reason}")
-            return False, []
+            return False, False, []
 
         body = json.dumps(
             neutral_event,
@@ -317,11 +329,12 @@ async def _post_to_agent(self, neutral_event: dict) -> tuple[bool, list]:
             data = resp.json()
         except Exception as e:
             logger.warning(f"llm_persona_gateway: agent request failed: {e}")
-            return False, []
+            return False, False, []
         replies = data.get("replies") if isinstance(data, dict) else None
         if not isinstance(replies, list):
-            return False, []
-        return bool(data.get("handled")), [
+            return False, False, []
+        handled = bool(data.get("handled"))
+        return handled, bool(data.get("owned", handled)), [
             r for r in replies if isinstance(r, dict)
         ]
 

integrations/astrbot/astrbot_plugin_llm_persona_gateway/metadata.yaml

@@ -1,5 +1,5 @@
 name: astrbot_plugin_llm_persona_gateway
 desc: Forwards messages from any AstrBot platform adapter to an external persona LLM agent (personagent) and relays its replies back.
-version: 0.2.0
+version: 0.3.0
 author: wangkant
 repo: https://github.com/wangkant/personagent

persona_agent/agent.py

@@ -759,7 +759,22 @@ async def handle_gateway(self, event: dict) -> dict:
                     self._gateway_inflight[gateway_key] = remaining
                 else:
                     self._gateway_inflight.pop(gateway_key, None)
-        return {"handled": bool(handled), "replies": sink.items}
+        # `owned` is not `handled`. See GatewaySink: a forwarder needs to know
+        # whether to suppress its own model, and "produced no reply" is the
+        # wrong signal for that — silence is frequently the persona's answer.
+        return {"handled": bool(handled), "owned": sink.owned,
+                "replies": sink.items}
+
+    def _claim_gateway_turn(self) -> None:
+        """Mark the current gateway turn as ours, whatever it decides to say.
+
+        Called once the admission gates pass, which is the moment the answer
+        to "is this conversation mine" is known — everything after it is about
+        what to say, including saying nothing.
+        """
+        sink = current_sink.get()
+        if sink is not None:
+            sink.owned = True
 
     async def _handle_inner(self, payload: dict) -> bool:
         if not self.enabled:
@@ -806,6 +821,7 @@ async def _handle_inner(self, payload: dict) -> bool:
             if current_sink.get() is None or channels.is_native(user_id):
                 if not is_owner and user_id not in self.private_allowed_qqs:
                     return False
+            self._claim_gateway_turn()
             if mid is not None:
                 self._remember_msg_id(mid)
             # Gateway DM keys are forwarder-chosen → register in the LRU so an
@@ -827,6 +843,7 @@ async def _handle_inner(self, payload: dict) -> bool:
                 and (current_sink.get() is None or channels.is_native(group_id)) \
                 and group_id not in self.allowed_groups:
             return False
+        self._claim_gateway_turn()
         if mid is not None:
             self._remember_msg_id(mid)
         # Gateway group keys are forwarder-chosen → register in the LRU.

persona_agent/gateway.py

@@ -152,6 +152,13 @@ class GatewaySink:
     def __init__(self) -> None:
         self.items: list[dict] = []
         self.closed = False
+        # Set once this turn clears the admission gates. It answers a
+        # different question than `items`: whether the conversation is OURS,
+        # not whether we chose to speak in it. A forwarder that conflates the
+        # two hands every deliberate silence — a PASS, a debounce merge, a
+        # rhythm-gate skip — to its own built-in model, which then answers as
+        # someone else in a conversation this persona had decided to sit out.
+        self.owned = False
 
     def add(self, message) -> bool:
         if self.closed:

tests/test_astrbot_plugin.py

@@ -140,6 +140,17 @@ async def post(self, url, **kwargs):
         return response
 
 
+class _SilentButOwnedClient(_RecordingClient):
+    """An agent that took the conversation and chose to say nothing."""
+
+    async def post(self, url, **kwargs):
+        self.calls.append((url, kwargs))
+        response = _Response()
+        response.json = lambda: {
+            "handled": False, "owned": True, "replies": []}
+        return response
+
+
 class _Event:
     def __init__(self, module, *, private: bool):
         message_type = (
@@ -239,7 +250,7 @@ def test_signed_request_uses_canonical_body_and_replay_headers():
     ).hexdigest()
 
     try:
-        delivered, replies = asyncio.run(plugin._post_to_agent(event))
+        delivered, _owned, replies = asyncio.run(plugin._post_to_agent(event))
     finally:
         module.time.time = real_time
         module.secrets.token_hex = real_token_hex
@@ -275,9 +286,9 @@ def test_off_host_endpoint_requires_https_and_a_token():
     )
 
     assert asyncio.run(
-        insecure._post_to_agent({"message": "hello"})) == (False, [])
+        insecure._post_to_agent({"message": "hello"})) == (False, False, [])
     assert asyncio.run(
-        no_token._post_to_agent({"message": "hello"})) == (False, [])
+        no_token._post_to_agent({"message": "hello"})) == (False, False, [])
     assert insecure._client.calls == []
     assert no_token._client.calls == []
 
@@ -293,7 +304,7 @@ def test_malformed_endpoint_is_rejected_without_a_request():
     )
 
     assert asyncio.run(
-        plugin._post_to_agent({"message": "hello"})) == (False, [])
+        plugin._post_to_agent({"message": "hello"})) == (False, False, [])
     assert plugin._client.calls == []
 
 
@@ -310,7 +321,7 @@ def test_forwarding_failure_does_not_stop_astrbot_fallback():
     event = _Event(module, private=True)
 
     async def fail(_neutral_event):
-        return False, []
+        return False, False, []
 
     plugin._post_to_agent = fail
 
@@ -341,6 +352,31 @@ async def collect():
     assert event.stopped is False
 
 
+def test_a_silent_but_owned_conversation_blocks_the_fallback():
+    """The agent is quiet far more often than it speaks — a PASS, a debounce
+    merge, the rhythm gate. Treating that as "not mine" hands the room to
+    AstrBot's own model, which answers in it as someone else. The test above
+    pins the other direction: an agent too old to send `owned` still falls
+    back to `handled`, so nothing changes for it."""
+    module = _import_plugin()
+    plugin = _plugin_instance(
+        module,
+        {
+            "private_enabled": True,
+            "private_whitelist": ["user-1"],
+            "block_default": True,
+        },
+    )
+    plugin._client = _SilentButOwnedClient()
+    event = _Event(module, private=True)
+
+    async def collect():
+        return [item async for item in plugin.forward_to_agent(event)]
+
+    assert asyncio.run(collect()) == []
+    assert event.stopped is True
+
+
 def test_forwarded_event_carries_source_timestamp_and_success_blocks_fallback():
     module = _import_plugin()
     plugin = _plugin_instance(
@@ -356,7 +392,7 @@ def test_forwarded_event_carries_source_timestamp_and_success_blocks_fallback():
 
     async def succeed(neutral_event):
         captured.update(neutral_event)
-        return True, []
+        return True, True, []
 
     plugin._post_to_agent = succeed
 
@@ -398,6 +434,7 @@ async def collect():
         test_malformed_endpoint_is_rejected_without_a_request,
         test_forwarding_failure_does_not_stop_astrbot_fallback,
         test_unhandled_gateway_response_does_not_stop_astrbot_fallback,
+        test_a_silent_but_owned_conversation_blocks_the_fallback,
         test_forwarded_event_carries_source_timestamp_and_success_blocks_fallback,
         test_missing_source_timestamp_is_not_forwarded_or_blocked,
     ]