roomkit 0.7.2__tar.gz → 0.8.0__tar.gz

{roomkit-0.7.2 → roomkit-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roomkit
-Version: 0.7.2
+Version: 0.8.0
 Summary: Pure async Python library for multi-channel conversations
 Project-URL: Homepage, https://roomkit.live
 Project-URL: Documentation, https://www.roomkit.live/docs/
@@ -350,7 +350,7 @@ For development:
 git clone https://github.com/roomkit-live/roomkit.git
 cd roomkit
 uv sync --extra dev
-make all                               # ruff check + mypy --strict + pytest
+make all                               # ruff check + ty + pytest
 ```
 
 Requires **Python 3.12+**.
@@ -729,7 +729,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.
 
 ```bash
 uv sync --extra dev
-make all                # ruff check + mypy --strict + pytest
+make all                # ruff check + ty + pytest
 ```
 
 All new code needs tests. Aim for >90% coverage.

{roomkit-0.7.2 → roomkit-0.8.0}/README.md

@@ -140,7 +140,7 @@ For development:
 git clone https://github.com/roomkit-live/roomkit.git
 cd roomkit
 uv sync --extra dev
-make all                               # ruff check + mypy --strict + pytest
+make all                               # ruff check + ty + pytest
 ```
 
 Requires **Python 3.12+**.
@@ -519,7 +519,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.
 
 ```bash
 uv sync --extra dev
-make all                # ruff check + mypy --strict + pytest
+make all                # ruff check + ty + pytest
 ```
 
 All new code needs tests. Aim for >90% coverage.

roomkit-0.8.0/src/roomkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.8.0"

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/channels/_ai_context.py

@@ -53,6 +53,7 @@ class AIContextHost(Protocol):
         _max_tokens: Default max tokens (overridable per room).
         _thinking_budget: Optional thinking budget for extended thinking.
         _skills: Skill registry for tool injection.
+        _skills_in_prompt: Whether to auto-inject the skills manifest into the prompt.
         _script_executor: Script executor for skill scripts.
         _sandbox: Sandbox executor for ad-hoc command execution.
         _memory: Memory provider for conversation retrieval.
@@ -75,6 +76,7 @@ class AIContextHost(Protocol):
     _max_tokens: int
     _thinking_budget: int | None
     _skills: SkillRegistry | None
+    _skills_in_prompt: bool
     _script_executor: ScriptExecutor | None
     _sandbox: SandboxExecutor | None
     _human_input_handler: HumanInputToolHandler | None
@@ -105,6 +107,7 @@ class AIContextMixin:
     _max_tokens: int
     _thinking_budget: int | None
     _skills: SkillRegistry | None
+    _skills_in_prompt: bool
     _script_executor: ScriptExecutor | None
     _sandbox: SandboxExecutor | None
     _human_input_handler: HumanInputToolHandler | None
@@ -183,15 +186,18 @@ class AIContextMixin:
                 existing_names = {t.name for t in tools}
                 tools.extend(t for t in hi_tools if t.name not in existing_names)
 
-        # Inject skill tools and prompt (infra tools added here, gated tools later)
+        # Inject skill tools and prompt (infra tools added here, gated tools later).
+        # The prompt block is skipped when the host renders its own skills
+        # manifest inside ``system_prompt`` (``skills_in_prompt=False``).
         if self._skills and self._skills.skill_count > 0:
             tools.extend(self._skill_tools())
-            preamble = _SKILLS_PREAMBLE
-            if not self._script_executor:
-                preamble += _SKILLS_NO_SCRIPTS_NOTE
-            skills_xml = self._skills.to_prompt_xml()
-            skill_block = f"\n\n{preamble}\n\n{skills_xml}"
-            system_prompt = (system_prompt or "") + skill_block
+            if self._skills_in_prompt:
+                preamble = _SKILLS_PREAMBLE
+                if not self._script_executor:
+                    preamble += _SKILLS_NO_SCRIPTS_NOTE
+                skills_xml = self._skills.to_prompt_xml()
+                skill_block = f"\n\n{preamble}\n\n{skills_xml}"
+                system_prompt = (system_prompt or "") + skill_block
 
         # Inject sandbox tools and preamble
         if self._sandbox is not None:

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/channels/_ai_generation.py

@@ -87,6 +87,7 @@ class AIGenerationHost(Protocol):
     _max_tool_rounds: int
     _tool_loop_timeout_seconds: float | None
     _tool_loop_warn_after: int
+    _max_empty_retries: int
     _tool_handler: Any
     _active_loops: dict[str, _ToolLoopContext]
     _after_response_hook: Any
@@ -143,6 +144,7 @@ class AIGenerationMixin:
     _max_tool_rounds: int
     _tool_loop_timeout_seconds: float | None
     _tool_loop_warn_after: int
+    _max_empty_retries: int
     _tool_handler: Any
     _active_loops: dict[str, _ToolLoopContext]
     _after_response_hook: Any
@@ -429,16 +431,19 @@ class AIGenerationMixin:
         self, context: AIContext, *, parent_span_id: str | None = None
     ) -> ToolLoopResult:
         """Generate -> execute tools -> re-generate until a text response."""
