patchbai 0.1.0__py3-none-any.whl

patchbai/__init__.py

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

patchbai/__main__.py

@@ -0,0 +1,10 @@
+from patchbai.app import PatchbaiApp
+
+
+def main() -> int:
+    PatchbaiApp().run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

patchbai/actions.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    name: str
+    callable: Callable
+    description: str
+    args_schema: dict
+
+
+class ActionRegistry:
+    """Enumerable action registry — name → ActionSpec."""
+
+    def __init__(self) -> None:
+        self._actions: dict[str, ActionSpec] = {}
+
+    def register(self, name: str, fn: Callable, *, description: str, args_schema: dict) -> None:
+        self._actions[name] = ActionSpec(
+            name=name, callable=fn, description=description, args_schema=args_schema,
+        )
+
+    def get(self, name: str) -> ActionSpec:
+        if name not in self._actions:
+            raise KeyError(f"unknown action: {name}")
+        return self._actions[name]
+
+    def list(self) -> list[ActionSpec]:
+        return sorted(self._actions.values(), key=lambda s: s.name)
+
+    def invoke(self, name: str, args: dict) -> Any:
+        spec = self.get(name)
+        return spec.callable(**(args or {}))

patchbai/activity/log.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime
+
+
+class ActivityKind:
+    """String constants for entry kinds. Plain class instead of an Enum so
+    `entry.kind == ActivityKind.AGENT_SPAWNED` and `entry.kind == "agent.spawned"`
+    are both valid — keeps test tables and the mode-filter dict ergonomic."""
+
+    AGENT_SPAWNED = "agent.spawned"
+    AGENT_STATE = "agent.state"
+    AGENT_DONE = "agent.done"
+    AGENT_MESSAGE = "agent.message"
+    AGENT_TOOL = "agent.tool"
+    AGENT_ASK = "agent.ask"
+    AGENT_NOTIFY = "agent.notify"
+    AGENT_ARCHIVE = "agent.archive"
+    ORCH_USER = "orch.user"
+    ORCH_REPLY = "orch.reply"
+    ORCH_SESSION = "orch.session"
+    LAYOUT_APPLIED = "layout.applied"
+    LAYOUT_FAILED = "layout.failed"
+    TAB_ADDED = "tab.added"
+    TAB_CLOSED = "tab.closed"
+    TAB_SWITCHED = "tab.switched"
+    WORKSPACE_CWD = "workspace.cwd"
+    FILE_SELECTED = "file.selected"
+
+
+@dataclass(frozen=True)
+class ActivityEntry:
+    """One normalized record in the ActivityLog. `kind` is one of the
+    ActivityKind dotted-string constants; `raw` is the original event object
+    for debugging/forensics."""
+    timestamp: datetime
+    kind: str
+    summary: str
+    detail: str | None
+    agent_id: str | None
+    tab_id: str | None
+    raw: object
+
+
+from patchbai.events import (  # noqa: E402 — deferred to avoid circular import
+    ActivityLogged, AgentArchiveChanged, AgentMessageAppended,
+    AgentNotifiedOrchestrator, AgentRequestedUserInput, AgentSpawned,
+    AgentStateChanged, EventBus, FileSelected, LayoutApplied, LayoutFailed,
+    OrchestratorReply, OrchestratorSessionSwitched, TabAdded, TabClosed,
+    TabSwitched, UserMessageToOrchestrator, WorkspaceCwdChanged,
+)
+
+
+class ActivityLog:
+    """App-singleton capture of curated EventBus events. Stores the last 500
+    normalized entries in a deque. Publishes ActivityLogged after every
+    append so subscribers can react incrementally without re-walking the
+    backlog. Mode filtering is the consumer's responsibility — the log
+    captures the union."""
+
+    BUFFER_SIZE = 500
+
+    def __init__(self, bus: EventBus) -> None:
+        self._bus = bus
+        self._entries: deque[ActivityEntry] = deque(maxlen=self.BUFFER_SIZE)
+        self._wire_subscriptions(bus)
+
+    def entries(self) -> tuple[ActivityEntry, ...]:
+        """Snapshot of current entries, oldest first."""
+        return tuple(self._entries)
+
+    # --- subscriptions -----------------------------------------------------
+
+    def _wire_subscriptions(self, bus: EventBus) -> None:
+        bus.subscribe(AgentSpawned, self._on_agent_spawned)
+        bus.subscribe(AgentStateChanged, self._on_agent_state)
+        bus.subscribe(AgentMessageAppended, self._on_agent_message)
+        bus.subscribe(AgentRequestedUserInput, self._on_agent_ask)
+        bus.subscribe(AgentNotifiedOrchestrator, self._on_agent_notify)
+        bus.subscribe(AgentArchiveChanged, self._on_agent_archive)
+        bus.subscribe(UserMessageToOrchestrator, self._on_orch_user)
+        bus.subscribe(OrchestratorReply, self._on_orch_reply)
+        bus.subscribe(OrchestratorSessionSwitched, self._on_orch_session)
+        bus.subscribe(LayoutApplied, self._on_layout_applied)
+        bus.subscribe(LayoutFailed, self._on_layout_failed)
+        bus.subscribe(TabAdded, self._on_tab_added)
+        bus.subscribe(TabClosed, self._on_tab_closed)
+        bus.subscribe(TabSwitched, self._on_tab_switched)
+        bus.subscribe(WorkspaceCwdChanged, self._on_cwd_changed)
+        bus.subscribe(FileSelected, self._on_file_selected)
+
+    def _on_agent_spawned(self, event: AgentSpawned) -> None:
+        info = event.info
+        self._append(
+            kind=ActivityKind.AGENT_SPAWNED,
+            summary=f"{info.name} spawned",
+            detail=f"cwd: {info.cwd}",
+            agent_id=info.id,
+            tab_id=None,
+            raw=event,
+        )
+
+    def _on_agent_state(self, event: AgentStateChanged) -> None:
+        info = event.info
+        kind = ActivityKind.AGENT_DONE if info.state.is_terminal else ActivityKind.AGENT_STATE
+        summary = f"{info.name}: {event.old_state.value} → {info.state.value}"
+        self._append(
+            kind=kind, summary=summary, detail=None,
+            agent_id=info.id, tab_id=None, raw=event,
+        )
+
+    def _on_agent_message(self, event: AgentMessageAppended) -> None:
+        if event.role in ("user", "assistant"):
+            kind = ActivityKind.AGENT_MESSAGE
+            detail = event.text
+        elif event.role in ("tool_use", "tool_result"):
+            kind = ActivityKind.AGENT_TOOL
+            detail = event.tool_name or event.text
+        else:
+            return  # thinking/system are not surfaced in the feed
+        self._append(
+            kind=kind,
+            summary=event.agent_id,
+            detail=detail,
+            agent_id=event.agent_id,
+            tab_id=None,
+            raw=event,
+        )
+
+    def _on_agent_ask(self, event: AgentRequestedUserInput) -> None:
+        self._append(
+            kind=ActivityKind.AGENT_ASK,
+            summary=event.agent_id,
+            detail=event.question,
+            agent_id=event.agent_id,
+            tab_id=None,
+            raw=event,
+        )
+
+    def _on_agent_notify(self, event: AgentNotifiedOrchestrator) -> None:
+        self._append(
+            kind=ActivityKind.AGENT_NOTIFY,
+            summary=event.agent_id,
+            detail=event.message,
+            agent_id=event.agent_id,
+            tab_id=None,
+            raw=event,
+        )
+
+    def _on_agent_archive(self, event: AgentArchiveChanged) -> None:
+        info = event.info
+        self._append(
+            kind=ActivityKind.AGENT_ARCHIVE,
+            summary=f"{info.name} {'archived' if info.archived else 'unarchived'}",
+            detail=None,
+            agent_id=info.id,
+            tab_id=None,
+            raw=event,
+        )
+
+    def _on_orch_user(self, event: UserMessageToOrchestrator) -> None:
+        self._append(
+            kind=ActivityKind.ORCH_USER, summary="user → orchestrator",
+            detail=event.text, agent_id=None, tab_id=None, raw=event,
+        )
+
+    def _on_orch_reply(self, event: OrchestratorReply) -> None:
+        self._append(
+            kind=ActivityKind.ORCH_REPLY, summary="orchestrator → user",
+            detail=event.text, agent_id=None, tab_id=None, raw=event,
+        )
+
+    def _on_orch_session(self, event: OrchestratorSessionSwitched) -> None:
+        self._append(
+            kind=ActivityKind.ORCH_SESSION,
+            summary=f"session → {event.session_id[:8]}",
+            detail=event.transcript_path, agent_id=None, tab_id=None, raw=event,
+        )
+
+    def _on_layout_applied(self, event: LayoutApplied) -> None:
+        self._append(
+            kind=ActivityKind.LAYOUT_APPLIED,
+            summary=event.layout_name or "(unnamed)",
+            detail=None, agent_id=None, tab_id=event.tab_id, raw=event,
+        )
+
+    def _on_layout_failed(self, event: LayoutFailed) -> None:
+        self._append(
+            kind=ActivityKind.LAYOUT_FAILED, summary="layout failed",
+            detail=event.error, agent_id=None, tab_id=event.tab_id, raw=event,
+        )
+
+    def _on_tab_added(self, event: TabAdded) -> None:
+        self._append(
+            kind=ActivityKind.TAB_ADDED, summary=event.title, detail=None,
+            agent_id=None, tab_id=event.tab_id, raw=event,
+        )
+
+    def _on_tab_closed(self, event: TabClosed) -> None:
+        self._append(
+            kind=ActivityKind.TAB_CLOSED, summary=event.tab_id, detail=None,
+            agent_id=None, tab_id=event.tab_id, raw=event,
+        )
+
+    def _on_tab_switched(self, event: TabSwitched) -> None:
+        self._append(
+            kind=ActivityKind.TAB_SWITCHED, summary=event.title, detail=None,
+            agent_id=None, tab_id=event.tab_id, raw=event,
+        )
+
+    def _on_cwd_changed(self, event: WorkspaceCwdChanged) -> None:
+        self._append(
+            kind=ActivityKind.WORKSPACE_CWD, summary=event.cwd, detail=None,
+            agent_id=None, tab_id=None, raw=event,
+        )
+
+    def _on_file_selected(self, event: FileSelected) -> None:
+        self._append(
+            kind=ActivityKind.FILE_SELECTED, summary=event.path, detail=None,
+            agent_id=None, tab_id=None, raw=event,
+        )
+
+    # --- append ------------------------------------------------------------
+
+    def _append(
+        self, *, kind: str, summary: str, detail: str | None,
+        agent_id: str | None, tab_id: str | None, raw: object,
+    ) -> None:
+        entry = ActivityEntry(
+            timestamp=datetime.now(),
+            kind=kind, summary=summary, detail=detail,
+            agent_id=agent_id, tab_id=tab_id, raw=raw,
+        )
+        self._entries.append(entry)
+        self._bus.publish(ActivityLogged(entry=entry))

