fix(deploy): fix 403 Forbidden and AttributeError in dashboard

.gitignore

@@ -0,0 +1,36 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Python cache and virtual env artifacts
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.ruff_cache/
+
+# Local environment files (keep template tracked)
+.env
+.env.*
+!.env.example

Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY bot/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY bot/ /app/bot/
+COPY dashboard/ /app/dashboard/
+# HF Spaces requires port 7860
+ENV PORT=7860
+EXPOSE 7860
+CMD ["python", "-m", "bot.main"]

README.md

@@ -0,0 +1,32 @@
+---
+title: Twitch Byte Bot
+emoji: 🤖
+colorFrom: purple
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# ByteBot Twitch (HF Space)
+
+Este é o deploy automático do ByteBot para a Twitch rodando no Hugging Face Spaces via Docker.
+
+## Configuração
+
+O bot precisa das seguintes variáveis de ambiente (configuradas no painel do Space em **Settings -> Repository Secrets**):
+
+- `NEBIUS_API_KEY`
+- `TWITCH_OWNER_ID`
+- `TWITCH_CLIENT_ID`
+- `TWITCH_BOT_ID`
+- `TWITCH_CHANNEL_ID`
+- `TWITCH_BOT_LOGIN`
+- `TWITCH_CHANNEL_LOGIN`
+- `TWITCH_USER_TOKEN`
+- `TWITCH_REFRESH_TOKEN`
+- `BYTE_DASHBOARD_ADMIN_TOKEN`
+- `SUPABASE_URL`
+- `SUPABASE_KEY`
+
+O bot usa o `duckduckgo-search` para current events e mantém a sessão ativa via self-heartbeat de 3 em 3 minutos.

bot/Dockerfile

@@ -0,0 +1,8 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY bot/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY bot/ /app/bot/
+COPY dashboard/ /app/dashboard/
+EXPOSE 8080
+CMD ["python", "-m", "bot.main"]

bot/access_control.py

@@ -0,0 +1,15 @@
+from typing import Any
+
+
+def is_owner(user_id: str, owner_id: str) -> bool:
+    return str(user_id) == str(owner_id)
+
+
+def is_moderator(author: Any) -> bool:
+    return bool(getattr(author, "is_mod", False)) or bool(
+        getattr(author, "is_moderator", False)
+    )
+
+
+def is_trusted_curator(author: Any, owner_id: str) -> bool:
+    return is_owner(getattr(author, "id", ""), owner_id) or is_moderator(author)

bot/autonomy_logic.py

@@ -0,0 +1,269 @@
+import time
+from typing import Any, Callable, Awaitable
+
+from bot.byte_semantics import format_chat_reply
+from bot.control_plane import (
+    RISK_AUTO_CHAT,
+    RISK_CLIP_CANDIDATE,
+    RISK_MODERATION_ACTION,
+    RISK_SUGGEST_STREAMER,
+    control_plane,
+)
+from bot.control_plane_constants import utc_iso
+from bot.hud_runtime import hud_runtime
+from bot.logic import MAX_REPLY_LENGTH, MAX_REPLY_LINES, agent_inference, context
+from bot.observability import observability
+from bot.runtime_config import CHANNEL_ID, ENABLE_LIVE_CONTEXT_LEARNING, client
+
+AutoChatDispatcher = Callable[[str], Awaitable[None]]
+
+def _clip_line(text: str, max_chars: int = 80) -> str:
+    compact = " ".join((text or "").split())
+    if len(compact) <= max_chars:
+        return compact
+    return compact[: max_chars - 3].rstrip() + "..."
+
+async def generate_goal_text(prompt: str, risk: str) -> str:
+    risk_hint = {
+        RISK_AUTO_CHAT: (
+            "Crie uma mensagem para o chat com valor imediato para a live. "
+            "Objetivo: estimular conversa util sem parecer spam."
+        ),
+        RISK_SUGGEST_STREAMER: (
+            "Crie uma sugestao objetiva para o streamer melhorar clareza, ritmo "
+            "ou engajamento nos proximos minutos."
+        ),
+        RISK_MODERATION_ACTION: (
+            "Identifique risco de moderacao e recomende acao conservadora com justificativa curta."
+        ),
+        RISK_CLIP_CANDIDATE: (
+            "Identifique um momento memoravel recente na live. "
+            "Se houver algo digno de clipe, descreva o motivo em 1 frase. "
+            "Se nao houver nada relevante, responda apenas 'NADA'."
+        ),
+    }.get(risk, "Responda com recomendacao objetiva.")
+    
+    autonomy_prompt = (
+        "Modo autonomia Byte para Twitch.\n"
+        f"Risco: {risk}\n"
+        f"Tarefa: {prompt}\n"
+        f"{risk_hint}\n"
+        "Contrato de saida: 1 mensagem, no maximo 4 linhas, alta densidade, sem markdown."
+    )
+    
+    answer = await agent_inference(
+        autonomy_prompt,
+        "autonomy",
+        client,
+        context,
+        enable_live_context=ENABLE_LIVE_CONTEXT_LEARNING,
+        max_lines=MAX_REPLY_LINES,
+        max_length=MAX_REPLY_LENGTH,
+    )
+    safe_text = format_chat_reply(str(answer or ""))
+    return safe_text.replace("[BYTE_SPLIT]", "").strip()
+
+async def process_autonomy_goal(
+    goal: dict[str, Any],
+    dispatcher: AutoChatDispatcher | None,
+) -> dict[str, Any]:
+    goal_id = str(goal.get("id", "goal") or "goal")
+    goal_name = _clip_line(str(goal.get("name", goal_id) or goal_id), max_chars=60)
+    risk = str(goal.get("risk", RISK_SUGGEST_STREAMER) or RISK_SUGGEST_STREAMER)
+    prompt = str(goal.get("prompt", "") or "").strip()
+    safe_prompt = prompt or f"Objetivo autonomo {goal_name}."
+
+    control_plane.register_goal_run(goal_id=goal_id, risk=risk)
+
+    generated_text = await generate_goal_text(prompt=safe_prompt, risk=risk)
+    if not generated_text:
+        control_plane.register_dispatch_failure("goal_generation_empty")
+        observability.record_error(
+            category="autonomy_goal",
+            details=f"{goal_id}: resposta vazia",
+        )
+        return {
+            "goal_id": goal_id,
+            "risk": risk,
+            "outcome": "generation_empty",
+        }
+
+    if risk == RISK_AUTO_CHAT:
+        return await _handle_auto_chat(goal_id, risk, goal_name, generated_text, dispatcher)
+
+    if risk == RISK_CLIP_CANDIDATE:
+        return _handle_clip_candidate(goal_id, risk, goal_name, generated_text)
+
+    return _handle_generic_suggestion(goal_id, risk, goal_name, safe_prompt, generated_text)
+
+async def _handle_auto_chat(
+    goal_id: str,
+    risk: str,
+    goal_name: str,
+    text: str,
+    dispatcher: AutoChatDispatcher | None,
+) -> dict[str, Any]:
+    allowed, block_reason, usage = control_plane.can_send_auto_chat()
+    if not allowed:
+        control_plane.register_budget_block(block_reason)
+        observability.record_autonomy_goal(
+            risk=risk,
+            outcome="budget_blocked",
+            details=block_reason,
+        )
+        return {
+            "goal_id": goal_id,
+            "risk": risk,
+            "outcome": "budget_blocked",
+            "block_reason": block_reason,
+            "budget_usage": usage,
+        }
+
+    if dispatcher is None:
+        queued = control_plane.enqueue_action(
+            kind="autonomy_fallback",
+            risk=RISK_SUGGEST_STREAMER,
+            title=f"Auto chat sem dispatcher ({goal_name})",
+            body=text,
+            payload={"goal_id": goal_id, "source_risk": risk},
+            created_by="autonomy",
+        )
+        observability.record_autonomy_goal(
+            risk=risk,
+            outcome="queued_no_dispatcher",
+            details=goal_id,
+        )
+        return {
+            "goal_id": goal_id,
+            "risk": risk,
+            "outcome": "queued_no_dispatcher",
+            "action_id": queued.get("id", ""),
+        }
+
+    try:
+        await dispatcher(text)
+    except Exception as error:
+        control_plane.register_dispatch_failure(f"auto_chat_send_error:{error}")
+        observability.record_error(
+            category="autonomy_dispatch",
+            details=str(error),
+        )
+        return {
+            "goal_id": goal_id,
+            "risk": risk,
+            "outcome": "dispatch_error",
+            "error": str(error),
+        }
+
+    control_plane.register_auto_chat_sent()
+    context.remember_bot_reply(text)
+    observability.record_reply(text=text)
+    observability.record_autonomy_goal(
+        risk=risk,
+        outcome="auto_chat_sent",
+        details=goal_id,
+    )
+    return {
+        "goal_id": goal_id,
+        "risk": risk,
+        "outcome": "auto_chat_sent",
+    }
+
+def _handle_clip_candidate(
+    goal_id: str,
+    risk: str,
+    goal_name: str,
+    text: str,
+) -> dict[str, Any]:
+    cfg = control_plane.get_config()
+    if not cfg.get("clip_pipeline_enabled"):
+        observability.record_autonomy_goal(
+            risk=risk,
+            outcome="disabled",
+            details="clip_pipeline_disabled",
+        )
+        return {
+            "goal_id": goal_id,
+            "risk": risk,
+            "outcome": "disabled",
+        }
+
+    if len(text) < 5 or "nada" in text.lower():
+        control_plane.register_dispatch_failure("clip_candidate_none")
+        observability.record_autonomy_goal(
+            risk=risk,
+            outcome="no_candidate",
+            details="LLM retornou NADA",
+        )
+        return {
+            "goal_id": goal_id,
+            "risk": risk,
+            "outcome": "no_candidate",
+        }
+
+    now_ts = utc_iso(time.time())
+    candidate_payload = {
+        "candidate_id": f"clip_{int(time.time())}",
+        "broadcaster_id": str(CHANNEL_ID),
+        "mode": str(cfg.get("clip_mode_default", "live")),
+        "suggested_duration": 30.0,
+        "suggested_title": text[:100],
+        "source": "autonomy_goal",
+        "source_ts": now_ts,
+        "context_excerpt": text,
+        "dedupe_key": f"clip_{int(time.time() / 60)}",
+    }
+
+    queued_item = control_plane.enqueue_action(
+        kind="clip_candidate",
+        risk=RISK_CLIP_CANDIDATE,
+        title=f"Sugestao de Clip ({goal_name})",
+        body=text,
+        payload=candidate_payload,
+        created_by="autonomy",
+    )
+    observability.record_autonomy_goal(
+        risk=risk,
+        outcome="queued",
+        details=queued_item.get("id", ""),
+    )
+    return {
+        "goal_id": goal_id,
+        "risk": risk,
+        "outcome": "queued",
+        "action_id": queued_item.get("id", ""),
+    }
+
+def _handle_generic_suggestion(
+    goal_id: str,
+    risk: str,
+    goal_name: str,
+    prompt: str,
+    text: str,
+) -> dict[str, Any]:
+    action_kind = "suggestion" if risk == RISK_SUGGEST_STREAMER else "moderation_review"
+    queued_item = control_plane.enqueue_action(
+        kind=action_kind,
+        risk=risk,
+        title=goal_name,
+        body=text,
+        payload={
+            "goal_id": goal_id,
+            "goal_prompt": prompt,
+            "requires_confirmation": risk == RISK_MODERATION_ACTION,
+        },
+        created_by="autonomy",
+    )
+    observability.record_autonomy_goal(
+        risk=risk,
+        outcome="queued",
+        details=queued_item.get("id", ""),
+    )
+    if risk == RISK_SUGGEST_STREAMER:
+        hud_runtime.push_message(text, source="autonomy")
+    return {
+        "goal_id": goal_id,
+        "risk": risk,
+        "outcome": "queued",
+        "action_id": queued_item.get("id", ""),
+    }

bot/autonomy_runtime.py

@@ -0,0 +1,136 @@
+import asyncio
+import threading
+from concurrent.futures import TimeoutError as FutureTimeoutError
+from typing import Any, Awaitable, Callable
+
+from bot.control_plane import control_plane
+from bot.observability import observability
+from bot.runtime_config import logger
+from bot.autonomy_logic import process_autonomy_goal
+
+AutoChatDispatcher = Callable[[str], Awaitable[None]]
+
+
+class AutonomyRuntime:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._loop_task: asyncio.Task[Any] | None = None
+        self._tick_lock: asyncio.Lock | None = None
+        self._auto_chat_dispatcher: AutoChatDispatcher | None = None
+        self._mode = "eventsub"
+
+    def bind(
+        self,
+        *,
+        loop: asyncio.AbstractEventLoop,
+        mode: str,
+        auto_chat_dispatcher: AutoChatDispatcher | None = None,
+    ) -> None:
+        with self._lock:
+            self._loop = loop
+            self._mode = (mode or "eventsub").strip().lower() or "eventsub"
+            self._auto_chat_dispatcher = auto_chat_dispatcher
+        loop.call_soon_threadsafe(self._ensure_loop_task)
+
+    def unbind(self) -> None:
+        with self._lock:
+            task = self._loop_task
+            self._loop = None
+            self._loop_task = None
+            self._tick_lock = None
+            self._auto_chat_dispatcher = None
+            self._mode = "eventsub"
+        if task is not None:
+            task.cancel()
+        control_plane.set_loop_running(False)
+
+    def _ensure_loop_task(self) -> None:
+        with self._lock:
+            loop = self._loop
+            task = self._loop_task
+        if loop is None or loop.is_closed():
+            return
+        if task is not None and not task.done():
+            return
+
+        created_task = loop.create_task(self._heartbeat_loop())
+        with self._lock:
+            if self._loop is loop:
+                self._loop_task = created_task
+            else:
+                created_task.cancel()
+
+    async def _heartbeat_loop(self) -> None:
+        control_plane.set_loop_running(True)
+        try:
+            while True:
+                with self._lock:
+                    active_loop = self._loop
+                if active_loop is None or active_loop is not asyncio.get_running_loop():
+                    break
+
+                try:
+                    await self._run_tick(force=False, reason="heartbeat")
+                except Exception as error:
+                    logger.error("Autonomy heartbeat falhou: %s", error)
+                    control_plane.register_dispatch_failure(f"heartbeat_error:{error}")
+                    observability.record_error(
+                        category="autonomy_heartbeat",
+                        details=str(error),
+                    )
+
+                heartbeat_seconds = int(
+                    control_plane.get_config().get("heartbeat_interval_seconds", 60)
+                )
+                await asyncio.sleep(max(15, heartbeat_seconds))
+        except asyncio.CancelledError:
+            raise
+        finally:
+            control_plane.set_loop_running(False)
+
+    async def _run_tick(self, *, force: bool, reason: str) -> dict[str, Any]:
+        if self._tick_lock is None:
+            self._tick_lock = asyncio.Lock()
+        async with self._tick_lock:
+            control_plane.touch_heartbeat()
+            control_plane.register_tick(reason=reason)
+
+            due_goals = control_plane.consume_due_goals(force=force)
+            processed: list[dict[str, Any]] = []
+            
+            dispatcher = self._get_auto_chat_dispatcher()
+            for goal in due_goals:
+                processed.append(await process_autonomy_goal(goal, dispatcher))
+
+            return {
+                "ok": True,
+                "reason": reason,
+                "force": bool(force),
+                "due_goals": len(due_goals),
+                "processed": processed,
+                "runtime": control_plane.runtime_snapshot(),
+            }
+
+    def _get_auto_chat_dispatcher(self) -> AutoChatDispatcher | None:
+        with self._lock:
+            return self._auto_chat_dispatcher
+
+    def run_manual_tick(self, *, force: bool = True, reason: str = "manual") -> dict[str, Any]:
+        coroutine = self._run_tick(force=force, reason=reason)
+        with self._lock:
+            loop = self._loop
+        if loop is None or loop.is_closed() or not loop.is_running():
+            return asyncio.run(coroutine)
+
+        future = asyncio.run_coroutine_threadsafe(coroutine, loop)
+        try:
+            return future.result(timeout=20.0)
+        except FutureTimeoutError as error:
+            future.cancel()
+            raise TimeoutError("Autonomy tick timeout.") from error
+
+
+autonomy_runtime = AutonomyRuntime()
+
+__all__ = ["AutonomyRuntime", "autonomy_runtime"]

bot/bootstrap_runtime.py

@@ -0,0 +1,188 @@
+import asyncio
+
+
+from bot.autonomy_runtime import autonomy_runtime
+from bot.clip_jobs_runtime import clip_jobs
+from bot.eventsub_runtime import ByteBot
+from bot.irc_runtime import IrcByteBot
+from bot.observability import observability
+from bot.runtime_config import (
+    CLIENT_ID,
+    TWITCH_BOT_LOGIN,
+    TWITCH_CHANNEL_LOGIN,
+    TWITCH_CHANNEL_LOGINS_RAW,
+    TWITCH_CLIENT_SECRET_INLINE,
+    TWITCH_CLIENT_SECRET_NAME,
+    TWITCH_IRC_HOST,
+    TWITCH_IRC_PORT,
+    TWITCH_IRC_TLS,
+    TWITCH_REFRESH_TOKEN,
+    TWITCH_TOKEN_REFRESH_MARGIN_SECONDS,
+    TWITCH_TOKEN_REFRESH_TIMEOUT_SECONDS,
+    TWITCH_TOKEN_VALIDATE_TIMEOUT_SECONDS,
+    TWITCH_USER_TOKEN,
+    irc_channel_control,
+    logger,
+)
+from bot.status_runtime import parse_channel_logins
+from bot.twitch_tokens import TwitchTokenManager, TwitchTokenManagerSettings
+
+
+import os
+
+def get_secret(secret_name: str = "twitch-client-secret") -> str:
+    # Ler do ENV usando o nome do secret
+    env_key = secret_name.upper().replace("-", "_")
+    val = os.environ.get(env_key)
+    if val:
+        return val
+    raise RuntimeError(f"Secret {env_key} not in env.")
+
+def require_env(name: str) -> str:
+    value = (os.environ.get(name) or "").strip()
+    if not value:
+        raise RuntimeError(f"Variavel obrigatoria ausente: {name}")
+    return value
+
+
+def resolve_irc_channel_logins() -> list[str]:
+    explicit_channels = parse_channel_logins(TWITCH_CHANNEL_LOGINS_RAW)
+    if explicit_channels:
+        return explicit_channels
+    fallback_channels = parse_channel_logins(TWITCH_CHANNEL_LOGIN)
+    if fallback_channels:
+        return fallback_channels
+
+    required_single_channel = require_env("TWITCH_CHANNEL_LOGIN")
+    required_channels = parse_channel_logins(required_single_channel)
+    if not required_channels:
+        raise RuntimeError(
+            "TWITCH_CHANNEL_LOGIN invalido. Use login Twitch sem # e com 3-25 caracteres."
+        )
+    return required_channels
+
+
+def resolve_client_secret_for_irc_refresh() -> str:
+    if TWITCH_CLIENT_SECRET_INLINE:
+        return TWITCH_CLIENT_SECRET_INLINE
+
+    secret_name = TWITCH_CLIENT_SECRET_NAME or "twitch-client-secret"
+    try:
+        return get_secret(secret_name=secret_name)
+    except Exception as error:
+        logger.warning(
+            "Nao foi possivel ler segredo '%s' para refresh automatico: %s",
+            secret_name,
+            error,
+        )
+        return ""
+
+
+def build_irc_token_manager() -> TwitchTokenManager:
+    user_token = TWITCH_USER_TOKEN or require_env("TWITCH_USER_TOKEN")
+    refresh_token = TWITCH_REFRESH_TOKEN.strip()
+    settings = TwitchTokenManagerSettings(
+        validate_timeout_seconds=TWITCH_TOKEN_VALIDATE_TIMEOUT_SECONDS,
+        refresh_timeout_seconds=TWITCH_TOKEN_REFRESH_TIMEOUT_SECONDS,
+    )
+    if not refresh_token:
+        return TwitchTokenManager(
+            access_token=user_token,
+            settings=settings,
+            observability=observability,
+            logger=logger,
+        )
+
+    client_id = CLIENT_ID or require_env("TWITCH_CLIENT_ID")
+    client_secret = resolve_client_secret_for_irc_refresh()
+    if not client_secret:
+        logger.warning(
+            "TWITCH_REFRESH_TOKEN definido, mas TWITCH_CLIENT_SECRET nao encontrado. "
+            "Refresh automatico do token nao funcionara. Configure TWITCH_CLIENT_SECRET na Host."
+        )
+
+    return TwitchTokenManager(
+        access_token=user_token,
+        refresh_token=refresh_token,
+        client_id=client_id,
+        client_secret=client_secret or "",
+        refresh_margin_seconds=TWITCH_TOKEN_REFRESH_MARGIN_SECONDS,
+        settings=settings,
+        observability=observability,
+        logger=logger,
+    )
+
+
+def run_irc_mode() -> None:
+    token_manager = build_irc_token_manager()
+    channel_logins = resolve_irc_channel_logins()
+    bot = IrcByteBot(
+        host=TWITCH_IRC_HOST,
+        port=TWITCH_IRC_PORT,
+        use_tls=TWITCH_IRC_TLS,
+        bot_login=TWITCH_BOT_LOGIN or require_env("TWITCH_BOT_LOGIN"),
+        channel_logins=channel_logins,
+        token_manager=token_manager,
+    )
+
+    async def run_with_channel_control() -> None:
+        running_loop = asyncio.get_running_loop()
+        irc_channel_control.bind(loop=running_loop, bot=bot)
+
+        async def _check_clips_auth() -> None:
+            # Avoid circular import
+            from bot.control_plane import control_plane
+
+            try:
+                token_valid, has_clips_edit = await token_manager.validate_clips_auth()
+
+                config = control_plane.get_config()
+                if config.get("clip_pipeline_enabled") and not has_clips_edit:
+                    logger.warning("Pipeline de clips habilitado mas scope 'clips:edit' ausente no token.")
+
+            except Exception as error:
+                logger.error("Erro ao validar auth de clips: %s", error)
+                observability.record_error(category="clips_auth", details=str(error))
+
+        async def verify_clips_auth_loop() -> None:
+            # Initial check
+            await asyncio.sleep(5)  # Wait for boot
+            while True:
+                await _check_clips_auth()
+                await asyncio.sleep(3600)
+
+        async def send_autonomy_chat(text: str) -> None:
+            await bot.send_reply(text)
+
+        autonomy_runtime.bind(
+            loop=running_loop,
+            mode="irc",
+            auto_chat_dispatcher=send_autonomy_chat,
+        )
+        
+        # Clip Jobs Runtime
+        clip_jobs.bind_token_provider(token_manager.ensure_token_for_connection)
+        clip_jobs.start(running_loop)
+        
+        # Start background task
+        asyncio.create_task(verify_clips_auth_loop())
+
+        try:
+            await bot.run_forever()
+        finally:
+            clip_jobs.stop()
+            autonomy_runtime.unbind()
+            irc_channel_control.unbind()
+
+    asyncio.run(run_with_channel_control())
+
+
+def run_eventsub_mode() -> None:
+    require_env("TWITCH_CLIENT_ID")
+    require_env("TWITCH_BOT_ID")
+    require_env("TWITCH_CHANNEL_ID")
+    bot = ByteBot(client_secret=get_secret())
+    try:
+        bot.run()
+    finally:
+        autonomy_runtime.unbind()

bot/byte_semantics.py

@@ -0,0 +1,81 @@
+from bot.byte_semantics_base import (
+    build_intro_reply,
+    compact_message,
+    format_chat_reply,
+    is_current_events_prompt,
+    is_follow_up_prompt,
+    is_high_risk_current_events_prompt,
+    is_intro_prompt,
+    is_movie_fact_sheet_prompt,
+    is_serious_technical_prompt,
+    normalize_text_for_scene,
+    parse_byte_prompt,
+)
+from bot.byte_semantics_constants import (
+    BYTE_HELP_MESSAGE,
+    BYTE_INTRO_TEMPLATES,
+    MAX_CHAT_MESSAGE_LENGTH,
+    MULTIPART_SEPARATOR,
+    QUALITY_SAFE_FALLBACK,
+    SERIOUS_REPLY_MAX_LENGTH,
+    SERIOUS_REPLY_MAX_LINES,
+)
+from bot.byte_semantics_current_events import (
+    build_current_events_safe_fallback_reply,
+    build_server_time_anchor_instruction,
+    build_verifiable_prompt,
+    normalize_current_events_reply_contract,
+)
+from bot.byte_semantics_quality import (
+    build_adaptive_ai_instruction,
+    build_anti_generic_contract_instruction,
+    build_direct_answer_instruction,
+    build_llm_enhanced_prompt,
+    build_quality_prompt_script,
+    build_quality_rewrite_prompt,
+    build_research_priority_instruction,
+    is_low_quality_answer,
+)
+from bot.byte_semantics_reply import (
+    build_movie_fact_sheet_query,
+    extract_movie_title,
+    extract_multi_reply_parts,
+    split_text_for_chat,
+)
+
+__all__ = [
+    "BYTE_HELP_MESSAGE",
+    "BYTE_INTRO_TEMPLATES",
+    "MAX_CHAT_MESSAGE_LENGTH",
+    "MULTIPART_SEPARATOR",
+    "QUALITY_SAFE_FALLBACK",
+    "SERIOUS_REPLY_MAX_LENGTH",
+    "SERIOUS_REPLY_MAX_LINES",
+    "build_adaptive_ai_instruction",
+    "build_anti_generic_contract_instruction",
+    "build_current_events_safe_fallback_reply",
+    "build_direct_answer_instruction",
+    "build_intro_reply",
+    "build_llm_enhanced_prompt",
+    "build_movie_fact_sheet_query",
+    "build_quality_prompt_script",
+    "build_quality_rewrite_prompt",
+    "build_research_priority_instruction",
+    "build_server_time_anchor_instruction",
+    "build_verifiable_prompt",
+    "compact_message",
+    "extract_movie_title",
+    "extract_multi_reply_parts",
+    "format_chat_reply",
+    "is_current_events_prompt",
+    "is_follow_up_prompt",
+    "is_high_risk_current_events_prompt",
+    "is_intro_prompt",
+    "is_low_quality_answer",
+    "is_movie_fact_sheet_prompt",
+    "is_serious_technical_prompt",
+    "normalize_current_events_reply_contract",
+    "normalize_text_for_scene",
+    "parse_byte_prompt",
+    "split_text_for_chat",
+]

bot/byte_semantics_base.py

@@ -0,0 +1,132 @@
+import re
+
+from bot.byte_semantics_constants import (
+    BYTE_INTRO_TEMPLATES,
+    BYTE_TRIGGER,
+    BYTE_TRIGGER_PATTERN,
+    COMPLEX_TECH_HINT_TERMS,
+    CURRENT_EVENTS_HINT_TERMS,
+    FOLLOW_UP_HINT_TERMS,
+    HIGH_RISK_CURRENT_EVENTS_TERMS,
+    MAX_CHAT_MESSAGE_LENGTH,
+    MULTIPART_SEPARATOR,
+    MOVIE_FACT_SHEET_PATTERN,
+    RELEVANCE_HINT_TERMS,
+    SERIOUS_TECH_TERMS,
+)
+from bot.logic_context import enforce_reply_limits
+
+_intro_template_index = 0
+
+
+def compact_message(text: str, max_len: int = 450) -> str:
+    if len(text) <= max_len:
+        return text
+    head = text[: max_len - 3].rstrip()
+    punctuation_positions = [head.rfind(symbol) for symbol in (".", "!", "?", ";", ":")]
+    best_punctuation = max(punctuation_positions)
+    if best_punctuation >= int(max_len * 0.5):
+        return head[: best_punctuation + 1].strip()
+    last_space = head.rfind(" ")
+    if last_space >= int(max_len * 0.5):
+        head = head[:last_space]
+    return head.rstrip(" ,;:") + "..."
+
+
+def normalize_text_for_scene(text: str, max_len: int = 120) -> str:
+    compact = " ".join((text or "").split())
+    if len(compact) <= max_len:
+        return compact
+    return compact[: max_len - 3].rstrip() + "..."
+
+
+def format_chat_reply(text: str) -> str:
+    normalized = str(text or "").replace(MULTIPART_SEPARATOR, "\n")
+    return compact_message(
+        enforce_reply_limits(normalized),
+        max_len=MAX_CHAT_MESSAGE_LENGTH,
+    )
+
+
+def parse_byte_prompt(message_text: str) -> str | None:
+    text = (message_text or "").strip()
+    if not text:
+        return None
+    normalized_text = text.lower()
+    if normalized_text in {BYTE_TRIGGER, f"!{BYTE_TRIGGER}", f"@{BYTE_TRIGGER}"}:
+        return ""
+    match = BYTE_TRIGGER_PATTERN.match(text)
+    if not match:
+        return None
+    return match.group(1).strip()
+
+
+def is_movie_fact_sheet_prompt(prompt: str) -> bool:
+    lowered = (prompt or "").lower()
+    return bool(MOVIE_FACT_SHEET_PATTERN.search(lowered))
+
+
+def is_intro_prompt(prompt: str) -> bool:
+    normalized = " ".join((prompt or "").lower().split()).strip(" ?!.,:")
+    if not normalized:
+        return False
+    exact_triggers = {
+        "se apresente",
+        "apresente se",
+        "apresente-se",
+        "quem e voce",
+        "quem e vc",
+        "quem e o byte",
+        "o que voce faz",
+    }
+    if normalized in exact_triggers:
+        return True
+    return normalized.startswith("se apresente")
+
+
+def build_intro_reply() -> str:
+    global _intro_template_index
+    template = BYTE_INTRO_TEMPLATES[_intro_template_index % len(BYTE_INTRO_TEMPLATES)]
+    _intro_template_index += 1
+    return template
+
+
+def is_current_events_prompt(prompt: str) -> bool:
+    lowered = (prompt or "").lower()
+    return any(hint in lowered for hint in CURRENT_EVENTS_HINT_TERMS)
+
+
+def is_high_risk_current_events_prompt(prompt: str) -> bool:
+    lowered = (prompt or "").lower()
+    return any(hint in lowered for hint in HIGH_RISK_CURRENT_EVENTS_TERMS)
+
+
+def is_serious_technical_prompt(prompt: str) -> bool:
+    normalized = " ".join((prompt or "").lower().split()).strip(" ?!.,:")
+    if len(normalized) < 24:
+        return False
+    has_technical_signal = any(term in normalized for term in SERIOUS_TECH_TERMS) or any(
+        term in normalized for term in COMPLEX_TECH_HINT_TERMS
+    )
+    if not has_technical_signal:
+        return False
+    has_relevance_signal = any(term in normalized for term in RELEVANCE_HINT_TERMS) or is_current_events_prompt(normalized)
+    return has_relevance_signal
+
+
+def is_follow_up_prompt(prompt: str) -> bool:
+    normalized = " ".join((prompt or "").lower().split()).strip(" ?!.,:")
+    if not normalized:
+        return False
+    if normalized in {"e agora", "e ai", "e aí", "e esse", "e essa", "e ele", "e ela"}:
+        return True
+    for term in FOLLOW_UP_HINT_TERMS:
+        boundary_pattern = rf"(^|[^a-z0-9]){re.escape(term)}([^a-z0-9]|$)"
+        if re.search(boundary_pattern, normalized):
+            return True
+    if normalized.startswith(("e ", "entao ", "então ")) and len(normalized.split()) <= 7:
+        return True
+    words = normalized.split()
+    if len(words) <= 5 and any(word in {"isso", "ele", "ela", "esse", "essa"} for word in words):
+        return True
+    return False

bot/byte_semantics_constants.py