-        from roomkit.channels.ai import _current_loop_ctx, _ToolLoopContext
+        from roomkit.channels.ai import (
+            _EMPTY_RETRY_NUDGE,
+            _current_loop_ctx,
+            _ToolLoopContext,
+        )
 
-        loop_ctx = _ToolLoopContext()
-        loop_ctx.loop_id = str(id(loop_ctx))
-        parent_lctx = _current_loop_ctx.get()
-        if parent_lctx is not None:
-            loop_ctx.current_participant_role = parent_lctx.current_participant_role
+        loop_ctx = _ToolLoopContext.for_loop(
+            _current_loop_ctx.get(), context.room.room.id if context.room else None
+        )
         _current_loop_ctx.set(loop_ctx)
         self._active_loops[loop_ctx.loop_id] = loop_ctx
         rounds: list[ToolRound] = []
+        empty_retries = 0
         try:
             context, should_cancel = self._drain_steering_queue(context, loop_ctx)
             if should_cancel:
@@ -462,6 +467,28 @@ class AIGenerationMixin:
 
             for round_idx in range(self._max_tool_rounds):
                 if not response.tool_calls or self._tool_handler is None:
+                    # Final answer reached. If it is empty *after* we ran tools,
+                    # the model skipped verbalizing the result — re-prompt once
+                    # (bounded) for the final answer instead of returning nothing.
+                    if (
+                        self._tool_handler is not None
+                        and rounds
+                        and not (response.content or "").strip()
+                        and empty_retries < self._max_empty_retries
+                        and not loop_ctx.cancel_event.is_set()
+                        and not (deadline and asyncio.get_running_loop().time() >= deadline)
+                    ):
+                        empty_retries += 1
+                        logger.warning(
+                            "Empty response after %d tool round(s); re-prompting for "
+                            "final answer (retry %d/%d)",
+                            len(rounds),
+                            empty_retries,
+                            self._max_empty_retries,
+                        )
+                        context.messages.append(AIMessage(role="user", content=_EMPTY_RETRY_NUDGE))
+                        response = await self._generate_with_retry(context)
+                        continue
                     break
 
                 if loop_ctx.cancel_event.is_set():

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/channels/_ai_streaming.py

@@ -70,6 +70,7 @@ class AIStreamingHost(Protocol):
     _max_tool_rounds: int
     _tool_loop_timeout_seconds: float | None
     _tool_loop_warn_after: int
+    _max_empty_retries: int
     _tool_handler: Any
     _active_loops: dict[str, _ToolLoopContext]
     _after_response_hook: Any