patchbai/agents/child_tools.py

@@ -0,0 +1,66 @@
+import asyncio
+
+from claude_agent_sdk import create_sdk_mcp_server, tool
+
+from patchbai.agents.request_inbox import RequestInbox
+from patchbai.events import (
+    AgentNotifiedOrchestrator,
+    AgentRequestedUserInput,
+    EventBus,
+)
+
+
+def build_child_tools(*, agent_id: str, bus: EventBus, inbox: RequestInbox):
+    """Return (notify_handler, ask_handler) — bare async callables for unit tests."""
+
+    async def notify_orchestrator(args: dict) -> dict:
+        message = args["message"]
+        bus.publish(AgentNotifiedOrchestrator(agent_id=agent_id, message=message))
+        return {"content": [{"type": "text", "text": "Notification delivered."}]}
+
+    async def ask_orchestrator(args: dict) -> dict:
+        question = args["question"]
+        timeout_s = float(args.get("timeout_s", 300))
+        request_id = inbox.register()
+        bus.publish(
+            AgentRequestedUserInput(
+                agent_id=agent_id, question=question, request_id=request_id
+            )
+        )
+        try:
+            response = await inbox.wait(request_id, timeout_s=timeout_s)
+            return {"content": [{"type": "text", "text": response}]}
+        except asyncio.TimeoutError:
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": (
+                            f"ask_orchestrator timed out after {timeout_s}s "
+                            "with no response."
+                        ),
+                    }
+                ]
+            }
+
+    return notify_orchestrator, ask_orchestrator
+
+
+def build_child_mcp_server(*, agent_id: str, bus: EventBus, inbox: RequestInbox):
+    notify_h, ask_h = build_child_tools(agent_id=agent_id, bus=bus, inbox=inbox)
+    notify = tool(
+        "notify_orchestrator",
+        "Send a fire-and-forget notification to the orchestrator.",
+        {"message": str},
+    )(notify_h)
+    ask = tool(
+        "ask_orchestrator",
+        (
+            "Ask the orchestrator a question and block until they respond. "
+            "Optional timeout_s defaults to 300 seconds."
+        ),
+        {"question": str},  # timeout_s is optional, not in schema
+    )(ask_h)
+    return create_sdk_mcp_server(
+        name="patchbai_child", version="1.0.0", tools=[notify, ask]
+    )