@@ -0,0 +1,98 @@
+import os
+import re
+
+from bot.logic_constants import BOT_BRAND, MAX_REPLY_LINES
+
+BYTE_TRIGGER = os.environ.get("BYTE_TRIGGER", BOT_BRAND).strip().lower() or "byte"
+BYTE_HELP_MESSAGE = (
+    "Byte entende chat natural. Acione com byte/@byte/!byte + pergunta. "
+    "Atalhos: ajuda | se apresente | ficha tecnica <filme> | status. "
+    "Dono (IRC): canais | join <canal> | part <canal>."
+)
+BYTE_TRIGGER_PATTERN = re.compile(rf"^\s*[@!]?(?:{re.escape(BYTE_TRIGGER)})\b[\s,:-]*(.*)$", re.IGNORECASE)
+MOVIE_FACT_SHEET_PATTERN = re.compile(r"ficha\s*t[eé]cnica", re.IGNORECASE)
+MOVIE_TITLE_QUOTE_PATTERN = re.compile(r"[\"'`](?P<title>[^\"'`]{2,120})[\"'`]")
+CURRENT_EVENTS_HINT_TERMS = (
+    "situacao atual", "situação atual", "como esta", "como está", "atualizacao", "atualização", "agora", "hoje",
+    "nesta semana", "nessa semana", "esta semana", "ultima semana", "última semana", "ultimos dias", "últimos dias",
+    "noticias", "notícias", "recente", "recentes", "agora mesmo", "tempo real", "breaking", "update", "updates",
+    "anunciou", "anunciaram", "novidade", "ultimo anuncio", "último anúncio", "lancamento", "lançamento",
+)
+HIGH_RISK_CURRENT_EVENTS_TERMS = (
+    "situacao atual", "situação atual", "agora", "hoje", "nesta semana", "nessa semana", "esta semana",
+    "ultima semana", "última semana", "ultimos dias", "últimos dias", "noticias", "notícias", "breaking",
+    "update", "updates", "anunciou", "anunciaram",
+)
+GENERIC_RESPONSE_HINT_TERMS = (
+    "depende", "pode variar", "em geral", "de forma geral", "geralmente", "na maioria dos casos",
+    "vale lembrar", "e importante lembrar", "por outro lado", "cada caso e um caso",
+)
+OVERCONFIDENT_HINT_TERMS = ("com certeza", "sem duvida", "definitivamente", "garantido", "sempre")
+UNCERTAINTY_HINT_TERMS = (
+    "nao consegui verificar", "não consegui verificar", "sem confirmacao", "sem confirmação", "sem confirmar", "incerto",
+    "nao ha confirmacao", "não há confirmação", "pode estar desatualizado", "baixa confianca", "baixa confiança",
+    "conexao com o modelo instavel", "conexão com o modelo instável",
+)
+TEMPORAL_ANCHOR_TERMS = (
+    "hoje", "agora", "atualmente", "ate o momento", "até o momento", "nesta semana", "neste momento",
+    "semana", "mes", "mês", "2025", "2026",
+)
+SOURCE_ANCHOR_TERMS = (
+    "segundo ", "de acordo com", "fonte:", "fontes:", "base:", "reportado por", "confirmado por",
+    "comunicado de", "anvisa", "ministerio", "ministério", "governo", "reuters", "bbc", "ap news",
+)
+CONFIDENCE_LABEL_TERMS = ("confianca:", "confiança:")
+QUALITY_STOPWORDS = {
+    "byte", "qual", "quais", "como", "onde", "quando", "quem", "porque", "por", "que", "isso", "esse", "essa",
+    "agora", "hoje", "sobre", "para", "com", "sem", "uma", "um", "uns", "umas", "dos", "das", "de", "do", "da",
+    "the", "and", "tem", "existe", "fala", "diz",
+}
+FOLLOW_UP_HINT_TERMS = (
+    "e agora", "e ai", "e aí", "e ele", "e ela", "e isso", "e esse", "e essa", "sobre isso", "sobre ele", "sobre ela",
+    "detalha isso", "resume isso", "resuma isso",
+)
+BRIEF_STYLE_TERMS = ("resuma", "resumo", "curto", "curta", "1 linha", "uma linha", "tl;dr", "tldr")
+ANALYTICAL_STYLE_TERMS = ("detalha", "aprofunda", "analisa", "compare", "comparar", "vs", "diferen", "prons", "contras")
+PLAYFUL_STYLE_TERMS = ("zoa", "zoeira", "meme", "engracad", "brinca", "tirada")
+QUESTION_OPENING_TERMS = (
+    "existe", "tem", "ha", "há", "qual", "quais", "como", "porque", "por que", "onde", "quando", "quem", "pode", "vale",
+    "compensa", "recomenda", "recomendacao", "recomendação", "indica",
+)
+EXISTENCE_QUESTION_TERMS = ("existe", "tem", "ha", "há")
+RECOMMENDATION_HINT_TERMS = ("recomenda", "recomendacao", "recomendação", "indica", "sugere", "lista", "melhores")
+SERIOUS_TECH_TERMS = (
+    "laminina", "parapleg", "medicina", "saude", "tratamento", "terapia", "pesquisa", "estudo", "cient", "neurolog",
+    "biolog", "genet", "clinico", "evidencia", "paper",
+)
+COMPLEX_TECH_HINT_TERMS = (
+    "como funciona", "mecanismo", "explica tecnicamente", "base cientifica", "protocolo", "metodologia", "efeitos", "riscos", "limites",
+)
+RELEVANCE_HINT_TERMS = ("relevante", "impacto", "hoje", "agora", "atual", "urgente", "importante", "cura")
+MAX_CHAT_MESSAGE_LENGTH = 460
+MULTIPART_SEPARATOR = "[BYTE_SPLIT]"
+SERIOUS_REPLY_MAX_LINES = MAX_REPLY_LINES
+SERIOUS_REPLY_MAX_LENGTH = MAX_CHAT_MESSAGE_LENGTH
+QUALITY_SAFE_FALLBACK = "Nao consegui verificar com confianca agora. Me manda 1 link/fonte no chat e eu resumo em ate 3 linhas."
+CURRENT_EVENTS_DEFAULT_SOURCE = "Fonte: pesquisa web em tempo real (DuckDuckGo)."
+CURRENT_EVENTS_PENDING_SOURCE = "Fonte: aguardando 1 link/fonte do chat para confirmar."
+REWRITE_REASON_GUIDANCE = {
+    "resposta_generica": "Troque generalidades por fatos especificos ligados ao pedido do usuario.",
+    "abertura_generica": "Comece respondendo direto a pergunta principal, sem 'depende' ou introducoes vagas.",
+    "resposta_curta_sem_substancia": "Adicione 1 ou 2 detalhes concretos (nome, data, local, obra ou numero).",
+    "off_topic": "Retorne ao objeto central da pergunta e remova desvios.",
+    "tema_atual_sem_ancora_temporal": "Inclua ancora temporal objetiva baseada no horario do servidor (hoje/nesta semana/mes-ano).",
+    "tema_atual_sem_confianca_explicita": "Inclua a linha final 'Confianca: alta|media|baixa'.",
+    "tema_atual_sem_base_verificavel": "Inclua a linha final 'Fonte: <origem confiavel>' quando houver afirmacao atual.",
+    "incerteza_sem_pedido_de_fonte": "Se houver incerteza, solicite 1 link/fonte para confirmar.",
+    "incerteza_fora_fallback_canonico": "Para tema atual de alto risco com incerteza, use apenas fallback canonico sem especulacao extra.",
+    "modelo_indisponivel": "Se o modelo estiver instavel/indisponivel, use fallback seguro pedindo 1 fonte do chat.",
+    "resposta_existencia_sem_posicao": "Em pergunta de existencia, comece com 'Sim,' ou 'Nao,'.",
+    "termina_com_pergunta_aberta": "Finalize com afirmacao objetiva; so faca pergunta se faltar dado essencial.",
+    "confianca_absoluta_sem_base": "Evite tom absoluto sem base verificavel; sinalize limite de confianca.",
+}
+BYTE_INTRO_TEMPLATES = (
+    "Sou Byte: IA premium da live. Latencia baixa, cerebro afiado e zoeira calibrada. Digita 'byte ajuda'.",
+    "Byte on. Modo high-tech + caos controlado: resposta rapida, precisa e sem textao. Usa 'byte ajuda'.",
+    "Copiloto oficial do chat: contexto em tempo real, ficha tecnica na veia e humor fino. Manda 'byte ajuda'.",
+    "Byte na pista. Se a pergunta vier torta, eu devolvo reta com classe e zoeira. Comandos em 'byte ajuda'.",
+)

bot/byte_semantics_current_events.py

@@ -0,0 +1,256 @@
+import re
+from datetime import datetime, timezone
+from urllib.parse import urlparse
+
+from bot.byte_semantics_base import (
+    compact_message,
+    is_current_events_prompt,
+    is_high_risk_current_events_prompt,
+)
+from bot.byte_semantics_constants import (
+    CONFIDENCE_LABEL_TERMS,
+    CURRENT_EVENTS_DEFAULT_SOURCE,
+    CURRENT_EVENTS_PENDING_SOURCE,
+    MAX_CHAT_MESSAGE_LENGTH,
+    MAX_REPLY_LINES,
+    QUALITY_SAFE_FALLBACK,
+    SOURCE_ANCHOR_TERMS,
+    TEMPORAL_ANCHOR_TERMS,
+    UNCERTAINTY_HINT_TERMS,
+)
+from bot.logic import enforce_reply_limits, has_grounding_signal
+
+
+def build_server_time_anchor_instruction(reference_utc_iso: str | None = None) -> str:
+    now_utc_iso = (reference_utc_iso or "").strip()
+    if not now_utc_iso:
+        now_utc = datetime.now(timezone.utc)
+        now_utc_iso = now_utc.isoformat(timespec="seconds").replace("+00:00", "Z")
+    return f"Timestamp de referencia do servidor (UTC): {now_utc_iso}. Use esse horario para interpretar hoje/agora/nesta semana."
+
+
+def build_verifiable_prompt(prompt: str, concise_mode: bool = True, server_time_instruction: str | None = None) -> str:
+    clean_prompt = (prompt or "").strip()
+    if not clean_prompt:
+        return clean_prompt
+    is_current_events = is_current_events_prompt(clean_prompt)
+    active_server_time_instruction = server_time_instruction or build_server_time_anchor_instruction()
+    if not concise_mode:
+        return (
+            f"{clean_prompt}\n"
+            f"{active_server_time_instruction} Instrucoes obrigatorias de confiabilidade: priorize fatos recentes e verificaveis. "
+            f"{'Considere prioridade alta para acontecimentos de hoje/agora. ' if is_current_events else ''}"
+            "Diferencie o que esta confirmado do que ainda e hipotese. "
+            "Se houver ambiguidade no nome (ex.: Push/Punch/Posh), avise explicitamente e peca 1 link para confirmar. "
+            "Se nao houver confirmacao forte, diga isso com clareza e solicite fonte."
+        )
+    if not is_current_events:
+        return clean_prompt
+    return (
+        f"{clean_prompt}\n"
+        f"{active_server_time_instruction} Instrucoes obrigatorias de confiabilidade: responda em ate 4 linhas curtas, densas e sem enrolacao. "
+        "Use apenas fatos com confirmacao recente em fontes confiaveis. "
+        "Inclua ancora temporal explicita (ex.: hoje, nesta semana, mes/ano) quando falar de status atual. "
+        "Para noticia/anuncio atual, inclua no final: 'Confianca: alta|media|baixa' e 'Fonte: <origem confiavel>'. "
+        "Diferencie o que esta confirmado do que ainda e rumor/hipotese. "
+        "Se houver ambiguidade no nome (ex.: Push/Punch/Posh), avise explicitamente e peca 1 link para confirmar. "
+        "Se nao houver confirmacao forte, responda exatamente: "
+        f"'{QUALITY_SAFE_FALLBACK}'"
+    )
+
+
+def _extract_reference_utc_iso(server_time_instruction: str | None) -> str:
+    text = (server_time_instruction or "").strip()
+    if not text:
+        return ""
+    match = re.search(r"\b(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)\b", text)
+    return match.group(1) if match else ""
+
+
+def _extract_grounding_queries(grounding_metadata: dict | None) -> list[str]:
+    if not isinstance(grounding_metadata, dict):
+        return []
+    queries = grounding_metadata.get("web_search_queries", [])
+    if not isinstance(queries, list):
+        return []
+    return [str(query).strip() for query in queries if str(query or "").strip()]
+
+
+def _extract_grounding_source_urls(grounding_metadata: dict | None) -> list[str]:
+    if not isinstance(grounding_metadata, dict):
+        return []
+    source_urls = grounding_metadata.get("source_urls", [])
+    if not isinstance(source_urls, list):
+        return []
+    return [str(source_url).strip() for source_url in source_urls if str(source_url or "").strip()]
+
+
+def _build_grounding_source_line(grounding_metadata: dict | None) -> str:
+    source_urls = _extract_grounding_source_urls(grounding_metadata)
+    if source_urls:
+        hosts: list[str] = []
+        for source_url in source_urls:
+            parsed_url = urlparse(source_url)
+            host = parsed_url.netloc.lower().removeprefix("www.")
+            if host and host not in hosts:
+                hosts.append(host)
+            if len(hosts) >= 2:
+                break
+        if hosts:
+            return f"Fonte: DuckDuckGo em {', '.join(hosts)}."
+    queries = _extract_grounding_queries(grounding_metadata)
+    if queries:
+        query_preview = compact_message(queries[0], max_len=90).strip().rstrip(" ,;:.")
+        if query_preview:
+            return f"Fonte: DuckDuckGo query: {query_preview}."
+    return CURRENT_EVENTS_DEFAULT_SOURCE
+
+
+def _is_confidence_line(line: str) -> bool:
+    lowered = (line or "").strip().lower()
+    return lowered.startswith(("confianca:", "confiança:"))
+
+
+def _is_source_line(line: str) -> bool:
+    lowered = (line or "").strip().lower()
+    return lowered.startswith("fonte:")
+
+
+def _is_temporal_line(line: str) -> bool:
+    lowered = (line or "").strip().lower()
+    return lowered.startswith("recorte temporal:")
+
+
+def _split_non_empty_lines(text: str) -> list[str]:
+    normalized = (text or "").replace("\r\n", "\n").replace("\r", "\n")
+    return [line.strip() for line in normalized.split("\n") if line.strip()]
+
+
+def _is_canonical_high_risk_fallback(answer: str) -> bool:
+    lines = _split_non_empty_lines(answer)
+    if not lines or lines[0].lower() != QUALITY_SAFE_FALLBACK.lower():
+        return False
+    lowered_lines = [line.lower() for line in lines]
+    has_low_confidence = any(line.startswith(("confianca: baixa", "confiança: baixa")) for line in lowered_lines)
+    has_pending_source = any(line == CURRENT_EVENTS_PENDING_SOURCE.lower() for line in lowered_lines)
+    if not has_low_confidence or not has_pending_source:
+        return False
+    for line in lowered_lines[1:]:
+        if _is_temporal_line(line) or _is_confidence_line(line) or _is_source_line(line):
+            continue
+        return False
+    return True
+
+
+def _fit_high_risk_current_events_reply(body_lines: list[str], confidence_line: str, source_line: str, temporal_line: str = "") -> str:
+    normalized_body = [line.strip() for line in body_lines if line and line.strip()]
+    tail_lines = [line.strip() for line in (temporal_line, confidence_line, source_line) if line and line.strip()]
+    tail_text = "\n".join(tail_lines)
+    if not tail_text:
+        return enforce_reply_limits("\n".join(normalized_body))
+    if not normalized_body:
+        return tail_text
+    max_body_lines = max(1, MAX_REPLY_LINES - len(tail_lines))
+    max_body_length = MAX_CHAT_MESSAGE_LENGTH - len(tail_text) - 1
+    if max_body_length <= 0:
+        return tail_text[:MAX_CHAT_MESSAGE_LENGTH].strip()
+    body_text = enforce_reply_limits("\n".join(normalized_body), max_lines=max_body_lines, max_length=max_body_length).strip()
+    combined = f"{body_text}\n{tail_text}" if body_text else tail_text
+    if len(combined) <= MAX_CHAT_MESSAGE_LENGTH:
+        return combined
+    compact_body = compact_message(" ".join(normalized_body), max_len=max_body_length).strip()
+    combined = f"{compact_body}\n{tail_text}" if compact_body else tail_text
+    if len(combined) <= MAX_CHAT_MESSAGE_LENGTH:
+        return combined
+    if max_body_length <= 0:
+        return tail_text[:MAX_CHAT_MESSAGE_LENGTH].strip()
+    cropped_body = compact_body[:max_body_length].rstrip(" ,;:")
+    return f"{cropped_body}\n{tail_text}" if cropped_body else tail_text
+
+
+def normalize_current_events_reply_contract(
+    prompt: str,
+    answer: str,
+    server_time_instruction: str | None = None,
+    grounding_metadata: dict | None = None,
+) -> str:
+    clean_prompt = (prompt or "").strip()
+    clean_answer = (answer or "").strip()
+    if not clean_prompt or not clean_answer or not is_current_events_prompt(clean_prompt):
+        return clean_answer
+    lines = _split_non_empty_lines(clean_answer)
+    if not lines:
+        lines = [" ".join(clean_answer.split())]
+    merged_answer = "\n".join(lines)
+    lowered_answer = merged_answer.lower()
+    has_uncertainty = any(term in lowered_answer for term in UNCERTAINTY_HINT_TERMS)
+    has_temporal_anchor = any(term in lowered_answer for term in TEMPORAL_ANCHOR_TERMS) or bool(
+        re.search(r"\b20(2[5-9]|3[0-9])\b", lowered_answer)
+    )
+    reference_utc_iso = _extract_reference_utc_iso(server_time_instruction)
+    added_temporal_line = ""
+    high_risk_current_events = is_high_risk_current_events_prompt(clean_prompt)
+    must_validate_grounding = grounding_metadata is not None
+    grounding_signal_present = has_grounding_signal(grounding_metadata)
+    if high_risk_current_events and has_uncertainty:
+        return build_current_events_safe_fallback_reply(clean_prompt, server_time_instruction=server_time_instruction)
+    if high_risk_current_events and must_validate_grounding and not grounding_signal_present:
+        return build_current_events_safe_fallback_reply(clean_prompt, server_time_instruction=server_time_instruction)
+    if not has_temporal_anchor and not has_uncertainty:
+        added_temporal_line = f"Recorte temporal: {reference_utc_iso} UTC." if reference_utc_iso else "Recorte temporal: agora (UTC)."
+        lines.append(added_temporal_line)
+    if not high_risk_current_events:
+        return "\n".join(lines)
+
+    body_lines: list[str] = []
+    confidence_line = ""
+    source_line = ""
+    for line in lines:
+        if added_temporal_line and line.strip() == added_temporal_line:
+            continue
+        if _is_confidence_line(line):
+            if not confidence_line:
+                confidence_line = line.strip()
+            continue
+        if _is_source_line(line):
+            if not source_line:
+                source_line = line.strip()
+            continue
+        body_lines.append(line.strip())
+
+    confidence_line = "Confianca: media"
+    source_line = _build_grounding_source_line(grounding_metadata)
+    return _fit_high_risk_current_events_reply(body_lines, confidence_line, source_line, temporal_line=added_temporal_line)
+
+
+def build_current_events_safe_fallback_reply(prompt: str, server_time_instruction: str | None = None) -> str:
+    clean_prompt = (prompt or "").strip()
+    if not is_high_risk_current_events_prompt(clean_prompt):
+        return QUALITY_SAFE_FALLBACK
+    reference_utc_iso = _extract_reference_utc_iso(server_time_instruction)
+    temporal_line = f"Recorte temporal: {reference_utc_iso} UTC." if reference_utc_iso else "Recorte temporal: agora (UTC)."
+    return "\n".join([QUALITY_SAFE_FALLBACK, temporal_line, "Confianca: baixa", CURRENT_EVENTS_PENDING_SOURCE])
+
+
+def has_current_events_source_anchor(text: str) -> bool:
+    lowered = (text or "").lower()
+    return any(term in lowered for term in SOURCE_ANCHOR_TERMS)
+
+
+def has_current_events_confidence_label(text: str) -> bool:
+    lowered = (text or "").lower()
+    return any(term in lowered for term in CONFIDENCE_LABEL_TERMS)
+
+
+def has_current_events_temporal_anchor(text: str) -> bool:
+    lowered = (text or "").lower()
+    return any(term in lowered for term in TEMPORAL_ANCHOR_TERMS) or bool(re.search(r"\b20(2[5-9]|3[0-9])\b", lowered))
+
+
+def has_current_events_uncertainty(text: str) -> bool:
+    lowered = (text or "").lower()
+    return any(term in lowered for term in UNCERTAINTY_HINT_TERMS)
+
+
+def is_canonical_high_risk_fallback(answer: str) -> bool:
+    return _is_canonical_high_risk_fallback(answer)

bot/byte_semantics_quality.py

@@ -0,0 +1,284 @@
+import re
+
+from bot.byte_semantics_base import (
+    is_current_events_prompt,
+    is_follow_up_prompt,
+    is_high_risk_current_events_prompt,
+    is_serious_technical_prompt,
+)
+from bot.byte_semantics_constants import (
+    ANALYTICAL_STYLE_TERMS,
+    BRIEF_STYLE_TERMS,
+    EXISTENCE_QUESTION_TERMS,
+    GENERIC_RESPONSE_HINT_TERMS,
+    OVERCONFIDENT_HINT_TERMS,
+    PLAYFUL_STYLE_TERMS,
+    QUALITY_SAFE_FALLBACK,
+    QUALITY_STOPWORDS,
+    QUESTION_OPENING_TERMS,
+    RECOMMENDATION_HINT_TERMS,
+    REWRITE_REASON_GUIDANCE,
+)
+from bot.byte_semantics_current_events import (
+    build_server_time_anchor_instruction,
+    build_verifiable_prompt,
+    has_current_events_confidence_label,
+    has_current_events_source_anchor,
+    has_current_events_temporal_anchor,
+    has_current_events_uncertainty,
+    is_canonical_high_risk_fallback,
+)
+
+
+def build_research_priority_instruction(prompt: str) -> str:
+    if not is_serious_technical_prompt(prompt):
+        return ""
+    return (
+        "Instrucoes de pesquisa aprofundada: priorize evidencia recente (2025-2026) e fontes confiaveis "
+        "(universidades, orgaos de saude, journals). "
+        "Quando existir contexto em alta relacionado ao tema, incorpore esse contexto explicitamente. "
+        "Se houver contribuicao relevante do Brasil no tema, mencione de forma objetiva."
+    )
+
+
+def build_anti_generic_contract_instruction(prompt: str) -> str:
+    clean_prompt = (prompt or "").strip()
+    if not clean_prompt:
+        return ""
+    return (
+        "Contrato anti-generico: responda o caso especifico da pergunta, sem texto enciclopedico amplo. "
+        "Nao use frases vagas como 'depende', 'em geral' ou 'cada caso' sem antes entregar resposta objetiva."
+    )
+
+
+def build_direct_answer_instruction(prompt: str) -> str:
+    normalized = " ".join((prompt or "").lower().split()).strip(" ?!.,:")
+    if not normalized:
+        return ""
+    is_question = "?" in (prompt or "")
+    starts_like_question = normalized.startswith(QUESTION_OPENING_TERMS)
+    if not is_question and not starts_like_question:
+        return ""
+
+    instructions = ["Formato de resposta obrigatorio: responda a pergunta principal na primeira linha, sem introducao."]
+    if normalized.startswith(EXISTENCE_QUESTION_TERMS):
+        instructions.append("Se for pergunta de existencia, comece com 'Sim,' ou 'Nao,'.")
+    if any(term in normalized for term in RECOMMENDATION_HINT_TERMS):
+        instructions.append("Se houver opcoes concretas, cite 1 a 3 nomes diretamente relevantes.")
+    instructions.append("Evite texto generico e nao desvie do foco da pergunta.")
+    return " ".join(instructions)
+
+
+def build_adaptive_ai_instruction(prompt: str) -> str:
+    lowered = (prompt or "").lower()
+    if any(term in lowered for term in BRIEF_STYLE_TERMS):
+        return "Estilo de resposta: ultra objetivo, no maximo 3 linhas."
+    if any(term in lowered for term in ANALYTICAL_STYLE_TERMS):
+        return "Estilo de resposta: analise pratica em ate 4 linhas, com 2 ou 3 pontos claros."
+    if any(term in lowered for term in PLAYFUL_STYLE_TERMS):
+        return "Estilo de resposta: humor leve e inteligente, sem perder precisao factual."
+    return ""
+
+
+def _quality_tokenize(text: str) -> list[str]:
+    tokens = re.findall(r"[a-z0-9]{3,}", (text or "").lower())
+    normalized: list[str] = []
+    for token in tokens:
+        if len(token) > 4 and token.endswith("s"):
+            token = token[:-1]
+        normalized.append(token)
+    return normalized
+
+
+def _extract_focus_terms(prompt: str, max_terms: int = 10) -> list[str]:
+    terms: list[str] = []
+    for token in _quality_tokenize(prompt):
+        if token in QUALITY_STOPWORDS:
+            continue
+        if token.isdigit() and len(token) < 4:
+            continue
+        if token in terms:
+            continue
+        terms.append(token)
+        if len(terms) >= max_terms:
+            break
+    return terms
+
+
+def _count_focus_overlap(focus_terms: list[str], answer_tokens: set[str]) -> int:
+    if not focus_terms or not answer_tokens:
+        return 0
+    overlap = 0
+    for focus_term in focus_terms:
+        if focus_term in answer_tokens:
+            overlap += 1
+            continue
+        focus_prefix = focus_term[:5]
+        if len(focus_prefix) < 4:
+            continue
+        if any(token.startswith(focus_prefix) or focus_term.startswith(token[:5]) for token in answer_tokens if len(token) >= 4):
+            overlap += 1
+    return overlap
+
+
+def build_quality_prompt_script(prompt: str, server_time_instruction: str | None = None) -> str:
+    clean_prompt = (prompt or "").strip()
+    is_current = is_current_events_prompt(clean_prompt)
+    is_high_risk_current = is_high_risk_current_events_prompt(clean_prompt)
+    active_server_time_instruction = server_time_instruction or build_server_time_anchor_instruction()
+    lines = [
+        "Script de qualidade obrigatorio:\n"
+        "1) Responda a pergunta principal na primeira linha, sem introducao.\n"
+        "2) Inclua 1 ou 2 detalhes concretos ligados ao pedido (nome, data, local, obra ou numero).\n"
+        "3) Maximize densidade informacional: cada linha precisa trazer dado novo.\n"
+        "4) Corte frases vagas/repetitivas que nao agregam informacao.\n"
+        "5) Se houver baixa confianca, admita incerteza de forma explicita e peca 1 fonte."
+    ]
+    if is_current:
+        lines.append(f"6) {active_server_time_instruction}")
+        lines.append("7) Para tema atual, separe explicitamente o que esta confirmado agora e o que ainda e rumor.")
+        if is_high_risk_current:
+            lines.append("8) Para noticia/anuncio atual, inclua as linhas finais: 'Confianca: alta|media|baixa' e 'Fonte: ...'.")
+            lines.append(f"9) Se faltar confirmacao robusta, use exatamente: '{QUALITY_SAFE_FALLBACK}'")
+        else:
+            lines.append(f"8) Se faltar confirmacao robusta, use exatamente: '{QUALITY_SAFE_FALLBACK}'")
+    else:
+        lines.append("6) Mantenha foco total no objeto perguntado.")
+        lines.append("7) Evite qualquer afirmacao absoluta sem base verificavel.")
+    lines.append("10) Nao termine com pergunta aberta, exceto se faltar dado essencial para responder.")
+    return "\n".join(lines)
+
+
+def is_low_quality_answer(prompt: str, answer: str) -> tuple[bool, str]:
+    clean_prompt = " ".join((prompt or "").split()).strip()
+    answer_lines = [line.strip() for line in (answer or "").replace("\r\n", "\n").replace("\r", "\n").split("\n") if line.strip()]
+    if not answer_lines:
+        return True, "resposta_vazia"
+    clean_answer = "\n".join(answer_lines)
+    compact_answer = " ".join(clean_answer.split()).strip()
+    if not compact_answer:
+        return True, "resposta_vazia"
+
+    normalized_prompt = " ".join(clean_prompt.lower().split()).strip(" ?!.,:")
+    lowered_answer = clean_answer.lower()
+    lowered_compact_answer = compact_answer.lower()
+    generic_hits = sum(1 for term in GENERIC_RESPONSE_HINT_TERMS if term in lowered_answer)
+    overconfident_hits = sum(1 for term in OVERCONFIDENT_HINT_TERMS if term in lowered_answer)
+    has_uncertainty = has_current_events_uncertainty(clean_answer)
+    has_temporal_anchor = has_current_events_temporal_anchor(clean_answer)
+    has_source_anchor = has_current_events_source_anchor(clean_answer)
+    has_confidence_label = has_current_events_confidence_label(clean_answer)
+
+    focus_terms = _extract_focus_terms(clean_prompt)
+    answer_tokens = set(_quality_tokenize(compact_answer))
+    overlap_count = _count_focus_overlap(focus_terms, answer_tokens)
+    first_line = answer_lines[0].strip().lower()
+
+    starts_too_generic = lowered_answer.startswith(("depende", "em geral", "de forma geral", "geralmente", "na maioria dos casos"))
+    prompt_is_complex = len(clean_prompt) >= 40
+    answer_is_short = len(clean_answer) < 70
+    follow_up_prompt = is_follow_up_prompt(clean_prompt)
+    current_events_prompt = is_current_events_prompt(clean_prompt)
+    current_events_high_risk = is_high_risk_current_events_prompt(clean_prompt)
+    existence_question = normalized_prompt.startswith(EXISTENCE_QUESTION_TERMS)
+
+    if "conexao com o modelo instavel" in lowered_answer or "conexão com o modelo instável" in lowered_answer:
+        return True, "modelo_indisponivel"
+    if generic_hits >= 2 and overlap_count <= 1:
+        return True, "resposta_generica"
+    if starts_too_generic and overlap_count <= 1:
+        return True, "abertura_generica"
+    if existence_question and not first_line.startswith(("sim", "nao", "não", "existe", "tem", "ha ", "há ")):
+        return True, "resposta_existencia_sem_posicao"
+    if prompt_is_complex and answer_is_short and overlap_count <= 1:
+        return True, "resposta_curta_sem_substancia"
+    if len(focus_terms) >= 3 and overlap_count == 0 and (generic_hits > 0 or answer_is_short):
+        return True, "off_topic"
+    if current_events_prompt and not follow_up_prompt and len(clean_prompt) >= 18 and not has_temporal_anchor and not has_uncertainty:
+        return True, "tema_atual_sem_ancora_temporal"
+    if current_events_high_risk and has_uncertainty and not is_canonical_high_risk_fallback(clean_answer):
+        return True, "incerteza_fora_fallback_canonico"
+    if current_events_high_risk and not follow_up_prompt and not has_confidence_label:
+        return True, "tema_atual_sem_confianca_explicita"
+    if current_events_high_risk and not follow_up_prompt and not has_uncertainty and not has_source_anchor and len(clean_answer) >= 120:
+        return True, "tema_atual_sem_base_verificavel"
+    if current_events_prompt and has_uncertainty and "link/fonte" not in lowered_answer and "fonte" not in lowered_answer:
+        return True, "incerteza_sem_pedido_de_fonte"
+    if lowered_compact_answer.endswith("?") and not has_uncertainty and not follow_up_prompt:
+        return True, "termina_com_pergunta_aberta"
+    if overconfident_hits > 0 and not has_temporal_anchor and not has_uncertainty:
+        return True, "confianca_absoluta_sem_base"
+    return False, ""
+
+
+def build_quality_rewrite_prompt(prompt: str, draft_answer: str, reason: str, server_time_instruction: str | None = None) -> str:
+    clean_prompt = (prompt or "").strip()
+    clean_draft = (draft_answer or "").strip()
+    safe_reason = (reason or "qualidade_insuficiente").strip()
+    active_server_time_instruction = server_time_instruction or build_server_time_anchor_instruction()
+    reason_fix = REWRITE_REASON_GUIDANCE.get(safe_reason, "Ajuste a resposta para ficar objetiva, verificavel e aderente a pergunta.")
+    return (
+        f"Pergunta original: {clean_prompt}\n"
+        f"Rascunho anterior reprovado ({safe_reason}): {clean_draft}\n"
+        "Reescreva para chat Twitch com as regras:\n"
+        f"- {active_server_time_instruction}\n"
+        f"- Correcao alvo: {reason_fix}\n"
+        "- Primeira linha responde direto.\n"
+        "- No maximo 4 linhas.\n"
+        "- Alta densidade: cada linha deve adicionar informacao nova.\n"
+        "- Inclua 1 ou 2 fatos concretos e relevantes.\n"
+        "- Para tema atual, diferencie confirmado agora vs rumor.\n"
+        "- Nao termine com pergunta aberta.\n"
+        "- Nao use frase vaga/generica.\n"
+        "- Se nao der para confirmar, use exatamente: "
+        f"'{QUALITY_SAFE_FALLBACK}'"
+    )
+
+
+def build_llm_enhanced_prompt(prompt: str, server_time_instruction: str | None = None) -> str:
+    clean_prompt = (prompt or "").strip()
+    if not clean_prompt:
+        return ""
+
+    serious_mode = is_serious_technical_prompt(clean_prompt)
+    active_server_time_instruction = server_time_instruction or build_server_time_anchor_instruction()
+    enriched_prompt = build_verifiable_prompt(clean_prompt, concise_mode=not serious_mode, server_time_instruction=active_server_time_instruction)
+    extra_instructions: list[str] = []
+    if active_server_time_instruction not in enriched_prompt:
+        extra_instructions.append(active_server_time_instruction)
+
+    anti_generic_instruction = build_anti_generic_contract_instruction(clean_prompt)
+    if anti_generic_instruction:
+        extra_instructions.append(anti_generic_instruction)
+    direct_answer_instruction = build_direct_answer_instruction(clean_prompt)
+    if direct_answer_instruction:
+        extra_instructions.append(direct_answer_instruction)
+
+    if is_follow_up_prompt(clean_prompt):
+        extra_instructions.append(
+            "Instrucoes de continuidade: trate esta pergunta como follow-up e resolva referencias vagas "
+            "(ex.: ele, ela, isso) usando o historico recente do chat."
+        )
+
+    research_instruction = build_research_priority_instruction(clean_prompt)
+    if research_instruction:
+        extra_instructions.append(research_instruction)
+
+    if serious_mode:
+        extra_instructions.append(
+            "Para tema tecnico serio e relevante, responda em uma unica mensagem. "
+            "Contrato obrigatorio: no maximo 4 linhas, alta densidade, sem separador de multiparte."
+        )
+
+    if not is_current_events_prompt(clean_prompt):
+        adaptive_instruction = build_adaptive_ai_instruction(clean_prompt)
+        if adaptive_instruction:
+            extra_instructions.append(adaptive_instruction)
+
+    quality_script = build_quality_prompt_script(clean_prompt, server_time_instruction=active_server_time_instruction)
+    if quality_script:
+        extra_instructions.append(quality_script)
+
+    if not extra_instructions:
+        return enriched_prompt
+    return f"{enriched_prompt}\n" + "\n".join(extra_instructions)