@@ -126,6 +127,7 @@ class AIStreamingMixin:
     _max_tool_rounds: int
     _tool_loop_timeout_seconds: float | None
     _tool_loop_warn_after: int
+    _max_empty_retries: int
     _tool_handler: Any
     _active_loops: dict[str, Any]
     _after_response_hook: Any
@@ -235,26 +237,42 @@ class AIStreamingMixin:
         self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
     ) -> ChannelOutput:
         """Return a streaming response that handles tool calls between rounds."""
+        from roomkit.channels.ai import _current_loop_ctx
+
         ai_context = await self._build_context(event, binding, context)  # ty: ignore[unresolved-attribute]
         ai_context, blocked = await self._fire_before_generation_hook(ai_context, event)  # ty: ignore[unresolved-attribute]
         if blocked:
             return ChannelOutput.empty()
+        # The generator below executes when the CONSUMER iterates the
+        # stream — by then handle_event has reset the loop contextvar, so
+        # the parent ctx (participant role, room, the toolset stamped by
+        # _build_context) must be captured NOW and passed explicitly.
         return ChannelOutput(
             responded=True,
-            response_stream=self._run_streaming_tool_loop(ai_context),
+            response_stream=self._run_streaming_tool_loop(
+                ai_context, parent_loop_ctx=_current_loop_ctx.get()
+            ),
             response_metadata=ai_context.response_metadata,
         )
 
-    async def _run_streaming_tool_loop(self, context: AIContext) -> AsyncIterator[StreamDelta]:
+    async def _run_streaming_tool_loop(
+        self, context: AIContext, *, parent_loop_ctx: Any | None = None
+    ) -> AsyncIterator[StreamDelta]:
         """Stream text deltas, executing tool calls between generation rounds."""
-        from roomkit.channels.ai import _current_loop_ctx, _ToolLoopContext
+        from roomkit.channels.ai import (
+            _EMPTY_RETRY_NUDGE,
+            _current_loop_ctx,
+            _ToolLoopContext,
+        )
         from roomkit.telemetry.context import get_current_span
 
-        loop_ctx = _ToolLoopContext()
-        loop_ctx.loop_id = str(id(loop_ctx))
-        parent_ctx = _current_loop_ctx.get()
-        if parent_ctx is not None:
-            loop_ctx.current_participant_role = parent_ctx.current_participant_role
+        # The handle_event ctx is gone from the contextvar by the time this
+        # generator runs (reset in handle_event's finally); the caller
+        # captured it at stream creation.
+        parent_ctx = parent_loop_ctx if parent_loop_ctx is not None else _current_loop_ctx.get()
+        loop_ctx = _ToolLoopContext.for_loop(
+            parent_ctx, context.room.room.id if context.room else None
+        )
         _current_loop_ctx.set(loop_ctx)
         self._active_loops[loop_ctx.loop_id] = loop_ctx
         telemetry = self._telemetry_provider
@@ -287,6 +305,8 @@ class AIStreamingMixin:
             )
 
             _dedup_prefix = ""
+            _saw_tool_call_any = False
+            _empty_retries = 0
 
             for _round_idx in range(self._max_tool_rounds + 1):
                 if loop_ctx.cancel_event.is_set():
@@ -465,8 +485,28 @@ class AIStreamingMixin:
                     )
 
                 if not tool_calls:
+                    # Final answer round. If it produced no text *after* a tool
+                    # round, the model skipped verbalizing the result — re-prompt
+                    # once (bounded) for the final answer instead of ending empty.
+                    if (
+                        _saw_tool_call_any
+                        and not "".join(text_parts).strip()
+                        and _empty_retries < self._max_empty_retries
+                        and not (deadline and asyncio.get_running_loop().time() >= deadline)
+                    ):
+                        _empty_retries += 1
+                        logger.warning(
+                            "Streaming empty response after tools; re-prompting for "
+                            "final answer (retry %d/%d)",
+                            _empty_retries,
+                            self._max_empty_retries,
+                        )
+                        context.messages.append(AIMessage(role="user", content=_EMPTY_RETRY_NUDGE))
+                        continue
                     return
 