patchbai/agents/fake_sdk_adapter.py

@@ -0,0 +1,45 @@
+from typing import AsyncIterator
+
+from claude_agent_sdk import ClaudeAgentOptions
+
+
+class FakeSDKAdapter:
+    """Replays canned message streams. One script per expected query call."""
+
+    def __init__(self, scripts: list[list[object]]) -> None:
+        self._scripts = scripts
+        self._next_query_index = 0
+        self._pending: list[object] = []
+        self._started = False
+
+    async def start(self, *, options: ClaudeAgentOptions) -> None:
+        self._started = True
+
+    async def query(self, prompt: str) -> None:
+        assert self._started, "start() must be called before query()"
+        if self._next_query_index >= len(self._scripts):
+            raise IndexError(
+                f"FakeSDKAdapter has no script for query #{self._next_query_index} "
+                f"(only {len(self._scripts)} provided)"
+            )
+        self._pending = list(self._scripts[self._next_query_index])
+        self._next_query_index += 1
+
+    def stream(self) -> AsyncIterator[object]:
+        # Snapshot _pending into a local so calling stream() then mutating
+        # _pending mid-iteration doesn't cause skipping.
+        msgs = self._pending
+        self._pending = []
+
+        async def _agen() -> AsyncIterator[object]:
+            for m in msgs:
+                yield m
+
+        return _agen()
+
+    async def interrupt(self) -> None:
+        # No-op for the fake.
+        return
+
+    async def stop(self) -> None:
+        self._started = False