bot/byte_semantics_reply.py

@@ -0,0 +1,105 @@
+import re
+
+from bot.byte_semantics_base import compact_message, format_chat_reply, normalize_text_for_scene
+from bot.byte_semantics_constants import (
+    MAX_CHAT_MESSAGE_LENGTH,
+    MOVIE_TITLE_QUOTE_PATTERN,
+    MULTIPART_SEPARATOR,
+)
+
+
+def split_text_for_chat(text: str, max_len: int = MAX_CHAT_MESSAGE_LENGTH, max_parts: int = 2) -> list[str]:
+    clean_text = (text or "").strip()
+    if not clean_text:
+        return []
+    if len(clean_text) <= max_len:
+        return [clean_text]
+
+    parts: list[str] = []
+    remaining = clean_text
+    while remaining and len(parts) < max_parts:
+        if len(remaining) <= max_len:
+            parts.append(remaining.strip())
+            remaining = ""
+            break
+
+        cut = remaining.rfind("\n", 0, max_len + 1)
+        if cut < int(max_len * 0.5):
+            sentence_cuts = [remaining.rfind(symbol, 0, max_len + 1) for symbol in (". ", "? ", "! ")]
+            cut = max(sentence_cuts)
+        if cut < int(max_len * 0.5):
+            cut = remaining.rfind(" ", 0, max_len + 1)
+        if cut <= 0:
+            cut = max_len
+
+        chunk = remaining[:cut].strip()
+        if chunk:
+            parts.append(chunk)
+        remaining = remaining[cut:].strip()
+
+    if remaining:
+        if parts:
+            parts[-1] = compact_message(f"{parts[-1]} {remaining}", max_len=max_len)
+        else:
+            parts.append(compact_message(remaining, max_len=max_len))
+
+    return [part for part in parts if part][:max_parts]
+
+
+def extract_multi_reply_parts(answer_text: str, max_parts: int = 2) -> list[str]:
+    if not answer_text:
+        return []
+
+    raw_parts = [segment.strip() for segment in answer_text.split(MULTIPART_SEPARATOR) if segment.strip()]
+    if len(raw_parts) >= 2:
+        normalized = [format_chat_reply(part) for part in raw_parts[:max_parts]]
+        return [part for part in normalized if part]
+
+    chunks = split_text_for_chat(answer_text, max_len=MAX_CHAT_MESSAGE_LENGTH, max_parts=max_parts)
+    normalized = [format_chat_reply(chunk) for chunk in chunks]
+    return [part for part in normalized if part]
+
+
+def extract_movie_title(prompt: str) -> str:
+    quote_match = MOVIE_TITLE_QUOTE_PATTERN.search(prompt or "")
+    if quote_match:
+        return normalize_text_for_scene(quote_match.group("title"), max_len=80)
+
+    candidate_match = re.search(
+        r"ficha\s*t[eé]cnica(?:\s+(?:do|da|de)\s+filme)?(?:\s+(?:do|da|de))?\s+(?P<title>.+)$",
+        prompt or "",
+        re.IGNORECASE,
+    )
+    if not candidate_match:
+        return ""
+
+    candidate = candidate_match.group("title").strip(" ?!.:,;")
+    if not candidate:
+        return ""
+
+    lowered = candidate.lower()
+    generic_fragments = (
+        "que estamos vendo",
+        "que estamos assistindo",
+        "que estamos assistindo hoje",
+        "agora",
+    )
+    if any(fragment in lowered for fragment in generic_fragments):
+        return ""
+    if lowered in {"filme", "hoje", "agora"}:
+        return ""
+
+    return normalize_text_for_scene(candidate, max_len=80)
+
+
+def build_movie_fact_sheet_query(movie_title: str) -> str:
+    return (
+        f"Monte uma ficha tecnica objetiva do filme '{movie_title}' para chat Twitch. "
+        "Responda em no maximo 4 linhas, sem markdown, com alta densidade e sem enrolacao. "
+        "Formato obrigatorio: "
+        "1) Titulo | Ano | Pais. "
+        "2) Direcao | Genero | Duracao. "
+        "3) Elenco principal (ate 3 nomes). "
+        "4) Nota media | Premios-chave (ou N/D). "
+        "Se nao houver confianca em algum dado, escreva N/D."
+    )

bot/channel_control.py

@@ -0,0 +1,158 @@
+import asyncio
+import base64
+import binascii
+import hmac
+import inspect
+import threading
+from concurrent.futures import TimeoutError as FutureTimeoutError
+from typing import Any, Coroutine, cast
+
+
+CHANNEL_CONTROL_TIMEOUT_SECONDS = 15.0
+SUPPORTED_ACTIONS = {"list", "join", "part"}
+
+
+def extract_admin_token(headers: Any) -> str:
+    direct = str(headers.get("X-Byte-Admin-Token", "") or "").strip()
+    if direct:
+        return direct
+
+    authorization = str(headers.get("Authorization", "") or "").strip()
+    if authorization.lower().startswith("bearer "):
+        return authorization[7:].strip()
+    if authorization.lower().startswith("basic "):
+        encoded_credentials = authorization[6:].strip()
+        if not encoded_credentials:
+            return ""
+        try:
+            decoded_credentials = base64.b64decode(
+                encoded_credentials, validate=True
+            ).decode("utf-8")
+        except (binascii.Error, UnicodeDecodeError):
+            return ""
+
+        if ":" in decoded_credentials:
+            _, password = decoded_credentials.split(":", 1)
+            return password.strip()
+        return decoded_credentials.strip()
+    return ""
+
+
+def is_dashboard_admin_authorized(headers: Any, expected_token: str) -> bool:
+    configured_token = (expected_token or "").strip()
+    if not configured_token:
+        return False
+
+    provided_token = extract_admin_token(headers)
+    if not provided_token:
+        return False
+    return hmac.compare_digest(provided_token, configured_token)
+
+
+def parse_terminal_command(command_text: str) -> tuple[str, str]:
+    normalized = " ".join((command_text or "").strip().split())
+    lowered = normalized.lower()
+    if not lowered:
+        raise ValueError("Command is required. Use: list | join <channel> | part <channel>.")
+
+    if lowered in {"list", "channels", "canais"}:
+        return ("list", "")
+
+    for prefix in ("join ", "entrar ", "add "):
+        if lowered.startswith(prefix):
+            return ("join", normalized[len(prefix):].strip())
+
+    for prefix in ("part ", "leave ", "sair ", "remove "):
+        if lowered.startswith(prefix):
+            return ("part", normalized[len(prefix):].strip())
+
+    raise ValueError("Unsupported command. Use: list | join <channel> | part <channel>.")
+
+
+class IrcChannelControlBridge:
+    def __init__(self, timeout_seconds: float = CHANNEL_CONTROL_TIMEOUT_SECONDS) -> None:
+        self._timeout_seconds = max(1.0, float(timeout_seconds))
+        self._lock = threading.Lock()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._bot: Any = None
+
+    def bind(self, *, loop: asyncio.AbstractEventLoop, bot: Any) -> None:
+        with self._lock:
+            self._loop = loop
+            self._bot = bot
+
+    def unbind(self) -> None:
+        with self._lock:
+            self._loop = None
+            self._bot = None
+
+    def _snapshot(self) -> tuple[Any, asyncio.AbstractEventLoop | None]:
+        with self._lock:
+            return self._bot, self._loop
+
+    def _submit(self, coroutine: Coroutine[Any, Any, Any]) -> Any:
+        bot, loop = self._snapshot()
+        if bot is None or loop is None or loop.is_closed() or not loop.is_running():
+            raise RuntimeError("IRC runtime is not connected yet.")
+
+        future = asyncio.run_coroutine_threadsafe(coroutine, loop)
+        try:
+            return future.result(timeout=self._timeout_seconds)
+        except FutureTimeoutError as error:
+            future.cancel()
+            raise TimeoutError("Channel control timeout while waiting for IRC runtime.") from error
+
+    def execute(self, *, action: str, channel_login: str = "") -> dict[str, Any]:
+        normalized_action = (action or "").strip().lower()
+        normalized_channel = (channel_login or "").strip()
+        if normalized_action not in SUPPORTED_ACTIONS:
+            return {
+                "ok": False,
+                "error": "invalid_action",
+                "message": "Unsupported action. Use: list, join, part.",
+            }
+
+        try:
+            if normalized_action == "list":
+                channels = self._submit(self._safe_call("admin_list_channels"))
+                return {
+                    "ok": True,
+                    "action": "list",
+                    "channels": channels,
+                    "message": f"Connected channels: {', '.join(f'#{item}' for item in channels) or 'none'}.",
+                }
+
+            if not normalized_channel:
+                return {
+                    "ok": False,
+                    "error": "missing_channel",
+                    "message": f"Action '{normalized_action}' requires a channel login.",
+                }
+
+            method_name = "admin_join_channel" if normalized_action == "join" else "admin_part_channel"
+            success, message, channels = self._submit(self._safe_call(method_name, normalized_channel))
+            return {
+                "ok": bool(success),
+                "action": normalized_action,
+                "channels": channels,
+                "message": str(message),
+            }
+        except TimeoutError as error:
+            return {"ok": False, "error": "timeout", "message": str(error)}
+        except RuntimeError as error:
+            return {"ok": False, "error": "runtime_unavailable", "message": str(error)}
+        except Exception as error:
+            return {"ok": False, "error": "runtime_error", "message": str(error)}
+
+    async def _safe_call(self, method_name: str, *args: Any) -> Any:
+        bot, _ = self._snapshot()
+        if bot is None:
+            raise RuntimeError("IRC runtime is not connected yet.")
+
+        target = getattr(bot, method_name, None)
+        if not callable(target):
+            raise RuntimeError(f"IRC runtime method not available: {method_name}")
+        result = target(*args)
+        if not inspect.iscoroutine(result):
+            raise RuntimeError(f"IRC runtime method is not awaitable: {method_name}")
+        return await cast(Coroutine[Any, Any, Any], result)

bot/channel_status.py

@@ -0,0 +1,64 @@
+import re
+
+TWITCH_CHANNEL_LOGIN_PATTERN = re.compile(r"^[a-z0-9_]{3,25}$")
+
+
+def normalize_channel_login(channel_login: str, *, pattern: re.Pattern[str] = TWITCH_CHANNEL_LOGIN_PATTERN) -> str:
+    normalized = (channel_login or "").strip().lstrip("#").lower()
+    if not normalized:
+        return ""
+    if not pattern.fullmatch(normalized):
+        return ""
+    return normalized
+
+
+def parse_channel_logins(raw_value: str, *, pattern: re.Pattern[str] = TWITCH_CHANNEL_LOGIN_PATTERN) -> list[str]:
+    unique_logins: list[str] = []
+    seen: set[str] = set()
+    for token in re.split(r"[,\s]+", raw_value or ""):
+        normalized = normalize_channel_login(token, pattern=pattern)
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        unique_logins.append(normalized)
+    return unique_logins
+
+
+def format_status_channels(
+    channel_logins: list[str] | None = None,
+    *,
+    fallback_channels: list[str] | None = None,
+    fallback_mode: str = "eventsub",
+    max_items: int = 3,
+    pattern: re.Pattern[str] = TWITCH_CHANNEL_LOGIN_PATTERN,
+) -> str:
+    resolved = [normalize_channel_login(login, pattern=pattern) for login in (channel_logins or [])]
+    resolved = [login for login in resolved if login]
+    if not resolved:
+        resolved = [normalize_channel_login(login, pattern=pattern) for login in (fallback_channels or [])]
+        resolved = [login for login in resolved if login]
+    if not resolved:
+        return "eventsub" if fallback_mode == "eventsub" else "n/a"
+
+    visible = resolved[:max(1, max_items)]
+    if len(resolved) <= len(visible):
+        return ", ".join(visible)
+    return f"{', '.join(visible)} +{len(resolved) - len(visible)}"
+
+
+def compose_status_line(
+    *,
+    bot_brand: str,
+    bot_version: str,
+    uptime_minutes: int,
+    channels_label: str,
+    chat_messages_10m: int,
+    active_chatters_10m: int,
+    triggers_10m: int,
+    p95_latency_ms: float,
+) -> str:
+    return (
+        f"{bot_brand} v{bot_version} | Uptime: {uptime_minutes}min | Canais: {channels_label} | "
+        f"Chat 10m: {chat_messages_10m} msgs/{active_chatters_10m} ativos | Triggers 10m: {triggers_10m} | "
+        f"P95: {p95_latency_ms:.1f}ms | Privacidade: metricas agregadas"
+    )

bot/clip_jobs_runtime.py

@@ -0,0 +1,316 @@
+import asyncio
+import logging
+import threading
+import time
+from typing import Any, Awaitable, Callable, Optional
+
+from bot.control_plane import control_plane
+from bot.control_plane_constants import utc_iso
+from bot.runtime_config import CLIENT_ID, EDITOR_ID
+from bot.clip_jobs_store import job_store
+from bot.twitch_clips_api import (
+    TwitchClipAuthError,
+    TwitchClipError,
+    TwitchClipNotFoundError,
+    TwitchClipRateLimitError,
+    create_clip_live,
+    create_clip_from_vod,
+    get_clip,
+    get_clip_download_url,
+)
+
+logger = logging.getLogger("byte.clips.runtime")
+
+TokenProvider = Callable[[], Awaitable[str]]
+
+
+class ClipJobsRuntime:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._jobs: dict[str, dict[str, Any]] = {}
+        self._token_provider: Optional[TokenProvider] = None
+        self._loop_task: Optional[asyncio.Task[Any]] = None
+        self._running = False
+        
+        # Hydrate from store
+        self._load_from_store()
+
+    def _load_from_store(self) -> None:
+        try:
+            active_jobs = job_store.load_active_jobs()
+            for job in active_jobs:
+                action_id = str(job.get("action_id"))
+                if action_id:
+                    self._jobs[action_id] = job
+        except Exception as e:
+            logger.error("Erro ao hidratar jobs do store: %s", e)
+
+    def bind_token_provider(self, provider: TokenProvider) -> None:
+        with self._lock:
+            self._token_provider = provider
+
+    def start(self, loop: asyncio.AbstractEventLoop) -> None:
+        if self._running:
+            return
+        self._running = True
+        self._loop_task = loop.create_task(self._process_loop())
+
+    def stop(self) -> None:
+        self._running = False
+        if self._loop_task:
+            self._loop_task.cancel()
+            self._loop_task = None
+
+    def get_jobs(self) -> list[dict[str, Any]]:
+        with self._lock:
+            return sorted(
+                self._jobs.values(),
+                key=lambda x: str(x.get("created_at", "")),
+                reverse=True,
+            )
+
+    async def _process_loop(self) -> None:
+        logger.info("ClipJobsRuntime loop iniciado.")
+        while self._running:
+            try:
+                await self._sync_from_queue()
+                await self._advance_jobs()
+            except asyncio.CancelledError:
+                break
+            except Exception as error:
+                logger.error("Erro no loop de clips: %s", error)
+            
+            await asyncio.sleep(2.0)
+
+    async def _sync_from_queue(self) -> None:
+        actions_payload = control_plane.list_actions(status="approved", limit=20)
+        items = actions_payload.get("items", [])
+        
+        for item in items:
+            if item.get("kind") != "clip_candidate":
+                continue
+            
+            action_id = str(item.get("id"))
+            with self._lock:
+                if action_id in self._jobs:
+                    continue
+                
+                now = time.time()
+                payload = item.get("payload") or {}
+                job = {
+                    "job_id": f"job_{action_id}",
+                    "action_id": action_id,
+                    "broadcaster_id": str(payload.get("broadcaster_id", "")),
+                    "mode": str(payload.get("mode", "live")),
+                    "status": "queued",
+                    "title": str(payload.get("suggested_title", "")),
+                    # Persist VOD params if present
+                    "vod_id": payload.get("vod_id"),
+                    "vod_offset": payload.get("vod_offset"),
+                    "duration": payload.get("suggested_duration"),
+                    "created_at": utc_iso(now),
+                    "updated_at": utc_iso(now),
+                    "twitch_clip_id": None,
+                    "edit_url": None,
+                    "clip_url": None,
+                    "download_url": None,
+                    "error": None,
+                    "attempts": 0,
+                    "next_poll_at": 0.0,
+                    "poll_until": 0.0,
+                    "next_download_poll_at": 0.0,
+                }
+                self._jobs[action_id] = job
+                job_store.save_job(job)
+                logger.info("Novo job de clip criado: %s", job["job_id"])
+
+    async def _advance_jobs(self) -> None:
+        with self._lock:
+            active_jobs = [
+                job for job in self._jobs.values()
+                if job["status"] in {"queued", "creating", "polling", "ready"} 
+                and not (job["status"] == "ready" and job.get("download_url")) # Keep processing ready jobs until download URL fetched
+            ]
+
+        for job in active_jobs:
+            try:
+                if job["status"] == "queued":
+                    await self._handle_queued(job)
+                elif job["status"] == "polling":
+                    await self._handle_polling(job)
+                elif job["status"] == "ready" and not job.get("download_url"):
+                    await self._handle_download_fetch(job)
+            except Exception as error:
+                logger.error("Erro ao processar job %s: %s", job["job_id"], error)
+                if job["status"] != "ready": # Don't fail a ready job just because download fetch failed
+                    self._update_job(job["action_id"], status="failed", error=str(error))
+
+    async def _get_token(self) -> str:
+        if not self._token_provider:
+            raise RuntimeError("Token provider nao configurado.")
+        return await self._token_provider()
+
+    async def _handle_queued(self, job: dict[str, Any]) -> None:
+        action_id = job["action_id"]
+        broadcaster_id = job["broadcaster_id"]
+        mode = job["mode"]
+        
+        self._update_job(action_id, status="creating")
+        
+        try:
+            token = await self._get_token()
+            client_id = CLIENT_ID or ""
+            
+            resp = {}
+            if mode == "live":
+                resp = await create_clip_live(
+                    broadcaster_id=broadcaster_id,
+                    token=token,
+                    client_id=client_id,
+                    title=job.get("title", ""),
+                    duration=float(job.get("duration") or 30.0),
+                )
+            elif mode == "vod":
+                vod_id = job.get("vod_id")
+                vod_offset = job.get("vod_offset")
+                duration = job.get("duration", 30)
+                title = job.get("title", "")
+
+                if not vod_id or not vod_offset:
+                     raise ValueError("Dados de VOD ausentes no job.")
+
+                resp = await create_clip_from_vod(
+                    broadcaster_id=broadcaster_id,
+                    editor_id=EDITOR_ID or "",
+                    vod_id=vod_id,
+                    vod_offset=int(vod_offset),
+                    duration=int(duration),
+                    token=token,
+                    client_id=client_id,
+                    title=title,
+                )
+            else:
+                 self._update_job(action_id, status="failed", error=f"mode_not_supported: {mode}")
+                 return
+            
+            clip_id = resp.get("id")
+            edit_url = resp.get("edit_url")
+            
+            if not clip_id:
+                raise TwitchClipError("API retornou sucesso mas sem ID.")
+            
+            now = time.time()
+            self._update_job(
+                action_id,
+                status="polling",
+                twitch_clip_id=clip_id,
+                edit_url=edit_url,
+                poll_until=now + 20.0,
+                next_poll_at=now + 2.0,
+            )
+            logger.info("Clip criado na Twitch (%s): %s. Polling...", mode, clip_id)
+
+        except TwitchClipAuthError as e:
+            self._update_job(action_id, status="failed", error=f"auth_error: {e}")
+        except TwitchClipNotFoundError as e:
+            self._update_job(action_id, status="failed", error=f"not_found: {e}")
+        except TwitchClipRateLimitError as e:
+             self._update_job(action_id, status="failed", error=f"rate_limit: {e}")
+        except Exception as e:
+            self._update_job(action_id, status="failed", error=str(e))
+
+    async def _handle_polling(self, job: dict[str, Any]) -> None:
+        now = time.time()
+        if now < job["next_poll_at"]:
+            return
+        
+        if now > job["poll_until"]:
+            self._update_job(job["action_id"], status="failed", error="poll_timeout")
+            return
+
+        action_id = job["action_id"]
+        clip_id = job["twitch_clip_id"]
+        
+        try:
+            token = await self._get_token()
+            client_id = CLIENT_ID or ""
+            
+            clip_data = await get_clip(
+                clip_id=clip_id,
+                token=token,
+                client_id=client_id,
+            )
+            
+            if clip_data:
+                clip_url = clip_data.get("url")
+                self._update_job(
+                    action_id,
+                    status="ready",
+                    clip_url=clip_url,
+                )
+                logger.info("Clip pronto: %s", clip_url)
+            else:
+                self._update_job(
+                    action_id,
+                    next_poll_at=now + 3.0,
+                )
+        
+        except Exception as e:
+             logger.warning("Erro no polling do clip %s: %s", clip_id, e)
+             self._update_job(action_id, next_poll_at=now + 3.0)
+
+    async def _handle_download_fetch(self, job: dict[str, Any]) -> None:
+        # Tenta buscar a URL de download para jobs 'ready'
+        # Isso é um "best effort" e pode falhar por rate limit
+        action_id = job["action_id"]
+        clip_id = job["twitch_clip_id"]
+        broadcaster_id = job["broadcaster_id"]
+        
+        now = time.time()
+        if now < job.get("next_download_poll_at", 0):
+            return
+
+        try:
+            token = await self._get_token()
+            client_id = CLIENT_ID or ""
+            
+            url = await get_clip_download_url(
+                clip_id=clip_id,
+                token=token,
+                client_id=client_id,
+                broadcaster_id=broadcaster_id,
+                editor_id=EDITOR_ID or "",
+            )
+            
+            if url:
+                self._update_job(action_id, download_url=url)
+                logger.info("Download URL obtida para clip %s", clip_id)
+            else:
+                # Nao disponivel ainda, tenta novamente em 60s
+                self._update_job(action_id, next_download_poll_at=now + 60.0)
+            
+        except TwitchClipRateLimitError as e:
+            # Respeita o reset do rate limit se fornecido, senao espera 60s
+            wait_until = getattr(e, "reset_at", now + 60.0)
+            self._update_job(action_id, next_download_poll_at=wait_until)
+            logger.warning("Rate limit atingido para download do clip %s. Retentando em %ds", clip_id, int(wait_until - now))
+        except Exception as e:
+            logger.warning("Falha ao buscar download URL para %s: %s", clip_id, e)
+            # Espera um pouco antes de tentar novamente em caso de erro generico
+            self._update_job(action_id, next_download_poll_at=now + 120.0)
+
+    def _update_job(self, action_id: str, **kwargs: Any) -> None:
+        with self._lock:
+            if action_id not in self._jobs:
+                return
+            job = self._jobs[action_id]
+            job.update(kwargs)
+            job["updated_at"] = utc_iso(time.time())
+            
+            # Persist async-ish (fire and forget for now, store handles errors)
+            job_store.save_job(job)
+
+
+clip_jobs = ClipJobsRuntime()
+
+__all__ = ["ClipJobsRuntime", "clip_jobs"]

bot/clip_jobs_store.py

@@ -0,0 +1,137 @@
+import logging
+import threading
+from typing import Any, List, Optional
+import os
+import psycopg2
+from psycopg2.extras import RealDictCursor
+
+logger = logging.getLogger("byte.clips.store")
+
+COLLECTION_NAME = "clip_jobs"
+
+class SupabaseJobStore:
+    def __init__(self) -> None:
+        self._db_url = os.environ.get("SUPABASE_DB_URL")
+        self._lock = threading.Lock()
+        self._initialized = False
+        
+        if not self._db_url:
+            logger.warning("SUPABASE_DB_URL nao definido. SupabaseJobStore operando em modo offline (no-op).")
+
+    def _get_connection(self):
+        if not self._db_url:
+            return None
+        try:
+            conn = psycopg2.connect(self._db_url)
+            if not self._initialized:
+                self._ensure_table(conn)
+            return conn
+        except Exception as e:
+            logger.error("Falha ao conectar no Supabase/Postgres: %s", e)
+            return None
+
+    def _ensure_table(self, conn):
+        try:
+            with self._lock:
+                if self._initialized:
+                    return
+                with conn.cursor() as cur:
+                    cur.execute(f"""
+                        CREATE TABLE IF NOT EXISTS {COLLECTION_NAME} (
+                            job_id TEXT PRIMARY KEY,
+                            status TEXT NOT NULL,
+                            download_url TEXT,
+                            metadata JSONB,
+                            created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+                            updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+                        );
+                    """)
+                    conn.commit()
+                self._initialized = True
+        except Exception as e:
+            logger.error("Erro ao criar tabela no Supabase: %s", e)
+
+    def save_job(self, job: dict[str, Any]) -> None:
+        conn = self._get_connection()
+        if not conn:
+            return
+
+        job_id = job.get("job_id")
+        status = job.get("status", "unknown")
+        download_url = job.get("download_url")
+        
+        # O resto do job vira metadados JSON
+        job_metadata = {k: v for k, v in job.items() if k not in ["job_id", "status", "download_url"]}
+
+        try:
+            with conn.cursor() as cur:
+                cur.execute(f"""
+                    INSERT INTO {COLLECTION_NAME} (job_id, status, download_url, metadata, updated_at)
+                    VALUES (%s, %s, %s, %s, CURRENT_TIMESTAMP)
+                    ON CONFLICT (job_id) DO UPDATE SET
+                        status = EXCLUDED.status,
+                        download_url = EXCLUDED.download_url,
+                        metadata = EXCLUDED.metadata,
+                        updated_at = CURRENT_TIMESTAMP;
+                """, (job_id, status, download_url, psycopg2.extras.Json(job_metadata)))
+                conn.commit()
+        except Exception as e:
+            logger.error("Erro ao salvar job %s no Supabase: %s", job_id, e)
+        finally:
+            conn.close()
+
+    def load_active_jobs(self) -> List[dict[str, Any]]:
+        conn = self._get_connection()
+        if not conn:
+            return []
+
+        try:
+            with conn.cursor(cursor_factory=RealDictCursor) as cur:
+                active_statuses = ["queued", "creating", "polling"]
+                cur.execute(f"""
+                    SELECT * FROM {COLLECTION_NAME} 
+                    WHERE status IN %s 
+                    OR (status = 'ready' AND download_url IS NULL)
+                """, (tuple(active_statuses),))
+                
+                rows = cur.fetchall()
+                jobs = []
+                for row in rows:
+                    job = dict(row)
+                    # Mescla o JSONB de metadados de volta no dict principal para paridade com o bot
+                    if job.get("metadata"):
+                        meta = job.pop("metadata")
+                        job.update(meta)
+                    jobs.append(job)
+                
+                logger.info("Carregados %d jobs ativos do Supabase.", len(jobs))
+                return jobs
+        except Exception as e:
+            logger.error("Erro ao carregar jobs do Supabase: %s", e)
+            return []
+        finally:
+            conn.close()
+
+    def get_job(self, job_id: str) -> Optional[dict[str, Any]]:
+        conn = self._get_connection()
+        if not conn:
+            return None
+
+        try:
+            with conn.cursor(cursor_factory=RealDictCursor) as cur:
+                cur.execute(f"SELECT * FROM {COLLECTION_NAME} WHERE job_id = %s", (job_id,))
+                row = cur.fetchone()
+                if row:
+                    job = dict(row)
+                    if job.get("metadata"):
+                        meta = job.pop("metadata")
+                        job.update(meta)
+                    return job
+                return None
+        except Exception as e:
+            logger.error("Erro ao buscar job %s no Supabase: %s", job_id, e)
+            return None
+        finally:
+            conn.close()
+
+job_store = SupabaseJobStore()

bot/control_plane.py

