@ngocsangairvds/vsaf 3.2.16 → 4.0.1

package/tools/vds-scripts/telegram_bridge/daemon/commands.py

@@ -1,457 +0,0 @@
-"""Telegram /commands handlers (P1-F partial — Wave 1 subset only).
-
-Wave 1 ships /start /help /spawn /sessions. Wave 3 expands to the full
-12-command surface (TSK-6.1–6.8) including /attach /detach /audit /tail
-/end /rename /subscribe /unsubscribe.
-
-`/start` semantics (FR-1.2.3): if no supergroup is registered AND the chat
-is a supergroup with forum topics enabled, register it. Otherwise reply
-with a status message. Subsequent /start from a different chat is silently
-dropped (the allow-list middleware already restricts to one user, and the
-supergroup_id is pinned in vds_telegram_supergroups).
-"""
-
-from __future__ import annotations
-
-import contextlib
-from pathlib import Path
-from typing import TYPE_CHECKING
-from uuid import UUID
-
-import structlog
-from aiogram import F, Router
-from aiogram.filters import Command
-
-from telegram_bridge.daemon.audit import (
-    PostgresUnavailable,
-)
-from telegram_bridge.daemon.registry_loader import (
-    AgentEntry,
-    SupportLevel,
-    find_runner_module,
-)
-from telegram_bridge.daemon.runner_orchestrator import (
-    RunnerOrchestrator,
-    RunnerSpawnRequest,
-)
-
-if TYPE_CHECKING:
-    from aiogram.types import Message
-
-    from telegram_bridge.daemon.config import Settings
-    from telegram_bridge.daemon.pg import PgPool
-    from telegram_bridge.daemon.session_registry import SessionRegistry
-
-log = structlog.get_logger(__name__)
-
-
-def build_router(
-    *,
-    settings: Settings,
-    pg: PgPool,
-    registry: SessionRegistry,
-    orchestrator: RunnerOrchestrator,
-    agents: dict[str, AgentEntry],
-) -> Router:
-    """Build the aiogram Router for Wave-1 commands.
-
-    Returned router should be `dp.include_router(...)`-ed by the daemon's
-    Dispatcher, ahead of any catch-all message handlers.
-    """
-    router = Router(name="telegram_bridge.commands")
-
-    @router.message(Command("start"))
-    async def _start(message: Message) -> None:
-        """One-time supergroup registration (FR-1.2.3)."""
-        chat = message.chat
-        # Only honour /start in a supergroup with forum topics enabled.
-        if chat.type != "supergroup" or not getattr(chat, "is_forum", False):
-            await message.answer(
-                "telegram-bridge requires a supergroup with forum topics enabled. See `references/setup.md`."
-            )
-            return
-
-        async with pg.pool.acquire() as conn:
-            existing_row = await conn.fetchrow("SELECT supergroup_id FROM vds_telegram_supergroups LIMIT 1")
-            if existing_row is None:
-                await conn.execute(
-                    """
-                    INSERT INTO vds_telegram_supergroups (supergroup_id, user_id, title)
-                    VALUES ($1, $2, $3)
-                    """,
-                    chat.id,
-                    settings.VDS_TELEGRAM_USER_ID,
-                    chat.title or "telegram-bridge supergroup",
-                )
-                await message.answer(
-                    f"<b>registered</b>\nsupergroup_id: <code>{chat.id}</code>\ntelegram-bridge is now homed here."
-                )
-                return
-
-            if existing_row["supergroup_id"] != chat.id:
-                # Silent drop in a different chat (FR-1.2.3).
-                log.info(
-                    "commands.start.drop_other_chat",
-                    seen_chat_id=chat.id,
-                    registered=existing_row["supergroup_id"],
-                )
-                return
-
-            await message.answer(f"already registered (supergroup_id <code>{chat.id}</code>). daemon healthy.")
-
-    @router.message(Command("help"))
-    async def _help(message: Message) -> None:
-        cmds = [
-            "/start — one-time supergroup registration",
-            "/help — show this list",
-            "/sessions — list active and idle sessions",
-            "/spawn &lt;agent&gt; [cwd] — start a new agent session",
-            "(more commands land in Wave 3: /attach /detach /audit /tail /end /rename /subscribe /unsubscribe)",
-        ]
-        agent_lines = [f"  <code>{name}</code> ({entry.support_level.value})" for name, entry in sorted(agents.items())]
-        await message.answer(
-            "<b>telegram-bridge</b>\n\n" + "\n".join(cmds) + "\n\n<b>agents</b>\n" + "\n".join(agent_lines)
-        )
-
-    @router.message(Command("sessions"))
-    async def _sessions(message: Message) -> None:
-        rows = registry.list_active()
-        if not rows:
-            await message.answer("no active sessions.")
-            return
-        lines = []
-        for r in rows:
-            lines.append(f"  <code>{str(r.id)[:8]}</code> {r.agent_id} {r.status.value} cwd=<code>{r.cwd}</code>")
-        await message.answer("<b>sessions</b>\n" + "\n".join(lines))
-
-    @router.message(Command("spawn"))
-    async def _spawn(message: Message) -> None:
-        """`/spawn <agent> [cwd]` — create a new session."""
-        text = message.text or ""
-        parts = text.split(maxsplit=2)
-        if len(parts) < 2:
-            await message.answer("usage: /spawn &lt;agent&gt; [cwd]")
-            return
-        agent_id = parts[1]
-        cwd = Path(parts[2]) if len(parts) > 2 else Path.home()
-
-        if agent_id not in agents:
-            await message.answer(f"unknown agent <code>{agent_id}</code>. available: {', '.join(sorted(agents))}")
-            return
-
-        entry = agents[agent_id]
-        if entry.support_level == SupportLevel.PLANNED:
-            await message.answer(
-                f"agent <code>{agent_id}</code> is `planned` — run `vds-cli telegram agent smoke {agent_id}` first."
-            )
-            return
-
-        for env_var in entry.requires_env:
-            if not getattr(settings, env_var, None):
-                await message.answer(
-                    f"agent <code>{agent_id}</code> requires env var <code>{env_var}</code>; not set in ~/.vds/.env"
-                )
-                return
-
-        rec = await registry.create_session(
-            agent_id=agent_id,
-            cwd=str(cwd),
-            parent_id=None,
-        )
-        socket_path = settings.VDS_TELEGRAM_RUNNER_DIR / "runners" / f"{rec.id}.sock"
-        # For the generic acp-runner, ship the command array as JSON in env
-        # (the runner subprocess reads VDS_TELEGRAM_RUNNER_ACP_COMMAND).
-        extra_env: dict[str, str] = {}
-        if entry.runner == "acp-runner" and entry.command is not None:
-            import json
-
-            extra_env["VDS_TELEGRAM_RUNNER_ACP_COMMAND"] = json.dumps(entry.command)
-        request = RunnerSpawnRequest(
-            session_id=rec.id,
-            agent_id=agent_id,
-            runner_module=find_runner_module(entry),
-            cwd=cwd,
-            socket_path=socket_path,
-            extra_env=extra_env or None,
-        )
-        await orchestrator.spawn(request)
-        warning = ""
-        if entry.support_level == SupportLevel.EXPERIMENTAL:
-            warning = " ⚠ <i>experimental — please report issues</i>"
-        await message.answer(f"<b>spawned</b> <code>{agent_id}</code> session <code>{str(rec.id)[:8]}</code>{warning}")
-
-    @router.message(Command("attach"))
-    async def _attach(message: Message) -> None:
-        """`/attach <topic-id>` — mark current chat as attached to a session
-        running elsewhere (e.g., a terminal-only session)."""
-        text = message.text or ""
-        parts = text.split(maxsplit=1)
-        if len(parts) < 2:
-            await message.answer("usage: /attach &lt;topic-id&gt;")
-            return
-        try:
-            topic_id = int(parts[1])
-        except ValueError:
-            await message.answer("topic-id must be an integer")
-            return
-        async with pg.pool.acquire() as conn:
-            row = await conn.fetchrow(
-                "SELECT session_id FROM vds_telegram_topics WHERE telegram_topic_id = $1",
-                topic_id,
-            )
-        if row is None:
-            await message.answer(f"no session bound to topic <code>{topic_id}</code>")
-            return
-        await registry.attach_telegram(row["session_id"], topic_id)
-        await message.answer(
-            f"attached chat to session <code>{str(row['session_id'])[:8]}</code> via topic <code>{topic_id}</code>"
-        )
-
-    @router.message(Command("detach"))
-    async def _detach(message: Message) -> None:
-        """`/detach` (inside a topic) — remove Telegram from session's surfaces_attached."""
-        if message.message_thread_id is None:
-            await message.answer("/detach must be used inside a session topic")
-            return
-        async with pg.pool.acquire() as conn:
-            row = await conn.fetchrow(
-                "SELECT session_id FROM vds_telegram_topics WHERE telegram_topic_id = $1",
-                message.message_thread_id,
-            )
-        if row is None:
-            await message.answer("this topic isn't bound to a session")
-            return
-        from telegram_bridge.daemon.session_registry import UnknownSessionError
-
-        try:
-            await registry.detach_surface(row["session_id"], f"telegram:{message.message_thread_id}")
-            await message.answer("detached")
-        except UnknownSessionError:
-            await message.answer("session not in registry (already ended)")
-
-    @router.message(Command("audit"))
-    async def _audit(message: Message) -> None:
-        """`/audit [n] [topic_id]` — last n events from the audit log."""
-        text = message.text or ""
-        parts = text.split()
-        n = 20
-        topic_id: int | None = message.message_thread_id
-        if len(parts) > 1:
-            with contextlib.suppress(ValueError):
-                n = max(1, min(100, int(parts[1])))
-        if len(parts) > 2:
-            with contextlib.suppress(ValueError):
-                topic_id = int(parts[2])
-
-        async with pg.pool.acquire() as conn:
-            if topic_id is not None and topic_id != 1:
-                # Topic-scoped query
-                rows = await conn.fetch(
-                    """
-                    SELECT e.ts, e.seq, e.event_type, e.source_surface
-                    FROM   vds_telegram_session_events e
-                    JOIN   vds_telegram_topics t ON t.session_id = e.session_id
-                    WHERE  t.telegram_topic_id = $1
-                    ORDER BY e.ts DESC
-                    LIMIT $2
-                    """,
-                    topic_id,
-                    n,
-                )
-            else:
-                rows = await conn.fetch(
-                    """
-                    SELECT e.ts, e.seq, e.event_type, e.source_surface, e.session_id
-                    FROM   vds_telegram_session_events e
-                    ORDER BY e.ts DESC
-                    LIMIT $1
-                    """,
-                    n,
-                )
-
-        if not rows:
-            await message.answer("no audit events found")
-            return
-
-        lines = ["<pre>"]
-        for r in rows:
-            sid_part = f" {str(r['session_id'])[:8]}" if "session_id" in r and topic_id is None else ""
-            lines.append(
-                f"{r['ts'].isoformat(timespec='seconds')} "
-                f"#{r['seq']:5d} {r['event_type']:24s} "
-                f"<- {r['source_surface']}{sid_part}"
-            )
-        lines.append("</pre>")
-        await message.answer("\n".join(lines))
-
-    @router.message(Command("tail"))
-    async def _tail(message: Message) -> None:
-        """`/tail [topic_id]` — last 20 events from a topic into current chat."""
-        text = message.text or ""
-        parts = text.split()
-        topic_id: int | None = message.message_thread_id
-        if len(parts) > 1:
-            with contextlib.suppress(ValueError):
-                topic_id = int(parts[1])
-        if topic_id is None or topic_id == 1:
-            await message.answer("usage: /tail &lt;topic-id&gt; (or run /tail inside a session topic)")
-            return
-
-        async with pg.pool.acquire() as conn:
-            rows = await conn.fetch(
-                """
-                SELECT e.ts, e.event_type, e.payload
-                FROM   vds_telegram_session_events e
-                JOIN   vds_telegram_topics t ON t.session_id = e.session_id
-                WHERE  t.telegram_topic_id = $1
-                ORDER BY e.ts DESC
-                LIMIT 20
-                """,
-                topic_id,
-            )
-
-        if not rows:
-            await message.answer(f"no events in topic <code>{topic_id}</code>")
-            return
-
-        import json
-
-        lines = [f"<b>tail topic {topic_id}</b>", "<pre>"]
-        for r in reversed(rows):
-            payload_str = json.dumps(r["payload"], ensure_ascii=False)[:120]
-            lines.append(f"{r['ts'].strftime('%H:%M:%S')} {r['event_type']:24s} {payload_str}")
-        lines.append("</pre>")
-        await message.answer("\n".join(lines))
-
-    @router.message(Command("end"))
-    async def _end(message: Message) -> None:
-        """`/end` (inside a topic) — force session end."""
-        if message.message_thread_id is None:
-            await message.answer("/end must be used inside a session topic")
-            return
-        async with pg.pool.acquire() as conn:
-            row = await conn.fetchrow(
-                "SELECT session_id FROM vds_telegram_topics WHERE telegram_topic_id = $1",
-                message.message_thread_id,
-            )
-        if row is None:
-            await message.answer("topic not bound to a session")
-            return
-        await orchestrator.stop(row["session_id"], reason="user_end")
-        await message.answer("session ended")
-
-    @router.message(Command("rename"))
-    async def _rename(message: Message) -> None:
-        """`/rename <title>` (inside a topic) — update topic title."""
-        if message.message_thread_id is None:
-            await message.answer("/rename must be used inside a session topic")
-            return
-        text = message.text or ""
-        parts = text.split(maxsplit=1)
-        if len(parts) < 2:
-            await message.answer("usage: /rename &lt;new-title&gt;")
-            return
-        new_title = parts[1].strip()[:128]
-        if not new_title:
-            await message.answer("title can't be empty")
-            return
-        from aiogram import Bot
-
-        bot = message.bot
-        assert isinstance(bot, Bot)
-        await bot.edit_forum_topic(
-            chat_id=message.chat.id,
-            message_thread_id=message.message_thread_id,
-            name=new_title,
-        )
-        async with pg.pool.acquire() as conn:
-            await conn.execute(
-                "UPDATE vds_telegram_topics SET title = $1 WHERE telegram_topic_id = $2",
-                new_title,
-                message.message_thread_id,
-            )
-        await message.answer(f"renamed to <code>{new_title}</code>")
-
-    @router.message(Command("subscribe"))
-    async def _subscribe(message: Message) -> None:
-        """`/subscribe <agent_type>` — always-promote spawns of agent_type."""
-        text = message.text or ""
-        parts = text.split(maxsplit=1)
-        if len(parts) < 2:
-            await message.answer("usage: /subscribe &lt;agent_type&gt;")
-            return
-        agent_type = parts[1].strip()
-        if not agent_type:
-            return
-        async with pg.pool.acquire() as conn:
-            await conn.execute(
-                """
-                INSERT INTO vds_telegram_topic_subscriptions (user_id, agent_type)
-                VALUES ($1, $2)
-                ON CONFLICT (user_id, agent_type) DO NOTHING
-                """,
-                settings.VDS_TELEGRAM_USER_ID,
-                agent_type,
-            )
-        await message.answer(f"subscribed: <code>{agent_type}</code> spawns will get their own topic immediately")
-
-    @router.message(Command("unsubscribe"))
-    async def _unsubscribe(message: Message) -> None:
-        text = message.text or ""
-        parts = text.split(maxsplit=1)
-        if len(parts) < 2:
-            await message.answer("usage: /unsubscribe &lt;agent_type&gt;")
-            return
-        agent_type = parts[1].strip()
-        async with pg.pool.acquire() as conn:
-            result = await conn.execute(
-                """
-                DELETE FROM vds_telegram_topic_subscriptions
-                WHERE user_id = $1 AND agent_type = $2
-                """,
-                settings.VDS_TELEGRAM_USER_ID,
-                agent_type,
-            )
-        await message.answer(f"unsubscribed <code>{agent_type}</code> ({result})")
-
-    @router.message(F.text & ~F.text.startswith("/"))
-    async def _text_to_runner(message: Message) -> None:
-        """Forward non-command text typed inside a session topic to the runner.
-
-        Only fires when:
-          * the message has text (not media — media is handled by uploads.py),
-          * the text is NOT a slash-command (Command handlers above already
-            claim their patterns; this filter excludes them),
-          * the message is in a forum topic that maps to an active session.
-
-        Strict-audit: PostgresUnavailable from orchestrator.send_input means
-        we refuse to forward and reply with a degraded notice (TSK-7.7).
-        """
-        thread_id = message.message_thread_id
-        if thread_id is None or thread_id == 1:
-            # General topic or non-forum chat — ignored. Use /spawn first.
-            return
-        async with pg.pool.acquire() as conn:
-            row = await conn.fetchrow(
-                "SELECT session_id FROM vds_telegram_topics WHERE telegram_topic_id = $1",
-                thread_id,
-            )
-        if row is None:
-            return  # orphan topic
-        session_id: UUID = row["session_id"]
-        text = message.text or ""
-        try:
-            await orchestrator.send_input(session_id, text=text, source_surface="telegram")
-        except KeyError:
-            await message.reply("session not active — start a new one with /spawn or resume via /attach")
-        except PostgresUnavailable:
-            log.warning(
-                "commands.text.degraded.pg_unavailable",
-                session_id=str(session_id),
-            )
-            await message.reply(
-                "⚠ service degraded — your message could not be audit-recorded. "
-                "Please retry once <code>vds-cli telegram status</code> reports healthy."
-            )
-
-    return router