patchbai/agents/manager.py

@@ -0,0 +1,272 @@
+import dataclasses
+import time
+import uuid
+from pathlib import Path
+from typing import Callable
+
+from claude_agent_sdk import ClaudeAgentOptions
+
+from patchbai.agents.child_tools import build_child_mcp_server
+from patchbai.agents.request_inbox import RequestInbox
+from patchbai.agents.sdk_adapter import SDKAdapter
+from patchbai.agents.session import AgentSession
+from patchbai.agents.state import AgentInfo, AgentState
+from patchbai.events import (
+    AgentArchiveChanged,
+    AgentSpawned,
+    AgentStateChanged,
+    DirectMessageToAgent,
+    EventBus,
+)
+from patchbai.persistence.agents_index import AgentsIndex
+from patchbai.persistence.transcript_store import AgentTranscript, TranscriptEntry
+
+
+class AgentManager:
+    """Owns child AgentSessions: spawn / list / read transcript / interrupt / kill."""
+
+    def __init__(
+        self,
+        *,
+        cwd: Path,
+        bus: EventBus,
+        adapter_factory: Callable[[], SDKAdapter],
+    ) -> None:
+        self._cwd = cwd
+        self._bus = bus
+        self._adapter_factory = adapter_factory
+        self._sessions: dict[str, AgentSession] = {}
+        self._inboxes: dict[str, RequestInbox] = {}
+        self._index = AgentsIndex(cwd=cwd)
+        # Any agent persisted as still-running belongs to a previous (dead)
+        # process. Flip those rows to ERROR so the AgentTable seed doesn't
+        # show ghosts as live.
+        self._index.reconcile_orphans()
+        self._unsub_state = bus.subscribe(AgentStateChanged, self._on_state_changed)
+        self._unsub_direct = bus.subscribe(DirectMessageToAgent, self._on_direct_message)
+
+    async def spawn(
+        self,
+        *,
+        name: str,
+        prompt: str,
+        cwd: str | None = None,
+        allowed_tools: list[str] | None = None,
+        disallowed_tools: list[str] | None = None,
+        model: str | None = None,
+        system_prompt: str | None = None,
+    ) -> str:
+        agent_id = uuid.uuid4().hex[:12]
+        now = time.time()
+        # Snapshot the JSON-serializable subset of options needed to rebuild
+        # ClaudeAgentOptions on resume. mcp_servers can't be persisted (it
+        # contains live server objects); we rebuild it from agent_id+bus+inbox
+        # in _build_options instead.
+        spawn_options = {
+            "cwd": cwd or str(self._cwd),
+            "allowed_tools": allowed_tools,
+            "disallowed_tools": disallowed_tools,
+            "model": model,
+            "system_prompt": system_prompt,
+        }
+        info = AgentInfo(
+            id=agent_id,
+            name=name,
+            cwd=cwd or str(self._cwd),
+            started_at=now,
+            spawn_options=spawn_options,
+        )
+        session = self._build_session(info)
+        self._index.upsert(info)
+        self._bus.publish(AgentSpawned(info=info))
+
+        await session.start(options=self._build_options(info))
+        await session.send(prompt)
+        return agent_id
+
+    def _build_session(self, info: AgentInfo) -> AgentSession:
+        adapter = self._adapter_factory()
+        transcript = AgentTranscript(cwd=self._cwd, agent_id=info.id)
+        session = AgentSession(
+            info=info,
+            adapter=adapter,
+            transcript=transcript,
+            bus=self._bus,
+            on_session_id=lambda sid, _id=info.id: self._on_session_id(_id, sid),
+        )
+        # Inbox lifecycle drives session state: count > 0 → WAITING,
+        # count == 0 → restore prior state. _mark_unwaiting is defensively
+        # a no-op outside WAITING, so a `kill()` mid-wait that drains the
+        # future after the session is gone is safe.
+        def _on_pending_changed(count: int, _session=session) -> None:
+            if count > 0:
+                _session._mark_waiting()
+            else:
+                _session._mark_unwaiting()
+
+        self._inboxes[info.id] = RequestInbox(
+            on_pending_changed=_on_pending_changed,
+        )
+        self._sessions[info.id] = session
+        return session
+
+    def _build_options(
+        self, info: AgentInfo, *, resume_session_id: str | None = None,
+    ) -> ClaudeAgentOptions:
+        # Bypass permissions for now: there's no Textual modal to render
+        # the SDK's permission prompts in plan 2, so the child would hang.
+        # The orchestrator can still narrow what a child may do via the
+        # allowed_tools / disallowed_tools args on the spawn_agent MCP tool.
+        # A proper can_use_tool callback that pops a Textual approval modal
+        # is plan-3 work.
+        child_mcp = build_child_mcp_server(
+            agent_id=info.id, bus=self._bus, inbox=self._inboxes[info.id],
+        )
+        opts = info.spawn_options or {}
+        kwargs: dict = {
+            "cwd": opts.get("cwd") or info.cwd,
+            "permission_mode": "bypassPermissions",
+            "mcp_servers": {"patchbai_child": child_mcp},
+        }
+        if opts.get("allowed_tools") is not None:
+            kwargs["allowed_tools"] = opts["allowed_tools"]
+        if opts.get("disallowed_tools") is not None:
+            kwargs["disallowed_tools"] = opts["disallowed_tools"]
+        if opts.get("model") is not None:
+            kwargs["model"] = opts["model"]
+        if opts.get("system_prompt") is not None:
+            kwargs["system_prompt"] = opts["system_prompt"]
+        if resume_session_id is not None:
+            kwargs["resume"] = resume_session_id
+        return ClaudeAgentOptions(**kwargs)
+
+    def _on_session_id(self, agent_id: str, session_id: str) -> None:
+        # The first ResultMessage carries the SDK session id. Capture it on
+        # the persisted info so a fresh process can pass it back as resume=
+        # to keep the conversation alive.
+        session = self._sessions.get(agent_id)
+        if session is None:
+            return
+        session.info.session_id = session_id
+        self._index.upsert(session.info)
+
+    async def resume(self, agent_id: str) -> AgentSession | None:
+        # If the agent already has a live session, just hand it back.
+        existing = self._sessions.get(agent_id)
+        if existing is not None:
+            return existing
+        # Find the persisted record. If it's missing, or it predates the
+        # resume feature (no session_id / no spawn_options), we can't bring
+        # it back to life — caller must spawn fresh.
+        for info in self._index.load():
+            if info.id == agent_id:
+                target = info
+                break
+        else:
+            return None
+        if target.session_id is None or target.spawn_options is None:
+            return None
+        # Resurrect: fresh adapter, AgentSession, and SDK process pointed at
+        # the same session_id so the conversation continues.
+        target.state = AgentState.IDLE
+        target.ended_at = None
+        session = self._build_session(target)
+        self._index.upsert(target)
+        self._bus.publish(AgentSpawned(info=target))
+        await session.start(
+            options=self._build_options(target, resume_session_id=target.session_id),
+        )
+        return session
+
+    def list_infos(self) -> list[AgentInfo]:
+        return [s.info for s in self._sessions.values()]
+
+    def get_session(self, agent_id: str) -> AgentSession | None:
+        return self._sessions.get(agent_id)
+
+    def read_transcript(self, agent_id: str) -> list[TranscriptEntry]:
+        path_transcript = AgentTranscript(cwd=self._cwd, agent_id=agent_id)
+        return path_transcript.read_all()
+
+    async def interrupt(self, agent_id: str) -> None:
+        session = self._sessions.get(agent_id)
+        if session is not None:
+            await session.interrupt()
+
+    async def kill(self, agent_id: str) -> None:
+        session = self._sessions.pop(agent_id, None)
+        self._inboxes.pop(agent_id, None)
+        if session is not None:
+            await session.stop()
+
+    async def wait_idle(self, agent_id: str) -> None:
+        session = self._sessions.get(agent_id)
+        if session is not None:
+            await session.wait_idle()
+
+    async def send(self, agent_id: str, text: str) -> None:
+        session = self._sessions.get(agent_id)
+        if session is None:
+            raise KeyError(f"unknown agent_id: {agent_id}")
+        await session.send(text)
+
+    def get_inbox(self, agent_id: str) -> RequestInbox | None:
+        return self._inboxes.get(agent_id)
+
+    def set_archived(self, agent_id: str, *, archived: bool) -> None:
+        """Toggle the archived flag for an agent. Persists to agents.json and
+        publishes AgentArchiveChanged so listeners (e.g., AgentTable) can
+        refresh. Raises KeyError if `agent_id` is unknown."""
+        # The archived flag is metadata, not runtime state — agents from a
+        # previous process show up in the table (seeded from agents.json) but
+        # have no live session here. Fall back to the persisted record so
+        # archive/unarchive works on those rows too.
+        session = self._sessions.get(agent_id)
+        if session is not None:
+            info = session.info
+        else:
+            info = next(
+                (i for i in self._index.load() if i.id == agent_id), None
+            )
+            if info is None:
+                raise KeyError(f"unknown agent_id: {agent_id}")
+        if info.archived == archived:
+            return
+        info.archived = archived
+        self._index.upsert(info)
+        # Publish a frozen snapshot so subscribers see a stable view.
+        self._bus.publish(AgentArchiveChanged(info=dataclasses.replace(info)))
+
+    async def shutdown(self) -> None:
+        for agent_id in list(self._sessions.keys()):
+            await self.kill(agent_id)
+        self._unsub_state()
+        self._unsub_direct()
+
+    # --- internals --------------------------------------------------------
+
+    def _on_state_changed(self, event: AgentStateChanged) -> None:
+        # Persist updated info on every state change so agents.json reflects reality.
+        self._index.upsert(event.info)
+
+    def _on_direct_message(self, event: DirectMessageToAgent) -> None:
+        session = self._sessions.get(event.agent_id)
+        if session is not None:
+            session.queue_send(event.text)
+            return
+        # No live session: this is a record from a previous process. Try to
+        # resurrect it via SDK resume so the user's message lands on a real
+        # conversation. Schedule on the running loop because EventBus
+        # handlers must be sync.
+        import asyncio
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return  # no loop — nothing we can do (e.g. unit-test without loop)
+        loop.create_task(self._resume_then_send(event.agent_id, event.text))
+
+    async def _resume_then_send(self, agent_id: str, text: str) -> None:
+        session = await self.resume(agent_id)
+        if session is None:
+            return  # legacy record without session_id/spawn_options
+        session.queue_send(text)