@@ -0,0 +1,180 @@
+from typing import Any
+
+from bot.control_plane_actions import ControlPlaneActionQueue
+from bot.control_plane_config import ControlPlaneConfigRuntime
+from bot.control_plane_constants import (
+    RISK_AUTO_CHAT,
+    RISK_CLIP_CANDIDATE,
+    RISK_MODERATION_ACTION,
+    RISK_SUGGEST_STREAMER,
+    SUPPORTED_DECISIONS,
+    SUPPORTED_RISK_LEVELS,
+)
+
+
+class ControlPlaneState:
+    MAX_ACTION_ITEMS = 600
+
+    def __init__(self) -> None:
+        self._config_runtime = ControlPlaneConfigRuntime()
+        self._action_queue = ControlPlaneActionQueue(max_items=self.MAX_ACTION_ITEMS)
+
+    def get_config(self) -> dict[str, Any]:
+        return self._config_runtime.get_config()
+
+    def update_config(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._config_runtime.update_config(payload)
+
+    def set_loop_running(self, running: bool) -> None:
+        self._config_runtime.set_loop_running(running)
+
+    def touch_heartbeat(self, timestamp: float | None = None) -> None:
+        self._config_runtime.touch_heartbeat(timestamp=timestamp)
+
+    def register_tick(self, reason: str, timestamp: float | None = None) -> None:
+        self._config_runtime.register_tick(reason=reason, timestamp=timestamp)
+
+    def register_goal_run(
+        self,
+        goal_id: str,
+        risk: str,
+        timestamp: float | None = None,
+    ) -> None:
+        self._config_runtime.register_goal_run(
+            goal_id=goal_id,
+            risk=risk,
+            timestamp=timestamp,
+        )
+
+    def register_budget_block(self, reason: str, timestamp: float | None = None) -> None:
+        self._config_runtime.register_budget_block(reason=reason, timestamp=timestamp)
+
+    def register_dispatch_failure(self, reason: str, timestamp: float | None = None) -> None:
+        self._config_runtime.register_dispatch_failure(reason=reason, timestamp=timestamp)
+
+    def can_send_auto_chat(self, timestamp: float | None = None) -> tuple[bool, str, dict[str, int]]:
+        return self._config_runtime.can_send_auto_chat(timestamp=timestamp)
+
+    def register_auto_chat_sent(self, timestamp: float | None = None) -> None:
+        self._config_runtime.register_auto_chat_sent(timestamp=timestamp)
+
+    def consume_due_goals(self, *, force: bool = False, timestamp: float | None = None) -> list[dict[str, Any]]:
+        return self._config_runtime.consume_due_goals(force=force, timestamp=timestamp)
+
+    def enqueue_action(
+        self,
+        *,
+        kind: str,
+        risk: str,
+        title: str,
+        body: str,
+        payload: dict[str, Any] | None = None,
+        created_by: str = "autonomy",
+        timestamp: float | None = None,
+    ) -> dict[str, Any]:
+        return self._action_queue.enqueue_action(
+            kind=kind,
+            risk=risk,
+            title=title,
+            body=body,
+            payload=payload,
+            created_by=created_by,
+            timestamp=timestamp,
+        )
+
+    def decide_action(
+        self,
+        *,
+        action_id: str,
+        decision: str,
+        note: str = "",
+        decided_by: str = "dashboard",
+        timestamp: float | None = None,
+    ) -> dict[str, Any]:
+        return self._action_queue.decide_action(
+            action_id=action_id,
+            decision=decision,
+            note=note,
+            decided_by=decided_by,
+            timestamp=timestamp,
+        )
+
+    def list_actions(
+        self,
+        *,
+        status: str | None = None,
+        limit: int = 80,
+        timestamp: float | None = None,
+    ) -> dict[str, Any]:
+        return self._action_queue.list_actions(
+            status=status,
+            limit=limit,
+            ignore_after_seconds=self._config_runtime.action_ignore_after_seconds(),
+            timestamp=timestamp,
+        )
+
+    def build_capabilities(self, *, bot_mode: str) -> dict[str, Any]:
+        safe_mode = (bot_mode or "eventsub").strip().lower() or "eventsub"
+        channel_enabled = safe_mode == "irc"
+        if channel_enabled:
+            channel_reason = "Controle de canais ativo no runtime IRC."
+            supported_actions = ["list", "join", "part"]
+        else:
+            channel_reason = (
+                "Channel control de runtime so funciona em TWITCH_CHAT_MODE=irc. "
+                "No modo eventsub, join/part ficam bloqueados."
+            )
+            supported_actions = []
+
+        config = self.get_config()
+        return {
+            "channel_control": {
+                "enabled": channel_enabled,
+                "reason": channel_reason,
+                "supported_actions": supported_actions,
+            },
+            "autonomy": {
+                "enabled": True,
+                "reason": "Autonomia com agenda e budget anti-spam disponivel.",
+                "active": bool(config.get("autonomy_enabled", False)),
+            },
+            "risk_actions": {
+                "enabled": True,
+                "reason": "Fluxo por risco com fila e decisao approve/reject.",
+                "levels": sorted(SUPPORTED_RISK_LEVELS),
+            },
+            "response_contract": {
+                "max_messages": 1,
+                "max_lines": 4,
+            },
+            "clip_pipeline": {
+                "enabled": config.get("clip_pipeline_enabled", False),
+                "modes": ["live", "vod"],
+                "default_mode": config.get("clip_mode_default", "live"),
+            },
+        }
+
+    def runtime_snapshot(self, *, timestamp: float | None = None) -> dict[str, Any]:
+        runtime = self._config_runtime.runtime_base_snapshot(timestamp=timestamp)
+        queue_runtime = self._action_queue.runtime_snapshot(
+            ignore_after_seconds=self._config_runtime.action_ignore_after_seconds(),
+            timestamp=timestamp,
+        )
+        runtime["queue"] = queue_runtime.get("queue", {})
+        runtime["queue_window_60m"] = queue_runtime.get("queue_window_60m", {})
+        return runtime
+
+
+control_plane = ControlPlaneState()
+
+__all__ = [
+    "RISK_AUTO_CHAT",
+    "RISK_CLIP_CANDIDATE",
+    "RISK_SUGGEST_STREAMER",
+    "RISK_MODERATION_ACTION",
+    "SUPPORTED_RISK_LEVELS",
+    "SUPPORTED_DECISIONS",
+    "ControlPlaneState",
+    "control_plane",
+]
+

bot/control_plane_actions.py

@@ -0,0 +1,235 @@
+import copy
+import threading
+import time
+from collections import Counter, deque
+from typing import Any
+
+from bot.control_plane_constants import (
+    RISK_SUGGEST_STREAMER,
+    SUPPORTED_DECISIONS,
+    SUPPORTED_RISK_LEVELS,
+    clip_text,
+    utc_iso,
+)
+
+
+class ControlPlaneActionQueue:
+    def __init__(self, *, max_items: int = 600) -> None:
+        self._lock = threading.Lock()
+        self._max_items = max(10, int(max_items))
+        self._action_items: dict[str, dict[str, Any]] = {}
+        self._action_order: deque[str] = deque(maxlen=self._max_items)
+        self._action_counter = 0
+
+    def _expire_pending_actions_locked(
+        self, now: float, ignore_after_seconds: int
+    ) -> list[dict[str, Any]]:
+        expired: list[dict[str, Any]] = []
+        for action_id in list(self._action_order):
+            item = self._action_items.get(action_id)
+            if not item or item.get("status") != "pending":
+                continue
+            created_epoch = float(item.get("created_epoch", now))
+            if now - created_epoch < ignore_after_seconds:
+                continue
+            item["status"] = "ignored"
+            item["decision"] = "auto_ignore"
+            item["decision_note"] = "Sem decisao dentro da janela configurada."
+            item["updated_epoch"] = now
+            item["updated_at"] = utc_iso(now)
+            item["audit"].append(
+                {
+                    "ts": item["updated_at"],
+                    "event": "ignored_timeout",
+                    "by": "system",
+                    "note": item["decision_note"],
+                }
+            )
+            expired.append(copy.deepcopy(item))
+        return expired
+
+    def _summary_locked(self) -> dict[str, int]:
+        summary_counter: Counter[str] = Counter(
+            str(self._action_items[action_id].get("status", "pending"))
+            for action_id in self._action_order
+            if action_id in self._action_items
+        )
+        return {
+            "pending": int(summary_counter.get("pending", 0)),
+            "approved": int(summary_counter.get("approved", 0)),
+            "rejected": int(summary_counter.get("rejected", 0)),
+            "ignored": int(summary_counter.get("ignored", 0)),
+            "total": int(sum(summary_counter.values())),
+        }
+
+    def enqueue_action(
+        self,
+        *,
+        kind: str,
+        risk: str,
+        title: str,
+        body: str,
+        payload: dict[str, Any] | None = None,
+        created_by: str = "autonomy",
+        timestamp: float | None = None,
+    ) -> dict[str, Any]:
+        now = time.time() if timestamp is None else float(timestamp)
+        safe_risk = (risk or RISK_SUGGEST_STREAMER).strip().lower()
+        if safe_risk not in SUPPORTED_RISK_LEVELS:
+            safe_risk = RISK_SUGGEST_STREAMER
+
+        with self._lock:
+            self._action_counter += 1
+            action_id = f"act_{int(now * 1000)}_{self._action_counter}"
+            created_at = utc_iso(now)
+            item = {
+                "id": action_id,
+                "kind": clip_text(kind or "goal", max_chars=60),
+                "risk": safe_risk,
+                "title": clip_text(title or "Acao sem titulo", max_chars=80),
+                "body": clip_text(body or "", max_chars=420),
+                "payload": payload or {},
+                "status": "pending",
+                "decision": "",
+                "decision_note": "",
+                "created_at": created_at,
+                "updated_at": created_at,
+                "created_epoch": now,
+                "updated_epoch": now,
+                "audit": [
+                    {
+                        "ts": created_at,
+                        "event": "created",
+                        "by": clip_text(created_by or "autonomy", max_chars=40),
+                        "note": "",
+                    }
+                ],
+            }
+
+            max_queue_size = self._action_order.maxlen
+            if max_queue_size is not None and len(self._action_order) >= max_queue_size:
+                oldest_id = self._action_order.popleft()
+                self._action_items.pop(oldest_id, None)
+
+            self._action_order.append(action_id)
+            self._action_items[action_id] = item
+            return copy.deepcopy(item)
+
+    def decide_action(
+        self,
+        *,
+        action_id: str,
+        decision: str,
+        note: str = "",
+        decided_by: str = "dashboard",
+        timestamp: float | None = None,
+    ) -> dict[str, Any]:
+        safe_action_id = (action_id or "").strip()
+        if not safe_action_id:
+            raise ValueError("action_id obrigatorio.")
+
+        safe_decision = (decision or "").strip().lower()
+        if safe_decision not in SUPPORTED_DECISIONS:
+            raise ValueError("Decision invalida. Use: approve ou reject.")
+
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            item = self._action_items.get(safe_action_id)
+            if not item:
+                raise KeyError("action_not_found")
+            if item.get("status") != "pending":
+                raise RuntimeError("action_not_pending")
+
+            item["decision"] = safe_decision
+            item["decision_note"] = clip_text(note or "", max_chars=240)
+            item["status"] = "approved" if safe_decision == "approve" else "rejected"
+            item["updated_epoch"] = now
+            item["updated_at"] = utc_iso(now)
+            item["audit"].append(
+                {
+                    "ts": item["updated_at"],
+                    "event": item["status"],
+                    "by": clip_text(decided_by or "dashboard", max_chars=40),
+                    "note": item["decision_note"],
+                }
+            )
+            return copy.deepcopy(item)
+
+    def list_actions(
+        self,
+        *,
+        status: str | None = None,
+        limit: int = 80,
+        ignore_after_seconds: int = 900,
+        timestamp: float | None = None,
+    ) -> dict[str, Any]:
+        now = time.time() if timestamp is None else float(timestamp)
+        safe_limit = max(1, min(300, int(limit)))
+        safe_status = (status or "").strip().lower()
+        ttl_seconds = max(60, int(ignore_after_seconds))
+
+        with self._lock:
+            expired = self._expire_pending_actions_locked(now, ttl_seconds)
+            items: list[dict[str, Any]] = []
+            for action_id in reversed(self._action_order):
+                item = self._action_items.get(action_id)
+                if not item:
+                    continue
+                if safe_status and item.get("status") != safe_status:
+                    continue
+                items.append(copy.deepcopy(item))
+                if len(items) >= safe_limit:
+                    break
+
+            return {
+                "items": items,
+                "summary": self._summary_locked(),
+                "expired": expired,
+            }
+
+    def runtime_snapshot(
+        self,
+        *,
+        ignore_after_seconds: int = 900,
+        timestamp: float | None = None,
+    ) -> dict[str, Any]:
+        now = time.time() if timestamp is None else float(timestamp)
+        ttl_seconds = max(60, int(ignore_after_seconds))
+        window_cutoff = now - 3600
+
+        with self._lock:
+            self._expire_pending_actions_locked(now, ttl_seconds)
+            summary = self._summary_locked()
+
+            decisions_window_counter: Counter[str] = Counter()
+            pending_created_60m = 0
+            for action_id in self._action_order:
+                item = self._action_items.get(action_id)
+                if not item:
+                    continue
+                status = str(item.get("status", "pending"))
+                created_epoch = float(item.get("created_epoch", 0.0))
+                updated_epoch = float(item.get("updated_epoch", 0.0))
+                if status == "pending" and created_epoch >= window_cutoff:
+                    pending_created_60m += 1
+                if status in {"approved", "rejected", "ignored"} and updated_epoch >= window_cutoff:
+                    decisions_window_counter[status] += 1
+
+        decisions_total_60m = int(sum(decisions_window_counter.values()))
+        ignored_60m = int(decisions_window_counter.get("ignored", 0))
+        ignored_rate_60m = (
+            round((ignored_60m / decisions_total_60m) * 100.0, 1)
+            if decisions_total_60m > 0
+            else 0.0
+        )
+        return {
+            "queue": summary,
+            "queue_window_60m": {
+                "pending_created": int(pending_created_60m),
+                "approved": int(decisions_window_counter.get("approved", 0)),
+                "rejected": int(decisions_window_counter.get("rejected", 0)),
+                "ignored": ignored_60m,
+                "decisions_total": decisions_total_60m,
+                "ignored_rate": ignored_rate_60m,
+            },
+        }

bot/control_plane_config.py

@@ -0,0 +1,271 @@
+import copy
+import threading
+import time
+from collections import deque
+from typing import Any
+
+from bot.control_plane_config_helpers import (
+    budget_usage,
+    normalize_goals,
+    runtime_base_snapshot as build_runtime_base_snapshot,
+)
+from bot.control_plane_constants import (
+    clip_text,
+    default_goals_copy,
+    to_int,
+    utc_iso,
+)
+
+
+class ControlPlaneConfigRuntime:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._config: dict[str, Any] = {
+            "version": 1,
+            "autonomy_enabled": False,
+            "clip_pipeline_enabled": False,
+            "clip_api_enabled": False,
+            "clip_mode_default": "live",
+            "heartbeat_interval_seconds": 60,
+            "min_cooldown_seconds": 90,
+            "budget_messages_10m": 2,
+            "budget_messages_60m": 8,
+            "budget_messages_daily": 30,
+            "action_ignore_after_seconds": 900,
+            "goals": default_goals_copy(),
+            "updated_at": utc_iso(time.time()),
+        }
+        self._runtime: dict[str, Any] = {
+            "loop_running": False,
+            "last_heartbeat_at": 0.0,
+            "last_tick_at": 0.0,
+            "last_tick_reason": "boot",
+            "last_goal_id": "",
+            "last_goal_risk": "",
+            "autonomy_ticks_total": 0,
+            "autonomy_goal_runs_total": 0,
+            "autonomy_budget_blocked_total": 0,
+            "autonomy_dispatch_failures_total": 0,
+            "autonomy_auto_chat_sent_total": 0,
+            "autonomy_last_block_reason": "",
+        }
+        self._auto_chat_sent_timestamps: deque[float] = deque(maxlen=3000)
+        self._next_goal_due_at: dict[str, float] = {}
+
+    def get_config(self) -> dict[str, Any]:
+        with self._lock:
+            return copy.deepcopy(self._config)
+
+    def update_config(self, payload: dict[str, Any]) -> dict[str, Any]:
+        if not isinstance(payload, dict):
+            raise ValueError("Payload de configuracao invalido.")
+
+        now = time.time()
+        with self._lock:
+            config = copy.deepcopy(self._config)
+
+            if "autonomy_enabled" in payload:
+                config["autonomy_enabled"] = bool(payload.get("autonomy_enabled"))
+
+            if "clip_pipeline_enabled" in payload:
+                config["clip_pipeline_enabled"] = bool(payload.get("clip_pipeline_enabled"))
+
+            if "clip_api_enabled" in payload:
+                config["clip_api_enabled"] = bool(payload.get("clip_api_enabled"))
+
+            if "clip_mode_default" in payload:
+                val = str(payload.get("clip_mode_default") or "live").strip().lower()
+                if val in ("live", "vod"):
+                    config["clip_mode_default"] = val
+
+            if "heartbeat_interval_seconds" in payload:
+                config["heartbeat_interval_seconds"] = to_int(
+                    payload.get("heartbeat_interval_seconds"),
+                    minimum=15,
+                    maximum=3600,
+                    fallback=config["heartbeat_interval_seconds"],
+                )
+
+            if "min_cooldown_seconds" in payload:
+                config["min_cooldown_seconds"] = to_int(
+                    payload.get("min_cooldown_seconds"),
+                    minimum=15,
+                    maximum=3600,
+                    fallback=config["min_cooldown_seconds"],
+                )
+
+            if "budget_messages_10m" in payload:
+                config["budget_messages_10m"] = to_int(
+                    payload.get("budget_messages_10m"),
+                    minimum=0,
+                    maximum=100,
+                    fallback=config["budget_messages_10m"],
+                )
+
+            if "budget_messages_60m" in payload:
+                config["budget_messages_60m"] = to_int(
+                    payload.get("budget_messages_60m"),
+                    minimum=0,
+                    maximum=600,
+                    fallback=config["budget_messages_60m"],
+                )
+
+            if "budget_messages_daily" in payload:
+                config["budget_messages_daily"] = to_int(
+                    payload.get("budget_messages_daily"),
+                    minimum=0,
+                    maximum=5000,
+                    fallback=config["budget_messages_daily"],
+                )
+
+            if "action_ignore_after_seconds" in payload:
+                config["action_ignore_after_seconds"] = to_int(
+                    payload.get("action_ignore_after_seconds"),
+                    minimum=60,
+                    maximum=86_400,
+                    fallback=config["action_ignore_after_seconds"],
+                )
+
+            if "goals" in payload:
+                config["goals"] = normalize_goals(payload.get("goals"))
+                active_goal_ids = {goal["id"] for goal in config["goals"]}
+                self._next_goal_due_at = {
+                    goal_id: due_at
+                    for goal_id, due_at in self._next_goal_due_at.items()
+                    if goal_id in active_goal_ids
+                }
+
+            config["updated_at"] = utc_iso(now)
+            self._config = config
+            return copy.deepcopy(self._config)
+
+    def set_loop_running(self, running: bool) -> None:
+        with self._lock:
+            self._runtime["loop_running"] = bool(running)
+
+    def touch_heartbeat(self, timestamp: float | None = None) -> None:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            self._runtime["last_heartbeat_at"] = now
+
+    def register_tick(self, reason: str, timestamp: float | None = None) -> None:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            self._runtime["last_tick_at"] = now
+            self._runtime["last_tick_reason"] = clip_text(reason or "tick", max_chars=40)
+            self._runtime["autonomy_ticks_total"] += 1
+
+    def register_goal_run(
+        self,
+        goal_id: str,
+        risk: str,
+        timestamp: float | None = None,
+    ) -> None:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            self._runtime["autonomy_goal_runs_total"] += 1
+            self._runtime["last_goal_id"] = clip_text(goal_id, max_chars=60)
+            self._runtime["last_goal_risk"] = clip_text(risk, max_chars=32)
+            self._runtime["last_heartbeat_at"] = now
+
+    def register_budget_block(self, reason: str, timestamp: float | None = None) -> None:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            self._runtime["autonomy_budget_blocked_total"] += 1
+            self._runtime["autonomy_last_block_reason"] = clip_text(reason, max_chars=80)
+            self._runtime["last_heartbeat_at"] = now
+
+    def register_dispatch_failure(self, reason: str, timestamp: float | None = None) -> None:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            self._runtime["autonomy_dispatch_failures_total"] += 1
+            self._runtime["autonomy_last_block_reason"] = clip_text(reason, max_chars=80)
+            self._runtime["last_heartbeat_at"] = now
+
+    def can_send_auto_chat(self, timestamp: float | None = None) -> tuple[bool, str, dict[str, int]]:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            usage = budget_usage(self._auto_chat_sent_timestamps, now)
+            cfg = self._config
+
+            if int(cfg["budget_messages_daily"]) <= 0:
+                return False, "budget_daily_disabled", usage
+
+            last_sent = self._auto_chat_sent_timestamps[-1] if self._auto_chat_sent_timestamps else 0.0
+            min_cooldown = int(cfg["min_cooldown_seconds"])
+            if last_sent > 0 and now - last_sent < min_cooldown:
+                return False, "cooldown_active", usage
+
+            if int(cfg["budget_messages_10m"]) >= 0 and usage["messages_10m"] >= int(cfg["budget_messages_10m"]):
+                return False, "budget_10m_exceeded", usage
+
+            if int(cfg["budget_messages_60m"]) >= 0 and usage["messages_60m"] >= int(cfg["budget_messages_60m"]):
+                return False, "budget_60m_exceeded", usage
+
+            if usage["messages_daily"] >= int(cfg["budget_messages_daily"]):
+                return False, "budget_daily_exceeded", usage
+
+            return True, "ok", usage
+
+    def register_auto_chat_sent(self, timestamp: float | None = None) -> None:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            self._auto_chat_sent_timestamps.append(now)
+            self._runtime["autonomy_auto_chat_sent_total"] += 1
+            self._runtime["last_heartbeat_at"] = now
+
+    def consume_due_goals(self, *, force: bool = False, timestamp: float | None = None) -> list[dict[str, Any]]:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            if not self._config.get("autonomy_enabled", False) and not force:
+                return []
+
+            due_goals: list[dict[str, Any]] = []
+            active_goal_ids = set()
+
+            for goal in self._config.get("goals", []):
+                if not isinstance(goal, dict):
+                    continue
+                goal_id = str(goal.get("id", "") or "").strip()
+                if not goal_id:
+                    continue
+                active_goal_ids.add(goal_id)
+
+                if not bool(goal.get("enabled", True)):
+                    continue
+
+                interval = max(60, int(goal.get("interval_seconds", 600) or 600))
+                if force:
+                    due_goals.append(copy.deepcopy(goal))
+                    self._next_goal_due_at[goal_id] = now + interval
+                    continue
+
+                due_at = self._next_goal_due_at.get(goal_id)
+                if due_at is None:
+                    self._next_goal_due_at[goal_id] = now + interval
+                    continue
+
+                if now >= due_at:
+                    due_goals.append(copy.deepcopy(goal))
+                    self._next_goal_due_at[goal_id] = now + interval
+
+            self._next_goal_due_at = {
+                goal_id: due_at
+                for goal_id, due_at in self._next_goal_due_at.items()
+                if goal_id in active_goal_ids
+            }
+
+            return due_goals
+
+    def action_ignore_after_seconds(self) -> int:
+        with self._lock:
+            return max(60, int(self._config.get("action_ignore_after_seconds", 900)))
+
+    def runtime_base_snapshot(self, *, timestamp: float | None = None) -> dict[str, Any]:
+        now = time.time() if timestamp is None else float(timestamp)
+        with self._lock:
+            usage = budget_usage(self._auto_chat_sent_timestamps, now)
+            cfg = dict(self._config)
+            rt = dict(self._runtime)
+
+        return build_runtime_base_snapshot(config=cfg, runtime=rt, usage=usage)

bot/control_plane_config_helpers.py

@@ -0,0 +1,119 @@
+from collections import deque
+from typing import Any
+
+from bot.control_plane_constants import (
+    RISK_SUGGEST_STREAMER,
+    SUPPORTED_RISK_LEVELS,
+    clip_text,
+    default_goals_copy,
+    to_int,
+    utc_iso,
+)
+
+
+def normalize_goal(raw_goal: Any, index: int) -> dict[str, Any]:
+    goal = raw_goal if isinstance(raw_goal, dict) else {}
+    fallback_id = f"goal_{index + 1}"
+    raw_id = str(goal.get("id", "") or "").strip().lower().replace(" ", "_")
+    goal_id = "".join(ch for ch in raw_id if ch.isalnum() or ch == "_") or fallback_id
+
+    name = clip_text(str(goal.get("name", "") or goal_id).strip(), max_chars=60)
+    prompt = clip_text(str(goal.get("prompt", "") or "").strip(), max_chars=420)
+    risk = str(goal.get("risk", "") or "").strip().lower()
+    if risk not in SUPPORTED_RISK_LEVELS:
+        risk = RISK_SUGGEST_STREAMER
+
+    interval_seconds = to_int(
+        goal.get("interval_seconds", 600),
+        minimum=60,
+        maximum=86_400,
+        fallback=600,
+    )
+    enabled = bool(goal.get("enabled", True))
+    return {
+        "id": goal_id,
+        "name": name,
+        "prompt": prompt,
+        "risk": risk,
+        "interval_seconds": interval_seconds,
+        "enabled": enabled,
+    }
+
+
+def normalize_goals(raw_goals: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw_goals, list):
+        return default_goals_copy()
+
+    normalized: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    for index, item in enumerate(raw_goals):
+        safe_goal = normalize_goal(item, index)
+        if safe_goal["id"] in seen_ids:
+            safe_goal["id"] = f"{safe_goal['id']}_{index + 1}"
+        seen_ids.add(safe_goal["id"])
+        normalized.append(safe_goal)
+
+    return normalized or default_goals_copy()
+
+
+def prune_auto_chat_history(history: deque[float], now: float) -> None:
+    daily_cutoff = now - 86_400
+    while history and history[0] < daily_cutoff:
+        history.popleft()
+
+
+def budget_usage(history: deque[float], now: float) -> dict[str, int]:
+    prune_auto_chat_history(history, now)
+    cutoff_10m = now - 600
+    cutoff_60m = now - 3600
+    usage_10m = 0
+    usage_60m = 0
+    usage_daily = 0
+    for timestamp in history:
+        usage_daily += 1
+        if timestamp >= cutoff_60m:
+            usage_60m += 1
+        if timestamp >= cutoff_10m:
+            usage_10m += 1
+    return {
+        "messages_10m": usage_10m,
+        "messages_60m": usage_60m,
+        "messages_daily": usage_daily,
+    }
+
+
+def runtime_base_snapshot(
+    *,
+    config: dict[str, Any],
+    runtime: dict[str, Any],
+    usage: dict[str, int],
+) -> dict[str, Any]:
+    return {
+        "enabled": bool(config.get("autonomy_enabled", False)),
+        "loop_running": bool(runtime.get("loop_running", False)),
+        "last_heartbeat_at": utc_iso(float(runtime.get("last_heartbeat_at", 0.0)))
+        if float(runtime.get("last_heartbeat_at", 0.0)) > 0
+        else "",
+        "last_heartbeat_epoch": float(runtime.get("last_heartbeat_at", 0.0)),
+        "last_tick_at": utc_iso(float(runtime.get("last_tick_at", 0.0)))
+        if float(runtime.get("last_tick_at", 0.0)) > 0
+        else "",
+        "last_tick_epoch": float(runtime.get("last_tick_at", 0.0)),
+        "last_tick_reason": str(runtime.get("last_tick_reason", "")),
+        "last_goal_id": str(runtime.get("last_goal_id", "")),
+        "last_goal_risk": str(runtime.get("last_goal_risk", "")),
+        "autonomy_ticks_total": int(runtime.get("autonomy_ticks_total", 0)),
+        "autonomy_goal_runs_total": int(runtime.get("autonomy_goal_runs_total", 0)),
+        "autonomy_budget_blocked_total": int(runtime.get("autonomy_budget_blocked_total", 0)),
+        "autonomy_dispatch_failures_total": int(runtime.get("autonomy_dispatch_failures_total", 0)),
+        "autonomy_auto_chat_sent_total": int(runtime.get("autonomy_auto_chat_sent_total", 0)),
+        "autonomy_last_block_reason": str(runtime.get("autonomy_last_block_reason", "")),
+        "budget_usage": {
+            **usage,
+            "limit_10m": int(config.get("budget_messages_10m", 0)),
+            "limit_60m": int(config.get("budget_messages_60m", 0)),
+            "limit_daily": int(config.get("budget_messages_daily", 0)),
+            "cooldown_seconds": int(config.get("min_cooldown_seconds", 0)),
+        },
+    }
+

bot/control_plane_constants.py

@@ -0,0 +1,76 @@
+import copy
+from datetime import datetime, timezone
+from typing import Any
+
+RISK_AUTO_CHAT = "auto_chat"
+RISK_SUGGEST_STREAMER = "suggest_streamer"
+RISK_MODERATION_ACTION = "moderation_action"
+RISK_CLIP_CANDIDATE = "clip_candidate"
+SUPPORTED_RISK_LEVELS = {
+    RISK_AUTO_CHAT,
+    RISK_SUGGEST_STREAMER,
+    RISK_MODERATION_ACTION,
+    RISK_CLIP_CANDIDATE,
+}
+SUPPORTED_DECISIONS = {"approve", "reject"}
+
+DEFAULT_GOALS = [
+    {
+        "id": "chat_pulse",
+        "name": "Pulso do chat",
+        "prompt": "Resumo autonomo curto com o momento atual da live e um insight util.",
+        "risk": RISK_AUTO_CHAT,
+        "interval_seconds": 900,
+        "enabled": True,
+    },
+    {
+        "id": "streamer_hint",
+        "name": "Sugestao ao streamer",
+        "prompt": "Sugestao objetiva para aumentar clareza, ritmo ou engajamento da live.",
+        "risk": RISK_SUGGEST_STREAMER,
+        "interval_seconds": 600,
+        "enabled": True,
+    },
+    {
+        "id": "safety_watch",
+        "name": "Watch de moderacao",
+        "prompt": "Sinalize padroes de risco no chat e recomende acao moderativa conservadora.",
+        "risk": RISK_MODERATION_ACTION,
+        "interval_seconds": 300,
+        "enabled": True,
+    },
+    {
+        "id": "detect_clip",
+        "name": "Deteccao de clips",
+        "prompt": "Analise o contexto recente (chat e eventos) e identifique um momento digno de clipe.",
+        "risk": RISK_CLIP_CANDIDATE,
+        "interval_seconds": 600,
+        "enabled": False,
+    },
+]
+
+
+def utc_iso(timestamp: float) -> str:
+    return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat(
+        timespec="seconds"
+    ).replace("+00:00", "Z")
+
+
+def clip_text(text: str, max_chars: int = 360) -> str:
+    compact = " ".join((text or "").split())
+    if len(compact) <= max_chars:
+        return compact
+    return compact[: max_chars - 3].rstrip() + "..."
+
+
+def to_int(value: Any, *, minimum: int, maximum: int, fallback: int) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return fallback
+    return max(minimum, min(maximum, parsed))
+
+
+def default_goals_copy() -> list[dict[str, Any]]:
+    return copy.deepcopy(DEFAULT_GOALS)
+

bot/dashboard_server.py

@@ -0,0 +1,187 @@
+import json
+import os
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+
+from bot.channel_control import is_dashboard_admin_authorized, parse_terminal_command
+from bot.dashboard_server_routes import (
+    CHANNEL_CONTROL_IRC_ONLY_ACTIONS,
+    build_observability_payload,
+    handle_get,
+    handle_post,
+    handle_put,
+)
+from bot.runtime_config import (
+    BYTE_DASHBOARD_ADMIN_TOKEN,
+    DASHBOARD_DIR,
+    TWITCH_CHAT_MODE,
+    irc_channel_control,
+)
+
+
+class HealthHandler(BaseHTTPRequestHandler):
+    MAX_CONTROL_BODY_BYTES = 4096
+    CHANNEL_CONTROL_IRC_ONLY_ACTIONS = CHANNEL_CONTROL_IRC_ONLY_ACTIONS
+
+    def _send_cors_headers(self) -> None:
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, PUT, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type, X-Byte-Admin-Token, Authorization")
+
+    def _send_bytes(
+        self, payload: bytes, content_type: str, status_code: int = 200
+    ) -> None:
+        self.send_response(status_code)
+        self._send_cors_headers()
+        self.send_header("Content-Type", content_type)
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _send_json(self, payload: dict[str, Any], status_code: int = 200) -> None:
+        serialized = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self._send_bytes(
+            serialized, "application/json; charset=utf-8", status_code=status_code
+        )
+
+    def _send_text(self, text: str, status_code: int = 200) -> None:
+        self._send_bytes(
+            text.encode("utf-8"), "text/plain; charset=utf-8", status_code=status_code
+        )
+
+    def _dashboard_authorized(self) -> bool:
+        if not BYTE_DASHBOARD_ADMIN_TOKEN:
+            return True
+        authorized = is_dashboard_admin_authorized(
+            self.headers, BYTE_DASHBOARD_ADMIN_TOKEN
+        )
+        if not authorized:
+            from bot.runtime_config import logger
+            logger.warning("Auth rejection for route %s from %s", self.path, self.address_string())
+        return authorized
+
+    def _send_dashboard_auth_challenge(self) -> None:
+        payload = b"Unauthorized"
+        self.send_response(401)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("WWW-Authenticate", 'Basic realm="Byte Dashboard"')
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _send_forbidden(self) -> None:
+        self._send_json(
+            {"ok": False, "error": "forbidden", "message": "Forbidden"},
+            status_code=403,
+        )
+
+    def _read_json_payload(self, *, allow_empty: bool = False) -> dict[str, Any]:
+        raw_length = str(self.headers.get("Content-Length", "0") or "0")
+        try:
+            content_length = int(raw_length)
+        except ValueError as error:
+            raise ValueError("Invalid Content-Length header.") from error
+        if content_length <= 0:
+            if allow_empty:
+                return {}
+            raise ValueError("Request body is required.")
+        if content_length > self.MAX_CONTROL_BODY_BYTES:
+            raise ValueError("Request body is too large.")
+
+        payload_bytes = self.rfile.read(content_length)
+        if not payload_bytes:
+            if allow_empty:
+                return {}
+            raise ValueError("Request body is empty.")
+        try:
+            payload = json.loads(payload_bytes.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ValueError("Invalid JSON payload.") from error
+        if not isinstance(payload, dict):
+            raise ValueError("JSON payload must be an object.")
+        return payload
+
+    def _send_dashboard_asset(self, relative_path: str, content_type: str) -> bool:
+        target_path = (DASHBOARD_DIR / relative_path).resolve()
+        if DASHBOARD_DIR not in target_path.parents:
+            self._send_text("Not Found", status_code=404)
+            return True
+        if not target_path.is_file():
+            self._send_text("Not Found", status_code=404)
+            return True
+        self._send_bytes(
+            target_path.read_bytes(), content_type=content_type, status_code=200
+        )
+        return True
+
+    def _build_observability_payload(self) -> dict[str, Any]:
+        return build_observability_payload()
+
+    def _handle_channel_control(self, payload: dict[str, Any]) -> tuple[dict[str, Any], int]:
+        action = str(payload.get("action", "") or "").strip().lower()
+        channel_login = str(payload.get("channel", "") or "").strip()
+        command_text = str(payload.get("command", "") or "").strip()
+        if command_text:
+            action, channel_login = parse_terminal_command(command_text)
+
+        if TWITCH_CHAT_MODE != "irc":
+            if action in self.CHANNEL_CONTROL_IRC_ONLY_ACTIONS:
+                return (
+                    {
+                        "ok": False,
+                        "error": "unsupported_mode",
+                        "message": "Channel control de runtime so funciona em TWITCH_CHAT_MODE=irc.",
+                        "mode": TWITCH_CHAT_MODE,
+                        "action": action,
+                    },
+                    409,
+                )
+            if action == "list":
+                return (
+                    {
+                        "ok": True,
+                        "action": "list",
+                        "channels": [],
+                        "mode": TWITCH_CHAT_MODE,
+                        "message": "Sem runtime IRC ativo neste modo. join/part ficam bloqueados em eventsub.",
+                    },
+                    200,
+                )
+
+        result = irc_channel_control.execute(action=action, channel_login=channel_login)
+        result["mode"] = TWITCH_CHAT_MODE
+        if result.get("ok"):
+            return result, 200
+
+        error_code = str(result.get("error", "") or "")
+        if error_code in {"runtime_unavailable", "timeout"}:
+            status_code = 503
+        elif error_code in {"runtime_error"}:
+            status_code = 500
+        else:
+            status_code = 400
+        return result, status_code
+
+    def do_OPTIONS(self) -> None:
+        self.send_response(204)
+        self._send_cors_headers()
+        self.end_headers()
+
+    def do_GET(self) -> None:
+        handle_get(self)
+
+    def do_PUT(self) -> None:
+        handle_put(self)
+
+    def do_POST(self) -> None:
+        handle_post(self)
+
+    def log_message(self, format: str, *args: object) -> None:
+        return
+
+
+def run_server() -> None:
+    port = int(os.environ.get("PORT", "8080"))
+    HTTPServer(("0.0.0.0", port), HealthHandler).serve_forever()

bot/dashboard_server_routes.py

@@ -0,0 +1,205 @@
+import mimetypes
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+from bot.clip_jobs_runtime import clip_jobs
+from bot.control_plane import control_plane
+from bot.hud_runtime import hud_runtime
+from bot.logic import BOT_BRAND, context
+from bot.observability import observability
+from bot.runtime_config import BYTE_VERSION, TWITCH_CHAT_MODE
+from bot.sentiment_engine import sentiment_engine
+from bot.vision_runtime import vision_runtime
+
+CHANNEL_CONTROL_IRC_ONLY_ACTIONS = {"join", "part"}
+HEALTH_ROUTES = {"/health", "/health/", "/healthz", "/healthz/"}
+
+
+def _is_api_route(route: str) -> bool:
+    return route.startswith("/api/")
+
+
+def build_observability_payload() -> dict[str, Any]:
+    snapshot = observability.snapshot(
+        bot_brand=BOT_BRAND,
+        bot_version=BYTE_VERSION,
+        bot_mode=TWITCH_CHAT_MODE,
+        stream_context=context,
+    )
+    capabilities = control_plane.build_capabilities(bot_mode=TWITCH_CHAT_MODE)
+    autonomy = control_plane.runtime_snapshot()
+    queue_window_60m = autonomy.get("queue_window_60m", {})
+    current_outcomes = snapshot.get("agent_outcomes", {}) or {}
+    snapshot["agent_outcomes"] = {
+        **current_outcomes,
+        "ignored_rate_60m": float(queue_window_60m.get("ignored_rate", 0.0)),
+        "ignored_total_60m": int(queue_window_60m.get("ignored", 0)),
+        "decisions_total_60m": int(queue_window_60m.get("decisions_total", 0)),
+    }
+    snapshot["capabilities"] = capabilities
+    snapshot["autonomy"] = autonomy
+    snapshot["ok"] = True
+    return snapshot
+
+
+def _dashboard_asset_route(handler: Any, route: str) -> bool:
+    if route in {"/", "/dashboard", "/dashboard/"}:
+        handler._send_dashboard_asset("index.html", "text/html; charset=utf-8")
+        return True
+    if route.startswith("/dashboard/"):
+        relative_path = route[len("/dashboard/") :]
+        guessed_content_type, _ = mimetypes.guess_type(relative_path)
+        content_type = guessed_content_type or "application/octet-stream"
+        if content_type == "text/javascript":
+            content_type = "application/javascript"
+        if content_type.startswith("text/") or content_type in {
+            "application/javascript",
+            "application/json",
+        }:
+            content_type = f"{content_type}; charset=utf-8"
+        handler._send_dashboard_asset(relative_path, content_type)
+        return True
+    return False
+
+
+def handle_get(handler: Any) -> None:
+    parsed_path = urlparse(handler.path or "/")
+    route = parsed_path.path or "/"
+    query = parse_qs(parsed_path.query or "")
+    if route in HEALTH_ROUTES:
+        handler._send_text("AGENT_ONLINE", status_code=200)
+        return
+
+    is_dashboard_route = route in {"/dashboard", "/dashboard/"} or route.startswith(
+        "/dashboard/"
+    )
+    if _is_api_route(route) and not handler._dashboard_authorized():
+        handler._send_forbidden()
+        return
+
+    if route == "/api/observability":
+        handler._send_json(handler._build_observability_payload(), status_code=200)
+        return
+
+    if route == "/api/control-plane":
+        handler._send_json(
+            {
+                "ok": True,
+                "mode": TWITCH_CHAT_MODE,
+                "config": control_plane.get_config(),
+                "autonomy": control_plane.runtime_snapshot(),
+                "capabilities": control_plane.build_capabilities(bot_mode=TWITCH_CHAT_MODE),
+            },
+            status_code=200,
+        )
+        return
+
+    if route == "/api/action-queue":
+        status_filter = str((query.get("status") or [""])[0] or "").strip().lower()
+        limit_raw = str((query.get("limit") or ["80"])[0] or "80")
+        try:
+            limit = int(limit_raw)
+        except ValueError:
+            limit = 80
+        queue_payload = control_plane.list_actions(
+            status=status_filter or None,
+            limit=limit,
+        )
+        handler._send_json(
+            {
+                "ok": True,
+                "mode": TWITCH_CHAT_MODE,
+                **queue_payload,
+            },
+            status_code=200,
+        )
+        return
+
+    if route == "/api/clip-jobs":
+        jobs = clip_jobs.get_jobs()
+        handler._send_json(
+            {
+                "ok": True,
+                "mode": TWITCH_CHAT_MODE,
+                "items": jobs,
+            },
+            status_code=200,
+        )
+        return
+
+    if route == "/api/hud/messages":
+        since_raw = str((query.get("since") or ["0"])[0] or "0")
+        try:
+            since = float(since_raw)
+        except ValueError:
+            since = 0.0
+        messages = hud_runtime.get_messages(since=since)
+        handler._send_json({"ok": True, "messages": messages}, status_code=200)
+        return
+
+    if route == "/api/sentiment/scores":
+        scores = sentiment_engine.get_scores()
+        scores["vibe"] = sentiment_engine.get_vibe()
+        handler._send_json({"ok": True, **scores}, status_code=200)
+        return
+
+    if route == "/api/vision/status":
+        handler._send_json({"ok": True, **vision_runtime.get_status()}, status_code=200)
+        return
+
+    if _dashboard_asset_route(handler, route):
+        return
+
+    handler._send_text("Not Found", status_code=404)
+
+
+def handle_put(handler: Any) -> None:
+    parsed_path = urlparse(handler.path or "/")
+    route = parsed_path.path or "/"
+    if route != "/api/control-plane":
+        handler._send_text("Not Found", status_code=404)
+        return
+
+    if not handler._dashboard_authorized():
+        handler._send_forbidden()
+        return
+
+    try:
+        payload = handler._read_json_payload()
+    except ValueError as error:
+        handler._send_json(
+            {"ok": False, "error": "invalid_request", "message": str(error)},
+            status_code=400,
+        )
+        return
+
+    try:
+        updated_config = control_plane.update_config(payload)
+    except ValueError as error:
+        handler._send_json(
+            {"ok": False, "error": "invalid_request", "message": str(error)},
+            status_code=400,
+        )
+        return
+
+    handler._send_json(
+        {
+            "ok": True,
+            "mode": TWITCH_CHAT_MODE,
+            "config": updated_config,
+            "autonomy": control_plane.runtime_snapshot(),
+            "capabilities": control_plane.build_capabilities(bot_mode=TWITCH_CHAT_MODE),
+        },
+        status_code=200,
+    )
+
+
+from bot.dashboard_server_routes_post import handle_post  # noqa: E402, F401
+
+__all__ = [
+    "build_observability_payload",
+    "handle_get",
+    "handle_put",
+    "handle_post",
+]
+

bot/dashboard_server_routes_post.py

@@ -0,0 +1,162 @@
+from typing import Any
+from urllib.parse import urlparse
+
+from bot.autonomy_runtime import autonomy_runtime
+from bot.control_plane import control_plane
+from bot.runtime_config import TWITCH_CHAT_MODE
+from bot.vision_runtime import vision_runtime
+
+
+def handle_post(handler: Any) -> None:
+    parsed_path = urlparse(handler.path or "/")
+    route = parsed_path.path or "/"
+
+    if route == "/api/channel-control":
+        _handle_channel_control_post(handler)
+        return
+
+    if route == "/api/autonomy/tick":
+        _handle_autonomy_tick(handler)
+        return
+
+    if route.startswith("/api/action-queue/") and route.endswith("/decision"):
+        _handle_action_decision(handler, route)
+        return
+
+    if route == "/api/vision/ingest":
+        _handle_vision_ingest(handler)
+        return
+
+    handler._send_text("Not Found", status_code=404)
+
+
+def _handle_channel_control_post(handler: Any) -> None:
+    if not handler._dashboard_authorized():
+        handler._send_forbidden()
+        return
+    try:
+        payload = handler._read_json_payload()
+    except ValueError as error:
+        handler._send_json(
+            {"ok": False, "error": "invalid_request", "message": str(error)},
+            status_code=400,
+        )
+        return
+
+    try:
+        response_payload, status_code = handler._handle_channel_control(payload)
+    except ValueError as error:
+        handler._send_json(
+            {"ok": False, "error": "invalid_command", "message": str(error)},
+            status_code=400,
+        )
+        return
+    handler._send_json(response_payload, status_code=status_code)
+
+
+def _handle_autonomy_tick(handler: Any) -> None:
+    if not handler._dashboard_authorized():
+        handler._send_forbidden()
+        return
+    try:
+        payload = handler._read_json_payload(allow_empty=True)
+    except ValueError as error:
+        handler._send_json(
+            {"ok": False, "error": "invalid_request", "message": str(error)},
+            status_code=400,
+        )
+        return
+    force = bool(payload.get("force", True))
+    reason = str(payload.get("reason", "manual") or "manual")
+    try:
+        tick_result = autonomy_runtime.run_manual_tick(force=force, reason=reason)
+    except TimeoutError as error:
+        handler._send_json(
+            {"ok": False, "error": "timeout", "message": str(error)},
+            status_code=503,
+        )
+        return
+    handler._send_json(tick_result, status_code=200)
+
+
+def _handle_action_decision(handler: Any, route: str) -> None:
+    if not handler._dashboard_authorized():
+        handler._send_forbidden()
+        return
+    action_id = route.removeprefix("/api/action-queue/").removesuffix("/decision").strip()
+    if not action_id:
+        handler._send_json(
+            {"ok": False, "error": "invalid_request", "message": "Action id obrigatorio."},
+            status_code=400,
+        )
+        return
+    try:
+        payload = handler._read_json_payload()
+    except ValueError as error:
+        handler._send_json(
+            {"ok": False, "error": "invalid_request", "message": str(error)},
+            status_code=400,
+        )
+        return
+    decision = str(payload.get("decision", "") or "").strip().lower()
+    note = str(payload.get("note", "") or "").strip()
+    try:
+        updated_item = control_plane.decide_action(
+            action_id=action_id,
+            decision=decision,
+            note=note,
+        )
+    except ValueError as error:
+        handler._send_json(
+            {"ok": False, "error": "invalid_request", "message": str(error)},
+            status_code=400,
+        )
+        return
+    except KeyError:
+        handler._send_json(
+            {"ok": False, "error": "action_not_found", "message": "Action nao encontrada."},
+            status_code=404,
+        )
+        return
+    except RuntimeError as error:
+        handler._send_json(
+            {"ok": False, "error": "action_not_pending", "message": str(error)},
+            status_code=409,
+        )
+        return
+
+    handler._send_json(
+        {
+            "ok": True,
+            "item": updated_item,
+            "mode": TWITCH_CHAT_MODE,
+        },
+        status_code=200,
+    )
+
+
+def _handle_vision_ingest(handler: Any) -> None:
+    if not handler._dashboard_authorized():
+        handler._send_forbidden()
+        return
+
+    content_type = str(handler.headers.get("Content-Type", "") or "").strip().lower()
+    if content_type not in {"image/jpeg", "image/png", "image/webp"}:
+        handler._send_json(
+            {"ok": False, "error": "invalid_content_type", "message": "Use image/jpeg, image/png or image/webp."},
+            status_code=400,
+        )
+        return
+
+    content_length = int(handler.headers.get("Content-Length", 0) or 0)
+    if content_length <= 0:
+        handler._send_json(
+            {"ok": False, "error": "empty_body", "message": "Frame body vazio."},
+            status_code=400,
+        )
+        return
+
+    frame_bytes = handler.rfile.read(content_length)
+    result = vision_runtime.ingest_frame(frame_bytes, mime_type=content_type)
+    status_code = 200 if result.get("ok") else 429 if result.get("reason") == "rate_limited" else 400
+    handler._send_json(result, status_code=status_code)

bot/eventsub_runtime.py

@@ -0,0 +1,232 @@
+import os
+import asyncio
+from typing import Any, cast
+
+import twitchio  # pyright: ignore[reportMissingImports]
+from twitchio import eventsub  # pyright: ignore[reportMissingImports]
+from twitchio.ext import commands  # pyright: ignore[reportMissingImports]
+
+from bot.access_control import is_owner
+from bot.autonomy_runtime import autonomy_runtime
+from bot.logic import BOT_BRAND, OBSERVABILITY_TYPES, agent_inference, context
+from bot.observability import observability
+from bot.prompt_runtime import format_chat_reply, handle_byte_prompt_text
+from bot.runtime_config import (
+    BOT_ID,
+    CHANNEL_ID,
+    CLIENT_ID,
+    ENABLE_LIVE_CONTEXT_LEARNING,
+    OWNER_ID,
+    client,
+    logger,
+)
+from bot.scene_runtime import auto_update_scene_from_message
+from bot.status_runtime import build_status_line
+from bot import byte_semantics
+
+
+def _require_env(name: str) -> str:
+    value = (os.environ.get(name) or "").strip()
+    if not value:
+        raise RuntimeError(f"Variavel obrigatoria ausente: {name}")
+    return value
+
+
+def get_ctx_message_text(ctx: commands.Context) -> str:
+    message = getattr(ctx, "message", None)
+    return str(getattr(message, "text", "") or "")
+
+
+def get_ctx_author(ctx: commands.Context) -> Any:
+    message = getattr(ctx, "message", None)
+    return getattr(message, "author", None)
+
+
+parse_byte_prompt = byte_semantics.parse_byte_prompt
+
+
+class AgentComponent(commands.Component):
+    def __init__(self, bot: "ByteBot") -> None:
+        self.bot = bot
+
+    async def component_check(self, ctx: commands.Context) -> bool:
+        return True
+
+    @commands.command(name="ask")
+    async def ask(self, ctx: commands.Context) -> None:
+        query = get_ctx_message_text(ctx).removeprefix("!ask").strip()
+        if not query:
+            return
+        author_name = str(getattr(get_ctx_author(ctx), "name", "viewer") or "viewer")
+        ans = await agent_inference(
+            query,
+            author_name,
+            client,
+            context,
+            enable_live_context=ENABLE_LIVE_CONTEXT_LEARNING,
+        )
+        await ctx.reply(format_chat_reply(ans))
+
+    @commands.command(name="vibe")
+    async def vibe(self, ctx: commands.Context) -> None:
+        author_id = str(getattr(get_ctx_author(ctx), "id", "") or "")
+        if is_owner(author_id, OWNER_ID):
+            new_vibe = get_ctx_message_text(ctx).removeprefix("!vibe").strip()
+            context.stream_vibe = new_vibe or "Conversa"
+            context.last_event = "Vibe atualizada"
+            await ctx.reply(f"Vibe atualizada para: {context.stream_vibe}")
+
+    @commands.command(name="style")
+    async def style(self, ctx: commands.Context) -> None:
+        style_text = get_ctx_message_text(ctx).removeprefix("!style").strip()
+        author_id = str(getattr(get_ctx_author(ctx), "id", "") or "")
+        if not is_owner(author_id, OWNER_ID):
+            await ctx.reply("Somente o dono do canal pode ajustar o estilo.")
+            return
+        if not style_text:
+            await ctx.reply(format_chat_reply(f"Estilo atual: {context.style_profile}"))
+            return
+
+        context.style_profile = style_text
+        context.last_event = "Estilo de conversa atualizado"
+        await ctx.reply("Estilo de conversa atualizado.")
+
+    @commands.command(name="scene")
+    async def scene(self, ctx: commands.Context) -> None:
+        payload = get_ctx_message_text(ctx).removeprefix("!scene").strip()
+        if not payload:
+            observability_text = context.format_observability()
+            await ctx.reply(
+                format_chat_reply(f"Observabilidade da live: {observability_text}")
+            )
+            return
+
+        author_id = str(getattr(get_ctx_author(ctx), "id", "") or "")
+        if not is_owner(author_id, OWNER_ID):
+            await ctx.reply("Somente o dono do canal pode atualizar a observabilidade.")
+            return
+
+        tokens = payload.split(maxsplit=1)
+        action_or_type = tokens[0].lower()
+        if action_or_type == "clear":
+            if len(tokens) < 2:
+                await ctx.reply(
+                    f"Uso: !scene clear <tipo>. Tipos: {context.list_supported_content_types()}"
+                )
+                return
+            content_type = tokens[1].strip().lower()
+            if not context.clear_content(content_type):
+                await ctx.reply(
+                    f"Tipo invalido. Tipos: {context.list_supported_content_types()}"
+                )
+                return
+            label = OBSERVABILITY_TYPES.get(content_type, content_type)
+            await ctx.reply(f"Contexto removido: {label}.")
+            return
+
+        if len(tokens) < 2:
+            await ctx.reply(
+                f"Uso: !scene <tipo> <descricao>. Tipos: {context.list_supported_content_types()}"
+            )
+            return
+
+        content_type = action_or_type
+        description = tokens[1].strip()
+        if not context.update_content(content_type, description):
+            await ctx.reply(
+                f"Tipo invalido ou descricao vazia. Tipos: {context.list_supported_content_types()}"
+            )
+            return
+
+        label = OBSERVABILITY_TYPES.get(content_type, content_type)
+        await ctx.reply(format_chat_reply(f"Contexto atualizado: {label} -> {description}"))
+
+    @commands.command(name="status")
+    async def status(self, ctx: commands.Context) -> None:
+        await ctx.reply(format_chat_reply(self.bot.build_status_line()))
+
+
+class ByteBot(commands.Bot):
+    def __init__(self, client_secret: str) -> None:
+        resolved_client_id = CLIENT_ID or _require_env("TWITCH_CLIENT_ID")
+        resolved_bot_id = BOT_ID or _require_env("TWITCH_BOT_ID")
+        super().__init__(
+            client_id=resolved_client_id,
+            client_secret=client_secret,
+            bot_id=resolved_bot_id,
+            owner_id=OWNER_ID or "",
+            prefix="!",
+        )
+
+    async def setup_hook(self) -> None:
+        autonomy_runtime.bind(
+            loop=asyncio.get_running_loop(),
+            mode="eventsub",
+            auto_chat_dispatcher=None,
+        )
+        await self.add_component(AgentComponent(self))
+        if not CHANNEL_ID:
+            raise RuntimeError("TWITCH_CHANNEL_ID e obrigatorio no modo eventsub.")
+        payload = eventsub.ChatMessageSubscription(
+            broadcaster_user_id=str(CHANNEL_ID),
+            user_id=str(self.bot_id),
+        )
+        await self.subscribe_websocket(payload=payload, as_bot=True)
+
+    async def close(self, **options: Any) -> None:
+        autonomy_runtime.unbind()
+        await super().close(**options)
+
+    async def event_ready(self) -> None:
+        logger.info("%s pronto no chat. Bot ID: %s", BOT_BRAND, self.bot_id)
+
+    def build_status_line(self) -> str:
+        return build_status_line()
+
+    async def handle_byte_prompt(self, message: Any, prompt: str) -> None:
+        author = getattr(message, "author", None)
+        author_name = str(getattr(author, "name", "viewer") or "viewer")
+        reply_fn = getattr(message, "reply", None)
+        if callable(reply_fn):
+            await handle_byte_prompt_text(
+                prompt,
+                author_name,
+                reply_fn,
+                status_line_factory=self.build_status_line,
+            )
+
+    async def event_message(self, payload: twitchio.ChatMessage) -> None:
+        message = cast(Any, payload)
+        if message.echo:
+            return
+
+        raw_text = message.text or ""
+        author = getattr(message, "author", None)
+        author_name = str(getattr(author, "name", "viewer") or "viewer")
+        byte_prompt = parse_byte_prompt(raw_text)
+        if raw_text and (not raw_text.startswith("!") or byte_prompt is not None):
+            if ENABLE_LIVE_CONTEXT_LEARNING:
+                context.remember_user_message(author_name, raw_text)
+            observability.record_chat_message(
+                author_name=author_name, source="eventsub", text=raw_text
+            )
+
+        updates: list[str] = []
+        if ENABLE_LIVE_CONTEXT_LEARNING:
+            updates = await auto_update_scene_from_message(message)
+        if updates:
+            labels = ", ".join(
+                OBSERVABILITY_TYPES.get(content_type, content_type)
+                for content_type in updates
+            )
+            logger.info("Observabilidade automatica atualizada: %s", labels)
+            observability.record_auto_scene_update(update_types=updates)
+
+        if byte_prompt is not None:
+            observability.record_byte_trigger(
+                prompt=byte_prompt, source="eventsub", author_name=author_name
+            )
+            await self.handle_byte_prompt(message, byte_prompt)
+            return
+
+        await cast(Any, self).handle_commands(message)

bot/heartbeat.py

@@ -0,0 +1,39 @@
+"""Self-heartbeat to keep HF Spaces alive.
+
+Pings the bot's own /health endpoint every HEARTBEAT_INTERVAL_SECONDS
+to prevent HF Spaces from putting the container to sleep.
+"""
+
+import http.client
+import logging
+import os
+import threading
+import time
+
+logger = logging.getLogger("ByteBot")
+
+HEARTBEAT_INTERVAL_SECONDS = 180  # 3 minutes
+
+
+def _heartbeat_loop() -> None:
+    """Background loop that pings localhost health endpoint."""
+    port = int(os.environ.get("PORT", "7860"))
+    while True:
+        time.sleep(HEARTBEAT_INTERVAL_SECONDS)
+        try:
+            conn = http.client.HTTPConnection("127.0.0.1", port, timeout=5)
+            conn.request("GET", "/health")
+            resp = conn.getresponse()
+            resp.read()
+            conn.close()
+            logger.debug("Heartbeat OK (%d)", resp.status)
+        except Exception:
+            logger.debug("Heartbeat ping failed (server may be starting)")
+
+
+def start_heartbeat() -> threading.Thread:
+    """Start the heartbeat daemon thread. Returns the thread for reference."""
+    thread = threading.Thread(target=_heartbeat_loop, name="heartbeat", daemon=True)
+    thread.start()
+    logger.info("Heartbeat started (every %ds)", HEARTBEAT_INTERVAL_SECONDS)
+    return thread

bot/hud_runtime.py

@@ -0,0 +1,52 @@
+import threading
+import time
+from collections import deque
+from typing import Any
+
+
+MAX_HUD_MESSAGES = 20
+HUD_MESSAGE_TTL_SECONDS = 600.0  # 10 minutos
+
+
+class HudRuntime:
+    """Buffer FIFO de mensagens privadas para o streamer (HUD overlay)."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._messages: deque[dict[str, Any]] = deque(maxlen=MAX_HUD_MESSAGES)
+
+    def push_message(self, text: str, source: str = "autonomy") -> dict[str, Any]:
+        if not text or not text.strip():
+            return {"ok": False, "reason": "empty_message"}
+
+        now = time.time()
+        entry: dict[str, Any] = {
+            "ts": now,
+            "text": text.strip()[:300],
+            "source": (source or "autonomy").strip().lower(),
+        }
+        with self._lock:
+            self._messages.append(entry)
+        return {"ok": True, "entry": entry}
+
+    def get_messages(self, since: float = 0.0) -> list[dict[str, Any]]:
+        now = time.time()
+        cutoff = max(since, now - HUD_MESSAGE_TTL_SECONDS)
+        with self._lock:
+            return [m for m in self._messages if float(m.get("ts", 0)) > cutoff]
+
+    def clear(self) -> None:
+        with self._lock:
+            self._messages.clear()
+
+    def get_status(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "count": len(self._messages),
+                "max": MAX_HUD_MESSAGES,
+            }
+
+
+hud_runtime = HudRuntime()
+
+__all__ = ["HudRuntime", "hud_runtime", "MAX_HUD_MESSAGES"]

bot/irc_connection.py

@@ -0,0 +1,135 @@
+import asyncio
+import ssl
+import time
+from typing import Any, TYPE_CHECKING
+
+from bot.irc_protocol import IRC_WELCOME_PATTERN
+from bot.logic import BOT_BRAND
+from bot.observability import observability
+from bot.runtime_config import logger
+from bot.twitch_tokens import TwitchAuthError, is_irc_auth_failure_line
+
+
+class IrcConnectionMixin:
+    host: str
+    port: int
+    use_tls: bool
+    bot_login: str
+    channel_logins: list[str]
+    reader: asyncio.StreamReader | None
+    writer: Any
+    token_manager: Any
+    _line_reader_running: bool
+    _line_reader_task: asyncio.Task[Any] | None
+    _pending_join_events: dict[str, asyncio.Event]
+    _pending_part_events: dict[str, asyncio.Event]
+
+    if TYPE_CHECKING:
+        async def _handle_membership_event(self, line: str) -> None: ...
+        async def _handle_notice_line(self, line: str) -> None: ...
+        async def _handle_privmsg(self, line: str) -> None: ...
+        async def _recover_authentication(self, auth_error: Exception) -> bool: ...
+        def _raise_auth_error(self, line: str) -> None: ...
+
+    async def _send_raw(self, line: str) -> None:
+        if self.writer is None:
+            raise RuntimeError("Conexao IRC nao inicializada.")
+        self.writer.write(f"{line}\r\n".encode("utf-8"))
+        await self.writer.drain()
+
+    async def _await_login_confirmation(self, timeout_seconds: float = 15.0) -> None:
+        deadline = time.monotonic() + timeout_seconds
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError("Timeout aguardando confirmacao de login IRC.")
+            if self.reader is None:
+                raise RuntimeError("Leitor IRC indisponivel durante login.")
+
+            payload = await asyncio.wait_for(self.reader.readline(), timeout=remaining)
+            if not payload:
+                raise ConnectionError("Conexao IRC encerrada durante autenticacao.")
+
+            line = payload.decode("utf-8", errors="ignore").rstrip("\r\n")
+            if not line:
+                continue
+            if line.startswith("PING"):
+                await self._send_raw(line.replace("PING", "PONG", 1))
+                continue
+            if is_irc_auth_failure_line(line):
+                raise TwitchAuthError(f"Falha de autenticacao IRC: {line}")
+            if IRC_WELCOME_PATTERN.search(line):
+                return
+
+    async def _connect(self) -> None:
+        access_token = await self.token_manager.ensure_token_for_connection()
+        ssl_context = ssl.create_default_context() if self.use_tls else None
+        self.reader, self.writer = await asyncio.open_connection(
+            self.host, self.port, ssl=ssl_context
+        )
+        await self._send_raw("CAP REQ :twitch.tv/membership twitch.tv/tags twitch.tv/commands")
+        await self._send_raw(f"PASS oauth:{access_token}")
+        await self._send_raw(f"NICK {self.bot_login}")
+        await self._await_login_confirmation()
+        for channel_login in self.channel_logins:
+            await self._send_raw(f"JOIN #{channel_login}")
+        channels_summary = ", ".join(f"#{channel}" for channel in self.channel_logins)
+        logger.info("%s conectado via IRC em %s", BOT_BRAND, channels_summary)
+
+    async def _close(self) -> None:
+        if self.writer is None:
+            return
+        try:
+            self.writer.close()
+            await self.writer.wait_closed()
+        finally:
+            self.reader = None
+            self.writer = None
+
+    async def run_forever(self) -> None:
+        while True:
+            reconnect_delay_seconds = 5
+            self._line_reader_running = False
+            self._line_reader_task = None
+            try:
+                await self._connect()
+                self._line_reader_running = True
+                self._line_reader_task = asyncio.current_task()
+                while True:
+                    if self.reader is None:
+                        raise RuntimeError("Leitor IRC indisponivel.")
+                    payload = await self.reader.readline()
+                    if not payload:
+                        raise ConnectionError("Conexao IRC encerrada.")
+                    line = payload.decode("utf-8", errors="ignore").rstrip("\r\n")
+                    if not line:
+                        continue
+                    if line.startswith("PING"):
+                        await self._send_raw(line.replace("PING", "PONG", 1))
+                        continue
+                    logger.info("IRC RAW: %s", line)
+                    if is_irc_auth_failure_line(line):
+                        self._raise_auth_error(line)
+                    if line.startswith("RECONNECT"):
+                        raise ConnectionError("Servidor IRC solicitou reconexao.")
+                    await self._handle_membership_event(line)
+                    await self._handle_notice_line(line)
+                    await self._handle_privmsg(line)
+            except asyncio.CancelledError:
+                raise
+            except TwitchAuthError as auth_error:
+                recovered = await self._recover_authentication(auth_error)
+                reconnect_delay_seconds = 2 if recovered else 20
+            except Exception as error:
+                logger.warning("Conexao IRC instavel: %s", error)
+                observability.record_error(
+                    category="irc_connection", details=str(error)
+                )
+                reconnect_delay_seconds = 5
+            finally:
+                self._line_reader_running = False
+                self._line_reader_task = None
+                self._pending_join_events.clear()
+                self._pending_part_events.clear()
+                await self._close()
+            await asyncio.sleep(reconnect_delay_seconds)

bot/irc_handlers.py

@@ -0,0 +1,181 @@
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from bot import byte_semantics
+from bot.irc_protocol import (
+    IRC_JOIN_PATTERN,
+    IRC_NOTICE_PATTERN,
+    IRC_PART_PATTERN,
+    IRC_PRIVMSG_PATTERN,
+    IrcAuthor,
+    IrcMessageAdapter,
+    is_irc_notice_delivery_block,
+    parse_irc_tags,
+)
+from bot.logic import OBSERVABILITY_TYPES, context
+from bot.observability import observability
+from bot.prompt_runtime import handle_byte_prompt_text
+from bot.runtime_config import ENABLE_LIVE_CONTEXT_LEARNING, logger
+from bot.scene_runtime import auto_update_scene_from_message
+from bot.sentiment_engine import sentiment_engine
+from bot.status_runtime import normalize_channel_login
+from bot.twitch_tokens import TwitchAuthError
+
+
+parse_byte_prompt = byte_semantics.parse_byte_prompt
+
+
+class IrcLineHandlersMixin:
+    bot_login: str
+    joined_channels: set[str]
+
+    if TYPE_CHECKING:
+        _pending_join_events: dict[str, asyncio.Event]
+        _pending_part_events: dict[str, asyncio.Event]
+        token_manager: Any
+
+        def _mark_channel_joined(self, channel_login: str) -> bool: ...
+        def _mark_channel_parted(self, channel_login: str) -> bool: ...
+        def _signal_pending_channel_action(
+            self, pending_map: dict[str, asyncio.Event], channel_login: str
+        ) -> None: ...
+        async def _handle_channel_management_prompt(
+            self, prompt: str, author: Any, source_channel: str
+        ) -> bool: ...
+        async def send_reply(self, text: str, channel_login: str | None = None) -> None: ...
+        def build_status_line(self) -> str: ...
+
+    async def _handle_membership_event(self, line: str) -> None:
+        join_match = IRC_JOIN_PATTERN.match(line)
+        if join_match:
+            author_login = (join_match.group("author") or "").strip().lower()
+            target_channel = normalize_channel_login(join_match.group("channel") or "")
+            if author_login == self.bot_login and target_channel:
+                changed = self._mark_channel_joined(target_channel)
+                self._signal_pending_channel_action(
+                    self._pending_join_events, target_channel
+                )
+                if changed:
+                    logger.info("Byte entrou no canal IRC #%s", target_channel)
+            return
+
+        part_match = IRC_PART_PATTERN.match(line)
+        if not part_match:
+            return
+        author_login = (part_match.group("author") or "").strip().lower()
+        target_channel = normalize_channel_login(part_match.group("channel") or "")
+        if author_login == self.bot_login and target_channel:
+            changed = self._mark_channel_parted(target_channel)
+            self._signal_pending_channel_action(self._pending_part_events, target_channel)
+            if changed:
+                logger.info("Byte saiu do canal IRC #%s", target_channel)
+
+    async def _handle_notice_line(self, line: str) -> None:
+        notice_match = IRC_NOTICE_PATTERN.match(line)
+        if not notice_match:
+            return
+
+        tags = parse_irc_tags(notice_match.group("tags") or "")
+        msg_id = (tags.get("msg-id") or "").strip().lower()
+        target = (notice_match.group("target") or "").strip()
+        message = (notice_match.group("message") or "").strip()
+        if target.startswith("#"):
+            target_channel = normalize_channel_login(target[1:])
+            target_label = f"#{target_channel}" if target_channel else target
+        else:
+            target_label = target or "*"
+
+        if msg_id:
+            logger.warning(
+                "IRC NOTICE target=%s msg_id=%s message=%s",
+                target_label,
+                msg_id,
+                message,
+            )
+        else:
+            logger.warning("IRC NOTICE target=%s message=%s", target_label, message)
+
+        if is_irc_notice_delivery_block(msg_id, message):
+            observability.record_error(
+                category="irc_notice",
+                details=f"{target_label} {msg_id or 'notice'}: {message}",
+            )
+
+    async def _handle_privmsg(self, line: str) -> None:
+        match = IRC_PRIVMSG_PATTERN.match(line)
+        if not match:
+            return
+
+        channel = match.group("channel").lstrip("#").lower()
+        if channel not in self.joined_channels:
+            return
+
+        author_login = (match.group("author") or "").strip().lower()
+        if not author_login or author_login == self.bot_login:
+            return
+
+        text = (match.group("message") or "").strip()
+        if not text:
+            return
+
+        tags = parse_irc_tags(match.group("tags") or "")
+        author = IrcAuthor(author_login, tags)
+        message = IrcMessageAdapter(text, author)
+        byte_prompt = parse_byte_prompt(text)
+        if not text.startswith("!") or byte_prompt is not None:
+            if ENABLE_LIVE_CONTEXT_LEARNING:
+                context.remember_user_message(author.name, text)
+            observability.record_chat_message(
+                author_name=author.name, source="irc", text=text
+            )
+            sentiment_engine.ingest_message(text)
+
+        updates: list[str] = []
+        if ENABLE_LIVE_CONTEXT_LEARNING:
+            updates = await auto_update_scene_from_message(message)
+            context.stream_vibe = sentiment_engine.get_vibe()
+        if updates:
+            labels = ", ".join(
+                OBSERVABILITY_TYPES.get(content_type, content_type)
+                for content_type in updates
+            )
+            logger.info("Observabilidade automatica atualizada: %s", labels)
+            observability.record_auto_scene_update(update_types=updates)
+
+        if byte_prompt is None:
+            return
+        observability.record_byte_trigger(
+            prompt=byte_prompt, source="irc", author_name=author.name
+        )
+        management_handled = await self._handle_channel_management_prompt(
+            byte_prompt, author, channel
+        )
+        if management_handled:
+            return
+
+        async def reply_in_source_channel(text: str) -> None:
+            await self.send_reply(text, channel_login=channel)
+
+        await handle_byte_prompt_text(
+            byte_prompt,
+            author.name,
+            reply_in_source_channel,
+            status_line_factory=self.build_status_line,
+        )
+
+    async def _recover_authentication(self, auth_error: Exception) -> bool:
+        logger.warning("Falha de autenticacao IRC: %s", auth_error)
+        observability.record_auth_failure(details=str(auth_error))
+        try:
+            await self.token_manager.force_refresh("falha de autenticacao IRC")
+            logger.info("Reconectando com token renovado automaticamente.")
+            return True
+        except Exception as refresh_error:
+            logger.error("Refresh automatico falhou: %s", refresh_error)
+            observability.record_error(
+                category="irc_refresh", details=str(refresh_error)
+            )
+            return False
+
+    def _raise_auth_error(self, line: str) -> None:
+        raise TwitchAuthError(line)

bot/irc_management.py

@@ -0,0 +1,127 @@
+from typing import TYPE_CHECKING, Any
+
+from bot.access_control import is_owner
+from bot.status_runtime import normalize_channel_login
+
+
+class IrcChannelManagementMixin:
+    owner_id: str
+    channel_logins: list[str]
+    joined_channels: set[str]
+
+    if TYPE_CHECKING:
+        async def _send_tracked_channel_reply(self, channel_login: str, text: str) -> None: ...
+        async def _join_channel(self, channel_login: str) -> bool: ...
+        async def _part_channel(self, channel_login: str) -> bool: ...
+        def _can_wait_for_channel_confirmation(self) -> bool: ...
+
+    def _parse_channel_management_prompt(self, prompt: str) -> tuple[str, str] | None:
+        normalized_prompt = " ".join((prompt or "").strip().split())
+        if not normalized_prompt:
+            return None
+
+        lowered_prompt = normalized_prompt.lower()
+        if lowered_prompt in {
+            "canais",
+            "canal",
+            "channels",
+            "channel",
+            "list channels",
+            "listar canais",
+        }:
+            return ("list", "")
+        for prefix in ("join ", "entrar ", "add "):
+            if lowered_prompt.startswith(prefix):
+                return ("join", normalized_prompt[len(prefix):].strip())
+        for prefix in ("part ", "leave ", "sair ", "remove "):
+            if lowered_prompt.startswith(prefix):
+                return ("part", normalized_prompt[len(prefix):].strip())
+        return None
+
+    async def _handle_channel_management_prompt(
+        self, prompt: str, author: Any, source_channel: str
+    ) -> bool:
+        command = self._parse_channel_management_prompt(prompt)
+        if command is None:
+            return False
+        if not is_owner(getattr(author, "id", ""), self.owner_id):
+            await self._send_tracked_channel_reply(
+                source_channel,
+                "Somente o owner pode gerenciar canais do Byte.",
+            )
+            return True
+
+        action, raw_target = command
+        if action == "list":
+            channels = ", ".join(f"#{channel}" for channel in self.channel_logins)
+            await self._send_tracked_channel_reply(source_channel, f"Canais ativos: {channels}.")
+            return True
+        if action == "join":
+            target_channel = normalize_channel_login(raw_target)
+            if not target_channel:
+                await self._send_tracked_channel_reply(source_channel, "Uso: byte join <canal>.")
+                return True
+            if target_channel in self.joined_channels:
+                await self._send_tracked_channel_reply(
+                    source_channel, f"Ja estou no canal #{target_channel}."
+                )
+                return True
+            can_wait_confirmation = self._can_wait_for_channel_confirmation()
+            joined = await self._join_channel(target_channel)
+            if joined and can_wait_confirmation:
+                message = (
+                    f"Canal adicionado: #{target_channel}. Byte responde onde for acionado."
+                )
+            elif joined:
+                message = (
+                    f"Solicitacao enviada para entrar em #{target_channel}. "
+                    "Aguarde confirmacao do IRC."
+                )
+            else:
+                message = f"Nao consegui entrar em #{target_channel}."
+            await self._send_tracked_channel_reply(source_channel, message)
+            return True
+        if action != "part":
+            return False
+
+        target_channel = normalize_channel_login(raw_target or source_channel)
+        if not target_channel:
+            await self._send_tracked_channel_reply(source_channel, "Uso: byte part <canal>.")
+            return True
+        if target_channel not in self.joined_channels:
+            await self._send_tracked_channel_reply(
+                source_channel, f"Nao estou no canal #{target_channel}."
+            )
+            return True
+        if len(self.channel_logins) <= 1:
+            await self._send_tracked_channel_reply(
+                source_channel,
+                "Nao posso sair do ultimo canal ativo. Entre em outro canal primeiro com 'byte join <canal>'.",
+            )
+            return True
+        if target_channel == source_channel:
+            await self._send_tracked_channel_reply(
+                source_channel,
+                f"Solicitacao recebida: tentando sair de #{target_channel}.",
+            )
+            parted = await self._part_channel(target_channel)
+            if not parted:
+                await self._send_tracked_channel_reply(
+                    source_channel,
+                    f"Nao consegui sair de #{target_channel}.",
+                )
+            return True
+
+        can_wait_confirmation = self._can_wait_for_channel_confirmation()
+        parted = await self._part_channel(target_channel)
+        if parted and can_wait_confirmation:
+            message = f"Canal removido: #{target_channel}."
+        elif parted:
+            message = (
+                f"Solicitacao enviada para sair de #{target_channel}. "
+                "Aguarde confirmacao do IRC."
+            )
+        else:
+            message = f"Nao consegui sair de #{target_channel}."
+        await self._send_tracked_channel_reply(source_channel, message)
+        return True

bot/irc_protocol.py

@@ -0,0 +1,90 @@
+import re
+
+IRC_PRIVMSG_PATTERN = re.compile(
+    r"^(?:@(?P<tags>[^ ]+) )?:(?P<author>[^!]+)![^ ]+ PRIVMSG #(?P<channel>[^ ]+) :(?P<message>.*)$"
+)
+IRC_NOTICE_PATTERN = re.compile(
+    r"^(?:@(?P<tags>[^ ]+) )?:[^ ]+ NOTICE (?P<target>[^ ]+) :(?P<message>.*)$",
+    re.IGNORECASE,
+)
+IRC_JOIN_PATTERN = re.compile(
+    r"^(?:@(?P<tags>[^ ]+) )?:(?P<author>[^!]+)![^ ]+ JOIN #(?P<channel>[^ ]+)$",
+    re.IGNORECASE,
+)
+IRC_PART_PATTERN = re.compile(
+    r"^(?:@(?P<tags>[^ ]+) )?:(?P<author>[^!]+)![^ ]+ PART #(?P<channel>[^ ]+)(?: :(?P<reason>.*))?$",
+    re.IGNORECASE,
+)
+IRC_WELCOME_PATTERN = re.compile(r"^:[^ ]+\s001\s", re.IGNORECASE)
+IRC_NOTICE_DELIVERY_BLOCK_IDS = {
+    "msg_bad_characters",
+    "msg_banned",
+    "msg_channel_blocked",
+    "msg_channel_suspended",
+    "msg_duplicate",
+    "msg_emoteonly",
+    "msg_followersonly",
+    "msg_followersonly_followed",
+    "msg_r9k",
+    "msg_requires_verified_phone_number",
+    "msg_slowmode",
+    "msg_subsonly",
+    "msg_suspended",
+    "msg_timedout",
+}
+IRC_NOTICE_DELIVERY_BLOCK_HINTS = (
+    "banned",
+    "followers-only",
+    "followers only",
+    "phone number must be verified",
+    "requires a verified phone number",
+    "room is no longer available",
+    "subscribers-only",
+    "subscribers only",
+    "timed out",
+    "you are permanently banned",
+)
+
+
+class IrcAuthor:
+    def __init__(self, login: str, tags: dict[str, str]) -> None:
+        self.login = login
+        self.name = tags.get("display-name") or login
+        self.id = tags.get("user-id", "")
+        is_mod = tags.get("mod") == "1" or "moderator/" in tags.get("badges", "")
+        self.is_mod = is_mod
+        self.is_moderator = is_mod
+
+
+class IrcMessageAdapter:
+    def __init__(self, text: str, author: IrcAuthor) -> None:
+        self.text = text
+        self.author = author
+        self.echo = False
+
+
+def parse_irc_tags(raw_tags: str) -> dict[str, str]:
+    if not raw_tags:
+        return {}
+    parsed: dict[str, str] = {}
+    for item in raw_tags.split(";"):
+        if "=" in item:
+            key, value = item.split("=", maxsplit=1)
+        else:
+            key, value = item, ""
+        parsed[key] = value.replace(r"\s", " ").replace(r"\:", ";").replace(r"\\", "\\")
+    return parsed
+
+
+def flatten_chat_text(text: str) -> str:
+    lines = [line.strip() for line in (text or "").splitlines() if line.strip()]
+    return " | ".join(lines)
+
+
+def is_irc_notice_delivery_block(msg_id: str, message: str) -> bool:
+    normalized_id = (msg_id or "").strip().lower()
+    if normalized_id in IRC_NOTICE_DELIVERY_BLOCK_IDS:
+        return True
+
+    lowered_message = (message or "").strip().lower()
+    return any(marker in lowered_message for marker in IRC_NOTICE_DELIVERY_BLOCK_HINTS)

bot/irc_runtime.py

@@ -0,0 +1,74 @@
+import asyncio
+from typing import Any
+
+from bot.irc_connection import IrcConnectionMixin
+from bot.irc_handlers import IrcLineHandlersMixin
+from bot.irc_management import IrcChannelManagementMixin
+from bot.irc_state import IrcChannelStateMixin
+from bot.observability import observability
+from bot.runtime_config import (
+    OWNER_ID,
+    TWITCH_TOKEN_REFRESH_TIMEOUT_SECONDS,
+    TWITCH_TOKEN_VALIDATE_TIMEOUT_SECONDS,
+    logger,
+)
+from bot.status_runtime import normalize_channel_login
+from bot.twitch_tokens import TwitchTokenManager, TwitchTokenManagerSettings
+
+
+class IrcByteBot(
+    IrcChannelManagementMixin,
+    IrcChannelStateMixin,
+    IrcLineHandlersMixin,
+    IrcConnectionMixin,
+):
+    def __init__(
+        self,
+        *,
+        host: str,
+        port: int,
+        use_tls: bool,
+        bot_login: str,
+        channel_login: str | None = None,
+        channel_logins: list[str] | None = None,
+        user_token: str = "",
+        token_manager: TwitchTokenManager | None = None,
+    ) -> None:
+        provided_channels = list(channel_logins or [])
+        if channel_login:
+            provided_channels.append(channel_login)
+
+        resolved_channels: list[str] = []
+        seen_channels: set[str] = set()
+        for candidate in provided_channels:
+            normalized = normalize_channel_login(candidate)
+            if not normalized or normalized in seen_channels:
+                continue
+            seen_channels.add(normalized)
+            resolved_channels.append(normalized)
+        if not resolved_channels:
+            raise RuntimeError("Defina ao menos 1 canal valido para o modo IRC.")
+
+        self.host = host
+        self.port = port
+        self.use_tls = use_tls
+        self.bot_login = bot_login.lower()
+        self.owner_id = OWNER_ID
+        self.channel_logins = resolved_channels
+        self.joined_channels = set(resolved_channels)
+        self.primary_channel_login = resolved_channels[0]
+        self.token_manager = token_manager or TwitchTokenManager(
+            access_token=user_token,
+            settings=TwitchTokenManagerSettings(
+                validate_timeout_seconds=TWITCH_TOKEN_VALIDATE_TIMEOUT_SECONDS,
+                refresh_timeout_seconds=TWITCH_TOKEN_REFRESH_TIMEOUT_SECONDS,
+            ),
+            observability=observability,
+            logger=logger,
+        )
+        self.reader: asyncio.StreamReader | None = None
+        self.writer: Any = None
+        self._line_reader_running = False
+        self._line_reader_task: asyncio.Task[Any] | None = None
+        self._pending_join_events: dict[str, asyncio.Event] = {}
+        self._pending_part_events: dict[str, asyncio.Event] = {}

bot/irc_state.py

@@ -0,0 +1,264 @@
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from bot.irc_protocol import flatten_chat_text
+from bot.logic import context
+from bot.observability import observability
+from bot.prompt_runtime import format_chat_reply
+from bot.runtime_config import TWITCH_IRC_CHANNEL_ACTION_TIMEOUT_SECONDS, logger
+from bot.status_runtime import build_status_line, normalize_channel_login
+
+
+class IrcChannelStateMixin:
+    channel_logins: list[str]
+    joined_channels: set[str]
+    primary_channel_login: str
+    reader: asyncio.StreamReader | None
+    _line_reader_running: bool
+    _line_reader_task: asyncio.Task[Any] | None
+    _pending_join_events: dict[str, asyncio.Event]
+    _pending_part_events: dict[str, asyncio.Event]
+
+    if TYPE_CHECKING:
+        async def _send_raw(self, line: str) -> None: ...
+
+    def build_status_line(self) -> str:
+        return build_status_line(channel_logins=self.channel_logins)
+
+    @property
+    def channel_action_timeout_seconds(self) -> float:
+        return max(0.1, float(TWITCH_IRC_CHANNEL_ACTION_TIMEOUT_SECONDS))
+
+    def _prepare_reply_text(self, text: str) -> str:
+        return flatten_chat_text(format_chat_reply(text))
+
+    async def send_reply(self, text: str, channel_login: str | None = None) -> None:
+        target_channel = normalize_channel_login(
+            channel_login or self.primary_channel_login
+        )
+        if not target_channel:
+            target_channel = self.primary_channel_login
+        if target_channel not in self.joined_channels:
+            target_channel = self.primary_channel_login
+
+        safe_text = self._prepare_reply_text(text)
+        if not safe_text:
+            return
+        await self._send_raw(f"PRIVMSG #{target_channel} :{safe_text}")
+
+    async def _send_tracked_channel_reply(self, channel_login: str, text: str) -> None:
+        target_channel = normalize_channel_login(channel_login)
+        if not target_channel or target_channel not in self.joined_channels:
+            return
+        safe_text = self._prepare_reply_text(text)
+        if not safe_text:
+            return
+        context.remember_bot_reply(safe_text)
+        observability.record_reply(text=safe_text)
+        await self._send_raw(f"PRIVMSG #{target_channel} :{safe_text}")
+
+    def _mark_channel_joined(self, channel_login: str) -> bool:
+        target_channel = normalize_channel_login(channel_login)
+        if not target_channel:
+            return False
+
+        changed = False
+        if target_channel not in self.joined_channels:
+            self.joined_channels.add(target_channel)
+            changed = True
+        if target_channel not in self.channel_logins:
+            self.channel_logins.append(target_channel)
+            changed = True
+        if (
+            not self.primary_channel_login
+            or self.primary_channel_login not in self.joined_channels
+        ):
+            self.primary_channel_login = self.channel_logins[0]
+            changed = True
+        return changed
+
+    def _mark_channel_parted(self, channel_login: str) -> bool:
+        target_channel = normalize_channel_login(channel_login)
+        if not target_channel:
+            return False
+
+        changed = False
+        if target_channel in self.joined_channels:
+            self.joined_channels.remove(target_channel)
+            changed = True
+        filtered_channels = [
+            channel for channel in self.channel_logins if channel != target_channel
+        ]
+        if len(filtered_channels) != len(self.channel_logins):
+            self.channel_logins = filtered_channels
+            changed = True
+        if not self.channel_logins and self.joined_channels:
+            self.channel_logins = sorted(self.joined_channels)
+            changed = True
+        if self.primary_channel_login == target_channel:
+            self.primary_channel_login = self.channel_logins[0] if self.channel_logins else ""
+            changed = True
+        elif (
+            self.primary_channel_login
+            and self.primary_channel_login not in self.joined_channels
+        ):
+            self.primary_channel_login = self.channel_logins[0] if self.channel_logins else ""
+            changed = True
+        elif not self.primary_channel_login and self.channel_logins:
+            self.primary_channel_login = self.channel_logins[0]
+            changed = True
+        return changed
+
+    def _signal_pending_channel_action(
+        self, pending_map: dict[str, asyncio.Event], channel_login: str
+    ) -> None:
+        event = pending_map.get(channel_login)
+        if event is not None and not event.is_set():
+            event.set()
+
+    def _can_wait_for_channel_confirmation(self) -> bool:
+        if self.reader is None or not self._line_reader_running:
+            return False
+        current_task = asyncio.current_task()
+        if self._line_reader_task is not None and current_task is self._line_reader_task:
+            return False
+        return True
+
+    async def _wait_for_channel_confirmation(
+        self,
+        *,
+        channel_login: str,
+        action: str,
+        pending_map: dict[str, asyncio.Event],
+    ) -> bool:
+        event = pending_map.get(channel_login)
+        if event is None:
+            return False
+
+        try:
+            await asyncio.wait_for(event.wait(), timeout=self.channel_action_timeout_seconds)
+            return True
+        except TimeoutError:
+            logger.warning(
+                "Timeout aguardando confirmacao de %s no IRC para #%s.",
+                action,
+                channel_login,
+            )
+            observability.record_error(
+                category="irc_channel_control",
+                details=f"timeout aguardando {action} #{channel_login}",
+            )
+            return False
+        finally:
+            current_event = pending_map.get(channel_login)
+            if current_event is event:
+                pending_map.pop(channel_login, None)
+
+    async def _join_channel(self, channel_login: str) -> bool:
+        target_channel = normalize_channel_login(channel_login)
+        if not target_channel:
+            return False
+        if target_channel in self.joined_channels:
+            return False
+
+        should_wait_confirmation = self._can_wait_for_channel_confirmation()
+        if should_wait_confirmation and target_channel not in self._pending_join_events:
+            self._pending_join_events[target_channel] = asyncio.Event()
+        
+        logger.info("IRC SEND: JOIN #%s", target_channel)
+        await self._send_raw(f"JOIN #{target_channel}")
+
+        if should_wait_confirmation:
+            return await self._wait_for_channel_confirmation(
+                channel_login=target_channel,
+                action="JOIN",
+                pending_map=self._pending_join_events,
+            )
+
+        logger.info(
+            "JOIN enviado para #%s sem espera de confirmacao imediata.",
+            target_channel,
+        )
+        return True
+
+    async def _part_channel(self, channel_login: str) -> bool:
+        target_channel = normalize_channel_login(channel_login)
+        if not target_channel:
+            return False
+        if target_channel not in self.joined_channels:
+            return False
+        if len(self.channel_logins) <= 1:
+            return False
+
+        should_wait_confirmation = self._can_wait_for_channel_confirmation()
+        if should_wait_confirmation and target_channel not in self._pending_part_events:
+            self._pending_part_events[target_channel] = asyncio.Event()
+        await self._send_raw(f"PART #{target_channel}")
+
+        if should_wait_confirmation:
+            return await self._wait_for_channel_confirmation(
+                channel_login=target_channel,
+                action="PART",
+                pending_map=self._pending_part_events,
+            )
+
+        logger.info(
+            "PART enviado para #%s sem espera de confirmacao imediata.",
+            target_channel,
+        )
+        return True
+
+    async def admin_list_channels(self) -> list[str]:
+        return list(self.channel_logins)
+
+    async def admin_join_channel(self, channel_login: str) -> tuple[bool, str, list[str]]:
+        target_channel = normalize_channel_login(channel_login)
+        if not target_channel:
+            return (
+                False,
+                "Invalid channel login. Use Twitch login format (no #).",
+                list(self.channel_logins),
+            )
+        if target_channel in self.joined_channels:
+            return (
+                True,
+                f"Already connected to #{target_channel}.",
+                list(self.channel_logins),
+            )
+        
+        # Optimistic Update: Mark as joined in memory immediately for instant UX
+        self._mark_channel_joined(target_channel)
+        
+        # Trigger the actual IRC join (fire and forget via background logic)
+        await self._join_channel(target_channel)
+        
+        return (True, f"Joined #{target_channel}.", list(self.channel_logins))
+
+    async def admin_part_channel(self, channel_login: str) -> tuple[bool, str, list[str]]:
+        target_channel = normalize_channel_login(channel_login)
+        if not target_channel:
+            return (
+                False,
+                "Invalid channel login. Use Twitch login format (no #).",
+                list(self.channel_logins),
+            )
+        if target_channel not in self.joined_channels:
+            return (
+                False,
+                f"Channel not connected: #{target_channel}.",
+                list(self.channel_logins),
+            )
+        if len(self.channel_logins) <= 1:
+            return (
+                False,
+                "Cannot leave the last active channel. Join another one first.",
+                list(self.channel_logins),
+            )
+        
+        # Optimistic Update: Remove from memory immediately
+        self._mark_channel_parted(target_channel)
+        
+        # Trigger actual IRC part
+        await self._part_channel(target_channel)
+        
+        return (True, f"Left #{target_channel}.", list(self.channel_logins))

bot/logic.py

@@ -0,0 +1,52 @@
+from bot.logic_constants import (
+    BOT_BRAND,
+    EMPTY_RESPONSE_FALLBACK,
+    MAX_REPLY_LENGTH,
+    MAX_REPLY_LINES,
+    MODEL_RATE_LIMIT_BACKOFF_SECONDS,
+    MODEL_RATE_LIMIT_MAX_RETRIES,
+    OBSERVABILITY_TYPES,
+    UNSTABLE_CONNECTION_FALLBACK,
+)
+from bot.logic_context import (
+    StreamContext,
+    build_dynamic_prompt,
+    build_system_instruction,
+    context,
+    enforce_reply_limits,
+    get_server_clock_snapshot,
+    normalize_memory_excerpt,
+)
+from bot.logic_grounding import (
+    GroundingMetadata,
+    empty_grounding_metadata,
+    extract_grounding_metadata,
+    extract_response_text,
+    has_grounding_signal,
+)
+from bot.logic_inference import agent_inference, is_rate_limited_inference_error
+
+__all__ = [
+    "BOT_BRAND",
+    "EMPTY_RESPONSE_FALLBACK",
+    "MAX_REPLY_LENGTH",
+    "MAX_REPLY_LINES",
+    "MODEL_RATE_LIMIT_BACKOFF_SECONDS",
+    "MODEL_RATE_LIMIT_MAX_RETRIES",
+    "OBSERVABILITY_TYPES",
+    "UNSTABLE_CONNECTION_FALLBACK",
+    "StreamContext",
+    "build_dynamic_prompt",
+    "build_system_instruction",
+    "context",
+    "enforce_reply_limits",
+    "get_server_clock_snapshot",
+    "normalize_memory_excerpt",
+    "GroundingMetadata",
+    "empty_grounding_metadata",
+    "extract_grounding_metadata",
+    "extract_response_text",
+    "has_grounding_signal",
+    "agent_inference",
+    "is_rate_limited_inference_error",
+]

bot/logic_constants.py

@@ -0,0 +1,41 @@
+import os
+
+BOT_BRAND = "Byte"
+MAX_REPLY_LINES = 4
+MAX_REPLY_LENGTH = 460
+MAX_RECENT_CHAT_ENTRIES = 12
+MAX_RECENT_CHAT_PREVIEW_CHARS = 140
+MAX_RECENT_CHAT_PROMPT_ENTRIES = 5
+MAX_GROUNDING_QUERIES = 3
+MAX_GROUNDING_URLS = 3
+
+OBSERVABILITY_TYPES = {
+    "game": "Jogo",
+    "movie": "Filme",
+    "series": "Serie",
+    "youtube": "Video YouTube",
+    "x": "Post X",
+    "topic": "Tema",
+}
+
+DEFAULT_STYLE_PROFILE = "Tom generalista, claro e natural em PT-BR, sem giria gamer forcada."
+
+SYSTEM_INSTRUCTION_TEMPLATE = (
+    "Voce e Byte, chatbot de uma live na Twitch. "
+    "Responda de forma objetiva para os assuntos ativos da live, incluindo jogos, filmes, series, videos do YouTube, posts do X e temas gerais. "
+    "Regras: 1) no maximo 4 linhas. 2) cada linha deve trazer informacao nova, concreta e relevante. "
+    "3) sem markdown. 4) nao use linguagem ofensiva nem invente fatos sem sinalizar incerteza. "
+    "5) se faltar contexto essencial, faca uma pergunta curta. "
+    "6) para assunto atual, priorize informacao recente e verificavel. "
+    "7) responda primeiro a pergunta principal, sem rodeio."
+)
+MODEL_NAME = "gemini-3-flash-preview"
+MODEL_MAX_OUTPUT_TOKENS = 320
+MODEL_TEMPERATURE = 0.15
+MODEL_INPUT_COST_PER_1M_USD = max(0.0, float(os.environ.get("MODEL_INPUT_COST_PER_1M_USD", "0.10")))
+MODEL_OUTPUT_COST_PER_1M_USD = max(0.0, float(os.environ.get("MODEL_OUTPUT_COST_PER_1M_USD", "0.40")))
+MODEL_RATE_LIMIT_MAX_RETRIES = max(0, int(os.environ.get("MODEL_RATE_LIMIT_MAX_RETRIES", "1")))
+MODEL_RATE_LIMIT_BACKOFF_SECONDS = max(0.0, float(os.environ.get("MODEL_RATE_LIMIT_BACKOFF_SECONDS", "0.8")))
+MODEL_INFERENCE_TIMEOUT_SECONDS = max(2.0, float(os.environ.get("MODEL_INFERENCE_TIMEOUT_SECONDS", "12.0")))
+EMPTY_RESPONSE_FALLBACK = "Nao consegui consolidar a resposta agora. Tente reformular em uma frase."
+UNSTABLE_CONNECTION_FALLBACK = "Conexao com o modelo instavel. Tente novamente em instantes."

bot/logic_context.py

@@ -0,0 +1,198 @@
+import time
+from datetime import datetime, timezone
+from typing import Dict
+
+from bot.logic_constants import (
+    BOT_BRAND,
+    DEFAULT_STYLE_PROFILE,
+    MAX_RECENT_CHAT_ENTRIES,
+    MAX_RECENT_CHAT_PREVIEW_CHARS,
+    MAX_RECENT_CHAT_PROMPT_ENTRIES,
+    MAX_REPLY_LENGTH,
+    MAX_REPLY_LINES,
+    OBSERVABILITY_TYPES,
+    SYSTEM_INSTRUCTION_TEMPLATE,
+)
+
+
+def normalize_memory_excerpt(text: str, max_length: int = MAX_RECENT_CHAT_PREVIEW_CHARS) -> str:
+    compact = " ".join((text or "").split())
+    if not compact:
+        return ""
+    if len(compact) <= max_length:
+        return compact
+
+    head = compact[: max_length - 3].rstrip()
+    last_space = head.rfind(" ")
+    if last_space >= int(max_length * 0.5):
+        head = head[:last_space]
+    return head.rstrip(" ,;:") + "..."
+
+
+class StreamContext:
+    def __init__(self):
+        self.current_game = "N/A"
+        self.stream_vibe = "Conversa"
+        self.last_event = "Bot Online"
+        self.style_profile = DEFAULT_STYLE_PROFILE
+        self.live_observability: Dict[str, str] = {
+            "game": "",
+            "movie": "",
+            "series": "",
+            "youtube": "",
+            "x": "",
+            "topic": "",
+        }
+        self.recent_chat_entries: list[str] = []
+        self.last_byte_reply = ""
+        self.start_time = time.time()
+
+    def get_uptime_minutes(self) -> int:
+        return int((time.time() - self.start_time) / 60)
+
+    def update_content(self, content_type: str, description: str) -> bool:
+        normalized_type = content_type.strip().lower()
+        cleaned_description = description.strip()
+        if normalized_type not in OBSERVABILITY_TYPES or not cleaned_description:
+            return False
+
+        self.live_observability[normalized_type] = cleaned_description
+        if normalized_type == "game":
+            self.current_game = cleaned_description
+        self.last_event = f"Contexto atualizado: {OBSERVABILITY_TYPES[normalized_type]}"
+        return True
+
+    def clear_content(self, content_type: str) -> bool:
+        normalized_type = content_type.strip().lower()
+        if normalized_type not in OBSERVABILITY_TYPES:
+            return False
+
+        self.live_observability[normalized_type] = ""
+        if normalized_type == "game":
+            self.current_game = "N/A"
+        self.last_event = f"Contexto removido: {OBSERVABILITY_TYPES[normalized_type]}"
+        return True
+
+    def list_supported_content_types(self) -> str:
+        return ", ".join(OBSERVABILITY_TYPES.keys())
+
+    def format_observability(self) -> str:
+        entries = []
+        for content_type, label in OBSERVABILITY_TYPES.items():
+            value = self.live_observability.get(content_type, "").strip()
+            if value:
+                entries.append(f"{label}: {value}")
+        return " | ".join(entries) if entries else "Sem conteudo registrado."
+
+    def status_snapshot(self) -> str:
+        active_count = sum(1 for value in self.live_observability.values() if value)
+        return f"Vibe: {self.stream_vibe} | Contextos ativos: {active_count}"
+
+    def remember_user_message(self, author_name: str, message_text: str) -> None:
+        safe_author = normalize_memory_excerpt(author_name or "viewer", max_length=32)
+        safe_message = normalize_memory_excerpt(message_text)
+        if not safe_message:
+            return
+        self.recent_chat_entries.append(f"{safe_author}: {safe_message}")
+        self.recent_chat_entries = self.recent_chat_entries[-MAX_RECENT_CHAT_ENTRIES:]
+
+    def remember_bot_reply(self, reply_text: str) -> None:
+        safe_reply = normalize_memory_excerpt(reply_text, max_length=180)
+        if not safe_reply:
+            return
+        self.last_byte_reply = safe_reply
+        self.recent_chat_entries.append(f"{BOT_BRAND}: {safe_reply}")
+        self.recent_chat_entries = self.recent_chat_entries[-MAX_RECENT_CHAT_ENTRIES:]
+
+    def format_recent_chat(self, limit: int = MAX_RECENT_CHAT_PROMPT_ENTRIES) -> str:
+        if not self.recent_chat_entries:
+            return "Sem historico recente."
+        selected = self.recent_chat_entries[-max(1, limit):]
+        return " || ".join(selected)
+
+
+context = StreamContext()
+
+
+def build_system_instruction(ctx: StreamContext) -> str:
+    return f"{SYSTEM_INSTRUCTION_TEMPLATE} Estilo ativo: {ctx.style_profile}"
+
+
+def get_server_clock_snapshot() -> tuple[str, int]:
+    now_utc = datetime.now(timezone.utc)
+    now_utc_iso = now_utc.isoformat(timespec="seconds").replace("+00:00", "Z")
+    return now_utc_iso, int(now_utc.timestamp())
+
+
+def build_dynamic_prompt(
+    user_msg: str,
+    author_name: str,
+    ctx: StreamContext,
+    *,
+    include_live_context: bool = True,
+) -> str:
+    server_utc_iso, server_epoch = get_server_clock_snapshot()
+    if not include_live_context:
+        return (
+            "Modo contexto estatico ativo. Ignore historico da live e responda somente ao pedido atual.\n"
+            f"Relogio servidor UTC: {server_utc_iso} | Epoch: {server_epoch}\n"
+            f"Usuario {author_name}: {user_msg}"
+        )
+
+    uptime = ctx.get_uptime_minutes()
+    observability = ctx.format_observability()
+    recent_chat = ctx.format_recent_chat()
+    last_reply = ctx.last_byte_reply or "N/A"
+    return (
+        "Contexto Atual da Live: "
+        f"[Vibe: {ctx.stream_vibe} | Uptime: {uptime}min | "
+        f"Observabilidade: {observability} | Ultimo evento: {ctx.last_event} | "
+        f"Relogio servidor UTC: {server_utc_iso} | Epoch: {server_epoch}]\n"
+        "Use o relogio do servidor como referencia para termos temporais (hoje/agora/nesta semana).\n"
+        f"Historico recente: {recent_chat}\n"
+        f"Ultima resposta do {BOT_BRAND}: {last_reply}\n"
+        f"Usuario {author_name}: {user_msg}"
+    )
+
+
+def enforce_reply_limits(text: str, max_lines: int = MAX_REPLY_LINES, max_length: int = MAX_REPLY_LENGTH) -> str:
+    cleaned = (text or "").replace("\r\n", "\n").replace("\r", "\n").strip()
+    if not cleaned:
+        return ""
+
+    normalized_lines = []
+    for raw_line in cleaned.split("\n"):
+        line = " ".join(raw_line.split())
+        if line:
+            normalized_lines.append(line)
+
+    if not normalized_lines:
+        normalized_lines = [" ".join(cleaned.split())]
+
+    limited_lines = normalized_lines[:max_lines]
+    result = "\n".join(limited_lines).strip()
+    if len(result) <= max_length:
+        return result
+
+    def close_sentence(fragment: str) -> str:
+        cleaned_fragment = fragment.strip().rstrip(" ,;:")
+        if not cleaned_fragment:
+            return ""
+        if cleaned_fragment[-1] in ".!?":
+            return cleaned_fragment
+        if len(cleaned_fragment) >= max_length:
+            cleaned_fragment = cleaned_fragment[: max_length - 1].rstrip(" ,;:")
+        if not cleaned_fragment:
+            return ""
+        return cleaned_fragment + "."
+
+    head = result[:max_length].rstrip()
+    punctuation_positions = [head.rfind(symbol) for symbol in (".", "!", "?")]
+    best_punctuation = max(punctuation_positions)
+    if best_punctuation >= int(max_length * 0.35):
+        return head[: best_punctuation + 1].strip()
+
+    last_space = head.rfind(" ")
+    if last_space >= int(max_length * 0.55):
+        return close_sentence(head[:last_space])
+    return close_sentence(head)

bot/logic_grounding.py

@@ -0,0 +1,110 @@
+from typing import Any, Mapping, TypedDict
+
+from bot.logic_constants import MAX_GROUNDING_QUERIES, MAX_GROUNDING_URLS
+
+
+class GroundingMetadata(TypedDict):
+    enabled: bool
+    has_grounding_signal: bool
+    query_count: int
+    source_count: int
+    chunk_count: int
+    web_search_queries: list[str]
+    source_urls: list[str]
+
+
+def empty_grounding_metadata(enabled: bool = False) -> GroundingMetadata:
+    return {
+        "enabled": bool(enabled),
+        "has_grounding_signal": False,
+        "query_count": 0,
+        "source_count": 0,
+        "chunk_count": 0,
+        "web_search_queries": [],
+        "source_urls": [],
+    }
+
+
+def _read_field(source: Any, key: str, default: Any = None) -> Any:
+    if isinstance(source, dict):
+        return source.get(key, default)
+    return getattr(source, key, default)
+
+
+def _append_unique_text(values: list[str], raw_value: Any, max_items: int) -> None:
+    normalized = " ".join(str(raw_value or "").split()).strip()
+    if not normalized:
+        return
+    if normalized in values:
+        return
+    values.append(normalized)
+    if len(values) > max_items:
+        del values[max_items:]
+
+
+def extract_grounding_metadata(response: Any, use_grounding: bool) -> GroundingMetadata:
+    metadata = empty_grounding_metadata(enabled=use_grounding)
+    candidates = _read_field(response, "candidates", []) or []
+    if not candidates:
+        return metadata
+
+    web_search_queries: list[str] = []
+    source_urls: list[str] = []
+    chunk_count = 0
+
+    for candidate in candidates:
+        grounding = _read_field(candidate, "grounding_metadata")
+        if grounding is not None:
+            for query in _read_field(grounding, "web_search_queries", []) or []:
+                _append_unique_text(web_search_queries, query, max_items=MAX_GROUNDING_QUERIES)
+
+            grounding_chunks = _read_field(grounding, "grounding_chunks", []) or []
+            chunk_count += len(grounding_chunks)
+            for chunk in grounding_chunks:
+                web_chunk = _read_field(chunk, "web")
+                uri = _read_field(web_chunk, "uri", "") if web_chunk is not None else ""
+                _append_unique_text(source_urls, uri, max_items=MAX_GROUNDING_URLS)
+
+        citation_metadata = _read_field(candidate, "citation_metadata")
+        citations = _read_field(citation_metadata, "citations", []) if citation_metadata is not None else []
+        for citation in citations or []:
+            _append_unique_text(source_urls, _read_field(citation, "uri", ""), max_items=MAX_GROUNDING_URLS)
+
+    metadata["web_search_queries"] = web_search_queries
+    metadata["source_urls"] = source_urls
+    metadata["chunk_count"] = max(0, int(chunk_count))
+    metadata["query_count"] = len(web_search_queries)
+    metadata["source_count"] = len(source_urls)
+    metadata["has_grounding_signal"] = bool(web_search_queries or source_urls or chunk_count > 0)
+    return metadata
+
+
+def has_grounding_signal(metadata: Mapping[str, Any] | None) -> bool:
+    if not metadata:
+        return False
+    if bool(metadata.get("has_grounding_signal")):
+        return True
+    return bool(
+        metadata.get("web_search_queries")
+        or metadata.get("source_urls")
+        or int(metadata.get("chunk_count", 0) or 0) > 0
+    )
+
+
+def extract_response_text(response: Any) -> str:
+    direct_text = getattr(response, "text", None)
+    if isinstance(direct_text, str) and direct_text.strip():
+        return direct_text.strip()
+
+    candidates = getattr(response, "candidates", None) or []
+    for candidate in candidates:
+        content = getattr(candidate, "content", None)
+        parts = getattr(content, "parts", None) or []
+        text_parts = []
+        for part in parts:
+            part_text = getattr(part, "text", None)
+            if isinstance(part_text, str) and part_text.strip():
+                text_parts.append(part_text.strip())
+        if text_parts:
+            return "\n".join(text_parts).strip()
+    return ""

bot/logic_inference.py

@@ -0,0 +1,225 @@
+import asyncio
+import logging
+from typing import Any, Literal, overload
+
+from bot.logic_constants import (
+    EMPTY_RESPONSE_FALLBACK,
+    MAX_REPLY_LENGTH,
+    MAX_REPLY_LINES,
+    MODEL_RATE_LIMIT_BACKOFF_SECONDS,
+    MODEL_RATE_LIMIT_MAX_RETRIES,
+    MODEL_TEMPERATURE,
+    UNSTABLE_CONNECTION_FALLBACK,
+)
+from bot.logic_context import build_dynamic_prompt, build_system_instruction, enforce_reply_limits
+from bot.logic_grounding import (
+    GroundingMetadata,
+    empty_grounding_metadata,
+)
+from bot.observability import observability
+from bot.web_search import format_search_context, search_web
+
+logger = logging.getLogger("ByteBot")
+
+
+def is_rate_limited_inference_error(error: Exception) -> bool:
+    message = str(error).lower()
+    return "429" in message or "rate limit" in message
+
+
+def is_timeout_inference_error(error: Exception) -> bool:
+    if isinstance(error, asyncio.TimeoutError):
+        return True
+    message = str(error).lower()
+    return "timed out" in message or "timeout" in message
+
+
+def _extract_usage(response: Any) -> tuple[int, int]:
+    usage = getattr(response, "usage", None)
+    if usage is None:
+        return 0, 0
+    return getattr(usage, "prompt_tokens", 0), getattr(usage, "completion_tokens", 0)
+
+
+def _select_model(enable_grounding: bool, is_serious: bool) -> str:
+    """Select the optimal Nebius model for the request type."""
+    from bot.runtime_config import NEBIUS_MODEL_DEFAULT, NEBIUS_MODEL_REASONING, NEBIUS_MODEL_SEARCH
+
+    if enable_grounding:
+        return NEBIUS_MODEL_SEARCH
+    if is_serious:
+        return NEBIUS_MODEL_REASONING
+    return NEBIUS_MODEL_DEFAULT
+
+
+def _extract_search_query(user_msg: str) -> str:
+    """Extract a clean search query from the user message.
+
+    Strips LLM instruction noise, keeps the factual question core.
+    """
+    clean = (user_msg or "").strip()
+    # If the message has embedded instructions (from build_llm_enhanced_prompt),
+    # use only the first line which is the actual user question.
+    if "\n" in clean:
+        clean = clean.split("\n")[0].strip()
+    # Cap length for DDG
+    if len(clean) > 200:
+        clean = clean[:200].rsplit(" ", 1)[0]
+    return clean
+
+
+def _build_grounding_metadata(
+    results: list[Any],
+    enabled: bool,
+) -> GroundingMetadata:
+    """Build real grounding metadata from DDG search results."""
+    if not results:
+        return empty_grounding_metadata(enabled=enabled)
+    return {
+        "enabled": enabled,
+        "has_grounding_signal": True,
+        "query_count": 1,
+        "source_count": len(results),
+        "chunk_count": len(results),
+        "web_search_queries": [results[0].snippet[:80] if results else ""],
+        "source_urls": [r.url for r in results if r.url],
+    }
+
+
+@overload
+async def agent_inference(
+    user_msg: str,
+    author_name: str,
+    client: Any,
+    context: Any,
+    enable_grounding: bool = False,
+    enable_live_context: bool = True,
+    max_lines: int = MAX_REPLY_LINES,
+    max_length: int = MAX_REPLY_LENGTH,
+    return_metadata: Literal[False] = False,
+) -> str: ...
+
+
+@overload
+async def agent_inference(
+    user_msg: str,
+    author_name: str,
+    client: Any,
+    context: Any,
+    enable_grounding: bool = False,
+    enable_live_context: bool = True,
+    max_lines: int = MAX_REPLY_LINES,
+    max_length: int = MAX_REPLY_LENGTH,
+    *,
+    return_metadata: Literal[True],
+) -> tuple[str, GroundingMetadata]: ...
+
+
+async def agent_inference(
+    user_msg: str,
+    author_name: str,
+    client: Any,
+    context: Any,
+    enable_grounding: bool = False,
+    enable_live_context: bool = True,
+    max_lines: int = MAX_REPLY_LINES,
+    max_length: int = MAX_REPLY_LENGTH,
+    return_metadata: bool = False,
+) -> str | tuple[str, GroundingMetadata]:
+    from bot.logic_constants import MODEL_INPUT_COST_PER_1M_USD, MODEL_OUTPUT_COST_PER_1M_USD
+
+    if not user_msg:
+        if return_metadata:
+            return "", empty_grounding_metadata(enabled=False)
+        return ""
+
+    # --- Web Search (DDG) para current events ---
+    search_results: list[Any] = []
+    if enable_grounding:
+        search_query = _extract_search_query(user_msg)
+        search_results = await search_web(search_query)
+
+    grounding_metadata = _build_grounding_metadata(search_results, enabled=enable_grounding)
+
+    # --- Model selection ---
+    is_serious = not enable_grounding and len(user_msg) >= 40
+    model = _select_model(enable_grounding, is_serious)
+
+    # --- Build messages ---
+    system_instr = build_system_instruction(context)
+    user_prompt = build_dynamic_prompt(
+        user_msg,
+        author_name,
+        context,
+        include_live_context=enable_live_context,
+    )
+
+    # Inject search context into system prompt
+    if search_results:
+        search_context = format_search_context(search_results)
+        system_instr += f"\n\n{search_context}"
+
+    messages = [
+        {"role": "system", "content": system_instr},
+        {"role": "user", "content": user_prompt}
+    ]
+
+    for attempt in range(MODEL_RATE_LIMIT_MAX_RETRIES + 1):
+        try:
+            response = await asyncio.wait_for(
+                asyncio.to_thread(
+                    client.chat.completions.create,
+                    model=model,
+                    messages=messages,
+                    temperature=MODEL_TEMPERATURE,
+                    max_tokens=2048,
+                ),
+                timeout=120.0,
+            )
+
+            input_tokens, output_tokens = _extract_usage(response)
+            if input_tokens > 0 or output_tokens > 0:
+                cost = (input_tokens / 1_000_000.0) * MODEL_INPUT_COST_PER_1M_USD + \
+                       (output_tokens / 1_000_000.0) * MODEL_OUTPUT_COST_PER_1M_USD
+
+                observability.record_token_usage(
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    estimated_cost_usd=cost,
+                )
+
+            if not response.choices:
+                logger.warning("Nebius retornou resposta sem escolhas (model=%s).", model)
+                break
+
+            reply_text = response.choices[0].message.content
+            if reply_text:
+                final_reply = enforce_reply_limits(reply_text, max_lines=max_lines, max_length=max_length)
+                if return_metadata:
+                    return final_reply, grounding_metadata
+                return final_reply
+
+            break
+        except Exception as error:
+            if is_timeout_inference_error(error):
+                logger.warning("Inference timeout (attempt %d, model=%s).", attempt + 1, model)
+                if attempt >= MODEL_RATE_LIMIT_MAX_RETRIES:
+                    if return_metadata:
+                        return UNSTABLE_CONNECTION_FALLBACK, empty_grounding_metadata(enabled=False)
+                    return UNSTABLE_CONNECTION_FALLBACK
+                continue
+
+            if is_rate_limited_inference_error(error) and attempt < MODEL_RATE_LIMIT_MAX_RETRIES:
+                backoff_seconds = MODEL_RATE_LIMIT_BACKOFF_SECONDS * (attempt + 1)
+                logger.warning("Inference rate-limited. Retrying in %.2fs (%d/%d).", backoff_seconds, attempt + 1, MODEL_RATE_LIMIT_MAX_RETRIES + 1)
+                await asyncio.sleep(backoff_seconds)
+                continue
+
+            logger.error("Inference Error (model=%s): %s", model, error)
+            if return_metadata:
+                return UNSTABLE_CONNECTION_FALLBACK, empty_grounding_metadata(enabled=False)
+            return UNSTABLE_CONNECTION_FALLBACK
+
+    if return_metadata:
+        return EMPTY_RESPONSE_FALLBACK, empty_grounding_metadata(enabled=False)
+    return EMPTY_RESPONSE_FALLBACK

bot/main.py

@@ -0,0 +1,153 @@
+import threading
+
+from bot import byte_semantics
+from bot.bootstrap_runtime import (
+    build_irc_token_manager,
+    get_secret,
+    resolve_irc_channel_logins,
+    run_eventsub_mode,
+    run_irc_mode,
+)
+from bot.dashboard_server import HealthHandler, run_server
+from bot.eventsub_runtime import AgentComponent, ByteBot
+from bot.irc_protocol import is_irc_notice_delivery_block
+from bot.irc_runtime import IrcByteBot
+from bot.logic import context
+from bot.observability import observability
+from bot.prompt_runtime import (
+    build_intro_reply,
+    build_quality_rewrite_prompt,
+    build_verifiable_prompt,
+    extract_movie_title,
+    handle_byte_prompt_text,
+    is_current_events_prompt,
+    is_follow_up_prompt,
+    is_intro_prompt,
+    is_low_quality_answer,
+    is_serious_technical_prompt,
+)
+from bot.runtime_config import (
+    AUTO_SCENE_REQUIRE_METADATA,
+    BOT_ID,
+    BYTE_DASHBOARD_ADMIN_TOKEN,
+    BYTE_HELP_MESSAGE,
+    BYTE_INTRO_TEMPLATES,
+    BYTE_VERSION,
+    CHANNEL_ID,
+    CLIENT_ID,
+    ENABLE_LIVE_CONTEXT_LEARNING,
+    MAX_CHAT_MESSAGE_LENGTH,
+    MULTIPART_SEPARATOR,
+    OWNER_ID,
+    QUALITY_SAFE_FALLBACK,
+    SERIOUS_REPLY_MAX_LENGTH,
+    SERIOUS_REPLY_MAX_LINES,
+    TWITCH_BOT_LOGIN,
+    TWITCH_CHANNEL_LOGIN,
+    TWITCH_CHANNEL_LOGINS_RAW,
+    TWITCH_CHAT_MODE,
+    TWITCH_CLIENT_SECRET_INLINE,
+    TWITCH_CLIENT_SECRET_NAME,
+    TWITCH_IRC_CHANNEL_ACTION_TIMEOUT_SECONDS,
+    TWITCH_IRC_HOST,
+    TWITCH_IRC_PORT,
+    TWITCH_IRC_TLS,
+    TWITCH_REFRESH_TOKEN,
+    TWITCH_TOKEN_REFRESH_MARGIN_SECONDS,
+    TWITCH_USER_TOKEN,
+    irc_channel_control,
+    logger,
+)
+from bot.scene_runtime import auto_update_scene_from_message, resolve_scene_metadata
+from bot.status_runtime import build_status_line
+from bot.twitch_tokens import TwitchTokenManager, is_irc_auth_failure_line
+
+parse_byte_prompt = byte_semantics.parse_byte_prompt
+build_llm_enhanced_prompt = byte_semantics.build_llm_enhanced_prompt
+build_direct_answer_instruction = byte_semantics.build_direct_answer_instruction
+extract_multi_reply_parts = byte_semantics.extract_multi_reply_parts
+
+__all__ = [
+    "main",
+    "run_server",
+    "run_eventsub_mode",
+    "run_irc_mode",
+    "get_secret",
+    "build_irc_token_manager",
+    "resolve_irc_channel_logins",
+    "HealthHandler",
+    "AgentComponent",
+    "ByteBot",
+    "IrcByteBot",
+    "context",
+    "observability",
+    "build_intro_reply",
+    "build_quality_rewrite_prompt",
+    "build_verifiable_prompt",
+    "extract_movie_title",
+    "handle_byte_prompt_text",
+    "is_current_events_prompt",
+    "is_follow_up_prompt",
+    "is_intro_prompt",
+    "is_low_quality_answer",
+    "is_serious_technical_prompt",
+    "auto_update_scene_from_message",
+    "resolve_scene_metadata",
+    "build_status_line",
+    "TwitchTokenManager",
+    "is_irc_auth_failure_line",
+    "is_irc_notice_delivery_block",
+    "parse_byte_prompt",
+    "build_llm_enhanced_prompt",
+    "build_direct_answer_instruction",
+    "extract_multi_reply_parts",
+    "AUTO_SCENE_REQUIRE_METADATA",
+    "BOT_ID",
+    "BYTE_DASHBOARD_ADMIN_TOKEN",
+    "BYTE_HELP_MESSAGE",
+    "BYTE_INTRO_TEMPLATES",
+    "BYTE_VERSION",
+    "CHANNEL_ID",
+    "CLIENT_ID",
+    "ENABLE_LIVE_CONTEXT_LEARNING",
+    "MAX_CHAT_MESSAGE_LENGTH",
+    "MULTIPART_SEPARATOR",
+    "OWNER_ID",
+    "QUALITY_SAFE_FALLBACK",
+    "SERIOUS_REPLY_MAX_LENGTH",
+    "SERIOUS_REPLY_MAX_LINES",
+    "TWITCH_BOT_LOGIN",
+    "TWITCH_CHANNEL_LOGIN",
+    "TWITCH_CHANNEL_LOGINS_RAW",
+    "TWITCH_CHAT_MODE",
+    "TWITCH_CLIENT_SECRET_INLINE",
+    "TWITCH_CLIENT_SECRET_NAME",
+    "TWITCH_IRC_CHANNEL_ACTION_TIMEOUT_SECONDS",
+    "TWITCH_IRC_HOST",
+    "TWITCH_IRC_PORT",
+    "TWITCH_IRC_TLS",
+    "TWITCH_REFRESH_TOKEN",
+    "TWITCH_TOKEN_REFRESH_MARGIN_SECONDS",
+    "TWITCH_USER_TOKEN",
+    "irc_channel_control",
+    "logger",
+]
+
+
+def main() -> None:
+    from bot.heartbeat import start_heartbeat
+
+    start_heartbeat()
+    threading.Thread(target=run_server, daemon=True).start()
+    try:
+        if TWITCH_CHAT_MODE == "irc":
+            run_irc_mode()
+        else:
+            run_eventsub_mode()
+    except Exception as error:
+        logger.critical("Fatal Byte Error: %s", error)
+        observability.record_error(category="fatal", details=str(error))
+
+
+if __name__ == "__main__":
+    main()

bot/observability.py

@@ -0,0 +1,5 @@
+from bot.observability_state import ObservabilityState
+
+observability = ObservabilityState()
+
+__all__ = ["ObservabilityState", "observability"]

bot/observability_analytics.py

@@ -0,0 +1,144 @@
+from collections import Counter
+from typing import Any
+
+from bot.observability_helpers import (
+    LEADERBOARD_LIMIT,
+    percentage,
+)
+
+def compute_chat_metrics(
+    chat_events: list[dict[str, Any]],
+    now: float,
+) -> dict[str, Any]:
+    cutoff_10m = now - 600
+    cutoff_60m = now - 3600
+    
+    events_10m = [e for e in chat_events if float(e.get("ts", 0.0)) >= cutoff_10m]
+    events_60m = [e for e in chat_events if float(e.get("ts", 0.0)) >= cutoff_60m]
+    
+    count_10m = len(events_10m)
+    count_60m = len(events_60m)
+    
+    avg_len_10m = round(sum(int(e.get("length", 0)) for e in events_10m) / count_10m, 1) if count_10m else 0.0
+    avg_len_60m = round(sum(int(e.get("length", 0)) for e in events_60m) / count_60m, 1) if count_60m else 0.0
+    
+    command_60m = sum(1 for e in events_60m if bool(e.get("is_command", False)))
+    url_60m = sum(1 for e in events_60m if bool(e.get("has_url", False)))
+    
+    return {
+        "messages_10m": count_10m,
+        "messages_60m": count_60m,
+        "messages_per_minute_10m": round(count_10m / 10, 2),
+        "messages_per_minute_60m": round(count_60m / 60, 2),
+        "avg_message_length_10m": avg_len_10m,
+        "avg_message_length_60m": avg_len_60m,
+        "prefixed_commands_60m": command_60m,
+        "prefixed_command_ratio_60m": percentage(command_60m, count_60m),
+        "url_messages_60m": url_60m,
+        "url_ratio_60m": percentage(url_60m, count_60m),
+        "events_60m": events_60m,  # return for further processing (e.g. source counts)
+    }
+
+def compute_interaction_metrics(
+    interaction_events: list[dict[str, Any]],
+    now: float,
+) -> dict[str, Any]:
+    cutoff_60m = now - 3600
+    events_60m = [e for e in interaction_events if float(e.get("ts", 0.0)) >= cutoff_60m]
+    
+    llm_60m = sum(1 for e in events_60m if bool(e.get("is_llm", False)))
+    useful_60m = sum(1 for e in events_60m if bool(e.get("is_useful_llm", False)))
+    
+    return {
+        "llm_interactions_60m": llm_60m,
+        "useful_llm_interactions_60m": useful_60m,
+        "useful_engagement_rate_60m": percentage(useful_60m, llm_60m),
+    }
+
+def compute_quality_metrics(
+    quality_events: list[dict[str, Any]],
+    llm_interactions_60m: int,
+    now: float,
+) -> dict[str, Any]:
+    cutoff_60m = now - 3600
+    events_60m = [e for e in quality_events if float(e.get("ts", 0.0)) >= cutoff_60m]
+    
+    retry_60m = sum(1 for e in events_60m if str(e.get("outcome", "")).strip().lower() == "retry")
+    success_60m = sum(1 for e in events_60m if str(e.get("outcome", "")).strip().lower() == "retry_success")
+    fallback_60m = sum(1 for e in events_60m if str(e.get("outcome", "")).strip().lower() == "fallback")
+    
+    return {
+        "quality_retry_60m": retry_60m,
+        "quality_retry_success_60m": success_60m,
+        "quality_fallback_60m": fallback_60m,
+        "correction_rate_60m": percentage(success_60m, retry_60m),
+        "correction_trigger_rate_60m": percentage(retry_60m, llm_interactions_60m),
+    }
+
+def compute_token_metrics(
+    token_usage_events: list[dict[str, Any]],
+    now: float,
+) -> dict[str, Any]:
+    cutoff_60m = now - 3600
+    events_60m = [e for e in token_usage_events if float(e.get("ts", 0.0)) >= cutoff_60m]
+    
+    input_60m = sum(max(0, int(e.get("input_tokens", 0) or 0)) for e in events_60m)
+    output_60m = sum(max(0, int(e.get("output_tokens", 0) or 0)) for e in events_60m)
+    cost_60m = sum(max(0.0, float(e.get("estimated_cost_usd", 0.0) or 0.0)) for e in events_60m)
+    
+    return {
+        "token_input_60m": input_60m,
+        "token_output_60m": output_60m,
+        "estimated_cost_usd_60m": cost_60m,
+    }
+
+def compute_autonomy_metrics(
+    autonomy_events: list[dict[str, Any]],
+    now: float,
+) -> dict[str, Any]:
+    cutoff_60m = now - 3600
+    events_60m = [e for e in autonomy_events if float(e.get("ts", 0.0)) >= cutoff_60m]
+    
+    total_60m = len(events_60m)
+    ignored_60m = sum(1 for e in events_60m if str(e.get("outcome", "")).strip().lower() == "ignored")
+    
+    return {
+        "autonomy_goals_60m": total_60m,
+        "ignored_total_60m": ignored_60m,
+        "ignored_rate_60m": percentage(ignored_60m, total_60m),
+    }
+
+def compute_leaderboards(
+    chat_events_60m: list[dict[str, Any]],
+    trigger_events_60m: list[dict[str, Any]],
+    chatter_totals: dict[str, int],
+    trigger_totals: dict[str, int],
+) -> dict[str, Any]:
+    chatters_60m: Counter[str] = Counter()
+    source_counts_60m: Counter[str] = Counter()
+    
+    for e in chat_events_60m:
+        author = str(e.get("author", "") or "").strip().lower()
+        source = str(e.get("source", "unknown") or "unknown")
+        if author:
+            chatters_60m[author] += 1
+        source_counts_60m[source] += 1
+            
+    triggers_60m: Counter[str] = Counter()
+    for e in trigger_events_60m:
+        author = str(e.get("author", "") or "").strip().lower()
+        if author:
+            triggers_60m[author] += 1
+            
+    top_chatters_60m = [{"author": a, "messages": c} for a, c in chatters_60m.most_common(LEADERBOARD_LIMIT)]
+    top_chatters_total = [{"author": a, "messages": c} for a, c in Counter(chatter_totals).most_common(LEADERBOARD_LIMIT)]
+    top_triggers_60m = [{"author": a, "triggers": c} for a, c in triggers_60m.most_common(LEADERBOARD_LIMIT)]
+    top_triggers_total = [{"author": a, "triggers": c} for a, c in Counter(trigger_totals).most_common(LEADERBOARD_LIMIT)]
+    
+    return {
+        "top_chatters_60m": top_chatters_60m,
+        "top_chatters_total": top_chatters_total,
+        "top_trigger_users_60m": top_triggers_60m,
+        "top_trigger_users_total": top_triggers_total,
+        "source_counts_60m": source_counts_60m,
+    }

bot/observability_helpers.py

@@ -0,0 +1,36 @@
+from datetime import datetime, timezone
+
+TIMELINE_RETENTION_MINUTES = 180
+TIMELINE_WINDOW_MINUTES = 30
+EVENT_LOG_MAX_ITEMS = 120
+LATENCY_WINDOW_MAX_ITEMS = 300
+CHAT_EVENTS_RETENTION_SECONDS = 6 * 3600
+BYTE_TRIGGER_EVENTS_RETENTION_SECONDS = 6 * 3600
+CHAT_EVENTS_MAX_ITEMS = 30_000
+BYTE_TRIGGER_EVENTS_MAX_ITEMS = 12_000
+LEADERBOARD_LIMIT = 8
+
+
+def utc_iso(timestamp: float) -> str:
+    return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def clip_preview(text: str, max_chars: int = 120) -> str:
+    compact = " ".join((text or "").split())
+    if len(compact) <= max_chars:
+        return compact
+    return compact[: max_chars - 3].rstrip() + "..."
+
+
+def compute_p95(values: list[float]) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    index = int(0.95 * (len(ordered) - 1))
+    return round(ordered[index], 1)
+
+
+def percentage(value: int, total: int) -> float:
+    if total <= 0:
+        return 0.0
+    return round((value / total) * 100, 1)

bot/observability_snapshot.py

@@ -0,0 +1,211 @@
+from datetime import datetime, timezone
+from typing import Any
+from bot.observability_helpers import (
+    TIMELINE_WINDOW_MINUTES,
+    clip_preview,
+    compute_p95,
+    utc_iso,
+)
+from bot.observability_analytics import (
+    compute_chat_metrics,
+    compute_interaction_metrics,
+    compute_quality_metrics,
+    compute_token_metrics,
+    compute_autonomy_metrics,
+    compute_leaderboards,
+)
+
+def build_observability_snapshot(
+    *,
+    now: float,
+    started_at: float,
+    counters: dict[str, int],
+    route_counts: dict[str, int],
+    latencies_ms: list[float],
+    minute_buckets: dict[int, dict[str, int]],
+    recent_events: list[dict[str, Any]],
+    chatter_last_seen: dict[str, float],
+    chat_events: list[dict[str, Any]],
+    byte_trigger_events: list[dict[str, Any]],
+    interaction_events: list[dict[str, Any]],
+    quality_events: list[dict[str, Any]],
+    token_usage_events: list[dict[str, Any]],
+    autonomy_goal_events: list[dict[str, Any]],
+    chatter_message_totals: dict[str, int],
+    trigger_user_totals: dict[str, int],
+    unique_chatters_total: int,
+    last_prompt: str,
+    last_reply: str,
+    estimated_cost_usd_total: float,
+    clips_status: dict[str, bool],
+    bot_brand: str,
+    bot_version: str,
+    bot_mode: str,
+    stream_context: Any,
+) -> dict[str, Any]:
+    # Active users
+    active_chatters_10m = sum(1 for value in chatter_last_seen.values() if now - value <= 600)
+    active_chatters_60m = sum(1 for value in chatter_last_seen.values() if now - value <= 3600)
+    
+    # Latency
+    avg_latency_ms = round(sum(latencies_ms) / len(latencies_ms), 1) if latencies_ms else 0.0
+    p95_latency_ms = compute_p95(latencies_ms)
+    
+    # Analytics
+    chat_metrics = compute_chat_metrics(chat_events, now)
+    interaction_metrics = compute_interaction_metrics(interaction_events, now)
+    quality_metrics = compute_quality_metrics(
+        quality_events, 
+        interaction_metrics["llm_interactions_60m"], 
+        now
+    )
+    token_metrics = compute_token_metrics(token_usage_events, now)
+    autonomy_metrics = compute_autonomy_metrics(autonomy_goal_events, now)
+    
+    # Leaderboards
+    # Need byte_trigger_events filtered for 60m first
+    cutoff_60m = now - 3600
+    trigger_events_60m = [e for e in byte_trigger_events if float(e.get("ts", 0.0)) >= cutoff_60m]
+    
+    leaderboards = compute_leaderboards(
+        chat_metrics.pop("events_60m"), # Pop to remove from result dict
+        trigger_events_60m,
+        chatter_message_totals,
+        trigger_user_totals,
+    )
+    
+    source_counts = leaderboards.pop("source_counts_60m")
+    chat_metrics["source_counts_60m"] = {
+        "irc": int(source_counts.get("irc", 0)),
+        "eventsub": int(source_counts.get("eventsub", 0)),
+        "unknown": int(source_counts.get("unknown", 0)),
+    }
+    chat_metrics["byte_triggers_10m"] = len([e for e in byte_trigger_events if float(e.get("ts", 0.0)) >= now - 600])
+    chat_metrics["byte_triggers_60m"] = len(trigger_events_60m)
+
+    # Context
+    context_vibe = str(getattr(stream_context, "stream_vibe", "Conversa") or "Conversa")
+    context_last_event = str(getattr(stream_context, "last_event", "Bot Online") or "Bot Online")
+    raw_observability = getattr(stream_context, "live_observability", {}) or {}
+    context_items = {str(key): str(value) for key, value in dict(raw_observability).items() if str(value).strip()}
+    context_active_count = len(context_items)
+
+    get_uptime_minutes = getattr(stream_context, "get_uptime_minutes", None)
+    if callable(get_uptime_minutes):
+        uptime_value = get_uptime_minutes()
+        if isinstance(uptime_value, (int, float, str)):
+            uptime_minutes = max(0, int(uptime_value))
+        else:
+            uptime_minutes = max(0, int((now - started_at) / 60))
+    else:
+        uptime_minutes = max(0, int((now - started_at) / 60))
+
+    # Timeline
+    now_minute = int(now // 60)
+    timeline = []
+    for minute_key in range(now_minute - TIMELINE_WINDOW_MINUTES + 1, now_minute + 1):
+        bucket: dict[str, int] = minute_buckets.get(minute_key) or {}
+        timeline.append(
+            {
+                "minute_epoch": minute_key * 60,
+                "label": datetime.fromtimestamp(minute_key * 60, tz=timezone.utc).strftime("%H:%M"),
+                "chat_messages": int(bucket.get("chat_messages", 0)),
+                "byte_triggers": int(bucket.get("byte_triggers", 0)),
+                "replies_sent": int(bucket.get("replies_sent", 0)),
+                "llm_requests": int(bucket.get("llm_requests", 0)),
+                "errors": int(bucket.get("errors", 0)),
+            }
+        )
+
+    sorted_routes = sorted(route_counts.items(), key=lambda item: item[1], reverse=True)
+    route_rows = [{"route": route, "count": count} for route, count in sorted_routes]
+    events_desc = list(reversed(recent_events[-40:]))
+
+    return {
+        "timestamp": utc_iso(now),
+        "bot": {
+            "brand": bot_brand,
+            "version": bot_version,
+            "mode": bot_mode,
+            "status": "online",
+            "uptime_minutes": uptime_minutes,
+        },
+        "metrics": {
+            "chat_messages_total": int(counters.get("chat_messages_total", 0)),
+            "chat_messages_irc_total": int(counters.get("chat_messages_irc", 0)),
+            "chat_messages_eventsub_total": int(counters.get("chat_messages_eventsub", 0)),
+            "chat_prefixed_messages_total": int(counters.get("chat_prefixed_messages", 0)),
+            "chat_messages_with_url_total": int(counters.get("chat_messages_with_url", 0)),
+            "byte_triggers_total": int(counters.get("byte_triggers_total", 0)),
+            "interactions_total": int(counters.get("interactions_total", 0)),
+            "replies_total": int(counters.get("replies_total", 0)),
+            "llm_interactions_total": int(counters.get("llm_interactions_total", 0)),
+            "serious_interactions_total": int(counters.get("serious_interactions_total", 0)),
+            "current_events_interactions_total": int(counters.get("current_events_interactions_total", 0)),
+            "follow_up_interactions_total": int(counters.get("follow_up_interactions_total", 0)),
+            "quality_checks_total": int(counters.get("quality_checks_total", 0)),
+            "quality_retry_total": int(counters.get("quality_retry_total", 0)),
+            "quality_retry_success_total": int(counters.get("quality_retry_success_total", 0)),
+            "quality_fallback_total": int(counters.get("quality_fallback_total", 0)),
+            "auto_scene_updates_total": int(counters.get("auto_scene_updates_total", 0)),
+            "token_input_total": int(counters.get("token_input_total", 0)),
+            "token_output_total": int(counters.get("token_output_total", 0)),
+            "estimated_cost_usd_total": round(max(0.0, float(estimated_cost_usd_total or 0.0)), 6),
+            "token_refreshes_total": int(counters.get("token_refreshes_total", 0)),
+            "auth_failures_total": int(counters.get("auth_failures_total", 0)),
+            "errors_total": int(counters.get("errors_total", 0)),
+            "vision_frames_total": int(counters.get("vision_frames_total", 0)),
+            "avg_latency_ms": avg_latency_ms,
+            "p95_latency_ms": p95_latency_ms,
+        },
+        "chatters": {
+            "unique_total": unique_chatters_total,
+            "active_10m": active_chatters_10m,
+            "active_60m": active_chatters_60m,
+        },
+        "chat_analytics": chat_metrics,
+        "leaderboards": leaderboards,
+        "agent_outcomes": {
+            **interaction_metrics,
+            **quality_metrics,
+            **autonomy_metrics,
+            "token_input_total": int(counters.get("token_input_total", 0)),
+            "token_output_total": int(counters.get("token_output_total", 0)),
+            **token_metrics,
+            "estimated_cost_usd_total": round(max(0.0, float(estimated_cost_usd_total or 0.0)), 6),
+        },
+        "context": {
+            "stream_vibe": context_vibe,
+            "last_event": context_last_event,
+            "active_contexts": context_active_count,
+            "items": context_items,
+            "last_prompt": clip_preview(last_prompt, max_chars=120),
+            "last_reply": clip_preview(last_reply, max_chars=140),
+            "clips_status": clips_status,
+        },
+        "counters": {key: int(value) for key, value in counters.items()},
+        "routes": route_rows,
+        "timeline": timeline,
+        "recent_events": events_desc,
+        "sentiment": _build_sentiment_block(),
+        "vision": _build_vision_block(),
+    }
+
+
+def _build_sentiment_block() -> dict[str, Any]:
+    from bot.sentiment_engine import sentiment_engine  # lazy: avoid circular
+
+    scores = sentiment_engine.get_scores()
+    return {
+        "vibe": sentiment_engine.get_vibe(),
+        "avg": scores["avg"],
+        "count": scores["count"],
+        "positive": scores["positive"],
+        "negative": scores["negative"],
+    }
+
+
+def _build_vision_block() -> dict[str, Any]:
+    from bot.vision_runtime import vision_runtime  # lazy: avoid circular
+
+    return vision_runtime.get_status()

bot/observability_state.py

@@ -0,0 +1,225 @@
+import threading
+import time
+from collections import Counter, deque
+from typing import Any
+
+from bot.observability_helpers import (
+    BYTE_TRIGGER_EVENTS_MAX_ITEMS,
+    CHAT_EVENTS_MAX_ITEMS,
+    EVENT_LOG_MAX_ITEMS,
+    LATENCY_WINDOW_MAX_ITEMS,
+)
+from bot.observability_snapshot import build_observability_snapshot
+from bot.observability_state_core import prune_locked, resolve_now
+from bot.observability_state_recorders import (
+    record_auth_failure_locked,
+    record_autonomy_goal_locked,
+    record_auto_scene_update_locked,
+    record_byte_interaction_locked,
+    record_byte_trigger_locked,
+    record_chat_message_locked,
+    record_error_locked,
+    record_quality_gate_locked,
+    record_reply_locked,
+    record_token_refresh_locked,
+    record_token_usage_locked,
+    record_vision_frame_locked,
+)
+
+
+class ObservabilityState:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._started_at = time.time()
+        self._counters: Counter[str] = Counter()
+        self._route_counts: Counter[str] = Counter()
+        self._minute_buckets: dict[int, dict[str, int]] = {}
+        self._latencies_ms: deque[float] = deque(maxlen=LATENCY_WINDOW_MAX_ITEMS)
+        self._recent_events: deque[dict[str, Any]] = deque(maxlen=EVENT_LOG_MAX_ITEMS)
+        self._chatter_last_seen: dict[str, float] = {}
+        self._known_chatters: set[str] = set()
+        self._chat_events: deque[dict[str, Any]] = deque(maxlen=CHAT_EVENTS_MAX_ITEMS)
+        self._byte_trigger_events: deque[dict[str, Any]] = deque(maxlen=BYTE_TRIGGER_EVENTS_MAX_ITEMS)
+        self._interaction_events: deque[dict[str, Any]] = deque(maxlen=BYTE_TRIGGER_EVENTS_MAX_ITEMS)
+        self._quality_events: deque[dict[str, Any]] = deque(maxlen=BYTE_TRIGGER_EVENTS_MAX_ITEMS)
+        self._token_usage_events: deque[dict[str, Any]] = deque(maxlen=BYTE_TRIGGER_EVENTS_MAX_ITEMS)
+        self._autonomy_goal_events: deque[dict[str, Any]] = deque(maxlen=BYTE_TRIGGER_EVENTS_MAX_ITEMS)
+        self._chatter_message_totals: Counter[str] = Counter()
+        self._trigger_user_totals: Counter[str] = Counter()
+        self._last_prompt = ""
+        self._last_reply = ""
+        self._estimated_cost_usd_total = 0.0
+        self._clips_status: dict[str, bool] = {
+            "token_valid": False,
+            "scope_ok": False,
+        }
+
+    def update_clips_auth_status(self, *, token_valid: bool, scope_ok: bool, timestamp: float | None = None) -> None:
+        with self._lock:
+            self._clips_status["token_valid"] = bool(token_valid)
+            self._clips_status["scope_ok"] = bool(scope_ok)
+            # We could record an event here if needed, but the requirement is just status.
+
+    def record_chat_message(self, *, author_name: str, source: str, text: str = "", timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_chat_message_locked(
+                self,
+                now=now,
+                author_name=author_name,
+                source=source,
+                text=text,
+            )
+
+    def record_byte_trigger(self, *, prompt: str, source: str, author_name: str = "", timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_byte_trigger_locked(
+                self,
+                now=now,
+                prompt=prompt,
+                source=source,
+                author_name=author_name,
+            )
+
+    def record_reply(self, *, text: str, timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_reply_locked(self, now=now, text=text)
+
+    def record_quality_gate(self, *, outcome: str, reason: str, timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_quality_gate_locked(self, now=now, outcome=outcome, reason=reason)
+
+    def record_byte_interaction(
+        self,
+        *,
+        route: str,
+        author_name: str,
+        prompt_chars: int,
+        reply_parts: int,
+        reply_chars: int,
+        serious: bool,
+        follow_up: bool,
+        current_events: bool,
+        latency_ms: float,
+        timestamp: float | None = None,
+    ) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_byte_interaction_locked(
+                self,
+                now=now,
+                route=route,
+                author_name=author_name,
+                prompt_chars=prompt_chars,
+                reply_parts=reply_parts,
+                reply_chars=reply_chars,
+                serious=serious,
+                follow_up=follow_up,
+                current_events=current_events,
+                latency_ms=latency_ms,
+            )
+
+    def record_token_usage(
+        self,
+        *,
+        input_tokens: int,
+        output_tokens: int,
+        estimated_cost_usd: float,
+        timestamp: float | None = None,
+    ) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_token_usage_locked(
+                self,
+                now=now,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                estimated_cost_usd=estimated_cost_usd,
+            )
+
+    def record_autonomy_goal(
+        self,
+        *,
+        risk: str,
+        outcome: str,
+        details: str = "",
+        timestamp: float | None = None,
+    ) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_autonomy_goal_locked(
+                self,
+                now=now,
+                risk=risk,
+                outcome=outcome,
+                details=details,
+            )
+
+    def record_auto_scene_update(self, *, update_types: list[str], timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_auto_scene_update_locked(self, now=now, update_types=update_types)
+
+    def record_token_refresh(self, *, reason: str, timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_token_refresh_locked(self, now=now, reason=reason)
+
+    def record_auth_failure(self, *, details: str, timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_auth_failure_locked(self, now=now, details=details)
+
+    def record_error(self, *, category: str, details: str, timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_error_locked(self, now=now, category=category, details=details)
+
+    def record_vision_frame(self, *, analysis: str, timestamp: float | None = None) -> None:
+        now = resolve_now(timestamp)
+        with self._lock:
+            record_vision_frame_locked(self, now=now, analysis=analysis)
+
+    def snapshot(
+        self,
+        *,
+        bot_brand: str,
+        bot_version: str,
+        bot_mode: str,
+        stream_context: Any,
+        timestamp: float | None = None,
+    ) -> dict[str, Any]:
+        now = resolve_now(timestamp)
+        with self._lock:
+            prune_locked(self, now)
+            return build_observability_snapshot(
+                now=now,
+                started_at=self._started_at,
+                counters=dict(self._counters),
+                route_counts=dict(self._route_counts),
+                latencies_ms=list(self._latencies_ms),
+                minute_buckets={key: value.copy() for key, value in self._minute_buckets.items()},
+                recent_events=list(self._recent_events),
+                chatter_last_seen=dict(self._chatter_last_seen),
+                chat_events=list(self._chat_events),
+                byte_trigger_events=list(self._byte_trigger_events),
+                interaction_events=list(self._interaction_events),
+                quality_events=list(self._quality_events),
+                token_usage_events=list(self._token_usage_events),
+                autonomy_goal_events=list(self._autonomy_goal_events),
+                chatter_message_totals=dict(self._chatter_message_totals),
+                trigger_user_totals=dict(self._trigger_user_totals),
+                unique_chatters_total=len(self._known_chatters),
+                last_prompt=self._last_prompt,
+                last_reply=self._last_reply,
+                estimated_cost_usd_total=float(self._estimated_cost_usd_total),
+                clips_status=dict(self._clips_status),
+                bot_brand=bot_brand,
+                bot_version=bot_version,
+                bot_mode=bot_mode,
+                stream_context=stream_context,
+            )
+

bot/observability_state_core.py

@@ -0,0 +1,76 @@
+import time
+from typing import Any
+
+from bot.observability_helpers import (
+    BYTE_TRIGGER_EVENTS_RETENTION_SECONDS,
+    CHAT_EVENTS_RETENTION_SECONDS,
+    TIMELINE_RETENTION_MINUTES,
+    clip_preview,
+    utc_iso,
+)
+
+
+def resolve_now(timestamp: float | None) -> float:
+    return time.time() if timestamp is None else float(timestamp)
+
+
+def touch_bucket_locked(state: Any, now: float) -> dict[str, int]:
+    minute_key = int(now // 60)
+    bucket = state._minute_buckets.get(minute_key)
+    if bucket is None:
+        bucket = {
+            "chat_messages": 0,
+            "byte_triggers": 0,
+            "replies_sent": 0,
+            "llm_requests": 0,
+            "errors": 0,
+        }
+        state._minute_buckets[minute_key] = bucket
+    return bucket
+
+
+def bump_timeline_locked(state: Any, now: float, **increments: int) -> None:
+    bucket = touch_bucket_locked(state, now)
+    for key, amount in increments.items():
+        if amount > 0:
+            bucket[key] = bucket.get(key, 0) + int(amount)
+
+
+def append_event_locked(state: Any, now: float, level: str, event: str, message: str) -> None:
+    state._recent_events.append(
+        {
+            "ts": utc_iso(now),
+            "level": level,
+            "event": event,
+            "message": clip_preview(message, max_chars=180),
+        }
+    )
+
+
+def prune_locked(state: Any, now: float) -> None:
+    oldest_minute = int(now // 60) - TIMELINE_RETENTION_MINUTES
+    for minute_key in list(state._minute_buckets):
+        if minute_key < oldest_minute:
+            del state._minute_buckets[minute_key]
+
+    oldest_chatter_cutoff = now - 86400
+    for chatter, last_seen in list(state._chatter_last_seen.items()):
+        if last_seen < oldest_chatter_cutoff:
+            del state._chatter_last_seen[chatter]
+
+    chat_cutoff = now - CHAT_EVENTS_RETENTION_SECONDS
+    while state._chat_events and float(state._chat_events[0].get("ts", 0.0)) < chat_cutoff:
+        state._chat_events.popleft()
+
+    trigger_cutoff = now - BYTE_TRIGGER_EVENTS_RETENTION_SECONDS
+    while state._byte_trigger_events and float(state._byte_trigger_events[0].get("ts", 0.0)) < trigger_cutoff:
+        state._byte_trigger_events.popleft()
+    while state._interaction_events and float(state._interaction_events[0].get("ts", 0.0)) < trigger_cutoff:
+        state._interaction_events.popleft()
+    while state._quality_events and float(state._quality_events[0].get("ts", 0.0)) < trigger_cutoff:
+        state._quality_events.popleft()
+    while state._token_usage_events and float(state._token_usage_events[0].get("ts", 0.0)) < trigger_cutoff:
+        state._token_usage_events.popleft()
+    while state._autonomy_goal_events and float(state._autonomy_goal_events[0].get("ts", 0.0)) < trigger_cutoff:
+        state._autonomy_goal_events.popleft()
+

bot/observability_state_recorders.py

@@ -0,0 +1,259 @@
+from typing import Any
+
+from bot.observability_helpers import clip_preview
+from bot.observability_state_core import append_event_locked, bump_timeline_locked, prune_locked
+
+
+def record_chat_message_locked(
+    state: Any,
+    *,
+    now: float,
+    author_name: str,
+    source: str,
+    text: str = "",
+) -> None:
+    safe_source = (source or "unknown").strip().lower() or "unknown"
+    safe_author = (author_name or "").strip().lower()
+    message_text = (text or "").strip()
+    is_command = bool(message_text.startswith("!"))
+    lowered_text = message_text.lower()
+    has_url = "http://" in lowered_text or "https://" in lowered_text
+
+    state._counters["chat_messages_total"] += 1
+    state._counters[f"chat_messages_{safe_source}"] += 1
+    bump_timeline_locked(state, now, chat_messages=1)
+    state._chat_events.append(
+        {
+            "ts": now,
+            "source": safe_source,
+            "author": safe_author,
+            "length": len(message_text),
+            "is_command": is_command,
+            "has_url": has_url,
+        }
+    )
+    if safe_author:
+        state._known_chatters.add(safe_author)
+        state._chatter_last_seen[safe_author] = now
+        state._chatter_message_totals[safe_author] += 1
+    if is_command:
+        state._counters["chat_prefixed_messages"] += 1
+    if has_url:
+        state._counters["chat_messages_with_url"] += 1
+    prune_locked(state, now)
+
+
+def record_byte_trigger_locked(
+    state: Any,
+    *,
+    now: float,
+    prompt: str,
+    source: str,
+    author_name: str = "",
+) -> None:
+    safe_source = (source or "unknown").strip().lower() or "unknown"
+    safe_author_key = (author_name or "").strip().lower() or "viewer"
+    safe_author = clip_preview(author_name or "viewer", max_chars=32)
+    prompt_preview = clip_preview(prompt or "(empty prompt)", max_chars=120)
+
+    state._counters["byte_triggers_total"] += 1
+    state._counters[f"byte_triggers_{safe_source}"] += 1
+    state._trigger_user_totals[safe_author_key] += 1
+    state._byte_trigger_events.append({"ts": now, "author": safe_author_key, "source": safe_source})
+    state._last_prompt = prompt_preview
+    bump_timeline_locked(state, now, byte_triggers=1)
+    append_event_locked(state, now, "INFO", "byte_trigger", f"{safe_author}: {prompt_preview}")
+    prune_locked(state, now)
+
+
+def record_reply_locked(state: Any, *, now: float, text: str) -> None:
+    reply_preview = clip_preview(text or "", max_chars=140)
+    if not reply_preview:
+        return
+    state._counters["replies_total"] += 1
+    state._counters["reply_chars_total"] += len(reply_preview)
+    state._last_reply = reply_preview
+    bump_timeline_locked(state, now, replies_sent=1)
+    prune_locked(state, now)
+
+
+def record_quality_gate_locked(
+    state: Any,
+    *,
+    now: float,
+    outcome: str,
+    reason: str,
+) -> None:
+    safe_outcome = (outcome or "unknown").strip().lower() or "unknown"
+    safe_reason = clip_preview(reason or "n/a", max_chars=120)
+    event_level = "WARN" if safe_outcome in {"retry", "fallback"} else "INFO"
+
+    state._counters["quality_checks_total"] += 1
+    state._counters[f"quality_{safe_outcome}_total"] += 1
+    state._quality_events.append(
+        {
+            "ts": now,
+            "outcome": safe_outcome,
+            "reason": safe_reason,
+        }
+    )
+    append_event_locked(state, now, event_level, "quality_gate", f"{safe_outcome}: {safe_reason}")
+    prune_locked(state, now)
+
+
+def record_byte_interaction_locked(
+    state: Any,
+    *,
+    now: float,
+    route: str,
+    author_name: str,
+    prompt_chars: int,
+    reply_parts: int,
+    reply_chars: int,
+    serious: bool,
+    follow_up: bool,
+    current_events: bool,
+    latency_ms: float,
+) -> None:
+    safe_route = (route or "unknown").strip().lower() or "unknown"
+    safe_author = clip_preview(author_name or "viewer", max_chars=32)
+
+    state._counters["interactions_total"] += 1
+    state._route_counts[safe_route] += 1
+    state._counters["prompt_chars_total"] += max(0, int(prompt_chars))
+    state._counters["interaction_reply_parts_total"] += max(0, int(reply_parts))
+    state._counters["interaction_reply_chars_total"] += max(0, int(reply_chars))
+    llm_route = safe_route.startswith("llm")
+    useful_llm = llm_route and "fallback" not in safe_route
+    state._interaction_events.append(
+        {
+            "ts": now,
+            "route": safe_route,
+            "is_llm": llm_route,
+            "is_useful_llm": useful_llm,
+        }
+    )
+    if safe_route.startswith("llm"):
+        state._counters["llm_interactions_total"] += 1
+        bump_timeline_locked(state, now, llm_requests=1)
+    if serious:
+        state._counters["serious_interactions_total"] += 1
+    if follow_up:
+        state._counters["follow_up_interactions_total"] += 1
+    if current_events:
+        state._counters["current_events_interactions_total"] += 1
+    if latency_ms >= 0:
+        state._latencies_ms.append(float(latency_ms))
+    details = (
+        f"{safe_route} by {safe_author} | prompt={max(0, int(prompt_chars))} chars | "
+        f"replies={max(0, int(reply_parts))} | latency={round(max(0.0, latency_ms), 1)}ms"
+    )
+    append_event_locked(state, now, "INFO", "byte_interaction", details)
+    prune_locked(state, now)
+
+
+def record_token_usage_locked(
+    state: Any,
+    *,
+    now: float,
+    input_tokens: int,
+    output_tokens: int,
+    estimated_cost_usd: float,
+) -> None:
+    safe_input = max(0, int(input_tokens))
+    safe_output = max(0, int(output_tokens))
+    safe_cost = max(0.0, float(estimated_cost_usd))
+
+    state._counters["token_input_total"] += safe_input
+    state._counters["token_output_total"] += safe_output
+    state._estimated_cost_usd_total += safe_cost
+    state._token_usage_events.append(
+        {
+            "ts": now,
+            "input_tokens": safe_input,
+            "output_tokens": safe_output,
+            "estimated_cost_usd": safe_cost,
+        }
+    )
+    prune_locked(state, now)
+
+
+def record_autonomy_goal_locked(
+    state: Any,
+    *,
+    now: float,
+    risk: str,
+    outcome: str,
+    details: str = "",
+) -> None:
+    safe_risk = (risk or "unknown").strip().lower() or "unknown"
+    safe_outcome = (outcome or "unknown").strip().lower() or "unknown"
+    details_preview = clip_preview(details or "", max_chars=100)
+
+    state._counters["autonomy_goals_total"] += 1
+    state._counters[f"autonomy_{safe_risk}_{safe_outcome}_total"] += 1
+    state._autonomy_goal_events.append(
+        {
+            "ts": now,
+            "risk": safe_risk,
+            "outcome": safe_outcome,
+        }
+    )
+    append_event_locked(
+        state,
+        now,
+        "INFO",
+        "autonomy_goal",
+        f"{safe_risk}/{safe_outcome}: {details_preview or 'ok'}",
+    )
+    prune_locked(state, now)
+
+
+def record_auto_scene_update_locked(
+    state: Any,
+    *,
+    now: float,
+    update_types: list[str],
+) -> None:
+    if not update_types:
+        return
+    safe_types = sorted({(item or "").strip().lower() for item in update_types if item})
+    if not safe_types:
+        return
+    state._counters["auto_scene_updates_total"] += len(safe_types)
+    append_event_locked(state, now, "INFO", "scene_update", f"updated: {', '.join(safe_types)}")
+    prune_locked(state, now)
+
+
+def record_token_refresh_locked(state: Any, *, now: float, reason: str) -> None:
+    safe_reason = clip_preview(reason or "n/a", max_chars=100)
+    state._counters["token_refreshes_total"] += 1
+    append_event_locked(state, now, "WARN", "token_refresh", safe_reason)
+    prune_locked(state, now)
+
+
+def record_auth_failure_locked(state: Any, *, now: float, details: str) -> None:
+    safe_details = clip_preview(details or "n/a", max_chars=120)
+    state._counters["auth_failures_total"] += 1
+    state._counters["errors_total"] += 1
+    bump_timeline_locked(state, now, errors=1)
+    append_event_locked(state, now, "ERROR", "auth_failure", safe_details)
+    prune_locked(state, now)
+
+
+def record_error_locked(state: Any, *, now: float, category: str, details: str) -> None:
+    safe_category = (category or "unknown").strip().lower() or "unknown"
+    safe_details = clip_preview(details or "n/a", max_chars=140)
+    state._counters["errors_total"] += 1
+    state._counters[f"errors_{safe_category}"] += 1
+    bump_timeline_locked(state, now, errors=1)
+    append_event_locked(state, now, "ERROR", safe_category, safe_details)
+    prune_locked(state, now)
+
+
+def record_vision_frame_locked(state: Any, *, now: float, analysis: str) -> None:
+    safe_analysis = clip_preview(analysis or "", max_chars=120)
+    state._counters["vision_frames_total"] += 1
+    append_event_locked(state, now, "INFO", "vision_frame", safe_analysis or "frame ingested")
+    prune_locked(state, now)
+

bot/prompt_flow.py

@@ -0,0 +1,249 @@
+import time
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Mapping
+
+
+ReplyFn = Callable[[str], Awaitable[None]]
+InferenceFn = Callable[..., Awaitable[Any]]
+
+
+@dataclass(frozen=True)
+class BytePromptRuntime:
+    agent_inference: InferenceFn
+    client: Any
+    context: Any
+    observability: Any
+    logger: Any
+    byte_help_message: str
+    max_reply_lines: int
+    max_chat_message_length: int
+    serious_reply_max_lines: int
+    serious_reply_max_length: int
+    quality_safe_fallback: str
+    format_chat_reply: Callable[[str], str]
+    is_serious_technical_prompt: Callable[[str], bool]
+    is_follow_up_prompt: Callable[[str], bool]
+    is_current_events_prompt: Callable[[str], bool]
+    is_high_risk_current_events_prompt: Callable[[str], bool]
+    build_server_time_anchor_instruction: Callable[[], str]
+    is_intro_prompt: Callable[[str], bool]
+    build_intro_reply: Callable[[], str]
+    is_movie_fact_sheet_prompt: Callable[[str], bool]
+    extract_movie_title: Callable[[str], str]
+    build_movie_fact_sheet_query: Callable[[str], str]
+    build_llm_enhanced_prompt: Callable[..., str]
+    has_grounding_signal: Callable[[Mapping[str, Any] | None], bool]
+    normalize_current_events_reply_contract: Callable[..., str]
+    is_low_quality_answer: Callable[[str, str], tuple[bool, str]]
+    build_quality_rewrite_prompt: Callable[..., str]
+    build_current_events_safe_fallback_reply: Callable[..., str]
+    extract_multi_reply_parts: Callable[..., list[str]]
+    enable_live_context_learning: bool
+
+
+def unwrap_inference_result(result: Any) -> tuple[str, dict | None]:
+    if isinstance(result, tuple) and len(result) == 2:
+        text_result, metadata_result = result
+        safe_text = text_result if isinstance(text_result, str) else str(text_result or "")
+        safe_metadata = metadata_result if isinstance(metadata_result, dict) else None
+        return safe_text, safe_metadata
+
+    if isinstance(result, str):
+        return result, None
+    return str(result or ""), None
+
+
+async def handle_movie_fact_sheet_prompt(
+    prompt: str,
+    author_name: str,
+    reply_fn: ReplyFn,
+    *,
+    runtime: BytePromptRuntime,
+) -> None:
+    movie_title_from_prompt = runtime.extract_movie_title(prompt)
+    if movie_title_from_prompt:
+        runtime.context.update_content("movie", movie_title_from_prompt)
+
+    active_movie = runtime.context.live_observability.get("movie", "").strip()
+    movie_title = movie_title_from_prompt or active_movie
+    if not movie_title:
+        await reply_fn("Preciso do nome do filme. Ex.: byte ficha tecnica de Duna Parte 2")
+        return
+
+    query = runtime.build_movie_fact_sheet_query(movie_title)
+    answer = await runtime.agent_inference(
+        query,
+        author_name,
+        runtime.client,
+        runtime.context,
+        enable_live_context=runtime.enable_live_context_learning,
+    )
+    await reply_fn(runtime.format_chat_reply(answer))
+
+
+async def handle_byte_prompt_text(
+    prompt: str,
+    author_name: str,
+    reply_fn: ReplyFn,
+    *,
+    runtime: BytePromptRuntime,
+    status_line_factory: Callable[[], str] | None = None,
+) -> None:
+    normalized_prompt = (prompt or "").strip()
+    lowered_prompt = normalized_prompt.lower()
+    prompt_length = len(normalized_prompt)
+    serious_mode = runtime.is_serious_technical_prompt(normalized_prompt)
+    follow_up_mode = runtime.is_follow_up_prompt(normalized_prompt)
+    current_events_mode = runtime.is_current_events_prompt(normalized_prompt)
+    high_risk_current_events_mode = current_events_mode and runtime.is_high_risk_current_events_prompt(
+        normalized_prompt
+    )
+    sent_replies: list[str] = []
+    interaction_started_at = time.perf_counter()
+    server_time_instruction = runtime.build_server_time_anchor_instruction()
+
+    async def tracked_reply(text: str) -> None:
+        final_text = runtime.format_chat_reply(text)
+        if not final_text:
+            return
+        sent_replies.append(final_text)
+        runtime.context.remember_bot_reply(final_text)
+        runtime.observability.record_reply(text=final_text)
+        await reply_fn(final_text)
+
+    def log_interaction(route: str) -> None:
+        total_reply_chars = sum(len(reply) for reply in sent_replies)
+        latency_ms = (time.perf_counter() - interaction_started_at) * 1000
+        runtime.logger.info(
+            "ByteInteraction route=%s author=%s prompt_chars=%d reply_parts=%d reply_chars=%d serious=%s follow_up=%s current_events=%s latency_ms=%.1f",
+            route,
+            author_name,
+            prompt_length,
+            len(sent_replies),
+            total_reply_chars,
+            serious_mode,
+            follow_up_mode,
+            current_events_mode,
+            latency_ms,
+        )
+        runtime.observability.record_byte_interaction(
+            route=route,
+            author_name=author_name,
+            prompt_chars=prompt_length,
+            reply_parts=len(sent_replies),
+            reply_chars=total_reply_chars,
+            serious=serious_mode,
+            follow_up=follow_up_mode,
+            current_events=current_events_mode,
+            latency_ms=latency_ms,
+        )
+
+    if not normalized_prompt or lowered_prompt in {"ajuda", "help", "comandos"}:
+        await tracked_reply(runtime.byte_help_message)
+        log_interaction("help")
+        return
+
+    if runtime.is_intro_prompt(normalized_prompt):
+        await tracked_reply(runtime.build_intro_reply())
+        log_interaction("intro")
+        return
+
+    if lowered_prompt.startswith("status"):
+        status_text = "status indisponivel"
+        if callable(status_line_factory):
+            try:
+                status_text = str(status_line_factory())
+            except Exception as error:
+                runtime.logger.warning("Falha ao montar status customizado: %s", error)
+        await tracked_reply(str(status_text))
+        log_interaction("status")
+        return
+
+    if runtime.is_movie_fact_sheet_prompt(normalized_prompt):
+        await handle_movie_fact_sheet_prompt(
+            normalized_prompt,
+            author_name,
+            tracked_reply,
+            runtime=runtime,
+        )
+        log_interaction("movie_fact_sheet")
+        return
+
+    quality_route_suffix = ""
+    inference_prompt = runtime.build_llm_enhanced_prompt(
+        normalized_prompt,
+        server_time_instruction=server_time_instruction,
+    )
+    if high_risk_current_events_mode:
+        inference_prompt = (
+            f"{inference_prompt}\n"
+            "Instrucao tecnica obrigatoria: use os dados do contexto web atualizado para responder. "
+            f"Se nao houver evidencia verificavel, retorne exatamente: '{runtime.quality_safe_fallback}'"
+        )
+
+    # Follow-up curto privilegia continuidade e baixa latencia; grounding fica para temas serios ou evento atual direto.
+    enable_grounding = serious_mode or (current_events_mode and not follow_up_mode)
+    inference_result = await runtime.agent_inference(
+        inference_prompt,
+        author_name,
+        runtime.client,
+        runtime.context,
+        enable_live_context=runtime.enable_live_context_learning,
+        enable_grounding=enable_grounding,
+        max_lines=runtime.serious_reply_max_lines if serious_mode else runtime.max_reply_lines,
+        max_length=runtime.serious_reply_max_length if serious_mode else runtime.max_chat_message_length,
+        return_metadata=True,
+    )
+    answer, grounding_metadata = unwrap_inference_result(inference_result)
+
+    answer = runtime.normalize_current_events_reply_contract(
+        normalized_prompt,
+        answer,
+        server_time_instruction=server_time_instruction,
+        grounding_metadata=grounding_metadata,
+    )
+    quality_failed, quality_reason = runtime.is_low_quality_answer(normalized_prompt, answer)
+    if quality_failed:
+        runtime.observability.record_quality_gate(outcome="retry", reason=quality_reason)
+        retry_prompt = runtime.build_quality_rewrite_prompt(
+            normalized_prompt,
+            answer,
+            quality_reason,
+            server_time_instruction=server_time_instruction,
+        )
+        retry_inference_result = await runtime.agent_inference(
+            retry_prompt,
+            author_name,
+            runtime.client,
+            runtime.context,
+            enable_live_context=runtime.enable_live_context_learning,
+            enable_grounding=enable_grounding,
+            max_lines=runtime.serious_reply_max_lines if serious_mode else runtime.max_reply_lines,
+            max_length=runtime.serious_reply_max_length if serious_mode else runtime.max_chat_message_length,
+            return_metadata=True,
+        )
+        retry_answer, retry_grounding_metadata = unwrap_inference_result(retry_inference_result)
+        retry_answer = runtime.normalize_current_events_reply_contract(
+            normalized_prompt,
+            retry_answer,
+            server_time_instruction=server_time_instruction,
+            grounding_metadata=retry_grounding_metadata,
+        )
+        retry_failed, retry_reason = runtime.is_low_quality_answer(normalized_prompt, retry_answer)
+        if retry_answer and not retry_failed:
+            answer = retry_answer
+            quality_route_suffix = "_quality_retry"
+            runtime.observability.record_quality_gate(outcome="retry_success", reason=quality_reason)
+        else:
+            answer = runtime.build_current_events_safe_fallback_reply(
+                normalized_prompt,
+                server_time_instruction=server_time_instruction,
+            )
+            quality_route_suffix = "_quality_fallback"
+            runtime.observability.record_quality_gate(outcome="fallback", reason=retry_reason or quality_reason)
+    else:
+        runtime.observability.record_quality_gate(outcome="pass", reason="ok")
+
+    await tracked_reply(answer)
+    route_prefix = "llm_serious" if serious_mode else "llm_default"
+    log_interaction(f"{route_prefix}{quality_route_suffix}")