package/tools/vds-scripts/telegram_bridge/daemon/config.py

@@ -1,129 +0,0 @@
-"""pydantic-settings model — reads ~/.vds/.env (mounted at /etc/vds/.env in container).
-
-Per FR-8.1 + feedback_feature_flags_in_dotenv.md: env vars from ~/.vds/.env must be
-inherited by both the daemon and runner subprocesses via uv run, NOT injected via
-inline shell. The Dockerfile entrypoint sources /etc/vds/.env before exec'ing the
-daemon; runner subprocess env is inherited from the daemon's environment dict.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from pydantic import Field, field_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-
-class Settings(BaseSettings):
-    """Daemon configuration sourced from ~/.vds/.env or process env."""
-
-    model_config = SettingsConfigDict(
-        env_file=("/etc/vds/.env", ".env"),  # /etc/vds/.env is the read-only mount in container
-        env_file_encoding="utf-8",
-        extra="ignore",  # the env file is shared with other VDS services; ignore unknown keys
-    )
-
-    # --- Required ---------------------------------------------------------
-
-    TELEGRAM_BOT_TOKEN: str = Field(
-        ...,
-        description="Bot token from @BotFather. Never logged.",
-        min_length=20,
-    )
-    VDS_TELEGRAM_USER_ID: int = Field(
-        ...,
-        description="Allow-listed Telegram user-id (FR-2.2). All other senders silently dropped.",
-    )
-
-    # --- Conditional (one or both depending on which agents are used) ----
-
-    ANTHROPIC_API_KEY: str | None = Field(
-        default=None,
-        description="Required by claude-sdk-runner (registry.yaml entry 'claude').",
-    )
-    OPENAI_API_KEY: str | None = Field(
-        default=None,
-        description="Required by codex-runner (registry.yaml entry 'codex').",
-    )
-
-    # --- Optional with documented defaults --------------------------------
-
-    VDS_TELEGRAM_SUPERGROUP_ID: int | None = Field(
-        default=None,
-        description="Populated by /start on first registration; persisted in vds_telegram_supergroups.",
-    )
-    VDS_TELEGRAM_DB_DSN: str = Field(
-        default="postgres://vds:vds@vds-postgres:5432/vds",
-        description="asyncpg DSN; defaults to existing VDS Postgres in same Compose project.",
-    )
-    VDS_TELEGRAM_RUNNER_DIR: Path = Field(
-        default=Path("/run/vds-telegram"),
-        description="UDS sockets parent directory. Mode 0o700; daemon-only.",
-    )
-    VDS_TELEGRAM_TOPIC_PROMOTION_THRESHOLD_S: int = Field(
-        default=30,
-        description="Subagent promotes to its own topic after this many seconds (FR-4.3 / Q9.8).",
-    )
-    VDS_TELEGRAM_AUDIT_RETENTION_DAYS: int = Field(
-        default=90,
-        description="Hot-retention window before nightly cold-rotation to parquet (FR-7.6).",
-    )
-    VDS_TELEGRAM_PARQUET_ROOT: Path = Field(
-        default=Path("/var/lib/vds-telegram/audit"),
-        description="Cold-storage root for parquet files written by the rotate job (FR-7.6). "
-        "Default targets a container-friendly path; override for host installs.",
-    )
-    VDS_TELEGRAM_AUDIT_REDACT_AWS_SECRET: bool = Field(
-        default=False,
-        description="Opt-in: enable the AWS_SECRET_KEY 40-char heuristic pattern. "
-        "WARNING: false-positives on git commit hashes — only enable when AWS access "
-        "key context is present in audit blobs (NFR-5.4).",
-    )
-    VDS_TELEGRAM_ACTIVE_TOPIC_SOFT_CAP: int = Field(
-        default=50,
-        description="Soft cap on active forum topics (FR-2.14); auto-archives oldest closed topic at cap.",
-    )
-    VDS_TELEGRAM_AGENTS_REGISTRY: Path = Field(
-        default=Path("/etc/vds/telegram_bridge/registry.yaml"),
-        description="Agent registry yaml path (FR-3.5). Override for tests.",
-    )
-    VDS_TELEGRAM_WORKSPACE_ROOTS: str = Field(
-        default="",
-        description="Comma-separated absolute paths to bind-mount RW (NFR-5.8). Empty = no host mount.",
-    )
-    VDS_TELEGRAM_ALLOW_BROAD_HOME_MOUNT: bool = Field(
-        default=False,
-        description="Opt-in to broad ${HOME} bind-mount (NFR-5.8). Documented security smell.",
-    )
-    VDS_TELEGRAM_AUDIT_REDACT_ENABLED: bool = Field(
-        default=True,
-        description="Pattern-redaction interceptor on by default (NFR-5.4 / ADR-13).",
-    )
-    VDS_TELEGRAM_AUDIT_REDACT_PATTERNS: str = Field(
-        default="",
-        description="Comma-separated additional regex patterns to redact (extends bundled defaults).",
-    )
-
-    VDS_TELEGRAM_NIGHTLY_HOUR_UTC: int = Field(
-        default=4,
-        description="Hour-of-day (UTC) to fire archive + rotate jobs (TSK-7.4 / TSK-7.5).",
-        ge=0,
-        le=23,
-    )
-
-    # Round-2 / claude-agent-sdk orphan-process bug (issue #22448) cap.
-    CLAUDE_CODE_MAXPROC: int = Field(default=4)
-
-    @field_validator("TELEGRAM_BOT_TOKEN")
-    @classmethod
-    def _bot_token_shape(cls, v: str) -> str:
-        # Light validation — a real bot token looks like "<digits>:<base64-ish>".
-        # Don't overdo it; failing here just helps surface obvious typos early.
-        if ":" not in v or len(v) < 20:
-            raise ValueError("TELEGRAM_BOT_TOKEN does not look like a Telegram bot token (missing ':' or too short)")
-        return v
-
-
-def load_settings() -> Settings:
-    """Load and cache the settings object once at startup."""
-    return Settings()

package/tools/vds-scripts/telegram_bridge/daemon/dispatcher.py

@@ -1,107 +0,0 @@
-"""Per-session bus dispatcher — fans out events to throttler + promoter.
-
-The audit subscriber writes BEFORE bus.publish (in runner_orchestrator), so
-this dispatcher does NOT subscribe `audit`. It subscribes the *post-audit*
-side-effect subscribers:
-  * `throttler` → ASSISTANT_CHUNK/COMPLETE drive editMessageText coalescing
-  * `topic_promoter` → SPAWN/SPAWN_END/TOOL_CALL_UPDATE/SESSION_END drive
-    forum-topic creation, parent announcements, child summaries
-
-One dispatcher per session, started on `attach(session_id)` and torn down
-on session end.
-"""
-
-from __future__ import annotations
-
-import asyncio
-from typing import TYPE_CHECKING
-from uuid import UUID
-
-import structlog
-
-from telegram_bridge.models.events import EventType
-
-if TYPE_CHECKING:
-    from telegram_bridge.daemon.bus import SessionBus
-    from telegram_bridge.daemon.throttler import StreamingThrottler
-    from telegram_bridge.daemon.topic_promoter import TopicPromoter
-
-log = structlog.get_logger(__name__)
-
-
-class SessionDispatcher:
-    """One per session. Spawns two subscriber tasks (throttler + promoter)."""
-
-    def __init__(
-        self,
-        *,
-        bus: SessionBus,
-        throttler: StreamingThrottler,
-        promoter: TopicPromoter,
-    ) -> None:
-        self._bus = bus
-        self._throttler = throttler
-        self._promoter = promoter
-        self._tasks: dict[UUID, list[asyncio.Task]] = {}
-
-    def attach(self, session_id: UUID) -> None:
-        """Subscribe throttler + promoter to events for this session."""
-        if session_id in self._tasks:
-            return
-        # Two independent labelled subscriptions — avoid "subscriber already
-        # registered" errors and let the bus log slow-subscriber drops per role.
-        throttler_iter = self._bus.subscribe(session_id, "throttler")
-        promoter_iter = self._bus.subscribe(session_id, "promoter")
-        t1 = asyncio.create_task(
-            self._throttler_loop(session_id, throttler_iter),
-            name=f"dispatcher-throttler-{session_id}",
-        )
-        t2 = asyncio.create_task(
-            self._promoter_loop(session_id, promoter_iter),
-            name=f"dispatcher-promoter-{session_id}",
-        )
-        self._tasks[session_id] = [t1, t2]
-
-    async def detach(self, session_id: UUID) -> None:
-        tasks = self._tasks.pop(session_id, None)
-        if not tasks:
-            return
-        for t in tasks:
-            t.cancel()
-        await asyncio.gather(*tasks, return_exceptions=True)
-        self._bus.unsubscribe(session_id, "throttler")
-        self._bus.unsubscribe(session_id, "promoter")
-
-    async def detach_all(self) -> None:
-        for sid in list(self._tasks.keys()):
-            await self.detach(sid)
-
-    async def _throttler_loop(self, session_id: UUID, aiter) -> None:
-        try:
-            async for event in aiter:
-                if event.event_type == EventType.ASSISTANT_CHUNK:
-                    delta = event.payload.get("delta", "")
-                    if delta:
-                        await self._throttler.on_chunk(session_id, delta)
-                elif event.event_type == EventType.ASSISTANT_COMPLETE:
-                    await self._throttler.on_complete(session_id)
-                elif event.event_type == EventType.SESSION_END:
-                    return
-        except asyncio.CancelledError:
-            raise
-        except Exception:
-            log.exception("dispatcher.throttler_loop.error", session_id=str(session_id))
-
-    async def _promoter_loop(self, session_id: UUID, aiter) -> None:
-        try:
-            async for event in aiter:
-                # Promoter tracks SPAWN/SPAWN_END/TOOL_CALL_UPDATE/SESSION_END
-                # for parent topics. Children topics get their own dispatcher
-                # via the orchestrator on subagent spawn.
-                await self._promoter.on_event(event)
-                if event.event_type == EventType.SESSION_END:
-                    return
-        except asyncio.CancelledError:
-            raise
-        except Exception:
-            log.exception("dispatcher.promoter_loop.error", session_id=str(session_id))