+                _saw_tool_call_any = True
+
                 # External tools: provider executed them internally.
                 # If ExternalToolHandler is set, hooks were already fired
                 # inline during streaming (see StreamToolCall handling above).

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/channels/_tool_eviction.py

@@ -21,15 +21,30 @@ class ToolEviction:
     stored in a FIFO-bounded buffer and replaced with a head/tail preview.
     The ``read_tool_result`` tool definition is injected into the AI
     context so the agent can paginate back through the full output.
+
+    The store is scoped per room: the eviction buffer lives on a channel
+    object shared by every room the channel serves, so an unscoped buffer
+    would leak one conversation's tool output into another (and inject
+    the re-read tool into rooms that evicted nothing). The room comes
+    from the tool-loop context; paths outside a loop share one fallback
+    scope.
     """
 
     def __init__(self, threshold_tokens: int = 5000) -> None:
         self.threshold_tokens = threshold_tokens
-        self._store: OrderedDict[str, str] = OrderedDict()
+        self._store: OrderedDict[tuple[str, str], str] = OrderedDict()
+
+    @staticmethod
+    def _room_scope() -> str:
+        from roomkit.channels.ai import _current_loop_ctx
+
+        ctx = _current_loop_ctx.get()
+        return (ctx.room_id if ctx is not None else None) or ""
 
     @property
     def has_evicted(self) -> bool:
-        return bool(self._store)
+        room = self._room_scope()
+        return any(key[0] == room for key in self._store)
 
     def maybe_evict(self, result: str, tool_call_id: str = "") -> str:
         """Evict large results to the store, returning a preview."""
@@ -38,7 +53,7 @@ class ToolEviction:
             return result
 
         result_id = f"evicted_{tool_call_id}" if tool_call_id else f"evicted_{id(result)}"
-        self._store[result_id] = result
+        self._store[(self._room_scope(), result_id)] = result
         while len(self._store) > _MAX_EVICTED:
             self._store.popitem(last=False)
 
@@ -71,11 +86,11 @@ class ToolEviction:
         offset = arguments.get("offset", 0)
         limit = arguments.get("limit", 200)
 
-        full_result = self._store.get(result_id)
+        room = self._room_scope()
+        full_result = self._store.get((room, result_id))
         if full_result is None:
-            return json.dumps(
-                {"error": f"Result '{result_id}' not found", "available": list(self._store.keys())}
-            )
+            available = [rid for scope, rid in self._store if scope == room]
+            return json.dumps({"error": f"Result '{result_id}' not found", "available": available})
 
         # Char budget per page: threshold_tokens chars ≈ threshold/4 tokens of
         # content, leaving ample headroom for JSON escaping (worst case 2×)

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/channels/ai.py

@@ -89,16 +89,44 @@ class _ToolLoopContext:
     activated_skills: set[str] = field(default_factory=set)
     all_context_tools: list[Any] = field(default_factory=list)
     current_participant_role: str | None = None
+    room_id: str | None = None
     steering_queue: asyncio.Queue[SteeringDirective] = field(default_factory=asyncio.Queue)
     cancel_event: asyncio.Event = field(default_factory=asyncio.Event)
     loop_id: str = ""
 
+    @classmethod
+    def for_loop(cls, parent: _ToolLoopContext | None, room_id: str | None) -> _ToolLoopContext:
+        """Create a tool-loop context inheriting per-turn state from *parent*.
+
+        _build_context ran under the parent (handle_event) ctx and stamped the
+        turn's full toolset there — without this inheritance the per-round
+        tools re-application never fires (skill-gated tools would stay hidden
+        after activation) and per-call allowlist accessors see nothing.
+        """
+        ctx = cls()
+        ctx.loop_id = str(id(ctx))
+        if parent is not None:
+            ctx.current_participant_role = parent.current_participant_role
+            ctx.all_context_tools = parent.all_context_tools
+        ctx.room_id = room_id or (parent.room_id if parent else None)
+        return ctx
+
 
 _current_loop_ctx: contextvars.ContextVar[_ToolLoopContext | None] = contextvars.ContextVar(
     "_current_loop_ctx", default=None
 )
 
 
+# Corrective nudge re-injected when a generation round ends after tool calls
+# without any final text (common with small local models): the tool results
+# are in context, the model just failed to verbalize the answer. Re-prompting
+# for the final answer recovers it. Bounded by ``max_empty_retries``.
+_EMPTY_RETRY_NUDGE = (
+    "You called tools and already have their results above. Now write your "
+    "final answer to the user in plain text. Do not call any more tools."
+)
+
+
 class AIChannel(
     AIStreamingMixin,
     AIGenerationMixin,
@@ -129,9 +157,11 @@ class AIChannel(
         max_tool_rounds: int = 200,
         tool_loop_timeout_seconds: float | None = 300.0,
         tool_loop_warn_after: int = 50,
+        max_empty_retries: int = 1,
         retry_policy: RetryPolicy | None = None,
         fallback_provider: AIProvider | None = None,
         skills: SkillRegistry | None = None,
+        skills_in_prompt: bool = True,
         script_executor: ScriptExecutor | None = None,
         sandbox: SandboxExecutor | None = None,
         external_tool_handler: ExternalToolHandler | None = None,
@@ -157,9 +187,15 @@ class AIChannel(
         self._max_tool_rounds = max_tool_rounds
         self._tool_loop_timeout_seconds = tool_loop_timeout_seconds
         self._tool_loop_warn_after = tool_loop_warn_after
+        self._max_empty_retries = max_empty_retries
         self._retry_policy = retry_policy
         self._fallback_provider = fallback_provider
         self._skills = skills
+        # Hosts that render their own skills manifest inside ``system_prompt``
+        # (e.g. positioned above a prompt-cache boundary) set this to False to
+        # skip the automatic preamble+XML injection while keeping the skill
+        # activation tools.
+        self._skills_in_prompt = skills_in_prompt
         self._script_executor = script_executor
         self._sandbox = sandbox
         self._memory = memory or SlidingWindowMemory(max_events=max_context_events)
@@ -310,14 +346,24 @@ class AIChannel(
 
         # Resolve participant role for role-based tool policy.
         # Set on a per-invocation _ToolLoopContext visible via contextvar so that
-        # _build_context and the tool loop methods can read it.
+        # _build_context and the tool loop methods can read it. ``room_id``
+        # rides the same contextvar: the channel object is registered once
+        # per channel_id and shared by every room it serves, so per-call
+        # room resolution (``current_tool_room_id``) is the only safe way
+        # for tool handlers to learn the originating room.
         event_ctx = _ToolLoopContext()
         event_ctx.current_participant_role = self._resolve_participant_role(event, context)
+        event_ctx.room_id = context.room.id if context.room else event.room_id
         token = _current_loop_ctx.set(event_ctx)
         try:
             raw_tools = binding.metadata.get("tools", [])
+            # A config_provider may deliver tools at _build_context time even
+            # when the binding carries no snapshot — route to the tool loop
+            # so those tools are executable. An empty turn toolset just runs
+            # the loop for a single round.
             has_tools = (
                 bool(raw_tools)
+                or self._config_provider is not None
                 or bool(self._user_tools)
                 or bool(self._injected_tools)
                 or (self._skills is not None and self._skills.skill_count > 0)

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/core/event_router.py

@@ -148,22 +148,15 @@ class EventRouter:
 
         result = BroadcastResult()
 
-        # Check source can write
-        if source_binding.access in (Access.READ_ONLY, Access.NONE):
+        # Check source can write (RFC §7.5). Inbound events from non-writable
+        # sources are already blocked before broadcast in the inbound pipeline;
+        # this guards reentry events and any direct broadcast callers.
+        if not source_binding.can_write:
             logger.debug(
-                "Source %s has no write access",
-                source_binding.channel_id,
-                extra={"room_id": event.room_id, "channel_id": source_binding.channel_id},
-            )
-            reset_span(broadcast_token)
-            telemetry.end_span(span_id, attributes={"target_count": 0})
-            return result
-
-        # Check source is not muted
-        if source_binding.muted:
-            logger.debug(
-                "Source %s is muted",
+                "Source %s cannot write (access=%s, muted=%s) — not broadcasting",
                 source_binding.channel_id,
+                source_binding.access,
+                source_binding.muted,
                 extra={"room_id": event.room_id, "channel_id": source_binding.channel_id},
             )
             reset_span(broadcast_token)

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/core/framework.py

@@ -53,6 +53,7 @@ from roomkit.core.mixins import (
     InboundStreamingMixin,
     RealtimeOpsMixin,
     RecordingMixin,
+    RegenerateMixin,
     RoomLifecycleMixin,
     SourceOpsMixin,
     VoiceOpsMixin,
@@ -60,6 +61,7 @@ from roomkit.core.mixins import (
 from roomkit.core.transcoder import DefaultContentTranscoder
 from roomkit.identity.base import IdentityResolver
 from roomkit.models.channel import RateLimit
+from roomkit.models.context import RoomContext
 from roomkit.models.enums import (
     ChannelType,
     EventStatus,
@@ -105,6 +107,7 @@ class RoomKit(
     InboundIdentityMixin,
     InboundLockedMixin,
     InboundStreamingMixin,
+    RegenerateMixin,
     ChannelOpsMixin,
     RoomLifecycleMixin,
     VoiceOpsMixin,
@@ -510,19 +513,23 @@ class RoomKit(
         )
         token = set_current_span(span_id, telemetry_ctx=telemetry.get_span_context(span_id))
         try:
+            # Direct injection traverses the SAME locked pipeline as inbound
+            # (RFC §10.5): index assignment, BEFORE_BROADCAST hooks, edit/delete
+            # handling, source write-permission gate, persistence, broadcast,
+            # reentry drain and AFTER_BROADCAST hooks. This keeps a single
+            # validation/hooks/indexing/persistence model across entry points.
+            pending_after_broadcast: list[tuple[RoomEvent, RoomContext]] = []
             async with self._lock_manager.locked(room_id):
-                count = await self._store.get_event_count(room_id)
-                event = event.model_copy(update={"index": count})
-                await self._persist_event(event)
-
                 context = await self._build_context(room_id)
-                router = self._get_router()
-                await router.broadcast(event, binding, context)
-
-                # Run AFTER_BROADCAST hooks for observability and fan-out
-                await self._hook_engine.run_async_hooks(
-                    room_id, HookTrigger.AFTER_BROADCAST, event, context
+                result = await self._process_locked(
+                    event,
+                    room_id,
+                    context,
+                    pending_after_broadcast_out=pending_after_broadcast,
                 )
+            event = result.event or event
+            # AFTER_BROADCAST runs outside the room lock (RFC §10.1)
+            await self._run_deferred_after_broadcast(room_id, pending_after_broadcast)
 
             telemetry.end_span(span_id)
         except Exception as exc:

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/core/mixins/__init__.py

@@ -14,6 +14,7 @@ from roomkit.core.mixins.inbound_locked import InboundLockedMixin
 from roomkit.core.mixins.inbound_streaming import InboundStreamingMixin
 from roomkit.core.mixins.realtime_ops import RealtimeOpsMixin
 from roomkit.core.mixins.recording import RecordingMixin
+from roomkit.core.mixins.regenerate import RegenerateMixin
 from roomkit.core.mixins.room_lifecycle import RoomLifecycleMixin
 from roomkit.core.mixins.source_ops import SourceOpsMixin
 from roomkit.core.mixins.voice_ops import VoiceOpsMixin
@@ -33,6 +34,7 @@ __all__ = [
     "InboundStreamingMixin",
     "RealtimeOpsMixin",
     "RecordingMixin",
+    "RegenerateMixin",
     "RoomLifecycleMixin",
     "SourceOpsMixin",
     "VoiceOpsMixin",

{roomkit-0.7.2 → roomkit-0.8.0}/src/roomkit/core/mixins/inbound.py

@@ -9,11 +9,13 @@ from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 from roomkit.core.exceptions import ChannelNotRegisteredError
 from roomkit.core.mixins.helpers import HelpersMixin
 from roomkit.core.mixins.inbound_identity import _IdentityBlockedError
+from roomkit.models.context import RoomContext
 from roomkit.models.delivery import InboundMessage, InboundResult
 from roomkit.models.enums import (
     ChannelType,
     HookTrigger,
 )
+from roomkit.models.event import RoomEvent
 
 if TYPE_CHECKING:
     from roomkit.channels.base import Channel
@@ -47,6 +49,7 @@ class InboundHost(Protocol):
     Cross-mixin methods (provided by other mixins in the MRO):
         _resolve_identity: From :class:`InboundIdentityMixin`.
         _process_locked: From :class:`InboundLockedMixin`.
+        _run_deferred_after_broadcast: From :class:`InboundLockedMixin`.
         _process_streaming_responses: From :class:`InboundStreamingMixin`.
         create_room: From :class:`RoomLifecycleMixin`.
         attach_channel: From :class:`ChannelOpsMixin`.
@@ -88,6 +91,7 @@ class InboundMixin(HelpersMixin):
     # Cross-mixin methods — attribute annotations avoid MRO shadowing
     _resolve_identity: Any  # see InboundHost
     _process_locked: Any  # see InboundHost
+    _run_deferred_after_broadcast: Any  # see InboundHost
     _process_streaming_responses: Any  # see InboundHost
     create_room: Any  # see InboundHost
     attach_channel: Any  # see InboundHost
@@ -181,6 +185,11 @@ class InboundMixin(HelpersMixin):
         # Let channel process inbound
         event = await channel.handle_inbound(message, context)
 
+        # Caller-requested visibility (e.g. ``"transport"`` for a proactive
+        # notification that must not wake the room's intelligence channel).
+        if message.visibility != "all" and event.visibility == "all":
+            event = event.model_copy(update={"visibility": message.visibility})
+
         # Identity resolution pipeline (RFC §7)
         try:
             event, resolved_identity, pending_id_result = await self._resolve_identity(
@@ -191,6 +200,7 @@ class InboundMixin(HelpersMixin):
 
         # Process under room lock
         pending_streams: list[Any] = []
+        pending_after_broadcast: list[tuple[RoomEvent, RoomContext]] = []
         async with self._lock_manager.locked(room_id):
             try:
                 result: InboundResult = await asyncio.wait_for(
@@ -201,6 +211,7 @@ class InboundMixin(HelpersMixin):
                         resolved_identity=resolved_identity,
                         pending_id_result=pending_id_result,
                         pending_streams_out=pending_streams,
+                        pending_after_broadcast_out=pending_after_broadcast,
                     ),
                     timeout=self._process_timeout,
                 )
@@ -218,6 +229,11 @@ class InboundMixin(HelpersMixin):
                 )
                 return InboundResult(blocked=True, reason="process_timeout")
 
+        # Run AFTER_BROADCAST async hooks now that the room lock is released
+        # (RFC §10.1) — a slow observer hook no longer blocks concurrent
+        # process_inbound calls for the same room.
+        await self._run_deferred_after_broadcast(room_id, pending_after_broadcast)
+
         # Handle streaming responses outside lock (TTS delivery can take seconds;
         # holding the lock would block concurrent process_inbound calls)
         if pending_streams: